Changes

This is a new API.

Purpose

The purpose of the S60 HS Content Control API is to provide services to manage the content of the Home screen application.

S60 or Symbian Exceptions

This API is valid for all platforms running on S60 release 5.0 or later.

Emulator support

This API is fully supported in the WINSCW emulator environment.

API description

HS Content Control API is a library API providing services to external Home screen UI components and external S60 applications. Services are provided by the Home screen application and implemented as synchronous method calls.

Use cases

HS Content Control API provides the following services:

  • Get a list of installed widgets

  • Get a list of installed views

  • Get a list of installed application configurations

  • Get a list of widgets included in the active application configuration

  • Get a list of widgets included in a view

  • Get a list of views included in the active application configuration

  • Add a widget to the active view

  • Add a view to the active application configuration

  • Remove a widget from the active screen view

  • Remove a view from the active application configuration

  • Get the active view

  • Get the active application configuration

  • Activate a view

  • Activate an application configuration

  • Request a notification when new widgets, views or application configurations are installed

API class structure


Home screen is an application displaying the user-defined content. Home screen provides a content controller interface defined in the MHsContentController interface class. Content controller interface can be used to modify the Home screen content. Home screen content controller interface for external applications is implemented in the CHsCcApiClient class. CHsCcApiClient connects to Home screen using the Content Control Server API.

External UI (Ext UI) is a UI component that can modify the Home screen content via the controller interface. External UI is implemented as an ECom component implementing the Home screen content control UI interface defined in the MHsContentControlUi interface class. The Home screen content control UI interface UID is 0x20026F51. By implementing notification methods, External UI can receive notifications of the Home screen content changes. External UI implements its full screen UI using a CAknView-based view class and a CCoeControl-based container class.

External application (Ext App) is an external application that wants to modify the Home screen content. External application uses a content controller interface provided by CHsCcApiClient. If External application wants to receive notifications when the Home screen content changes, it implements a content control interface defined by the MHsContentControl interface class.


The CHsContentInfo class defines the data used in the HS Content Control API. It is used to represent the content included in the Home screen application. The Home screen application content is defined with three levels of configurations: application configuration (root level), view configuration and widget configuration. Application configuration can contain one or more view configurations and view configuration can contain zero or more widget configurations. The CHsContentInfo class contains the basic information of a configuration. The CHsContentInfoArray class defines the array of the CHsContentInfo class objects.

Related APIs
  • CAknView
  • CCoeControl
  • CHsCcApiClient
  • CHsContentInfo
  • CHsContentInfoArray
  • MHsContentControl
  • MHsContentControlUi
  • MHsContentController

Using the HS Content Control API

Loading External UI

The Home screen application loads the External UI component via ECom.


.

Launching External UI

The Home screen application launches External UI when the user starts modifying the Home screen content. Extenal UI creates a full screen view and activates it. When Avkon UI FW informs that the view is activated, External UI stores the previously active view, which is activated when External UI is closed.


Closing External UI


External application connection

External application connects to HS Content Control API by constructing the HS Content Control API client. If External application requests notifications when application, view or widget configuration list changes, it must provide a pointer to the observing object ( aControl). Otherwise aControl must be defined as NULL.


Related APIs
  • aControl

Adding a widget to the active Home screen view

A widget can be added to the active Home screen view with the following steps:

  • Get the list of installed widgets by calling the WidgetListL( CHsContentInfoArray& aArray )method, where aArray returns the widget information list.

  • Select a widget from the returned list and call the AddWidgetL( CHsContentInfo& aInfo) method, where aInfo is a widget selected from aArray.

Related APIs
  • aArray
  • aInfo

Removing a widget from the active Home screen view

A widget can be removed from the active Home screen view with the following steps:

  • Get the active Home screen view by calling the ActiveViewL( CHsContentInfo& aInfo ) method, where aInfo returns the active Home screen view information.

  • Get a list of widgets included in the active Home screen view by calling the WidgetListL(CHsContentInfo& aInfo, CHsContentInfoArray& aArray ) method, where aInfo is the returned active Home screen view and aArray returns the list of widgets included in it.

  • Select a widget to be removed and call the RemoveWidgetL(CHsContentInfo& aInfo ) method, where aInfo defines the removed widget.

