1 /*
2 * Copyright 2006-2016 The JGUIraffe Team.
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License")
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16 package net.sf.jguiraffe.gui.builder.enablers;
17
18 import net.sf.jguiraffe.gui.builder.components.ComponentBuilderData;
19 import net.sf.jguiraffe.gui.builder.components.FormBuilderException;
20
21 /**
22 * <p>
23 * Definition of an interface to be implemented by components that can change
24 * the enabled state of specific elements.
25 * </p>
26 * <p>
27 * In a UI application it is frequently the case that some elements (e.g. UI
28 * components, actions, or windows) become enabled or disabled based on certain
29 * criteria defined by the application. For instance, when the user selects a
30 * menu item that starts a long running action in a background task, typically
31 * this menu item should be disabled so that the user cannot start a second
32 * process before the first one terminates. On the other hand, maybe a menu item
33 * for canceling the background process becomes active during its life time.
34 * </p>
35 * <p>
36 * With this interface such status changes can be implemented in a generic way.
37 * There will be specific implementations for dealing with different UI elements
38 * that can be disabled and enabled. The interface itself is pretty lean. It
39 * defines only a single generic method for changing the enabled state of an
40 * element.
41 * </p>
42 *
43 * @author Oliver Heger
44 * @version $Id: ElementEnabler.java 205 2012-01-29 18:29:57Z oheger $
45 */
46 public interface ElementEnabler
47 {
48 /**
49 * Changes the enabled state of the element this {@code ElementEnabler} is
50 * responsible for. This method is always called when the enabled state of
51 * elements has to be changed. The passed in {@code ComponentBuilderData}
52 * object can be used for accessing relevant elements; especially the
53 * {@code BeanContext} maintained by this object can be used for retrieving
54 * all objects available in the current builder context. The boolean
55 * argument determines whether the associated element should be enabled or
56 * disabled. If the state of the element cannot be changed - for whatever
57 * reason -, an implementation should throw a {@code FormBuilderException}.
58 *
59 * @param compData a reference to the current {@code ComponentBuilderData}
60 * object
61 * @param state the new enabled state of the associated element: <b>true</b>
62 * if the element is to be enabled, <b>false</b> if it should be
63 * disabled
64 * @throws FormBuilderException if the state of the element cannot be
65 * changed
66 */
67 void setEnabledState(ComponentBuilderData compData, boolean state)
68 throws FormBuilderException;
69 }