# Widget Reference

A widget is a unit of a user interface, a single element doing a single thing, for example, a tappable button, or an editable text field. A form contains various widgets, the user interacts with them, and the application is notified via `events`. See the PalmOS documentation and the example application included with Guikachu for more information on handling widget events.

## Label

Labels are static text that can't interact with the user and can't be changed by the application at run-time either. For non-static labels, use a non-editable text field.

### Properties

Resource ID

  A unique string ID used for accessing the resource at run-time from the program

Usable

  Non-usable widgets are not rendered on the screen and don't receive events. You can set/unset the "usable" property at run-time with the `CtlSetUsable` function.

Text and font

  The textual contents of the widget. It will be rendered using the specified font.

  Guikachu currently only supports the built-in fonts.

X and Y

  Horizontal and vertical position relative to the parent form, in pixels, counted from left to right and top to bottom. Due to the size of the screen of PalmOS devices, both X and Y are integer values between 0 and 159.

## Text field

A text field contains text that is changeable at run-time, either by the application or by the user.

There are several ways to set/get the currently displayed text of a text field, see the PalmOS SDK for details.

### Properties

Resource ID

  A unique string ID used for accessing the resource at run-time from the program

Usable

  Non-usable widgets are not rendered on the screen and don't receive events. You can set/unset the "usable" property at run-time with the `CtlSetUsable` function.

Font

  The font used to display the contents of the text field

  Guikachu currently only supports the three default built-in fonts: #0 is the "normal", #1 is the "bold" and #2 is the "large" font.

Editable

  Controls whether the user is able to change the field's contents.

Multi-line

  Multi-line text fields automatically wrap input at the end of visible lines. They also accept newline and tab as input.

Numeric-only

  Set this property to restrict input by the user to numbers only. Since it only controls user input, it makes sense only for editable text fields.

Maximum length

  Maximum allowed length of text entered by the user. Set this to 0 to force no restrictions (actually, there is still a restriction on length due to the PalmOS architecture).

Underlined

  It is usually a good idea to underline editable text fields, since otherwise the user has no visual clue about the existence of the field.

Auto-shift

  If you set this property, the graffiti shift state will behave "smartly", e.g. shift will be turned on for new sentences.

Dynamic size

  If this flag is set, `fldHeightChangedEvent`s are generated when the number of lines needed to display the contents changes. The application then needs to handle this event by optionally changing the size of the field.

  This only makes sense for multi-line text fields.

Right-aligned

  Alignment of the text contents.

  Right-aligned text fields don't accept the Tab character as input.

Scrollbar

  Set this to have a scrollbar on the right-hand side of the text field when the contents are larger than the size of the widget.

  The scrolling itself will be automatically done by the OS, you don't need to do anything on your own.

X and Y

  Horizontal and vertical position relative to the parent form, in pixels, counted from left to right and top to bottom. Due to the size of the screen of PalmOS devices, both X and Y are integer values between 0 and 159.

Width and height

  Horizontal and vertical size, in pixels. Due to the size of the screen of PalmOS devices, both width and height are integer values between 1 and 160.

  You can also use automatic values calculated from the size of the widget's contents.

## Graffiti State Indicator

This widget displays an icon showing the current state (like upper-case input, or punctuation marks) of the Graffiti input system. It is automatically connected to the input system, so you don't have to bother implementing it. Just place it on a form and you're set.

### Properties

Resource ID

  A unique string ID used for accessing the resource at run-time from the program

X and Y

  Horizontal and vertical position relative to the parent form, in pixels, counted from left to right and top to bottom. Due to the size of the screen of PalmOS devices, both X and Y are integer values between 0 and 159.

## Button

A button is a (rounded) rectangular user interface element that emits a specific signal to the application when the user taps it with the stylus.

### Properties

Resource ID

  A unique string ID used for accessing the resource at run-time from the program

