GUI programming using JControl/Vole
|
II. Basic StructureThis Tutorial describes the basic concepts of JControl/Vole using program examples. A skeletal structure for applications based on JControl/Vole will also be developed. Figure 1 shows the structure of the GUI framework JControl/Vole. Each application using JControl/Vole has to create an instance of the class |  |
An application using JControl/Vole can be seen as a tree structure (Figure 2): The root is represented by the Frame instance, the branches are represented by the Containers. The leafs are made up of Components, implementing the GUI components currently seen (e.g. buttons, labels, menus etc.).
Frame
The class jcontrol.ui.vole.Frame is responsible for keyboard queries, event handling and focus management. It also extends the class jcontrol.ui.vole.Container and therefore owns all of its features. Components and containers can be added to a frame. The following source code shows a simple application using JControl/Vole, displaying one Label-component and two Button-components.
| 1 | import jcontrol.ui.vole.Button; |
| 2 | import jcontrol.ui.vole.Frame; |
| 3 | import jcontrol.ui.vole.Label; |
| 4 | |
| 5 | /** |
| 6 | * <p>This example demonstrates how to implement JControl |
| 7 | * applications with a graphical user interface |
| 8 | * using the GUI framework JControl/Vole.</p> |
| 9 | * |
| 10 | * <p>(C) DOMOLOGIC Home Automation GmbH 2003-2005</p> |
| 11 | */ |
| 12 | public class VoleExampleBase extends Frame { |
| 13 | |
| 14 | Button b1, b2; |
| 15 | Label l; |
| 16 | |
| 17 | /** |
| 18 | * Create and show a label and two buttons. |
| 19 | */ |
| 20 | public VoleExampleBase() { |
| 21 | // create some components |
| 22 | l = new Label("Welcome to Vole!", 0, 5, 128, 10, |
| 23 | Label.ALIGN_CENTER); |
| 24 | b1 = new Button("Button 1", 8,20,50,12); |
| 25 | b2 = new Button("Button 2", 62,20,50,12); |
| 26 | |
| 27 | // add the components to the frame |
| 28 | this.add(l); |
| 29 | this.add(b1); |
| 30 | this.add(b2); |
| 31 | |
| 32 | // make the frame visible |
| 33 | show(); |
| 34 | } |
| 35 | |
| 36 | public static void main(String[] args) { |
| 37 | new VoleExampleBase(); |
| 38 | } |
| 39 | } |
Figure 2 shows a screenshot of the example program shown above. You may download the examples' source code, add it to new JControl/IDE project, start the simulator and see the features of JControl/Vole action. The class Frame continously queries the keyboard. Using the pushbutton of a JControl device may toggle the focus between the two buttons. Since our example program doesn't install an ActionListener for the buttons, the program does not receive any ActionEvents and therefore it can't respond to a button being pressed. The event handling will be discussed in chapter 4 of this tutorial.
Container
A container (jcontrol.ui.vole.Container) can hold an arbitrary amount of further containers or components. The input focus will be transferred from one component to another within a container until the last component or subcontainer is reached. The focus will then move on to the next container in which it will again be handed off from one component to the next. So it makes sense to organise components that belong together into one container. The order in which the components receive the focus is the same as the one in which the components were added to the container or frame respectively.
Furthermore will all operations applied to a container affect all the contained child components: If, for example, a container is deleted by using the method remove(), all components within it will be deleted and removed from the user interface as well.
The most important methods of the class Container are listed and briefly described in the following table (Table 1):
| Method | Description |
|---|---|
Container(int x, int y, int width, int height) | Creates a new Container with the specified dimensions. |
add(Component c) | Adds a new Component to the Container. The contained components will be drawn in the order in which they were added. |
remove(Component c) | Removes a component from the Container. |
removeAll() | Removes all components from the Container. |
remove() | Removes all components from the Container and the Container itself. |
transferFocus() | Forces the focus to be transferred to the next Component |
jcontrol.ui.vole.Container
A complete list of all methods of this class including a detailed description can be found in the JControl API documentation http://www.jcontrol.org/current/docs/api/jcontrol/ui/vole/Container.html.
Component
The class jcontrol.ui.vole.Component is used as a basic class for all user interface components and comprises the following standard methods, that are implemented by every GUI component and every Container.
| Method | Description |
|---|---|
getParent() | Returns the Container that comprises this Component. |
boolean isVisible() | Checks if this Component is visible. |
remove() | Removes this Component from its Container. |
requestFocus() | Requests the focus to be transferred to this Component. In some cases, this may not be possible. |
removeFocus() | Removes the focus from this Component. |
setBounds(int x, int y, int width, int height) | Changes position and dimensions of the current Component, which will thereupon be redrawn. |
setFont(Font f) | Sets the passed font as the font to be used by this Component, which will thereupon be redrawn. |
setVisible(boolean b) | Toggles the visibility of this Component. |
validate() | Recalculates the dimensions (the so called PreferredSize) of the actual Component, which will thereupon be redrawn. |
jcontrol.ui.vole.Component
A complete list of all methods of the class Component including a detailed description can be found in the JControl API documentation http://www.jcontrol.org/current/docs/api/jcontrol/ui/vole/Component.html.
Komponenten of JControl/Vole
The following table shows a list of all components, that are included in the JControl/Vole framework. A detailed description of these components as well as some program examples can be found in chapter Standard Components. A mouse click on a components' name refers to a related subchapter in which it will be discussed more comprehensive. To see the API documentation of a component, click on the appropriate class.
| Icon | Name | Brief Description | Class |
|---|---|---|---|
| AnimationContainer | Container with special functions for Components which implement the "Animateable" interface | jcontrol.ui.vole.AnimationContainer | |
 | Border | Draws a border | jcontrol.ui.vole.Border |
 | Button | Labeled button; active while pressed | jcontrol.ui.vole.Button |
 | CheckBox | Component with continuing state on or off | jcontrol.ui.vole.CheckBox |
 | ComboBox | From a list of entries, one can be choosen (activated) | jcontrol.ui.vole.ComboBox |
