Class CQUiConfigClient

class CQUiConfigClient : public CCoeStatic;

Description

CQUiConfigClient is used for accessing UI configurations.

Some API's require communication whith the server (All leaving functions), but most API's operates on a cached TQikUiConfig. The cache is loaded when the client is created and then updated automatically by the server whenever the value changes. This pattern minimizes client/server communication which increases performance and ease of use.

The server startup and session handling is all encapsulated within the client so all API calls can be done directly after successfully creating an instance.

The UI config server is responsible for updating all clients when the current configuration changes. The server also manages the list of supported configurations and handles communication for changing configuration in the device when it is requested from a client.

the list of supported device configurations, validation data for configuration transitions and the default configurations are defined in the server resource.

Derivation

• CBase - Base class for all classes to be instantiated on the heap
• CCoeStatic - Base class for creating singleton objects that will be stored by CCoeEnv
• CQUiConfigClient - CQUiConfigClient is used for accessing UI configurations

Members

Defined in CQUiConfigClient:
AddUiConfigChangeObserverL(), AddUiConfigChangeObserverL(), AddUiConfigChangeObserverL(), AddUiConfigChangeObserverL(), CreateL(), CurrentConfig(), EAfterScreenDeviceUpdated, EAlways, EBeforeScreenDeviceUpdated, ENonCQikViewBaseView, EOnlyNotifyWhenInForeground, ESendDelayedNotificationsWhenGainingForeground, FindBestMatchingConfigL(), GetConfigSupportedByDeviceL(), GetConfigSupportedByDeviceL(), IsConfigSupportedByDeviceL(), IsConfigSupportedByDeviceL(), LockServer(), RemoveUiConfigChangeObserver(), SetClientNotificationPreference(), SetClientNotificationPreference(), SetCurrentConfigL(), SetCurrentConfigL(), SetInteractionStyleL(), SetOrientationL(), SetScreenModeL(), SetTouchScreenL(), SetUiValidationMatrixDebug(), SetUnlockScreenDeviceInBackground(), Static(), Static(), SystemDefaultUiConfigMode(), TNotificationPreference, TNotificationSchedule, UpdateScreenDevice()

Inherited from CBase:
Delete(), Extension_(), operator new()

Inherited from CCoeStatic:
CCoeStatic_Reserved1(), CCoeStatic_Reserved2(), EApp, EDefaultDestructionPriority, EThread, TScope, anonymous

static IMPORT_C CQUiConfigClient &Static();

Description

Symbian style Singleton access method.

It is recommended to minimize the usage of this method (as well as CCoeEnv::Static() or CEikonEnv::Static()) since they invovles retrieval of the CEikonEnv stored in Tls which is an expensive operation.

You should strive to use the overload that takes a CCoeEnv& paramter whereever possible. The aplication environment is available as a protected iCoeEnv varaiable in CCoeControl and CCoeAppUi.

Return value

Panic codes

static IMPORT_C CQUiConfigClient &Static(CCoeEnv &aCoeEnv);

Description

Parameters

Return value

See also:

• CQUiConfigClient::Static()

static IMPORT_C void CreateL();

Description

Factory method to create the CQUiConfigClient singelton instance.

If the singelton is already created, the function will return without creating a new instance and without generating any error.

The singelton is created by the DLL initialization.

Leaves if not enough memory to create the singelton instance.

IMPORT_C TQikUiConfig CurrentConfig() const;

Description

Returns current configuration.

The current configuration is cached in the client but is allways guaranteed to be up to date.

Return value

See also:

• TQikUiConfig

IMPORT_C TInt SetCurrentConfigL(TInt aConfigMode);

Description

Sets current configuration based on specified configuration identifier by calling CQUiConfigClient::SetCurrentConfigL(const TQikUiConfig& aConfig)

Parameters

Return value

IMPORT_C TInt SetCurrentConfigL(const TQikUiConfig &aConfig);

Description

Sets the current UI configuration. Leaves if client fails to communicate with the server.

Be careful not to assume that the requested ui config really is the one that will be used to set current config. The server may redirect the requested ui config if it is not currently available. The redirection choices are product specific.

To find the best matching ui config mode or to change current config to the best match to screen mode, orientation, touch screen or interaction style. Use any of the APIs listed below.

Parameters

Return value

Leave codes

Panic codes

See also:

• SetScreenModeL(TQikScreenMode aScreenMode)
• SetOrientationL(TQikOrientation aOrientation)
• SetInteractionStyleL(TQikInteractionStyle aInteractionStyle)
• SetTouchScreenL(TQikTouchScreen aTouchScreen)
• FindBestMatchingConfigL(TInt aUiConfigIdentifier, TQikUiConfig& aBestMatch)

IMPORT_C TInt SetScreenModeL(TQikScreenMode aScreenMode);

Description

Sets the best fitting ui config mode based on aScreenMode.