Usable

  Non-usable widgets are not rendered on the screen and don't receive events. You can set/unset the "usable" property at run-time with the `CtlSetUsable` function.

Text and font

  The textual contents of the widget. It will be rendered using the specified font.

  Guikachu currently only supports the built-in fonts.

Bitmap/Selected Bitmap

  Select a Bitmap or Bitmap Group resource to be displayed instead of the textual caption.

  Usually, you should specify a separate bitmap for the widget's selected state, since otherwise the normal bitmap is used.

Frame type

  Buttons can optionally have one of two types of frame around them. It is usually a good idea to give buttons a frame as this helps users distinguishing it from a simple label

Repeating

  Repeating buttons emit several `ButtonPress` signals when kept pressed by the user.

Anchor right

  If the widget's size changes at run-time and this flag is set, the new horizontal position is calculated to leave the widget's right edge at place.

X and Y

  Horizontal and vertical position relative to the parent form, in pixels, counted from left to right and top to bottom. Due to the size of the screen of PalmOS devices, both X and Y are integer values between 0 and 159.

Width and height

  Horizontal and vertical size, in pixels. Due to the size of the screen of PalmOS devices, both width and height are integer values between 1 and 160.

  You can also use automatic values calculated from the size of the widget's contents.

## Check box

A check box contains a state icon and a text label. The state icon shows whether the widget is "checked", this state can then be handled by the application via the `CtlGetValue` function.

### Properties

Resource ID

  A unique string ID used for accessing the resource at run-time from the program

Usable

  Non-usable widgets are not rendered on the screen and don't receive events. You can set/unset the "usable" property at run-time with the `CtlSetUsable` function.

Text and font

  The textual contents of the widget. It will be rendered using the specified font.

  Guikachu currently only supports the built-in fonts.

Toggled

  Initial checked/unchecked state of the widget

Group ID

  If a check box or pushbutton belongs to a group, only one per group can be checked by the user. This is automatically enforced by PalmOS. Note that check boxes and pushbuttons share their groups.

  Set the group ID to 0 if you don't want to include it in any group.

Anchor right

  If the widget's size changes at run-time and this flag is set, the new horizontal position is calculated to leave the widget's right edge at place.

X and Y

  Horizontal and vertical position relative to the parent form, in pixels, counted from left to right and top to bottom. Due to the size of the screen of PalmOS devices, both X and Y are integer values between 0 and 159.

Width and height

  Horizontal and vertical size, in pixels. Due to the size of the screen of PalmOS devices, both width and height are integer values between 1 and 160.

  You can also use automatic values calculated from the size of the widget's contents.

## Pushbutton

A pushbutton behaves a lot like a check box, except it has no initial state and is rendered as a rectangular button.

### Properties

Resource ID

  A unique string ID used for accessing the resource at run-time from the program

Usable

  Non-usable widgets are not rendered on the screen and don't receive events. You can set/unset the "usable" property at run-time with the `CtlSetUsable` function.

Text and font

  The textual contents of the widget. It will be rendered using the specified font.

  Guikachu currently only supports the built-in fonts.

Bitmap/Selected Bitmap

  Select a Bitmap or Bitmap Group resource to be displayed instead of the textual caption.

  Usually, you should specify a separate bitmap for the widget's selected state, since otherwise the normal bitmap is used.

Group ID

  If a check box or pushbutton belongs to a group, only one per group can be checked by the user. This is automatically enforced by PalmOS. Note that check boxes and pushbuttons share their groups.

  Set the group ID to 0 if you don't want to include it in any group.

X and Y

  Horizontal and vertical position relative to the parent form, in pixels, counted from left to right and top to bottom. Due to the size of the screen of PalmOS devices, both X and Y are integer values between 0 and 159.

Width and height

  Horizontal and vertical size, in pixels. Due to the size of the screen of PalmOS devices, both width and height are integer values between 1 and 160.

  You can also use automatic values calculated from the size of the widget's contents.

