/*

* Copyright (c) 2002-2006 Nokia Corporation and/or its subsidiary(-ies).

* All rights reserved.

* This component and the accompanying materials are made available

* under the terms of "Eclipse Public License v1.0"

* which accompanies this distribution, and is available

* at the URL "http://www.eclipse.org/legal/epl-v10.html".

*

* Initial Contributors:

* Nokia Corporation - initial contribution.

*

* Contributors:

*

* Description:  Interface for fetching certain system settings in UI controls.

*

*/

#ifndef AKN_SETTING_CACHE_H

#define AKN_SETTING_CACHE_H

// INCLUDES

#include <e32base.h>

#include <AknLayoutDef.h> // for TAknLayoutId

#include <AknDef.h> // for TAknUiZoom

// CONSTANTS

// FORWARD DECLARATIONS

// CLASS DECLARATIONS

/**

* Interface for implementing setting cache plugins, provided by AppUi clients. 

* The plugin mechanism offers clients the ability to register themselves with 

* the AppUi, so that client specific settings can be updated when necessary, 

* and so that the plugin can report that a change has occurred to those settings. 

* The plugin can also cache the value of the setting, and report it when requested,

* although in practice the AppUi would have to know about the setting in order to 

* know what to do with it.

*

* The idea is that there may be a single setting whose current value can in principle 

* be controlled by a number of clients. At any one time, one of those clients has the 

* right to control the actual value of the setting, but each of the other clients may

* need to listen to other events in order to keep their values up to date. The clients 

* are arranged in a stack, so that the most recently added client overrides the values

* that are managed by the previously added clients.

*

* The plugins can handle specific event IDs, for example @c KAknLocalZoomLayoutSwitch. 

* When the setting cache is updated, for example during a layout switch event, 

* the plugins are asked to update their own cached values (in the order of the stack). 

*

* The first plugin that claims to handle the event id, and successfully updates, 

* is then asked for its value; however all other plugins will still get a chance to update. 

*

* It is possible to de-register from the middle of the stack (although in 

* practice clients should ensure that the stacking corresponds logically to 

* their own application context). 

*

* Consult the document S60 AVKON Zoom Design Document for a description of how 

* this API can be used to implement local zoom functionality by handling the 

* @c KAknLocalZoomLayoutSwitch event id.

*

* @lib avkon.lib

* @since 3.1

* @internal to S60

*/

class MAknSettingCacheUpdatePlugin

    {

    public:

        /**

        * Report whether the plugin handles a given event id. Resgistered 

        * plugins are queried in order of most recent registration. @c Update is 

        * only called on the plugin if it claims to handle the event id.

        * @param aEventId event id to be queried

        * @return ETrue if the event id is handled

        */

        virtual TBool HandlesEvent(TInt aEventId) const = 0;

        /**

        * Update the setting cache plugin's cached values,

        * and report whether any values were changed. If this plugin is not 

        * the most recently registered plugin (that handles a given event id) 

        * the return value will be ignored.

        * @param aEventId event id to be processed

        * @return ETrue if the event has caused an update, EFalse otherwise

        */

        virtual TBool Update(TInt aEventId) = 0;

        /**

        * Return the value that is being managed by this plugin for the 

        * specified event. 

        * @param aEventId the event id

        * @param aValue output the value

        * @return KErrNone if there was no error.

        */

        virtual TInt GetValue(TInt aEventId, TInt& aValue) const = 0;

    };

/**

* Interface for fetching certain system settings in UI controls.

* AknEnv owns an instance of this.

*

* @lib avkon.dll

* @since 2.0

* @internal to S60

*/