Related APIs
  • aArray
  • aInfo

Adding a Home screen view to the active Home screen application configuration

A Home screen view can be added to the active Home screen application configuration with the following steps:

  • Get a list of installed views by calling the ViewListL( CHsContentInfoArray& aArray ) method, where aArray returns the view information list.

  • Select a view from the returned list and call the AddViewL( CHsContentInfo& aInfo ) method, where aInfo is a view selected from aArray.

Related APIs
  • aArray
  • aInfo

Removing a Home screen view from the active Home screen application configuration

A Home screen view can be removed from the active Home screen application configuration with the following steps:

  • Get the active Home screen application configuration by calling the ActiveAppL( CHsContentInfo& aInfo ) method, where aInfo returns the active Home screen application configuration information.

  • Get a list of the Home screen views included in the active Home screen application configuration by calling the ViewListL( CHsContentInfo& aInfo, CHsContentInfoArray& aArray ) method, where aInfo defines the active Home screen application configuration and aArray returns the list of the Home screen views included in it.

  • Select a view to be removed and call the RemoveViewL( CHsContentINfo& aInfo ) method, where aInfo defines the removed Home screen view.

Related APIs
  • aArray
  • aInfo

Replacing a widget from the active Home screen view

When the active Home screen view is full, a widget can be replaced from the active Home screen view with the following steps:

  • Get a list of installed widgets by calling the WidgetListL( CHsContentInfoArray& aArray )method, where aArray returns the widget information list.

  • Select a widget to be added from the returned list.

  • Get the active Home screen view by calling the ActiveViewL(CHsContentInfo& aInfo ) method, where aInfo returns the active Home screen view information.

  • Get the list of widgets included in the active Home screen view by calling the WidgetListL(CHsContentInfo& aInfo, CHsContentInfoArray& aArray ) method, where aInfo is the returned active Home screen view and aArray returns the widget information list.

  • Select a widget to be replaced and call the RemoveWidgetL(CHsContentInfo& aInfo ) method, where aInfo defines the removed widget information.

  • Add the selected widget by calling the AddWidgetL(CHsContentInfo& aInfo ) method, where aInfo defines the added widget information.

Related APIs
  • aArray
  • aInfo

Activating a Home screen application configuration

The active Home screen application configuration can be changed with the following steps:

  • Get a list of Home screen application configurations by calling the AppListL( CHsContentInfoArray& aArray ) method, where aArray returns the application configuration list.

  • Select a Home screen application configuration and call the ActivateAppL( CHsContentInfo& aInfo ) method, where aInfo is the selected application configuration.

Related APIs
  • aArray
  • aInfo

Activating a Home screen view

The active Home screen view can be changed with the following steps:

  • Get the active Home screen application configuration by calling the ActiveAppL( CHsContentInfo& aInfo ) method, where aInfo returns the active Home screen application configuration.

  • Get a list of views included in the active Home screen application configuration by calling the ViewListL( CHsContentInfo& aInfo, CHsContentInfoArray& aArray ) method, where aInfo is the returned Home screen application configuration and aArray returns the view information list.

  • Select a Home screen view and call the ActivateViewL( CHsContentInfo& aInfo ) method, where aInfo is the selected Home screen view.

Related APIs
  • aArray
  • aInfo

Error handling

The following status values are used with the HS Content Control API methods:

Error code

Description

KErrNone

Service request completed successfully.

KHsErrorViewFull

When a widget is requested to be added to the active Home screen view and a maximum count of widgets already exists in the active Home screen view.

KHsErrorMaxInstanceCountExceeded

When a widget is requested to be added to the active Home screen view and a maximum count of widget instances already exists in the active Home screen application configuration.

KHsErrorDoesNotFit

When a widget is requested to be added to the active Home screen view and there is not enough space left for it.

Any other system wide error code

Otherwise, normal Symbian leave mechanism is used.

Memory overhead

In case of External UI, memory overhead depends on the implementation of the External UI component. In case of External application, the CHsCcApiClient object is reserved from the External application's process. If there are lots of installed widgets, it may be reasonable to clean the widget array when it is possible.

Related APIs
  • CHsCcApiClient

Extensions to the API

There are no extensions to the API.

Limitations of the API

There are no limitations in the API.