Contents > Library Reference > User Interface

User Interface

Objects and functions representing the application's user interface.

Objects and Structures

| Bitmap | A bitmap created in the app designer or resource language.
| Draw | Provides all drawing routines.
| Event | Data related to the current event.
| UIApp | Represents the application.
| UIButton | A button created in the app designer or resource language.
| UICheckbox | A checkbox created in the app designer or resource language.
| UIFBitmap | A form bitmap created in the app designer or resource language.
| UIField | A field created in the app designer or resource language.
| UIForm | A form created in the app designer or resource language.
| UIGadget | Base implementation of a gadget.
| UILabel | A label created in the app designer or resource language.
| UIList | A list created in the app designer or resource language.
| UIMenuItem | A menu item created in the app designer or resource language.
| UIPopup | A popup trigger created in the app designer or resource language.
| UIPushButton | A push button created in the app designer or resource language.
| UIRepeatButton | A repeat button created in the app designer or resource language.
| UIScroll | A scroll bar created in the app designer or resource language.
| UISelector | A selector created in the app designer or resource language.
| UISlider | A slider created in the app designer or resource language.
| UIString | A project string created in the app designer or resource language.

Functions

| void alert(string text) | Displays an alert dialog containing the text text.
| int alertc(string title, string message, string buttons, int type) | Displays an alert dialog with the specified title, text, and buttons. buttons is the text of a button, or a string containing the names of several buttons separated by colons. "OK:Cancel".
| bool confirm(string text) | Displays a confirmation dialog containing the text text and "yes" and "no" buttons. Returns true if the user tapped "yes", false otherwise.
| string prompt(string text) | Displays an input prompt with the specified text, returning the string entered by the user. If the user presses the Cancel button, an empty string is returned. Works only on OS 3.5 and higher.
| int promptc(string title, string message, string buttons, int type, string* pentry) | Displays an input prompt with the specified title, message, and buttons. buttons is the text of a button, or a string containing the names of several buttons separated by colons. "OK:Cancel".
| int promptcd(string title, string message, string buttons, int type, string text, string* pentry) | Displays an input prompt with the specified title, message, and buttons. text is used to initialize the prompt's field. buttons is the text of a button, or a string containing the names of several buttons separated by colons. "OK:Cancel".
| int keystate() | Retrieves the current set of pressed keys. Can be zero of more of the following flags: keyPageUp, keyPageDown, keyHard1-keyHard4, keyContrast. The return value may also include other device-specific flags.
| bool penstate() | Retrieves the current state of the pen: true for down, false for up.

Additional Topics

| Color Tables | A table of colors by index.

Contents > Library Reference > User Interface > Bitmap object

Bitmap

A Bitmap object represents a bitmap created in the app designer or resource language. An object of this type is automatically created by the app designer or compiler for each bitmap defined in you application. Do not create Bitmap objects manually. A Bitmap can be drawn using Draw.bitmap().

Contents > Library Reference > User Interface > Draw object

Draw

The Draw object provides access to all drawing functions. There are several steps involved in setting up and using a Draw object. First, the object must either be attached to a form or gadget, or created as an offscreen buffer. If the object is attached to a form or gadget, all drawing operations are applied immediately to the form or gadget. There are two ways to create an offscreen buffer -- either using the create method, or the copyForm/copyGadget method. If the object is set up as an offscreen buffer, it must be released when no longer needed.

Before drawing to an object, the begin or nbegin method must be called. When finished, the end method must be called. Note: Only one object may be in drawing mode at a time. For a discussion of drawing in native resolutions, see High Density Graphics.

The available colors are determined by the current color depth. Use UIApp.getdepth() to find the current depth. For color tables, see Color Tables. The RGB functions can be used in any color depth - the system will set the color to the nearest palette entry in 1-, 2-, 4-, and 8-bit mode.

Object Properties

| int handle | The WinHandle of the the draw object. This handle is only available for offscreen buffers, and only if the begin() method has been called.
| int nw | Gets the width of the drawing surface in native pixels. This value can only be retrieved after calling nbegin() and before calling end().
| int nh | Gets the height of the drawing surface in native pixels. This value can only be retrieved after calling nbegin() and before calling end().

Object Methods

| void attachForm(UIForm form) | Attaches this object to form. All operations performed on this Draw object will immediately affect the attached form. There is no need to call release().
| void attachGadget(UIGadget gadget) | Attaches this object to gadget. All operations performed on this Draw object will immediately affect the attached gadget. There is no need to call release().
| bool create(int w, int h) | Creates an offscreen buffer with width w and height h. release() must be called when the offscreen buffer is no longer needed.
| bool copyForm(UIForm form) | Creates an offscreen buffer the same size as form, and copies the form's contents to the buffer. release() must be called when the offscreen buffer is no longer needed.
| bool copyGadget(UIGadget gadget) | Creates an offscreen buffer the same size as gadget, and copies the gadget's contents to the buffer. release() must be called when the offscreen buffer is no longer needed.
| void release() | Releases the offscreen buffer if one was created.
| void begin() | Prepares the object for drawing. Either this method or nbegin() must be called before any drawing operation.
| void nbegin() | Prepares the object for drawing at native resolution. Either this method or begin() must be called before any drawing operation.
| void end() | Cleans up from the drawing process. This must be called after the drawing operations are complete.
| int fg(int index) | Sets the foreground color to the color specified by index in the current palette.
| void fgRGB(int r, int g, int b) | Sets the foreground color.
| int bg(int index) | Sets the background color to the color specified by index in the current palette.
| void bgRGB(int r, int g, int b) | Sets the background color.
| int textColor(int index) | Sets the text color to the color specified by index in the current palette.
| void textRGB(int r, int g, int b) | Sets the text color.
| int font(int fontid) | Sets the drawing font to be used by the text method.
| int textAlign(int mode) | Sets the text alignment mode used by the text method.
| int textWidth(string str) | Measures the number of pixel required to display str in the currently selected font.
| int textHeight() | Measures the height in pixels of the currently selected font.
| int underline(int mode) | Sets the underline mode to be used by the text method.
| int indexFromColor(int r, int g, int b) | Calculates the nearest index in the current color palette to the color specified by (r, g, b).
| int uiColor(int uiType) | Retrieves the color the system uses to draw a particular UI element. Only available on OS 3.5 and higher - on earlier OSes this method returns 0.
| bool selectIndex(string title, int* pIndex) | Displays a color picker dialog box with the given title. pIndex is a pointer to an int which contains initial color index and which will contain the selected index upon return. If the user selected a color, this method return true; if the user canceled, false is returned. Do NOT call this method during a draw operation (between begin and end). Available only on OS 3.5 and higher.
| void line(int c, int x1, int y1, int x2, int y2) | Draws a line from (x1, y1) to (x2, y2) in color c.
| void pixel(int c, int x, int y) | Draws a pixel at (x, y).
| void rect(int c, int x1, int y1, int x2, int y2, int rad) | Draws a solid rectangle from (x1, y1) to (x2, y2) in color c, with rounded corners of radius rad.
| void frame(int c, int x1, int y1, int x2, int y2, int rad, int thick) | Draws an empty frame from (x1, y1) to (x2, y2) in color c, with rounded corners of radius rad and line thickness thick.
| void bitmap(Bitmap bmp, int x, int y) | Draws the bitmap bmp at (x, y).
| void bitmapm(Bitmap bmp, int x, int y, int mode) | Draws the bitmap bmp at (x, y), using the specified mode.
| void text(int c, int x, int y, string text) | Draws the text text at (x, y).
| void textTrunc(int x, int y, int w, string text) | Draws the text text at (x, y), truncating and adding "..." it if necessary so that its width is no more than w.
| void draw(Draw d, int x, int y) | Draws the contents of d at (x, y).
| void drawm(Draw d, int x, int y, int mode) | Draws the contents of d at (x, y), using the specified mode.

