RIM Inter@active UI Developer's Guide

Developers Guide

5,0 ,Q

5,0 ,QW

WHU#

HU#F

FWLYH 3DJ

WLYH 3DJH

HU

U

User Interface Engine API

Version 1.0

RIM Inter@ctive Pager 950 User Interface Engine API,Version 1.0Last revised 11/19/98

Part Number: MAT-02110-001 Rev. 002

1997-98, RESEARCH IN MOTION LIMITED

Research In Motion, RIM, the RIM logo, and Inter@ctiveare trademarks of Research In Motion Limited. Research InMotion and RIM are registered, U.S. Patent andTrademark Office.

Complies with software O/S version 030a and applicationsversion BSWD-050.

Visual C++ and Windows are trademarks of MicrosoftCorporation. Intel is a registered trademark of IntelCorporation. Mobitex is a registered trademark of SwedishTelecom. All other brands, product names and companynames mentioned herein are registered trademarks ortrademarks of their respective holders.

Warning: This document is for the use of licensed usersonly. Any unauthorized copying, distribution or disclosureof information is a violation of copyright laws.

While every effort has been made to ensure technicalaccuracy, information in this document is subject to changewithout notice and does not represent a commitment onthe part of Research In Motion Limited.

Research In Motion Limited295 Phillip StreetWaterloo, OntarioCanada N2L 3W8Tel. (519) 888-7465Fax (519) 888-6906Web site: www.rim.netE-mail: [email protected]

Printed In Canada KM1198/uiengine

User Interface EngineAPI addendumAt the time of publication, this document is still inprogress. The following API functions will beavailable in future versions of our UI InterfaceEngine API.

New Classes:

Class Associatedheader file

Table member functions table.h

BusyStatus memberfunctions

busystatus.h

Clickdialog memberfunctions

clickdialog.h

Okdialog member functions okdialog.h

ii User Interface Engine API addendum

Developers Guide RIM Inter@ctive Pager 950

New member functions in current objects:

Class Functions

Choicex GetFieldTypex IsDirtyx MarkAsDirtyx MarkAsClean

Editx GetFieldTypex IsDirtyx MarkAsDirtyx MarkAsCleanx GetSelectionx ReplaceSelectionx SetSelectionx SetBookmarkx GetBookmark

Listx GetFieldTypex IsDirtyx MarkAsDirtyx MarkAsClean

Tablex GetFieldTypex IsDirtyx MarkAsDirtyx MarkAsClean

ContentsUser Interface Engine API addendum..................i1. Introduction ........................................................ 1

About this guide......................................................1

2. UI Engine overview ........................................... 3Screens .....................................................................3Menus ......................................................................4Fields........................................................................4Status boxes .............................................................6Dialog boxes ............................................................6

3. Application software design principles .......... 9Design guidelines....................................................9Style guide .............................................................13

4. API functions.................................................... 17UIEngine class .......................................................19Menu class .............................................................32Status class.............................................................47Screen class ............................................................55Title class................................................................70Edit class ................................................................74DecimalEdit class ..................................................96Separator class.....................................................100List class...............................................................102StringList class.....................................................115Choice class..........................................................118YesNoChoice class ..............................................128TopBottomChoice class.......................................132BeepChoice class .................................................136Dialog class..........................................................141YesNoDialog class...............................................149

5. AutoText API .................................................. 159Index of API functions ...................................... 165Index .................................................................... 167

11.Introduction

The User Interface Engine (UI Engine) API is a setof classes that provides a common look and feel forall applications developed for the RIM Inter@ctivePager 950. Features include menu and screenhandling, user fields and dialog boxes. Thisfunctionality works to complement and enhancethe base functionality of the Operating System(OS) API.

In using this guide, it is assumed that you arefamiliar with the RIM Inter@ctive Pager 950 OS API.

About this guideThe RIM Inter@ctive Pager 950 SDK includesDevelopers Guides to assist you in creating yourapplications. This guide includes generalinformation on the User Interface Engine API, aswell as a complete listing of all its function calls.Other Developers Guides are provided for theOperating System API and the Transport, AddressBook, Options, Database, and Messaging DLLs.

Throughout this guide, the RIM Inter@ctive Pager950 may be referred to as the pager. Thesimulator will be referred to as the Pager 950simulator.

2 Introduction -- About this guide


You may encounter tips and notes in this guide.The tips are provided to offer you an alternativemethod of performing the action. Notes containadditional information that will help you completethe task.

The names of various program groups, icons,folders, sections, windows, parameters etc. willappear in bold text. An example would be theResearch In Motion program group.

Menu options, menu names, fields, tabs,checkboxes etc. will appear in Arial font.References to buttons will also appear in thisfashion, with the hot key underlined if applicable.An example would be the Next> button.

Returns, events, constants, structures etc. willappear in bold text, small capitals. An examplewould be the COMM_RX_ERROR error code.

22.UI Engine overview

The UI Engine is composed of basic elementsdesigned to accept and display user information.All RIM Inter@ctive Pager 950 applications are builtaround these elements.

ScreensScreens are rectangular containers for a list offields. Screens present the fields in a verticalordering, and the UI Engine is responsible fordisplaying the screen based on the user input andthe field selected by the user. A screen can becomposed of as many fields as possible. As shownbelow, the LCD display shows only a portion ofthe actual screen. The user can navigate betweenfields, typically with the roller wheel. A screen canalso have a title on the first line of the display, oneline in length.

Note: Some fields can increase in size when theuser adds information, and decrease in size whenthe user deletes information from the field.

Screen

4 UI Engine overview -- Menus


MenusMenus are rectangular containers that arecomposed of a set of text or menu items. Menusappear on top of screens and cover approximatelythree-quarters of the screens width. Menusshould be context sensitive to the data on theassociated screen.

Menu

FieldsFields are screen objects that accept user data.Fields are peers to each other; they are alwayscontained within a screen. Typically rectangular instructure, fields take up the width of the display.

Edit boxesEdit boxes are fields typically used to input textdata. An edit box has an optional label (as shownbelow) and is a field that can grow in size. There isa cursor associated with an edit field and wordwrapping is performed automatically.

Edit boxes

Menu item 1Menu item 2Menu item 3etc

One edit box containing an optionallabel, Fax:, andexample input text,123-4567.

UI Engine overview Fields 5


Note: One property worth noting is READ_ONLY,which allows the application to effectively have anedit field that cannot be changed by user input.

ListsLists are fields that present related yet separateitems on each line. When a line in the field isselected, the cursor takes up the entire line.

List

Choice boxesChoice boxes are actually one line text boxes thatalways have a label. Choice boxes right justify thedata, which is either a value in a numeric range ora string which is part of an array of strings.

Choice boxes

SeparatorsSeparators are one-line fields that either have astring or bitmap on them. Separators separate twoother kinds of fields for readability purposes andcan never be selected or highlighted. By default,

List

One choice box Choice boxesalways contain alabel, in thisexample the labelis In Holster:.

6 UI Engine overview -- Status boxes


the string associated with a separator is a line thatis the length of the display.

Separator

Status boxesStatus boxes are rectangular containers thatcontain application text or text and bitmaps. Astatus box appears in the middle of the LCDdisplay and is system modal. It does not receiveuser input yet the foreground application will stillreceive input while the status box is active. Thestatus box can remain active for a period of timethat is definable but since it visually disrupts thescreen display, it is typically used only wheninstant notification is required.

Status box

Dialog boxesDialog boxes are rectangular containers that areapplication modal and appear in the middle of theLCD display. A dialog box has three components:

x An optional Bitmap,

Separator

