Before we begin, please open a window of Java API reference and another window of Eclipse Platform 3.0 API reference.
Contents
Hello World!
For this example, we are going to have a window with a label saying "Hello World!" As you may notice, all the tags and attribute names are in lower case. CookSwt is quite case sensitive, and in general all tags and attributes should be in lower case. All SWT components, except Text, have their corresponding tags in lower case. For Text, it is <textarea>.
What attributes can be set for an object directly correspond to the setters and publicly
accessible variables of that object. For example, in case of Shell, it has setText(String) function,
thus one could assign a String object to the attribute text. In case of
setSize(Point) function, however, one must convert the string "640,480" to a Point
object some how, before such assignment can be taken place. CookSwt provides a number of converters
that convert a string value to various target object types, such as Date and Color. More can be found
in the converters reference page.
HelloWorld.java:
import cookxml.cookswt.CookSwt;
import cookxml.cookswt.util.SwtUtils;
public class HelloWorld
{
public static void main (String[] args)
{
CookSwt cookSwt = new CookSwt ();
SwtUtils.showDisplay ((Display)cookSwt.xmlDecode ("examples/cookswt/xml/helloworld.xml"));
}
}
Let's explain the code step by step.
CookSwt cookSwt = new CookSwt ();
This line of code creates a CookSwt object, which can be used multiple times to parse XML documents.SwtUtils.showDisplay ((Display)cookSwt.xmlDecode ("examples/cookswt/xml/helloworld.xml"));This line parses the XML document and obtains an Object. In this case, helloworld.xml has <display> as the root, so we know for sure it is a Display object. SwtUtils.showDisplay (Display) is just a simple utility function that is equivalent toShell shell = display.getShells ()[0]; while (!shell.isDisposed ()) { if (!display.readAndDispatch ()) display.sleep (); } display.dispose ();
The Java code should be simple. After all, that is a part of reason using the toolkit, to reduce the burden of hard coding complex GUI elements.
If you have downloaded the CookSwt binary, you can run HelloWorld locally with
java -ea -cp [classpath] -Djava.library.path=[swt library path] examples.cookswt.HelloWorld
The -ea flags instruct the VM to enable assertion. With enable assertion on, detailed debugging messages can be seen. If you misspelled an attribute or tag name or some other values, CookXml may be able to detect them and report them to the console. You will also be able to notice automatic disposal of Color, Cursor, Font and Image resources that are attached to widgets. CookSwt takes care of them automatically so you don't have to. If you wish to turn the feature off, you can set the flags inside SwtUtils.
GUI Layout
Check out the Layout Tags Reference for a complete list of SWT layouts. CookSwt poses no restrictions on how you can layout your components.
Begin Action
CookSwt also provides the facility of hooking up listeners with various Swing components. This demo basically shows that. To hook up an ActionListener with a Button, for instance, one just needs to have the action listener as a public variable:
public SelectionListener buttonAction = new SelectionAdapter ()
{
public void widgetSelected (SelectionEvent e)
{
System.out.println (e.getSource ());
}
};
When constructing the CookSwing object, it is necessary to tell CookSwing the object where variables can be found.
CookSwt cookSwt = new CookSwt (this);
Then in the XML document, variables inside the "this" object can be read or written. In this case, buttonAction can be read and hooked up with the button.
<button text="action button" selectionlistener="buttonAction" />
If you play around with the demo, you will notice several features that CookSwt does internally.
- If a drop down toolitem has a drop down menu declared inside, this menu will automatically repositioned to the toolitem when the arrow is pressed.
- Controls (in this case a combo box) can be added to tool bar easily simply by declaring it inside a <toolitem>.
- If the toolbar has WRAP style associated with it, it can reposition toolitems when the width becomes too narrow.
- While you can't see in this demo, but when CoolBar (used in CookSwtDemo) is resized, Shell automatically re-do the layout.
- When a control is declared inside a CoolItem/ToolItem, the size of the item is set to the preferred size of the control.
xmldialog
CookSwt provides a facility to generate dialogs easily using XmlDialog. It is not necessary to overload XmlDialog. Simply does the following:
<xmldialog var="myDialog" xml="customdialog.xml" varobj="this" />
Where var is a general attribute that use to write the result of parsing the tag to the variable. In this case, an XmlDialog is constructed and saved to the myDialog variable. To open the dialog, simply call "myDialog.open ()". Check out CookSwtDemo for the About dialog box and the custom dialog box.
ResourceBundle and Locale
This demo demonstrates how to change string, images etc based on the Locale. A string starts with @ will be used as a key to lookup the necessary resource from the resource bundle. If the key could not be found, then the original string is returned as-is. You may ask, why not use entity resolver to do the job? I consider it as another approach compatible with this one. CookSwt can let you change the default DocumentBuilder to the one you liked.
Beyond Swt
Although this tutorial puts emphasis on creating Swt components, CookSwt actually does much more than just Swt components. As you might have seen from previous examples, CookSwt can be used to configure various string and image resources. It is also possible to use it to load start up configurations etc.
Questions? Comments? You can either contact me (although I may not have time to respond all your emails), or post it in the forum.
