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)
}