This API should be used when only a screen mode change is wanted instead of a complete ui config mode change. This method provides a generic behaviour for downgrading the requested configuration to the best matching configuration that is supported by the device. The downgrade path from CQikUiConfigUtils is used.

The best matching ui config might be redirected in the server if it is not currently available in the system. The rule for redirection is device specific.

If the best matching ui config is wanted without changing current config, FindBestMatchingConfigL should be used instead.

Parameters

Return value

See also:

• SetCurrentConfigL(const TQikUiConfig& aConfig)
• ;
• FindBestMatchingConfigL(TInt aUiConfigIdentifier, TQikUiConfig& aBestMatch)

IMPORT_C TInt SetOrientationL(TQikOrientation aOrientation);

Description

Sets the best fitting ui config mode based on aOrientation.

This API should be used when only a orientation change is wanted instead of a complete ui config mode change. This method provides a generic behaviour for downgrading the requested configuration to the best matching configuration that is supported by the device. The downgrade path from CQikUiConfigUtils is used.

The best matching ui config might be redirected in the server if it is not currently available in the system. The rule for redirection is device specific.

Parameters

Return value

See also:

• SetCurrentConfigL(const TQikUiConfig& aConfig)
• ;

IMPORT_C TInt SetInteractionStyleL(TQikInteractionStyle aInteractionStyle);

Description

Sets the best fitting ui config mode based on aInteractionStyle.

This API should be used when only a interaction style change is wanted instead of a complete ui config mode change. This method provides a generic behaviour for downgrading the requested configuration to the best matching configuration that is supported by the device. The downgrade path from CQikUiConfigUtils is used.

The best matching ui config might be redirected in the server if it is not currently available in the system. The rule for redirection is device specific.

Parameters

Return value

See also:

• SetCurrentConfigL(const TQikUiConfig& aConfig)
• ;

IMPORT_C TInt SetTouchScreenL(TQikTouchScreen aTouchScreen);

Description

Sets the best fitting ui config mode based on aTouchScreen.

This API should be used when only a touch screen change is wanted instead of a complete ui config mode change. This method provides a generic behaviour for downgrading the requested configuration to the best matching configuration that is supported by the device. The downgrade path from CQikUiConfigUtils is used.

The best matching ui config might be redirected in the server if it is not currently available in the system. The rule for redirection is device specific.

Parameters

Return value

See also:

• SetCurrentConfigL(const TQikUiConfig& aConfig)
• ;

IMPORT_C TInt FindBestMatchingConfigL(TInt aUiConfigIdentifier, TQikUiConfig &aBestMatch);

Description

Finds the best matching ui config based on the specified identifiers. This method uses the downgrade path from CQikUiConfigUtils

This API should be used when you need to find the best matching ui config without changing current config.

This example finds the best matching landscape, touch screen configuration from the list of supported ui configurations.

TQikUiConfig config:
FindBestMatchingConfigL(EQikUiConfigLandscape | EQikUiConfigTouchScreenYes, config);

Parameters

Return value

See also:

• SetScreenModeL(TQikScreenMode aScreenMode)
• ;
• SetOrientationL(TQikOrientation aOrientation)
• ;
• SetInteractionStyleL(TQikInteractionStyle aInteractionStyle)
• ;
• SetTouchScreenL(TQikTouchScreen aTouchScreen)
• ;
• CQikUiConfigUtils

IMPORT_C TInt SystemDefaultUiConfigMode();

Description

Returns the unique id for the default UI configuration which may be diffrent on diffrent devices.

Return value

IMPORT_C TBool IsConfigSupportedByDeviceL(TInt aUiConfigMode);

Description

Checks if configuration based on specified configuration id is supported by the device. Leaves if client fails to communicate with the server.

Parameters

Return value

Leave codes

IMPORT_C TBool IsConfigSupportedByDeviceL(const TQikUiConfig &aConfig);

Description

Checks if specified configuration is supported by the device. Leaves if client fails to communicate with the server.

Parameters

Return value

Leave codes

See also:

• TQikUiConfig

IMPORT_C void GetConfigSupportedByDeviceL(RArray< TInt > &aUiConfigModeList);

Description

Returns a list of configurations supported by the device.

Leaves if client fails to communicate with the server. Leaves if not enough memory to allocate the aUiConfigModeList elements.

Parameters

Leave codes

IMPORT_C void GetConfigSupportedByDeviceL(RArray< TQikUiConfig > &aConfigList);

Description

Returns a list of configurations supported by the device.

Leaves if client fails to communicate with the server.

Parameters

Leave codes

IMPORT_C void UpdateScreenDevice();

Description

Update and unlock the CWsScreenDevice so windowserver will display the windowgroup after a screen mode change. After the screen mode is changed, a windowgroup must call this method to confirm support for the new screenmode.

For standard applications, this is taken care of by CQikViewBase.

See also:

• TScreenModeEnforcement

IMPORT_C void SetUnlockScreenDeviceInBackground(TBool aPref);

Description

