Qtopia Home - Classes - Hierachy - Annotated - Functions - Qt Embedded |

# ContextBar Class Reference

The ContextBar class allows the context label in the phone context bar to be set. More...

`#include <qtopia/contextbar.h>`

List of all member functions.

## Public Members

- enum EditingState { Modal = 1, NonModal = 2, ModalAndNonModal = 3 }
- enum StandardLabel { NoLabel, Options, Ok, Edit, Select, View, Cancel, Back, BackSpace, Next, Previous }

## Static Public Members

- void setLabel ( QWidget * w, int key, const QString & pm, const QString & t, EditingState state = ModalAndNonModal )
- void setLabel ( QWidget * w, int key, StandardLabel label, EditingState state = ModalAndNonModal )
- void clearLabel ( QWidget * w, int key, EditingState state = ModalAndNonModal )
- const QArray<int> & keys ()

## Detailed Description

The ContextBar class allows the context label in the phone context bar to be set.

ContextBar is only available in the Qtopia phone edition. It is used to set the text in the context bar to describe the action performed when pressing the associated context button. Keep in mind that not all phones have soft keys and therefore may not have a visible context bar. The application should be useable without soft key shortcuts.

The context labels are updated whenever a widget gains or loses focus or their modal editing state changes. Therefore, the labels should be set for each widget that may gain focus, and will respond to a context key. The standard Qt and Qtopia widgets set the labels appropriately, so this is usually only necessary for custom widgets.

The rule for determining what label is displayed on the context bar and where the key events are delivered is:

- If the current focus widget has claimed the key, then the corresponding context label is shown.
- Otherwise, the widget's parent, grandparent and so on may set the label.
- If the focus widget has not claimed the key and an ancestor has, then the key event will be sent directly to the ancestor.

ContextBar labels specify both a pixmap and a text label. Currently, Qtopia Phone Edition will always use the pixmap rather than text. The text label must still be provided because future versions of Qtopia Phone Edition may allow the user to choose to view text labels.

ContextBar is only available in the Qtopia Phone Edition.

See also Qtopia Phone Classes.

## Member Type Documentation

### ContextBar::EditingState

- `ContextBar::Modal` - apply the label setting when in Modal editing state.
- `ContextBar::NonModal` - apply the label setting when in Nonmodal editing state.
- `ContextBar::ModalAndNonModal` - apply the label setting regardless of editing state.

### ContextBar::StandardLabel

- `ContextBar::NoLabel`
- `ContextBar::Options`
- `ContextBar::Ok`
- `ContextBar::Edit`
- `ContextBar::Select`
- `ContextBar::View`
- `ContextBar::Cancel`
- `ContextBar::Back`
- `ContextBar::BackSpace`
- `ContextBar::Next`
- `ContextBar::Previous`

## Member Function Documentation

### void ContextBar::clearLabel ( QWidget * w, int key, EditingState state = ModalAndNonModal )`[static]`

Clears any label set for widget w, key key in state state.

See also setLabel().

### const QArray<int> & ContextBar::keys ()`[static]`

Returns the list of context keys.

### void ContextBar::setLabel ( QWidget * w, int key, const QString & pm, const QString & t, EditingState state = ModalAndNonModal )`[static]`

When widget w gains focus, sets the label in the context bar for key key to text t and pixmap pm when in state state.

The pixmaps used in the context bar may be no larger than 22x16 pixels.

### void ContextBar::setLabel ( QWidget * w, int key, StandardLabel label, EditingState state = ModalAndNonModal )`[static]`

When widget w gains focus, sets the label in the context bar for key key to the standard label label when in state state.

This file is part of the Qtopia platform, copyright © 1995-2004 Trolltech, all rights reserved.