Documentation  |   Table of Contents   |  < Previous   |  Next >   |  Index

33    Status Bar Reference

User Interface

Exploring Palm OS®

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 ^TOP^

Error Code Constants ^TOP^

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 ^TOP^

Purpose

Status bar attribute values that you pass as a parameter to StatGetAttribute().

Declared In

StatusBar.h

Constants

statAttrBarVisible
StatGetAttribute() returns a Boolean value of true to indicate the status bar is currently visible or false to indicate the status bar is currently hidden.
statAttrDimension
StatGetAttribute() returns a pointer to a RectangleType structure that gives the dimensions in active coordinates of the status bar.

Status Bar Functions and Macros ^TOP^

StatGetAttribute Function ^TOP^

Purpose

Retrieves the value of a status bar attribute.

Declared In

StatusBar.h

Prototype

status_t StatGetAttribute (
   StatAttrType selector,
   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:

sysErrParamErr
The dataP parameter is NULL or the selector is an unknown value.

StatHide Function ^TOP^

Purpose

Hides the status bar.

Declared In

StatusBar.h

Prototype

status_t StatHide (
   void
)

Parameters

None.

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 ^TOP^

Purpose

Displays the status bar or ensures that the status bar is being displayed.

Declared In

StatusBar.h

Prototype

status_t StatShow (
   void
)

Parameters

None.

Returns

Always returns errNone.

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.