Contents > Library Reference > User Interface > Event object

Event

The Event object provides details about the current user event. Depending on the event that occured, only some of the properties will provide useful information. There is a global Event object named 'event', so there is no need for the user to create one.

Object Properties

| int x | The relative horizontal location at which the event occured
| int y | The relative vertical location at which the event occured
| int nx | The relative horizontal location in native pixels at which the event occured
| int ny | The relative vertical location in native pixels at which the event occured
| bool inside | True if the pen location is within the object
| int value | The new value of the object
| int prev | The previous value of the object
| char key | The key entered or hard key pressed
| int code | The form redraw code specified in the call to UIForm.redraw(). If the form is being redrawn by the system, code is 0x8000

Contents > Library Reference > User Interface > UIApp object

UIApp

The UIApp object represents your application. A global UIApp object is created by the app designer or resource language, using the name that you provide. Do not create UIApp objects manually.

Object Properties

| string version | Gets the string version of the current application.
| string creator | Gets the creator id of the current application.
| string launchArgs | Gets the string passed to your app when launched. See launchCustomString.

Object Methods

| int getdepth() | Gets the current color depth in bits per pixel.
| bool setdepth(int bits) | Sets the current color depth to bits bits per pixel. Returns true if successful. This will fail if the hardware does not support the the color depth.
| int getScreenAttrib(int attrib) | Retrieves various screen attributes. This method is only supported on OS 5 and higher - it will always return 0 on earlier OSes.
| int getSysPref(int prefID) | Retrieves various system preference values.
| void hookhard(bool hook) | Enables the app to handle the hard keys (Memo, Address, etc.). If hook is false, the system will process the keys. If hook is true, pressing the hard keys will generate calls to the current form's onhkey handler.
| void abort() | Forcefully exits the application. This method should only be called in the case of a fatal error since it aborts the application immediately without calling any handlers. If you would like to display an error message before exiting, using fatal instead.

Object Handlers

| onstart | Called when the application is started. All app initialization should occur here.
| onstop | Called when the application is exiting. All app cleanup work should occur here, and should execute quickly. There is no way to keep the app from exiting.

Contents > Library Reference > User Interface > UIButton object

UIButton

The UIButton object represents a button in your application. The app designer automatically creates objects of this type for each button in your application. Do not create UIButton objects manually.

Setting the x, y, w, and h properties may only be set when the control is invisible.

Object Properties

| int x | Gets or sets the x value of control location.
| int y | Gets or sets the y value of control location.
| int w | Gets or sets the width of the control.
| int h | Gets or sets the height of the control.
| bool visible | Gets or sets the visibility of the control.
| bool enabled | Gets or sets whether this control will receive input.
| int bmpid | Sets the default bitmap for a graphic control. This property cannot be read. Ex. button.bmpid = newbitmap.id;
| int sbmpid | Sets the selected bitmap for a graphic control. This property cannot be read.
| string text | Gets or sets the button caption. Do not use for graphic controls.

Object Handlers

| onselect | Called when the button is tapped.

Contents > Library Reference > User Interface > UICheckbox object

UICheckbox

The UICheckbox object represents a checkbox in your application. The app designer automatically creates objects of this type for each checkbox in your application. Do not create UICheckbox objects manually.

Setting the x, y, w, and h properties may only be set when the control is invisible.

Object Properties

| int x | Gets or sets the x value of control location.
| int y | Gets or sets the y value of control location.
| int w | Gets or sets the width of the control.
| int h | Gets or sets the height of the control.
| bool visible | Gets or sets the visibility of the control.
| bool enabled | Gets or sets whether this control will receive input.
| int checked | Gets or sets the check on the checkbox
| string text | Gets or sets the checkbox caption.

Object Handlers

| onselect | Called when the checkbox is tapped. UICheckbox.checked contains the new value.

Contents > Library Reference > User Interface > UIFBitmap object

UIFBitmap

The UIFBitmap object represents a form bitmap in your application. The app designer automatically creates objects of this type for each form bitmap in your application. Do not create UIFBitmap objects manually.

Setting the x and y properties may only be done when the bitmap is invisible. bitmap must first be made invisible, then visible again to redraw it.

Object Properties

| int x | Gets or sets the x value of bitmap location.
| int y | Gets or sets the y value of bitmap location.
| int w | Gets the width of the bitmap.
| int h | Gets the height of the bitmap.
| bool visible | Gets or sets the visibility of the control.

Contents > Library Reference > User Interface > UIField object

UIField

The UIField object represents a field in your application. The app designer automatically creates objects of this type for each field in you application. Do not create UIField objects manually.

For details on how to associate a field to a scroll bar, see UIScroll

Setting the x, y, w, and h properties may only be set when the control is invisible.

Object Properties

| int x | Gets or sets the x value of control location.
| int y | Gets or sets the y value of control location.
| int w | Gets or sets the width of the control.
| int h | Gets or sets the height of the control.
| bool visible | Gets or sets the visibility of the control.
| bool editable | Sets whether of not the field can be edited. This property cannot be read.
| bool numeric | Sets whether of not the field is restricted to numbers. This property cannot be read.
| string text | Gets or sets the text of the field.
| int inspt | Gets or sets the insertion point as an index into the text.
| string seltext | Gets or sets the selected text. Setting the text overwrite the current selection, or insert the text at the insertion point if there is no selection.
| int fontid | Gets or sets the field font. Crashes on OS < 3.5 (OS bug)
| int scrollpos | Gets the offset of the first visible character in the first visible line in the field.
| int dirty | Gets or sets the dirty attribute.
| int underline | Sets the underline style of a field. Valid values are ulNone, ulDot, ulSolid.

Object Methods

| void insert(string text) | Inserts text at the current insertion point.
| void select(int start, int end) | Sets the selection to the characters inclusively between start and end.
| void cut() | Cuts the current selection and places it on the clipboard.
| void copy() | Copies the current selection to the clipboard.
| void paste() | Paste the contents of the clipboard to the current insertion point.
| void undo() | Undoes the last editing operation. Some operations cannot be undone.
| void del(int start, int end) | Deletes the text inclusively between the start and end.
| void grabfocus() | Sets the focus of the current form to this field.
| void relfocus() | Releases the focus from this field.
| void scroll(int nLines) | Scrolls the field down nLines lines. If nLines is negative, the field is scrolled up. Call this method if the user drags a scroll bar associated with this field. See UIScroll for details.
| void phonelookup() | Searches the address book and replaces the selected text or word at the cursor with the matching entry from the address book.

