Fields

Fields are the fundamental UI components that you'll use when you create UIs for your applications. A field is a rectangular region that is contained by a manager and can be drawn on the screen of a BlackBerry® device. A field contains content, such as the text label of a button or items in a drop-down list, and a border that surrounds the content. A field also contains padding, which is the area of space between the content and the border.

A field is represented by the Field class, which is included in the net.rim.device.api.ui package. All UI components in the BlackBerry® Java® SDK are derived from Field. For example, prebuilt UI components such as the ButtonField, CheckboxField, LabelField, and TextField classes all extend Field. Managers, which are represented by the Manager class, and screens, which are represented by the Screen class, also extend Field.

Constructors for the various field classes can accept style bits as parameters. Style bits are constants in Field that specify the visual properties of the field. These properties include the alignment of the field within its manager, how much space the field is allowed to use within its manager, and whether the field can be edited or accept the focus. For example, you can specify the Field.FIELD_HCENTER style bit to center a field horizontally within its manager, and you can specify the Field.USE_ALL_WIDTH style bit to direct a field to use all of the available width of its manager when it is drawn. A field is responsible for sizing itself when it is drawn, but the manager that contains the field is responsible for scrolling. The Manager class extends the ScrollView class, which implements the scrolling functionality.

The Field class is an abstract class, meaning that you cannot create Field objects directly. Instead, you can use the UI components that are included in the net.rim.device.api.ui package in your applications, or you can extend Field to create your own custom field. If you choose to create a custom field, you must implement the layout() and paint() abstract methods to specify how to arrange and draw the field.

The layout() method arranges the contents of the field. You can override this method to provide custom layout instructions for your field. For example, you might use this method to specify the size and positioning of the content in your field. This method is invoked when events occur that might change the arrangement of fields on a screen, such as when fields are added to or removed from a screen or when the device is rotated. If you choose to override this method, you must invoke setExtent() within layout() to specify the size of the field.

The paint() method draws the content area of the field. The content area might include text or graphics, and this method determines how this content appears when it is drawn. For example, you can override this method to draw text in a specific color in your field. This method is invoked when events occur that might change the visual appearance of a field, such as when the screen scrolls or when the field gains or loses the focus. If you need to force a field to repaint itself, you can invoke invalidate() on the field. A Graphics object is passed into paint() when the method is invoked, and you can use this object to draw on the screen.

Next topic: Box model

Was this information helpful? Send us your comments.