The C Programmer’s Guide to the
Mosaic Handheld
Table of Contents
PART 1 GETTING STARTED
Introduction. How to Use This Manual
Chapter 1: Getting to Know Your Handheld Instrument
Chapter 2: Powering Your Handheld
PART 2 PROGRAMMING THE MOSAIC HANDHELD
Chapter 3: Your First Program
Chapter 4: The IDE: Writing, Compiling, Downloading and Debugging Programs
Chapter 5: Making Effective Use of Memory
Chapter 6: Real Time Programming
Chapter 7: Failure and Run-Time Error Recovery
Chapter 8: Programming the Graphical User Interface
The Structure Of The GUI Toolkit
The GUI Toolkit Objects
Building Your Application
Designing Your User Interface
Transferring Your Images to the Handheld Controller
Coding Your Application
Handling Errors
Expanding the GUI Toolkit’s Objects and Methods
GUI Objects in Detail
GUI_TOOLKIT
GUI_DISPLAY
GUI Screens
GUI Keypads
GUI_PEN
GUI_BUZZER
GUI_BATTERY
GUI_TIMER
Graphic Object
Font Object
Controls
Action Key Object
Data Entry Key Object
Shift Key Object
Plot Object
Screen Object
Customizing the Keypad Overlay
PART 3 COMMUNICATIONS, MEASUREMENT, AND CONTROL
Chapter 9: Digital and Timer-Controlled I/O
Chapter 10: Data Acquisition
Chapter 11: Serial Communications
Chapter 12: The Battery-Backed Real Time Clock
Chapter 13: Customizing the Handheld's I/O
PART 4: REFERENCE DATA
Appendix A: GUI Function Reference
Appendix B: Handheld Schematics
|
Chapter 8 (continued)
<< Previous | Next>>
GUI Objects in Detail
There are many kinds of GUI objects. Some are tied
tightly to particular hardware (the GUI_BATTERY
and GUI_DISPLAY),
some collect other objects together (GUI Screens), some respond to events
(controls), some are tools (the GUI_PEN),
and some simply contain data for display (graphics and textboxes). Several of
the GUI objects are created and configured when Initialize_GUI is
called. These objects include the GUI_DISPLAY,
GUI_BATTERY,
GUI_BUZZER,
GUI_FONT,
GUI Screens, GUI Keypads, and GUI_PEN.
You can not create more of these object types. For other object such as
graphics, textboxes, keys, screens, and plots, you can create as many as you
like. All of the GUI Toolkit objects, their 32-bit properties, associated methods,
and possible errors are described below. More detailed descriptions of each
method, property, and value is available in the GUI Toolkit Glossary.
The GUI Toolkit is itself an object that contains
properties that effect all other objects. The GUI Toolkit Object is called GUI_TOOLKIT.
These are its properties, methods, and possible errors:
Properties
Table 8‑2 Properties of the GUI_TOOLKIT.
|
|
|
|
|
ABORT_ON_ERROR
|
GUI_TRUE,
GUI_FALSE
|
If true, disables interrupts,
stops multitasking, and sends a detailed message to serial 1 when an error
occurs.
|
|
AVAILABLE_HEAP_SPACE
|
Unsigned Long
|
Read only. Contains the number of bytes remaining in the
GUI Heap.
|
|
CURRENT_SCREEN
|
GUI_SCREEN0 to GUI_SCREEN3
|
Contains the current visible screen.
|
|
SERVICE_EVENTS
|
GUI_TRUE,
GUI_FALSE
|
If false, events are not serviced. All events generated
by pressed keys are ignored.
|
|
STANDARD_FONT
|
GUI_FONT
or custom font object
|
Contains the reference to the font object used to render
string data in textboxes. At initialization, STANDARD_FONT
is set to GUI_FONT
which is a proportional font with a height of 10 pixels. You can set this
property to your own custom font, if desired.
|
|
HORIZONTAL_SNAP_TO_GRID
|
GUI_TRUE
|
Read only. Causes all objects
loaded onto a screen to be located on the nearest 8-pixel horizontal
boundary. This property is always true for speed.
|
|
VERICAL_SNAP_TO_GRID
|
GUI_TRUE,
GUI_FALSE
|
If true, causes all objects loaded on to a screen to be
located on the nearest 8-pixel vertical boundary.
|
Methods
Table 8‑3 Methods of the GUI_TOOLKIT.
|
|
|
|
|
|
Initialize_GUI
|
Start of the GUI Heap, End of the
GUI Heap
|
None
|
Initializes the GUI_TOOLKIT,
GUI_DISPLAY,
GUI_BATTERY,
GUI_PEN,
GUI_FONT,
GUI_BUZZER,
GUI Screens, and GUI Keypads. Sets up and activates a task in common
memory. Initializes and starts the timeslicer. Calling any other GUI
Toolkit method before calling Initialize_GUI
will crash the controller.
|
|
Service_GUI_Events
|
None
|
None
|
Executes the event procedures of controls. This method
must be included in a task as part of your infinite loop to service events
generated from the GUI Task.
|
|
Read_Error
|
None
|
Error code
|
Reads the last reported error.
|
|
Clear_Error
|
None
|
None
|
Clears the last reported error.
|
|
New_Object
|
Object Type
|
Object Reference
|
Create a new object and return an object reference which
is stored in an object variable for later use.
|
|
Set_Property
|
Object Reference, Property, Value
|
None
|
Set an object’s property as a 32-bit value.
|
|
Get_Property
|
Object Reference, Property
|
Value
|
Get an object’s property as a 32-bit value.
|
Errors
Table 8‑4 Errors of the GUI_TOOLKIT.
|
|
|
|
|
HEAP_FULL
|
Initialize_GUI,
New_Object
|
Heap is full. There is no room
to create the GUI Toolkit, create new objects, or resize existing objects.
|
|
GUI_EXISTS
|
Initialize_GUI
|
The GUI Task has already been activated. Do not call Initialize_GUI
more than once!
|
|
DISPLAY_INITIALIZATION_FAILURE
|
Initialize_GUI
|
There was a problem initializing the display. This error
occurs if there was a hardware communications problem talking to the display
controller. If the problem persists, contact Mosaic Industries.
|
|
INVALID_OBJECT
|
New_Object,
Set_Property,
Get_Property
|
The object reference is not valid.
|
|
INVALID_PROPERTY
|
Get_Property,
Set_Property
|
The property is not valid.
|
|
INVALID_IMAGE
|
Set_Property
|
There is no valid image at the specified address. This
error is returned after attempting to set the IMAGE property of a
graphic or a font.
|
|
INVALID_FONT
|
Set_Property
|
The object reference is not a font when setting the STANDARD_FONT
property of the GUI Toolkit or setting the TEXTBOX_FONT
property of a textbox.
|
|
BUFFER_SIZE_OUT_OF_RANGE
|
Set_Property
|
The size of the plot object buffer must be greater than or
equal to the width of the plot in pixels
|
|
WIDTH_OUT_OF_RANGE
|
Set_Property
|
The width will create a plot or textbox that is wider than
the width of the screen.
|
|
HEIGHT_OUT_OF_RANGE
|
Set_Property
|
The height will create a plot or textbox that is taller
than the height of the screen.
|
The GUI_DISPLAY
corresponds to the physical display. Properties of the GUI_DISPLAY
and all other GUI objects are accessed or modified using the GUI_TOOLKIT
methods Set_Property
and Get_Property.
Properties
Table 8‑5 Properties of the GUI_DISPLAY.
|
|
|
|
|
WIDTH_IN_PIXELS
|
128xels
|
Read only. Contains the width of
the display in pixels.
|
|
HEIGHT_IN_PIXELS
|
128xels
|
Read only. Contains the height of the display in pixels.
|
|
CONTRAST
|
0 to 31
|
Changes the contrast voltage of the monochrome display.
Saturates at 0 or 31. Initialized to 16.
|
|
BACKLIGHT_ON
|
GUI_TRUE,
GUI_FALSE
|
If true, turns the backlight on for monochrome displays.
Initialized to GUI_TRUE.
|
|
BRIGHT_BACKLIGHT
|
GUI_TRUE,
GUI_FALSE
|
If true and the backlight is on, supplies more current to
the backlight to increase the brightness. Initialized to GUI_FALSE.
|
A screen is a collection of functionally related objects,
including textboxes, plots, and graphics that are presented together on the
display. Screens are fixed in size to 128 pixels wide by 128 pixels tall. For
speed, objects loaded into screens are aligned on 8 pixel horizontal grid. A
property of the GUI Toolkit, called VERTICAL_SNAP_TO_GRID,
allows you to align objects vertically as well. The coordinate system for
specifying the location of objects and drawing to a screen is in pixels and the
origin is the upper left corner of a screen. The x coordinate represents a
displacement from the origin in the horizontal direction and the y coordinate
represents a displacement from the origin in the vertical direction. An
increase in x moves the coordinate to the right and an increase in y moves the
coordinate down.
Screens whose object images are stored in the display’s
memory are called GUI Screens. GUI screens have a visible property that when
set, causes the selected screen to be shown on the display and makes all other
GUI Screens invisible. Only one GUI Screen can be made visible at a time. GUI
Screens are the only objects that are shown on the physical display. To show
an object like a graphic on the display, the object must first be loaded into a
GUI Screen. The visible screen after Initialize_GUI is
called is GUI_SCREEN0.
You can also create additional screens that reside in the
heap. Heap screens, unlike GUI Screens, can not be made visible. Heap screens
allow you to build many different screens when you are initializing your
application and then quickly switch them into GUI Screens at run time using the
Copy_Screen
method. Heap screens are described in detail in a later section.
Properties
Table 8‑6 Properties of GUI Screens.
|
|
|
|
|
WIDTH_IN_PIXELS
|
128 pixels
|
Read only. Contains the width of
the screen in pixels.
|
|
HEIGHT_IN_PIXELS
|
128 pixels
|
Read only. Contains the height of the screen in pixels.
|
|
VISIBLE
|
GUI_TRUE,
GUI_FALSE
|
If true, makes the screen visible and sets the last
visible screen’s property to false.
|
|
NUM_OBJECTS
|
Unsigned Long
|
Read only. Contains the number of objects contained in
the screen.
|
|
IN_DISPLAY
|
GUI_TRUE,
GUI_FALSE
|
Read only. TRUE if the screen is in the display memory,
FALSE otherwise. All GUI screens have this property set to GUI_TRUE.
|
|
SCREEN_ADDRESS
|
Extended Address
|
Read only. Contains the address of the rendered image of
the screen and its objects in the display.
|
Methods
Table 8‑7 Methods of GUI Screens.
|
|
|
|
|
|
Load
|
Screen Reference, Object
Reference, X Coordinate, Y Coordinate
|
None
|
Load an object into a screen at
the specified x and y coordinates.
|
|
Un_Load
|
Screen Reference, Object Reference, X Coordinate, Y
Coordinate
|
None
|
Unload an object from a screen at the specified x and y
coordinates.
|
|
Copy_Screen
|
Source Screen Reference, Destination Screen Reference
|
None
|
Copies the contents of the source screen into the
destination screen. The contents of the destination screen are over written.
|
|
Clear
|
Screen Reference
|
None
|
Unloads all objects from the screen and erases the screen.
|
|
Refresh
|
Screen Reference
|
None
|
Re-renders graphics, textboxes and plots in the screen
that have their refresh flags set to true. Sets the refresh flags to false
once the objects have been refreshed.
|
|
Redraw
|
Screen Reference
|
None
|
Re-draws all objects contained in the screen.
|
Errors
Table 8‑8 Errors of GUI Screens.
|
|
|
|
|
HEAP_FULL
|
Load
|
Heap is full. There is no room
to load an object into a GUI Screen.
|
|
INVALID_OBJECT
|
Load, Un_Load
|
The object reference cannot be loaded into a GUI Screen.
|
|
INVALID_SCREEN
|
Load, Un_Load,
Clear,
Redraw,
Refresh,
Copy_Screen
|
The object reference is not a GUI Screen.
|
|
X_OUT_OF_RANGE
|
Load, Un_Load
|
The x coordinate plus the width of the object is greater
than the width of the GUI Screen.
|
|
Y_OUT_OF_RANGE
|
Load, Un_Load
|
The y coordinate plus the height of the object is greater
than the height of the GUI Screen.
|
Each GUI Screen has a corresponding keypad that holds the keys
that animate the screen. GUI_SCREEN0
is associated with GUI_KEYPAD0,
GUI_SCREEN1
is associated with GUI_KEYPAD1, GUI_SCREEN2
is associated with GUI_KEYPAD2,
and GUI_SCREEN3
is associated with GUI_KEYPAD3.
GUI Keypads can contain three different types of keys - action keys, data entry
keys, and shift keys. Each type of key is covered in a later section. Only
the keypad of the visible screen is active (i.e. responds to key presses).
Properties
Table 8‑9 Properties of the GUI
Keypads.
|
|
|
|
|
DATA_ENTRY_EVENT_PROCEDURE
|
Extended Address
|
Execute this user defined event
procedure when a non-overloaded data entry key is pressed or an overloaded
data entry key is pressed and a timeout has been reached. If zero, no event
procedure is executed.
|
|
INT_DATA_ENTRY_EVENT_PROCEDURE
|
Extended Address
|
Execute this user defined event procedure when an
overloaded data entry key is pressed and a timeout has not been reached. If
zero, no event procedure is executed.
|
|
SHIFT_EVENT_PROCEDURE
|
Extended Address
|
Execute this user defined event procedure when any shift
key is pressed. If zero, no event procedure is executed.
|
|
DATA_ENTRY_TEXTBOX
|
Textbox object
|
The textbox that contains the keycodes of pressed data
entry keys.
|
|
SHIFT_STATE_TEXTBOX
|
Textbox Object
|
The textbox that contains a string corresponding to the
shift state.
|
|
KEYPAD_BEEP
|
GUI_TRUE, GUI_FALSE
|
If true, sounds the buzzer when a key is pressed.
|
|
KEYPAD_BEEP_DURATION
|
Unsigned Integer
|
Controls the length of time (in 5 ms intervals) the piezo
electric buzzer is on when a key is pressed. The default value is 1,
corresponding to 5 milliseconds.
|
|
KEY_CODE
|
1 – 255
|
Read only. Contains the key code of the last pressed data
entry key. See the following section on Data Entry Keys for more information
on Key Codes.
|
|
PRIOR_KEY_CODE
|
1 – 255
|
Read only. Contains the key code of the data entry key
that was pressed before the last data entry key.
|
|
KEY_EVENT
|
PRESS_EVENT, HOLD_EVENT, RELEASE_EVENT, NO_EVENT
|
Read only. Contains the last event.
|
|
PRIOR_KEY_EVENT
|
PRESS_EVENT, HOLD_EVENT, RELEASE_EVENT, NO_EVENT
|
Read only. Contains the event that occurred before the
last event.
|
|
KEY_POSITION
|
0 – 15 or 20 – 34
|
Read only. Contains the key position of the last key.
See Table 8‑1 for the key positions on the keypad.
|
|
PRIOR_KEY_POS
|
0 – 15 or 20 – 34
|
Read only. Contains the key position of the key pressed
before the last key.
|
|
KEY_TYPE
|
ACTION_KEY, DATA_ENTRY_KEY, SHIFT_KEY, NO_KEY
|
Read only. Contains the type of key that was last
pressed.
|
|
PRIOR_KEY_TYPE
|
ACTION_KEY, DATA_ENTRY_KEY, SHIFT_KEY, NO_KEY
|
Read only. Contains the type of key that was pressed
before the last key.
|
|
PRESS_NUMBER
|
Unsigned Integer
|
Read only. Contains the number of times the last data
entry key was pressed before a timeout expired.
|
|
SHIFT_STATE
|
SHIFT_UP, SHIFT_NEUTRAL, SHIFT_DOWN
|
Contains the current shift state.
|
Methods
Table 8‑10 Methods of the GUI Keypads.
|
|
|
|
|
|
Insert_Key
|
Keypad Reference, Key Reference,
and Key Position
|
None
|
Inserts a key object into the
specified keypad object at the specified position. Valid positions are shown
in Table 8‑1.
|
Errors
Table 8‑11 Errors of the GUI Keypads.
|
|
|
|
|
INVALID_KEY
|
Insert_Key
|
The specified object reference is
not a valid key.
|
|
INVALID_KEYPAD
|
Insert_Key
|
The specified object reference is
not a valid keypad.
|
|
KEY_POS_OUT_OF_RANGE
|
Insert_Key
|
The specified key position is not
between 0 and 15 or 20 and 34.
|
The GUI_PEN is
a tool used to draw points, lines, and shapes on a screen. You use its Draw
method to draw to the screen, and its properties control how points or lines
are rendered so you don’t have to pass all the optional parameters to the Draw
method.
Properties
Table 8‑12 Properties of the GUI_PEN.
|
|
|
|
|
PEN_TYPE
|
SET, UNSET
|
Determines whether the pen draws
or erases from the screen.
|
|
SHAPE
|
POINT, LINE
|
Determines the shape that is drawn or erased from the
screen.
|
|
TARGET_SCREEN
|
Screen Reference
|
Contains the screen the pen is rendering to.
|
|
LAST_COORDS
|
Unsigned Long
|
Contains the last coordinates passed to the Draw
method. The y coordinate is located in the 16 most significant bits and the
x coordinate is located in the 16 least significant bits.
|
Methods
Table 8‑13 Methods of the GUI_PEN.
|
|
|
|
|
|
Draw
|
X Coordinate, Y Coordinate
|
None
|
Draw or erase a point or a line
onto a screen. If drawing a line, draws from the last coordinate to the
coordinates passed to Draw. To draw a line from an arbitrary point
rather than the last coordinate, place the new coordinate into LAST_COORDS.
|
Errors
Table 8‑14 Errors of the GUI_PEN.
|
|
|
|
|
X_OUT_OF_RANGE
|
Draw
|
The x coordinate is outside of
the width of the screen.
|
|
Y_OUT_OF_RANGE
|
Draw
|
The y coordinate is outside of the height of the screen.
|
The GUI_BUZZER
corresponds to the piezo electric beeper and controls the length of the beep
when the Buzz
method is called. The GUI_BUZZER
is useful for alarms and system notifications.
Properties
Table 8‑15 Properties of the GUI_BUZZER.
|
|
|
|
|
BEEP_TIME
|
Unsigned Long
|
Controls the length of time the
piezo electric buzzer is on during a call to the Buzz method. Only the 16
least significant bits are used. The units of BEEP_TIME
are in TCNTs or 2 microsecond intervals. The default value is 1000,
corresponding to 2 milliseconds.
|
|
BEEPER_ON
|
|