Object Handlers

| onchange | Called when a key event has occured in the field, usually causing the contents of the field to change. To get the new value of the field, retrieve the text property.
| onhchange | Called when the height of the field has changed. If this field is associated with a scroll bar, this is the time to call UIScroll.update

Contents > Library Reference > User Interface > UIForm object

UIForm

The UIForm object represents a form in your application. The app designer or compiler automatically creates objects of this type for each form in your application. Do not create UIForm objects manually.

There are two types of forms - regular and modal (see also Forms and Controls). Only one regular form can be displayed at a time. When you load a regular form, any previous normal form is first closed. A modal form is displayed on top of another form (like a dialog box on desktop operating systems). The way that a form must be opened and closed depends on whether it is a regular form or a modal form. The rules are as follows:

- Regular Forms: A regular form is opened using the load method. Since only one regular form can be open at a time, loading a new form closes the previously opened regular form (if there was one). Calling load does not immediately open the form. Instead, it posts a message to the OS event queue which will eventually open it. Because of this you cannot access any controls on the form until the onopen handler is executed.
- Modal Forms: A modal form is opened using the domodal method. The domodal method does not open the form immediately, instead it schedules the form to be opened in the same way as the load method does for regular forms. A modal form opened with domodal must be closed by using the close method. You may NOT load a regular form from a modal form.
- Modal Forms as Dialogs: A modal form can also be opened as a dialog using the dodialog method. When opened as a dialog, the modal form is opened immediately and the dodialog method does not return until the user selects a button on the form. Once a button is pressed, the form closes, and the id of the button is returned. Note: A modal form that is opened with dodialog will not receive events, and the controls on the form will not receive events.

Resizable Forms: OrbC allows your application to easily handle screen layout changes on devices with a dynamic input area (only OS 5+ devices and later Sony devices are supported). The runtime automatically resizes and moves forms and controls according to the form and control properties. In most cases this will be sufficient. When more complex behavior is required (such as needing to stetch two controls to each grow half of the additional space), you must write a handler for the onresize event. When the event is called, the automatic resizing has already been done, so only the more complicated controls need to be adjusted. The form's current width and height should be used to determine the new control positions and sizes.

Resizable Form Note: The Tungsten T3 device shipped before Palm standardized the dynamic input area APIs. In order to fully use resizable forms on a T3, the T3 DIA compatibility libraries must be installed on the device. For you convenience, these library are included in the PocketC Architect installation directory.

Object Properties

| int x | Gets the x value of form location
| int y | Gets the y value of form location
| int w | Gets the width of the form
| int h | Gets the height of the form
| string title | Gets or sets the title of the form
| int menu | Sets the menu bar of the form using the id of the menu bar. `form.menu = menubar.id`. This property is write-only.
| bool obscured | Gets whether or not something is obscuring the form. This property is true when a menu or pop-up list is displayed above the form.

Object Methods

| void load() | Loads the form and sets it to be displayed. If another form is currently open, it is first closed. Returns immediately.
| void close() | Close the form and return to the previous form. This should only be called on a modal form, and is usually called in an onselect handler for a button.
| void redraw(int code) | Queues an event to redraw the form, eventually calling the ondraw handler. The code can be retrieved in the ondraw handler through the Event object's code property.
| void domodal() | Loads the modal form and sets it to be displayed. Returns immediately. To execute a modal form synchronously (to wait until the user dismisses the form before continuing), use the events() function.
| int dodialog() | Loads the modal form, displays it as a dialog, and returns the id of the button the user pressed. The form and its controls will not receive events.
| void timer(int nticks) | Sets a timer to be fired after nticks clock ticks (approx. 1/100 sec). When the timer is fired, the form's ontimer handler is called. The form will only receive the timer event if it is the active window.
| void select(int groupid, int ctrlid) | Selects a pushbutton in the group specified by groupid. Use the id member of the pushbutton as ctrlid.
| void help(UIString str) | Display a help form with the specified string str as the help text (same form displayed when clicking the (i) icon on a modal form). The string str is the name of one of the strings in your project.
| UIField* activefield() | Retrieve the pointer of the currently active field, or null if no field is active.
| void keyboard() | Displays the system keyboard dialog if there is an active field on the form.

Object Handlers

| onopen | Called when the form is first opening, but before it is displayed. No Draw methods can be called at this point, but controls on the form can be manipulated. This is the appropriate time to initialize the controls (e.g. by checking checkboxes, filling lists).
| onclose | Called when the form is closing. No drawing can be done at this point.
| ondraw | Called when the system requires the form to be drawn.
| onresize | Called after the form and its controls have been resized. This event is only generated for resizable form. In this handler, only controls should be moved or resized - no drawing is allowed.
| onchar | Called when the user enters a keystroke when no field is active.
| onhkey | Called when the user presses one of the hard keys, or a virtual key press is generated by the OS. When called, event.key will be one of ev0, ev1, ev2, ev3, evNextField, evPrevField, evUp, evDown, evLeft, evRight, evSelect, evJogPush, evJogPushRepeat, evJogRelease. To receive this event for the four application buttons, you must first call UIApp.hookhard(). evLeft, evRight, and evSelect will only occur on a device with a 5-way control (e.g. Tungsten T). evJog only occur on a device with a Jog control.
| ontimer | Called when the active form has set a timer and it has expired. This is the correct place to set a new timer if you want the timer to fire repeatedly.
| onpendown | Called when the pen is placed down on the screen within the bounds of this form.
| onpenup | Called when the pen is removed from the screen and was originally placed down on the screen within the bounds of this form.
| onpenmove | Called when the pen is moved on the screen and was originally placed down on the screen within the bounds of this form.

Contents > Library Reference > User Interface > UIGadget object

UIGadget

The UIGadget object is used by user-defined gadgets. Each user defined gadget object type contains an instance of UIGadget as its first member. See the topic Gadgets for full details.

The x, y, w, and h properties may only be set when the gadget is invisible. Also, if a Draw object is currently attached to the gadget, it must be re-attached or drawing will occur in the wrong location.

Object Properties

| int x | Gets or sets the x value of control location.
| int y | Gets or sets the y value of control location.
| int w | Gets or sets the width of the control.
| int h | Gets or sets the height of the control.
| bool visible | Gets or sets the visibility of the control.
| bool enabled | Gets or sets whether this control will receive input.

Object Handlers

| onopen | Called when the form containing the gadget is being opened. No Draw method can be called at this time. This is called after the form's onopen event.
| onclose | Called when the form containing the gadget is being closed. No drawing can be done at this time. This is called before the form's onclose event.
| ondraw | Called when the form containing the gadget needs to be drawn. This is called after the form's ondraw event.
| onpendown | Called when the pen is placed down on the screen within the bounds of this gadget.
| onpenup | Called when the pen is removed from the screen and was originally placed down on the screen within the bounds of this gadget.
| onpenmove | Called when the pen is move on the screen and was originally placed down on the screen within the bounds of this gadget.

