This chapter provides reference material for the status bar API:
Status Bar Constants
Status Bar Functions and Macros
The header file StatusBar.h
declares the API that this chapter describes.
Status Bar Constants
Error Code Constants
Purpose
Errors returned by the status bar functions.
Declared In
StatusBar.h
Constants
-
#define statErrInputWindowOpen (statErrorClass | 3)
- An attempt was made to hide the status bar, but the dynamic input area is open. The status bar can only be hidden if the input area is closed.
-
#define statErrInvalidLocation (statErrorClass | 1)
- Not currently used.
-
#define statErrInvalidName (statErrorClass | 2)
- Not currently used.
StatAttrType Enum
Purpose
Status bar attribute values that you pass as a parameter to StatGetAttribute()
.
Declared In
StatusBar.h
Constants
-
statAttrBarVisible
-
StatGetAttribute()
returns a Boolean value oftrue
to indicate the status bar is currently visible orfalse
to indicate the status bar is currently hidden. -
statAttrDimension
-
StatGetAttribute()
returns a pointer to aRectangleType
structure that gives the dimensions in active coordinates of the status bar.
Status Bar Functions and Macros
StatGetAttribute Function
Purpose
Retrieves the value of a status bar attribute.
Declared In
StatusBar.h
Prototype
status_t StatGetAttribute ( StatAttrTypeselector
, uint32_t*dataP
)
Parameters
-
→ selector
- One of the
StatAttrType
constants. -
← dataP
- The value of the specified status bar attribute.
Returns
errNone
upon success, or one of the following:
StatHide Function
Purpose
Declared In
StatusBar.h
Prototype
status_t StatHide ( void )
Parameters
Returns
errNone
upon success or one of the following:
-
statErrInputWindowOpen
- The device contains a dynamic input area and the dynamic input area is open. The status bar can only be hidden if the dynamic input area is closed.
Comments
Applications should only hide the status bar if there is a very good reason to make the application entirely full screen. For example, a game application might need as much of the screen as possible and may choose to hide the status bar as well as the input area.
If you do hide the status bar, you must provide a way for the user to exit your application, either through your user interface or by using a hard key. You must also show the status bar again upon application exit.
Note that devices that do not have a dynamic input area in general show the status bar only when the Launcher application is active.
StatShow Function
Purpose
Displays the status bar or ensures that the status bar is being displayed.
Declared In
StatusBar.h
Prototype
status_t StatShow ( void )
Parameters
Returns
Comments
You might use this function to start displaying the status bar again after a previous call to StatHide()
.
TIP: If you want the status bar to display on devices without a dynamic input area while your application runs, set the minimum size constraint for each form to be less than 160 coordinates high.