Status Pane API Specification

Changes in Status Pane API documentation

1.0 19.10.2006 Approved

Changes in Status Pane API

1.0 First release

Contents

Purpose

The status pane displays status information of the current application and state, as well as general information about the device status, e.g. the signal strength and battery charging. It occupies the top part of the screen. The status pane contains more sub panes. Status pane contents controls provide an API to change the content of the title, context and navigation panes.

The status pane contains the following sub-panes:

  • Title pane

  • Context pane

  • Navigation pane

  • Signal pane

  • Battery pane/universal indicator pane

Every application has its own status pane instance. Status pane and status pane contents controls are created by the application UI framework when an application is constructed. The status pane layout is read from AVKON resources. The layout resource contains also information about the control that is put inside the sub panes.

Constraints

None.

Classification and release information

Status Pane API is an SDK API and part of S60 3rd Edition.

API Description

Status Pane API provides support for accessing the application’s status pane. Status pane contents controls are AVKON controls. Status pane contents controls are dependent of Symbian platform and AVKON UI services. The controls are inside the status pane framework.

The status pane is divided in local application owned and global status pane server owned panes. Applications have direct API to the application owned panes.

The status pane exists outside the current application’s client area. Each pane is a window owning control. This allows the panes to be tiled together, even though they belong to different processes. A container control is used to host the status control for each pane.

Application owned panes are:

  • the title pane.

  • the context pane.

  • the navigation pane.

Status pane server owned panes are:

  • the signal pane.

  • the battery pane.

  • the indicator pane.

  • the Idle layout context pane.

The whole status pane layout and behavior is controlled by the CEikStatusPaneBase class. The status pane base class contains a status pane container to every pane. Every container owns one status pane control.

For details on Application owned panes see the following documentations:

  • Title Pane API

  • Context Pane API

  • Navigation Pane API

Use cases

The main use cases of the Status Pane API are:

  • Defining status pane in resource file

  • Accessing status pane control

  • Accessing a control inside status pane’s sub pane

  • Modifying status pane visibility

  • Changing status pane layout

  • Observing status pane events

API class structure

This diagram shows the relationships between the client application ( CEikAppUi ), the UIKON server ( CEikServAppUi ), the status pane classes ( CEikStatusPaneBase , CEikStatusPane and CEikServStatusPane ) and the resource structure representations (the model classes).

Each UI owns an instance of the status pane (through the application UI factory mechanism) that contains the pane model and contents relevant to it. There are common base classes for the status pane and its model, used by the client applications and the server. Each status pane owns a set of CEikStatusPaneContainer controls, which hold the status pane indicator controls.

UML diagram of Status Pane API


UML diagram of Status Pane API

Related APIs
  • CEikAppUi
  • CEikServAppUi
  • CEikServStatusPane
  • CEikStatusPane
  • CEikStatusPaneBase
  • CEikStatusPaneContainer
Related APIs
  • CEikStatusPaneBase

Status pane API

Defining status pane in resource file

The status panes’s resource definition describes the application’s status pane properties. The resource contains also information about the control that is put inside the sub panes. Status pane’s id and type field values are defined in avkon.hrh . Status pane layout can be optionally defined by the layouts and default_layout fields. In this example status pane’s sub panes are: navigation pane with a label control, and a title pane. 

             
              RESOURCE EIK_APP_INFO
              

                  {
              

                  status_pane = r_app_status_pane;
              

                  }
              

              

              RESOURCE STATUS_PANE_APP_MODEL r_app_status_pane
              

                  {
              

                  panes=
              

                      {
              

                      SPANE_PANE
              

                          {
              

                          id = EEikStatusPaneUidNavi;
              

                          type = EAknCtNaviPane;
              

                          resource = r_navi_decorator;
              

                          },
              

                      SPANE_PANE
              

                          {
              

                          id = EEikStatusPaneUidTitle;
              

                          type = EAknCtTitlePane;
              

                          resource = r_overriden_app_name;
              

                          }
              

                      };
              

                  }
              

              

              RESOURCE TITLE_PANE r_overriden_app_name
              

                  {
              

                  txt = "Title";
              

                  }
              

              

              RESOURCE NAVI_DECORATOR r_navi_decorator
              

                  {
              

                  type = ENaviDecoratorLabel;
              

                  control = NAVI_LABEL
              

                      {
              

                      txt="label";
              

                      };
              

                  }
Related APIs
  • default_layout
  • id
  • layouts
  • type

Accessing status pane

When using Status Pane API, the first step is to access a pointer to the application’s status pane by calling the CAknAppUi::StatusPane() method. CAknAppUi is the base class of the application UI.

The status pane layout is read from AVKON resources. 

             
              // Gets a pointer to the status pane 
              

              CEikStatusPane* sp = StatusPane();
Related APIs
  • CAknAppUi
  • CAknAppUi::StatusPane()