Contents > Library Reference > User Interface > UILabel object

UILabel

The UILabel object represents a label in your application. The app designer automatically creates objects of this type for label item in your application. Do not create UILabel objects manually.

Although the text of the label can be changed programmatically using the text property, the length of the label (in characters) cannot exceed the length of the text defined in the visual designer. So, if the original text was "ABC", and you attempt to set it to "WXYZ", the new text would be truncated to just the first 3 characters, "WXY".

Setting the x and y properties may only be done when the control is invisible.

Object Properties

| int x | Gets or sets the x value of control location.
| int y | Gets or sets the y value of control location.
| int w | Gets the width of the control.
| int h | Gets the height of the control.
| bool visible | Gets or sets the visibility of the control.
| string text | Gets or sets the label caption.

Contents > Library Reference > User Interface > UIList object

UIList

The UIList object represents a list in your application. The app designer automatically creates objects of this type for each list in you application. Do not create UIList objects manually.

Setting the x, y, w, and h properties can only be done on a list associated with a popup, and only when it is not visible.

Object Properties

| int x | Gets or sets the x value of control location.
| int y | Gets or sets the y value of control location.
| int w | Gets or sets the width of the control.
| int h | Gets or sets the height of the control.
| bool visible | Gets or sets the visibility of the control. This property only works on OS 3.5 and higher. This property cannot be read.
| int selitem | Gets or sets the item selected. Evaluates to -1 if no item is selected.
| int topitem | Sets the top visible item. This property cannot be read.
| int count | Gets the number of items in the list.

Object Methods

| bool setitems(int num, string* ptext) | Sets the items in the list. ptext is an array of num strings in the order in which they will be displayed in the list.
| bool setitemslist(StringList sl) | Sets the items in the list to the contents of sl.
| string gettext(int index) | Gets the text assosciate with the item at location index.
| void makevisible(int index) | Makes the item at location index visible.
| bool scroll(int lines) | Scrolls the list down lines lines. If lines is negative, the list is scrolled up. Returns true if the list is actually scrolled.
| int popup() | Displays the list as a popup list and returns the item selected or -1 if none selected.
| void redraw() | Redraws the list. After the list items are set, the list should be redrawn. Just like other drawing functions, this may not be called in a forms onopen handler.
| void setdrawfunc(UIListDrawFunc func) | Sets the custom drawing function for the list. Specifying null causes the OS to draw the list itself.

Object Handlers

| onselect | Called when the user makes a selection. event.value contains the newly selected item.

Contents > Library Reference > User Interface > UIMenuItem object

UIMenuItem

The UIMenuItem object represents a menu item in your application. The app designer automatically creates objects of this type for each menu item in your application. Do not create UIMenuItem objects manually.

Object Handlers

| onselect | Called when the user selects the menu item.

Contents > Library Reference > User Interface > UIPopup object

UIPopup

The UIPopup object represents a popup trigger in your application. The app designer automatically creates objects of this type for each popup in you application. Do not create UIPopup objects manually.

When a popup is selected, it should display a list from which the user may select an option. To do this, the list must be associated with the popup. In the app designer or resource language, create the popup and the list in the same location. Set the "Trigger ID" property of the list to the name of the popup.

Handling the selection of the list item can be done in two ways (these methods may not be used together - you may only define ONE of the two handlers):

- Define a handler for the popup's onselect event. In this handler call the popup() method of the list, which will return the index of the selected item (or -1). Use this method if you need to set the contents of the list when the popup is selected.
- Define a handler for the popup's onlistselect event. This event provides you with the index of the selected item and the previously selected item.

When an item from the list is selected, the text of the popup will be updated but ONLY if no handler is defined. If you defing a handler, you will need to update the popup text manually. Also, when the form is first opened, the application must set the text correctly.

Setting the x, y, w, and h properties may only be set when the control is invisible.

Object Properties

| int x | Gets or sets the x value of control location.
| int y | Gets or sets the y value of control location.
| int w | Gets or sets the width of the control.
| int h | Gets or sets the height of the control.
| bool visible | Gets or sets the visibility of the control.
| bool enabled | Gets or sets whether this control will receive input.
| string text | Gets or sets the popup caption.

Object Handlers

| onselect | Called when the user taps the popup trigger. If this popup should display a list (which is the primary purpose of the control), this is the appropriate time to call UIList.popup(). If this handler is defined, onlistselect will not be executed.
| onlistselect | Called when/if the user selects an item from the popup list. event.value contains the newly selected item, and event.prev contains the previously selected item. This handler will only be executed if onselect is not defined.

Contents > Library Reference > User Interface > UIPushButton object

UIPushButton

The UIPushButton object represents a push button in your application. The app designer automatically creates objects of this type for each push button in your application. Do not create UIPushButton objects manually.

Setting the x, y, w, and h properties may only be set when the control is invisible.

Object Properties

| int x | Gets or sets the x value of control location.
| int y | Gets or sets the y value of control location.
| int w | Gets or sets the width of the control.
| int h | Gets or sets the height of the control.
| bool visible | Gets or sets the visibility of the control.
| bool enabled | Gets or sets whether this control will receive input.
| int bmpid | Sets the default bitmap for a graphic control. This property cannot be read. Ex. button.bmpid = newbitmap.id;
| int sbmpid | Sets the selected bitmap for a graphic control. This property cannot be read.
| int checked | Gets or sets the selection of the pushbutton. However, this method does not uncheck the other buttons in the group. In order to properly select a push button from a group, use UIForm.select().
| string text | Gets or sets the pushbutton caption. Do not use for graphic controls.

Object Handlers

| onselect | Called when the push button is tapped. UIPushButton.checked contains the new value.

Contents > Library Reference > User Interface > UIRepeatButton object

UIRepeatButton

The UIRepeatButton object represents a repeat button in your application. The app designer or compiler automatically creates objects of this type for each repeat button in your application. Do not create UIRepeatButton objects manually.

Setting the x, y, w, and h properties may only be set when the control is invisible.

Object Properties

| int x | Gets or sets the x value of control location.
| int y | Gets or sets the y value of control location.
| int w | Gets or sets the width of the control.
| int h | Gets or sets the height of the control.
| bool visible | Gets or sets the visibility of the control.
| bool enabled | Gets or sets whether this control will receive input.
| int bmpid | Sets the default bitmap for a graphic control. This property cannot be read. Ex. button.bmpid = newbitmap.id;
| int sbmpid | Sets the selected bitmap for a graphic control. This property cannot be read.
| string text | Gets or sets the repeatbutton caption. Do not use for graphic controls.

Object Handlers

| onselect | Called when the repeat button is tapped, or hold long enough to generate another event.

Contents > Library Reference > User Interface > UIScroll object

UIScroll