Enables/disables if the screen device will be unlocked when the client is in the background. This is needed for applications and servers that needs to display UI but does not gain foreground.

Parameters

IMPORT_C void AddUiConfigChangeObserverL(MQUiConfigChangedObserver &aUiConfigChangeObserver);

Description

Adds an observer to the list that will be notified of ui config changes by calling CQUiConfigClient::AddUiConfigChangeObserverL(MQUiConfigChangedObserver& aUiConfigChangeObserver, TNotificationSchedule aSchedule, TNotificationPreference aPreference) with TNotificationSchedule set to EAfterScreenDeviceUpdated and with TNotificationPreference set to ESendDelayedNotificationsWhenGainingForeground .

Parameters

See also:

• CQUiConfigClient::AddUiConfigChangeObserverL(MQUiConfigChangedObserver& aUiConfigChangeObserver, TNotificationSchedule aSchedule, TNotificationPreference aPreference)

IMPORT_C void AddUiConfigChangeObserverL(MQUiConfigChangedObserver &aUiConfigChangeObserver, TNotificationSchedule aSchedule);

Description

Adds an observer to the list that will be notified of ui config changes by calling CQUiConfigClient::AddUiConfigChangeObserverL(MQUiConfigChangedObserver& aUiConfigChangeObserver, TNotificationSchedule aSchedule, TNotificationPreference aPreference) with TNotificationPreference set to ESendDelayedNotificationsWhenGainingForeground .

Parameters

See also:

• CQUiConfigClient::AddUiConfigChangeObserverL(MQUiConfigChangedObserver& aUiConfigChangeObserver, TNotificationSchedule aSchedule, TNotificationPreference aPreference)

IMPORT_C void AddUiConfigChangeObserverL(MQUiConfigChangedObserver &aUiConfigChangeObserver, TNotificationPreference aPreference);

Description

Adds an observer to the list that will be notified of ui config changes by calling CQUiConfigClient::AddUiConfigChangeObserverL(MQUiConfigChangedObserver& aUiConfigChangeObserver, TNotificationSchedule aSchedule, TNotificationPreference aPreference) with TNotificationSchedule set to EAfterScreenDeviceUpdated .

Parameters

See also:

• CQUiConfigClient::AddUiConfigChangeObserverL(MQUiConfigChangedObserver& aUiConfigChangeObserver, TNotificationSchedule aSchedule, TNotificationPreference aPreference)

IMPORT_C void AddUiConfigChangeObserverL(MQUiConfigChangedObserver &aUiConfigChangeObserver, TNotificationSchedule aSchedule, TNotificationPreference aPreference);

Description

Adds an observer to the list that will be notified of ui config changes.

Views should use the ENonCQikViewBaseView schedule. Views that inherit from CQikViewBase don't need to add themselves as observers as the framework does that (that's the reason for the bad naming of ENonCQikViewBaseView - that only views not inheriting from CQikViewBase needs to add as observer).

If a CQikViewBase needs to be updated in the background it is possible to add it as a EAlways observer, it will still only receive one notification for each change. Only do this if absolutely necessary since it affects performance badly.

Parameters

IMPORT_C void RemoveUiConfigChangeObserver(const MQUiConfigChangedObserver &aUiConfigChangeObserver);

Description

Removes an observer from the list that will be notified of ui config changes.

Parameters

IMPORT_C void SetClientNotificationPreference(TNotificationPreference aPref);

Description

Set the notification behavior on all observers in this threads CQUiConfigClient. Default is ESendDelayedNotificationsWhenGainingForeground.

When ESendDelayedNotificationsWhenGainingForeground is selected, notifications are hold while this application is in the background and is sent out next time this application gains foreground.

Use CQUiConfigClient::SetClientNotificationPreference(TNotificationPreference aPref, MQUiConfigChangedObserver& aUiConfigChangeObserver) to change a single observer.

Parameters

IMPORT_C void SetClientNotificationPreference(TNotificationPreference aPref, const MQUiConfigChangedObserver *aObserver);

Description

Set the notification behavior on a specific observer. Default is ESendDelayedNotificationsWhenGainingForeground.

When ESendDelayedNotificationsWhenGainingForeground is selected, notifications are hold while this application is in the background and is sent out next time this application gains foreground.

Use CQUiConfigClient::SetClientNotificationPreference(TNotificationPreference aPref) to change all observer.

Parameters

IMPORT_C TInt SetUiValidationMatrixDebug(TBool aDebug) const;

Description

Use this method to enable the debug UI validation matrix. Using the debug UI validation removes all UI config change restrictions (You still cannot change screenmode). UDEB only, does nothing in UREL

Parameters

Return value

IMPORT_C TInt LockServer(TBool aLock);

Description

Use this method to flush the current UI configuration to all applications(also those in the background) and make the server refuse changing UI configuration until it has been unlocked.

Parameters

Return value

TNotificationSchedule

Description

TNotificationPreference

Description