1 /*

     2 * Copyright (c) 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:   Environment class.

    15 *

    16 */

    17 

    18 

    19 

    20 #ifndef C_ALFENV_H

    21 #define C_ALFENV_H

    22 

    23 #include <e32base.h>

    24 #include <aknappui.h>

    25 #include <AknWsEventObserver.h>

    26 #include <alf/alfcommand.h>

    27 #include <alf/alftexturemanager.h>

    28 #include <alf/alfversion.h>

    29 

    30 class RAlfClient;

    31 class CAlfDisplay;

    32 class CAlfDisplayCoeControl;

    33 class CAlfControlGroup;

    34 class CAlfControl;

    35 class TAlfEvent;

    36 class CAlfTextureManager;

    37 class CAlfTextStyleManager;

    38 class RFTokenClient;

    39 class CAlfLayoutMetricsUtility;

    40 class CAlfBatchBuffer;

    41 class MAlfEnvObject;

    42 

    43 namespace Alf

    44     {

    45     class IAlfWidgetFactory;            

    46     class IAlfWidget;

    47     }

    48 

    49     

    50 using namespace Alf; 

    51 

    52 const TInt KAlfOrpheanPtrEventReceived(0x2000B4D0);

    53 

    54 

    55 /** Device screensize or ui style has changed */

    56 const TInt KAlfActionIdDeviceLayoutChanged(KEikDynamicLayoutVariantSwitch);

    57 

    58 /** Ui skin graphics has been changed */

    59 const TInt KAlfActionIdSkinChanged(KAknsMessageSkinChange);

    60 

    61 /** Application is now in the focused app */

    62 const TInt KAlfActionIdFocusGained(0x200110DB); 

    63 

    64 /** Application is no more the focused app */

    65 const TInt KAlfActionIdFocusLost(0x200110DC);

    66 

    67 /** Application is now brought to foreground */

    68 const TInt KAlfActionIdForegroundGained(0x200110DD);

    69 

    70 /** Application is no more in foreground */

    71 const TInt KAlfActionIdForegroundLost(0x200110DE);

    72 

    73 /** Device input language has been changed */

    74 const TInt KAlfActionIdInputLanguageChanged(0x200110DF);

    75 

    76 /** Application has been requested to exit (e.g. from a task manager or OOM watcher) */

    77 const TInt KAlfActionIdExitRequested(0x200110E0);

    78 

    79 

    80 /**

    81  * TAlfRefreshMode modes can be used to define when the screen redraws

    82  * should be performed.

    83  * @see CAlfEnv::SetRefreshMode()

    84  */

    85 enum TAlfRefreshMode

    86     {

    87     /** Refresh occurs only when requested by calling CAlfEnv::RefreshCallBack(). */

    88     EAlfRefreshModeManual,

    89 

    90     /** Refresh is done automatically when necessary. */

    91     EAlfRefreshModeAutomatic, // = default

    92 

    93     /** Refresh is done all the time, even if nothing has changed. Dirty regions

    94         are not used for determining what has changed. Instead, displays are

    95         always fully redrawn. */

    96     EAlfRefreshModeForced

    97     };

    98     

    99 /**

   100  * @enum TAlfRenderer

   101  * 

   102  * Enumerates renderers. The renderer depends on the used hardware.

   103  * 

   104  * Different renderers may not support all features available.

   105  * For example the EAlfRendererBitgdi does not support any 3D-related

   106  * methods, whereas EAlfRendererGles11 supports most of them.

   107  * 

   108  */

   109 enum TAlfRenderer

   110     {

   111     /** Symbian BITGDI renderer. */

   112     EAlfRendererBitgdi      = 1,

   113 

   114     /** OpenVG 1.0 renderer (Not implemented). */

   115     EAlfRendererVg10        = 2,

   116 

   117     /** OpenGL ES 1.0 renderer. */

   118     EAlfRendererGles10      = 3,

   119 

   120     /** OpenGL ES 1.1 renderer. */

   121     EAlfRendererGles11      = 4,

   122 

   123     /** OpenGL ES 1.1 DSA renderer. Implemented, but please use EAlfRendererGles11. */

   124     EAlfRendererGles11DSA   = 5,

   125 

   126     /** OpenGL ES 2.0 renderer (Not implemented). */

   127     EAlfRendererGles20      = 6

   128     };

   129 

   130     

   131 

   132 class MAlfActionObserver

   133     {

   134 public:

   135 

   136     /**

   137      * Called by the server when an action command is executed.

   138      *

   139      * @param aActionCommand  The command that is being executed.

   140      */

   141     virtual void HandleActionL(const TAlfActionCommand& aActionCommand) = 0;

   142 

   143     };

   144 

   145 /**

   146  *  This is the UI Accelerator Toolkit environment object. It needs to be created before any other toolkit

   147  *  functionality can be used.

   148  *

   149  *  Through environment it is possible to create display objects that are required to display graphics.

   150  *  It is also possible to create control groups that are required to include controls in.

   151  *

   152  *  Usually an application creates an environment object, after which it creates a single display object

   153  *  to handle the drawing surface of the application. After this at least one control group is required

   154  *  that can be used to encapsulate application controls. Controls themselves need to be derived from

   155  *  CAlfControl - base class.

   156  *

   157  *  @code

   158  *  // Create CAlfEnv

   159  *  iEnv = CAlfEnv::NewL();

   160  *

   161  *  // Create a display

   162  *  CAlfDisplay& display = iEnv->NewDisplayL(aRect, CAlfEnv::ENewDisplayAsCoeControl);

   163  *	

   164  *  // Create a control group

   165  *  CAlfControlGroup& group = iEnv->NewControlGroupL(KIdMainGroup);

   166  *  CMyControl* control = CMyControl::NewL(aEnv);

   167  *  group.AppendL(control);

   168  *

   169  *  display.Roster().ShowL(group);

   170  *  @endcode 

   171  *  

   172  *  @lib alfclient.lib

   173  *  @since S60 v3.2

   174  */

   175 NONSHARABLE_CLASS( CAlfEnv ): public CBase, public MAknWsEventObserver, 

   176     public MAlfActionObserver, public MAlfTextureManagerStateChangedObserver, public MAlfTextureLoadingCompletedObserver, public MCoeMessageMonitorObserver

   177     {

   178 

   179 public:

   180 

   181     /**

   182      * Flags for creating new displays.

   183      * @see NewDisplayL()

   184      */

   185     enum TNewDisplayFlags

   186         {

   187         /** Newly created display will fill the whole device screen. */

   188         ENewDisplayFullScreen = 0x1,        

   189         ENewDisplayOverlaid = 0x2,

   190         /**

   191          * Newly created display will be created as a CCoeControl - derived object.

   192          * This will ensure that key events are automatically delivered to the

   193          * correct CAlfControl - derived objects within the roster of the newly

   194          * created display.

   195          */        

   196         ENewDisplayAsCoeControl = 0x4

   197         };

   198 

   199 

   200     /**

   201      * Constructor

   202      * @param aVersion Default parameters should always be used as parameters for compatibility reasons.

   203      */

   204     IMPORT_C static CAlfEnv* NewL(TVersion aVersion = TVersion(ALF_VERSION_MAJOR, ALF_VERSION_MINOR, ALF_VERSION_BUILD));

   205 

   206     /**

   207      * Constructor

   208      * @param aVersion Default parameters should always be used  as parameters for compatibility reasons.

   209      */

   210     IMPORT_C static CAlfEnv* NewLC(TVersion aVersion = TVersion(ALF_VERSION_MAJOR, ALF_VERSION_MINOR, ALF_VERSION_BUILD));

   211 

   212     /**

   213      * Destructor

   214      */

   215     IMPORT_C virtual ~CAlfEnv();

   216 

   217     /**

   218      * Returns client

   219      *

   220      * @return Client to Alfred server

   221      */

   222     IMPORT_C RAlfClient& Client();

   223     

   224     /**

   225      * Creates a new display. You have to use ENewDisplayAsCoeControl - flag if you want to receive key events

   226      * automatically to the CAlfControl - derived objects in your application. If display is created without

   227      * ENewDisplayAsCoeControl - flag the key events have to be passed to the system manually using 

   228      * the HandleKeyEventL() - method.

   229      *

   230      * @param aRect   Size of the display.

   231      * @param aFlags  Flags for the display as a combination of flags from CAlfEnv::TNewDisplayFlags enumerator.

   232      * @param aDisplayType Type of the display, flags from CAlfDisplay::TDisplayType enumerator.

   233      * @return        Newly created CAlfDisplay object.

   234      */

   235     IMPORT_C CAlfDisplay& NewDisplayL( const TRect& aRect,

   236                                        TInt aFlags = 0, 

   237                                        TInt aDisplayType = 0  );

   238                                       

   239     /**

   240      * Creates a new display. You have to use ENewDisplayAsCoeControl - flag if you want to receive key events

   241      * automatically to the CAlfControl - derived objects in your application. If display is created without

   242      * ENewDisplayAsCoeControl - flag the key events have to be passed to the system manually using 

   243      * the HandleKeyEventL() - method.

   244      *

   245      * @param aRect   Size of the display.

   246      * @param aFlags  Flags for the display as a combination of flags from CAlfEnv::TNewDisplayFlags enumerator.

   247      * @param aRosterOwningDisplay Not used. Display that owns shared roster. 

   248      * @param aDisplayType Type of the display, flags from CAlfDisplay::TDisplayType enumerator.

   249      * @param aBackBufferUid Screen back buffer uid

   250      * @return        Newly created CAlfDisplay object.

   251      */

   252 	IMPORT_C CAlfDisplay& NewDisplayL( const TRect& aRect, 

   253 									   TInt aFlags, 

   254 									   CAlfDisplay* aRosterOwningDisplay, 

   255                                        TInt aDisplayType, 

   256                                        TUid aBackBufferUid );

   257                                       

   258     /**

   259      * Removes a display from the environment.

   260      *

   261      * @param aDisplay  The display to remove.

   262      */

   263     void RemoveDisplay( CAlfDisplay& aDisplay );

   264     

   265     /**

   266      * Constructs a new empty control group.

   267      * Leaves with KErrAlreadyExists if the group with the same ID is already

   268      * created.

   269      *

   270      * @param aId (Resource) Identifier of the new group.

   271      * @return  Reference to the new group.

   272      */                                  

   273     IMPORT_C CAlfControlGroup& NewControlGroupL( TInt aId );

   274     

   275     /**

   276      * Deletes a previously loaded control group. The controls inside the

   277      * groups will also be destroyed. Note that this will also destroy the

   278      * visuals of the controls, because they are owned by the controls.

   279      *

   280      * @param aId  Identifier of the group to be deleted.

   281      *

   282      * @return  <code>KErrNone</code>, if the deletion is successful.

   283      *          <code>KErrNotFound</code>, if there are no control groups

   284      *          with the specified identifier.

   285      */

   286     IMPORT_C TInt DeleteControlGroup(TInt aId);

   287     

   288     /**

   289      * Returns an existing control group based on its identifier.

   290      * @note Will panic with TAlfPanic::EInternal if the specified

   291      * control group is not found.

   292      *

   293      * @param aResourceId Control group ID.

   294      * @return Contorl group

   295      */

   296     IMPORT_C CAlfControlGroup& ControlGroup(TInt aResourceId);

   297     

   298     /**

   299      * Returns an existing control group based on its identifier if

   300      * it is found. Returns NULL if the group cannot be found.

   301      *

   302      * @param aResourceId Control group ID.

   303      * @return Contorl group. Ownership not transferred. NULL if not found.

   304      */ 

   305     IMPORT_C CAlfControlGroup* FindControlGroup(TInt aResourceId) const;

   306     

   307     /**

   308      * Finds a control from the control groups of this

   309      * environment.

   310      *

   311      * @param aId The id of the control.

   312      * @param aUserId searches user given id if set true, otherwise uses system generated identifier 

   313      *

   314      * @see CAlfControl::SetId()

   315      * @see CAlfControl::Id()

   316      * @see CAlfControl::Identifier()

   317      * @return The control instance, or NULL if no such control exists.

   318      */

   319     IMPORT_C CAlfControl* FindControl(TInt aId, TBool aUserId = ETrue) const;

   320     

   321     /**

   322      * Determines the number of displays currently created with NewDisplayL().

   323      *

   324      * @return  Display count.

   325      */

   326     IMPORT_C TInt DisplayCount() const;

   327     

   328     /**

   329      * Sets the refresh mode.

   330      *

   331      * @param aMode  New refresh mode.

   332      *

   333      * @see TAlfRefreshMode

   334      */

   335     IMPORT_C void SetRefreshMode(TAlfRefreshMode aMode);

   336 

   337     /**

   338      * Gets the refresh mode.

   339      *

   340      * @return  Current refresh mode.

   341      *

   342      * @see TAlfRefreshMode

   343      */

   344     IMPORT_C TAlfRefreshMode RefreshMode();

   345     

   346     /**

   347      * Sets the maximum allowed frame rate. Specify 0.0 to use the default limit.

   348      *

   349      * @param aFrameRate  New maximum frame rate in frames per second.

   350      */

   351     IMPORT_C void SetMaxFrameRate(TReal32 aFrameRate) __SOFTFP;

   352     

   353     /**

   354      * Continues normal display refreshing. If display refreshing is already

   355      * being done, calling this has no effect. This is called automatically

   356      * from inside the toolkit when something is done that may lead to a

   357      * visible change on a display. The application may also call this if it

   358      * has previously paused refresh with PauseRefresh().

   359      */

   360     IMPORT_C void ContinueRefresh();

   361 

   362     /**

   363      * Pauses display refreshing temporarily. This is called when it is clear

   364      * that any displays will not be updated soon. The application may call

   365      * this at times when it needs more processing time for other tasks.

   366      */

   367     IMPORT_C void PauseRefresh();

   368     

   369     /**

   370      * Refresh callback, that is called by a refresh timer. Called periodically

   371      * when there might be something to update on the display. Has the

   372      * responsibility to update time for all ALF environments.

   373      *

   374      * @param aInstance  A CAlfEnv instance.

   375      * @see StartRefresh() to modify how often updates are being made.

   376      * @see StopRefresh() to stop updates.

   377      */

   378     IMPORT_C static TInt RefreshCallBack(TAny* aInstance);

   379     

   380     /**

   381      * Returns the primary display, that is the display

   382      * that was created first.

   383      *

   384      * @return Display

   385      */

   386     IMPORT_C CAlfDisplay& PrimaryDisplay() const;

   387 

   388     /**

   389      * Returns the default texture manager.

   390      * @return Default texture manager of this environment.

   391      */

   392     IMPORT_C CAlfTextureManager& TextureManager() const;

   393 

   394     /**

   395      * Returns the text style manager.

   396      * @return Default text style manager of this environment.

   397      */

   398     IMPORT_C CAlfTextStyleManager& TextStyleManager() const;    

   399     

   400     /**

   401      * Creates a shared texture manager. If texture manager with given uid already 

   402      * exists, a pointer to it is returned and reference count is increased. 

   403      *

   404      * Shared texturemanager can be used to create/load textures that are 

   405      * shared between components/applications to preserve memory. 

   406      *

   407      * @param aUid Unique identifier for the shared texture manager

   408      * @return Shared texture manager

   409      *   

   410      * Example of shared texturemanager usage:

   411      *

   412      * CScrollBar::ConstructL()

   413      *     {

   414      *     // Create shared texturemanager instead of default texture manager to save RAM

   415      *     // because same texture is used in multiple components in different apps.

   416      *     CAlfTextureManager* sharedManager = 

   417      *         iEnv->CreateSharedTextureManagerL(KScrollBarTextureManagerUid);

   418      *     

   419      *     // Create texture, if it already exists inside this application or in some

   420      *     // other application, then bitmap from bitmapprovider and texture flags are ignored

   421      *     // and already existing texture is returned.

   422      *     iBackgroundTexture = sharedManager->CreateTexture(KScrollBarBackgroudId, 

   423      *         iBitmapProvider,

   424      *         EAlfTextureFlagDefault);

   425      *     

   426      *     // Create another texture...

   427      *     iHandleTexture = sharedManager->CreateTexture(KScrollBarHandleId, 

   428      *         iBitmapProvider,

   429      *         EAlfTextureFlagDefault);

   430      *     }

   431      *

   432      * CScrollBar::~CScrollBar()

   433      *     {

   434      *     // We created shared texture manager so we should delete it here.

   435      *     // If this is last instance of this shared texture manager in the device, 

   436      *     // all of its textures get unloaded.

   437      *     iEnv->DeleteSharedTextureManagerL(KScrollBarTextureManagerUid);

   438      *     }

   439      */

   440     IMPORT_C CAlfTextureManager* CreateSharedTextureManagerL(TUid aUid);

   441 

   442     /**

   443      * This method deletes shared texture manager and all its textures get released if there

   444      * are no other references to the texture manager. Otherwise only the reference count

   445      * is decreased.

   446      * 

   447      * @param aUid Unique identifier of the shared texture manager

   448      *

   449      */

   450     IMPORT_C void DeleteSharedTextureManager(TUid aUid);

   451 

   452     /**

   453      * Returns pointer to a shared texture manager, NULL if it does not exist.

   454      *

   455      * @param aUid Unique identifier of the shared texture manager

   456      * @return Shared texture manager

   457      *   

   458      */

   459     IMPORT_C CAlfTextureManager* SharedTextureManager(TUid aUid) const;

   460 

   461      /**

   462      * Adds action observer

   463      *

   464      * @param aObserver observer to be added to array

   465      * @leave any system wide error code

   466      */

   467     IMPORT_C void AddActionObserverL(MAlfActionObserver* aObserver);

   468 

   469      /**

   470      * Removes action observer, this must be done at latest when observer is being deleted

   471      *

   472      * @param aObserver observer to be added to array

   473      */

   474     IMPORT_C void RemoveActionObserver(MAlfActionObserver* aObserver);

   475     

   476     

   477     /**

   478      * Schedule a command.

   479      *

   480      * @param aCommand  Command to send.

   481      * @param aDelayMilliSeconds  Time in ms to wait before executing the command. If

   482      * set to zero, the command is executed immediately. Note that the point of

   483      * execution may not be exactly this amount of milliseconds.

   484      *

   485      * @return  System-wide error code. If successful, returns <code>KErrNone</code>.

   486      */

   487     IMPORT_C TInt Send(const TAlfCommand& aCommand, TInt aDelayMilliSeconds = 0);

   488     

   489     /**

   490      * Cancel commands where object is aObject.

   491      *

   492      * @param aObject Command object.

   493      */

   494     IMPORT_C void CancelCommands( TAny* aObject );

   495     

   496     /**

   497      * Cancel commands where object is aObject and operation is aCommandOperation.

   498      *

   499      * @param aObject Command object.

   500      * @param aCommandOperation Command operation.

   501      */

   502     IMPORT_C void CancelCommands( TAny* aObject, TAlfOp aCommandOperation);

   503 

   504     /**

   505      * Cancel commands where object is aObject and type is aCommandType.

   506      *

   507      * @param aObject Command object.

   508      * @param aCommandType Command type.

   509      */

   510     IMPORT_C void CancelCommands( TAny* aObject, TAlfCommandType aCommandType );

   511  

   512     /**

   513      * Cancel custom commands where object is aObject.

   514      *

   515      * @param aObject Command object.

   516      */   

   517     IMPORT_C void CancelCustomCommands( MAlfEventHandler* aObject ); 

   518     

   519     /**

   520      * Cancel commands where object is aObject and custom parater is aCustomParam 

   521      *

   522      * @param aObject Command object.

   523      * @param aCustomParam Custom paramerer.

   524      */

   525     IMPORT_C void CancelCustomCommands( MAlfEventHandler* aObject, TInt aCustomParam );         

   526     

   527     /**

   528      * Time until next command where object is aObject.

   529      *

   530      * @param aObject Command object.

   531      * @return Time left in milliseconds to the first found command, which 

   532      *         matched the criteria. KErrNotFound if the none found. The return

   533      *         value is set to 0 if the command timer has expired and waits

   534      *         execution from the active scheduler.

   535      */

   536     IMPORT_C TInt MilliSecondsUntilCommand( TAny* aObject );

   537     

   538     /**

   539      * Time until next command where object is aObject and operation is aCommandOperation 

   540      *

   541      * @param aObject Command object.

   542      * @param aCommandOperation Custom paramerer.

   543      * @return Time left in milliseconds to the first found command, which 

   544      *         matched the criteria. KErrNotFound if the none found. The return

   545      *         value is set to 0 if the command timer has expired and waits

   546      *         execution from the active scheduler.

   547      */

   548     IMPORT_C TInt MilliSecondsUntilCommand( TAny* aObject, TAlfOp aCommandOperation);

   549 

   550     /**

   551      * Time until next commands where object is aObject and type is aCommandType.

   552      *

   553      * @param aObject Command object.

   554      * @param aCommandType Command type.

   555      * @return Time left in milliseconds to the first found command, which 

   556      *         matched the criteria. KErrNotFound if the none found. The return

   557      *         value is set to 0 if the command timer has expired and waits

   558      *         execution from the active scheduler.

   559      */

   560     IMPORT_C TInt MilliSecondsUntilCommand( TAny* aObject, TAlfCommandType aCommandType );

   561         

   562     /**

   563      * Time until next custom commands where object is aObject.

   564      *

   565      * @param aObject Command object.

   566      * @return Time left in milliseconds to the first found command, which 

   567      *         matched the criteria. KErrNotFound if the none found. The return

   568      *         value is set to 0 if the command timer has expired and waits

   569      *         execution from the active scheduler.

   570      */     

   571     IMPORT_C TInt MilliSecondsUntilCustomCommand( MAlfEventHandler* aObject ); 

   572     

   573     /**

   574      * Time until next commands where object is aObject and custom parater is aCustomParam 

   575      *

   576      * @param aObject Command object.

   577      * @param aCustomParam Custom paramerer.

   578      * @return Time left in milliseconds to the first found command, which 

   579      *         matched the criteria. KErrNotFound if the none found. The return

   580      *         value is set to 0 if the command timer has expired and waits

   581      *         execution from the active scheduler.

   582      */

   583     IMPORT_C TInt MilliSecondsUntilCustomCommand( MAlfEventHandler* aObject, TInt aCustomParam ); 

   584                                   

   585     /**

   586      * Handles a key event received from CONE. This can be called directly by application

   587      * to pass in external key events. You will have to call this from an application to pass

   588      * key events to CAlfControl - derived objects unless you have created the CAlfDisplay 

   589      * class with the ENewDisplayAsCoeControl flag.

   590      *

   591      * @param aKeyEvent  Received key event to handle.

   592      * @param aType      Type of event.

   593      * @param aAssocDisplay  Associated CAlfDisplay, if there is one.

   594      *                   If specified, the event is handled by this display's

   595      *                   roster only. If <code>NULL</code>, event is offered

   596      *                   to all displays.

   597      */

   598     IMPORT_C TKeyResponse HandleKeyEventL(const TKeyEvent& aKeyEvent, TEventCode aType,

   599                                    CAlfDisplay* aAssocDisplay = 0);

   600 

   601 

   602     /**

   603      * Handles a pointer event received from CONE. This can be called directly by application

   604      * to pass in external pointer events. You will have to call this from an application to pass

   605      * pointer events to CAlfControl - derived objects if you have created the CAlfDisplay 

   606      * class as offscreen buffer that has no window.

   607      *

   608      * @param aPointerEvent  Received pointer event to handle. Note that iParentPosition of the 

   609      * pointerevent should always be in the same coordinate space as where the displays rect 

   610      * was defined when it was created.

   611      * @param aAssocDisplay  Associated CAlfDisplay.

   612      */

   613     IMPORT_C void HandlePointerEventL(const TPointerEvent& aPointerEvent, 

   614                                    CAlfDisplay& aAssocDisplay);

   615                                   

   616 

   617     /**

   618      * Determines which renderer is currently in use. Returns the real

   619      * explicit identifier of the renderer.

   620      *

   621      * @return  TAlfRenderer enum.

   622      */

   623     IMPORT_C TAlfRenderer Renderer() const;

   624 

   625 

   626     /**

   627      * Sets the interval before an idle notification is sent. Idling

   628      * begins when no input has been received after this delay.

   629      *

   630      * Also note that scheduled events may keep display refresh running even

   631      * when there's no input.

   632      *

   633      * @param aSeconds  Threshold in milliseconds.

   634      */

   635     IMPORT_C void SetIdleThreshold(TInt aMilliSeconds);

   636 

   637 	/**

   638      * Releases as many resources as possible. Among the released resources 

   639      * may be all objects in the toolkit's ownership, for example texture 

   640      * images and drawing surfaces. This should be called when the Hitchcock 

   641      * user interface is not needed for a while, for example when the application 

   642      * goes to the background. 

   643      *

   644      * At the moment the Environment releases all textures. Shared textures

   645      * are also tried to release if so instructed in the params.

   646      * 

   647      * The resources need to be restored with a call to RestoreL() before

   648      * the user interface is used again.

   649      *

   650      * The AppUI can call this method to release resources. The AppUI can

   651      * overload HandleWsEventL() and react to KAknFullOrPartialForegroundLost

   652      * window server event by calling this method.

   653      *

   654      * @param aReleaseSharedTextures If ETrue also shared textures are released

   655      *  if there are no other apps using them.

   656      * @see RestoreL()

   657      */

   658     IMPORT_C void Release(TBool aReleaseSharedTextures=EFalse);

   659     

   660     /**

   661      * Restores all resources that were released with a call to Release().

   662      * After this the Hitchcock user interface should be in the same state

   663      * in terms of resources as it was prior to the Release() call.

   664      *     

   665      * The AppUI can call this method to Restore resources. The AppUI can

   666      * overload HandleWsEventL() and react to KAknFullOrPartialForegroundGained

   667      * window server event by calling this method.

   668      *

   669      * @see Release()

   670      */

   671     IMPORT_C void RestoreL();    

   672 

   673     /**

   674      * Notifies everyone of a change in the environment's skin. Note that this

   675      * method gets called automatically when system skin is changed.

   676      * 

   677      * Method is exported so that applications can call this in some special

   678      * situations when skinned graphics needs to be refreshed.

   679      */

   680     IMPORT_C void NotifySkinChangedL();    

   681 

   682     /**

   683      * Notifies everyone of a change in the environment's layout. Exported so that 

   684      * applications can call this from their HandleResourceChange() methods.

   685      */

   686     IMPORT_C void NotifyLayoutChangedL();    

   687 

   688     /**

   689     * defines if Alfred draws on top of (or below) application windowgroup 

   690     */

   691     IMPORT_C void SetFullScreenDrawing(TBool aEnable);

   692 

   693     IMPORT_C RFTokenClient* TokenClient();

   694 

   695     /**

   696      * @deprecated <b>Always returns an invalid reference!</b>

   697      * 

   698      * Widget factory for widget and their part creation 

   699      */

   700     IMPORT_C IAlfWidgetFactory& WidgetFactory()const;

   701     

   702     /**

   703      * @deprecated <b>Doesn't do anything anymore!</b>

   704      * 

   705      * Append widgets into environment

   706      */

   707     IMPORT_C void AppendWidgetL(IAlfWidget* aAlfWidget);

   708 

   709     /**

   710      * @deprecated <b>Doesn't do anything anymore!</b>

   711      * 

   712      * Destroy a widget from the environment

   713      */

   714     IMPORT_C TInt DestroyWidget(IAlfWidget* aAlfWidget);

   715     

   716     /**

   717      * @deprecated <b>Always returns an invalid reference!</b>

   718      * 

   719      * Find named widgets owned by environment 

   720      */

   721     IMPORT_C IAlfWidget* FindWidget(const char* aWidgetName)const;

   722 

   723     void BroadcastEventL(const TAlfEvent& aEvent);

   724     

   725     TInt ReportAction(const TAlfActionCommand& aCommand);

   726 

   727     // From MAlfTextureLoadingCompletedObserver

   728     void TextureLoadingCompleted(CAlfTexture& aTexture,

   729                                          TInt aTextureId,

   730                                          TInt aErrorCode);

   731 

   732     // From MAlfTextureManagerStateChangedObserver

   733     void TextureManagerStateChanged(const CAlfTextureManager& aManager);

   734 

   735     //From MCoeMessageMonitorObserver

   736 	void MonitorWsMessage(const TWsEvent& aEvent);

   737 

   738     /**

   739      * Gets pointer into layout metrics utility.

   740      */

   741     IMPORT_C CAlfLayoutMetricsUtility* LayoutMetricsUtility();

   742     

   743     /**

   744      * Gets pointer to application enviroment singleton

   745      * @return singleton or NULL

   746      */

   747     IMPORT_C static CAlfEnv* Static();

   748     

   749     /**

   750      * !Direct access to Symbian pointer event data. This information is usually relevant only when

   751      * associated action command KAlfOrpheanPtrEventReceived is sent by environment 

   752      * @return null or last received pointer event

   753      */

   754      IMPORT_C TPointerEvent* LastReceivedPtrEvent();

   755     

   756     /**

   757      * Returns version of the Alf in runtime environment.

   758      * @return Version of the runtime Alf

   759      */

   760      IMPORT_C TVersion Version() const;

   761 

   762      /**

   763      * Returns version of the Alf that application was compiled against

   764      * @return Version of the compiletime Alf

   765      */

   766     TVersion ApiVersion() const;   

   767     

   768     /**

   769      * Returns the batch buffer handler.

   770      *

   771      * @return Batch buffer handler

   772      */

   773     IMPORT_C CAlfBatchBuffer& BatchBufferHandler() const;

   774    

   775    

   776     /**

   777      * Handles texture info changed event.

   778      * @param aEventData descriptor containing event data.

   779      */

   780     void HandleTextureInfo( const TDesC8& aEventData );

   781     

   782     TBool SkinChangePending() const;

   783 

   784     void SetSkinChangePending(TBool aPending);

   785 

   786     TBool LayoutChangePending() const;

   787 

   788     void SetLayoutChangePending(TBool aPending);

   789 

   790     void ReportWsEventAsActionCommand(TInt aActionCommandId);

   791     

   792     /**

   793     * Access AlfEnv extensions via their UID

   794     *

   795     * AlfEnv holds a number of extensions that have been set there

   796     * by users of AlfEnv.  They are owned by AlfEnv and are 

   797     * deleted by it when the environment is destroyed. The objects

   798     * must derive from MAlfEnvObject.

   799     * 

   800     * The objects are added to the environment with a Uid. This Uid is

   801     * used here to access them.

   802     * 

   803     * @see AddExtension

   804     *

   805     * @param aUid   Uid corresponding to the object being requested

   806     * @return pointer to object requested, or NULL

   807     */

   808     IMPORT_C MAlfEnvObject* Extension( TInt aUid) const;

   809 

   810     /**

   811     * Add an extension object to AlfEnv

   812     *

   813     * Extension objects, derived from MAlfEnvObject, can be given

   814     * to AlfEnv, so that other AlfEnv clients can access the

   815     * singleton objects.

   816     * 

   817     * The objects are added with an accompanying Uid. This Uid is used

   818     * to access the object.

   819     *

   820     * Objects added to AlfEnv must have their Release() method implemented

   821     * in DLLs that remain in memory until after AlfEnv is deleted.

   822     *

   823     * @see Extension

   824     *

   825     * @param aUid   Uid corresponding to the object being requested

   826     * @param aNewExtension   Pointer to the new object given to the system

   827     * @return an error code. KErrNone if there has been no error

   828     */

   829     IMPORT_C TInt AddExtension( TInt aUid, MAlfEnvObject* aNewExtension);

   830 

   831     /**

   832      * Finds the index of a display in the environment.

   833      *

   834      * @param aDisplay  Display.

   835      * @return Index. KErrNotFound if not found.

   836      */

   837     IMPORT_C TInt FindDisplayIndex(const CAlfDisplay& aDisplay) const;

   838     

   839     /**

   840      * Returns one of the displays owned by the environment.

   841      * Panics with error code USER 130, if aIndex is negative, or is greater

   842      * than the number of displays in the array.

   843      *

   844      * @param aIndex  Index number of the display to return.

   845      *

   846      * @return  Display.

   847      */

   848     IMPORT_C CAlfDisplay& Display( TInt aIndex) const;

   849     

   850 

   851 private:

   852 

   853     // Constructor

   854     CAlfEnv();

   855     

   856     // ConstructL

   857     void ConstructL(TVersion aVersion);

   858     

   859     // from MAknWsEventObserver

   860     void HandleWsEventL(const TWsEvent& aEvent, CCoeControl* aDestination);

   861 

   862     // from MAlfActionObserver

   863     void HandleActionL(const TAlfActionCommand& aActionCommand);    

   864      

   865 private:

   866     

   867     // Private data. Own.

   868     struct TPrivateData;

   869     TPrivateData* iData;

   870 

   871     };

   872 

   873 #endif // C_ALFENV_H