## GUI Functions

Legend:
x is X (left) coordinate, y is Y (top) coordinate, w is Width and h is Height, all of x, y, w and h are v|n.
#v|n is the Object ID and is in the range [1...999]

CHECKBOX(#v|n)

Returns 0 if the given checkbox is unchecked and 1 if it is checked

COLORSELECT(v|n)

Opens the Palm OS standard color selector window, and returns the selected color

Notes:

- v|n is the initial proposed color
- PalmOS 3.5 onwards

DOEVENTS

Returns on which object an event occurred (if one occurred)

Return Value | Comment | KEYEVENTS Required
-24, -23, -22, -21 | App Key #4, #3, #2, #1 | ON
-13 | HotSync Button on Cradle | ON | PARTIAL
-12 | Page Down Button | ON | PARTIAL
-11 | Page Up Button | ON | PARTIAL
-10 | Power On/Off Button | ON | PARTIAL
-1 | ExitAppRequest
0 | No event
#v|n in [1..999] | Object that was clicked (Button, CheckBox, ListChoice, PopupChoice, PushButton, ScrollBar or TextSelector)
1000 | Pen event (get related information from the PENDOWN, PENX and PENY functions)
1001 | Menu event (get related information from the MENUITEM function)
1002 | ABOUTBOX event (for information back to your program)

Notes:

- You will usually include a DOEVENTS in a DO/LOOP, REPEAT/UNTIL or WHILE/WEND loop and track for the exit of program condition. Example:

  REPEAT
  E=DOEVENTS
  [Statement]
  UNTIL E<0

- Unless you want to monitor hard keys (which are usually devoted to launching programs, you just have to check that DOEVENTS returns a negative value to exit your program if the KEYEVENTS directive is set.

FONTSELECT(v|n)

Opens the Palm OS standard font selector window, and returns the selected font

Notes:

- The v|n parameter is the default highlighted font in the dialog box and it has to be one of these three values:

  0 stdFont
  1 boldFont
  7 largeBoldFont

FONTWIDTH(c|t, v|n)

Returns the width in pixels of the c|t text for a given font v|n

Notes:

- Please refer to the SETFONT statement as for the possible values for v|n

GETFOCUS

Returns the object ID that has the focus

MENUITEM

Returns the last menu item ID which was selected during the last menu event, 0 if the menu was just opened or -1 if the menu was just closed

Notes:

- The returned ID is the one of the menu item as defined in the MBAR resource
- You should capture the menu event with a DOEVENTS or a WAITEVENT and get the selected menu item just afterwards

MESSAGEBOX(c|t1 [+ c|t2 [+ c|t3]], v|n)

Pops up a message window, with a choice of return buttons given by v|n, and returns the button pressed (1=first , 2=second, ...)

Notes:

- You may pass up to 3 text strings to build a MessageBox with up to 186 characters long (including line feeds)
- v|n is the type of MessageBox with the following return buttons:

  0= Done
  1= OK
  2= OK|Cancel
  3= Yes|No
  4= 1|2
  5= 1|2|3
  6= 1|2|3|4
  7= 1|2|3|4|5
  8= 1|2|3|4|5|6
  9= 1|2|3|4|5|6|7

NOTICEBOX(v|n)

Pops up a message window, with a choice of return buttons given by v|n, and returns the button pressed (1=first , 2=second, ...) or 0 if the message resource does not exist.

The message has to be defined at design time, which is the main difference with MESSAGEBOX.

Notes:

- v|n is a custom message ID as provided in a resource file, the resource being of type Talt (Alert resource, please refer to the RESOURCEFILE compiling directive)
- v|n is to be in the range [1...999]
- the differences between MESSAGEBOX and NOTICEBOX are that MESSAGEBOX's text is created on the fly but it comes with predefined button sets, whilst NOTICEBOX takes a predefined message from a resource file but allowing more customized button labels. If you do not know or want to manage a resource file, then consider using MESSAGEBOX

PENDOWN

Returns 1 when pen is down and 0 when pen is up

Notes:

- PENDOWN is trapped during a DOEVENTS or a WAITEVENT call (return value of pen event is 1000)

PENX

Returns X position of where the pen was last ticked on the screen

PENY

Returns Y position of where the pen was last ticked on the screen

Notes:

- PENX/PENY is trapped during a DOEVENTS or a WAITEVENT call (return value of pen event is 1000)

PUSHBUTTON(#v|n)

Returns the status of a push button: 0=not pushed or 1=pushed

SCROLLBAR(#v|n)

Returns the position of the scroll car of a scrollbar, in the [1...100] range

SELECTEDCHOICE

Returns the selected item (0=non selected, 1=first , 2=second, ...) of the last LISTCHOICE or POPUPCHOICE event

Notes:

- You should capture the ListChoice or the PopupChoice event with a DOEVENTS or a WAITEVENT and get the selected item just afterwards

WAITEVENT

Returns the same values as DOEVENTS (except for the 0=no event value)

Notes:

- be aware that control is not returned to your program until one event occurs, use DOEVENTS if you need to get control back between events. In other words,

  A=WAITEVENT

  is equivalent to

  REPEAT : A=DOEVENTS : UNTIL A<>0

DATESELECT$(c|t)

Opens the Palm OS standard date selector window, and returns the selected date

Notes:

- c|t is the default date sent to the Date Selector, format is "DD/MM/YYYY". Pass an empty text string if you wish to send the current date.
- date format returned is "DD/MM/YYYY" or empty if the user cancelled the input

FIELD$(#v|n)

Retrieves the value stored in a NumField or a TextField

Notes:

- to convert the returned value in a NumField to a number, use the VAL function
- see the FIELD$$ function in the MegaString chapter

TIMESELECT$(c|t)

Opens the Palm OS standard time selector window, and returns the selected time

Notes:

- c|t is the default time sent to the Time Selector, format is "HH:mm". Pass an empty text string if you wish to send the current time.
- time format returned is "HH:mm" or empty if the user cancelled the input
- be careful with this time format as it differs from the "HH:mm:ss" format used in the TIME$ function
- PalmOS 3.1 onwards