The UIScroll object represents a scroll bar in your application. The app designer automatically creates objects of this type for each scroll bar in your application. Do not create UIScroll objects manually.

Scroll bars can be used by themselves, but are usually used with a UIField. There a few simple things you need to do to associate a field with a scroll bar.

- Set the "Has Scroll" property of the field
- In the form's onopen handler, call UIScroll.update
- In the field's onhchange handler, call UIScroll.update
- In either the onmove OR ondone handler, call UIField.scroll(event.value - event.prev). Follow that with a call to update
- When you set the text of the control using the UIField.text property, call UIScroll.update

Setting the x, y, w, and h properties may only be set when the scrollbar is invisible.

Object Properties

| int x | Gets or sets the x value of control location.
| int y | Gets or sets the y value of control location.
| int w | Gets or sets the width of the control.
| int h | Gets or sets the height of the control.
| bool visible | Gets or sets the visibility of the control. This property is only supported on OS 3.5 and higher.
| int value | Gets or sets the value of the scroll bar position.
| int min | Gets or sets the minimum value.
| int max | Gets or sets the maximum value.
| int page | Gets or sets the page value.

Object Methods

| void update(UIField field) | Updates the position, min, max, and page values of this scroll bar to match the associated field. Call this method when the height of the field has changed, or when the user drags the scroll bar.

Object Handlers

| onmove | Called when the user has moved the scroll bar, but has not released it yet. event.value has the new value, and event.prev has the previous value. If you implement this handler, you do NOT need to implement ondone.
| ondone | Called when the user stops moving the slider. event.value has the new value, event.prev has the previous value. If you implement this handler, you do NOT need to implement onmove.

Contents > Library Reference > User Interface > UISelector object

UISelector

The UISelector object represents a selector in your application. The app designer automatically creates objects of this type for each selector in you application. Do not create UISelector objects manually.

Setting the x, y, w, and h properties may only be set when the control is invisible.

Object Properties

| int x | Gets or sets the x value of control location.
| int y | Gets or sets the y value of control location.
| int w | Gets or sets the width of the control.
| int h | Gets or sets the height of the control.
| bool visible | Gets or sets the visibility of the control.
| bool enabled | Gets or sets whether this control will receive input.
| string text | Gets or sets the selector caption.

Object Handlers

| onselect | Called when the selector is tapped.

Contents > Library Reference > User Interface > UISlider object

UISlider

The UISlider object represents a slider in your application. The app designer automatically creates objects of this type for each slider in your application. Do not create UISlider objects manually.

Setting the x, y, w, and h properties may only be set when the slider is invisible.

Object Properties

| int x | Gets or sets the x value of control location.
| int y | Gets or sets the y value of control location.
| int w | Gets or sets the width of the control.
| int h | Gets or sets the height of the control.
| bool visible | Gets or sets the visibility of the control.
| int value | Gets or sets the value of the slider position.
| int min | Gets or sets the minimum value.
| int max | Gets or sets the maximum value.
| int page | Gets or sets the page value.

Object Handlers

| onmove | Called when the user has moved the slider, but has not released it yet. event.value has the new value.
| ondone | Called when the user stops moving the slider. UISlider.value has the new value.

Contents > Library Reference > User Interface > UIString object

UIString

A UIString object represents a project string created in the app designer or resource language. An object of this type is automatically created by the app designer or compiler for each project string defined in you application. Do not create UIString objects manually. A UIString can be displayed in a help form using UIForm.help().

A UIString can be specified directly in source code using the following syntax:

    @resstring UIString stringName {
      id = string id number
      text = "your text here"
    }

Object Properties

| string text | Gets the value of the string resource.

Contents > Library Reference > User Interface > Draw object > attachForm

Draw.attachForm

`void attachForm(UIForm form)`

Parameters:

| form | form to attach to

Attaches this object to form. All operations performed on this Draw object will immediately affect the attached form. There is no need to call release().

Contents > Library Reference > User Interface > Draw object > attachGadget

Draw.attachGadget

`void attachGadget(UIGadget gadget)`

Parameters:

| gadget | gadget to attach to

Attaches this object to gadget. All operations performed on this Draw object will immediately affect the attached gadget. There is no need to call release().

Contents > Library Reference > User Interface > Draw object > create

Draw.create

`bool create(int w, int h)`

Parameters:

| w | width
| h | height

Return value: true on success

Creates an offscreen buffer with width w and height h. release() must be called when the offscreen buffer is no longer needed.

Contents > Library Reference > User Interface > Draw object > copyForm

Draw.copyForm

`bool copyForm(UIForm form)`

Parameters:

| form | form to copy

Return value: true on success

Creates an offscreen buffer the same size as form, and copies the form's contents to the buffer. release() must be called when the offscreen buffer is no longer needed.

Contents > Library Reference > User Interface > Draw object > copyGadget

Draw.copyGadget

`bool copyGadget(UIGadget gadget)`

Parameters:

| gadget | gadget to copy

Return value: true on success

Creates an offscreen buffer the same size as gadget, and copies the gadget's contents to the buffer. release() must be called when the offscreen buffer is no longer needed.

Contents > Library Reference > User Interface > Draw object > release

Draw.release

`void release()`

Releases the offscreen buffer if one was created.

Contents > Library Reference > User Interface > Draw object > begin

Draw.begin

`void begin()`

Prepares the object for drawing. Either this method or nbegin() must be called before any drawing operation.

Contents > Library Reference > User Interface > Draw object > nbegin

Draw.nbegin

`void nbegin()`

Prepares the object for drawing at native resolution. Either this method or begin() must be called before any drawing operation.

Contents > Library Reference > User Interface > Draw object > end

Draw.end

`void end()`

Cleans up from the drawing process. This must be called after the drawing operations are complete.

Contents > Library Reference > User Interface > Draw object > fg

Draw.fg

`int fg(int index)`

Parameters:

| index | color index

Return value: previous color index

Sets the foreground color to the color specified by index in the current palette.

Contents > Library Reference > User Interface > Draw object > fgRGB

Draw.fgRGB

`void fgRGB(int r, int g, int b)`

Parameters:

| r | red value
| g | green value
| b | blue value

Sets the foreground color.

Contents > Library Reference > User Interface > Draw object > bg

Draw.bg

`int bg(int index)`

Parameters:

| index | color index

Return value: previous color index

Sets the background color to the color specified by index in the current palette.

Contents > Library Reference > User Interface > Draw object > bgRGB

Draw.bgRGB

`void bgRGB(int r, int g, int b)`

Parameters:

| r | red value
| g | green value
| b | blue value

Sets the background color.

Contents > Library Reference > User Interface > Draw object > textColor

Draw.textColor

`int textColor(int index)`

Parameters:

| index | color index

Return value: previous color index

Sets the text color to the color specified by index in the current palette.

Contents > Library Reference > User Interface > Draw object > textRGB

Draw.textRGB

`void textRGB(int r, int g, int b)`

Parameters:

| r | red value
| g | green value
| b | blue value

Sets the text color.

