Skins API SpecificationChanges in Skins API documentation
Changes in Skins API
PurposeThe principal use of Skins API is using of AVKON Skins in applications and components that need to be made skin-aware. Skins API provides functionality to skin support in the AVKON UI controls. Skins can be used either application-wide or on per-component basis. The skin-aware AVKON UI controls include:
Skins API supports common operations. It provides utility methods to initialize skins support, retrieve a pointer to the current skin instance or data context, and to perform other skin-related tasks. API descriptionSkins API provides services for UI controls and applications. These services consist of:
To make a UI control (for example, one defined by the application itself) skin-aware, it may be necessary to modify its drawing code. For example, if a control clears its background, it must be done using a method provided by AVKON Skins. To make a UI control use resources provided by the skins (for example, bitmaps), the control must be modified so that it retrieves the resources using AVKON Skins interfaces and reacts properly to the skin change event. Any container that occupies the full main pane (or pop-up window) needs to be modified to provide a skin control context. This is done to specify how layout backgrounds are used by its child controls. AVKON Skins also provides means to cache skin item data objects and to control the lifetime of a cached item data object. It is up to the application (or UI control), whether it will or will not take advantage of these. Each skin item represents a single resource (i.e., bitmap or application icon) that can be retrieved using the AVKON Skins interfaces. A skin item is identified by its identifier. Item identifiers are common among all skin packages. They are mapped to concrete resources (skin item data objects) using skin item definitions. Item definitions for system-wide skin items are stored and managed by Skins Server. Most applications and components have, however, no reason to do so. Typically, a UI component needs to obtain or construct an item data object by providing the corresponding item ID to the AVKON Skins subsystem. An item data object (or a resource instance extracted from it) is returned to the caller. Skins API supports only Symbian skins. If application needs skinning of its own bitmaps, it has to implement skinning. Skin drawingProvides utility methods to perform skin-aware drawing operations, such
as background drawing for a UI control. Contains the following class:
Related APIs
Skin utilitySupports AVKON Skins common operations. AknsUtils provides utility methods
to initialize skins support, retrieve a pointer to the current skin instance
or data context, and to perform other skin-related tasks. Contains the following
class:
Related APIs
Wallpaper utilityA utility class for manipulating the Idle state wallpaper. Contains the
following class:
Related APIs
Control contextIn order to maintain binary compatibility and to avoid passing additional
parameters to child controls, skins support relies on context information
passed in the control hierarchy using the
For example, when the
The entity that provides the control context is usually the one that represents the layout element that defines the background to be used. For the status pane and control pane, the control context is provided by their implementation. For the main pane, the control context may be provided by the system classes (for instance, when an AVKON control covering the entire main pane is used), but in other cases should be provided by the application. The proper place for this is usually the container that occupies the main pane. If no control context is found, the drawing operations provided by AVKON Skins function as the corresponding methods in Symbian OS UI Graphics Utilities. This ensures backwards compatibility with applications that are not aware of the skins support even if they use controls that take advantage of AVKON Skins. Contains the following classes:
Related APIs
Item dataThe skin instance takes care of updating cached item data objects when item definitions change and they are owned (and therefore deleted) by the skin instance. The caller is responsible for updating independent objects. If the UI control can be drawn even when the skin instance singleton is
not available (for example, during an AppUi destroyer), it must handle situations
when skin support is not available and
Contains the following classes:
Related APIs
Use casesThe main use cases of Skins API are:
Using Skins APIEnabling skin support in an applicationGenerally, if the entire layout area (i.e. status pane, control pane, main pane or pop-up window) is drawn by a single AVKON control, which already provides the necessary parameters, there is no need for significant application changes at all. Always enable skins in application level. This can be done either application-wide or on a component-by-component basis:
It is also possible to enable skins for a skin providing control, but not all controls supports this method.
Accessing application skin instanceThe skins enabled Symbian application framework constructs a singleton object called a skin instance for every application. It performs several fundamental operations related to skin support. Firstly, the skin instance performs skin item lookup and data construction. This involves querying the item definition from Skins Server and using the item data factory to construct the item data object. Secondly, the skin instance maintains the item data cache. If the caller requests a cached item data object, it is stored in the cache and any skin change triggers automatic reconstruction. Thirdly, local item definitions are managed by the skin instance. An application may set local item definitions that are visible only within its own thread. In this example, application supports skins, and a pointer to the application’s skin instance is requested.
Providing control context and drawing background
The container may optionally provide a data context to ensure that skin items reserved by it and its child controls are released properly when the container goes out of scope. To provide data context, the container must override the
Creates the control context with a defined background ID.
Modifies the container’s
Updates the position in container’s
Related APIs
Accessing item data objectsSkin item data is constructed and cached if necessary, based on the item definition available from the local definition list or, if not found there, the shared memory chunk lookup provided by AVKON Skins Server. A pointer to the cached item data object is returned to the caller. In this example scrollbar's top background skin element is accessed. The
returned
Accesses the bitmap in skin item data.
In the case of a bitmap item, the same can be performed with much less
code by using
Related APIs
Accessing cached item data objectsUtility methods should be used to facilitate, for example, fetching bitmap type skin item data.
Skin items of the image type (such as bitmaps) can also be drawn directly
using the
Related APIs
Setting idle state wallpaper
Related APIs
Using other skin utilitiesCreates an independent copy by the given item ID, and creates a
A faster method to create a
Gets an application icon supporting scalable graphics. This example gets the icon of the calculator application.
This utility method creates an independent (in terms of instance ownership) copy of a masked bitmap by the given item ID and applies color-based skinning to it.
This example gets the text color of the main area in the current skin context. Color groups and indexes can be found in the file AknsConstants.h.
Related APIs
Error handlingSkins API uses standard Symbian OS error reporting mechanism. Possible panic circumstances and panic codes are indicated in class or method descriptions. There are also API methods that cannot be allowed to leave, e.g. utility methods used during drawing operations. These methods either fail silently or return an error value as specified in their documentation in C++ header file comments. Memory overheadA skin instance object is allocated for every application thread. This causes minor heap consumption, estimated to be approximately 100 bytes per application thread. In addition, local item definitions and cached item data objects demand heap causing variable heap consumption depending on the size and number of objects allocated. The application should consider deleting bitmaps when no longer needed. GlossaryAbbreviationsSkins API abbreviations
Related APIs
Skins API definitions
Related APIs
Copyright ©2010 Nokia Corporation and/or its subsidiary(-ies). All rights reserved. License: EPL
|