leos software development manual - volume 2 api

8/3/2019 LEOs Software Development Manual - Volume 2 API

1/88

D E V E L O P M E N T K I T

LEOs Software Development ManuVolume 2: API

2005 Empower Technologies, Inc. or its subsidiaries. All rights reserved. The registered trademark Linux is used pursuant to a sublicense from the Linux MaInstitute,the exclusive licensee of Linus Torvalds, owner of the mark on a world-wide basis. LinuxDA and LEOs are trademarks of Empower Technologies, Inc. OMA

is a registered trademark of Texas Instruments. All other trademarks are the property of their respective owners.


2/88

Table of Contents

1 Introduction ...........................................................................................................................................12 Form API ................................................................................................................................................32.1 FORM Data Structure...........................................................................................................................32.2 Form Constants ....................................................................................................................................62.3 Form Components................................................................................................................................92.4 Form Functions...................................................................................................................................203 GUI Message API.................................................................................................................................343.1 GUI_ MSG Data Structure..................................................................................................................343.2 GUI Message Types...........................................................................................................................343.3 GUI Message Functions.....................................................................................................................374

Draw API ..............................................................................................................................................39

4.1 Draw Structures and Constants .........................................................................................................394.2 Draw Functions...................................................................................................................................425 Text Functions.....................................................................................................................................486 Database API .......................................................................................................................................516.1 Database Structures and Constants ..................................................................................................516.2 Database Functions............................................................................................................................527 Communication Functions.................................................................................................................638 Camera Functions...............................................................................................................................669 Sound API ............................................................................................................................................6910 Other Functions ..................................................................................................................................7111 Sample Programs................................................................................................................................7611.1 Sample Program 1..............................................................................................................................7611.2 Sample Program 2..............................................................................................................................7711.3 Sample Program 3..............................................................................................................................7811.4 Sample Program 4..............................................................................................................................7911.5 Sample Program 5..............................................................................................................................8111.6 Sample Program 6..............................................................................................................................8211.7 Sample Program 7..............................................................................................................................8311.8 Sample Program 8..............................................................................................................................8411.9 Sample Program 9..............................................................................................................................8511.10Sample Wav Demonstration...............................................................................................................86

LEOs Software Development Manual Volume 2: API i


3/88

1 Introduction

The LinuxDA Embedded Operating System (LEOs) Application Program Interface (API) is designed tomake developing applications for the LDK5910 EVM straight forward and efficient. This manual contains abrief tutorial and complete command reference for the LEOs API. More information about developingapplications, including the basic code structure, instructions for working with the compiler and directions forhow to rapidly test and deploy new applications for the LDK5910 EVM can be found in the LEOs SoftwareDevelopment Manual Volume 1: SDK.

LEOs applications are mostly single-threaded programs. An application will usually display a screen andthen poll the operating system for graphic user interface messages (GUI messages) in a messageprocessing loop.

The screen itself is a form, as are all other components the GUI provides, like buttons, scroll bars and textboxes. Forms are defined using arrays of elements of the FORM data structure. Once defined, a form can be

displayed with a function call. Form arrays and the FORM data structure are discussed in detail inSection 2.

All user input, like tapping the stylus on the screen or pushing a hardware button, generates GUI messages.GUI messages can also be generated by the system or other applications. When an event occurs,

information about the event and its context is recorded in the GUI_MSG data structure and added to themessage queue. The applications message processing loop requests messages, one at a time, from thefront of the queue and processes them. Messages received by the application which cannot be handledproperly must be returned to the system for processing. GUI messages are discussed in detail in Section 3.

Finally, when applications which use the LEOs API are started, they will receive a launch command fromthe system. The launch command depends on the mode of the system, and it is important that the

application handles it properly. To do this, the int main(){} in .c should follow the

model shown in the sample code for the function init_screen(), Section 2.4.

Given these three core concepts, the typical LEOs application flow will follow the diagram in Figure 1.

Along with the GUI based API components the LEOs API provides tools for working with databases,drawings, data communication and more.

Section 1 Introduction: How to use the manual and an introduction to core LEOs GUI concepts.Section 2 Form API: Detailed instructions for working with forms and a complete reference for all formcomponents and form related functions.

Section 3 GUI Message API: A complete reference of all GUI messages and GUI message functions.

Section 4 Draw API:A complete reference of all drawing related API components.

Section 5 Text Functions:A complete reference of all text processing functions.

Section 6 Database API:A complete reference of all database handling functions.

Section 7 Communication Functions:A complete reference of all data communication functions.

Section 8 Camera Functions:A complete reference of functions related to capturing from the camera.

Section9 Sound API:A complete reference of functions related to sound.Section 10 Other Functions:Functions provided by the API that don't belong in another category.

Section 11 Sample Programs:Brief descriptions of 9 sample programs included in the LDK5910 whichcan help new developers get up and running as fast as possible.

LEOs Software Development Manual Volume 2: API 1


4/88

LaunchApplication

LaunchCommand

Initialize GUI&Create form

Send App.

Information

Get GUIMessage

MessageDestination

Return Msg.To System

Close GUI

TimeTo Quit?

Exit

Incorrect

Run Normal

Yes

No

Correct

Send Info.

ProcessMessage

Figure 1: Typical Application Organization



5/88

2 Form API

2.1 FORM Data Structure

Forms are defined within programs using an array of elements of the FORM data structure. A form array

always begins with a caption component which gives the form array a title and defines the size and positionof the array on the screen. The caption is followed by any number of other components, like buttons, labels,and scroll bars.

Figure 2 is a screenshot of the form array in sample program 3 included in the LDK5910. It consists of acaption with the text Sample3" which fills the screen and 14 other form components. Only 9 of thecomponents are visible in the screenshot. The LEOs taskbar is also visible, but it is not part of the formarray. The taskbar is attached by the system when a program is executed.

Label

Button

Spin Button

Scroll Bar

Combo Box

Text Box

Check Button

Button

LEOsTaskbar

Bitmap

Figure 2: Screenshot

The FORM data structure is a collection of variables which together define the precise appearance and

function of each form component to be displayed. Table 1 contains a detailed description of each memberof the FORM data structure.



6/88

Table 1: FORM data structure

{type, id, x, y, w, h, *text, style, status, font} gui.h

The component type. U8type

For example, caption, button, or label. There are currently 13 form componentsdefined in the LEOs API. For a quick list, see Table 5. For details about a specificcomponent, see the form component reference in 2.3.

Identifying number (ID). U8id

GUI messages read by a program use id to indicate which form component the

message applies to. id must be unique within a form array.

Form component position. U16, U16x, y

The horizontal and vertical coordinates of the upper left hand corner of the form

component, respectively. The position of some components is automaticallycalculated, so x ory may not be used. When not in use, set x ory to 0.

Form component size. U16, U16w, h

The width and height of the form component, respectively. The size of some elementsis automatically calculated, so w orhmay not be used. When not in use, set w ory to 0.

Pointer to a component specific structure void*text

For certain components, like buttons and menus, this is a pointer to the text stringdisplayed. For other components, this is a pointer to a type specific structure with moreinformation about the form to be displayed. A quick listing of component specificstructures is included in Table 5. Detailed descriptions are included under appropriateentries of the form component reference in 2.3.

Component specific style. U8style

Styles are component specific. For example, a buttons border can be suppressed

using the button specific style BUTTON_NO_BORDER here. For a quick listing ofavailable styles, see Table 5. Descriptions of component specific styles are includedunder appropriate entries of the form component reference in 2.3.

Visibility of component. U8status

Any component can be made either visible or invisible. See Table 3 for all availablestatus values.

Text size. U8font

Three fonts are available, small, medium, and large. Small is recommended due to the

screen size. See Table 4 for a listing of all available font values.

Note: U8 and U16 are defined in gui.h. They are currently equivalent to unsigned char and unsigned short,respectively.



7/88

The screenshot in Figure 2 can be generated with the following form array declaration.

Table 2: Sample form array

static FORM frmSample[]={

Declaration offrmSample

, an array of form components. The form array elements and their

descriptions follow.

{FORM_CAPTION, 0, 0, 0, SCREEN_WIDTH, SCREEN_HEIGHT-TASKBAR_HEIGHT,&frm_caption, FORM_FRAME_CAPTION, COMPONENT_VISIBLE, FONT_MEDIUM},

All form arrays must begin with a caption. The ID for this component can be set to 0 because it will nothandle any messages. The caption takes up the whole screen, from the top left corner (0,0), to thebottom right(SCREEN_WIDTH, SCREEN_HEIGHT - TASKBAR_HEIGHT). Captions have a

component specific structure, FORMCAPTION. The title string is one of the structure's elements (i.e.

frm_caption.str = "Sample3").

{FORM_MENU, 10, 5, 20, 0, 0, "File", 0, COMPONENT_VISIBLE},

This array element places the menu File" at (5,20). The width and height are set to 0 because they

are calculated by the system based on the text to be displayed. Menus are hidden until the user tapson them, which is why this element is not visible in Figure 2.

{FORM_MENUITEM, 11, 0, 0, 0, 0, "Exit", 0},

Menu items must come directly after the menu in which they are to appear. This element creates themenu item Exit" in the File" menu. Position and size are to be calculated.