## Selector trigger

Selector triggers are a lot like buttons, the only difference is in the looks. The real difference is in intention: selector triggers should be used in cases where input is done by tapping the trigger, and then filling in the form that pops up.

### Properties

Resource ID

  A unique string ID used for accessing the resource at run-time from the program

Usable

  Non-usable widgets are not rendered on the screen and don't receive events. You can set/unset the "usable" property at run-time with the `CtlSetUsable` function.

Text and font

  The textual contents of the widget. It will be rendered using the specified font.

  Guikachu currently only supports the built-in fonts.

Bitmap/Selected Bitmap

  Select a Bitmap or Bitmap Group resource to be displayed instead of the textual caption.

  Usually, you should specify a separate bitmap for the widget's selected state, since otherwise the normal bitmap is used.

Anchor right

  If the widget's size changes at run-time and this flag is set, the new horizontal position is calculated to leave the widget's right edge at place.

X and Y

  Horizontal and vertical position relative to the parent form, in pixels, counted from left to right and top to bottom. Due to the size of the screen of PalmOS devices, both X and Y are integer values between 0 and 159.

Width and height

  Horizontal and vertical size, in pixels. Due to the size of the screen of PalmOS devices, both width and height are integer values between 1 and 160.

  You can also use automatic values calculated from the size of the widget's contents.

## Popup trigger

Popup triggers are usually called "drop-down lists" or "combo boxes" on other platforms. On tapping, the popup trigger displays a list of items and waits for the user to select a list item.

The list linked to the trigger is usually placed at the same spot as the trigger, with the list set to unusable so it isn't displayed until the trigger is tapped.

### Properties

Resource ID

  A unique string ID used for accessing the resource at run-time from the program

Usable

  Non-usable widgets are not rendered on the screen and don't receive events. You can set/unset the "usable" property at run-time with the `CtlSetUsable` function.

Text and font

  The textual contents of the widget. It will be rendered using the specified font.

  Guikachu currently only supports the built-in fonts.

Bitmap/Selected Bitmap

  Select a Bitmap or Bitmap Group resource to be displayed instead of the textual caption.

  Usually, you should specify a separate bitmap for the widget's selected state, since otherwise the normal bitmap is used.

List ID

  The ID of the list widget to pop up when the trigger is tapped by the user.

Anchor right

  If the widget's size changes at run-time and this flag is set, the new horizontal position is calculated to leave the widget's right edge at place.

X and Y

  Horizontal and vertical position relative to the parent form, in pixels, counted from left to right and top to bottom. Due to the size of the screen of PalmOS devices, both X and Y are integer values between 0 and 159.

Width and height

  Horizontal and vertical size, in pixels. Due to the size of the screen of PalmOS devices, both width and height are integer values between 1 and 160.

  You can also use automatic values calculated from the size of the widget's contents.

## Scroll bar

Scroll bars are vertical rulers displaying a user-changeable value in a given interval. The user can change this value by dragging a slider up or down.

You can use the `SclGetScrollBar`/`SclSetScrollBar` functions to retrieve/modify the value and state of the scroll bar at run-time.

### Properties

Resource ID

  A unique string ID used for accessing the resource at run-time from the program

Usable

  Non-usable widgets are not rendered on the screen and don't receive events. You can set/unset the "usable" property at run-time with the `CtlSetUsable` function.

Value interval

  Minimal and maximal value of the slider.

  Due to limitations of the PalmOS platform, both the minimal and the maximal value need to be integers between 0 and 32767 (this is enforced by the property editor in Guikachu)

Initial value

  The initial value of the scroll bar at start-up, within the valid interval.

Page size

  The amount of change when the user taps the scroll bar instead of dragging the slider or tapping one of the arrows at the end of the bar.

X and Y

  Horizontal and vertical position relative to the parent form, in pixels, counted from left to right and top to bottom. Due to the size of the screen of PalmOS devices, both X and Y are integer values between 0 and 159.

