The GUI framework JControl/Wombat provides mechanisms for an message based handling of events that are used by all interactive components. Programmers of JControl/Wombat based applications just have to implement an ActionListener
to be albe to react to user inputs. How to install an ActionListener
onto a specific GUI component and process its ActionEvents
, will be shown in the following sections.
Figure 1 outlines the principle of the transmission of messages by JControl/Wombat: An event loop, which runs as a background thread, is automatically installed by the class Frame
. This loop continuously queries keyboard and touch screen and triggers a KeyEvent
or a TouchEvent
respectively whenever the user provides some input. The Event then is transmitted to the user interfaces' Container
framework, that now has to determine which GUI component has to be associated with the Event. Depending on the type of event, the deciding factors are either the location of the GUI component on screen (TouchEvent
) or the current ownership or the input focus (KeyEvent
). The determined GUI componente will now react on the user input and eventually trigger an ActionEvent
.
Once the application has attached an ActionListener
to a GUI component (via the method setActionListener(ActionListener listener)
), it is able to receive the ActionEvents issued by this specific GUI component. On the occurrence on an ActionEvent
, JControl/Wombat will call the listeners onActionEvent(ActionEvent event)
, where application specific actions may be implemented.
A program example shall demonstrate the handling of ActionEvents
. Two Button
s and a Label
are created. An ActionListener
is installed onto both Button
s, that ought to react to their activation by the user in form of altering the Label
s' content.
1 | import jcontrol.ui.wombat.Button; |
2 | import jcontrol.ui.wombat.Container; |
3 | import jcontrol.ui.wombat.Frame; |
4 | import jcontrol.ui.wombat.Label; |
5 | import jcontrol.ui.wombat.event.ActionEvent; |
6 | import jcontrol.ui.wombat.event.ActionListener; |
7 | |
8 | /** |
9 | * <p>This example demonstrates how to handle |
10 | * events within the GUI framework JControl/Wombat. |
11 | * This program needs the image resource |
12 | * 'mouse.jcif'.</p> |
13 | * |
14 | * <p>(C) DOMOLOGIC Home Automation GmbH 2003-2005</p> |
15 | */ |
16 | public class WombatEventHandlingExample |
17 | extends Frame implements ActionListener { |
18 | // the Label |
19 | Label label; |
20 | // the right Button |
21 | Button button_right; |
22 | |
23 | /** |
24 | * Create two buttons and a label and add an ActionListener. |
25 | */ |
26 | public WombatEventHandlingExample() { |
27 | // create the Buttons |
28 | Button b1 = new Button("Left Button", 2, 10, 60, 13); |
29 | button_right = new Button("Right Button", 66, 10, 60, 13); |
30 | |
31 | // add the ActionListener |
32 | b1.setActionListener(this); |
33 | button_right.setActionListener(this); |
34 | |
35 | // create a content pane |
36 | Container content = new Container(); |
37 | this.setContent( content); |
38 | |
39 | // add the Buttons to the Frame |
40 | content.add(b1); |
41 | content.add(button_right); |
42 | |
43 | // create the Label |
44 | label = new Label("Please press a button!", 0, 30, 128, 10, |
45 | Label.STYLE_ALIGN_CENTER); |
46 | content.add(label); |
47 | } |
48 | |
49 | /** |
50 | * This is the event handler. When a component fires an |
51 | * ActionEvent for us, this method is invoked. |
52 | */ |
53 | public void onActionEvent(ActionEvent event) { |
54 | // check whether this is a BUTTON_PRESSED event |
55 | if (event.type == ActionEvent.BUTTON_PRESSED) { |
56 | |
57 | // recognize event's source by using getActionCommand() |
58 | if ( "Left Button".equals(event.command)) |
59 | label.setText("You pressed the left button!"); |
60 | |
61 | // recognize event's source by using getSource() |
62 | if (event.source == button_right) |
63 | label.setText("The right button was hit!"); |
64 | } |
65 | } |
66 | |
67 | /** |
68 | * Instantiate and show the main frame. |
69 | */ |
70 | public static void main(String[] args) { |
71 | new WombatEventHandlingExample().setVisible(true); |
72 | } |
73 | } |
The ActionListener
instance to receive ActionEvents
in the program example of the previous section is the class WombatEventHandlingExample
itself. This is defined during the class declaration by the argument "implements ActionListener
". To satisfy the requirements of an ActionListener
instance, the method onActionEvent(ActionEvent event)
has to be implemented. The following sections were taken from the source code listing and show the relevant segments for successfully installing an ActionListener
.
... | |
16 public class WombatEventHandlingExample | |
17 extends Frame implements ActionListener { | |
... | |
31 // add the ActionListener | |
32 b1.setActionListener(this); | |
33 button_right.setActionListener(this); | |
... | |
52 public void onActionEvent(ActionEvent event) { | |
... |
For onActionEvent
s to be triggerd by both Button
s, we pass a pointer to the class instance by using Button.setActionListener(this)
and therewith register the ActionListener
. A pointer to any other class that implements the interface ActionListener
will be acceptable as well.
The class ActionEvent
provides three member variables to process received messages: type
, command
and source
.
int type
: This variable contains the type of the ActionEvent
as an int
. Table 1 lists the possible values:
Value | Description |
---|---|
BUTTON_PRESSED | The message has been triggered by a Button . |
ITEM_SELECTED | An item of a List or ComboBox has been selected. |
VALUE_CHANGED | A numerical value has been changed (e.g. of a Slider ). |
STATE_CHANGED | The state of a RadioButtons or CheckBox has been changed. |
String command
: Using the ActionCommand
, GUI components are able to add String information to an ActionEvent
. The receiver can access this information via the member variable command
. The kind of information depends on the component. Button
s, for example, will transmit their label text. Note that the command
string may also be null
.ActionProducer source
: The member variable source
contains a reference to the object which issued the ActionEvent
.In the following excerpt of the example program are two techniques demonstrated of how to determine the source of an ActionEvents
. At first, the method onActionEvent
checks if the received event has been triggered by a Button
(event.type
). Thereafter will be decided if the left or right Button
has been pressed. The left Button
is hereby identified by comparing event.command
with the Button
's label. The right Button
is identified by using event.source
. The last method may seem more elegant, but assumes the presence of a reference to the Button
as a variable of the class instance. This may not be the case, if the ActionListener
is implemented by a separate class.
... | |
53 public void onActionEvent(ActionEvent event) { | |
54 // check whether this is a BUTTON_PRESSED event | |
55 if (event.type == ActionEvent.BUTTON_PRESSED) { | |
56 | |
57 // recognize event's source by using getActionCommand() | |
58 if ( "Left Button".equals(event.command)) | |
59 label.setText("You pressed the left button!"); | |
60 | |
61 // recognize event's source by using getSource() | |
62 if (event.source == button_right) | |
63 label.setText("The right button was hit!"); | |
64 } | |
65 } | |
... |
The kinds of ActionEvent
s that are generated by the components of JControl/Wombat are described in the according API documentation. However, all components share the presence of the method setActionListener(ActionListener listener)
. That way, an application program may individually process the user triggered events and define, which events it will react to and which events will be ignored.