{FORM_MENU, 20, 55, 20, 0, 0, "Help", 0, COMPONENT_VISIBLE},{FORM_MENUITEM, 21, 0, 0, 0, 0, "How to", 0},{FORM_MENUITEM, 22, 0, 0, 0, 0, "About", 0},

These three elements create the Help" menu with the items How to" and About".

{FORM_BUTTON, 30, 50, 150, 40, 20, "Test", 0, COMPONENT_VISIBLE, 0},{FORM_BUTTON, 40, 50, 200, 40, 20, "Add", 0, COMPONENT_VISIBLE},

These two elements create the buttons Test" and Add".

{FORM_SPINBUTTON, 50, 150, 200, 0, 0, &spin, HSPINBUTTON, COMPONENT_VISIBLE},

This element creates the spin button at (150,200). The style, HSPINBUTTON, specifies that it is

horizontal. When the spin button is tapped, a GUI message of type EVENT_CLICK will be generated.

The message's value will be 1 for the left arrow, +1 for the right arrow.

{FORM_COMBOBOX, 60, 150, 150, 62, 12, &cmb, COMBOBOX_LEFT_ALIGN,COMPONENT_VISIBLE, FONT_MEDIUM},

This element creates the combo box at (150,150). When the combo box is tapped, an EVENT_CLICK

message is generated and the list is displayed automatically.

{FORM_TEXTBOX, 70, 70, 30, 70, 15, &tb, 0, COMPONENT_VISIBLE, FONT_LARGE},

This element creates the text box at (70,30). When the text box is tapped, the soft keyboard willappear automatically and the user can enter text. When the user leaves the soft keyboard, the GUImessage EVENT_INPUTCHAR is generated indicating that the text box has changed.



8/88

{FORM_LABEL, 80, 2, 30, 60, 10, &bla_str, LABEL_MULTILINE, COMPONENT_VISIBLE,FONT_SMALL},

This element creates the label at (2,30). The style, LABEL_MULTILINE, tells the system to check thetext string for new line characters and display the label appropriately. A labels style can also include

text alignment methods. Multiple styles can be combined with |.

{FORM_SCROLLBAR, 90, 230, 15, 0, 280, &scr, VSCROLLBAR, COMPONENT_VISIBLE},

This element creates the scroll bar at (230,15). w is fixed, so it is not used. Scroll bars do not have a

corresponding screen control. The screen must be updated based on the scroll bar position manuallywithin the application.

{FORM_BITMAP, 100, 50, 80, 21, 21, &sample_pic, 0, COMPONENT_VISIBLE, 0},

This element creates the 21x21 pixel bitmap component at (50,80). The bitmap data is storeduncompressed in an array. Often, as in sample program 3, the bitmap data is included directly withinthe array declaration at the beginning of.c. Bitmaps have a type specific data

structure BITMAP. In this case the bitmap array is sample_pic.img.

{FORM_CHECKBUTTON, 110, 30, 100, 40, 10, &cb, 0, COMPONENT_VISIBLE, 0},

This element creates the check button at (30,100). When the check button is tapped, anEVENT_CLICK message is generated.

{FORM_END}};

The last entry of the form array must be {FORM_END}.

2.2 Form Constants

Table 3: Form component status constants

COMPONENT_VISIBLE MENU_DROPPED

COMPONENT_INVISIBLE MENU_UNDROPPED

Note: Component status values can be used with all form components. By convention the values with theMENU_ prefix are only used with menu components. In practice, they are synonymous with theCOMPONENT_ prefixed values.

Note: Constants are defined in gui.h.

Table 4: Form font constants

Font Height Font Height

FONT_SYS 13 FONT_MEDIUM 15

FONT_SMALL 13 FONT_LARGE 21

FONT_BOLD 21

Note: Constants are defined in gui.h.



9/88

Table 5: Component specific form constants and data types

Form Component Applicable Styles Component Specific Type

FORM_CAPTION FORM_FRAME_CAPTIONFORM_FRAME_BORDERFORM_SAVEBEHINDFORM_DLGFRAME

typedef struct {char *str;void *icon;RECR r;

}FORMCAPTION;

FORM_LABEL X_ALIGN_LEFTX_ALIGN_MIDDLEX_ALIGN_RIGHTY_ALIGN_TOPY_ALIGN_CENTERY_ALIGN_BOTTOMLABEL_BORDERLABEL_MULTILINE

None

FORM_BUTTON BUTTON_NO_BORDER None

FORM_BITMAP BITMAP_BORDERBITMAP_BUTTONBITMAP_CAPTION_INNERBITMAP_DOTBORDERBITMAP_CAPTION_RIGHTBITMAP_CAPTION_BOTTOM

Typedef struct {short width,height;void *img;char *caption;void *mask;

}BITMAP;

FORM_MENU None None

FORM_MENUITEM None None

FORM_SYSTEM None None

FORM_SCROLLBAR VSCROLLBARHSCROLLBAR

typedef struct{short max,position,page_height;RECT first_r, second_r;RECT third_r, last_r;RECT button_r;

} SCROLLBAR;

FORM_TEXTBOX None typedef struct {short counter_lines;char string[TEXTBOX_MAX_CHAR];short max_char;short min_empty_lines;short start_line;

short visible_lines;}TEXTBOX;

FORM_SPINBUTTON VSPINBUTTONHSPINBUTTON

typedef struct {short spacing;char str[32];

}SPINBUTTON;



10/88

Form Component Applicable Styles Component Specific Type

FORM_CHECKBUTTON None typedef struct{short value;void *caption;

}CHECKBUTTON;

FORM_COMBOBOX COMBOBOX_NO_BORDERCOMBOBOX_LEFT_ALIGNCOMBOBOX_RIGHT_ALIGNCOMBOBOX_NO_ARROW

typedef struct {short index;char str[32];

}ITEM;

typedef struct {short max_items;short selected;short drop_down_width;short drop_down_height;ITEM items;

}COMBOBOX;

FORM_END

Note: Descriptions of component specific structures are included under appropriate entries in the formcomponent reference, Section2.3.

Note: The constants and data structures in this table are defined in gui.h.



11/88

caption Caption must be the first item in your form array declaration.

a) FORM_FRAME_CAPTION b) FORM_DLGFRAME

c) FORM_FRAME_BORDER

Figure 3: Caption styles

type FORM_CAPTION

id Not used, set to 0.

x,y,w,h (x,y) are the coordinates of the top-left of the form. w is the width and h is the height

*text pointer to the structure FORMCAPTION.

typedef struct {char *str; //the caption string, NULL if the

//caption is an iconvoid *icon; //the caption icon, NULL if the

//caption is a stringRECR r; //reserved for system use.

}FORMCAPTION;

style A caption can use one or more of the following four styles. Use the | operand to connect

them.

FORM_FRAME_CAPTION

If this style is set, a caption bar will be shown as depicted in Figure 3a. The blank areaon the left of the caption can be used to hold other components, such as buttons and

combo boxes.

FORM_DLGFRAME

The caption bar is as wide as the form as depicted in Figure 3b.

FORM_FRAME_BORDER

A boarder will be attached to the form as depicted in Figure 3c.

0

The form will be displayed without a caption, not shown.


2.3 Form Components


12/88

status not used, set to 0

font Any available font, see Table 4 for a listing (FONT_MEDIUM is recommended)

examples The FORM_CAPTION in Figure 3a was created with the form definition below:

FORMCAPTION form_caption = {"Sample3"};FORM frmMain[]={{FORM_CAPTION, 0, 0, 0, SCREEN_WIDTH, SCREEN_HEIGHT, &from_caption,FORM_FRAME_CAPTION, COMPONENT_VISIBLE, FONT_MEDIUM},{FORM_END}};

The FORM_CAPTION in Figure 3b was created with the form definition below:

FORMCAPTION form_cap = {"MagicPen"};FORM frmMain[]={{FORM_CAPTION, 0, 0, 20, SCREEN_WIDTH, 60, &form_cap,

FORM_FRAME_CAPTION | FORM_FRAME_BORDER | FORM_DLGFRAM |FORM_SAVEBEHIND, COMPONENT_VISIBLE, FONT_MEDIUM},{FORM_END}};

The FORM_CAPTION in Figure 3c was created with the form definition below:

FORMCAPTION form_caption = {"Set Time"};FORM frmMain[]={{FORM_CAPTION, 0, 0, 0, SCREEN_WIDTH, SCREEN_HEIGHT, &from_caption,FORM_FRAME_BORDER, COMPONENT_VISIBLE, FONT_MEDIUM},{FORM_END}};

label Labels are often used to indicate what another component is for. For example, in Figure 4,

Last Name:" is a label indicating that the text box to the right is for inputting a last name.

Figure 4: Labels

type FORM_LABEL

id component ID

x,y,w,h (x,y) are the coordinates of the top-left of the form. w is width and h is height.

*text Pointer to the label's text string.

style Indicates the text alignment. There are 6 alignment methods available, see Table 5 for thecomplete listing. Both the x and y alignments must be set or the label may not displayproperly.



13/88

Other styles:

LABEL_BORDER

This will make the label look like a button.

LABEL_MULTILINE

The label has multiple lines. Each line is separated by \n.

status COMPONENT_VISIBLE orCOMPONENT_INVISIBLE