Status boxcontainingapplication textand a bitmap

UI Engine overview Dialog boxes 7


x A Text field, and

x Either a List field, Edit field, or ChoiceBoxfield.

When the dialog box appears, the list/edit/choicebox field is highlighted.

Dialog box

Note: The size of the field can be larger than theLCD display.

33.Application softwaredesign principlesDesign guidelinesIn order to provide a consistent interface betweenRIM Inter@ctive Pager 950 applications, thefollowing guidelines should be considered whenusing UI Engine components.

User controlThe user should always be in control of theapplication; principles to keep in mind that help toachieve user control include the following:

ResponsivenessThe user must be able to navigate and performactions quickly. If there are long delays betweenthe time the user performs an action andprocessing of the action, the user will not feel incontrol.

CustomizationBecause users preferences differ, users shouldhave the ability to customize the interface (e.g.,what information to display in the message listand the order in which information is displayed).

10 Application software design principles -- Design guidelines


However, the software should provide defaultsthat are helpful for the majority of users.

Perform tasks at handThe best interfaces are the ones that make theusers tasks easier, not draw attention to theinterface. The best interfaces are the ones that arehardly noticed.

IntuitivenessAn interface should be as intuitive andstraightforward as possible. One of the best waysto achieve this is using the object-action paradigm.Users select objects and perform actions on them(e.g., user selects a mail message and reads it).

ConsistencyConsistency should exist throughout each task inand between applications. The onus is on you, as adeveloper, to have an awareness of otherapplications being written for the pager so thatyour applications interface is a consistent part ofthe whole. Consistency also allows for thereusability of common interface elements.

ClarityThe interface should be clear, not only from avisual point of view, but also from a conceptualpoint of view. Clarity is an especially importantdesign aspect because the RIM Inter@ctive Pager950 has a small interface (132x65 pixels). If theinterface is jumpy (i.e., causes distractions bybreaking visual flow), users may have troublemaintaining control. If using icons, keep in mind

Application software design principles Design guidelines 11


that they will be small and if they are cluttered, itwill not be clear to the user how the icon is relatedto the interface at hand. RIM Inter@ctive Pager950 applications are not Windows applications!Do not fill the interface with a lot of controls. Toomany controls will only emphasize the small sizeof the display.

Dialog and status boxes should contain brief andconcise text. This text should not merely indicateto users what they have done incorrectly; theyshould also indicate what action is necessary tocorrect the problem.

AestheticsThe RIM Inter@ctive Pager 950 device is a two-waywireless device it is not a desktop solution. Assuch, RIM Inter@ctive Pager 950 applications arenot to be compared with Windows applications.Three-dimensional graphics or flashing cursors onthe pager display are inefficient and distracting. Asimple design offers the best way to ensure thatRIM Inter@ctive Pager 950 applications areaesthetically pleasing.

Keep the changing information on the display toone item, and keep the users focus on one place ata time. When presenting a lot of information tousers, ensure that the most important informationis displayed first (e.g., when presenting eachaddress book entry, display the name fields first,followed by the E-mail address, phone, fax andpager numbers fields, and leave the Notes field tothe end).

12 Application software design principles -- Design guidelines


Another way the UI Engine keeps the RIMInter@ctive Pager 950 aesthetically pleasing is bytaking advantage of the vertical nature of the rollerwheel. Menu items and lists are all presented in avertical fashion. Double-clicking (as opposed to 2quick single clicks) is not desirable based on thesize of the device and the size of the roller wheelitself.

FeedbackFeedback is the applications response to usersinput (e.g., the appearance of a menu when usersclick the roller wheel or character display whenusers add information to a field). Immediatefeedback is essential and the application shouldrespond quickly to users commands. For instance,one of the learning curves for new users of the RIMInter@ctive Pager 950 will be typing on thekeyboard. Since keyboard typing may take a whileto get used to, new users could become frustratedquickly if feedback from typing or invokingscreens/dialogs/menu is slow.

ForgivenessThe interface must allow users to change theirmind and undo commands; essentially, it must beforgiving Two classic instances of keeping theinterface forgiving follow.

First, users cannot be allowed to do anythingdestructive without being warned (e.g., an actionsuch as deleting a message or address book entrymust be confirmed before the action occurs).

Application software design principles Style guide 13


Second, common menu items are not close toothers that undo the task at hand (e.g., the Cancelmenu item is not close to the Hide menu menuitem)

Style guideCertain UI Engine components are designed tohave a specific use. This section outlines specificcomponents and typical applications.

Screen titleEvery screen will have a title on the first line of thedisplay. The title line should be a repository notonly to inform the users where they are, but also todisplay brief information to help the users with theparticular task at hand. For example, when usersperform a search in the address book application,the screens first line will display the screen titleplus the text typed to invoke a search.

Address book screen

When users subsequently type A, the screen willdisplay all of the records that start with HA andthe title will display Find: HA.

Screen title

14 Application software design principles -- Style guide


Address book screen

MenusInvoking a menuFor consistency, a click of the roller wheel willalways invoke a menu. Once a menu item ishighlighted (by scrolling the roller wheel), the itemcan be selected (by clicking the roller wheel).Subsequently, a screen will be displayed.Depending on the functionality of the itemselected, this screen may be the same as theprevious one.

Menu items The first item in the menu is Hide Menu. The UIEngine automatically places this item at the top ofthe menu. When users select Hide Menu, the menuwill disappear and the previous screen remains onthe display.

Another item in the menu list is Cancel. ChoosingCancel allows users to escape from the currenttask and return to a familiar screen. For example,suppose users select the Compose menu item fromthe menu associated with the 0HVVDJH /LVW screen.They then select a recipient to send the message to,and start composing a message body. If users thendecide not to send the message, they can invoke

Application software design principles Style guide 15


the menu and select Cancel. This will bring themback to the message list screen.

Note: Cancel may not be applicable in all cases.For example, Cancel is not applicable in the firstscreen of an application.

Menu formatThe default item will be highlighted when themenu first appears and will be in the middle of thelist of items. The menu items that are selectedmore often by users will immediately surround thedefault item while the items that are less oftenselected will be further away from the defaultitem.

For example, if the 0HVVDJH /LVW screen is on theLCD display and users click the roller wheel, themenu will look like this:

Message List menu

Note: The default menu item should never bedestructive. For example, the user should not beable to delete an entry or a message by clicking onthe default menu item.

ControlsControls are tools such as icons and buttons thatthe user selects to issue commands. Keep thenumber of controls on the display at any one time

Defaultmenu item

16 Application software design principles -- Style guide


as small as possible. Too many controls on thedisplay will only emphasize the small size of thedisplay.

Keyboard and roller wheelAs much as possible, try to keep the user fromhaving to flip back and forth between thekeyboard and the roller wheel. For example, if theuser is entering data using the keyboard, he shouldnot have to use the roller wheel for some form ofinput and then go back to using the keyboard.

44.API functions

The following are public member functions withwhich you need to be familiar. These memberfunctions are identified in the associated headerfiles by the heading public: // used by client.

API functions Start onpage

Associatedheader files

UIEngine memberfunctions

19 uiengine.h

Menu memberfunctions

32 menu.h

Status memberfunctions

47 status.h

Screen memberfunctions

55 screen.h

Title memberfunctions

70 label.h

Edit memberfunctions

74 edit.h

DecimalEditmember functions

96 edit.h

Separator memberfunctions

100 separator.h

List memberfunctions

102 list.h

18 API functions


API functions Start onpage

Associatedheader files

StringList memberfunctions

115 list.h

Choice memberfunctions