NONSHARABLE_CLASS(CAknSettingCache) : public CBase

    {

    public:     // Public c'tor and d'tor

        static CAknSettingCache* NewL();

        ~CAknSettingCache();

    public: // New methods

        /**

        * Returns the current input language (Symbian OS language code).

        *

        * @since 2.0

        *

        * @return Current input language.

        */

        IMPORT_C TLanguage InputLanguage();

        /**

        * Returns the current layout ID.

        *

        * @since 2.0

        *

        * @return Current layout ID.

        */

        IMPORT_C TAknLayoutId LayoutId();

        /**

        * Returns the current hardware layout state.

        *

        * @since 2.8

        *

        * @return Current hardware layout state.

        */

        IMPORT_C TInt HardwareLayoutState();

        /**

        * Returns the preferred orientation for the current hardware layout state.

        *

        * @since 3.1

        *

        * @return Preferred orientation for current hardware layout state.

        */

        IMPORT_C TInt PreferredOrientation();

        /**

        * Returns the current hardware layout state.

        *

        * @since 3.1

        *

        * @return Current Global UI Zoom level

        */

        IMPORT_C TAknUiZoom GlobalUiZoom();

    public: // New methods

        /**

        * Updates the cache.

        * Called by CEikAppUi before forwarding events to application controls.

        * Others should not call this method.

        *

        * @internal

        *

        * @param aEventId UID of the event that causes cache update.

        *

        * @return ETrue if value was changed, EFalse if not.

        */

        IMPORT_C TBool Update( TInt aEventId );

        /**

        * Register a new plugin. This plugin may be queried during update

        * if internal settings or previously registered plugins have not already 

        * reported an update. Leaves if there was an error.

        * 

        * @internal

        * @since 3.1

        * @param aPlugin plugin being registered, ownership is not passed

        */

        IMPORT_C void RegisterPluginL(MAknSettingCacheUpdatePlugin* aPlugin);

        /**

        * De-register and destroy a plugin. If the plugin has been previously registered, then

        * it will be removed from the internal data structure. If the plugin cannot be found, 

        * no action is taken.

        * 

        * @internal

        * @since 3.1

        * @param aPlugin plugin being de-registered

        *

        */

        IMPORT_C void DeRegisterPlugin(MAknSettingCacheUpdatePlugin* aPlugin);

        /**

        * Request the value from the most recently registered plugin for a given

        * channel. There should be a registered plugin that is listening to the 

        * specified channel id, otherwise an error will be reported

        *

        * @internal

        * @since 3.1

        * @param aEventId the event id 

        * @param aValue the output value, will be invalid if return value is KErrNotFound

        * @return KErrNone if plugin found that supports this channel, otherwise KErrNotFound

        */

        IMPORT_C TInt PluginValue(TInt aEventId, TInt& aValue);

        /**

        * Return if Transparency is Enabled .

        *

        * @since 5.0

        *

        * @return if Transparency is Enabled.

        */

        IMPORT_C TBool TransparencyEnabled();

    private:    // Private constructors

        CAknSettingCache();

    private:    // New methods

        enum TCacheFlag

            {

            EInputLanguage  = 0x00000001,

            ELayoutId       = 0x00000002,

            EHardwareLayout = 0x00000004,

            EGlobalUiZoom = 0x00000008,

            EPreferredOrientation = 0x00000010,

            ETransparencyEnabled = 0x00000020

            };

        TBool UpdateFromPubSub(

            const TUid aUid, TUint32 aKey, TInt& aValue, TCacheFlag aFlag);

        TBool UpdateFromCenRep(

            const TUid aUid, TUint32 aKey, TInt& aValue, TCacheFlag aFlag);

    private:    // Data

        TInt iFlags;

        // cached settings

        TLanguage iInputLanguage;

        TAknLayoutId iLayoutId;

        TInt iHardwareLayout;

        TAknUiZoom iGlobalUiZoom;

        TInt iPreferredOrientation;

        TInt iTransparencyEnabled;

        // plugins

        RPointerArray<MAknSettingCacheUpdatePlugin> iPlugins; // plugins are not owned

    };

#endif // AKN_SETTING_CACHE_H

// End of File