font Any available font, see Table 4 for a listing.

examples The FORM_LABEL in Figure 4 was created with the form definition below.

FORM frmMain[]={...{FORM_LABEL, 10, 5, 5, 30, 15, "Last Name:", X_ALIGN_RIGHT |Y_ALIGN_CENTER, COMPONENT_VISIBLE, FONT_SMALL},{FORM_LABEL, 20, 5, 25, 30, 15, "First Name", X_ALIGN_RIGHT |Y_ALIGN_CENTER, COMPONENT_VISIBLE, FONT_SMALL},...{FORM_END}};

menu The menu bar is hidden unless the user taps in the caption region where the menu is.Option" in Figure 5 is a menu in the menu bar.

The event EVENT_SHOW_MENUBAR will be triggered when the menu bar is shown. The

event EVENT_HIDE_MENUBAR will be triggered when the menu bar is hidden.

Figure 5: Menu

type FORM_MENU

id Component ID

x,y,w,h (x,y) are the coordinates of the top-left of the form. w and h are automatically calculated,set them to 0.

*text Pointer to the text string which will be shown on the menu.

style Not used, set to 0.


font Any available font, see Table 4 for a listing (FONT_MEDIUM is recommended).

examples See menu item below.



14/88

menu item Menu items are shown in a rectangle when the menu is tapped. In Figure 5 the menuitems are Preference...", Category...", "ViewBy...", "-" and "Reboot". The menu item "-"creates the seperator line whch appears between "ViewBy..." and "Reboot".

type FORM_MENUITEM

id component ID

x,y,w,h x, y, w, h are automatically calculated, set them to 0.

*text Pointer to the text string which will be shown as the menu item when the menu isdisplayed.



font Any available font, see Table 4 for a listing (FONT_MEDIUM is recommended).

examples CAUTION: In a form array menu items must be placed directly after the menu in whichthey are to appear.

The menu and menu items in Figure 5 are defined in the form definition below:

FORM frm[]={...{FORM_MENU, 10, 5, 20, 0, 0, "Option", 0, COMPONENT_VISIBLE,FONT_SMALL}, {FORM_MENUITEM, 11, 0, 0, 0, 0, "Preference...", 0,COMPONENT_VISIBLE, FONT_SMALL}, {FORM_MENUITEM, 12,0, 0, 0, 0,"Category...", 0, COMPONENT_VISIBLE, FONT_SMALL}...{FORM_END}};

button FORM_BUTTON is a standard rectangular button with a string on it.

type FORM_BUTTON

id Component ID

x,y,w,h (x,y) are the coordinates of the top-left of the form. w is width, and h is height

*text Pointer to the string which will be displayed on the button.

style BUTTON_NO_BORDER will suppress the buttons border.





15/88

examples The FORM_BUTTON in Figure 3c was created with the form definition below.

FORM frmMain[]={...{FORM_BUTTON, 40, 20, 20, 40, 20, "Ok!", 0, COMPONENT_VISIBLE,FONT_SMALL},...{FORM_END}};

bitmap Display uncompressed bitmaps.

Bitmaps can be used to implement Owner draw components. The program must handleevents that the component responds to. See Section 3 for details.

type FORM_BITMAP

id Component ID

x,y,w,h (x,y) are the coordinates of the top-left of the form, w is width of the bitmap, and h is height

*text Pointer to the BITMAP structure, defined as follows.

Typedef struct {short width,height; //width and height of the bitmapvoid *img; //location of uncompressed bitmap

//(monochrome or 16 bit color)char *caption; //string that the bitmap can be

//displayed withvoid *mask; //location of monochrome mask for

//transparency, set to NULL if not used}BITMAP;

style BITMAP_COLORIndicates that the bitmap is 16 bit color. IfBITMAP_COLOR is not set it is assumed that

the bitmap is monochrome.

BITMAP_BORDER

Adds a border around the bitmap.

BITMAP_BUTTON

Causes the bitmap to act like a button.

BITMAP_CAPTION_INNER

The bitmaps caption text is shown in the bitmap.

BITMAP_DOTBORDER

Adds a dotted border around the bitmap.

BITMAP_CAPTION_BOTTOMThe bitmaps caption text is shown along the bottom of the bitmap.





16/88

examples #define l_icon_width 32#define l_icon_height 32unsigned char l_icon_bitmap[] = {0x00, 0x00, 0x00, 0x01, 0xFC, 0x00,0x01, 0xFC, ...}; //generated with the bmp2txt toolunsigned char l_icon_bitmap_mask[]={0xFC, 0x00, 0x01, 0xFC, 0x00,

0x01, 0x6C, 0x00, 0x01, 0xFC, 0x00, ...};

static BITMAP large_icon={l_icon_width, l_icon_height,l_icon_bitmap,NULL,l_icon_bitmap_mask};

static FORM frmBasic[]={...{FORM_BITMAP,100,1,40, l_icon_width, l_icon_height,large_icon,BITMAP_COLOR,COMPONENT_VISIBLE,},...{FORM_END}};

check button Displays a check button as shown in Figure 6. When a check mark is in the square the

check button is said to be checked.

Figure 6: Check button

type FORM_CHECKBUTTON

id Component ID

x,y,w,h (x,y) are the coordinates of the top-left of the form. w and h are automatically calculated,set them to 0.

*text Pointer to the CHECKBOX structure, defined as follows.

