Skip to content
infamous1982 edited this page Nov 22, 2011 · 77 revisions

Getting Started

This page will show you how to setup Glaze and introduce you to its basic principles.

Get Glaze

To use Glaze in your BlackBerry Java development, please clone the following git repository :

https://github.com/Enough-Software/glaze.git

The resulting project contains all classes needed for development with Glaze.

Alternatively, you can download the latest version as an archive here.

Glaze is available under the MIT, Apache and GPL with classpath exception license. In short this means you can use Glaze both commercially and open source.

Requirements

Glaze development requires the BlackBerry Java Plug-in for Eclipse. For requirements and setup please refer to the documentation.

The use of the BlackBerry JDE is not encouraged.

Setup a project

For Glaze development you may use a new or an existing project. A tutorial from BlackBerry how to setup up a project can be found here.

In both cases the source of glaze needs to be linked to your project :

  • Right-click on the project and choose ‘Properties’
  • Select ‘Java Build Path’ and choose ‘Source’
  • Select ‘Link source…’
  • In the newly opened window, choose ‘Browse…’
  • Browse to the folder you installed Glaze in and choose the folder “src/core”.
    This will link the Glaze core sources to your project.
  • Set the name in ‘Folder name’ to ‘glaze.core’.
  • Link one of the following source folders :
Platform Folder
4.6 and above src/4.6.0
5.0 and above src/5.0.0
6.0 and above src/6.0.0

Each folder links needed Glaze implementations of UI components like TextField or FlowFieldManager to your project.

As new managers and fields were introduced in BlackBerry platform releases, the field and managers that are available as Glaze implementations also vary between platforms. For example, the AbsoluteFieldManager was introduced to the BlackBerry framework in version 5.0 thus the Glaze implementation of AbsoluteFieldManager is only available in the sources of the folders ‘src/5.0.0’ and ‘src/6.0.0’.

  • Set the name in ‘Folder name’ to ‘glaze.ui’
  • Your project is now ready to use Glaze.

A typical resulting project structure looks like this :

A simple application using Glaze

As a simple example we’ll create an application displaying a styled LabelField.

Create a new project

Create a new BlackBerry project using any name you like and link the Glaze sources as described above.

The result will be an application consisting of the classes ‘MyApp’, the main application class and ‘MyScreen’, the screen that is displayed.

Use the Glaze UI classes

Add a LabelField to the screen class ‘MyScreen’ :

public final class MyScreen extends MainScreen
{
    /**
     * Creates a new MyScreen object
     */
    public MyScreen()
    {        
        LabelField labelField = new LabelField("Hello World!", Field.USE_ALL_WIDTH);
        add(labelField);
    }
}

Glaze uses their own implementations of common screens, fields and managers (e.g. MainScreen, TextField, FlowFieldManager).
The classnames of the fields and managers are the same, only the packages differs.

The screen class above has the following import statements :

import net.rim.device.api.ui.container.MainScreen;
import net.rim.device.api.ui.component.LabelField;

To use the Glaze implementation of MainScreen and LabelField, change the import statement to the following :

import de.enough.glaze.ui.container.MainScreen;
import de.enough.glaze.ui.component.LabelField;

Next we will set a style for the LabelField and the MainScreen. A style can be retrieved through the call of Style.id(id). If no style is available for the given id an empty style is returned. The resulting style from Style.id(id) can be assigned to all commonly used screens, managers and fields as long as the corresponding Glaze implementation is used.

To style the screen we’ll add a super(Style.id("myScreenStyle")) call to the constructor :

public MyScreen()
{   
    // set the style "myScreenStyle" for this screen
    super(Style.id("myScreenStyle"));
    ...
}

To style the LabelField, we simply adjust the add(labelField) call to add(labelField,Style.id("myLabelStyle")) :

public MyScreen()
{   
    ...
    // set the style "myLabelStyle" for the LabelField
    add(labelField,Style.id("myLabelStyle"));
}

The resulting class will look like this :

public MyScreen()
{   
    // set the style "myScreenStyle" for this screen
    super(Style.id("myScreenStyle"));
    LabelField labelField = new LabelField("Hello World!", Field.USE_ALL_WIDTH);
    // set the style "myLabelStyle" for the label field
    add(labelField,Style.id("myLabelStyle"));
}

This is the way styles are assigned to fields : Each Glaze implementation of a screen or manager (e.g. MainScreen, VerticalFieldManager, FlowFieldManager, GridFieldManager) offers methods to add, set or insert fields with a style.

For example, a VerticalFieldManager adding a TextField with a style works like this :

VerticalFieldManager myManager = new VerticalFieldManager();
TextField myTextField = new TextField();
myManager.add(myTextField,Style.id("myTextfieldStyle"));

The screen and the field are now prepared to use the styles ‘myScreenStyle’ and ‘myLabelStyle’.

Write a CSS stylesheet

Next we’ll create and load the stylesheet which defines these styles.

A CSS stylesheet for use in Glaze is a simple text file. It can have any name or extension. For our example, we’ll create a stylesheet named ‘myStyles.css’ which will hold the two styles ‘myScreenStyle’ and ‘myLabelStyle’.

  • Create a new file named ‘myStyles.css’ and save it to the ‘res’ folder of your application project.
  • Open the ‘myStyles.css’ to edit it.
  • Add the following contents :
myScreenStyle {
    background-color: black;
}

myLabelStyle {
    margin: 10px;
    padding: 10px;
    border-color: silver;
    border-width: 5px;
    background-color: orange;
    color: white;
}
  • Save the file

This will create a very simple styling for the screen and the field.

Load a CSS stylesheet

Next we need to load the stylesheet in our application. For that the method StyleSheet.getInstance().update(url) is called from the constructor of our main application class :

public MyApp()
{        
    // Load the stylesheet
    try {
	StyleSheet.getInstance().update("/myStyles.css");
    } catch (CssSyntaxError e) {
	e.printStackTrace();
    } catch (Exception e) {
	e.printStackTrace();
    }

    // Push our screen
    pushScreen(new MyScreen());
}

Run your application

Run your application in the simulator or on a real device.

The result should look like this :

What’s next?

This is just the very tip of the iceberg and, to be fair, the above result of our example doesn’t look that stunning.

To learn all about the syntax and possibilities for creating stylesheets and styles, please read the basics.

To find out about all the properties and features you can use for styling your application, please check out the reference.

To easily create and test styles in an application check out sandboxing.

Learn here how to add custom style properties and adopt your custom fields and managers for Glaze.

Showcase

To see Glaze in action, a showcase has been prepared showing various samples how a login form can be styled with Glaze.

To prepare and run the showcase project, please follow these steps :

  • Get Glaze.
  • Clone the showcase project from following git repository:
https://github.com/Enough-Software/glaze-showcase.git

Alternatively, you can download the showcase project as an archive here.

  • Import the showcase project to your workspace. Initially the project will show errors as no glaze sources are linked to the project.
  • Link the Glaze sources as described above. The showcase is optimized for BlackBerry 6.0.
  • Run the simulator.