1 /*

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

     3 * All rights reserved.

     4 * This component and the accompanying materials are made available

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

     6 * which accompanies this distribution, and is available

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

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

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

    15 *

    16 */

    17 

    18 

    19 #ifndef AKN_SETTING_CACHE_H

    20 #define AKN_SETTING_CACHE_H

    21 

    22 // INCLUDES

    23 #include <e32base.h>

    24 #include <AknLayoutDef.h> // for TAknLayoutId

    25 #include <AknDef.h> // for TAknUiZoom

    26 

    27 // CONSTANTS

    28 

    29 // FORWARD DECLARATIONS

    30 

    31 // CLASS DECLARATIONS

    32 

    33 /**

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

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

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

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

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

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

    40 * know what to do with it.

    41 *

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

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

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

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

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

    47 * that are managed by the previously added clients.

    48 *

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

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

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

    52 *

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

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

    55 *

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

    57 * practice clients should ensure that the stacking corresponds logically to 

    58 * their own application context). 

    59 *

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

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

    62 * @c KAknLocalZoomLayoutSwitch event id.

    63 *

    64 * @lib avkon.lib

    65 * @since 3.1

    66 * @internal to S60

    67 */

    68 class MAknSettingCacheUpdatePlugin

    69     {

    70     public:

    71         /**

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

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

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

    75         * @param aEventId event id to be queried

    76         * @return ETrue if the event id is handled

    77         */

    78         virtual TBool HandlesEvent(TInt aEventId) const = 0;

    79 

    80         /**

    81         * Update the setting cache plugin's cached values,

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

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

    84         * the return value will be ignored.

    85         * @param aEventId event id to be processed

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

    87         */

    88         virtual TBool Update(TInt aEventId) = 0;

    89         

    90         /**

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

    92         * specified event. 

    93         * @param aEventId the event id

    94         * @param aValue output the value

    95         * @return KErrNone if there was no error.

    96         */

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

    98     };

    99 

   100 /**

   101 * Interface for fetching certain system settings in UI controls.

   102 * AknEnv owns an instance of this.

   103 *

   104 * @lib avkon.dll

   105 * @since 2.0

   106 * @internal to S60

   107 */

   108 NONSHARABLE_CLASS(CAknSettingCache) : public CBase

   109     {

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

   111 

   112         static CAknSettingCache* NewL();

   113         ~CAknSettingCache();

   114 

   115     public: // New methods

   116 

   117         /**

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

   119         *

   120         * @since 2.0

   121         *

   122         * @return Current input language.

   123         */

   124         IMPORT_C TLanguage InputLanguage();

   125 

   126         /**

   127         * Returns the current layout ID.

   128         *

   129         * @since 2.0

   130         *

   131         * @return Current layout ID.

   132         */

   133         IMPORT_C TAknLayoutId LayoutId();

   134 

   135         /**

   136         * Returns the current hardware layout state.

   137         *

   138         * @since 2.8

   139         *

   140         * @return Current hardware layout state.

   141         */

   142         IMPORT_C TInt HardwareLayoutState();

   143 

   144         /**

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

   146         *

   147         * @since 3.1

   148         *

   149         * @return Preferred orientation for current hardware layout state.

   150         */

   151         IMPORT_C TInt PreferredOrientation();

   152 

   153         /**

   154         * Returns the current hardware layout state.

   155         *

   156         * @since 3.1

   157         *

   158         * @return Current Global UI Zoom level

   159         */

   160         IMPORT_C TAknUiZoom GlobalUiZoom();

   161 

   162     public: // New methods

   163 

   164         /**

   165         * Updates the cache.

   166         * Called by CEikAppUi before forwarding events to application controls.

   167         * Others should not call this method.

   168         *

   169         * @internal

   170         *

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

   172         *

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

   174         */

   175         IMPORT_C TBool Update( TInt aEventId );

   176 

   177         /**

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

   179         * if internal settings or previously registered plugins have not already 

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

   181         * 

   182         * @internal

   183         * @since 3.1

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

   185         */

   186         IMPORT_C void RegisterPluginL(MAknSettingCacheUpdatePlugin* aPlugin);

   187         

   188         /**

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

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

   191         * no action is taken.

   192         * 

   193         * @internal

   194         * @since 3.1

   195         * @param aPlugin plugin being de-registered

   196         *

   197         */

   198         IMPORT_C void DeRegisterPlugin(MAknSettingCacheUpdatePlugin* aPlugin);

   199         

   200         /**

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

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

   203         * specified channel id, otherwise an error will be reported

   204         *

   205         * @internal

   206         * @since 3.1

   207         * @param aEventId the event id 

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

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

   210         */

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

   212         

   213         /**

   214         * Return if Transparency is Enabled .

   215         *

   216         * @since 5.0

   217         *

   218         * @return if Transparency is Enabled.

   219         */

   220         IMPORT_C TBool TransparencyEnabled();

   221                 

   222     private:    // Private constructors

   223 

   224         CAknSettingCache();

   225 

   226     private:    // New methods

   227 

   228         enum TCacheFlag

   229             {

   230             EInputLanguage  = 0x00000001,

   231             ELayoutId       = 0x00000002,

   232             EHardwareLayout = 0x00000004,

   233             EGlobalUiZoom = 0x00000008,

   234             EPreferredOrientation = 0x00000010,

   235             ETransparencyEnabled = 0x00000020

   236             };

   237 

   238         TBool UpdateFromPubSub(

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

   240 

   241         TBool UpdateFromCenRep(

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

   243 

   244     private:    // Data

   245 

   246         TInt iFlags;

   247 

   248         // cached settings

   249         TLanguage iInputLanguage;

   250         TAknLayoutId iLayoutId;

   251         TInt iHardwareLayout;

   252         TAknUiZoom iGlobalUiZoom;

   253         TInt iPreferredOrientation;

   254         TInt iTransparencyEnabled;

   255                

   256         // plugins

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

   258     };

   259 

   260 #endif // AKN_SETTING_CACHE_H

   261 

   262 // End of File