LEOs Software Development Manual - Volume 2 API

D E V E L O P M E N T
K I T
LEOs Software Development Manual Volume 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 Mark Institute, the exclusive licensee of Linus Torvalds, owner of the mark on a world-wide basis. LinuxDA and LEOs are trademarks of Empower Technologies, Inc. OMAP is a registered trademark of Texas Instruments. All other trademarks are the property of their respective owners.
Table of Contents
1 2 2.1 2.2 2.3 2.4 3 3.1 3.2 3.3 4 4.1 4.2 5 6 6.1 6.2 7 8 9 Introduction ...........................................................................................................................................1 Form API ................................................................................................................................................3 FORM Data Structure...........................................................................................................................3 Form Constants ....................................................................................................................................6 Form Components................................................................................................................................9 Form Functions...................................................................................................................................20 GUI Message API.................................................................................................................................34 GUI_ MSG Data Structure..................................................................................................................34 GUI Message Types...........................................................................................................................34 GUI Message Functions .....................................................................................................................37 Draw API ..............................................................................................................................................39 Draw Structures and Constants .........................................................................................................39 Draw Functions...................................................................................................................................42 Text Functions.....................................................................................................................................48 Database API .......................................................................................................................................51 Database Structures and Constants ..................................................................................................51 Database Functions............................................................................................................................52 Communication Functions.................................................................................................................63 Camera Functions...............................................................................................................................66 Sound API ............................................................................................................................................69
10 Other Functions ..................................................................................................................................71 11 Sample Programs................................................................................................................................76 11.1 Sample Program 1..............................................................................................................................76 11.2 Sample Program 2..............................................................................................................................77 11.3 Sample Program 3..............................................................................................................................78 11.4 Sample Program 4..............................................................................................................................79 11.5 Sample Program 5..............................................................................................................................81 11.6 Sample Program 6..............................................................................................................................82 11.7 Sample Program 7..............................................................................................................................83 11.8 Sample Program 8..............................................................................................................................84 11.9 Sample Program 9..............................................................................................................................85 11.10Sample Wav Demonstration...............................................................................................................86
Introduction
The LinuxDA Embedded Operating System (LEOs) Application Program Interface (API) is designed to make developing applications for the LDK5910 EVM straight forward and efficient. This manual contains a brief tutorial and complete command reference for the LEOs API. More information about developing applications, including the basic code structure, instructions for working with the compiler and directions for how to rapidly test and deploy new applications for the LDK5910 EVM can be found in the LEOs Software Development Manual Volume 1: SDK. LEOs applications are mostly single-threaded programs. An application will usually display a screen and then poll the operating system for graphic user interface messages (GUI messages) in a message processing loop. The screen itself is a form, as are all other components the GUI provides, like buttons, scroll bars and text boxes. 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 in Section 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 the message queue. The applications message processing loop requests messages, one at a time, from the front of the queue and processes them. Messages received by the application which cannot be handled properly 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 from the 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 <program file>.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 form components 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. Section 9 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 which can help new developers get up and running as fast as possible.
Launch Application Send App. Information Send Info. Launch Command Run Normal Initialize GUI& Create form Get GUI Message Incorrect Message Destination Correct Process Message No Time To Quit? Yes Close GUI Return Msg. To System
Exit
Figure 1: Typical Application Organization
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 position of 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 a caption with the text Sample3" which fills the screen and 14 other form components. Only 9 of the components are visible in the screenshot. The LEOs taskbar is also visible, but it is not part of the form array. The taskbar is attached by the system when a program is executed.
Label Text Box Bitmap Check Button Button Combo Box Button Spin Button Scroll Bar LEOs Taskbar
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 member of the FORM data structure.
Table 1: FORM data structure {type, id, x, y, w, h, *text, style, status, font} type The component type. gui.h U8
For example, caption, button, or label. There are currently 13 form components defined in the LEOs API. For a quick list, see Table 5. For details about a specific component, see the form component reference in 2.3. id Identifying number (ID). 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. x, y Form component position. U16, U16 U8
The horizontal and vertical coordinates of the upper left hand corner of the form component, respectively. The position of some components is automatically calculated, so x or y may not be used. When not in use, set x or y to 0. w, h Form component size. U16, U16
The width and height of the form component, respectively. The size of some elements is automatically calculated, so w or h may not be used. When not in use, set w or y to 0. *text Pointer to a component specific structure void
For certain components, like buttons and menus, this is a pointer to the text string displayed. For other components, this is a pointer to a type specific structure with more information about the form to be displayed. A quick listing of component specific structures is included in Table 5. Detailed descriptions are included under appropriate entries of the form component reference in 2.3. style Component specific style. U8
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 of available styles, see Table 5. Descriptions of component specific styles are included under appropriate entries of the form component reference in 2.3. status Visibility of component. U8
Any component can be made either visible or invisible. See Table 3 for all available status values. font Text size. U8
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.
The screenshot in Figure 2 can be generated with the following form array declaration. Table 2: Sample form array static FORM frmSample[]={ Declaration of frmSample, 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 not handle any messages. The caption takes up the whole screen, from the top left corner (0,0), to the bottom 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 taps on 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 the menu 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 will appear automatically and the user can enter text. When the user leaves the soft keyboard, the GUI message EVENT_INPUTCHAR is generated indicating that the text box has changed.
{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 the text 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 manually within 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 stored uncompressed in an array. Often, as in sample program 3, the bitmap data is included directly within the array declaration at the beginning of <program name>.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, an EVENT_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 COMPONENT_INVISIBLE
MENU_DROPPED MENU_UNDROPPED
Note: Component status values can be used with all form components. By convention the values with the MENU_ prefix are only used with menu components. In practice, they are synonymous with the COMPONENT_ prefixed values. Note: Constants are defined in gui.h. Table 4: Form font constants Font FONT_SYS FONT_SMALL FONT_BOLD Note: Constants are defined in gui.h. Height 13 13 21 Font FONT_MEDIUM FONT_LARGE Height 15 21
Table 5: Component specific form constants and data types Form Component FORM_CAPTION Applicable Styles FORM_FRAME_CAPTION FORM_FRAME_BORDER FORM_SAVEBEHIND FORM_DLGFRAME X_ALIGN_LEFT X_ALIGN_MIDDLE X_ALIGN_RIGHT Y_ALIGN_TOP Y_ALIGN_CENTER Y_ALIGN_BOTTOM LABEL_BORDER LABEL_MULTILINE BUTTON_NO_BORDER BITMAP_BORDER BITMAP_BUTTON BITMAP_CAPTION_INNER BITMAP_DOTBORDER BITMAP_CAPTION_RIGHT BITMAP_CAPTION_BOTTOM None None None VSCROLLBAR HSCROLLBAR Component Specific Type typedef struct { char *str; void *icon; RECR r; }FORMCAPTION; None
FORM_LABEL
FORM_BUTTON FORM_BITMAP
None Typedef struct { short width,height; void *img; char *caption; void *mask; }BITMAP; None None None typedef struct{ short max,position,page_height; RECT first_r, second_r; RECT third_r, last_r; RECT button_r; } SCROLLBAR; typedef struct { short counter_lines; char string[TEXTBOX_MAX_CHAR]; short max_char; short min_empty_lines; short start_line; short visible_lines; }TEXTBOX; typedef struct { short spacing; char str[32]; }SPINBUTTON;
FORM_MENU FORM_MENUITEM FORM_SYSTEM FORM_SCROLLBAR
FORM_TEXTBOX
None
FORM_SPINBUTTON
VSPINBUTTON HSPINBUTTON
Form Component FORM_CHECKBUTTON None
Applicable Styles
Component Specific Type typedef struct{ short value; void *caption; }CHECKBUTTON; 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_COMBOBOX
COMBOBOX_NO_BORDER COMBOBOX_LEFT_ALIGN COMBOBOX_RIGHT_ALIGN COMBOBOX_NO_ARROW
FORM_END Note: Descriptions of component specific structures are included under appropriate entries in the form component reference, Section 2.3. Note: The constants and data structures in this table are defined in gui.h.
2.3
Form Components Caption must be the first item in your form array declaration.
caption
a) FORM_FRAME_CAPTION
b) FORM_DLGFRAME
c) FORM_FRAME_BORDER Figure 3: Caption styles type id x,y,w,h *text FORM_CAPTION Not used, set to 0. (x,y) are the coordinates of the top-left of the form. w is the width and h is the height pointer to the structure FORMCAPTION. typedef struct { char *str; void *icon; RECR r; }FORMCAPTION; style //the caption string, NULL if the //caption is an icon //the caption icon, NULL if the //caption is a string //reserved for system use.
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 area on 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.
status font
not used, set to 0 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 id x,y,w,h *text style FORM_LABEL component ID (x,y) are the coordinates of the top-left of the form. w is width and h is height. Pointer to the label's text string. Indicates the text alignment. There are 6 alignment methods available, see Table 5 for the complete listing. Both the x and y alignments must be set or the label may not display properly.
10
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 font examples COMPONENT_VISIBLE or COMPONENT_INVISIBLE Any available font, see Table 4 for a listing. 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 id x,y,w,h *text style status font examples FORM_MENU Component ID (x,y) are the coordinates of the top-left of the form. w and h are automatically calculated, set them to 0. Pointer to the text string which will be shown on the menu. Not used, set to 0. COMPONENT_VISIBLE or COMPONENT_INVISIBLE Any available font, see Table 4 for a listing (FONT_MEDIUM is recommended). See menu item below.
11
menu item
Menu items are shown in a rectangle when the menu is tapped. In Figure 5 the menu items are Preference...", Category...", "ViewBy...", "-" and "Reboot". The menu item "-" creates the seperator line whch appears between "ViewBy..." and "Reboot". FORM_MENUITEM component ID x, y, w, h are automatically calculated, set them to 0. Pointer to the text string which will be shown as the menu item when the menu is displayed. Not used, set to 0. COMPONENT_VISIBLE or COMPONENT_INVISIBLE Any available font, see Table 4 for a listing (FONT_MEDIUM is recommended). CAUTION: In a form array menu items must be placed directly after the menu in which they 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}};
type id x,y,w,h *text style status font examples
button type id x,y,w,h *text style status font
FORM_BUTTON is a standard rectangular button with a string on it. FORM_BUTTON Component ID (x,y) are the coordinates of the top-left of the form. w is width, and h is height Pointer to the string which will be displayed on the button. BUTTON_NO_BORDER will suppress the buttons border. COMPONENT_VISIBLE or COMPONENT_INVISIBLE Any available font, see Table 4 for a listing.
12
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 handle events that the component responds to. See Section 3 for details.
type id x,y,w,h *text
FORM_BITMAP Component ID (x,y) are the coordinates of the top-left of the form, w is width of the bitmap, and h is height Pointer to the BITMAP structure, defined as follows. Typedef struct { short width,height; void *img; char *caption; void *mask; }BITMAP; //width and height of the bitmap //location of uncompressed bitmap //(monochrome or 16 bit color) //string that the bitmap can be //displayed with //location of monochrome mask for //transparency, set to NULL if not used
style
BITMAP_COLOR Indicates that the bitmap is 16 bit color. If BITMAP_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_BOTTOM The bitmaps caption text is shown along the bottom of the bitmap.
status font
COMPONENT_VISIBLE or COMPONENT_INVISIBLE Any available font, see Table 4 for a listing.
13
examples
#define l_icon_width 32 #define l_icon_height 32 unsigned char l_icon_bitmap[] = {0x00, 0x00, 0x00, 0x01, 0xFC, 0x00, 0x01, 0xFC, ...}; //generated with the bmp2txt tool unsigned 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 id x,y,w,h *text FORM_CHECKBUTTON Component ID (x,y) are the coordinates of the top-left of the form. w and h are automatically calculated, set them to 0. Pointer to the CHECKBOX structure, defined as follows. typedef struct{ short value; void *caption; }CHECKBUTTON; style status font Not used, set to 0. COMPONENT_VISIBLE or COMPONENT_INVISIBLE Any available font, see Table 4 for a listing. // 1 for checked and 0 for not checked // the caption string to be displayed // following the checkbox.
14
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,F ONT_SMALL}, ... {FORM_END}};
spin button
There are two styles of spin button, horizontal and vertical. A horizontal spin button displays 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 id x,y,w,h *text FORM_SPINBUTTON Component ID (x,y) are the coordinates of the top-left of the form, w and h are automatically calculated, set them to 0. Pointer to the SPINBUTTON structure, defined as follows. typedef struct { short spacing; char str[32]; }SPINBUTTON; style status font examples //space to leave between the two arrows. //Text to display between the arrows, //HSPINBUTTON only.
VSPINBUTTON or HSPINBUTTON COMPONENT_VISIBLE or COMPONENT_INVISIBLE Any available font, see Table 4 for a listing. 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}};
15
scroll bar type id x,y,w,h *text
The scroll bar is a vertical bar with an arrow on each end and a grabber as shown in Figure 5. It keeps state information about the position of the grabber FORM_SCROLLBAR Component ID (x,y) are the coordinates of the top-left of the form. w is fixed and should be set to 0. h is the height. 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 be in the range of 0 to max-1. page_height:This is the amount position will change when the page is scrolled. The system will adjust the value if it is set to 0 or greater 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.
status font examples
COMPONENT_VISIBLE or COMPONENT_INVISIBLE Not used, set to 0. 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}};
16
combo box
A combo box is a list with the ability to display the currently selected item. The list is displayed when the combo box is tapped on. If an item is selected from the list or when the user taps out of the component, the list will be closed and the selected item will be reflected in the combo box. When all of the list items cannot be displayed at once, a spin button is added automatically for scrolling through the items. In Figure 8, the combo box with string Basic" has been tapped displaying the full list of items .
Figure 8: LEOs Launcher with combo box dropped type id x,y,w,h *text FORM_COMBOBOX Component ID (x,y) are the coordinates of the top-left of the form. w is width and h is height. Pointer to the COMBOBOX structure, defined as follows. typedef struct { short index; char str[32]; }ITEM; typedef struct { short max_items; short selected; //item index. //items string value.
// the max items the list can have. //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 droped ITEM items; //see the structure ITEM above }COMBOBOX;
17
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 string COMBOBOX_RIGHT_ALIGN Right align the selected string. COMBOBOX_NO_ARROW Remove the arrow from the combo box.
status font examples
COMPONENT_VISIBLE or COMPONENT_INVISIBLE Any available font, see Table 4 for a listing. 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 id x,y,w,h FORM_TEXTBOX Component ID (x,y) are the coordinates of the top left of the form. w is the width of the text box. h is automatically 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 use char 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
18
short start_line; short visible_lines; }TEXTBOX; style status font examples Not used, set to 0.
//regardless of the length of string. //first line to be shown. //number of lines to show.
COMPONENT_VISIBLE or COMPONENT_INVISIBLE Any available font, see Table 4 for a listing. 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 type
The last line of the form definition. This line is necessary. FORM_END
19
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 is finished. CAUTION: Some API components may not work properly if init_screen() is not called. arguments returns sample code Launch_cmd Value returned by GetLaunchCommand() None 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 decide between run normal or calling PutAppInfo(). int main(int argc, char* argv[]){ short launch_cmd; //get the launch command launch_cmd = GetLaunchCommand(argc, argv); init_screen(launch_cmd); switch(launch_cmd){ case CMD_RUN_NORMAL: wait_loop(); //wait for messages loop break; 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 returns None Nothing
20
sample code
See init_screen()
GetLaunchCommand short GetLaunchCommand(int argc, char *argv[]); This function translates command line parameters passed to the application into a launch code. arguments returns sample code PutAppInfo short GetLaunchCommand(int argc, char *argv[]); This function registers the application's information with the LEOs application database. arguments app_info Defined in <program name>.rsrc, it is a pointer to the structure APP_INFO. The structure contains standard program information needed by the system. The structure definition follows. typedef struct { char nick_name[16]; char version[16]; char owner[32]; char creator[32]; BITMAP *large_icon; BITMAP *small_icon; }APP_INFO; returns sample code None See init_screen(). //applications name //version string vx.x.xxx //company that owns the application //development team of the application //32x32 image in hex (see FORM_BITMAP) //16x16 image in hex (see FORM_BITMAP) argc, argv Command line arguments passed into main() The launch code, either CMD_RUN_NORMAL or CMD_RUN_GET_INFO 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.
21
returns sample code
The index of the component if found, 0 if the ID doesnt match. 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 as bitblt(). arguments returns sample code None A pointer to the screen. #define BITMAP_WIDTH #define BITMAP_HEIGHT 16 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);
22
This function gets the screen height. Using this function can make a program more portable. arguments returns sample code None The height of the screen in pixels. See PixelInRect
GetScreenWidth U8 GetScreenWidth(void); Get the screen width. Using this function can make a program more portable. arguments returns sample code none This returns the width of the screen. See PixelInRect()
SetAvailableRegion void SetAvailableRegion(RECT *r); This function specifies the region of the screen to be available for certain operations like drawing. For example, it can be used to restrict drawing to a specific region of the screen and 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 returns r The rectangular region functions such as drawing will be restricted to.
None
23
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. Before exiting, 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 width and 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 returns sample code w, h Width and height of the screen buffer. A pointer to an allocated screen buffer of the required size. NULL if memory is not available. 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 new window and calls the main loop. When it is done, it closes the window, puts the original screen back and frees the memory. static void Sample(void) { U8 *background; //momery block to save background background = 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); };
24
FreeScreen U8 FreeScreen(U8 *p); This function frees memory blocks allocated with MallocScreen(). arguments returns sample code CopyScreen void CopyScreen(U8 *p, U16 x, U16 y, U16 w, U16 h); This function copies a region of the screen to memory. arguments p Pointer to memory allocated with MallocScreen(). The allocated memory must have the correct size. x, y Coordinates of the top-left corner of the screen region to save. w, h Width and height of the screen region to save returns sample code PasteScreen void PasteScreen(U8 *p, U16 x, U16 y, U16 w, U16 h); This function pastes the contents of p to the screen. The contents of p could be the result of CopyScreen() or any other bitmap data in memory. arguments p Pointer to image data to be pasted. None See MallocScreen(). p Pointer to the memory block to be freed.
It returns 0. See MallocScreen().
x, y Coordinates of the top-left corner of the screen region to paste to. w, h Width and height of the screen region to paste to. returns sample code CreateForm void CreateForm(FORM *dlg); None See MallocScreen().
25
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 returns sample code CloseForm void CloseForm(FORM *dlg); This function closes the current form and deactivates all GUI components in the form. arguments returns sample code dlg The form array to be closed. None See MallocScreen(). dlg The form array to be displayed. None See MallocScreen().
HideComponent void HideComponent(short index, FORM *frm); This function makes a form component invisible. A component cannot receive messages while it is invisible. arguments index The array index of the component to be hidden. frm The form array that contains the component. returns sample code None 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.
26
arguments
index The array index of the component to be shown. frm The form array that contains the component.
returns sample code
None See HideComponent().
RefreshComponent void RefreshComponent(short index, FORM *frm); This function redraws a specific form component. This is an alternative to redrawing every component in the form (i.e. with CreateForm()) when the attributes of a single component have changed. arguments index The array index of the component to be refreshed. frm The form array that contains the component. returns sample code none This sample code demonstrates how to use RefreshComponent(). It finds the array index of a component and then refreshes it.. void sample_play25() { 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
27
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, is tapped. static sample_play27(short msgvalue) { short i; i = atoi(spinbutton_sample.str) + msgvalue; if((i<100)&&(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 sample code The number of lines needed to display the content. 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 ID nIndex = GetIndexFromId(frmMainFrame, LABEL_CONTENT_ID); //Update label string sprintf(szLabelCaption, "Hello World\nLinuxDA"); //refresh the multi-line label RefreshMultiLineString(&frmMainFrame[nIndex], 1); }; RefreshTextBoxContents void RefreshTextBoxContents(FORM *txt, short start_pos, short end_pos, short flag);
28
This function refreshes the string in a text box between the cursor start position and the cursor 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 sample code The number of lines required to display the content. 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 ID nIndex = GetIndexFromId(frmMainFrame, TEXTBOX_CONTENT_ID); //Update textbox attributes textbox_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 Pointer to a form component of type FORM_TEXTBOX. s returns The new text box string.
None
29
sample code
void SetTextBoxTextDemo(char szContent) { int nIndex; //get textbox index nIndex = GetIndexFromId(frmMainFrame, TEXTBOX_CONTENT_ID); //Update textbox attribute SetTextBoxText(&frmMainFrame[nIndex] , szContent); };
GetTextBoxLines short GetTextBoxLines(FORM *txt); This function returns the total number of lines in a text box. arguments returns sample code txt Pointer to a form component of type FORM_TEXTBOX. The total number of lines in the text box. 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 Pointer to a form component of type FORM_TEXTBOX. line Line number of first line to be displayed in the text box. returns none
30
sample code
void ScrollTextBoxDemo(int nStartPosition) { int nIndex; nIndex = GetIndexFromId(frmMainFrame, TEXTBOX_CONTENT_ID); // Update textbox attribute SetTextBoxStartLine(&frmMainFrame[nIndex], nStartPosition); // Refresh textbox RefreshComponent(nIndex, frmMainFrame); // After refreshing the textbox, SetFocus is required SetFocus(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 sample code none void SetTextBoxVisibleLinesDemo(int nVisibleLines) { int nIndex; nIndex = GetIndexFromId(frmMainFrame, TEXTBOX_CONTENT_ID); //Update textbox attribute SetTextBoxEndLine(&frmMainFrame[nIndex], nVisibleLines); //Refresh textbox RefreshComponent(nIndex , frmMainFrame); };
SetTextBoxEmptyLines void SetTextBoxEmptyLines(FORM *txt, short line); This function sets the minimum number of lines the text box will display. arguments txt Pointer to a form component of type FORM_TEXTBOX. line Minimum number of lines to be displayed in the text box. returns None
31
sample code
void SetTextBoxEmptyLinesDemo(int nEmptyLines) { int nIndex; nIndex = GetIndexFromId(frmMainFrame, TEXTBOX_CONTENT_ID); //Update textbox attribute SetTextBoxEmptyLines(&frmMainFrame[nIndex], nEmptyLines); //Refresh textbox RefreshComponent(nIndex, frmMainFrame); };
SetFocus void SetFocus(FORM *frm, short id); This function sets the focus to the text box with a given ID. arguments frm Pointer to a form component of type FORM_TEXTBOX. id returns sample code ID of the component.
None See SetTextBoxStartLine().
GetCurrentActivatedTextBox short GetCurrentActivatedTextBox(void); Return the ID of the active text box, 0 if there is no text box selected. arguments returns sample code PixelInRect U8 PixelInRect(PIXEL px, RECT r); This function checks if a pixel's coordinates lie within a rectangular region. Return value is 1 if yes, 0 if no. arguments px r returns Pixel the system will check. Rectangular region. None Text box ID on success and 0 if none is selected.
1 if the pixel is within the rectangle and 0 if it is not.
32
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 sample code None void AddCharToTextBox(int nCharCode) { SendKeyToForm(frmMainFrame , nCharCode); };
33
3 GUI Message API

3.1 GUI_ MSG Data Structure Table 6: GUI_MSG data structure {id, event, lParam, keycode, value} id Form identification number The ID of the form component the message is associated with. event The message type. U16 gui.h U8
For example click or pen up. There are currently 9 GUI message types defined in the LEOs API. For more information, see the GUI message type reference, 3.2. lParam Message type specific parameter. Typically, lParam contains the coordinates where the event took place, x=hibyte(lParam), y=lobyte(lParam). keycode Hardware button keycode. U8 U32
When a hardware button is pressed, generic hardware button events are generated. This element indicates which button was used. value Form component specific value. short
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. For EVENT_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 short and unsigned long, respectively. 3.2 GUI Message Types No event occurred. EVENT_NOTHING Not used. Not used. Not used. Not used.
nothing event type id lParam keycode value
34
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 id lParam
EVENT_CLICK ID of the form component at the screen position where the tap occurred. (x, y) coordinates of the pen on the screen where x=hibyte(lParam), and y=lobyte(lParam). Not used. Form component specific. See the form component reference, Section 2.3, for details. This event is generated when the user leaves the soft keyboard form or the magic pen form after completing changes to a text box. EVENT_INPUTCHAR Identification number of the text box that was edited. Not used. Not used. The change in the number of lines of text contained in a text box, i.e. old line count new line count. This event is generated when a hardware button is pressed. EVENT_KEYDOWN Not used. Not used. A value corresponding to the hardware button pressed. See Figure 10 below for possible keycode 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.
keycode value input character event type id lParam keycode value key down event type id lParam keycode
value key up event type id
Not used. This event is generated when a hardware button is released. EVENT_KEYUP Not used.
35
lParam keycode value pen up event type id lParam
Not used. A value corresponding to the hardware button released, see Figure 10 for details. Not used. This event is generated when the pen is removed from the touchscreen. EVENT_PENUP Identification number of the form component at the screen position where the pen last touched the screen. (x, y) coordinates of the pen on the screen where x=hibyte(lParam), and y=lobyte(lParam). Not used. Not used. This event is generated when the menu bar is shown. EVENT_SHOW_MENUBAR Not used. Not used. Not used. Not used. This event is generated when the menu bar is hidden. EVENT_HIDE_MENUBAR Not used. Not used. Not used. Not used.
keycode value show menu bar event type id lParam keycode value hide menu bar event type id lParam keycode value
36
3.3
GUI Message Functions
ClearMessageQueue void ClearMessageQueue(void); This function clears the message queue. It is common to clear the message queue when a new form is created to eliminate stale messages for an old form. arguments returns sample code None None 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 for the form. Messages are passed into the switch statement to find the corresponding action. 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.
37
arguments
frm The form array requesting a message to process. msg Location to store the retrieved message, see 3.1 for the GUI message data structure.
returns sample code
None 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 not processed by the application. arguments dlg The form array which received, but did not process the message. msg Pointer to the unprocessed message. returns sample code SendMessage void SendMessage(GUI_MSG *msg) This function puts a message onto the message queue. arguments returns sample code msg Pointer to the message to be added to the queue. None This program demonstrates how to use SendMessage(). The message sent emulates an EVENT_CLICK event on a menu. void sample_play20() { GUI_MSG exit_msg; exit_msg.event = EVENT_CLICK; exit_msg.id = MENUITEM_MAIN_EXIT; SendMessage(&exit_msg); }; None See ClearMessageQueue().
38
4 Draw API
4.1 Draw Structures and Constants Table 7: PIXEL data structure {x, y} x, y The coordinates of a pixel. Table 8: RECT data structure {left, top, right, bottom} left,top right,bottom The (x, y) coordinates of the rectangle's top left corner. The (x, y) coordinates of the rectangle's bottom right corner Table 9: Color data structure {R, G, B} R, G, B A colors red, green, and blue values, respectively. Several colors have been predefined for convenience. static static static static static static static const const const const const const const Color Color Color Color Color Color Color GUI_WHITE={255,255,255}; GUI_BLACK={0,0,0}; GUI_RED={255,0,0}; GUI_GREEN={0,255,0}; GUI_BLUE={0,0,255}; GUI_PURPLE={255,0,255}; GUI_YELLOW ={255,255,0}; gui.h U8 gui.h short short gui.h short
Note: U8 is defined in gui.h. It is currently equivalent to unsigned char.
39
Table 10: GraphicsContext data structure {color, mode, fill_index} color Color to be used by the drawing function. gui.h Color
The (R,G,B) value to be used by the function. For example, the color of the ellipse drawn by draw_ellipse(). mode Logical operation to be applied when copying or pasting. CopyMode
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; fill_index Identifying number. typedef enum {WhitePattern = 0, BlackPattern, DarkGreyPattern, LightGreyPattern, MicroPengPattern, HoriDotPattern, VertDotPattern, InvalidPattern, MonochromePattern } PatternIndex; PatternIndex
Table 11: Pattern data structure {height, data} height The pattern's y dimension, or height, in pixels. Patterns are monochrome and their width is always 8 pixels. gui.h U16
data
Data is an array of 8 bit elements. Each element represents a row of monochrome pixel values.
U8
Note: U8 and U16 are defined in gui.h. They are currently equivalent to unsigned char and unsigned short respectively.
40
Table 12: Bitmap data structure {width, height, *img, *caption, *mask} width, height Width and height of the bitmap. gui.h short
*img
The bitmap A pointer to the uncompressed monochrome or color bitmap data.
void
*caption
Display text A string that the bitmap can be displayed with.
char
*mask
Transparency mask
void
A pointer to the uncompressed monochrome bitmap to be used as a transparency mask.
41
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 sample code None 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 of coordinates. arguments x1, y1 Coordinates of the start point. x2, y2 Coordinates of the end point. color Line color.
42
returns sample code xor_draw_line
None See draw_pixel().
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 second set of coordinates. arguments x1, y1 Coordinates of the start point. x2, y2 Coordinates of the end point. returns sample code 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 b returns sample code 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, short dest_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. Dimension of the long axis of the ellipse. Dimension of the short axis of the ellipse. None See draw_pixel().
None See draw_pixel().
43
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_y Coordinates 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 if src is monochrome. CAUTION: When drawing only parts of the source image, src_units_per_line has to 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
44
sample code
This sample code demonstrates bitblt() and PixelsUnits(). It displays a bitmap image. void sample_play24() { 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 returns sample code PixelsUnitsOld U8 PixelsUnitsOld(short pxs); Find the number of bytes required to store a certain number of monochrome bitmap pixels. arguments returns sample code pxs Number of monochrome bitmap pixels. Number of bytes. See bitblt(). pxs Number of 16bit color bitmap pixels. Number of bytes. See bitblt().
45
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. If gc->fill_index = InvalidPattern, the region will be filled with gc->color CAUTION: dest_units_per_line is not equal to PixelsUnits(w) if w is only a fraction of the total width of the whole image. returns sample code None 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 image patternfill(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);
46
This function is a simpler version of patternfill() that can only draw onto the screen. arguments r gc A rectangular region of the screen. Graphics Context.
gc->fill_index One of the pattern constants defined in Table 11. If gc->fill_index = InvalidPattern, the region will be filled with gc->color returns sample code draw_rect void draw_rect(RECT r,GraphicsContext *gc); This function draws a colored rectangle. arguments r gc A rectangular region of the screen. Graphics Context. None See patternfill().
gc->color The rectangles color. returns sample code XorButtonFace void XorButtonFace(RECT r); This function inverts the pixels in a rectangular region of the screen. arguments returns sample code r The rectangular region to invert None See patternfill().
None
47
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 specified font. arguments str The string to be measured. font_lib The font the string is drawn in. returns sample code The string width in pixels. #define MAP_WIDTH #define MAP_HEIGHT 150 110
void ShowWelcome(char *szWelcomeInfo) { int nPositionX; int nPositionY; GraphicsContext gc; //Display the welcome information gc.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 returns None The current font height in pixels.
48
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 returns sample code 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 of gc are not used. font_lib One of the available fonts, see Table 4.This will become the default font. returns sample code None See GetStringWidth(). font_lib One of the available fonts, see Table 4. None See GetFontHeight().
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 be cropped. Note: This function changes the default font to font_lib.
49
arguments
Rectangular region where the string will be displayed.
str 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 of gc 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 sample code None void DisplaySomething(char szMessage) { RECT rectRange; GraphicsContext gc; //set up the area rectRange.top = 10; rectRange.left = 10; rectRange.bottom = rectRange.top + 100; rectRange.right = rectRange.left + 100; //set up some attributes gc.mode = Mode_SRC; gc.color = GUI_BLACK; //call the function to display the string DrawStringInRect(&rectRange, szMessage, &gc, FONT_SMALL, Y_ALIGN_CENTER | X_ALIGN_MIDDLE); };
50
6 Database API
6.1 Database Structures and Constants Table 13: General definitions Constant MAX_FILENAME_LENGTH DB_SHOW_SECURITY DB_HIDE_SECURITY Description The maximum file name length. Currently set at 16 characters. One of two possible security modes for the database. Allows all records to be accessed regardless of their security property. One of two possible security modes for the database. Restricts access to records with the DB_RECORD_SECURITY property.
Note: These constants are defined in mini_db.h.. Table 14: Database record properties Constant DB_RECORD_SECURITY DB_RECORD_DELETED DB_RECORD_UPDATED Description If the database's security mode is DB_HIDE_SECURITY, records with this property cannot be retrieved. Indicates that the record will be deleted from the datebase on the next synchronization. Indicates that the record is going to be updated during the next synchronization.
Note: These constants are defined in mini_db.h.
51
Table 15: DBFIELD structure {field_name, field_length, field_type} field_name Database field name Field names can not be longer than MAX_FILENAME_LENGTH. field_length Database field length. short mini_db.h char
field_type
Database field 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.
short
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.
52
arguments
DBName Database name string, size must be less than MAX_FILENAME_LENGTH. DBFlags 0 to create a new database or DB_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 sample code
0 on success, 1 on error. #define FIELD1 "field1" #define FIELD2 "field3" #define DBNAME "database1" #include <mini_db.h> DBFIELD field_descriptions[]={ {FIELD1,25,DBSTRING}, {FIELD2,25,DBSTRING}, }; static void OpenTaskDB(void) { short idx; short i,j; //Create the Task database with 3 categories g_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 16 categories. Note: A category is different from a field. Each record can have many fields but it can only belong to one category.
53
arguments
dbhandle Pointer to a database's handle. cate_name Category name string.
returns sample code
The category ID on success, 1 on error. See LDACreateDB().
LDADeleteDBCategory int LDADeleteDBCategory(DBHANDLE *dbhandle, int cate_index); This function deletes a category from a database. All records that belonged to the deleted category will belong to category 0. arguments dbhandle Pointer to a database's handle. cate_index Category ID returns sample code 0 on success, 1 on error. //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. returns sample code The category ID on success, 1 on error. //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.
54
arguments returns sample code
dbhandle Pointer to a database's handle The number of categories on success, 1 on error. 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 also overwrites cate_name with the name of the category with the given alphabetical rank. arguments dbhandle Pointer to a database's handle cate_rank Rank of a category, alphabetically. Not the category ID. cate_name Buffer to store category name, if found. returns sample code The category ID on success, 1 on error. if (CheckOpen(g_db_handle) == -1){ // database was opened successfully //Get the total number of categories g_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 or DB_EXCLUSIVE to open the database in exclusive mode. returns sample code The database handle on success, 1 on error. See LDACreateDB().
55
LDADeleteDB int LDADeleteDB(char *DBName); This function deletes the named database. arguments returns sample code DBName Name string of database to be deleted. 0 on success, 1 on error. #define DBNAME database1" #include <mini_db.h> static void DeleteDB(void) { DBHANDLE g_db_handle; g_db_handle = LDAOpenDB(DBNAME,0); if (CheckOpen(g_db_handle) == -1){ // open database sucessfully LDACloseDB(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 sample code 0 on success, 1 on. 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 the specified category.
56
returns sample code
0 on success, 1 on error. 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 dbhandle database handle secu_option DB_SHOW_SECURITY or DB_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. returns sample code 0 on success, 1 on error. See LDAGetRecordNumber().
LDAGetRecordNumber long LDAGetRecordNumber(DBHANDLE dbhandle) This function returns the number of records in the current category and the indicated database. arguments returns sample code dbhandle Database handle. The number of records on success, 1 on error. #define DBNAME "database1" #include <mini_db.h> typedef struct { char last_name[25]; char first_name[25]; }ADDRESS_T; //must match corresponding field description array static void GetRecordCount(void) { short i; DBHANDLE g_db_handle; ADDRESS_T rec1, rec2; long num1, num2, total; strcpy(rec1.last_name, "Johns"); strcpy(rec1.first_name, "Smith"); strcpy(rec2.last_name, "Philips"); strcpy(rec1.first_name, "Adams")
57
g_db_handle = LDAOpenDB(DBNAME, 0); if (CheckOpen(g_db_handle) == -1){ //opened database sucessfully cate_index1 = LDAAddDBCategory(&g_db_handle, "Personal"); cate_index2 = LDAAddDBCategory(&g_db_handle, "Business"); //normal record LDAAddRecord(&g_db_handle, &rec1, cate_index1, DB_SHOW_SECURITY)); //protected record LDAAddRecord(&g_db_handle, &rec2, cate_index2, DB_RECORD_SECURITY); //set the database to protected mode LDASetDBSecurity(g_db_handle, DB_HIDE_SECURITY); LDASetDBCategory(&g_db_handle, cate_index1); //There is one record in Personal catalog ,num1=1 num1 = LDAGetRecordNumber(g_db_handle); LDASetDBCategory(g_db_handle, cate_index2); //There is one record in Business catalog. //It is protected, so num2=0 num2=LDAGetRecordNumber(g_db_handle); //total is 2. There are two records. total=LDAGetTotalRecords(g_db_handle); LDACloseDB(&g_db_handle,0);
};
LDAGetTotalRecords long LDAGetTotalRecords(DBHANDLE dbhandle); This function returns the total number of records in the indicated database. arguments returns sample code LDAAddRecord int LDAAddRecord(DBHANDLE *dbhandle, void *data, char category, char property); This function adds a record to the database. CAUTION: All records are sorted by their first field. Record IDs for other records might change when adding a new record. dbhandle Database handle. The number of records on success, 1 on error. See LDAGetRecordNumber().
58
arguments
dbhandle Pointer to a database's handle. data Pointer to the user-defined record structure. category Category ID of the category this record belongs to. property 0 for an unsecured record or DB_RECORD_SECURITY for a record that should be hidden when the database is in DB_HIDE_SECURITY mode.
returns sample code
0 on success, 1 on error. See LDAGetRecordNumber().
LDAFindRecordByValue long LDAFindRecordByValue(DBHANDLE dbhandle, void *data, void *CompareValue, char *category, char *property); This function finds a record by comparing its first field to a given value. If there is no exact match, the first record with a value greater than the given value will be returned. data, category and property will be updated to reflect the returned record's values. CAUTION: This function only checks the first field of records. arguments dbhandle Database handle. data Pointer to the user-defined record structure for returning the search result. CompareValue Value to compare with, only implemented for first field. category Location to store the search result's category ID. property Location to store the search result's property. returns The index of a record on success, 1 on error.
59
sample code
static void SearchRecord(void) { short search_id, cate_index1, cate_index2; ADDRESS_T rec_addr, rec1, rec2; char last_name[100], cat, sec; strcpy(rec1.last_name, "Johns"); strcpy(rec1.first_name, "Smith"); strcpy(rec2.last_name, "Philips"); strcpy(rec1.first_name, "Adams"); g_db_handle = LDAOpenDB("address", 0); if (CheckOpen(g_db_handle) == -1){ //opened database successfully cate_index1 = LDAAddDBCategory(&g_db_handle, "Personal"); LDAAddRecord(&g_db_handle, &rec1, cate_index1, DB_SHOW_SECURITY); LDAAddRecord(&g_db_handle, &rec2, cate_index2, DB_SHOW_SECURITY); strcpy(last_name,"Smith"); //using lastname to find the record, //record ID saves at search_id. //The record saves at rec_addr search_id = LDAFindRecordByValue(g_db_handle, &rec_addr, last_name, &cat,&sec); LDACloseDB(&g_db_handle); };
LDAGetNextRecord int LDAGetNextRecord(DBHANDLE dbhandle, void *data, char *category, char *property); This function retrieves the next record. Use this function for efficient record iterating. data, category and property will be modified with the next records values on success. Note: Records with the DB_RECORD_SECURITY property will be passed over if the database security mode is set to DB_HIDE_SECURITY. arguments dbhandle Database handle data Pointer to the user-defined record structure for returning the retrieved record. category Location to store the retrieved records category ID. property Location to store the retrieved records property. returns sample code 0 on success, 1 on error. See LDAGetRecord().
60
LDAGetRecord int LDAGetRecord(DBHANDLE dbhandle, void *data, long RecordId, char *category, char *property); This function retrieves the record with the given RecordId. data, category and property will be modified with the matching records values on success. Note: Records with the DB_RECORD_SECURITY property will not be returned when the database security mode is set to DB_HIDE_SECURITY. arguments dbhandle Database handle. data Pointer to the user-defined record structure for returning the retrieved record. RecordId ID of record for retrieval. category Location to store the retrieved records category ID. property Location to store the retrieved records property. returns sample code 0 on success, 1 on error. static void HandleRecordDemo(void) { short cate_index1, cate_index2; ADDRESS_T rec_addr, rec1, rec2; char cat,sec; strcpy(rec1.last_name, "Johns"); strcpy(rec1.first_name, "Smith"); strcpy(rec2.last_name, "Philips"); strcpy(rec1.first_name, "Adams"); g_db_handle = LDAOpenDB("address", 0); if (CheckOpen(g_db_handle) == -1){ //opened database successfully cate_index1 = LDAAddDBCategory(&g_db_handle, "Personal"); LDAAddRecord(&g_db_handle, &rec1, cate_index1, DB_SHOW_SECURITY); LDAAddRecord(&g_db_handle, &rec2, cate_index2, DB_SHOW_SECURITY); LDAGetRecord(g_db_handle, &rec__addr, 0, &cat,&sec); LDAGetNextRecord(g_db_handle, &rec__addr, &cat,&sec); LDADeleteRecord(&g_db_handle, 0); LDAUpdateRecord(g_db_handle, &rec1, 0, cate_index1, DB_SHOW_SECURITY); LDACloseDB(&g_db_handle); } };
LDADeleteRecord int LDADeleteRecord(DBHANDLE *dbhandle, short RecordId);
61
This function deletes the indicated record. CAUTION: The record IDs of other records may be changed when this function is called. arguments dbhandle Pointer to a database's handle. RecordId Record ID of the record to be deleted. returns sample code 0 on success, 1 on error. See LDAGetRecord().
LDAUpdateRecord int LDAUpdateRecord(DBHANDLE dbhandle, void *data, short RecordId, char category, char property); This function updates the indicated record with the information in data, category and property. CAUTION: The record IDs of other records may be changed when this function is called. arguments dbhandle Database handle. data Pointer to the user-defined record structure with new values. RecordId Record ID of the record to be updated. category New category ID for the record to be updated. property New property for the record to be updated, see LDAAddRecord(). returns sample code 0 on success, 1 on error. See LDAGetRecord().
62
7 Communication Functions
OpenUART void OpenUART(void); This function initializes the UART device. The UART device must be opened before communicating using the COM port. arguments returns sample code CloseUART void CloseUART(void); This function closes the UART device. arguments returns sample code ReadUART short ReadUART(U8 *data); This function reads a byte from the COM port and puts the byte into data. arguments returns sample code WriteUART short WriteUART(U8 code); This function sends a byte to the COM port. arguments returns sample code OpenIRDA void OpenIRDA(void); code The byte of data to be sent. 0 on success, 1 when timed out. data Location to store the byte read by the COM port. 0 on success, 1 when timed out. None None None None
63
This function initializes the IRDA device. The IRDA device must be opened before communicating using the IRDA port. arguments returns sample code CloseIRDA void CloseIRDA(void); This function closes the IRDA device. arguments returns sample code ReadIRDA short ReadIRDA(void *data, long size); This function reads a number of bytes from the IRDA port and puts the bytes into data. arguments data Location to store the bytes read by the IRDA port. size Number of bytes to read. returns sample code WriteIRDA short WriteIRDA(void *data, long size); This function writes a number of bytes to the IRDA port. arguments data Location of bytes to send. size Number of bytes to send. returns The number of bytes written on success, 1 when timed out. The number of bytes read on success, 1 when timed out. See WriteIRDA(). None None See WriteIRDA(). None None See WriteIRDA().
64
sample code
Suggestion: Call OpenIRDA() at the beginning of your main function and CloseIRDA() at the end of it. void sendbyIrda(ADDRESS_T *rec) { short state, sendtry=0; background=(U8*)MallocScreen(160, 160); CopyScreen(background, 0, 0, 160, 160); CreateForm(frmBeam); state = WriteIRDA(rec, sizeof(ADDRESS_T)); while(state<0){ sendtry++; if(sendtry>5) break; state = WriteIRDA(rec, sizeof(ADDRESS_T)); } if(state<0){ MsgBox(IRDA_SEND_FAILS, FRM_IRDA_SEND, MB_OK); } else { MsgBox(IRDA_SEND_SUCCESS, FRM_IRDA_SEND, MB_OK); } CloseForm(frmBeam); PasteScreen(background, 0, 0, 160, 160); FreeScreen(background); } void recvbyIrda(ADDRESST *RecvRec){ short status; status = ReadIRDA(RecvRec, sizeof(ADDRESS_T)); if(status==sizeof(ADDRESS_T)){ strcpy(message, ""); strcat(message, RecvRec->last_name); strcat(message, RecvRec->first_name); answer = MsgBox(message, FRM_IRDA_RECEIVE, MB_YESNO); if (answer==MB_YES) LDAAddRecord(g_db_handle, RecvRec, 0, 0); } };
65
8 Camera Functions
q_cif_DMA_preview_on int q_cif_DMA_preview_on(int x, int y); This function starts the DMA preview. It first checks that the system is not in some non-ready state, then it opens the device and sets the resolution to q_cif. It then sets the DMA window in the frame buffer and starts DMA. arguments returns sample code cif_DMA_preview_on int cif_DMA_preview_on(int x, int y, int w, int h) This function starts the DMA preview. It first checks that the system is not in some non-ready state then it opens the device and sets the resolution to cif. It then sets the DMA window in the frame buffer and starts DMA. arguments x, y Coordinates of the start point in the frame buffer for the data to be sent to. w, h Width and height of the window. x, y Coordinates of the start point in the frame buffer for the data to be sent to. 0 on success, a negative on error.
returns sample code
0 on success, a negative on error.
DMA_preview_off int DMA_preview_off(); This function stops DMA preview and closes the device. arguments returns sample code q_cif_stream_on int q_cif_stream_on(unsigned int bkgrndptr, char *mov_path); This function starts streaming to a memory mapped location. It first checks that the system is not in some non-ready state, then it opens the device and sets the resolution to q_cif. It then sets up the driver buffer and maps the memory. 0 on success, a negative on error.
66
arguments
bkgrndptr Pointer to the frame buffer, stored for quick access in polling. mov_path Path of the file, stored and opened for quick access.
returns sample code stream_off
int stream_off(); This function stops streaming, unmaps memory, and closes the file and the device. arguments returns sample code q_cif_still_capture int q_cif_still_capture(char *picture, int size); This function takes a still frame picture and stores it. This is a q_cif sized picture and will return an error if the indicated size is not set appropriately. The device is opened and closed in this call. If the camera is BGR, the data is swapped before returning. Note: VGA and QVGA resolutions are not supported yet arguments picture Storage array for the image. The size of the array should be 176*144*2 for 16 bit color images or 176*144*3 for 24 bit color images. size The size of the array. returns sample code cif_still_capture int cif_still_capture(char *picture, int size); This function takes a still frame picture and stores it. This is a cif size picture and will return an error if the indicated size is not set appropriately. The device is opened and closed in this call. If the camera is BGR, the data is swapped before returning. Note: VGA and QVGA resolutions are not supported yet 0 on success, a negative on error. 0 on success, a negative on error.
67
arguments
picture Storage array for the image. The size of the array should be 352*288*2 for 16 bit color images or 352*288*3 for 24 bit color images. size The size of the array.
returns sample code
68
9 Sound API
snd_getWavHeader int snd_getWavHeader(char* file, WAV_HEADER* header); This function get the header of a wave file and return the header through the header argument. arguments file The name of the wave file header This WAV_HEADER struct will hold the header 0 is successful, -1 otherwise
returns sample code
snd_playLongWavFile void snd_playLongWavFile(char* file); This function sends a "play" message to the sound server arguments returns sample code snd_ffLongWavFile void snd_ffLongWavFile(); This function sends a "fastforward" message to the sound server arguments returns sample code snd_rewLongWavFile void snd_rewLongWavFile(); This function sends a "rewind" message to the sound server arguments returns sample code None None None None file The name of the wave file None
69
snd_stopWavFile void snd_stopWavFile(); This function sends a "stop" message to the sound server arguments returns sample code snd_playSound void snd_playSound(int sound_sample); This function play a default sound identified by the argument. arguments sound_sample Either 1) SOUND_SAMPLE_DING, which plays /sound/ding.wav or 2) SOUND_SAMPLE_PHONE_RING, which plays /sound/ring2.wav returns sample code snd_setVolume void snd_setVolume(int vol); This function sets volume by sending a message to the sound server arguments returns sample code snd_getVolume int snd_getVolume(); This function gets volume by sending a message to the sound server arguments returns sample code None The current volume vol The volume that you want to set to (must be between 1 and 10). None None None None
70
10 Other Functions
Showdate void Showdate(short *year, short *mon, short *mday); This function generates a form which displays a calendar, see Figure 11. The form will show the date indicated by the arguments and will modify the arguments as the user interacts with the form.
Figure 11: Showdate form CAUTION: The data type of the parameters are short, not int. Remember to convert values from the data structure tm before they are used in this function. arguments year Pointer to a variable containing the year to be displayed, in years since 1900 (e.g. for 2005 the value should be 105). mon Pointer to a variable containing the month to be displayed, in months since January (i.e.. a number in the range 0 to 11). mday Pointer to a variable containing the day of the month to be displayed (i.e. a number in the range 1 to 31). returns sample code gui_settime void gui_settime(time_t *time_set); KEY_ENTER on "Ok", 0 on "cancel", KEY_RETURN if the system needs to interrupt.
71
This function generates a form which displays a timer, see Figure 12.The form will show the time indicated by the arguments and will modify the arguments as the user interacts with the form.
Figure 12: gui_settime form arguments time_set Pointer to a variable containing the time to be displayed, in seconds since Jan 1, 1970. KEY_ENTER on "Ok", 0 on "cancel", KEY_RETURN if the system needs to interrupt.
returns sample code gui_how_to
short gui_how_to(char *str); This function displays an applications How_to screen. The application must control the format of the string passed into this function.
Figure 13: How_to form arguments str Applications How_to string, formatted for correct display.
72
returns sample code gui_about
KEY_RETURN if the user presses the return key, KEY_ENTER if the user presses the enter key, 0 otherwise.
short gui_about(char *title, char *version); This function displays an applications about screen.
Figure 14: About form arguments title Application's title string. version Application's version string in format v.x.x.xxx". returns sample code MsgBox short MsgBox(char *msgstr, char *title, short mode); Returns 1 if the user pressed the return key, 0 otherwise.
73
This function displays a dialog box to ask for user input.
a) MB_OKCANCEL
b) MB_YESNO
c) MB_OK Figure 15: Three possible message boxes arguments msgstr Message string. title Dialog box title string. mode Buttons to be displayed. Can be MB_OKCANCEL, MB_YESNO, or MB_OK. returns sample code MB_OKCANCEL, MB_YES, MB_NO, or MB_OK depending on the user input. sAnswer = MsgBox("Do you want to Save it?", "LinuxDA", MB_YESNO); switch(sAnswer){ case MB_YES: SaveProcess(); CloseProcess(); break; case MB_NO: CloseProcess(); break; };
lobyte U16 lobyte(U32 lParam); Extract the low byte of lParam. arguments returns lParam U32 value to be divided. The low byte of lParam
74
sample code
int EventClick_Process(GUI_MSG *pcusMessage) { int nStickPositionX; int nStickPositionY; char szMessage[32]; int nResult = pcusMessage->id; nStickPositionX = hibyte(pcusMessage->lParam); nStickPositionY = lobyte(pcusMessage->lParam); sprintf(szMessage, "Current Click Position: X - %d , Y = %d", nStickPositionX, nStickPositionY); MsgBox(szMessage, "LinuxDA", MB_OK); return nResult; };
hibyte U16 hibyte(U32 lParam); Extract the high byte of lParam arguments returns sample code lParam U32 value to be divided. The high byte of lParam See lobyte().
75
11 Sample Programs
11.1 Sample Program 1
Program 1 is a very simple introduction to forms and GUI messages. It demonstrates the use of the form components caption, label and button, as well as the GUI messages generated by a button tap. The wait_loop() function in prog1.c continuously searches for a GUI message indicating the "Tap me" button has been tapped. When the button is tapped by the user, a GUI message is created by the system, then received and processed by wait_loop(). This causes gui_about() to be called, and Program 1's About" page is displayed. The user can then go back to the original form by tapping the OK" button. Concepts demonstrated are the "About" page and the following form components: caption, label, button.
a) Program 1 main form
b) Program 1 "About" screen
Figure 16: Program 1 screenshots
76
11.2
Sample Program 2
Program 2 demonstrates use of several form components and the message box function. When a user taps on the text box, a soft keyboard will appear. If the user taps on the Show text" button, a message box will appear and show the string from the text box. The Add" button increments the length of the scroll bar. One important concept to keep in mind is that the scroll bar does not have a corresponding screen control, therefore, users have to refresh the screen according to the scroll bar position by themselves. The spin button and the combo box are just there to show how they are implemented. Drop down menus are also shown in this program. Concepts demonstrated are the message box function and the following form components: caption, button, combo box, text box, menu, spin button and scroll bar.
Figure 17: Program 2 screenshot
77
11.3
Sample Program 3
Program 3 is similar to program 2. A check button and a bitmap picture are added. Remember, bitmaps must be transformed into hexadecimal values before they can be used. Two conversion utilities, bmp2txt and Bmp2txtBW, are provided in the development environment to simplify the process. Concepts demonstrated are getting the styluss position and the following form components: caption, button, combo box, text box, menu, spin button, scroll bar, check button and bitmap.
78
11.4
Sample Program 4
Program 4 is a mini memo program. A database is created if it doesnt exist and 5 default records are added. A scroll bar will appear if there are more than 10 records. When a user taps on a record, it will be highlighted and the program will jump to a new screen displaying the contents of that record. The user can also use the up and down buttons to select a record in the main screen. New records can be added by tapping the New" button. This will allow the user to type" using the soft keyboard. Pressing the Switch" button will change the Soft keyboard to Handwriting entry, which allows the user to write alphanumeric characters with the stylus. Concepts demonstrated are database functions, the magic pen form, and the following form components: caption, label, combo box, button, text box, and scroll bar.
79
b) Program 4 record view
a) Soft keyboard screen
b) Handwriting screen
Figure 20: Magic pen screenshots
80
11.5
Sample Program 5
Program 5 is similar to program 3. A beam button has been added. When a user taps on the beam button, a new screen will appear and the program will put everything in the text box in a text file and prepare to send it out through the IrDA port. If the user taps send a status bar will come up and report the status of the sending process. Concepts demonstrated are using the IrDA port, getting the styluss position, and the following form components: caption, button, combo box, text box, menu, spin button, scroll bar, check button and bitmap.
b) IrDA communications screen
81
11.6
Sample Program 6
Program 6 is a pen position detector. It displays the coordinate of the stylus at the lower left corner. Concepts demonstrated are click messages, and the following form components: caption, label and menu.
82
11.7
Sample Program 7
Program 7 is a timer seconds timer. The digits displayed are bitmap pictures. If the wait loop detects that one second has elapsed, the screen will be refreshed automatically. Concepts demonstrated: bitmap, menu.
83
11.8
Sample Program 8
Program 8 demonstrates the button control. Two bitmap pictures are displayed, and they will act like buttons. When the user taps on either the left or right bitmap, the picture will move accordingly. This is achieved by changing the x coordinate of the bitmap and covering the old picture position with the screen background color. Concepts demonstrated: bitmap, menu.
84
11.9
Sample Program 9
Program 9 is a drawing program. The user can draw on the screen with the stylus. This is done by detecting the stylus position and filling in the corresponding pixel. Concepts demonstrated are getting the styluss position, drawing functions, and the following form components: caption, menu.
85
11.10
Sample Wav Demonstration
Demo Wave is a simple wave file player. You can play, pause, stop, fast forward and rewind the sample wave file as well as adjust the volume. Concepts demonstrated are using the Sound API in a GUI application.
Figure 26: Demo Wave screenshot
86

LEOs Software Development Manual - Volume 2 API

Încărcat de

Informații document

Drepturi de autor

Formate disponibile

Partajați acest document

Partajați sau inserați document

Opțiuni de partajare

Vi se pare util acest document?

Este necorespunzător acest conținut?

Drepturi de autor:

Formate disponibile

LEOs Software Development Manual - Volume 2 API

Încărcat de

Drepturi de autor:

Formate disponibile

D E V E L O P M E N T

LEOs Software Development Manual Volume 2: API

LEOs Software Development Manual Volume 2: API

LEOs Software Development Manual Volume 2: API

LEOs Software Development Manual Volume 2: API

LEOs Software Development Manual Volume 2: API

LEOs Software Development Manual Volume 2: API

LEOs Software Development Manual Volume 2: API

Form Constants Table 3: Form component status constants

LEOs Software Development Manual Volume 2: API

FORM_MENU FORM_MENUITEM FORM_SYSTEM FORM_SCROLLBAR

LEOs Software Development Manual Volume 2: API

Form Component FORM_CHECKBUTTON None

COMBOBOX_NO_BORDER COMBOBOX_LEFT_ALIGN COMBOBOX_RIGHT_ALIGN COMBOBOX_NO_ARROW

LEOs Software Development Manual Volume 2: API

LEOs Software Development Manual Volume 2: API

LEOs Software Development Manual Volume 2: API

LEOs Software Development Manual Volume 2: API

type id x,y,w,h *text style status font examples

button type id x,y,w,h *text style status font

LEOs Software Development Manual Volume 2: API

type id x,y,w,h *text

COMPONENT_VISIBLE or COMPONENT_INVISIBLE Any available font, see Table 4 for a listing.

LEOs Software Development Manual Volume 2: API

LEOs Software Development Manual Volume 2: API

LEOs Software Development Manual Volume 2: API

scroll bar type id x,y,w,h *text

VSCROLLBAR Vertical scroll bar. HSCROLLBAR Horizontal scroll bar.

status font examples

LEOs Software Development Manual Volume 2: API

LEOs Software Development Manual Volume 2: API

status font examples

Text boxes take and display user input

LEOs Software Development Manual Volume 2: API

LEOs Software Development Manual Volume 2: API

LEOs Software Development Manual Volume 2: API

LEOs Software Development Manual Volume 2: API

returns sample code

LEOs Software Development Manual Volume 2: API

LEOs Software Development Manual Volume 2: API

LEOs Software Development Manual Volume 2: API

It returns 0. See MallocScreen().

LEOs Software Development Manual Volume 2: API

LEOs Software Development Manual Volume 2: API

returns sample code

None See HideComponent().

LEOs Software Development Manual Volume 2: API

LEOs Software Development Manual Volume 2: API

LEOs Software Development Manual Volume 2: API

LEOs Software Development Manual Volume 2: API

LEOs Software Development Manual Volume 2: API

None See SetTextBoxStartLine().

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

LEOs Software Development Manual Volume 2: API

LEOs Software Development Manual Volume 2: API

3 GUI Message API

nothing event type id lParam keycode value

LEOs Software Development Manual Volume 2: API

event type id lParam

value key up event type id

LEOs Software Development Manual Volume 2: API

lParam keycode value pen up event type id lParam

LEOs Software Development Manual Volume 2: API

GUI Message Functions