Selectors

All Tutorials

GUI Programming Using JControl/Wombat

IV. Event Handling

Selectors

ComboBox

The ComboBox is an interactive GUI component, that presents the user multiple text items to choose from. While in inactive state, it is closed and only shows the currently selected item. When it gets the input focus, the ComboBox can be opened by using the Select button or pressing the touch screen. The user may now choose one of the other provided items. If the list of possible choices is bigger than the viewable area, it will be srolled up or down.

The most important methods of the class jcontrol.ui.wombat.ComboBox are shown in table 1:

Method	Description
`ComboBox(int x, int y, int width)`	Creates a new `ComboBox` at the given coordinates with the given width
`add(String item)`	Adds a new entry to the `ComboBox`
`String getSelectedItem()`	Returns the currently selected entry of the `ComboBox` as a `String`
`int getSelectedIndex()`	Returns the index of the currently selected entry of the `ComboBox` as an `int`
`remove(String item)`	Removes an item from the `ComboBox`
`setSelection(int index)`	Selects the {index}th entry of the `ComboBox`.

Table 1: Methods of class jcontrol.ui.wombat.Container

Installing an ActionListener onto a ComboBox (using method setActionListener(ActionListener listener)) will result in the ComboBox firing ITEM_SELECTED-ActionEvents every time the user selects an item.

NumberChooser

