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.action;
17
18 import net.sf.jguiraffe.gui.builder.event.BuilderEvent;
19
20 /**
21 * <p>
22 * An interface describing an action.
23 * </p>
24 * <p>
25 * An action in terms of this framework is a piece of code that must be executed
26 * in reaction of a user action. Actions are associated with GUI controls like
27 * menu items or toolbar buttons.
28 * </p>
29 * <p>
30 * This definition of an action is compatible with similar concepts in typical
31 * GUI libraries like Swing or SWT (jface). The purpose of this interface is to
32 * provide an abstraction for specific action classes and/or interfaces used in
33 * different GUI libraries. There will be adapter implementations for the
34 * supported libraries.
35 * </p>
36 * <p>
37 * From this framework's point of view an action has the following
38 * characteristics:
39 * <ul>
40 * <li>It has a unique name by which it can be identified.</li>
41 * <li>It can be disabled if the corresponding GUI controls should not be
42 * available for the user because of the actual state of the application.</li>
43 * <li>It has a task, which is an arbitrary object. This task will be invoked
44 * when the action is executed. It is possible to set the task at runtime.</li>
45 * <li>It has an {@code execute()} method for invoking the action.</li>
46 * </ul>
47 * </p>
48 * <p>
49 * Note: Concrete implementations cannot be expected to be thread-safe; the
50 * manipulation of an action's properties is only safe in the UI thread of the
51 * platform in use.
52 * </p>
53 *
54 * @author Oliver Heger
55 * @version $Id: FormAction.java 205 2012-01-29 18:29:57Z oheger $
56 */
57 public interface FormAction
58 {
59 /**
60 * Returns the name of this action.
61 *
62 * @return this action's name
63 */
64 String getName();
65
66 /**
67 * Returns a flag whether this action is enabled at the moment.
68 *
69 * @return the enabled flag
70 */
71 boolean isEnabled();
72
73 /**
74 * Allows to set this action's enabled flag. If set to <b>false</b>, the
75 * user is not allowed to do something with the associated GUI controls.
76 *
77 * @param f the value of the enabled flag
78 */
79 void setEnabled(boolean f);
80
81 /**
82 * Returns a flag whether this action is checked at the moment.
83 *
84 * @return the checked flag
85 */
86 boolean isChecked();
87
88 /**
89 * Allows to set this action's checked flag. The checked flag is important
90 * for actions only if they are represented as checked menu items or toggle
91 * buttons in a toolbar. They then act as a kind of switch.
92 *
93 * @param f the value of the checked flag
94 */
95 void setChecked(boolean f);
96
97 /**
98 * Executes this action. The corresponding code will be invoked. The event
99 * that caused the action to be executed is passed as parameter. Note that
100 * depending on the information available at the time the action is invoked,
101 * some properties of the event may be undefined.
102 *
103 * @param event the event that caused the execution of this action
104 */
105 void execute(BuilderEvent event);
106
107 /**
108 * Returns the task of this action.
109 *
110 * @return the task of this action
111 */
112 Object getTask();
113
114 /**
115 * Sets the task of this action. The task will be executed when this action
116 * is triggered. It can be changed at runtime to assign the action a
117 * different behavior (however this feature should be used with care). Which
118 * tasks an action supports, is up to a concrete implementation. Every
119 * {@code FormAction} implementation should support objects
120 * implementing one of these interfaces: {@code Runnable},
121 * {@link ActionTask}.
122 *
123 * @param task the task for this action
124 * @throws IllegalArgumentException if the task is not supported by this
125 * action
126 */
127 void setTask(Object task);
128 }