118 choice.h

YesNoChoicemember functions

128 choice.h

TopBottomChoicemember functions

132 choice.h

BeepChoice memberfunctions

136 choice.h

Dialog memberfunctions

141 dialog.h

YesNoDialogmember functions

149 yesnodialog.h

API functions UIEngine class 19


UIEngine classThe UIEngine class is a required component forusing any functionality in this API. This class isused to handle user input from the keyboard androller wheel and to manage the display context.

The following is a list of functions in the UIEnginepublic member class.

_ClearDialog ..............................20

_ClearMenu ...............................21

_ClearScreen ..............................22

_GetUIVersion ...........................23

_HandleInput.............................24

_Initialize....................................26

_ProcessDialog...........................27

_ProcessMenu............................28

_ProcessScreen...........................29

_RestoreDisplayContext............30

_UIEngine ..................................31

20 API functions -- UIEngine class


UIEngine::ClearDialogvoid ClearDialog ()

Returns:There are no returns for this function.

Remarks:This function removes the application instantiateddialog on the display. A ProcessDialog must becalled in order for the UI Engine to be aware of thedialog again.



UIEngine::ClearMenuvoid ClearMenu ()


Remarks:This function removes the application instantiatedmenu on the display. A ProcessMenu must beinvoked in order for the UI Engine to be aware ofthe menu again. While the ClearMenu functionremoves the menu from the display context,foreground applications will need to callProcessScreen to remove the image of the menufrom the screen.



UIEngine::ClearScreenvoid ClearScreen ()


Remarks:This function clears the application instantiatedscreen from the UI Engine. A ProcessScreen mustbe invoked in order for the UI Engine to be awareof it again.



UIEngine::GetUIVersionvoid GetUIVersion (int *Major, int *Minor, int *Revision)

Major:This parameter is a pointer to the UI Engine majorversion number.

Minor:This parameter is a pointer to the UI Engine minorversion number.

Revision:This parameter is a pointer to the UI Enginerevision number.


Remarks:This function returns the version of the UI Engine.



UIEngine::HandleInputRESULT HandleInput (MESSAGE &Message)

Message:This parameter is a RIM Message which containsdevice events.

Returns:This function returns one of five RESULT values:

x UNHANDLED,

x CONTINUE,

x CLICK,

x UI_SWITCH_TO_BACKGROUND, or

x HIDE_MENU.

Remarks:

UNHANDLEDThis implies the UI Engine did not know what todo with this input. Typical examples of this are:

x Receiving input from a non-keyboarddevice

x Typing a key when a field that has thefocus does not accept keys (e.g., list fields)

CONTINUEThis implies the UI Engine handled this input.Typical examples of input the UI Engine handlesinclude:

x Input that is navigational in nature (e.g.,rolling the roller wheel), and



x New key input if an edit field has thefocus.

CLICKThis implies the user has clicked the roller wheel.Typically clicking the roller wheel implies theapplication will bring up a menu, or if there is amenu or dialog already up, it will disappear.

UI_SWITCH_TO_BACKGROUNDThe UI Engine has switched the application to thebackground. This happens when the user selectsanother application from the menu (see Menu classon page 32). Typically an application would clearthe menu and go back waiting for another RIMmessage, when receiving this.

HIDE_MENUThe user has selected this menu item. Typically anapplication would go back to processing the screenunder the menu.



UIEngine::Initializevoid Initialize ()


Remarks:This function is the first function that should becalled after the UI Engine is instantiated.



UIEngine::ProcessDialogvoid ProcessDialog (Dialog &newDialog)

newDialog:This parameter is the application-instantiateddialog.


Remarks:This function displays the application instantiateddialog on the display. This dialog remains intactuntil either the application calls ClearDialog or theapplication invokes another ProcessDialogfunction. Remember the UI Engine only keepstrack of one screen at a time.



UIEngine::ProcessMenuvoid ProcessMenu (Menu &newMenu)

newMenu:This parameter is the application instantiatedscreen.


Remarks:This function displays the application instantiatedmenu on the display. This menu remainsdisplayed until either the application callsClearMenu or the application invokes anotherProcessMenu function. Remember the UI Engineonly keeps track of one menu at a time.



UIEngine::ProcessScreenvoid ProcessScreen (Screen &newScreen)

newScreen:This parameter is the application instantiatedscreen.


Remarks:This function displays the application instantiatedscreen on the display. This screen remains intactuntil either the application calls ClearScreen or theapplication invokes another ProcessScreenfunction. Remember the UI Engine only keepstrack of one screen at a time.



UIEngine::RestoreDisplayContextvoid RestoreDisplayContext ()


Remarks:This function restores the display contextassociated with the application when theapplication first instantiates the UI Engine. Thisallows one application to call another application(one thread to call a function in another thread)and use the latter display context.



UIEngine::UIEngineUIEngine()


Remarks:This is the constructor. There should only be oneUIEngine object per application. All input(typically from the keyboard device) to the UIEngine from a field object, a menu object, or adialog object should come through the UIEngineobject.

Where the input goes is determined by thefollowing: If a Dialog is on the display (the userhas performed a ProcessDialog()), the input will gothere. Otherwise, if a menu is on the display (theuser has performed a ProcessMenu()), it will gothere. Otherwise, the input will go to the screen(the user has performed a ProcessScreen()).Remember a screen is composed of fields;therefore, the input will go to the field with focus.

Note: The only way for the UI Engine to receiveinput is through an application.

It is important to note that the UI Engine doesntretain the previous contents of the display whenoutputting to the screen. If the application puts upa screen (ProcessScreen()) then puts up a menu,(ProcessMenu()), even if the application clears themenu (ClearMenu()) or the menu object goes out ofscope, the application must perform aProcessScreen() again to see the original screen.

32 API functions -- Menu class


Menu classThe following is the list of functions in the Menupublic member class.

_GetSelectedIndex.........................33

_HideAllTasksFromThread..........34

_HideItem......................................35

_HideItems ....................................36

_HideTaskNumber .......................37

_Menu............................................38

_RegisterSystemMenuItem...........40

_SetMenuItems..............................41

_SetSelectedIndex..........................43

_ShowAllTasksFromThread.........44

_ShowItem.....................................45

_ShowTaskNumber ......................46

API functions Menu class 33


Menu::GetSelectedIndexint GetSelectedIndex ()

Returns:The offset of the user selected menu item or valuereturned from the RegisterSystemMenuItemfunction.

Remarks:This function returns the offset of the menu itemselected by the user.

Note: Menu separator item strings that begin withtwo hyphens (--) can never be returned.



Menu::HideAllTasksFromThreadvoid HideAllTasksFromThread ()


Remarks:This function hides all application tasks from thecurrent task.

Note: This is a global function. Once invoked, alltasks will not show up, even if another menuwithin this task is instantiated.



Menu::HideItemvoid HideItem (int const Item)

ItemThis parameter is the offset innewMenuStringArray of the item requested to behidden.


Remarks:This function allows you the ability to not displaycertain menu items that are passed in thenewMenuStringArray. One purpose for this wouldbe to allow the user to use the same string array formore than one menu, where one menu woulddisplay certain items and another menu wouldnot.

Note: This function does not do anything if youalready have this menu displayed (ProcessMenu).



Menu::HideItemsvoid HideItems (int const Bitmap)

Bitmap:This parameter is a bitmap relationship with theassociated newMenuStringArray. A value of 1implies hide; a value of 0 implies display.


Remarks:This function allows you the ability not to displaycertain menu items that are passed in thenewMenuStringArray. One purpose for this wouldbe to allow the user to use the same string array formore than one menu, where one menu woulddisplay certain items and another menu wouldnot. In order for this function to visibly take effect,the application must perform a ProcessMenu.



