Idle Fw API
Changes in 5.2 Idle Fw API documentation
| Version |
Date |
Status |
Description |
|
1.0
|
10.06.2010
|
Approved
|
|
Purpose
The Idle Fw API provides interfaces that allow its clients (UI controllers)
to access the Idle Framework services. These services are related to content
publisher plug-ins' life cycle management and event handling. The API provides
an access for controlling a subset of the Idle Framework's state machine.
The Idle Fw API also defines an abstract base class for UI controllers
and interfaces for main and secondary UI controllers. These APIs allow the
Idle Framework to own and control UI controllers that are implemented in the
Idle Home screen collection.
S60 or Symbian Exceptions
This API is valid for all platforms running on S60 release 5.2 or later.
Emulator support
This API is fully supported in the WINSCW emulator environment.
API description
The Idle Fw API can be categorized as Framework and Library API.
From a Framework API point of view, it provides an abstract base class
for UI controllers and interfaces for separating main and secondary UI controllers
from each other. With these interfaces, Idle Framework rules a protocol which
defines communication between Idle Framework and UI controllers from the Idle
Home screen collection. The clients of this API are the instances implementing
UI controllers. Idle Framework instantiates UI controllers using the ECom
architecture.
From a Library API point of view, the Idle Fw API provides interfaces for
its clients (UI controllers) to access the Idle Framework services. Services
are mainly related to content publisher plug-ins' life cycle management (load,
destroy and state management) and routing events from the UI layer to content
publisher plug-ins. The API provides also an integration interface for the
main UI controller. This interface is used to provide a common functionality
for the main UI controller.
Use cases
The most important use cases of the Idle Fw API are:
-
Creating and destroying UI controller(s)
-
Handling UI activation and deactivation
-
Loading and destroying content publisher plug-ins from UI controller(s)
-
Changing a subset of content publisher plug-ins state
-
Forwarding events from UI controllers to content publisher plug-ins
-
Creating Idle Integration implementation
API class structure
The following diagram illustrates the services provided by the Idle Fw
API.
Using the Idle Fw API
The Idle Fw API consists of the following APIs:
-
CAiUiController
-
MAiMainUiController
-
MAiSecondaryUiController
-
CAiUiIdleIntegration
-
MAiFwEventHandler
-
MAiFwStateHandler
-
TAiFwPublisherInfo
-
TAiFwCallback
-
TAiIdleKeySoundConfig
The APIs are explained in a more detailed level in the following chapters.
Using CAiUiController
CAiUiController acts as an abstract base class for
UI controllers. A subclass, which is derived from the CAiUiController class,
must implement the following pure virtual methods:
-
LoadUiDefinitionL() is called by the Idle Framework to
instruct the UI controller to load its static UI definition.
-
GetSettingsL( const THsPublisherInfo&, RAiSettingsItemArray&
) is called by the Idle Framework to get settings for a content publisher
plug-in during its construction phase. Refer to AI Plug-in Management
API Specification for further details on the content publisher plug-ins.
-
ActivateUI() is called by the Idle Framework to activate
the main UI controller's UI.
-
GetContentObserver() is called by the Idle Framework
to get content observer interface, which is MAiContentObserver,
implemented by this UI controller. Framework passes the function's return
value to the content publisher plug-in. Refer to AI Plug-in Management
API Specification for further details on the content publisher plug-ins and
content observers.
-
SetEventHandler( MAiEventHandler& ) is called by
the Idle Framework to pass event handler interface for this UI controller.
-
SetStateHandler( MAiFwStateHandler& ) is called by
the Idle Framework to pass state handler interface for this UI controller.
-
MainInterface() is called by the Idle Framework to access
the Main UI controller interface. The UI controller must return a pointer
to the main interface (usually this pointer) if the UI controller is running
as main. If the UI controller is not running as main, then this method must
return NULL.
-
SecondaryInterface() is called by the Idle Framework
to access the Secondary UI controller interface. The UI controller must return
a pointer to the secondary interface (usually this pointer) if the UI controller
is running as secondary. If the UI controller is not running as secondary,
then this method must return NULL.
Related APIs
ActivateUI()CAiUiControllerGetContentObserver()LoadUiDefinitionL()MAiContentObserverMainInterface()SecondaryInterface()
Using MAiMainUiController
The UI controller that is running as a main interface must be derived from
the
MAiMainUiController class. The subclass must implement
the following pure virtual methods:
-
RunApplicationL() is called by the Idle Framework when
UI controller should start application framework and application event loop.
Usually the UI controller calls EikStart::RunApplication() in
this method. This method returns when the application is shut down.
-
CoeEnv() is used by the Idle Framework to access the
Control Environment object this main UI controller uses.
-
Exit() is used by the Idle Framework to instruct this
main UI controller to exit its application event loop.
-
IsMenuOpen() is used by the Idle Framework to query whether
there is menu or dialog displaying in the AppUi.
Related APIs
CoeEnv()EikStart::RunApplication()Exit()IsMenuOpen()MAiMainUiControllerRunApplicationL()
Using MAiSecondaryUiController
The UI controller that is running as a secondary interface must be derived
from the
MAiSecondaryUiController class. The subclass must
implement the following pure virtual methods:
Related APIs
Using CAiUiIdleIntegration
The UI controller, which is running as a main interface, must instantiate
an instance from the
CAiUiIdleIntegration class. The CAiUiIdleIntegration implementation
provides common functionality for all UI controllers.
-
NewL() . Static factory function.
-
HandleWsEventL( const TWsEvent&, CCoeControl* ).
The main UI controller must pass all Window server events to this interface.
Related APIs
CAiUiIdleIntegrationNewL()
Using MAiFwEventHandler
The Idle Framework passes the
MAiFwEventHandler interface
to all of its UI controllers during their construction phase. This interface
can be used to pass events from UI controllers to Idle Framework. The Idle
Framework implements the following pure virtual methods:
-
AppEnvReadyL(). The main UI controller must call this
method when it has Control Environment initialized and ready; usually this
method is called in the end of the AppUi's ConstructL method.
-
HandleUiReadyEventL( CAiUiController& ). A UI controller
must call this method when its startup-related activities are ready. The Idle
Framework sets the startup domain PS key, IdlePhase1Ok, to
notify System Starter to continue the phone startup.
-
HandleActivateUI() method is called by the Idle Integration
implementation when Startup Domain Publish and Subscribe key UIStartupPhaseAllDone is
set by System Starter. This method will call internally CAiUiController::ActivateUI().
-
HandleUiShutdown( CAiUiController& ). A UI controller
must call this method during its shutdown sequence.
-
HandlePluginEvent( const TDesC& ). A UI controller
uses this interface to pass events to content publisher plug-ins. The Idle
Framework extracts the plug-in information from the parameter. Notice that
this method overload does not uniquely identify the target plug-in, hence
if overlapping plug-ins are present, there is no guarantee which plug-in is
invoked to handle the event.
-
HandlePluginEvent( const THsPublisherInfo&, const TDesC&
). A UI controller uses this interface to pass events to the content
publisher plug-in. The plug-in is uniquely identified by the method's first
parameter.
-
HasMenuItemL( const THsPublisherInfo&, const TDesC& ).
A UI controller can use this interface to query whether the content publisher
plug-in has a menu item to show in the UI controllers UI. The plug-in is uniquely
identified by the method's first parameter.
-
RefreshContent( const TDesC& ). A UI controller can
use this interface to request a content publisher plug-in to refresh (republish)
data from a specified content item ID. The Idle Framework extracts the plug-in
information from the parameter. Notice that this method overload does not
uniquely identify the target plug-in, hence if overlapping plug-ins are present,
there is no guarantee which plug-in is invoked to handle the event. Refer
to AI Content Model API Specification for further information about content
model.
-
RefreshContent( const THsPublisherInfo&, const TDesC&
). A UI controller can use this interface to request a content publisher
plug-in to refresh (republish) data from a specified content item ID. The
plug-in is uniquely identified by the method's first parameter. Refer to
AI Content Model API Specification for further information about content model.
-
SuspendContent( const THsPublisherInfo&, const TDesC&
). A UI controller can use this interface to request a content publisher
plug-in to suspend data publishing from a specified content item ID. The plug-in
is uniquely identified by the method's first parameter. Refer to AI Content
Model API Specification for further information about content model.
-
QueryIsMenuOpen() The Idle Framework can query from the
UI controller whether it is currently displaying menu or dialog.
Related APIs
AppEnvReadyL()CAiUiController::ActivateUI()ConstructLHandleActivateUI()IdlePhase1OkMAiFwEventHandlerQueryIsMenuOpen()UIStartupPhaseAllDone
Using MAiFwStateHandler
The Idle Framework passes the
MAiFwStateHandler interface
to UI controllers during their construction phase. This interface can be used
to control content publisher plug-ins' life cycle in the Idle Framework. It
also provides an interface to control a subset of the Idle Framework's internal
state machine. The Idle Framework implements the following pure virtual methods:
-
LoadPlugin( const TAiFwPublisherInfo& ). A UI controller
can use this interface to request the Idle Framework to load a content publisher
plug-in specified by the parameter TAiFwPublisherInfo.
-
DestroyPlugin( const TAiFwPublisherInfo& ). A UI
controller can use this interface to request the Idle Framework to destroy
a content publisher plug-in specified by the parameter TAiFwPublisherInfo.
-
ChangePluginState( TAiFwState ) A UI controller can use
this interface to request the Idle Framework to change its internal state
based on the parameter TAiFwState. A state change in the
Idle Framework state machine is always reported to the content publisher plug-ins
that are active at the time when this method is called.
Related APIs
MAiFwStateHandlerTAiFwPublisherInfoTAiFwState
Using TAiFwPublisherInfo
The UI controllers and the Idle Framework use the
TAiFwPublisherInfo class
to encapsulate information that is required for loading or destroying a content
publisher plug-in. TAiFwPublisherInfo contains the following
data fields:
-
THsPublisherInfo. Publisher information, which uniquely
identifies the content publisher plug-in to be loaded or destroyed. Refer
to AI Plug-in Management API Specification for further details.
-
TAiFwCallback. Callback function that is called when
a content publisher plug-in handling is complete. The callback function's
second parameter is used to tell the result of the action.
-
TInt. Reason for loading / destroying a content
publisher plug-in. Possible reason values are listed in the
Related APIs
TAiFwCallbackTAiFwPublisherInfoTHsPublisherInfoTInt
Using TAiFwCallback
The
TAiFwCallback class encapsulates a callback function
and a pointer to the TAny type, which is used to notify the
caller of a completion of content publisher plug-in handling.
Related APIs
Using TAiIdleKeySoundConfig
The
TAiIdleKeySoundConfig class is used to pass key sound
context and resources from the main UI controller to CAiUiIdleIntegration.
Related APIs
CAiUiIdleIntegration.TAiIdleKeySoundConfig
Error handling
Normal Symbian error handling practises are used.
Memory overhead
Implementations should follow the convention to minimize RAM consumption.
Extensions to the API
The Idle Fw API does not support extensions.
Limitations of the API
There are no limitations in the API.
Related APIs
CAiUiControllerCAiUiIdleIntegrationMAiFwEventHandlerMAiFwStateHandlerMAiMainUiControllerMAiSecondaryUiControllerTAiFwCallbackTAiFwPublisherInfoTAiIdleKeySoundConfig
References
|
AI Content Model API Specification
|
|
|
AI Plug-in Management API Specification
|
|