| Component | Base class for JControl/Vole user interface objects | jcontrol.ui.vole.Component | |
| Container | Component that can contain other components | jcontrol.ui.vole.Container | |
| Frame | Starting point for creating a graphical user interface | jcontrol.ui.vole.Frame | |
 | Label | Component which displays non-editable text or an image resource | jcontrol.ui.vole.Label |
 | List | Shows a list of text items with a vertical scroll bar on the right | jcontrol.ui.vole.List |
 | NumberChooser | Shows a number that can be altered | jcontrol.ui.vole.NumberChooser |
 | RadioButton | Component with continuing state on or off | jcontrol.ui.vole.RadioButton |
 | RockerSwitch | Component with continuing state on or off | jcontrol.ui.vole.RockerSwitch |
 | ScrollBar | Implements a graphical scroll bar | jcontrol.ui.vole.ScrollBar |
 | Slider | A graphical slider for JControl/Vole | jcontrol.ui.vole.Slider |
 | TextArea | A text area with optional scroll bar | jcontrol.ui.vole.TextArea |
 | TextScroller | Scrolls text automatically up or down | jcontrol.ui.vole.TextScroller |
 | Diagram | Draws an animated diagram | jcontrol.ui.vole.graph.Diagram |
 | Histogram | Draws an animated histogram | jcontrol.ui.vole.graph.Histogram |
 | BigImageMenu | A menu containing multiple items but only showing one at a time | jcontrol.ui.vole.menu.BigImageMenu |
| Menu | Abstract base class for menus in JControl/Vole | jcontrol.ui.vole.menu.Menu | |
 | MenuBar | Simple menu bar | jcontrol.ui.vole.menu.MenuBar |
 | MultiImageMenu | Menu items are displayed as images | jcontrol.ui.vole.menu.MultiImageMenu |
 | TextMenu | Text based, scrollable menu | jcontrol.ui.vole.menu.TextMenu |
 | AnalogClock | Shows an analogue clock | jcontrol.ui.vole.meter.AnalogClock |
 | AnalogMeter | An analogue gauge | jcontrol.ui.vole.meter.AnalogMeter |
 | BarMeter | Animated bar representing (relative) values | jcontrol.ui.vole.meter.BarMeter |
 | DigitalMeter | Values are displayed in digital form | jcontrol.ui.vole.meter.DigitalMeter |
 | FanMeter | An animated fan displaying a (rotation speed) value | jcontrol.ui.vole.meter.FanMeter |
 | SevenSegmentMeter | A seven-segment display | jcontrol.ui.vole.meter.SevenSegmentMeter |
 | Thermometer | Thermometer to vividly display measured values | jcontrol.ui.vole.meter.Thermometer |