Menu::HideTaskNumbervoid HideTaskNumber (TASK TaskHandleToHide)

TaskHandleToHide:This parameter is the handle of the task theapplication wants hidden. This can be obtainedusing RimGetCurrentTaskID().


Remarks:This function hides the associated task from the listof menu items.

Note: This is a global function. Once invoked, thistask will not show up, even if other tasks are put inthe foreground.



Menu::MenuForm 1: Menu()

Form 2: Menu (char const *const *constnewMenuStringArray, int NumberofEntries=-1)

newMenuStringArray:This parameter is a pointer to the address of astring array, containing user defined menu items.

NumberofEntries:This parameter is the number of applicationdefined menu items in the newMenuStringArray(maximum 32).


Remarks:This is the constructor. An item string that beginswith two underscore marks (__) is a menuseparator.

Note: The user can never select menu separatorsand GetSelectedIndex (below) never returns itsoffset in the newMenuStringArray.

Menus are composed of 4 kinds of elements:

HIDE_MENUThis always appears at the beginning. The UIEngine will return a status code of HIDE_MENUfrom HandleInput().



Application defined menu itemsThese are the menu items passed in from theapplication.

Note: These can be hidden or shown individuallyby the associated member functions.

System menu itemsThese are menu items that are also defined by theapplication with the RegisterSystemMenuItemfunction. This function passes a callback functionas a parameter, which the UI Engine will call whenthe user selects this menu item. This functionreturns an integer that the application can use asinput to SetSelectedIndex.

Task ItemsThese items are added by the UI Engine. They arethe applications tasks that are currently running.The displayed name is the name in the VersionPtrvariable in the applications PagerMain() function.



Menu::RegisterSystemMenuItemvoid RegisterSystemMenuItem (char const *const

pItemString, int TokenToReturn, void(*SpecialHandlerFunction) (int Token))

pItemString:This parameter is the pointer to the string that willbe displayed as a menu item.

TokenToReturn:This parameter is the value to return as the firstparameter when the UI Engine invokes theSpecialHandlerFunction.

SpecialHandlerFunction:This is the application callback function that the UIEngine invokes when the user selects theassociated menu item.


Remarks:This function allows the application to insert aglobal menu item in which the UI Engine will callSpecialHandlerFunction when the user selects theitem.

Note: This is a global function. Once invoked, theassociated menu item will show up in all menus,even other menus in other tasks.



Menu::SetMenuItemsvoid SetMenuItems (char const * const * constnewMenuStringArray, int const NumberofEntries)

newMenuStringArray:This parameter is the pointer to the address of astring array, containing menu items.

NumberofEntries:This parameter is the number of menu items in thenewMenuStringArray (maximum 32).


Remarks:An item string that begins with two underscoremarks (__) is a menu separator.

Note: The user can never select menu separatorsand GetSelectedIndex (below) never returns itsoffset in the newMenuStringArray.

Menus are composed of 4 kinds of elements:

HIDE_MENUThis always appears at the beginning. The UIEngine will return a status code of HIDE_MENUfrom HandleInput().

Application defined menu itemsThese are the menu items passed in from theapplication.



Note: These can be hidden or shown individuallyby the associated member functions.

System menu itemsThese are menu items that are also defined by theapplication with the RegisterSystemMenuItemfunction. This function passes a callback functionas a parameter, which the UI Engine will call whenthe user selects this menu item. This functionreturns an integer that the application can use asinput to SetSelectedIndex.

Task ItemsThese items are added by the UI Engine. They arethe applications tasks that are currently running.The displayed name is the name in the VersionPtrvariable in the applications PagerMain() function.



Menu::SetSelectedIndexvoid SetSelectIndex( int const Item )

Item:This parameter is the offset in thenewMenuStringArray or value returned from theRegisterSystemMenuItem function.


Remarks:This function selects the associated menu item.



Menu::ShowAllTasksFromThreadvoid ShowAllTasksFromThread ( void )


Remarks:This function will re-display all application tasksin the current task.

Note: This is a global function. Once invoked, alltasks will show up, even if another menu withinthis task is instantiated.



Menu::ShowItemvoid ShowItem( int const Item )

Item:This parameter is the offset innewMenuStringArray of the item requested to bemade visible.


Remarks:This function is the opposite of the HideItemfunction.



Menu::ShowTaskNumbervoid ShowTaskNumber( TASK TaskHandleToShow )

TaskHandleToShow:This parameter is the handle of the task theapplication wants redisplayed in the menu list.Use RimGetCurrentTaskID() to obtain this.Normally it is used after the invocation ofHideTaskNumber().


Remarks:This function redisplays the associated task in thelist of menu items.

Note: This is a global function. Once invoked, thistask will show up, even if other tasks are put in theforeground.

API functions Status class 47


Status classThe purpose of the status box is for system modalinformational messages to be displayed for a pre-defined period of time. For any other kinds ofmessages, a dialog box should be used. Thefollowing is an example of a status box with therelative position of the MessageString and theBitmap (which are both optional). DisplayTime isalways in 1/100 second intervals.

A status box

The following is the list of functions in the Statuspublic member class.

_DisplayModalStatus ................... 48

_GetDisplayTime.......................... 49

_SetBitmap .................................... 50

_SetDisplayTime........................... 51

_SetText......................................... 52

_Status ........................................... 53

48 API functions -- Status class


Status::DisplayModalStatusvoid DisplayModalStatus()


Remarks:This function is used if the default constructor wasinvoked. It displays the status box system-modallyfor the length of time specified. After the time hasexpired, the dialog box will be cleared from thescreen.



Status::GetDisplayTimeint GetDisplayTime() const

Returns:This function returns the amount of time (in 1/100second intervals) that the status will be displayed.

Remarks:This function is used if the default constructor wasinvoked.



Status::SetBitmapForm 1: void SetBitmap( BitMap const * const pBitmap )

Form 2: void SetBitmap( Bitmaps::PREDEFINED_BITMAP const pdb )

pBitmap:This parameter is the pointer to a bitmap.

pdb:This parameter is the pre-defined bitmap.





Status::SetDisplayTimevoid SetDisplayTime( int const DisplayTime )

DisplayTime:This parameter is the amount of time (in 1/100second intervals) the status is displayed.





Status::SetTextvoid SetText( char const * const pDisplayString )

pDisplayString:This parameter is the string to be displayed in thestatus box. Word wrapping is done automatically,so there is no need to manually line break thestring.





Status::StatusForm 1: Status()

Form 2: Status(char const * const pDisplayString, intconst DisplayTime = STATUS_DEFAULT_TIME)

Form 3: Status( BitMap const * const pBitmap, intconst DisplayTime = STATUS_DEFAULT_TIME )

Form 4: Status( Bitmaps::PREDEFINED_BITMAPconst pdb, int const DisplayTime =

STATUS_DEFAULT_TIME )

Form 5: Status(char const * const pDisplayString,BitMap const * const pBitmap, int const DisplayTime =

STATUS_DEFAULT_TIME )

Form 6: Status(char const * const pDisplayString,Bitmaps::PREDEFINED_BITMAP const pdb, int const

DisplayTime = STATUS_DEFAULT_TIME )

pDisplayString:This parameter is the string to be displayed in thestatus box. Word-wrapping is done automatically,so there is no need to manually line break thestring.

pBitmap:This parameter is the pointer to a bitmap.

pdb:This parameter is the pre-defined bitmap.