typedef struct{short value; // 1 for checked and 0 for not checkedvoid *caption; // the caption string to be displayed

// following the checkbox.}CHECKBUTTON;






17/88

examples The check button in Figure 6 was created with the form definition below.

CHECKBUTTON checkbutton = {0,"First Name"};FORM frmMain[]={...{FORM_CHECKBUTTON,10,2,2,40,15,&checkbutton,0,COMPONENT_VISIBLE,FONT_SMALL},...{FORM_END}};

spin button There are two styles of spin button, horizontal and vertical. A horizontal spin buttondisplays a string between two arrows. In Figure 7 the word SPIN and the adjacent arrows,is a horizontal spin button. Vertical spin buttons do not appear in the same style.

Figure 7: Spin button

When the spin button is tapped, the value field of the GUI message generated will return-1 for up or left, and +1 for down or right.

type FORM_SPINBUTTON

id Component ID

x,y,w,h (x,y) are the coordinates of the top-left of the form, w and h are automatically calculated,set them to 0.

*text Pointer to the SPINBUTTON structure, defined as follows.

typedef struct {short spacing; //space to leave between the two arrows.char str[32]; //Text to display between the arrows,

//HSPINBUTTON only.}SPINBUTTON;

style VSPINBUTTON orHSPINBUTTON



examples The FORM_SPINBUTTON in Figure 5 was created with the form definition below.

SPINBUTTON spinbutton={15, "5"};FORM frmMain[]={...{FORM_SPINBUTTON, 10, 90, 30, 0, 0, &spinbutton, HSPINBUTTON,COMPONENT_VISIBLE, FONT_SMALL},...{FORM_END}};



18/88

scroll bar The scroll bar is a vertical bar with an arrow on each end and a grabber as shown inFigure 5. It keeps state information about the position of the grabber

type FORM_SCROLLBAR

id Component ID

x,y,w,h (x,y) are the coordinates of the top-left of the form. w is fixed and should be set to 0. h isthe height.

*text Pointer to the SCROLLBAR structure, defined as follows.

typedef struct{short max, position, page_height;

/* max: The total number of intervals in the scrollbar.Position cannot be greater than max.

position: The current position of the bar. It can bein the range of 0 to max-1.

page_height:This is the amount position will change

when the page is scrolled. The system willadjust the value if it is set to 0 orgreater than max.*/

RECT first_r, second_r, third_r, last_r, button_r;/* reserved for system use.*/

}SCROLLBAR;

style VSCROLLBAR

Vertical scroll bar.

HSCROLLBAR

Horizontal scroll bar.


font Not used, set to 0.

examples The scroll bar in Figure 5 was created with the form definition below.

SCROLLBAR scollbar={10,0,20,};FORM frmMain[]={...{FORM_SCROLLBAR, 50, 230, 15, 0, 280, &scollbar, VSCOLLBAR,COMPONENT_VISIBLE, 0},...{FORM_END}};



19/88

combo box A combo box is a list with the ability to display the currently selected item. The list isdisplayed when the combo box is tapped on. If an item is selected from the list or whenthe user taps out of the component, the list will be closed and the selected item will bereflected in the combo box. When all of the list items cannot be displayed at once, a spinbutton is added automatically for scrolling through the items.

In Figure 8, the combo box with string Basic" has been tapped displaying the full list ofitems .

Figure 8: LEOs Launcher with combo box dropped

type FORM_COMBOBOX

id Component ID

x,y,w,h (x,y) are the coordinates of the top-left of the form. w is width and h is height.

*text Pointer to the COMBOBOX structure, defined as follows.

typedef struct {short index; //item index.char str[32]; //items string value.

}ITEM;typedef struct {

short max_items; // the max items the list can have.short selected; //selected item's location, counting

//from 0. NOT the item's index.short drop_down_width, drop_down_height;

//the listbox size when it is dropedITEM items; //see the structure ITEM above

}COMBOBOX;



20/88

style There are four combo box styles.

COMOBOX_NO_BORDER

Remove the dotted border around the combo box

COMBOBOX_LEFT_ALIGN

Left align the selected stringCOMBOBOX_RIGHT_ALIGN

Right align the selected string.

COMBOBOX_NO_ARROW

Remove the arrow from the combo box.



examples The combo box in Figure 8 was created with the form definition below.

ITEM items[] = {{0, "Basic"}, {1, "Scientific"}, {2, "Financial"},

{3, "Exit"}};COMBOBOX combobox = {10, 0, 40, 60, items};FORM frmMain[]={...{FORM_COMBOBOX, 60, 120, 3, 40, 60, &combobox, 0, COMPONENT_VISIBLE,FONT_SMALL},...{FORM_END}};

text box Text boxes take and display user input

Figure 9: Two text boxes

type FORM_TEXTBOX

id Component ID

x,y,w,h (x,y) are the coordinates of the top left of the form. w is the width of the text box. h isautomatically calculated based on min_empty_lines and visible_lines from the

TEXTBOX structure, and the font used.

Note: Every line of a multiple line text box has the same width.

*text Pointer to the TEXTBOX structure, defined as follows.

typedef struct {short counter_lines; //reserved for system usechar string[TEXTBOX_MAX_CHAR]; //the string shown in

//the textbox;short max_char; //the maximum number of characters

//the textbox can hold.short min_empty_lines; //minimum number of lines to display



21/88

//regardless of the length of string.short start_line; //first line to be shown.short visible_lines; //number of lines to show.

}TEXTBOX;




examples The text box in Figure 9 was created with the form definition below.

TEXTBOX textFirstName = {0, "Toris", 32,1,0, 0};TEXTBOX textLastName = {0,"Chang", 32, 1, 0, 0};FORM frmMain[]={...{FORM_TEXTBOX, 10, 35, 5, 60, 0, &textFirstName, 0,

COMPONENT_VISIBLE, FONT_SMALL},{FORM_TEXTBOX, 20, 35, 25, 60, 0, &textLastName, 0,COMPONENT_VISIBLE, FONT_SMALL},...{FORM_END}};

end The last line of the form definition. This line is necessary.

type FORM_END



22/88

2.4 Form Functions

init_screen

void init_screen(short launch_cmd);Initializes all the devices necessary to run a GUI application.

Normal programs will use init_screen() to initialize the screen for GUI operations

and close_screen() when no more GUI operations are needed, i.e. the program isfinished.

CAUTION: Some API components may not work properly ifinit_screen() is notcalled.

arguments Launch_cmd

Value returned by GetLaunchCommand()

returns None

sample code This sample code demonstrates how to use GetLaunchCommand(), PutAppInfo(),

init_screen(), and close_screen(). int main() calls GetLaunchCommand()

to parse the command line input parameters and uses the returned value to decidebetween run normal or calling PutAppInfo().

int main(int argc, char* argv[]){short launch_cmd;//get the launch commandlaunch_cmd = GetLaunchCommand(argc, argv);init_screen(launch_cmd);switch(launch_cmd){

case CMD_RUN_NORMAL:

wait_loop(); //wait for messages loopbreak;case CMD_RUN_GET_INFO: //for app registration

PutAppInfo(&app_info);break;

}close_screen();return 0;

}

close_screen

void close_screen(void);This function releases GUI related devices.

arguments None

returns Nothing



23/88

sample code See init_screen()

GetLaunchCommand

short GetLaunchCommand(int argc, char *argv[]);This function translates command line parameters passed to the application into alaunch code.

arguments argc, argv

Command line arguments passed into main()

returns The launch code, eitherCMD_RUN_NORMAL orCMD_RUN_GET_INFO

sample code See init_screen()

PutAppInfo

short GetLaunchCommand(int argc, char *argv[]);

This function registers the application's information with the LEOs application database.

arguments app_info

Defined in .rsrc, it is a pointer to the structure APP_INFO. Thestructure contains standard program information needed by the system. Thestructure definition follows.

typedef struct {char nick_name[16]; //applications namechar version[16]; //version string vx.x.xxxchar owner[32]; //company that owns the applicationchar creator[32]; //development team of the applicationBITMAP *large_icon; //32x32 image in hex (see FORM_BITMAP)BITMAP *small_icon; //16x16 image in hex (see FORM_BITMAP)

}APP_INFO;

returns None

sample code See init_screen().

GetIndexFromId

U8 GetIndexFromId(FORM *frm, U8 id);

This function returns the index of the frm array component with the given ID.

arguments frm

Pointer to the form array.

id

ID of the component for which the array index is being found.



24/88

returns The index of the component if found, 0 if the ID doesnt match.

sample code This sample code uses GetIndexFromId() to find the ID of the form array sample

and then draws a rectangle around it.

void sample_play21(short id){short idx;GraphicsContext gc;RECT temp;idx = GetIndexFromId(sample, id);

temp.left = sample[idx].x;temp.right = sample[idx].x + sample[idx].w;temp.top = sample[idx].y;temp.bottom = sample[idx].y + sample[idx].h;gc.color = GUI_BLACK;gc.mode = Mode_SRC;draw_rect(temp, &gc);

};

GetScreenPtr

U8 *GetScreenPtr(void);

This function retrieves the screen pointer. It is often used in functions, such asbitblt().

arguments None

returns A pointer to the screen.

sample code #define BITMAP_WIDTH 16

#define BITMAP_HEIGHT 11

const unsigned char pcBitmapData[] = {0xFF, 0xFF, 0x80, 0x01, 0x8F, 0xF1, 0x80, 0x01, 0x8F, 0xF1, 0x80,0x01, 0x8F, 0xF1, 0x80 , 0x01, 0x8F, 0xF1, 0x80, 0x01, 0xFF, 0xFF};void PaintBitmap(short sPositionX, short sPositionY){

U8 *pcusScreen;GraphicsContext gc;gc.color = GUI_BLACK;gc.mode = Mode_SRC;gc.fill_index = MonochromePattern;pcusScreen = GetScreenPtr();

bitblt(0, 0, BITMAP_WIDTH, BITMAP_HEIGHT, sPositionX,sPositionY, pcBitmapData, PixelsUnitsOld(BITMAP_WIDTH),pcusScreen, SCREEN_WIDTH, &gc);

};

GetScreenHeight

U8 GetScreenHeight(void);



25/88

This function gets the screen height. Using this function can make a program moreportable.

arguments None

returns The height of the screen in pixels.

sample code See PixelInRect

GetScreenWidth

U8 GetScreenWidth(void);

Get the screen width. Using this function can make a program more portable.

arguments none

returns This returns the width of the screen.

sample code See PixelInRect()

SetAvailableRegion

void SetAvailableRegion(RECT *r);

This function specifies the region of the screen to be available for certain operations likedrawing. For example, it can be used to restrict drawing to a specific region of the screenand clip all drawing operations made outside of the region.

CAUTION: Remember to set the available region to {0,0,SCREEN_WIDTH,

SCREEN_HEIGHT} after use because it may affect other forms.

arguments r

The rectangular region functions such as drawing will be restricted to.

returns None



26/88

sample code This program demonstrates how to use SetAvailableRegion(). It tries to draw a line

across the screen after setting the available region to a rectangle in the center. Beforeexiting, it sets the available region back to full screen.

static sample_play28(){RECT temp;temp.left = GetScreenWidth()/2-10;temp.right = GetScreenWidth()/2+10;temp.top = GetScreenHeight()/2-10;temp.bottom = GetScreenHeight()/2+10;SetAvailableRegion(&temp);draw_line(0, 0, GetScreenWidth(), GetScreenHeight(),

GUI_BLACK);temp.left = 0;temp.right = GetScreenWidth();temp.top = 0;temp.bottom = GetScreenHeight();SetAvailableRegion(&temp);

};

MallocScreen

U8 *MallocScreen(U16 w, U16 h);

This function allocates a memory block that can store a screen buffer of the given widthand height. It is strongly recommended to use this for screen operations.

NOTE: Remember to use FreeScreen() when finished with the memory allocated

with MallocScreen().

arguments w, h

Width and height of the screen buffer.

returns A pointer to an allocated screen buffer of the required size. NULL if memory is notavailable.

sample code This sample code demonstrates how to use MallocScreen(), CopyScreen(),

CreateForm(), CloseForm(), PasteScreen(), and FreeScreen(). It first

allocates a block of memory and saves the current screen there. Then, it creates a newwindow and calls the main loop. When it is done, it closes the window, puts the originalscreen back and frees the memory.

static void Sample(void){

U8 *background; //momery block to save backgroundbackground = MallocScreen(SCREEN_WIDTH,SCREEN_HEIGHT);CopyScreen(background, 0, 0, SCREEN_WIDTH, SCREEN_HEIGHT);CreateForm(sample);wait_loop();CloseForm(sample);PasteScreen(background, 0, 0, SCREEN_WIDTH, SCREEN_HEIGHT);FreeScreen(background);

};



27/88

FreeScreen

U8 FreeScreen(U8 *p);

This function frees memory blocks allocated with MallocScreen().

arguments p

Pointer to the memory block to be freed.

returns It returns 0.

sample code See MallocScreen().

CopyScreen

void CopyScreen(U8 *p, U16 x, U16 y, U16 w, U16 h);

This function copies a region of the screen to memory.

arguments pPointer to memory allocated with MallocScreen(). The allocated memory musthave the correct size.

x, yCoordinates of the top-left corner of the screen region to save.

w, h

Width and height of the screen region to save

returns None


PasteScreenvoid PasteScreen(U8 *p, U16 x, U16 y, U16 w, U16 h);

This function pastes the contents ofp to the screen. The contents ofp could be the

result ofCopyScreen() or any other bitmap data in memory.

arguments p

Pointer to image data to be pasted.

x, y

Coordinates of the top-left corner of the screen region to paste to.

w, hWidth and height of the screen region to paste to.

returns None


CreateForm

void CreateForm(FORM *dlg);



28/88

This function draws and initializes all GUI components in the form array. See Section 2.1

for a discussion of the FORM data structure and form arrays.

arguments dlg

The form array to be displayed.

returns None


CloseForm

void CloseForm(FORM *dlg);

This function closes the current form and deactivates all GUI components in the form.

arguments dlg

The form array to be closed.

returns None


HideComponent

void HideComponent(short index, FORM *frm);

This function makes a form component invisible. A component cannot receivemessages while it is invisible.

arguments index

The array index of the component to be hidden.

frm

The form array that contains the component.

returns None

sample code This sample code demonstrates how to use HideComponent() and

ShowComponent(). It hides and then displays a form component.

void sample_play26(){

short idx;idx = GetIndexFromId(sample, BUTTON_SHOW_BITMAP);HideComponent(idx, sample);

Delay();ShowComponent(idx, sample);};

ShowComponent

void ShowComponent(short index, FORM *frm);

This function makes a form component visible.



29/88

arguments index

The array index of the component to be shown.

frm


returns None

sample code See HideComponent().

RefreshComponent

void RefreshComponent(short index, FORM *frm);

This function redraws a specific form component. This is an alternative to redrawingevery component in the form (i.e. with CreateForm()) when the attributes of a singlecomponent have changed.

arguments index

The array index of the component to be refreshed.

frm


returns none

sample code This sample code demonstrates how to use RefreshComponent(). It finds the array

index of a component and then refreshes it..


short idx;idx = GetIndexFromId(sample, BUTTON_SHOW_BITMAP);

RefreshComponent(idx, sample);};

