Apptoy - A Java GUI Browser

Apptoy Introduction

This page describes how you can develop your own GUIs using Apptoy.

Using Apptoy to develop a GUI includes the following steps:

• Configure your workspace to develop Apptoy applications
• Arrange the visual elements on your form using XML (assisted by your editor)
• Write event scripts
• Connect your event scripts to a business logic.
• Deploy your Application

But first of all you need to understand some basics.

Basics

Running an Apptoy application

Apptoy comes with a main class that you start from the command line. Apptoy reads the configuration and loads the main script (the path to the configuration is a command-line argument). This script must at least load the main form (an XML file) which is then rendered and displayed. From that point on, event scripts take over the control until the main form is closed.

Apptoy is not thought to be embedded into your application or to simply make SWT forms out of XML, it is a platform that completely takes over control and processes all the GUI interaction - like a web browser.

While Apptoy applications work like web sites for a certain extent, they have to be programmed like web sites: You only see the frontend while the business logic is hidden behind calls made by the event scripts.

However, in contrast to web applications it is not necessary to put the business logic on a web server. It may also be put into a local context, but Apptoy naturally supports the separation of presentation and business logic by design.

Apptoy URIs

Within the forms, links may exist to other resources (images, scripts, other forms). Apptoy introduces URIs that look like: apptoy://<source>/<path> to locate the resources..

The configuration tells Apptoy how to "translate" these links into real-world input streams, e.g. apptoy://images/abc.png might reside on a web server (e.g. translated to http://apptoy.sf.net/abc.png), but it might also be available on a local file path or even as part of a JAR delivered with your Apptoy application. Every <source> may deliver data in a different way.

This allows a great flexibility when developing an application: You define the actual source of the document when you start the application. That enables you to use different ways to access the same resource without having to change a single line of code or a form. Some examples to make this a little bit more clear:

• you can retrieve the forms from a web server and store the images locally.
• You can start developping an application locally (using local files) and once you think it's time to move it onto a web server, you move it and then you just start your application with another configuration which reads the files from the web server instead from the local files.
• You can collect all the images you need in one directory and make your development work with those local files. Once your application is finished, you may deliver the images packed in a JAR file.
• you can run the same application on different web servers using different configurations (relative paths are not allowed in Apptoy, but not necessary).
• You can put different parts of your application to different <sources>

Configuration of your Eclipse Workspace

The Markup (SWT)

If you thought you'd get around SWT by using Apptoy, you're wrong. The opposite is the case. Apptoy's SWT implementation tries to be as close to the SWT API as possible.

This includes layouts of course... My suggestion is: Try it, it's not that hard at all, perhaps Apptoy even gives you another point of view because the structure looks quite logical in XML.

This introduction will not replace reading about SWT. However, you may try to get through with only basic knowledge...

 
<?xml version="1.0" encoding="UTF-8"?>
<form xmlns="http://apptoy.sf.net/swt" 
        title="Getting started" 
        type="APPLICATION_MODAL" 
        style="SHELL_TRIM"
        id="mainform"
        x="1" y="1" w="400" h="200">

    <resources>
        <font name="Arial" height="20" style="BOLD" id="arial20"/>
    </resources>
   	
    <gridlayout>
        <label text="Hello, Apptoy!" font="arial20">
        <griddata grab="BOTH"�horizontalalignment="CENTER" verticalalignment="CENTER" />
        </label>
    </gridlayout>
	
    <script/>
</form>

The namespace (xmlns) is important if you enabled your browser to use the swt.xsd file to validate your markup.

The first section of the markup is <resources>. This is the place where fonts, images and menus are defined. Resources are automatically disposed when a form closes. To be able to use these resources in the form, an id must be defined which is then used later (check the font attribute in the label element in the example).

The next big section is enclosed by the basic layout of the form (in this case, a gridlayout).

Controls are put within this layout, for each control, there may be constraints that further define the position in the parent layout (griddata in that case). One kind of controls are containers (e.g. composite) which can contain more controls. Containers must have their constraints (to define their position in the parent container) and their own layout, possible standard layouts are gridlayout, nulllayout, stacklayout, rowlayout, filllayout, formlayout.

The last section is the script section. Depending on the used language, you can insert code here directly or use the include attribute to read it from a file (e.g. Jython is structured by indent which is not suitable for XML files. It's better to put the script into an external file in that case)

The Event Scripts

If an attribute on... is specified, a listener is registered. Event scripts are called right when an event occurs.

Basic example

	<button text="OK" onselection="log.warning('OK button pressed!');"/>

This is a very basic example. The script is executed when the button is pressed. The script is just within the event attribute. It could also call a script from the script section (use the CDATA section to be able to use '<' instead of '&lt;')

    <button text="OK" onselection="okButton();" id="btn"/>

    <script><![CDATA[
    
        function okButton() {
        	log.warning("OK Button pressed!");
        }
        
    ]]></script>

Objects Known to the Script

There are the following objects known to the scripts:

• log

  A simple way to output messages to the log. You can use log.warning("Hello Log!");

• controls

  A hashtable of all controls that have the id tag set. A control with an id is stored in the controls hashtable and can be accessed using controls.get("<ID>");, e.g. controls.get("btn").setText("Cancel") calls the setText() method of the SWT Button object.

• context

  The context object provides methods

  • ...to load other forms

  • ... to access stores for form and session variables: Every event is an isolated piece of code that is executed. That way, variables cannot be preserved between two scripts. For that reason, Apptoy provides form and session variable storages to store variables that are available throughout the whole session or are disposed when the form closes.

  • ... to load XML data into a DataContext (this DataContext can be accessed using XPath)

  • ...to post data to the server

  The two objects _form and _session offer an abbreviated access to the form and session variables:

  context.getSessionVar("abc") is the same as _session.get("abc")

• data

  The standard data context that may be filled while loading the form.

GUI vs Business Logic

Apptoy is a front-end system, a GUI browser. At some point you must connect to some kind of business logic. There are several approaches to do that. Here are some thoughts on that.

Data Contexts

The data contexts are an idea which has been established in a very early stage of Apptoy's development. It was thought to simplify the usage of XML data that may be retrieved using apptoy:// URIs. The data of the DataContext is retrieved using ctx = context.loadData(URI). The context can then be processed using XPath functions and posted back to the server.

Presentation Model

Deploying an Apptoy Application

Abstract: All Jars and the configuration into one directory, create java command-line..., explain Java Web Start deployment.

TBD: Detailed description.

Summary

This is no detailed guide to Apptoy, but I hope it helps to get started and to understand the concept of Apptoy. Apptoy is under development at the moment, and since I am doing all the work alone at the moment, I have to find effective ways to provide all the needed information.