DisplayTime:This parameter is the amount of time (in 1/100second intervals) the status is displayed.




Remarks:These functions are the constructors. The statusbox is displayed immediately.

API functions Screen class 55


Screen classThe following is the list of functions in the Screenpublic member class.

_AddField ..................................... 56

_AddLabel..................................... 57

_GetFieldwithFocus...................... 58

_GetFirstField ............................... 59

_GetNextField......................... 60, 61

_IsFieldDirty ................................. 62

_MarkFieldAsClean...................... 63

_MarkFieldAsDirty....................... 64

_RemoveField ............................... 65

_RemoveLabel .............................. 66

_ResetScreen ................................. 67

_Screen .......................................... 68

_SetFieldwithFocus....................... 69

56 API functions -- Screen class


Screen::AddFieldvoid AddField(Field &newField, Field *

pFieldAfterNewField = NULL)

newField:This parameter is a field object (menu, list, choicebox, edit box, table).

pFieldAfterNewField:This parameter is the pointer to a field object thatappears after the newField.


Remarks:This function adds the field object to the associatedscreen. If the second parameter is NULL, the field isadded to the end of the list of fields.



Screen::AddLabelbool AddLabel(Label &newTitle)

newTitle:This parameter is a title object.

Returns:This function returns TRUE if successful. It returnsFALSE if the title object doesnt exist (i.e., you didnot instantiate a title object).

Remarks:See the section Title member functions on page 70for details on title objects.



Screen::GetFieldwithFocusField * GetFieldwithFocus()

Returns:This function returns the pointer to the field on thescreen that currently has the focus.



Screen::GetFirstFieldField * GetFirstField ()

Returns:This function returns the pointer to the field that isthe first in the list of field in the screen.



Screen::GetNextFieldField * GetNextField ()

Returns:This function returns the pointer to the subsequentfield.

Note: GetFirstField() must be called beforeGetNextField().



Screen::GetNextFieldField * GetNextField (Field * pField)

pField:This parameter is a pointer to a field.

Returns:This function returns the pointer to the field afterpField.



Screen::IsFieldDirtybool IsFieldDirty ()

Returns:This function returns TRUE if any of the fieldsassociated with the screen have changed.

Remarks:The application must invoke the member functionMarkFieldAsClean in order for the UI Engine toclear this state.



Screen::MarkFieldAsCleanvoid MarkFieldAsClean ()


Remarks:This function marks all the fields associated withthe screen as clean (i.e., no changes have beenmade to them).



Screen::MarkFieldAsDirtyvoid MarkFieldAsDirty ()


Remarks:This function marks all the fields associated withthe screen as dirty (i.e., simulates changes to them).



Screen::RemoveFieldvoid RemoveField (Field &FieldToRemove)

FieldToRemove:This parameter is a field object (menu, list, choicebox, edit box, table).


Remarks:This function removes the field object from the listof fields in the associated screen.



Screen::RemoveLabelvoid RemoveLabel (Label &TitleToRemove)

TitleToRemove:This parameter is a title object.


Remarks:This function removes the title object from the listof titles in the associated screen.



Screen::ResetScreenvoid ResetScreen()


Remarks:This function effectively does what ClearScreen inthe UI Engine does. It also removes all the linksbetween the fields (linked when AddField isinvoked) and all the titles (linked when AddLabelis invoked), and it physically blanks out thedisplay.



Screen::ScreenScreen()


Remarks:This is the constructor. This instantiates a screenobject. A screen object is the container of the fieldobjects and a title object.



Screen::SetFieldwithFocusbool SetFieldwithFocus( Field * pField)

pField:This parameter is a pointer to a field object (menu,list, choice box, edit box, table).