Width and height

  Horizontal and vertical size, in pixels. Due to the size of the screen of PalmOS devices, both width and height are integer values between 1 and 160.

  You can also use automatic values calculated from the size of the widget's contents.

## List

This widget is a list of one-line text items. Selecting a list item emits a `lstSelectEvent`. You can then use `LstGetSelection` in the event handler to get the currently selected item.

Lists are also used by popup triggers: the list linked to the trigger is shown when the trigger is tapped by the user.

### Properties

Resource ID

  A unique string ID used for accessing the resource at run-time from the program

Usable

  Non-usable widgets are not rendered on the screen and don't receive events. You can set/unset the "usable" property at run-time with the `CtlSetUsable` function.

Visible items

  Number of items displayed at a time. There needs to be at least that many items in the list, or undefined things may happen (including the possibility of the PalmOS device freezing).

  If there are more items than displayed at a time, the user is able to scroll through items.

Font

  The font used to display the list items

  Guikachu currently only supports the three default built-in fonts: #0 is the "normal", #1 is the "bold" and #2 is the "large" font.

X and Y

  Horizontal and vertical position relative to the parent form, in pixels, counted from left to right and top to bottom. Due to the size of the screen of PalmOS devices, both X and Y are integer values between 0 and 159.

Width

  Horizontal size, in pixels. Due to the size of the screen of PalmOS devices, this is an integer value between 1 and 160.

  You can also use an automatic value calculated from the width of the first list item.

  The height of the widget will be automatically calculated from the number of visible items and the font used.

## Table

Use tables to show multi-column data. The PalmOS API makes it very easy to bind table cells to database fields and other persistent data.

Most of the behavior of tables are defined at run-time instead of the resource file. Refer to the PalmOS API documentation for further information on the related library functions.

### Properties

Resource ID

  A unique string ID used for accessing the resource at run-time from the program

Number of rows

  The number of rows visible. The height of the rows will be calculated at run-time based on cell type and content.

  The Form Editor displays rows at the default height of 11 pixels.

Columns

  Only the number of columns, and each column's width is stored in the resource file. All other aspects of columns (most notably, their content type) is set at run-time.

X and Y

  Horizontal and vertical position relative to the parent form, in pixels, counted from left to right and top to bottom. Due to the size of the screen of PalmOS devices, both X and Y are integer values between 0 and 159.

Width and height

  Although PilRC allows you to include height and width information for tables, these values are not used, and an automatic size based on column width and number of rows. Due to this, Guikachu doesn't confuse the user with bogus size settings.

## Bitmap widget

### Properties

Resource ID

  A unique string ID used for accessing the resource at run-time from the program

Usable

  Non-usable widgets are not rendered on the screen and don't receive events. You can set/unset the "usable" property at run-time with the `CtlSetUsable` function.

Bitmap ID

  ID of the Bitmap/Bitmap Group resource to display.

X and Y

  Horizontal and vertical position relative to the parent form, in pixels, counted from left to right and top to bottom. Due to the size of the screen of PalmOS devices, both X and Y are integer values between 0 and 159.

## Gadget

Gadgets are placeholders for widgets implemented by the app author. The application is responsible for rendering the widget and maintaining any associated state data.

### Properties

Resource ID

  A unique string ID used for accessing the resource at run-time from the program

Usable

  Non-usable widgets are not rendered on the screen and don't receive events. You can set/unset the "usable" property at run-time with the `CtlSetUsable` function.

X and Y

  Horizontal and vertical position relative to the parent form, in pixels, counted from left to right and top to bottom. Due to the size of the screen of PalmOS devices, both X and Y are integer values between 0 and 159.

Width and height

  Horizontal and vertical size, in pixels. Due to the size of the screen of PalmOS devices, both width and height are integer values between 1 and 160.