The NumberChooser is a GUI component consisting of a text field and two buttons. The text field displays a decimal value that can be altered using either of the buttons. The value will be in- or decreased by 1 by pressing the according button (the step size can't be varied directly). Minimal and maximal values are to be assigned by using the constructor. Font as well as size and position of the GUI component can be influenced by the programmer. The following methods are provided:

Method	Discription
`NumberChooser(int x, int y, int min, int max)`	Creates a new `NumberChooser` at the given position with a values margin defined by the parameters `min` and `max`.
`int getValue()`	Returns the current value of the `NumberChooser` component
`setValue(int value)`	Sets the value of the `NumberChooser` to the passed value (the value has to be within the defined values margin)

Table 2: Methods of class jcontrol.ui.wombat.NumberChooser

MultiImageMenu

The MultiImageMenu is component that supports selection of image icons or text entries. The menu entries are arranged in a table layout, the number of rows and columns is customized. The spacing between the items depends on the size of the MultiImageMenu, i.e. on the available space. The MultiImageMenu doesn't support scrollbars. Thus, the number and size of all items should not exceed the available space inside the MultiImageMenu. The following methods are provided:

Method	Description
`MultiImageMenu(int x, int y, int width, int height, int horizontalCount, int verticalCount, int style)`	Creates a new `MultiImageMenu` with specified bounds. The parameters `horizontalCount` and `verticalCount` specify the number of rows and columns. The `style` parameter provides two constant values `STYLE_SHOW_BORDER` and `STYLE_NONE`.
`setImageItems(Resource[] imageItems)`	Sets the specified list of image resources to the the MultiImageMenu. The array may contain `null` values to define blanks in the MultiImageMenu.
`setTextItems(String[] textItems)`	Sets the specified list of strings to the the MultiImageMenu. The array may contain `null` values to define blanks in the MultiImageMenu.
`int addMenuItem(String item)`	Adds an entry into the MultiImageMenu. If there is an image resource available matching the specified string the icon will be shown. Otherwise, the string itself will be shown. The returned value specifies the index of the item.
`int insertMenuItem(String item, int index)`	Inserts an entry into the MultiImageMenu at the specified position. Any existing entry at this position will be discarded. If there is an image resource available matching the specified string the icon will be shown. Otherwise, the string itself will be shown. The returned value specifies the index of the item.
`int getFirstFreeIndex()`	Returns the first index in the MultiImageMenu that is empty, i.e. does not contain any item.
`setTouchMargin(int margin)`	Specifies the size of the non-touchable area around the menu items. Default value is 5.

Table 3: Methods of class jcontrol.ui.wombat.menu.MultiImageMenu

A short source code shall be given at the conclusion of this section, that demonstrates the usage of the GUI components ComboBox, NumberChooser, and MultiImageMenu. It is available in the project WombatSelectorExample in the installation directory of your JControl/IDE under "demos/cobra5329/WombatTutorial/WombatSelectorExample" (on Windows "C:\Program Files\JControl\demos\cobra5329\WombatTutorial\WombatSelectorExample"). Figure 2 shows a screenshot of the running program.

Figure 2: The WombatSelectorExample

1	/**
2	* <p>This example demonstrates how to use the
3	* components ComboBox, NumberChooser and MultiImageMenu within
4	* the GUI framework JControl/Wombat.</p>
5	*
6	* <p>(C) DOMOLOGIC Home Automation GmbH 2007</p>
7	*/
8	import jcontrol.ui.wombat.Frame;
9	import jcontrol.ui.wombat.Container;
10	import jcontrol.ui.wombat.event.ActionListener;
11	import jcontrol.ui.wombat.Border;
12	import jcontrol.ui.wombat.ComboBox;
13	import jcontrol.ui.wombat.NumberChooser;
14	import jcontrol.ui.wombat.menu.MultiImageMenu;
15	import jcontrol.io.Resource;
16	import java.io.IOException;
17	import jcontrol.graphics.Color;
18	import jcontrol.ui.wombat.event.ActionEvent;
19
20	public class WombatSelectorExample extends Frame implements ActionListener {
21
22	/**
23	* Constructor WombatComboNumberExample
24	*/
25	public WombatSelectorExample() {
26	// create a container for the content of this frame
27	Container content = new Container();
28
29	// create borders and add them to the content
30	Border border1 = new Border("ComboBox", 60, 40, 180, 40,
31	Border.STYLE_ETCHED_BORDER);
32	content.add(border1);
33	Border border2 = new Border("NumberChooser", 60, 80, 180, 40,
34	Border.STYLE_ETCHED_BORDER);
35	content.add(border2);
36	Border border3 = new Border("MultiImageMenu", 60, 120, 180, 70,
37	Border.STYLE_ETCHED_BORDER);
38	content.add(border3);
39
40	/* create all components
41	add them to the content
42	and define an actionlistener for each component */
43
44	// ComboBox
45	ComboBox comboBox = new ComboBox(new String[]{
46	"Entry 1", "Entry 2", "Entry 3"}, 110, 56, 80);
47	content.add(comboBox);
48	comboBox.setActionListener(this);
49
50	// NumberChooser
51	NumberChooser numberChooserDay = new NumberChooser(112, 96, 1, 31);
52	numberChooserDay.setValue(1);
53	content.add(numberChooserDay);
54	numberChooserDay.setActionListener(this);
55	NumberChooser numberChooserMonth = new NumberChooser(136, 96, 1, 12);
56	numberChooserMonth.setValue(1);
57	content.add(numberChooserMonth);
58	numberChooserMonth.setActionListener(this);
59	NumberChooser numberChooserYear = new NumberChooser(160, 96, 2000, 2100);
60	numberChooserYear.setValue(1);
61	content.add(numberChooserYear);
62	numberChooserYear.setActionListener(this);
63
64	// MultiImageMenu
65	MultiImageMenu multiImageMenu = new MultiImageMenu(70, 136, 160, 44,
66	3, 1, MultiImageMenu.STYLE_SHOW_BORDER);
67	try {
68	multiImageMenu.setImageItems(new Resource[]{
69	new Resource("item1.jcif"),
70	new Resource("item2.jcif"),
71	new Resource("item3.jcif")});
72	} catch(IOException ioe) {}
73	multiImageMenu.setBackgroundColor(Color.WHITE);
74	content.add(multiImageMenu);
75	multiImageMenu.setActionListener(this);
76
77	// set the content to this frame
78	setContent(content);
79	// finally, make the frame visible
80	setVisible(true);
81	}
82
83	/**
84	* This method is called every time any component declared above
85	* fires an action event.
86	*
87	* @param e the ActionEvent
88	*/
89	public void onActionEvent(ActionEvent e) {
90	// add some code if you want to
91	}
92
93	/**
94	* The main method.
95	*
96	* @param args
97	* The main arguments
98	*/
99	public static void main(String[] args) {
100	new WombatSelectorExample();
101	}
102	}

Listing 2: WombatSelectorExample.java

Buttons

Slider