Contents > Library Reference > User Interface > Draw object > font

Draw.font

`int font(int fontid)`

Parameters:

| fontid | font id to draw with

Return value: previous font id

Sets the drawing font to be used by the text method.

Note: Valid font ids are: fntStandard, fntBold, fntLarge, fntSymbol, fntSymbol11, fntSymbol7, fntLED, fntLargeBold

Contents > Library Reference > User Interface > Draw object > textAlign

Draw.textAlign

`int textAlign(int mode)`

Parameters:

| mode | text alignment mode

Return value: previous text alignment mode

Sets the text alignment mode used by the text method.

Note: mode is a number between 0 and 22. The first digit specifies the vertical alignment (0=top, 1=center, 2=bottom), and the second digit specifies horizontal alignment (0=left, 1=center, 2=right). When mode is 0, the point specified to the text method is used as the top left of the text to be drawn.

Contents > Library Reference > User Interface > Draw object > textWidth

Draw.textWidth

`int textWidth(string str)`

Parameters:

| str | string to measure

Return value: pixel width of string in current font

Measures the number of pixel required to display str in the currently selected font.

Contents > Library Reference > User Interface > Draw object > textHeight

Draw.textHeight

`int textHeight()`

Return value: pixel height of the current font

Measures the height in pixels of the currently selected font.

Contents > Library Reference > User Interface > Draw object > underline

Draw.underline

`int underline(int mode)`

Parameters:

| mode | underline mode

Return value: previous underline mode

Sets the underline mode to be used by the text method.

Note: Valid underline modes are: ulNone, ulDot, ulSolid

Contents > Library Reference > User Interface > Draw object > indexFromColor

Draw.indexFromColor

`int indexFromColor(int r, int g, int b)`

Parameters:

| r | red value
| g | green value
| b | blue value

Return value: index of nearest color

Calculates the nearest index in the current color palette to the color specified by (r, g, b).

Contents > Library Reference > User Interface > Draw object > uiColor

Draw.uiColor

`int uiColor(int uiType)`

Parameters:

| uiType | UI element to retrieve

Return value: color index of the UI element

Retrieves the color the system uses to draw a particular UI element. Only available on OS 3.5 and higher - on earlier OSes this method returns 0.

Note: Valid UI elements are: uiColorObjectFrame, uiColorObjectFill, uiColorObjectForeground, uiColorObjectSelectedFill, uiColorObjectSelectedForeground, uiColorMenuFrame, uiColorMenuFill, uiColorMenuForeground, uiColorMenuSelectedFill, uiColorMenuSelectedForeground, uiColorFieldBackground, uiColorFieldText, uiColorFieldTextLines, uiColorFieldCaret, uiColorFieldTextHighlightBackground, uiColorFieldTextHighlightForeground, uiColorFieldFepRawText, uiColorFieldFepRawBackground, uiColorFieldFepConvertedText, uiColorFieldFepConvertedBackground, uiColorFieldFepUnderline, uiColorFormFrame, uiColorFormFill, uiColorDialogFrame, uiColorDialogFill, uiColorAlertFrame, uiColorAlertFill, uiColorOK, uiColorCaution, uiColorWarning.

Contents > Library Reference > User Interface > Draw object > selectIndex

Draw.selectIndex

`bool selectIndex(string title, int* pIndex)`

Parameters:

| title | title for color selector dialog
| pIndex | pointer to index

Return value: whether the user selected a color

Displays a color picker dialog box with the given title. pIndex is a pointer to an int which contains initial color index and which will contain the selected index upon return. If the user selected a color, this method return true; if the user canceled, false is returned. Do NOT call this method during a draw operation (between begin and end). Available only on OS 3.5 and higher.

Contents > Library Reference > User Interface > Draw object > line

Draw.line

`void line(int c, int x1, int y1, int x2, int y2)`

Parameters:

| c | color
| x1 | start x
| y1 | start y
| x2 | end x
| y2 | end y

Draws a line from (x1, y1) to (x2, y2) in color c.

Note: Valid colors are: clrFG, clrBG, clrDot, clrXOR.

Contents > Library Reference > User Interface > Draw object > pixel

Draw.pixel

`void pixel(int c, int x, int y)`

Parameters:

| c | color
| x | x value
| y | y value

Draws a pixel at (x, y).

Note: Valid colors are: clrFG, clrBG, clrXOR.

Contents > Library Reference > User Interface > Draw object > rect

Draw.rect

`void rect(int c, int x1, int y1, int x2, int y2, int rad)`

Parameters:

| c | color
| x1 | start x
| y1 | start y
| x2 | end x
| y2 | end y
| rad | corner radius

Draws a solid rectangle from (x1, y1) to (x2, y2) in color c, with rounded corners of radius rad.

Note: Valid colors are: clrFG, clrBG, clrXOR.

Contents > Library Reference > User Interface > Draw object > frame

Draw.frame

`void frame(int c, int x1, int y1, int x2, int y2, int rad, int thick)`

Parameters:

| c | color
| x1 | start x
| y1 | start y
| x2 | end x
| y2 | end y
| rad | corner radius
| thick | thickness

Draws an empty frame from (x1, y1) to (x2, y2) in color c, with rounded corners of radius rad and line thickness thick.

Note: Valid colors are: clrFG, clrBG, clrDot, clrXOR.

Contents > Library Reference > User Interface > Draw object > bitmap

Draw.bitmap

`void bitmap(Bitmap bmp, int x, int y)`

Parameters:

| bmp | bitmap to draw
| x | x value
| y | y value

Draws the bitmap bmp at (x, y).

Contents > Library Reference > User Interface > Draw object > bitmapm

Draw.bitmapm

`void bitmapm(Bitmap bmp, int x, int y, int mode)`

Parameters:

| bmp | bitmap to draw
| x | x value
| y | y value
| mode | mode

Draws the bitmap bmp at (x, y), using the specified mode.

Note: Valid modes are: modePaint, modeErase, modeMask, modeInvert, modeOverlay, modePaintInverse, modeSwap.

Contents > Library Reference > User Interface > Draw object > text

Draw.text

`void text(int c, int x, int y, string text)`

Parameters:

| c | color
| x | x value
| y | y value
| text | text to draw

Draws the text text at (x, y).

Note: Valid colors are: clrText, clrInv.

Contents > Library Reference > User Interface > Draw object > textTrunc

Draw.textTrunc

`void textTrunc(int x, int y, int w, string text)`

Parameters:

| x | x value
| y | y value
| w | width
| text | text to draw

Draws the text text at (x, y), truncating and adding "..." it if necessary so that its width is no more than w.

Contents > Library Reference > User Interface > Draw object > draw

Draw.draw

`void draw(Draw d, int x, int y)`

Parameters:

| d | source
| x | x value
| y | y value

Draws the contents of d at (x, y).

Note: The source object must be an offscreen buffer

Contents > Library Reference > User Interface > Draw object > drawm

Draw.drawm

`void drawm(Draw d, int x, int y, int mode)`

Parameters:

| d | source
| x | x value
| y | y value
| mode | mode

Draws the contents of d at (x, y), using the specified mode.

Note: The source object must be an offscreen buffer. Valid modes are: modePaint, modeErase, modeMask, modeInvert, modeOverlay, modePaintInverse, modeSwap.

Contents > Library Reference > User Interface > UIApp object > getdepth

UIApp.getdepth

`int getdepth()`

Return value: color depth

Gets the current color depth in bits per pixel.

Contents > Library Reference > User Interface > UIApp object > setdepth

UIApp.setdepth

`bool setdepth(int bits)`

Parameters:

| bits | desired bits per pixel

Return value: true if successful

Sets the current color depth to bits bits per pixel. Returns true if successful. This will fail if the hardware does not support the the color depth.

Contents > Library Reference > User Interface > UIApp object > getScreenAttrib

UIApp.getScreenAttrib

`int getScreenAttrib(int attrib)`

Parameters:

| attrib | attribute to retrieve

Return value: attribute value

Retrieves various screen attributes. This method is only supported on OS 5 and higher - it will always return 0 on earlier OSes.

Note: Valid attribs are: screenWidth, screenHeight, screenDensity, screenResolutionX, screenResolutionY.

Contents > Library Reference > User Interface > UIApp object > getSysPref

UIApp.getSysPref

`int getSysPref(int prefID)`

Parameters:

| prefID | preference ID to retreive

Return value: system preference value

Retrieves various system preference values.

Note: Valid preferences are: sysPrefSysSoundVolume, sysPrefGameSoundVolume, sysPrefAlarmSoundVolume.

Contents > Library Reference > User Interface > UIApp object > hookhard

UIApp.hookhard

`void hookhard(bool hook)`

Parameters:

| hook | true to hook the hard keys

Enables the app to handle the hard keys (Memo, Address, etc.). If hook is false, the system will process the keys. If hook is true, pressing the hard keys will generate calls to the current form's onhkey handler.

Contents > Library Reference > User Interface > UIApp object > abort

UIApp.abort

`void abort()`

Forcefully exits the application. This method should only be called in the case of a fatal error since it aborts the application immediately without calling any handlers. If you would like to display an error message before exiting, using fatal instead.

Contents > Library Reference > User Interface > UIField object > insert

UIField.insert

`void insert(string text)`

Parameters:

| text | text to insert

Inserts text at the current insertion point.

Contents > Library Reference > User Interface > UIField object > select

UIField.select

`void select(int start, int end)`

Parameters:

| start | first character index
| end | last character index

Sets the selection to the characters inclusively between start and end.

Contents > Library Reference > User Interface > UIField object > cut

UIField.cut

`void cut()`

Cuts the current selection and places it on the clipboard.

Contents > Library Reference > User Interface > UIField object > copy

UIField.copy

`void copy()`

Copies the current selection to the clipboard.

Contents > Library Reference > User Interface > UIField object > paste

UIField.paste

`void paste()`

Paste the contents of the clipboard to the current insertion point.

Contents > Library Reference > User Interface > UIField object > undo

UIField.undo

`void undo()`

Undoes the last editing operation. Some operations cannot be undone.

Contents > Library Reference > User Interface > UIField object > del

UIField.del

`void del(int start, int end)`

Parameters:

| start | first character index
| end | last character index

Deletes the text inclusively between the start and end.

Contents > Library Reference > User Interface > UIField object > grabfocus

UIField.grabfocus

`void grabfocus()`

Sets the focus of the current form to this field.

Contents > Library Reference > User Interface > UIField object > relfocus

UIField.relfocus

`void relfocus()`

Releases the focus from this field.

Contents > Library Reference > User Interface > UIField object > scroll

UIField.scroll

`void scroll(int nLines)`

Parameters:

| nLines | number of lines to scroll down

Scrolls the field down nLines lines. If nLines is negative, the field is scrolled up. Call this method if the user drags a scroll bar associated with this field. See UIScroll for details.

Contents > Library Reference > User Interface > UIField object > phonelookup

UIField.phonelookup

`void phonelookup()`

Searches the address book and replaces the selected text or word at the cursor with the matching entry from the address book.

Contents > Library Reference > User Interface > UIForm object > load

UIForm.load

`void load()`

Loads the form and sets it to be displayed. If another form is currently open, it is first closed. Returns immediately.

Contents > Library Reference > User Interface > UIForm object > close

UIForm.close

`void close()`

Close the form and return to the previous form. This should only be called on a modal form, and is usually called in an onselect handler for a button.

Contents > Library Reference > User Interface > UIForm object > redraw

UIForm.redraw

`void redraw(int code)`

Parameters:

| code | redraw code

Queues an event to redraw the form, eventually calling the ondraw handler. The code can be retrieved in the ondraw handler through the Event object's code property.

Contents > Library Reference > User Interface > UIForm object > domodal

UIForm.domodal

`void domodal()`

Loads the modal form and sets it to be displayed. Returns immediately. To execute a modal form synchronously (to wait until the user dismisses the form before continuing), use the events() function.

Example:

Displays a dialog synchronously. Calling executeDialog() will open myDialog, process all its events, and return when the dialog has been closed.

    bool myDialogClosed;
    handler myDialog.onclose() {
      myDialogClosed = true;
    }
    void executeDialog() {
      myDialogClosed = false;
      myDialog.domodal();
      while (!myDialogClosed) {
        events(true);
      }
    }

Contents > Library Reference > User Interface > UIForm object > dodialog

UIForm.dodialog

`int dodialog()`

Return value: The id of the button pressed

Loads the modal form, displays it as a dialog, and returns the id of the button the user pressed. The form and its controls will not receive events.

Example:

Open the dialog myDialog which has two buttons (button1 and button2), and display which button was pressed.

    int buttonID;
    buttonID = myDialog.dodialog();
    if (buttonID == button1.id) {
      alert("Button 1 pressed");
    } else if (buttonID == button2.id) {
      alert("Button 2 pressed");
    }

Contents > Library Reference > User Interface > UIForm object > timer

UIForm.timer

`void timer(int nticks)`

Parameters:

| nticks | number of ticks to wait

Sets a timer to be fired after nticks clock ticks (approx. 1/100 sec). When the timer is fired, the form's ontimer handler is called. The form will only receive the timer event if it is the active window.

Contents > Library Reference > User Interface > UIForm object > select

UIForm.select

`void select(int groupid, int ctrlid)`

Parameters:

| groupid | control group id
| ctrlid | control id

Selects a pushbutton in the group specified by groupid. Use the id member of the pushbutton as ctrlid.

Contents > Library Reference > User Interface > UIForm object > help

UIForm.help

`void help(UIString str)`

Parameters:

| str | string to display

Display a help form with the specified string str as the help text (same form displayed when clicking the (i) icon on a modal form). The string str is the name of one of the strings in your project.

Contents > Library Reference > User Interface > UIForm object > activefield

UIForm.activefield

`UIField* activefield()`

Return value: Pointer to the active field, or null