Returns:This function returns TRUE if successful. It returnsFALSE if the field does not exist (i.e. you did notinvoke AddField member function.

Remarks:If the field has more than one item that can be setor selected, the previous item that was set beforethat field lost the focus will be re-selected bydefault.

70 API functions -- Title class


Title classThe following is the list of functions in the Titlepublic member class.

_SetLocation ..................................71

_SetText .........................................72

_Title ..............................................73

API functions Title class 71


Title::SetLocationvoid SetLocation( int const XPosition, int const Width)

XPosition:This parameter is the position where text starts (inpixels).

Width:This parameter is the width of the text (in pixels).


Remarks:Titles always appear on the first line of the display.As indicated by the above parameters, there can bemore than one title object on the top line. RIMInter@ctive Pager 950 is 132 pixels wide and theaverage width of system font characters is 5 pixels.

72 API functions -- Title class


Title::SetTextvoid SetText (char const * const pnewText)

PnewText:This parameter is the pointer to the text thatappears in title.


Remarks:Titles always appear on the first line of the display.The text will be displayed in the associated offsetand location that is passed in the SetLocationmember function.

API functions Title class 73


Title::TitleForm 1: Title (int const XPosition = 0, int const Width =

LCD_WIDTH, char const * const pnewText = NULL)

Form 2: Title (char const * const pnewText, int constXPosition = 0, int const Width = LCD_WIDTH)

pnewText:This parameter is the position where text starts (inpixels).

XPosition:This parameter is the position where text starts (inpixels) from top left hand corner.

Width:This parameter is the width of the text (in pixels).


Remarks:These are the constructors. Titles always appear onthe first line of the display. As indicated by theabove parameters, there can be more than one titleobject on the top line. RIM Inter@ctive Pager 950 is132 pixels wide and the average width of systemfont characters is 5 pixels.

74 API functions -- Edit class


Edit classThe following is the list of functions in the Editpublic member class.

_AddProperties .............................75

_Append........................................76

_ClearProperties............................77

_Delete ...........................................78

_Edit...............................................79

_GetBuffer .....................................81

_GetBufferLength..........................82

_GetCursorOffset ..........................83

_GetLabel.......................................84

_GetProperties...............................85

_GetStringLength ..........................86

_Insert ............................................87

_Redraw.........................................88

_SetBuffer ......................................89

_SetCursorOffset ...........................90

_SetJustification.............................91

_SetLabel........................................92

_SetProperties................................93

API functions Edit class 75


Edit::AddPropertiesvoid AddProperties (unsigned long FlagstoSet)

FlagstoSet:This parameter is the properties to add.


Remarks:See SetProperties for the definitions. This leavesthe current properties intact.



Edit::Appendbool Append ( char const * const pInsertionString, int

const Length = -1 );

pInsertionString:This parameter is the pointer of the insertion stringto append.

Length:This parameter is the length of string. The defaultis the length of the insertion string.

Returns:This function returns TRUE if successful. It returnsFALSE if it was not successful.



Edit::ClearPropertiesvoid ClearProperties (unsigned long FlagstoClear)

FlagstoSet:This parameter is the properties to clear.


Remarks:See SetProperties for the definitions. This leaves allother properties intact.



Edit::Deletevoid Delete (int const Offset, int const Length)

Offset:This parameter is the offset in the edit buffer.

Length:This parameter is the length of string in the editbuffer to delete.




Edit::EditForm 1: Edit()

Form 2: Edit(char const * const pnewLabel, char *const pnewBuffer, int const newLengthofBuffer, int

const newCharacterOffset=0, int constJustify=LCD_LEFT_JUSTIFIED);

Form 3: Edit(char const * const pnewLabel, int constInitialSize, int const MaximumSize, int const

Justify=LCD_LEFT_JUSTIFIED);

pnewLabel:This parameter is the label associated with thefield.

pnewBuffer:This parameter is the pointer to the applicationdefined buffer.

newLengthofBuffer:This parameter is the length of the buffer.

newCharacterOffset:This parameter is the cursor offset.

InitialSize:This parameter is the initial size of UI Engineallocated buffer.

MaximumSize:This parameter is the maximum size of UI Engineallocated buffer.



Justify:This parameter is the justification of the edit bufferwith respect to the screen.


Remarks:These are the constructors. Two ways to use theEdit class are: using an application defined bufferor using a UI Engine defined buffer. The UI Engineallocates memory in the latter case.



Edit::GetBufferchar const * GetBuffer()

Returns:This parameter is the pointer to a buffer containingthe current contents of the edit buffer. A NULLvalue will be returned if the buffer is has nocharacters in it.



Edit::GetBufferLengthint GetBufferLength ()

Returns:This function returns the length of the buffer.



Edit::GetCursorOffsetint GetCursorOffset ()

Returns:This function returns the current offset in the editbuffer of the cursor.



Edit::GetLabelchar const * const GetLabel()

Returns:This function returns the label associated withcurrent edit field.



Edit::GetPropertiesunsigned long GetProperties()

Returns:This function returns the edit buffer properties.

Remarks:See SetProperties for the definitions.



Edit::GetStringLengthint GetStringLength() const

Returns:This function returns the length of the currentstring in the buffer.



Edit::Insertbool Insert (char const * const pInsertionString, int const

Position = -1, int const Length = -1)

pInsertionString:This parameter is the pointer of the insertionstring.

Position:This parameter is the position of insertion.

Length:This parameter is the length of string. The defaultis the length of the insertion string.

Returns:This function returns TRUE if successful. It returnsFALSE if it was not successful.



Edit::Redrawvoid Redraw()


Remarks:This function redraws the edit buffer.



Edit::SetBufferForm 1: void SetBuffer(char * const pnewBuffer, int const

newLengthofBuffer)

Form 2: void SetBuffer(char const * const pnewBuffer, intconst newLengthofBuffer)

Form 3: bool SetBuffer(int const InitialSize, int constMaximumSize)

pnewBuffer:This parameter is the pointer to application bufferused in the edit field.

newLengthofBuffer:This parameter is the length of above buffer.

InitialSize:This parameter is the initial size of UI Engineallocated buffer.

MaximumSize:This parameter is the maximum size of UI Engineallocated buffer.

Returns:The third SetBuffer can fail if the UI Engine cannotallocate the memory.

Remarks:Use the first SetBuffer when the buffer is allocatedby the application and is read/write. Use thesecond when the buffer is allocated by theapplication and is read-only. Use the third whenthe buffer is allocated by the UI Engine and isread/write.



Edit::SetCursorOffsetvoid SetCursorOffset (int newCharacterOffset=0)

newCharacterOffset:This parameter is the offset in the edit bufferwhere the character cursor is set.


Remarks:The cursor will advance one character as keys aretyped; the cursor will go back a character each timethe BACKSPACE key is pressed.



Edit::SetJustificationvoid SetJustification (int const

newJustify=LCD_LEFT_JUSTIFIED)

newJustify:This has one of 3 values:

x LCD_LEFT_JUSTIFIED,

x LCD_RIGHT_JUSTIFIED, or

x LCD_CENTERED.


Remarks:This function justifies the edit buffer.



Edit::SetLabelvoid SetLabel(char const * const pnewLabel)


pnewLabel:This parameter is the pointer to the label.



Edit::SetPropertiesvoid SetProperties (unsigned long FlagstoSet,

unsigned long FlagstoClear = 0xFF)

FlagstoSet:This parameter is the field and character propertiesto set. The upper 24 bits is the field propertydefinitions. The lower 8 bits define the characterproperties.

FlagstoClear:This parameter is the field and character propertiesto clear. By default all character properties arecleared.


Remarks:When first instantiated, there are no fieldproperties and all characters are accepted.

Edit objects have two kinds of properties:

Field properties:

READ_ONLYThe edit buffer is read only. If the field has thefocus and is given keyboard input (using the UIEngine member function HandleInput), the UIEngine returns UNHANDLED.

CR_TO_ROLL_DOWNThis property changes the meaning of ENTER frombeing insert a new line to roll down. If the cursor is



at the end of a field and the ENTER key is pressed,the cursor will go to the next field.

HANGING_INDENTThis indents the edit buffer.

AUTO_SPACE_SUBSTITUTIONThis is internal to the UI Engine.

PASSWORD_FIELDThis substitutes every character entered with anasterisk.

DISABLE_PRESS_HOLD_AUTO_CAPThis disables the property of pressing and holdingan alpha key down to automatically capitalize it.

DISABLE_POSITION_AUTO_CAPThis disables the property of capitalizing the wordafter a punctuation mark followed by a space.

DISABLE_POSITION_AUTO_PUNCThis disables the property of substituting 2 spaceswith period then space.

DISABLE_AUTO_FORMAT=DISABLE_PRESS_HOLD_AUTO_CAP|DISABLE_POSITION_AUTO_CAP|DISABLE_POSITION_AUTO_PUNC

EMAIL_FIELD=AUTO_SPACE_SUBSTITUTION|CTYPE::EMAIL_ADDRESS|DISABLE_AUTO_FORMATTING



Character properties:

DECIMAL_NUMERIC 0-9

ALPHABETICA-Z, a-z

ALPHANUMERICALPHABETIC + DECIMAL_NUMERIC

HEXIDECIMAL_NUMERIC0-9,a-f

PHONE0-9, (,), -,+,.,x,X

EMAIL_ADDRESSAll characters except specials, CTRLs, and SPACE(except @ and .).

EMAIL_WORDAll characters except specials, CTRLs, and SPACE.

URLURL characters (a-z,0-9,@,.,#,?,=

96 API functions -- DecimalEdit class


DecimalEdit classDecimalEdit is a class derived from Edit.

Note: If the ALT key is held while an alpha key istyped when this field has the focus, and the key isnumeric, the UI Engine will display the secondaryfunction character (the character displayed abovethe numeric key.)

The following is a list of functions in theDecimalEdit public member class.

_DecimalEdit .................................97

_GetNumber..................................98

_SetNumber...................................99

API functions DecimalEdit class 97


DecimalEdit::DecimalEditDecimalEdit (char * pLabel, int InitialNumber, int const

Justify=LCD_RIGHT_JUSTIFIED)

pLabel:This parameter is the label associated with the editbuffer.

InitialNumber:This parameter is the current number associatedwith the number.

Justify:This parameter is the justification.


98 API functions -- DecimalEdit class


DecimalEdit::GetNumberint GetNumber ()

Returns:This function returns the current number in theDecimalEdit field.

API functions DecimalEdit class 99


DecimalEdit::SetNumbervoid SetNumber( int Number )

Number:This parameter is the number to be placed in theDecimalEdit field.


100 API functions -- Separator class


Separator classA separator field is used to separate 2 fields forreadability purposes. If no parameters are passedto it, the string displayed is a line.

Note: A separator field can never have the focus.Therefore if you are scrolling over a separatorfield, the subsequent field will get the focus.

API functions Separator class 101


Separator::SeparatorForm 1: Separator (char const * const

pnewSeparatorString = NULL, intnewSeparatorStringLength = -1,int const newJustification

= LCD_LEFT_JUSTIFIED)

Form 2: Separator (BitMap const * constpnewSeparatorBitMap, int const newXOffset = 0)

pnewSeparatorString:This parameter is the pointer to the labelassociated with the separator.

newSeparatorStringLength:This parameter is the length associated with theseparator.

pnewSeparatorBitMap:This parameter is the pointer to bitmap associatedwith the separator.

newSeparatorStringLength:This parameter is the current number associatedwith the number.

newXOffset:This parameter is the horizontal Offset of thebitmap.


102 API functions -- List class


List classThe following is a list of functions in the Listpublic member class.

_Delete .........................................103

_GetNumEntries .........................104

_GetSelectedIndex.......................105

_GetTopLineEntry.......................106

_Insert ..........................................107

_List..............................................108

_NowDisplaying .........................109

_PutColumn ................................110

_Redraw............................... 111, 112

_SetNumEntries ..........................113

_SetSelectedIndex........................114

API functions List class 103


List::Deletevoid Delete( int const Index, bool Redraw = true )

Index:This parameter is the index of the item deleted.

Redraw:This parameter is an indicator to the UI Enginethat the list, if present on the screen, should beredrawn.




List::GetNumEntriesint NumEntries()

Returns:This function gets the number of entries in the list.



List::GetSelectedIndexint GetSelectedIndex()

Returns:This function returns the index of the selected itemin the list.



List::GetTopLineEntryint GetTopLineEntry()

Returns:This function gets the index of the first entry beingdisplayed on the display.



List::Insertvoid Insert( int const Index, bool Redraw = true )

Index:This parameter is the index where the item isinserted.

Redraw:This parameter is an indicator to the UI Enginethat the list, if present on the screen, should beredrawn.


Remarks:The UI Engine will call NowDisplaying for theinserted item.



List::ListForm 1: List()

Form 2: List( int const NumEntries)

NumEntriesThis parameter is the number of entries in the list.


Remarks:These are the constructors. When the UI Engineneeds to display the string associated with index inthe number of entries, the UI Engine calls the purevirtual member function NowDisplaying, once forevery line (this must be implemented by theapplication). NowDisplaying would then call thePutColumn member function, perhaps a numberof times, which tells the UI Engine the associatedstring(s) to display. This is useful if the displayedlist needs its information columnized. The onus ison you, as a developer, to write theNowDisplaying member function.



List::NowDisplayingvoid NowDisplaying(int const Index)

Index:This parameter is the index in the string array ofitem being updated.


Remarks:This is a pure virtual function (written by you,called by the UI Engine). The UI Engine calls thisfunction when the application invokes one of thedrawing functions. This triggers the application tocall the PutColumn member function to update thestring associated with this handle. The PutColumnmember function can be called more than once,normally if the application wants columnizedstrings on the associated line.



List::PutColumnvoid PutColumn (char const * const pnewStr, int const

ColumnWidth = LCD_WIDTH, int const Flags =DEFAULT, int const StrLength = INT_MAX)

pnewStr:This parameter is the pointer to the stringassociated with this index.

ColumnWidth:This parameter is the maximum width of thelocation (in pixels).

Flag:This parameter is reserved for futureenhancement.

StrLength:This parameter is reserved for futureenhancement.


Remarks:This function can be called more than once.Subsequent calls after the first call abut based onthe previous ColumnWidth. The text is leftjustified in ColumnWidth.



List::Redrawvoid Redraw()


Remarks:This function instigates redrawing of the entire list,based on the selected item.

Note: The UI Engine will call NowDisplaying forall items it wants to display.



List::Redrawvoid Redraw(int const Index)

Index:This parameter is the index in the string array ofitem being updated.


Remarks:This function causes the UI Engine to redraw theline associated with the item in the string array(perhaps the string associated with the line haschanged).

Note: The UI Engine will call NowDisplaying forthe item.



List::SetNumEntriesvoid SelectIndex( int Index)

Index:This parameter sets the number of entries in thelist.




List::SetSelectedIndexvoid SetSelectedIndex( int const Index)

Index:This parameter is the index of the item in list theapplication wants selected.


API functions StringList class 115


StringList classStringList is a class derived from List. This is a listin which the members are constant strings thatnever change. Unlike List, the application does notneed to implement the NowDisplaying memberfunction.

The following is a list of functions in the StringListpublic member class.

_SetStringList .............................. 116

_StringList................................... 117

116 API functions -- StringList class


StringList::SetStringListvoid SetStringList (char const *const * StringArray)

StringArray:This parameter is a pointer to an array of strings.The last entry must be 0.


API functions StringList class 117


StringList::StringListForm 1: StringList()

Form 2: StringList ( char const *const * StringArray)

StringArray:This parameter is a pointer to an array of strings.The last entry must be 0.


Remarks:These are constructors.

118 API functions -- Choice class


Choice classThe following is a list of functions in the Choicepublic member class.

_ChangeChoice ...........................119

_Choice ........................................120

_GetLabel.....................................122

_GetSelectedIndex.......................123

_GetSelectedValue ......................124

_SetChoices..................................125

_SetLabel......................................126

_SetSelectedIndex........................127

API functions Choice class 119


Choice::ChangeChoiceRESULT ChangeChoice( UIEngine &newCallingUI, void

((*CallbackFunction)(int Value)) = NULL)

NewCallingUI:This parameter is the UIEngine object associatedwith this choice box.

CallbackFunction:If the value is not NULL, this function is called eachtime the associated ChoiceBox value is called.

Returns:

UNHANDLEDThis implies the BACKSPACE key was hit.

CLICKEDThe user hit either the ENTER key or clicked theroller wheel.

Remarks:One way the user changes the Choice Box choice isby hitting ALT+ROLL. ChangeChoice is an alternativewhich, when invoked, places a Dialog on thescreen that uses another Choice Box (using thesame data) as the field in the Dialog. Rolling upand down changes the data associated with theChoice Box. Each time a change is made, the UIEngine calls the CallBackFunction.



Choice::ChoiceForm 1: Choice()

Form 2: Choice (char const * const pnewLabel, charconst * const * const newStringArray, int const

newIndex=0, int const Justify=LCD_RIGHT_JUSTIFIED)

Form 3: Choice( char const * const pnewLabel,unsigned int const newStartValue, unsigned int const

newEndValue, int const newIndex=0, int constIncrement=1, int const Justify=LCD_RIGHT_JUSTIFIED

)

pnewLabel:This parameter is the pointer to the choice boxlabel. Labels are left justified.

pnewStringArray:This parameter is a pointer to a string array. Thisstring is displayed right justified.

NewStartValue:This parameter is the integer values to start arange.

NewEndValue:This parameter is the integer value to end a range.

NewIndex:This parameter is the starting value within theabove range.

Increment:This parameter is the increment value in the aboverange.



Justify:This parameter is the display justification of thedata portion of a choice box.



Choice Boxes are effectively one line text boxes.There are two ways to trigger the UI Engine tochange the displayed data: simultaneouslypressing the ALT key and rolling, or using theChangeChoice member function. The applicationpasses data to the UI Engine in 2 ways:

x

Pass a pointer to a string array and theoffset in the array for the initial value.When the user performs ALT+ROLL, the nextvalue in the array will be displayed(rolling down will set the next value,rolling up will display the previous value).

x

Pass an integer range, and initial value.When the user performs ALT+ROLL, the nextvalue in the range will be displayed(rolling down will set the next value,rolling up will display the previous value).



Choice::GetLabelchar const * const GetLabel()

Returns:This function returns the label associated withchoice box.



Choice::GetSelectedIndexint GetSelectedIndex()

Returns:This function returns the index of either the stringarray or index of the value, depending on whatconstructor is used.

Remarks:This function returns the value selected by theuser.



Choice::GetSelectedValueint GetSelectedValue()

Returns:This function returns the value of the choice box.

Remarks:When the 3rd constructor above is used, thisreturns the value that is displayed in the choicebox.



Choice::SetChoicesForm 1: void SetChoices (char const * const * const

newStringArray, int const newIndex=0)

Form 2: void SetChoices (unsigned int constnewStartValue,unsigned int const newEndValue,int

const newIndex=0)

newStringArray:This parameter is the string array containingchoice box entries.

newIndex:This parameter is the index into the currentlyselected entry associated with newIndex.

newStartValue:This parameter is the start value.

newEndValue:This parameter is the end value.




Choice::SetLabelvoid SetLabel(char const * const pnewLabel)

pnewLabel:This parameter is the label associated with thechoice box.




Choice::SetSelectedIndexvoid SetSelectedIndex(int const newIndex)

newIndex:This sets the index of either the string array or theindex of the value, depending on what constructoris used.


Remarks:This function sets the index of the choice box.

128 API functions -- YesNoChoice class


YesNoChoice classYesNoChoice is a class derived from Choice. Itfixes the string array to be either Yes or No.

The following is a list of functions in theYesNoChoice public member class.

_GetFlag.......................................129

_SetFlag........................................130

_YesNoChoice .............................131

API functions YesNoChoice class 129


YesNoChoice::GetFlagbool GetFlag()

Returns:This function returns TRUE if Yes and FALSE if No.

130 API functions -- YesNoChoice class


YesNoChoice::SetFlagSetFlag (bool newFlagValue)

NewFlagValue:If this parameter is TRUE, the value in the choicebox is set to Yes. If this parameter is FALSE, thevalue in the choice box is set to No.


API functions YesNoChoice class 131


YesNoChoice::YesNoChoiceYesNoChoice( char * Label, bool CurrentChoice )

Label:This parameter is the label associated with thechoice box.

CurrentChoice:If this parameter is TRUE, the current value in thechoice box is Yes. If this parameter is FALSE, thecurrent value in the choice box is No.



132 API functions -- TopBottomChoice class


TopBottomChoice classTopBottomChoice is a class derived from Choice.It fixes the string array to be either Top or Bottom.

The following is a list of functions in theTopBottomChoice public member class.

_GetFlag.......................................133

_SetFlag........................................134

_TopBottomChoice .....................135

API functions TopBottomChoice class 133


TopBottomChoice::GetFlagbool GetFlag()

Returns:This function returns TRUE if Top and FALSE ifBottom.

134 API functions -- TopBottomChoice class


TopBottomChoice::SetFlagSetFlag(bool newFlagValue)

newFlagValue:If this parameter is TRUE, the value in the choicebox is set to Top. If this parameter is FALSE, thevalue in the choice box is set to Bottom.


API functions TopBottomChoice class 135


TopBottomChoice::TopBottomChoiceTopBottomChoice( char * pLabel, bool CurrentChoice )

pLabel:This parameter is the pointer to the labelassociated with the choice.

CurrentChoice:If this parameter is TRUE, the current value in thechoice box is Top. If this parameter is FALSE, thecurrent value in the choice box is Bottom.



136 API functions -- BeepChoice class


BeepChoice classBeepChoice is a class derived from Choice. It istied directly to the OS function RimTestAlert.

The following is a list of functions in theBeepChoice public member class.

_BeepChoice ................................137

_GetBeep......................................138

_SetBeep.......................................139

_SetLabel......................................140

API functions BeepChoice class 137


BeepChoice::BeepChoiceBeepChoice( char * Label, int CurrentChoice )

Label:This parameter is the label associated with thechoice box.

CurrentChoice:This is the same as the first parameter inRimTestAlert.





BeepChoice::GetBeepint GetBeep()

Returns:This is the same as the first parameter inRimTestAlert.

API functions BeepChoice class 139


BeepChoice::SetBeepSetBeep(int newBeepNumber)

newBeepNumber:This is the same as the first parameter inRimTestAlert.




BeepChoice::SetLabelvoid SetLabel(char const * const pnewLabel)

pnewLabel:This parameter is the label associated with thechoice box.


API functions Dialog class 141


Dialog classThe following is a list of functions in the Dialogpublic member class.

_ClearDialog ............................... 142

_Dialog ........................................ 143

_DisplayDialog ........................... 145

_SetBitmap .................................. 146

_SetDisplayString ....................... 147

_SetField...................................... 148

142 API functions -- Dialog class


Dialog::ClearDialogvoid ClearDialog ()


Remarks:This function clears the dialog box from thedisplay.



Dialog::DialogForm 1: Dialog ()

Form 2: Dialog ( char const * const newpDisplayString,BitMap const * const newpBitmap=NULL, Field * const

pField=NULL )

Form 3: Dialog ( char const * const newpDisplayString,BitMaps::PREDEFINED const * const

newpBitmap=NULL, Field * const pField=NULL )

newpDisplayString:This parameter is the pointer to the stringassociated with the dialog box.

newpBitmap:This parameter is the pointer to a bitmap (customor pre-defined).

pField:This parameter is a pointer to a field (typically editor list).


Remarks:These are the constructors.

The DisplayString, Bitmap and Field are placed inan application modal dialog box on the display.The following is an example of a dialog box withthe relative position of the DisplayString, Bitmap,and a Field.



A dialog box



Dialog::DisplayDialogvoid DisplayDialog ()


Remarks:This function displays the dialog box on thedisplay.



Dialog::SetBitmapvoid SetBitmap (BitMap const * const Bitmap)

void SetBitmap (BitMaps::PREDEFINED_BITMAPconst Bitmap)

Bitmap:This parameter is the pointer to a bitmap (customor pre-defined).


Remarks:The Bitmap is placed in a dialog box on thedisplay.



Dialog::SetDisplayStringvoid SetDisplayString(char const * const

newpDisplayString )

newpDisplayString:This parameter is the pointer to the stringassociated with the status box.




Dialog::SetFieldvoid SetField( Field &newpField , int const

newFieldHeight = LCD_HEIGHT, int constnewFieldWidth = LCD_WIDTH)

newpField:This parameter is the field (typically Edit or List)that is part of the dialog.

newFieldHeight:This parameter is the height of the field.

newFieldWidth:This parameter is the width of the field.


API functions YesNoDialog class 149


YesNoDialog classYesNoDialog is a class derived from Dialog. Ituses a list object as the field, poses an optionalquestion, and puts up the list items Yes, No andoptionally Cancel.

The following is a list of functions in theYesNoDialog public member class.

_AnswerIsNo .............................. 150

_AnswerIsYes ............................. 151

_GetAnswer ................................ 152

_Go .............................................. 153

_SetDefaultItem .......................... 154

_SetQuestion ............................... 155

_ShowCancelItem....................... 156

_YesNoDialog ............................. 157

150 API functions -- YesNoDialog class


YesNoDialog::AnswerIsNobool AnswerIsNo()

Returns:This function returns TRUE if the item that wasselected last was no.



YesNoDialog::AnswerIsYesbool AnswerIsYes()

Returns:This function returns TRUE if the item that wasselected last was yes.



YesNoDialog::GetAnswerYN_ITEM GetAnswer()

Returns:This function returns the item that was selectedlast.



YesNoDialog::Govirtual YN_ITEM Go(UIEngine &UIEngineToUse );

UIEngineToUse:This parameter is the associated UIEngine object touse.

Returns:This function returns ITEM_YES, ITEM_NO, oroptionally ITEM_CANCEL.

Remarks:This function displays the dialog.



YesNoDialog::SetDefaultItembool SetDefaultItem( YN_ITEM DefaultItem )

DefaultItem:Thi

RIM Inter@active UI Developer's Guide

Documents

Transcript of RIM Inter@active UI Developer's Guide