SetSpinButtonText

void SetSpinButtonText(FORM *frm, char *str);

This functions refreshes the text in a horizontal spin button.

arguments frm

Pointer to a form component of type FORM_SPINBUTTON. The component must

have style HSPINBUTTON.

str

The new string to be used in the spin button.

returns None



30/88

sample code This sample code demonstrates SetSpinButtonText(). This code updates the

number displayed when a spin button, displaying a number in the range -99 to 99, istapped.

static sample_play27(short msgvalue){

short i;i = atoi(spinbutton_sample.str) + msgvalue;if((i-100)){

SetSpinButtonText(&sample[GetIndexFromId(sample,SPINBUTTON_SAMPLE)], itoa(i));

}};

RefreshMultiLineString

short RefreshMultiLineString(FORM *txt, short flag);

This function refreshes the content of a label and returns the number of lines needed to

display the text properly.

arguments txt

Pointer to a form component of type FORM_LABEL.

flag

1 to refresh immediately, 0 otherwise.

returns The number of lines needed to display the content.

sample code char szLabelCaption[32];static FORM frmMainFrame[]={{FORM_CAPTION, 0, 0, 0, SCREEN_WIDTH, SCREEN_HEIGHT,&cusFormCaption_MainFrame, FORM_FRAME_CAPTION, COMPONENT_VISIBLE,FONT_SMALL},{FORM_LABEL, LABEL_CONTENT_ID, 20, 100, 100, 40, szLabelCaption,X_ALIGN_LEFT | Y_ALIGN_CENTER | LABEL_BORDER | LABEL_MULTILINE,COMPONENT_VISIBLE, FONT_SMALL},{FORM_END}};

void RefreshDemo(void){

int nIndex;//Get the form array index using the label IDnIndex = GetIndexFromId(frmMainFrame, LABEL_CONTENT_ID);//Update label stringsprintf(szLabelCaption, "Hello World\nLinuxDA");

//refresh the multi-line labelRefreshMultiLineString(&frmMainFrame[nIndex], 1);

};

RefreshTextBoxContents

void RefreshTextBoxContents(FORM *txt, short start_pos, shortend_pos, short flag);



31/88

This function refreshes the string in a text box between the cursor start position and thecursor end position.

arguments txt

Pointer to a form component of type FORM_TEXTBOX.

start_pos, end_pos

Start position and end position of the content to be updated, respectively.

flag

1 to refresh immediately, 0 otherwise.

returns The number of lines required to display the content.

sample code TEXTBOX textbox_Content = {3, "abcdefg\n12345678\nhijklmn", 250, 3,0, 9};

static FORM frmMainFrame[] = {{FORM_CAPTION, 0, 0, 0, SCREEN_WIDTH, SCREEN_HEIGHT,

&cusFormCaption_MainFrame, FORM_FRAME_CAPTION, COMPONENT_VISIBLE,FONT_SMALL},{FORM_TEXTBOX, TEXTBOX_CONTENT_ID, 20, 20, 100, 60,&textbox_Content, 0, COMPONENT_VISIBLE, FONT_SMALL},{FORM_END}};

void RefreshDemo(void){

int nIndex;//Get the form array index using the textbox IDnIndex = GetIndexFromId(frmMainFrame, TEXTBOX_CONTENT_ID);//Update textbox attributestextbox_Content.string[0] = 'A';textbox_Content.string[1] = 'B';

textbox_Content.string[2] = 'C';textbox_Content.string[6] = 'Z';//refresh the textbox and get the number of lines//from textbox object ( system use only)//if the last parameter is 0, it wont refresh the//object. It will only get the number of lines.RefreshTextBoxContents(&frmMainFrame[nIndex], 0, 7, 1);

};

SetTextBoxText

void SetTextBoxText(FORM *txt, char *s);

This function updates a text box with a new string and refreshes immediately.

arguments txt


s

The new text box string.

returns None



32/88

sample code void SetTextBoxTextDemo(char szContent){

int nIndex;//get textbox indexnIndex = GetIndexFromId(frmMainFrame, TEXTBOX_CONTENT_ID);

//Update textbox attributeSetTextBoxText(&frmMainFrame[nIndex] , szContent);

};

GetTextBoxLines

short GetTextBoxLines(FORM *txt);

This function returns the total number of lines in a text box.

arguments txt


returns The total number of lines in the text box.

sample code void ShowTextBoxLineCount(U8 TextBoxID){

int nIndex;int nTextBoxLineCount = 0;char szMessage[32];

nIndex = GetIndexFromId(frmMainFrame, TextBoxID);nTextBoxLineCount = GetTextBoxLines();

sprintf(szMessage, "TextBox Lines : %d ", nTextBoxLineCount);MsgBox(szMessage, "LinuxDA", MB_OK);

};

SetTextBoxStartLine

void SetTextBoxStartLine(FORM *txt, short line);

This function sets the first line to be displayed in a text box.

arguments txt


line

Line number of first line to be displayed in the text box.

returns none



33/88

sample code void ScrollTextBoxDemo(int nStartPosition){

int nIndex;nIndex = GetIndexFromId(frmMainFrame, TEXTBOX_CONTENT_ID);

// Update textbox attributeSetTextBoxStartLine(&frmMainFrame[nIndex], nStartPosition);

// Refresh textboxRefreshComponent(nIndex, frmMainFrame);

// After refreshing the textbox, SetFocus is requiredSetFocus(frmMainFrame , TEXTBOX_CONTENT_ID);

};

SetTextBoxEndLine

void SetTextBoxEndLine(FORM *txt, short line);

This function sets the last line to be displayed in a text box.

arguments txt

Pointer to a form component of type FORM_TEXTBOX

line

Line number of last line to be displayed in the text box.

returns none

sample code void SetTextBoxVisibleLinesDemo(int nVisibleLines){

int nIndex;

nIndex = GetIndexFromId(frmMainFrame, TEXTBOX_CONTENT_ID);//Update textbox attributeSetTextBoxEndLine(&frmMainFrame[nIndex], nVisibleLines);//Refresh textboxRefreshComponent(nIndex , frmMainFrame);

};

SetTextBoxEmptyLines

void SetTextBoxEmptyLines(FORM *txt, short line);

This function sets the minimum number of lines the text box will display.

arguments txt


line

Minimum number of lines to be displayed in the text box.

returns None



34/88

sample code void SetTextBoxEmptyLinesDemo(int nEmptyLines){

int nIndex;nIndex = GetIndexFromId(frmMainFrame, TEXTBOX_CONTENT_ID);//Update textbox attribute

SetTextBoxEmptyLines(&frmMainFrame[nIndex], nEmptyLines);//Refresh textboxRefreshComponent(nIndex, frmMainFrame);

};

SetFocus

void SetFocus(FORM *frm, short id);

This function sets the focus to the text box with a given ID.

arguments frm


idID of the component.

returns None

sample code See SetTextBoxStartLine().

GetCurrentActivatedTextBox