Retrieve the pointer of the currently active field, or null if no field is active.

Contents > Library Reference > User Interface > UIForm object > keyboard

UIForm.keyboard

`void keyboard()`

Displays the system keyboard dialog if there is an active field on the form.

Contents > Library Reference > User Interface > UIList object > setitems

UIList.setitems

`bool setitems(int num, string* ptext)`

Parameters:

| num | number of items
| ptext | array of strings

Return value: true if successful

Sets the items in the list. ptext is an array of num strings in the order in which they will be displayed in the list.

Contents > Library Reference > User Interface > UIList object > setitemslist

UIList.setitemslist

`bool setitemslist(StringList sl)`

Parameters:

| sl | string list of items

Return value: true if successful

Sets the items in the list to the contents of sl.

Contents > Library Reference > User Interface > UIList object > gettext

UIList.gettext

`string gettext(int index)`

Parameters:

| index | index of item

Return value: text of desired item

Gets the text assosciate with the item at location index.

Contents > Library Reference > User Interface > UIList object > makevisible

UIList.makevisible

`void makevisible(int index)`

Parameters:

| index | index of item

Makes the item at location index visible.

Contents > Library Reference > User Interface > UIList object > scroll

UIList.scroll

`bool scroll(int lines)`

Parameters:

| lines | lines to scroll

Return value: true if the list was actually scrolled

Scrolls the list down lines lines. If lines is negative, the list is scrolled up. Returns true if the list is actually scrolled.

Contents > Library Reference > User Interface > UIList object > popup

UIList.popup

`int popup()`

Return value: the selected item, or -1 if canceled

Displays the list as a popup list and returns the item selected or -1 if none selected.

Contents > Library Reference > User Interface > UIList object > redraw

UIList.redraw

`void redraw()`

Redraws the list. After the list items are set, the list should be redrawn. Just like other drawing functions, this may not be called in a forms onopen handler.

Contents > Library Reference > User Interface > UIList object > setdrawfunc

UIList.setdrawfunc

`void setdrawfunc(UIListDrawFunc func)`

Parameters:

| func | custom drawing function

Sets the custom drawing function for the list. Specifying null causes the OS to draw the list itself.

Note: UIListDrawFunc is defined as funcptr UIListDrawFunc void(int item, int x, int y, int w, int h, string text), where item is the 0-based item index currently being drawn, x, y are the window-relative coordinates of the upper left of the current item, and text is the text of the item to draw. The OS sets the foreground and background color before calling the function, according to whether the item is selected or not.

Example:

Create a color selection list.

    void drawColorList(int item, int x, int y, int w, int h, string text);
    string colorNames[3] = { "red", "green", "blue" };
    int colorRed[3] = { 255, 0, 0 };
    int colorGreen[3] = { 0, 255, 0 };
    int colorBlue[3] = { 0, 0, 255 };

    Draw draw;
    handler mainform.onopen() {
      draw.attachForm(this);
      listColor.setitems(3, colorNames);
      listColor.setdrawfunc(drawColorList);
    }

    void drawColorList(int item, int x, int y, int w, int h, string text) {
      draw.begin();
      draw.textTrunc(x + 12, y, w - 12, text);
      draw.fgRGB(colorRed[item], colorGreen[item], colorBlue[item]);
      draw.rect(clrFG, x, y+1, x+9, y+10, 0);
      draw.end();
    }

Contents > Library Reference > User Interface > UIScroll object > update

UIScroll.update

`void update(UIField field)`

Parameters:

| field | The field associated with this scroll bar

Updates the position, min, max, and page values of this scroll bar to match the associated field. Call this method when the height of the field has changed, or when the user drags the scroll bar.

Contents > Library Reference > User Interface > alert

alert

`void alert(string text)`

Parameters:

| text | text to display

Displays an alert dialog containing the text text.

Contents > Library Reference > User Interface > alertc

alertc

`int alertc(string title, string message, string buttons, int type)`

Parameters:

| title | title
| message | message to display
| buttons | button text
| type | alert type

Return value: the 0-based index of the button pressed

Displays an alert dialog with the specified title, text, and buttons. buttons is the text of a button, or a string containing the names of several buttons separated by colons. "OK:Cancel".

Note: Valid types are: alertInfo, alertQuestion, alertWarning, alertError.

Contents > Library Reference > User Interface > confirm

confirm

`bool confirm(string text)`

Parameters:

| text | text to display

Return value: true if the user tapped "yes"

Displays a confirmation dialog containing the text text and "yes" and "no" buttons. Returns true if the user tapped "yes", false otherwise.

Note: This form's default button is "no", so if the user switches applications while the dialog is open, the OS will dismiss it by selecting the "no" option. Therefore, you should ensure that the "no" option does not cause data loss.

Contents > Library Reference > User Interface > prompt

prompt

`string prompt(string text)`

Parameters:

| text | text to display

Return value: response entered by user

Displays an input prompt with the specified text, returning the string entered by the user. If the user presses the Cancel button, an empty string is returned. Works only on OS 3.5 and higher.

Contents > Library Reference > User Interface > promptc

promptc

`int promptc(string title, string message, string buttons, int type, string* pentry)`

Parameters:

| title | title
| message | message to display
| buttons | button text
| type | alert type
| pentry | string address where the entry is stored

Return value: the 0-based index of the button pressed

Displays an input prompt with the specified title, message, and buttons. buttons is the text of a button, or a string containing the names of several buttons separated by colons. "OK:Cancel".

Note: Valid types are: alertInfo, alertQuestion, alertWarning, alertError.

Contents > Library Reference > User Interface > promptcd

promptcd

`int promptcd(string title, string message, string buttons, int type, string text, string* pentry)`

Parameters:

| title | title
| message | message to display
| buttons | button text
| type | alert type
| text | initial field text
| pentry | string address where the entry is stored

Return value: the 0-based index of the button pressed

Displays an input prompt with the specified title, message, and buttons. text is used to initialize the prompt's field. buttons is the text of a button, or a string containing the names of several buttons separated by colons. "OK:Cancel".

Note: Valid types are: alertInfo, alertQuestion, alertWarning, alertError.

Contents > Library Reference > User Interface > keystate

keystate

`int keystate()`

Return value: flags of keys currently pressed

Retrieves the current set of pressed keys. Can be zero of more of the following flags: keyPageUp, keyPageDown, keyHard1-keyHard4, keyContrast. The return value may also include other device-specific flags.

Contents > Library Reference > User Interface > penstate

penstate

`bool penstate()`

Return value: true if the pen is down

Retrieves the current state of the pen: true for down, false for up.

Contents > Library Reference > User Interface > Color Tables

Color Tables

8-bit Color Table:

0 |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |
16 |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |
32 |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |
48 |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |
64 |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |
80 |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |
96 |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |
112 |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |
128 |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |
144 |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |
160 |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |
176 |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |
192 |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |
208 |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |
224 |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |
240 |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |

4-bit Color Table:

0 |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |

2-bit Color Table:

0 |  |  |  |

1-bit Color Table:

0 |  |