HS Content Control API
Changes in HS Content Control API documentation
| Version |
Date |
Status |
Description |
|
1.0
|
17.05.2010
|
Approved
|
|
ChangesThis is a new API.
PurposeThe purpose of the S60 HS Content Control API is to provide services to
manage the content of the Home screen application.
S60 or Symbian ExceptionsThis API is valid for all platforms running on S60 release 5.0 or later.
Emulator supportThis API is fully supported in the WINSCW emulator environment.
API descriptionHS 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 casesHS 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
CAknViewCCoeControlCHsCcApiClientCHsContentInfoCHsContentInfoArrayMHsContentControlMHsContentControlUiMHsContentController
Using the HS Content Control API
Loading External UIThe Home screen application loads the External UI component via ECom.
.
Launching External UIThe 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.
External application connectionExternal 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
Adding a widget to the active Home screen viewA 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
Removing a widget from the active Home screen viewA 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
Adding a Home screen view to the active Home screen application configurationA 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
Removing a Home screen view from the active Home screen application configurationA 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
Replacing a widget from the active Home screen viewWhen 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
Activating a Home screen application configurationThe 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
Activating a Home screen viewThe 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
Error handlingThe 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 overheadIn 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
Extensions to the APIThere are no extensions to the API.
Limitations of the APIThere are no limitations in the API.
Copyright ©2010 Nokia Corporation and/or its subsidiary(-ies). All rights reserved. License: EPL
|