short GetCurrentActivatedTextBox(void);

Return the ID of the active text box, 0 if there is no text box selected.

arguments None

returns Text box ID on success and 0 if none is selected.

sample code

PixelInRect

U8 PixelInRect(PIXEL px, RECT r);

This function checks if a pixel's coordinates lie within a rectangular region. Return valueis 1 if yes, 0 if no.

arguments px

Pixel the system will check.r

Rectangular region.

returns 1 if the pixel is within the rectangle and 0 if it is not.



35/88

sample code This sample code demonstrates how to use GetScreenWidth(),

GetScreenHeight(), PixelInRect(), and xor_draw_line(). If the pixel is

within the rectangle, fill the square, otherwise draw a diagonal line.

void sample_play22(PIXEL px)

{ RECT temp;GraphicsContext gc;temp.left = GetScreenWidth()/2-10;temp.right = GetScreenWidth()/2+10;temp.top = GetScreenHeight()/2-10;temp.bottom = GetScreenHeight()/2+10;gc.color = GUI_BLACK;gc.mode = Mode_SRC;gc.fill_index = BlackPattern;if(PixelInRect(px,temp)==1)

FillRect(temp,&gc);else

xor_draw_line(temp.left, temp.top, temp.right,

temp.bottom);};

SendKeyToForm

void SendKeyToForm(FORM *frm, U16 code);

Send an ASCII character to a form component, usually to text box, for input.

arguments frm

The form array the character is being sent to.

code

ASCII character code.

returns None

sample code void AddCharToTextBox(int nCharCode){

SendKeyToForm(frmMainFrame , nCharCode);};



36/88

3 GUI Message API

3.1 GUI_ MSG Data Structure

Table 6: GUI_MSG data structure

{id, event, lParam, keycode, value} gui.h

Form identification number U8id

The ID of the form component the message is associated with.

The message type. U16event

For example click or pen up. There are currently 9 GUI message types defined in theLEOs API. For more information, see the GUI message type reference, 3.2.

Message type specific parameter. U32lParam

Typically, lParam contains the coordinates where the event took place,

x=hibyte(lParam), y=lobyte(lParam).

Hardware button keycode. U8keycode

When a hardware button is pressed, generic hardware button events are generated.This element indicates which button was used.

Form component specific value. shortvalue

The value is dependant on the type of form the event was generated from. For a spin

button the value will be 1 or 1 depending on the arrow tapped. ForEVENT_INPUTCHAR, it is the change in the number of lines contained in the text box.

Note: U8, U16, and U32 are defined in gui.h. They are currently equivalent to unsigned char, unsigned shortand unsigned long, respectively.

3.2 GUI Message Types

nothing No event occurred.

event type EVENT_NOTHING

id Not used.

lParam Not used.

keycode Not used.

value Not used.



37/88

click This event is generated continuously while the pen is in contact with the touchscreen.

CAUTION: A single tap on the screen may trigger this event more than once.

event type EVENT_CLICK

id ID of the form component at the screen position where the tap occurred.

lParam (x, y) coordinates of the pen on the screen where x=hibyte(lParam), and

y=lobyte(lParam).

keycode Not used.

value Form component specific. See the form component reference, Section 2.3, for details.

inputcharacter

This event is generated when the user leaves the soft keyboard form or the magic penform after completing changes to a text box.

event typeEVENT_INPUTCHAR

id Identification number of the text box that was edited.

lParam Not used.

keycode Not used.

value The change in the number of lines of text contained in a text box, i.e. old line count newline count.

key down This event is generated when a hardware button is pressed.

event type EVENT_KEYDOWN

id Not used.

lParam Not used.

keycode A value corresponding to the hardware button pressed. See Figure 10 below for possiblekeycode values.

Error! Objects cannot be created from editing field codes.

Figure 10: Hardware switch key codes

Note: The key code constants are defined in gui.h.

value Not used.

key up This event is generated when a hardware button is released.

event type EVENT_KEYUP

id Not used.



38/88

lParam Not used.

keycode A value corresponding to the hardware button released, see Figure 10 for details.

value Not used.

pen up This event is generated when the pen is removed from the touchscreen.

event type EVENT_PENUP

id Identification number of the form component at the screen position where the pen lasttouched the screen.

lParam (x, y) coordinates of the pen on the screen where x=hibyte(lParam), and

y=lobyte(lParam).

keycode Not used.

value Not used.

show menubar

This event is generated when the menu bar is shown.

event type EVENT_SHOW_MENUBAR

id Not used.

lParam Not used.

keycode Not used.

value Not used.

hide menubar

This event is generated when the menu bar is hidden.

event type EVENT_HIDE_MENUBAR

id Not used.

lParam Not used.

keycode Not used.

value Not used.



39/88

3.3 GUI Message Functions

ClearMessageQueue

void ClearMessageQueue(void);

This function clears the message queue. It is common to clear the message queue whena new form is created to eliminate stale messages for an old form.

arguments None

returns None

sample code This sample code demonstrates how to use ClearMessageQueue(),

GetMessage(), and DefaultMessageRoutine(). It first clears the message queue.

Then, it goes into the main loop and uses GetMessage() to retrieve new messages forthe form. Messages are passed into the switch statement to find the correspondingaction. If a message is not processed in the switch statement, it is passed to

DefaultMessageRoutine() so that the system can process it.

static void wait_loop(){

U8 loopFlag = 1;PIXEL px;GUI_MSG msg;short i = 0;ClearMessageQueue();while (loopFlag) {

GetMessage(sample, &msg);px.x = hibyte(msg.lParam);px.y = lobyte(msg.lParam);switch (msg.event) {

case EVENT_CLICK:switch (msg.id) {

case MENUITEM_MAIN_EXIT:loopFlag = 0;break;

case BUTTON_MAIN_PLAY://sample action BUTTON_MAIN_PLAY is pressed.sample_play20();break;

default: DefaultMessageRoutine(sample, &msg);}break;

default: DefaultMessageRoutine(sample,&msg);

}}};

GetMessage

void GetMessage(FORM *frm, GUI_MSG *msg);

This function retrieves messages for a form from the queue.



40/88

arguments frm

The form array requesting a message to process.

msg

Location to store the retrieved message, see 3.1 for the GUI message datastructure.

returns None

sample code See ClearMessageQueue().

DefaultMessageRoutine

void DefaultMessageRoutine(FORM *dlg, GUI_MSG *msg);

Passes messages not processed by the application back to the system.

CAUTION: Messages must be returned to the system if and only if they are notprocessed by the application.

arguments dlgThe form array which received, but did not process the message.

msg

Pointer to the unprocessed message.

returns None

sample code See ClearMessageQueue().

SendMessage

void SendMessage(GUI_MSG *msg)

This function puts a message onto the message queue.

arguments msg

Pointer to the message to be added to the queue.

returns None

sample code This program demonstrates how to use SendMessage(). The message sent emulatesan EVENT_CLICK event on a menu.


GUI_MSG exit_msg;exit_msg.event = EVENT_CLICK;exit_msg.id = MENUITEM_MAIN_EXIT;SendMessage(&exit_msg);

};



41/88

4 Draw API

4.1 Draw Structures and Constants

Table 7: PIXEL data structure

{x, y} gui.h

x, y The coordinates of a pixel. short

Table 8: RECT data structure

{left, top, right, bottom} gui.h

left,top The (x, y) coordinates of the rectangle's top left corner. short

right,bottom The (x, y) coordinates of the rectangle's bottom right corner short

Table 9: Color data structure

{R, G, B} gui.h

A colors red, green, and blue values, respectively. U8R, G, B

Several colors have been predefined for convenience.

static const Color GUI_WHITE={255,255,255};static const Color GUI_BLACK={0,0,0};static const Color GUI_RED={255,0,0};

static const Color GUI_GREEN={0,255,0};static const Color GUI_BLUE={0,0,255};static const Color GUI_PURPLE={255,0,255};static const Color GUI_YELLOW ={255,255,0};

Note: U8 is defined in gui.h. It is currently equivalent to unsigned char.



42/88

Table 10: GraphicsContext data structure

{color, mode, fill_index} gui.h

Color to be used by the drawing function. Colorcolor

The (R,G,B) value to be used by the function. For example, the color of the ellipse

drawn by draw_ellipse().

Logical operation to be applied when copying or pasting. CopyModemode

Primarily used in the drawing function, bitblt(). SRC indicates the source bitmap

and DST indicates the destination bitmap. For modes that use multiple logical

operators, NOT takes precedence. The operators are otherwise self explanatory.

typedef enum { Mode_SRC, Mode_NOT_SRC, Mode_SRC_OR_DST,Mode_SRC_AND_DST, Mode_SRC_XOR_DST,Mode_SRC_OR_NOT_DST, Mode_SRC_AND_NOT_DST,

Mode_SRC_XOR_NOT_DST, Mode_NOT_SRC_OR_DST,Mode_NOT_SRC_AND_DST, Mode_NOT_SRC_XOR_DST,Mode_NOT_SRC_OR_NOT_DST, Mode_NOT_SRC_AND_NOT_DST,Mode_NOT_SRC_XOR_NOT_DST, InvalidMode

} CopyMode;

Identifying number. PatternIndexfill_index