Accessing a control inside status pane’s sub pane

In this example the title pane's text is changed. For checking if a pane is part of the layout, before accessing it, see Status pane layout and capabilities .

iTitlePane is a pointer to CAknTitlePane . 

             
              // Gets a pointer to the status pane 
              

              CEikStatusPane* sp = StatusPane();
              

              

              // Fetch pointer to the title pane control
              

              iTitlePane = ( CAknTitlePane* )sp->ControlL(
              

                             TUid::Uid( EEikStatusPaneUidTitle ));
              

              iTitlePane->SetTextL( _L("New Title") );
Related APIs
  • CAknTitlePane
  • iTitlePane

Modifying status pane visibility

Status pane can be visible, or invisible, so this way the application can be set full screen. 

             
              // Gets a pointer to the status pane 
              

              CEikStatusPane* sp = StatusPane();
              

              

              // Changing status pane visibility to invisible
              

              sp->MakeVisible( EFalse );

Requesting status pane visibility is trivial. 

             
              // Gets a pointer to the status pane 
              

              CEikStatusPane* sp = StatusPane();
              

              

              // Requesting visibility
              

              TBool visible = sp->IsVisible();

Status pane layout and capabilities

Status pane layout can be changed dynamically. Based on the layout, status pane can be small, or defined with different controls, e.g. the signal strength and battery charging.

There are some predefined status pane layouts:

  • R_AVKON_STATUS_PANE_LAYOUT_USUAL

  • R_AVKON_STATUS_PANE_LAYOUT_SMALL

  • R_AVKON_STATUS_PANE_LAYOUT_EMPTY

This example changes the status pane to small layout. Checks if title pane is the part of the current layout, and sets title text. Layouts are defined in avkon.hrh . iTitle pane is a pointer to CAknTitlePane . 

             
              // Gets a pointer to the status pane 
              

              CEikStatusPane* sp = StatusPane();
              

              // Switch layout
              

              sp->SwitchLayoutL( R_AVKON_STATUS_PANE_LAYOUT_SMALL );
              

              

              // After switching layout check if title pane is in current layout.
              

              TBool isTitlepaneInLayout = sp->PaneCapabilities( TUid::Uid( EEikStatusPaneUidTitle ) ).IsInCurrentLayout();
              

              

              // If title pane is in the curent layout, change title text.
              

              if ( isTitlepaneInLayout )
              

                   {
              

                   // Fetch pointer to the title pane control
              

                   iTitlePane = (CAknTitlePane*)sp->ControlL( TUid::Uid(EEikStatusPaneUidTitle));
              

                   iTitlePane->SetTextL( _L("New Title") );
              

                   }
Related APIs
  • CAknTitlePane
  • iTitle

Observing status pane events

Handling status pane events requires that the observing class must be derived from MEikStatusPaneObserver , and the observer must implement method HandleStatusPaneSizeChange() . This event notifies the observer that the status pane size has changed.

Note that CAknAppUi sets itself as observer. If you call SetObserver , then AppUI does not receive those events. So it is not recommended to overwrite observer in case of avkon applications.

In the example, CMyClass observes the status pane events. 

             
              class CMyClass : public CBase, MEikStatusPaneObserver
              

                   {
              

                   …
              

                   // From MEikStatusPaneObserver
              

                   void HandleStatusPaneSizeChange();     
              

                   …
              

                   };

Access the status pane, and set CMyClass as an observer. 

             
              void CMyClass::Construct()
              

                   {
              

                   …
              

                   // Get a pointer to status pane
              

                   CEikStatusPane* sp = STATIC_CAST( CAknAppUi*, CEikonEnv::Static()->EikAppUi() )->StatusPane();
              

                   // Register this object as a status pane observer
              

                   sp->SetObserver( this );
              

                   …
              

                   }

The HandleStatusPaneSizeChange() receives status pane events. 

             
              void CMyClass::HandleStatusPaneSizeChange()
              

                   {
              

                   // Do event handling code here…
              

                   }
Related APIs
  • CAknAppUi
  • CMyClass
  • HandleStatusPaneSizeChange()
  • MEikStatusPaneObserver
  • SetObserver

Error handling

Status Pane API uses standard Symbian platform error reporting mechanism. Possible panic circumstances and panic codes are indicated in class or method descriptions.

Leaves and system wide error codes as function return values are used if the error is recoverable. A client application can handle these errors similarly as a normal Symbian platform application.

Memory overhead

The amount of reserved memory for application owned navigation pane controls depend on the application, but despite the application the amount of reserved memory is relatively small.

Limitations of the API

None.

Glossary

Abbreviations

Status Pane API abbreviations

API Application Programming Interface

AVKON

Extensions and modifications to Uikon and other parts of the Symbian application framework.

Definitions

Status Pane API definitions

Status pane The status pane displays status information of the current application and state, as well as general information about the device status, e.g. the signal strength and battery charging.