PalmWidgets.borg

PalmWidgets.borg


{
`******************************************************************************
`*
`* -- PalmWidgets --
`*
`*****************************************************************************/

` The meaning of some often recurring arguments:
` (unsigned short) id       : The unique id of an UI element, must be > 10.
` (char*) text              : The label of a ui element
` (unsigned short) minwidth : minwidth in pixels(= width for fixed size els)
` (unsigned short) minheight: minheight in pixels(= height for fixed size els)
`

`******************************************************************************
`*
`* PART I: Windows.
`*
`*   Only one window is visible and active at a time.
`*   Windows have a standard size of 160 * 160 pixels
`*   Multiple windows per app are supported.
`*   All these functions are synchroneous.
`*
`*****************************************************************************/

` Creates a new window, which is automatically selected for layout
` (see widgetplace, nr 240) returns 0 if fails
` [returns an integer]
newWindow(id,title)::
    external(210,id,title);

` Remove the window from screen and from memory. Everything
` associated with the window (menu and widgets) is freed aswell
` returns nothing
freeWindow(id)::
    external(211,id);

` Put the window in the foreground
` returns nothing
showWindow(id)::
    external(212,id);

` Select this window for adding widgets
` returns nothing
layoutWindow(id)::
    external(213,id);

` Set the title of the window
` rteturns nothing
windowSetTitle(id, title)::
    external(214,id,title);

` Returns a copy of the title, you must free it yourself
` returns a text
windowGetTitle(id)::
    external(215,id);


`******************************************************************************
`*
`* PART II: Creation and accessing of widgets.
`*
`*   Widgets that have been created but never laid out will have to be
`*   removed from memory when cleaning up. For this use widgetRemove (nr 241)
`*
`*   Construction of controls: UI elements that provide feedback to the
`*   app. We can consider these functions to be asynchroneous: they
`*   return void, and callback functions will be called when something
`*   interesting happens
`*
`*****************************************************************************/

` Make a new button, with label text
` returns nothing
` id = integer
` text = string
` minwidth = integer
` minheight = integer
` selectfunction = lambda with one parameter (the widgetid)
newButton(id,text,minwidth,minheight,select)::
    external(221,id,text,minwidth,minheight,select);

` Make a repeating button, with label text
` returns nothing
` id = integer
` text = string
` minwidth = integer
` minheight = integer
` repeatfunction = name of a function with one parameter (the widgetid)
` selectfunction = name of a function with one parameter (the widgetid)
newRepeatButton(id,text,minwidth,minheight,repeat,select)::
    external(222,id,text,minwidth,minheight,repeat,select);

` Make a pushbutton: it can be selected and deselected
` return nothing
newPushButton(id,text,minwidth,minheight,selectfunction)::
    external(223,id,text,minwidth,minheight,selectfunction);

` Make a checkbox: a pushbutton with a V in front when selected
` returns nothing
newCheckBox(id,text,minwidth,minheight,selectfunction)::
    external(224,id,text,minwidth,minheight,selectfunction);


`******************************************************************************
`*
`* Accessors & mutators for controls. These functions are
`* synchroneous: accessors return the information requested, mutators
`* do not provide a relevant return value.
`*
`*****************************************************************************/

` Set the value of the pushbutton/checkbox, 0 = off, 1 = on.
` returns nothing
` id = integer
` value = integer
pushButtonSetValue(id,value)::
    external(225,id,value);

checkBoxSetValue(id,value)::
    external(226,id,value);

` Return the value of the pushbutton/checkbox, 0 = off, 1 on.
` returns string
` id = integer
pushButtonGetValue(id)::
    external(227,id);

checkBoxGetValue(id)::
    external(228,id);


`******************************************************************************
`*
`* Field is a UI element that displays text.
`*
`* All of the field functions are synchroneous.
`*
`*****************************************************************************/

` Semantics of the arguments (0 = false, 1 = true)
` maxchars:     The field will never contain more characters than this.
` editable:     May the field be edited?
` underline:    Is the text underlined?
` singleLine:   Is the field only 1 line?
` autoresize:   Must extra lines be drawn if text becomes to long for current
`               number of lines?
` hasScrollBar: Is a vertical scrollbar required?
` numeric:      Is the field only for numbers?
` returns nothing
` id = integer
` text = string
` minwidth = integer
` minheight = integer
` maxchars = integer
` editable = integer
` underline = integer
` singleLine = integer
` autoresize = integer
` hasScrollBar = integer
` numeric = integer;
newField(id,text,minwidth,minheight,maxchars,editable,underline,singleline,autoresize,hasScrollBar,numeric)::
    external(229,id,text,minwidth,minheight,maxchars,editable,underline,singleline,autoresize,hasScrollBar,numeric);

` returns a copy of the text
` id = integer
fieldGetText(id)::
    external(230,id);

` returns nothing
` id = integer
` text = string
fieldSetText(id,text)::
    external(231,id,text);


`******************************************************************************
`*
`* PART III: Layout of widgets.
`*
`*   Widgets are placed on absolute coordinates, no resizing is allowed (yet)
`*   All these functions are synchroneous.
`*
`*****************************************************************************/

` Place a widget on the window selected for layout,
` coords are in pixels, returns 0 for fail (usually out of memory)
` returns integer
` id, x, y = integer
widgetPlace(id,x,y)::
    external(240,id,x,y);

` Removes widget from window AND from memory
` returns nothing
` id = integer
widgetRemove(id)::
    external(241,id);

` Hide a widget, it does not appear in the window anymore
` returns nothing
` id = integer
widgetHide(id)::
    external(242,id);

` Show a hidden widget
` returns nothing
` id = integer
widgetShow(id)::
    external(243,id);


`******************************************************************************
`*
`* PART IV: Menus.
`*
`*   Only one menu. Setup before bringing window to front.
`*   All these functions are synchroneous.
`*
`*****************************************************************************/

` Add a menu item after id previd (first id = 0)
` id is integer
` previd is integer
` itemtext is char
` shortcutletter is character
menuAddItem(id,previd,itemtext,shortcutletter,select)::
    external(250,id,previd,itemtext,shortcutletter,select);

` Hide or show a menu item
` returns nothing
` id is an integer
menuHideItem(id)::
    external(251,id);

menuShowItem(id)::
    external(252,id);

`******************************************************************************
`*
`* PART V: Dialog boxes.
`*
`* 4 Types of dialog boxes: Notification (0), Question (1), Warning
`* (2), Error (3).
`* Dialogs are modal.
`* All functions are synchronous.
`*
`*****************************************************************************/

` Show modal dialog box, return value is button pushed (0=ok, 1=cancel)
` retunrs an integer
` type is integer
` test is string
showDialog(type,text)::
    external(260,type,text);

` Show modal dialog box, lets user enter text of max length maxlen chars
` which is put in response, return value is button pushed (0=ok, 1=cancel)
` returns an integer
` type is integer
` text is string
` maxlen is integer
` response is string
showResponseDialog(type,text,maxlen,response)::
    external(261,type,text,maxlen,response);


`******************************************************************************
`*
`* PART VI: Ultimate Destruction (of the widgets)
`*
`*****************************************************************************/

` This function cleanly closes all windows (and dialog boxes)
` of the agent and frees all UI resources held by the agent
uiCleanUp()::
    external(270);

display("PalmWidgets loaded.",eoln)
}