typedef enum {WhitePattern = 0,BlackPattern, DarkGreyPattern,LightGreyPattern, MicroPengPattern,HoriDotPattern, VertDotPattern,InvalidPattern, MonochromePattern

} PatternIndex;

Table 11: Pattern data structure

{height, data} gui.h

The pattern's y dimension, or height, in pixels. Patterns aremonochrome and their width is always 8 pixels.

U16height

Data is an array of 8 bit elements. Each element represents a row

of monochrome pixel values.

U8data

Note: U8 and U16 are defined in gui.h. They are currently equivalent to unsigned char and unsigned shortrespectively.



43/88


44/88

4.2 Draw Functions

draw_pixel

void draw_pixel (U16 x, U16 y, Color color1)

This function draws a colored pixel at the specified coordinates.

arguments x,y

Coordinates of the pixel to be drawn.

color

Color of the pixel to be drawn.

returns None

sample code This sample code demonstrates how to use draw_pixel(), draw_line(),

xor_draw_line(), and draw_ellipse().

void sample_play23(PIXEL px){

GraphicsContext gc;short idx;short x, y, x1, y1, x2, y2;gc.color = GUI_BLACK;gc.mode = Mode_SRC;gc.fill_index = BlackPattern;idx = GetIndexFromId(sample, BITMAP_MAIN);x = sample[idx].x+sample[idx].w/2;y = sample[idx].y+sample[idx].h/2;draw_pixel(x, y, gc.color);x1 = sample[idx].x;y1 = sample[idx].y;x2 = sample[idx].x + sample[idx].w;y2 = sample[idx].y;draw_line(x1, y1, x2, y2, gc.color);xor_draw_line(y1, x1, y2, x2);draw_ellipse(x, y, sample[idx].w/2, sample[idx].h/2, &gc);

};

draw_line

void draw_line(short x1, short y1, short x2, short y2, Color color);

This function draws a colored line from the first set of coordinates to the second set ofcoordinates.

arguments x1, y1

Coordinates of the start point.

x2, y2

Coordinates of the end point.

color

Line color.



45/88

returns None

sample code See draw_pixel().

xor_draw_line

void xor_draw_line(short x1, short y1,short x2, short y2);

This function inverts the pixels along a line from the first set of coordinates to the secondset of coordinates.

arguments x1, y1

Coordinates of the start point.

x2, y2

Coordinates of the end point.

returns None


draw_ellipse

void draw_ellipse(short x, short y, short a, short b,GraphicsContext *gc);

This function draws a colored ellipse centered at (x, y) with long axis a and short axis b.

arguments x, y

Coordinates of the center of the ellipse.

a

Dimension of the long axis of the ellipse.

b Dimension of the short axis of the ellipse.

returns None


bitblt

void bitblt(short src_x, short src_y, short w, short h, short dest_x,short dest_y, U8 *src, short src_units_per_line, U8 *dest, shortdest_units_per_line, GraphicsContext *gc);

This function performs logical operations comparing a source and destination image.

The result is stored in the destination memory location.



46/88

arguments src_x, src_y

Coordinates of the top left corner of the source image.

w, h

Width and height of the source image, in pixels.

dest_x, dest_yCoordinates of the top left corner of the destination image.

src

Pointer to the source image data.

src_units_per_line

Width of source image in bytes (i.e. is the image color or monochrome).

dest

Pointer to the destination image data.

dest_units_per_line

Width of destination image in bytes (i.e. is the image color or monochrome).

gc

See Table 10 for the GraphicsContext data structure.

gc->color

Not used.

gc->CopyMode

The logical operation to be performed between source and destination.

gc->fill_index

MonochromePattern ifsrc is monochrome.

CAUTION: When drawing only parts of the source image, src_units_per_line hasto be equal to the width of the entire source image in bytes. For example, when drawing

an 8x8 portion of a 16x16 source image src_units_per_line is still equal to

PixelsUnits(16).

returns None



47/88

sample code This sample code demonstrates bitblt() and PixelsUnits(). It displays a bitmap

image.


short idx;GraphicsContext gc;idx = GetIndexFromId(sample, BUTTON_SHOW_BITMAP);gc.color = GUI_BLACK;gc.mode = Mode_SRC;gc.fill_index = BlackPattern;bitblt(0, 0, smilie_oops_bmp.width, smilie_oops_bmp.height,

sample[idx].x+1, sample[idx].y+1, smilie_oops_bmp.img,PixelsUnits(smilie_oops_bmp.width), GetScreenPtr(),SCREEN_LINE_BYTES, &gc);

idx = GetIndexFromId(sample, BUTTON_SHOW_MONO_BITMAP);gc.color = GUI_BLACK;gc.mode = Mode_SRC;

gc.fill_index = MonochromePattern;bitblt(0, 0, smilie_mono_bmp.width, smilie_mono_bmp.height,

sample[idx].x+1, sample[idx].y+1, smilie_mono_bmp.img,PixelsUnitsOld(smilie_mono_bmp.width), GetScreenPtr(),SCREEN_LINE_BYTES, &gc);};

PixelsUnits

U8 PixelsUnits(short pxs);

Find the number of bytes required to store a certain number of 16bit color bitmap pixels.

arguments pxsNumber of 16bit color bitmap pixels.

returns Number of bytes.

sample code See bitblt().

PixelsUnitsOld

U8 PixelsUnitsOld(short pxs);

Find the number of bytes required to store a certain number of monochrome bitmappixels.

arguments pxsNumber of monochrome bitmap pixels.

returns Number of bytes.

sample code See bitblt().



48/88

patternfill

void patternfill(short dest_x, short dest_y, short w, short h, U8*dest, short dest_units_per_line, GraphicsContext *gc);

This function fills a rectangular region with a pre-defined monochrome pattern or a solid

color.

arguments dest_x, dest_y

Coordinates of the top left corner of destination image.

w, h

Width and height of the destination image in pixels.

dest

Pointer to the destination image data.

dest_units_per_line

Width of destination image in bytes (i.e. is the image color or monochrome).

gc

Graphics Context.gc->fill_index

One of the pattern constants defined in Table 11. Ifgc->fill_index =

InvalidPattern, the region will be filled with gc->color

CAUTION: dest_units_per_line is not equal to PixelsUnits(w) ifw is only afraction of the total width of the whole image.

returns None

sample code void FillPatternDemo(void){

GraphicsContext gc;

Rect r;U8 *pcusScreen = GetScreenPtr();gc.mode = Mode_SRC;gc.fill_index = DarkGreyPattern;//width in this case does not equal the total//width of the imagepatternfill(16, 120, 24, 24, pcusScreen,

PixelsUnits(SCREEN_WIDTH), &gc);gc.fill_index = InvalidPattern;gc.color = GUI_RED;r.left=10; r.right=200;r.top=50; r.bottom=200;FillRect(r,&gc);gc.color=GUI_BLUE;

r.left-=5; r.right+=5;r.top-=5; r.bottom+=5;draw_rect(r,&gc);

};

FillRect

void FillRect(RECT r, GraphicsContext *gc);



49/88

This function is a simpler version ofpatternfill() that can only draw onto the

screen.

arguments r

A rectangular region of the screen.

gc

Graphics Context.

gc->fill_index

One of the pattern constants defined in Table 11. Ifgc->fill_index =

InvalidPattern, the region will be filled with gc->color

returns None

sample code See patternfill().

draw_rect

void draw_rect(RECT r,GraphicsContext *gc);

This function draws a colored rectangle.

arguments r

A rectangular region of the screen.

gc

Graphics Context.

gc->color

The rectangles color.

returns None

sample code See patternfill().

XorButtonFace

void XorButtonFace(RECT r);

This function inverts the pixels in a rectangular region of the screen.

arguments r

The rectangular region to invert

returns None

sample code



50/88

5 Text Functions

GetStringWidth

U16 GetStringWidth(char *str, short font_lib)

This function returns the width of a string in pixels when displayed using the specifiedfont.

arguments str

The string to be measured.

font_lib

The font the string is drawn in.

returns The string width in pixels.

sample code #define MAP_WIDTH 150#define MAP_HEIGHT 110

void ShowWelcome(char *szWelcomeInfo){

int nPositionX;int nPositionY;GraphicsContext gc;//Display the welcome informationgc.color = GUI_BLACK;gc.mode = Mode_SRC;gc.fill_index = WhitePattern;

nPositionX = (MAP_WIDTH - GetStringWidth(szWelcomeInfo,FONT_SMALL)) / 2;

nPositionY = MAP_HEIGHT / 2;

do_drawString(nPositionX, nPositionY, szWelcomeInfo, &gc,FONT_SMALL);};

GetFontHeight

U16 GetFontHeight(void)

This function returns the current font height in pixels.

arguments None

returns The current font height in pixels.



51/88

sample code static void ShowFontInfo(short nIndex){

short sFontHeight;char szMessage[32];SetFont(FONT_SYS);

sFontHeight = GetFontHeight();sprintf(szMessage, "System Font Height : %d ", sFontHeight);MsgBox(szMessage, "LinuxDA", MB_OK);

};

SetFont

void SetFont(Short font_lib)

This function sets the default font.

arguments font_lib

One of the available fonts, see Table 4.

returns None

sample code See GetFontHeight().

