Basics
This page will explain how you prepare your code for Glaze and how styles and stylesheets are created, loaded and used.
Please refer to Getting Started how a project is prepared for Glaze.
Styling BlackBerry managers and fields with Glaze always follows the principle that when a field or a manager is added or inserted to a manager or a screen the style to use is added with the field.
VerticalManager myManager = new VerticalManager();
TextField textField = new TextField();
// add the manager with the style "myManagerStyle"
myScreen.add(myManager,Style.id("myManagerStyle"));
// add the manager with the style "myTextfieldStyle"
myManager.add(textField,Style.id("myTextfieldStyle"));
A MainScreen has no parenting manager thus the style to use is passed to it while constructing it:
// construct a screen with the style "myScreenStyle"
MainScreen myScreen = new MainScreen(Style.id("myScreenStyle"));
Which fields and managers are available depends on your targeted BlackBerry platform version. The main rule is that all fields and managers that a certain BlackBerry platform version offers are also available as a Glaze implementation. You can also check the linked source folder ‘glaze.ui’ (as explained in Getting Started) to find out which fields are available for your targeted platform.
Important
Always use the Glaze implementations of fields and managers. Normal BlackBerry fields and managers won’t use a Glaze style even though they might be added with one.
If field or managers are not styled, always check the package imports if a used field is imported as the normal BlackBerry implementation:
// a normal BlackBerry TextField import import net.rim.device.api.ui.component.TextField; // the Glaze TextField import import de.enough.glaze.ui.component.TextField;
Styles in Glaze use the same syntax for CSS declarations as web browsers :
myStyle {
color: red;
}
Every style starts with the selector (‘myStyle’) followed by an opening curved parenthesis, a number of attribute-value pairs (‘color: red;’) and a closing curved parenthesis. The selector can consist of several item-names and contain an “extends” clause. Each attribute-value pair needs to be finished by a semicolon.
Pseudo styles are used to design fields in different states, e.g. when they are focused. Pseudo styles use a colon between the basic style name and the pseudo style, for example myButton:focus or .myButton:active. Pseudo styles inherit all properties of the basic style and add/overwrite their own properties.
myStyle {
margin: 10px;
padding: 5px;
background-color: silver;
color: black;
}
myStyle:focus {
background-color: red;
color: white;
}
The :focus pseudo style of ‘myStyle’ is created which inherits the margin and padding property and overwrites the background color and color
The following pseudo styles are available :
focus
Defines the design for the focused state of a field. If no :focus style is given, the normal style is used.
active
Defines the design for a field when it is pressed, meaning the user selects it by holding down a pointer or a key.
If no :active style is given, the :focus style is used.
disabled
Defines the design for a field when it is disabled. If no :disabled style is given, the normal style is used.
disabled_focused
Defines the design for a field when it is disabled and focused. If no :disabled_focus style is given, the :disabled style is used.
A style can extend another style. The extending style will inherit all properties of the style to extend and add/overwrite its own properties.
.myStyle {
color: black;
font-size: 20px;
}
.myExtendingStyle extends mainItem {
font-size: 40px;
}
The style ‘myExtendingStyle’ extends ‘myStyle’ thus inheriting all properties and overwritting the ‘font-size’ property
Comments can be inserted at any place and start with “/*” and stop with “*/”. Everything between these boundaries is ignored.
myStyle {
/* defining the color of a font: */
font-color: black;
}
All availalbe style properties can be found in the reference.
Glaze uses the CSS box model to design fields :
The CSS box model describing the content, padding, border and margin areas of a field
The margin describes the gap to other fields in a manager or screen. The padding describes the gap between the border of the item and the actual content of that item. The margin and padding defaults to 0 pixels. In the following example, the top, right and bottom margin is 5 pixels, whereas the left margin is 10 pixels:
myStyle {
margin: 5px;
margin-left: 10px;
}
Percentage values can also be used to define the margin and padding. Like in the standard CSS 2.1, percentage values are calculated relative to the available width of the corresponding field, even for top and bottom values.
For more supported units please see the dimension reference.
Backgrounds are drawn behind the content of a field (e.g. its text) inside the content and padding areas in the CSS box model. The following example will draw a blue background :
myStyle {
background-color: blue;
}
For all supported background properties please see the background reference.
Borders are drawn around the content and padding areas in the CSS box model. The following example will draw a red border :
myStyle {
border-color: red;
}
For all supported border properties please see the border reference.
Stylesheets are updated and extended through various methods of the class StyleSheet.
Each method supports the loading of web-based (http://) and packaged (resource) stylesheets.
Depending on the complexity of a stylesheet (number and complexity of styles, use of web-based resources) the loading
of stylesheet might take a while. Therefore Updates or extensions should always be handled during the startup phase of an application where other resources and data of the application is loaded.
An update of a stylesheet clears the previous definition of a stylesheet and replaces it with the definitions of the new stylesheet. An update is also used to initially load a stylesheet.
// updates a stylesheet with the file 'styles.css' located in the application resources
StyleSheet.getInstance().update('/styles.css');
// updates a stylesheet with 'http://myserver.com/styles.css'
StyleSheet.getInstance().update("http://myserver.com/styles.css");
Stylesheet updates can either be updated synchronous or asynchronous. Asynchronous updates are recommended
if a complex stylesheet is given and/or web-based style resources like images need to be downloaded.
// loads a stylesheet synchronously
try {
StyleSheet.getInstance().update('/styles.css');
} catch(CssSyntaxException e) {
// thrown when the CSS syntax is wrong
} catch(Exception e) {
// thrown when a general error (e.g. connection timeouts) occurs
}
// loads a stylesheet and notifies the given listener when the stylesheet is loaded or an error occured
StyleSheet.getInstance().update('/styles.css', myListener);
An extension of a stylesheet keeps the current definition of a stylesheet. The styles of the
newly loaded stylesheet file are added to the stylesheet or overwrite existing definitions if
the id of the style already exists in the current stylesheet definition.
// extends a stylesheet with the file 'styles.css' located in the application resources
StyleSheet.getInstance().extend('/styles.css');
// extends a stylesheet with 'http://myserver.com/styles.css'
StyleSheet.getInstance().extend("http://myserver.com/styles.css");
Extension of a stylesheet is used to adopt certain styles of a stylesheet to certain developer-defined conditions. For
example, if the display exceeds a specific width, a basic stylesheet is extended with a specific stylesheet for the given
resolution :
// load the basic stylesheet
StyleSheet.getInstance().update("styles.css");
// if the display width is larger than 360 pixels ...
if(Display.getWidth() > 360) {
// extend the stylesheet definitions with a specific stylesheet
StyleSheet.getInstance().extend("/styles.large.css");
}
As updates, a stylesheet can either be extended synchronous or asynchronous.
Stylesheet updates and extensions may result in errors. The most common is a CSS syntax error when an error was made while writing the stylesheet. CSS syntax errors are always printed to the console to inform the user :
//GLAZE///////////////////////////////// A CSS syntax error was found : 6 : unknown property id : foo ////////////////////////////////////////
A CSS syntax error is printed : the first part is the line the error was found (6), the second part describes the error (unknown property id) and the last part is the wrong property value (foo)
CSS syntax error and general errors, e.g. connection timeouts while loading a web-based stylesheet, are thrown in update(url) and extend(url). Asynchronous updates and extensions notify the developer via the callback methods onSyntaxError(CssSyntaxError) and onError(Exception).