Changes

No changes.

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 UI Controllers

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()
  • CAiUiController
  • GetContentObserver()
  • LoadUiDefinitionL()
  • MAiContentObserver
  • MainInterface()
  • 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()
  • MAiMainUiController
  • RunApplicationL()

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:

  • SetCoeEnv( CCoeEnv& ) is called by the Idle Framework to provide Control Environment with this secondary UI controller.

Related APIs
  • MAiSecondaryUiController

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
  • CAiUiIdleIntegration
  • NewL()

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()
  • ConstructL
  • HandleActivateUI()
  • IdlePhase1Ok
  • MAiFwEventHandler
  • QueryIsMenuOpen()
  • 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
  • MAiFwStateHandler
  • TAiFwPublisherInfo
  • TAiFwState

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
  • TAiFwCallback
  • TAiFwPublisherInfo
  • THsPublisherInfo
  • TInt

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
  • TAiFwCallback
  • TAny

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
  • CAiUiController
  • CAiUiIdleIntegration
  • MAiFwEventHandler
  • MAiFwStateHandler
  • MAiMainUiController
  • MAiSecondaryUiController
  • TAiFwCallback
  • TAiFwPublisherInfo
  • TAiIdleKeySoundConfig

Glossary

Abbreviations

None.

Definitions

None.

References

AI Content Model API Specification

AI Plug-in Management API Specification