do_drawString

void do_drawString(int x, int y, char *data, GraphicsContext *gc,short font_lib);

This function displays a string at the specified coordinates and in the specified font.

Note: This function changes the default font to font_lib.

arguments x, y

Coordinates of the top left corner of the text to be displayed.

data

The string to be displayed

gc->mode

Logical operation to perform between the pixels of the string being written and the

existing screen pixels. The other elements ofgc are not used.

font_lib

One of the available fonts, see Table 4.This will become the default font.

returns None

sample code See GetStringWidth().

DrawStringInRect

void DrawStringInRect(RECT *r, char *str, GraphicsContext *gc,short font_lib, short align_flag);

This function displays a string in a rectangular area. Content which does not fit will becropped.

Note: This function changes the default font to font_lib.



52/88

arguments r

Rectangular region where the string will be displayed.

str

The string to be displayed

gc->modeLogical operation to perform between the pixels of the string being written and theexisting screen pixels. The other elements ofgc are not used.

font_lib

One of the available fonts, see Table 4.This will become the default font.

align_flag

One of the available alignment methods, see Table 5.

returns None

sample code void DisplaySomething(char szMessage){

RECT rectRange;GraphicsContext gc;//set up the arearectRange.top = 10;rectRange.left = 10;rectRange.bottom = rectRange.top + 100;rectRange.right = rectRange.left + 100;//set up some attributesgc.mode = Mode_SRC;gc.color = GUI_BLACK;//call the function to display the stringDrawStringInRect(&rectRange, szMessage, &gc, FONT_SMALL,

Y_ALIGN_CENTER | X_ALIGN_MIDDLE);};



53/88

6 Database API

6.1 Database Structures and Constants

Table 13: General definitions

Constant Description

MAX_FILENAME_LENGTH The maximum file name length. Currently set at 16 characters.

DB_SHOW_SECURITY One of two possible security modes for the database. Allows all recordsto be accessed regardless of their security property.

DB_HIDE_SECURITY One of two possible security modes for the database. Restricts access torecords with the DB_RECORD_SECURITY property.

Note: These constants are defined in mini_db.h..

Table 14: Database record properties

Constant Description

DB_RECORD_SECURITY If the database's security mode is DB_HIDE_SECURITY, records withthis property cannot be retrieved.

DB_RECORD_DELETED Indicates that the record will be deleted from the datebase on the nextsynchronization.

DB_RECORD_UPDATED Indicates that the record is going to be updated during the nextsynchronization.

Note: These constants are defined in mini_db.h.



54/88

Table 15: DBFIELD structure

{field_name, field_length, field_type} mini_db.h

Database field name charfield_name

Field names can not be longer than MAX_FILENAME_LENGTH.

Database field length. shortfield_length

Database field type. shortfield_type

DBCHAR

The field will be used to store a single character.

DBINT

The field will be used to store an integer.DBLONG

The field will be used to store a long integer.

DBDATE

The field will be used to store a date.

DBTIME

The field will be used to store a time.

DBSTRING

The field will be used to store a fixed size character array.

DBBINARY

The field will be used to store a binary value.

DBVARCHAR

The field will be used to store a variable length string, terminated with \0.

6.2 Database Functions

Note: DBHANDLE is defined in mini_db.h. It is equivalent to int.

LDACreateDB

int LDACreateDB(char *DBName, short DBFlags, DBFIELD *dbField,short dbFieldNumber);

This function creates a new database.



55/88

arguments DBName

Database name string, size must be less than MAX_FILENAME_LENGTH.

DBFlags

0 to create a new database orDB_SET_OVERWRITE to overwrite an existing

database with the same name.dbField

The DBFIELD array, which contains all of the fields in the database.

dbFieldNumber

Size of the array dbField.

returns 0 on success, 1 on error.

sample code #define FIELD1 "field1"#define FIELD2 "field3"#define DBNAME "database1"

#include

DBFIELD field_descriptions[]={{FIELD1,25,DBSTRING},{FIELD2,25,DBSTRING},

};

static void OpenTaskDB(void){

short idx;short i,j;//Create the Task database with 3 categoriesg_db_handle = LDAOpenDB(DBNAME,0);if (CheckOpen(g_db_handle) == -1){

//Task database does not exist, so create it.LDACreateDB(DBNAME, DB_SET_OVERWRITE, field_descriptions,

sizeof(field_descriptions)/sizeof(DBFIELD));taskDBHandle = LDAOpenDB(DBNAME,0);LDAAddDBCategory(&g_db_handle, CATEGORY_TYPE_BUSINESS);LDAAddDBCategory(&g_db_handle, CATEGORY_TYPE_PERSONAL);LDAAddDBCategory(&g_db_handle, CATEGORY_TYPE_UNFILED);

};

LDAAddDBCategory

int LDAAddDBCategory(DBHANDLE *dbhandle, char *cate_name);

This function adds a category to the database. A database can have a maximum of 16categories.

Note: A category is different from a field. Each record can have many fields but it canonly belong to one category.



56/88

arguments dbhandle

Pointer to a database's handle.

cate_name

Category name string.

returns The category ID on success, 1 on error.

sample code See LDACreateDB().

LDADeleteDBCategory

int LDADeleteDBCategory(DBHANDLE *dbhandle, int cate_index);

This function deletes a category from a database. All records that belonged to thedeleted category will belong to category 0.

arguments dbhandle

Pointer to a database's handle.

cate_indexCategory ID


sample code //Delete the category "Personal"g_cate_index = LDAAddDBCategory(g_db_handle, "Personal");LDADeleteDBCategory(g_db_handle, g_cate_index);

LDAUpdateDBCategory

int LDAUpdateDBCategory(DBHANDLE *dbhandle, int cate_index, char*cate_name);

This function changes the name of the category with the given category ID.

arguments dbhandle

Pointer to a database's handle

cate_index

Category ID

cate_name

New category name string.


sample code //Change the category name from "Personal" to "Business"

g_cate_index = LDAAddDBCategory(g_db_handle, "Personal");LDAUpdateDBCategory(g_db_handle, g_cate_index, "Business");

LDAGetDBCategoryTotal

int LDAGetDBCategoryTotal(DBHANDLE *dbhandle);

This function returns the total number of categories in the database.



57/88

arguments dbhandle


returns The number of categories on success, 1 on error.

sample code See LDAGetDBCategoryAlphbet().

LDAGetDBCategoryAlphbet

int LDAGetDBCategoryAlphbet(DBHANDLE *dbhandle, int cate_rank,char *cate_name);

This function returns the ID of the category with the given alphabetical rank. It alsooverwrites cate_name with the name of the category with the given alphabetical rank.

arguments dbhandle


cate_rank

Rank of a category, alphabetically. Not the category ID.

cate_name

Buffer to store category name, if found.


sample code if (CheckOpen(g_db_handle) == -1){// database was opened successfully

//Get the total number of categoriesg_cate_total = LDAGetDBCategoryTotal(g_db_handle);for(i = 0;i < g_cate_total;i++){

g_cate_id[i] = LDAGetDBCategoryAlphbet(g_db_handle, i,g_cate_str[i]);

}};

LDAOpenDB

DBHANDLE LDAOpenDB(char *DBName, short DBFlag);

This function opens the named database.

arguments DBName

Name string of database to be opened.

DBFlag

DB_READ_ONLY to open the database in read only mode orDB_EXCLUSIVE toopen the database in exclusive mode.

returns The database handle on success, 1 on error.

sample code See LDACreateDB().



58/88

LDADeleteDB

int LDADeleteDB(char *DBName);

This function deletes the named database.

arguments DBName

Name string of database to be deleted.


sample code #define DBNAME database1"#include

static void DeleteDB(void){

DBHANDLE g_db_handle;g_db_handle = LDAOpenDB(DBNAME,0);if (CheckOpen(g_db_handle) == -1){

// open database sucessfullyLDACloseDB(g_db_handle,0);LDADeleteDB(DBNAME);

}};

LDACloseDB

int LDACloseDB(DBHANDLE dbhandle, short flag);

Closes the indicated database.

arguments dbhandle

Database handle of an open database.flag

reserved, not currently in use.

returns 0 on success, 1 on.

sample code See LDADeleteDB().

LDASetDBCategory

int LDASetDBCategory(DBHANDLE *dbhandle, char cate_option);

This function sets the current category of the database.

Note: Record retrieval operations ignore records which are not in the current category.

arguments dbhandle

Pointer to the database handle.

cate_option

DB_CATEGORY_ALL to access all records, or a category ID to restrict access to thespecified category.



59/88


sample code See LDAGetRecordNumber().

LDASetDBSecurity

int LDASetDBSecurity(DBHANDLE dbhandle, char secu_option);

This function sets the database security mode. Depending on the mode, records with

the security attribute DB_RECORD_SECURITY may be hidden from functions like

LDAGetRecord().

arguments dbhandledatabase handle

secu_option

DB_SHOW_SECURITY orDB_HIDE_SECURITY.

When set to DB_HIDE_SECURITY, records with the security attribute,

DB_RECORD_SECURITY, cannot be retrieved. When set to DB_SHOW_SECURITY,all records are available.


sample code See LDAGetRecordNumber().

LDA

leos software development manual - volume 2 api

Documents