1 // Copyright (c) 1997-2009 Nokia Corporation and/or its subsidiary(-ies).

     2 // All rights reserved.

     3 // This component and the accompanying materials are made available

     4 // under the terms of "Eclipse Public License v1.0"

     5 // which accompanies this distribution, and is available

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

     7 //

     8 // Initial Contributors:

     9 // Nokia Corporation - initial contribution.

    10 //

    11 // Contributors:

    12 //

    13 // Description:

    14 //

    15 

    16 #ifdef SYMBIAN_ENABLE_SPLIT_HEADERS

    17 #include <apaidpartner.h>

    18 #include <vwsdefpartner.h>

    19 #endif

    20 #include <coeaui.h>

    21 #include <coecntrl.h>

    22 #include "coepanic.h"

    23 #include <coemain.h>

    24 #include <apgtask.h>

    25 #include "COETLS.H"

    26 #include "COEVWMAN.H"

    27 

    28 #define STRICT_INNER_AND_OUTER_CHECKING

    29 

    30 const TInt KAppUiControlStackGroupId=0;

    31 

    32 //

    33 // class CCoeControlStack

    34 //

    35 

    36 struct SStackedControl

    37 	{

    38 	CCoeControl* iControl;

    39 	TInt iPriority;

    40 	TInt iFlags;

    41 	TInt iGroupId;

    42 	};

    43 

    44 class CCoeControlStack : public CArrayFixFlat<SStackedControl>

    45 	{

    46 public:

    47 	inline CCoeControlStack() : CArrayFixFlat<SStackedControl>(2) { } // granularity of two

    48 	TKeyResponse OfferKeyL(const TKeyEvent& aKeyEvent,TEventCode aType);

    49 	inline void SetCurrentGroupId(TInt aGroupId) { iCurrentGroupId=aGroupId; };

    50 	TBool IsGroupIdCurrent(TInt aGroupId) const;

    51 public:

    52 	TInt iKeyIndex;

    53 	TInt iCurrentGroupId;

    54 	};

    55 

    56 TBool CCoeControlStack::IsGroupIdCurrent(TInt aGroupId) const

    57 	{

    58 	return (aGroupId==KAppUiControlStackGroupId || aGroupId==iCurrentGroupId);

    59 	}

    60 

    61 TKeyResponse CCoeControlStack::OfferKeyL(const TKeyEvent& aKeyEvent,TEventCode aType)

    62 	{

    63 	iKeyIndex=0;

    64 	while (iKeyIndex<Count())

    65 		{ // both iKeyIndex and Count() can be changed inside OfferKeyEventL call below

    66 		SStackedControl& stacked=(*this)[iKeyIndex++];

    67 		if (stacked.iFlags&ECoeStackFlagRefusesAllKeys)

    68 			continue;

    69 		if ( !IsGroupIdCurrent(stacked.iGroupId) )

    70 			continue;

    71 		const TInt oldKeyIndex=iKeyIndex;

    72 		const TInt oldCount=Count();

    73 		const TKeyResponse keyResponse=stacked.iControl->OfferKeyEventL(aKeyEvent,aType);

    74 		if (Count()==oldCount)

    75 			iKeyIndex=oldKeyIndex; // doing this means that CCoeControl::OfferKeyEventL implementations can be nested inside one another (which would happen if a control calls CCoeEnv::SimulateKeyEventL from it's OfferKeyEventL)

    76 		if (keyResponse==EKeyWasConsumed)

    77 			return(EKeyWasConsumed);

    78 		}

    79 	return(EKeyWasNotConsumed);

    80 	}

    81 

    82 

    83 //

    84 // CCoeAppUi::CExtra class definition

    85 //

    86 

    87 class CCoeAppUi::CExtra : public CBase

    88 	{

    89 public:

    90 	CCoeAppUi* iOuter; // this pointer does not own anything

    91 	CCoeAppUi* iInner; // this pointer does not own anything

    92 	};

    93 

    94 //

    95 // CCoeAppUi class definitions

    96 //

    97 

    98 /** C++ constructor. 

    99 

   100 To complete construction, call ConstructL(). */

   101 EXPORT_C CCoeAppUi::CCoeAppUi()

   102 	{

   103 	iCoeEnv=TheCoe();

   104 	}

   105 

   106 /** The destructor frees all resources owned by the object, 

   107 including the control stack and the view server session. */

   108 EXPORT_C CCoeAppUi::~CCoeAppUi()

   109 	{

   110 	if (iStack)

   111  		{

   112 		TInt pos=0;

   113 		const TInt count=iStack->Count();

   114 		CCoeControlStack* stack=iStack;

   115 		iStack=NULL;

   116 		while (pos<count)

   117 			{

   118 			SStackedControl& stacked=(*stack)[pos++];

   119 			if (stacked.iFlags&ECoeStackFlagOwnershipTransfered)

   120 				{

   121 				if (iExtra!=NULL)

   122 					{

   123 #if defined(STRICT_INNER_AND_OUTER_CHECKING)

   124 					// we do not need to remove stacked.iControl from outer appUI-s as controls owned by an appUI (which, by this stage, we know is true of stacked.iControl) are *not* propagated to outer appUIs by AddToStackL

   125 					__ASSERT_ALWAYS(iExtra->iInner==NULL, Panic(ECoePanicInnerAppUiNotNull1));

   126 #else

   127 					CCoeAppUi* appUi;

   128 					for (appUi=iExtra->iOuter; appUi!=NULL; appUi=appUi->iExtra->iOuter)

   129 						{

   130 						appUi->DoRemoveFromStack(appUi->iStack,stacked.iControl,ERemoveOnlyIfSharable);

   131 						}

   132 					for (appUi=iExtra->iInner; appUi!=NULL; appUi=appUi->iExtra->iInner)

   133 						{

   134 						appUi->DoRemoveFromStack(appUi->iStack,stacked.iControl,ERemoveOnlyIfSharable);

   135 						}

   136 #endif

   137 					}

   138 				delete(stacked.iControl);

   139 				}

   140 			}

   141 		delete(stack);

   142 		}

   143 	if (iExtra!=NULL)

   144 		{

   145 		CCoeAppUi* outer=iExtra->iOuter;

   146 		CCoeAppUi* inner=iExtra->iInner;

   147 		if (outer!=NULL)

   148 			{

   149 			outer->iExtra->iInner=inner;

   150 			}

   151 #if defined(STRICT_INNER_AND_OUTER_CHECKING)

   152 		__ASSERT_ALWAYS(inner==NULL, Panic(ECoePanicInnerAppUiNotNull2));

   153 #else

   154 		if (inner!=NULL)

   155 			{

   156 			inner->iExtra->iOuter=outer;

   157 			}

   158 #endif

   159 		}

   160 

   161 	delete iViewManager;

   162 	delete iExtra;

   163 	}

   164 

   165 /** Completes construction of the CCoeAppUi object.

   166 

   167 It creates the application's control stack and starts a view server session.

   168 

   169 @param aPrevious If non-NULL, ConstructL() transfers ownership of all of the 

   170 controls owned by aPrevious to the new app UI being constructed, adding them 

   171 to the new app UI's control stack. */

   172 EXPORT_C void CCoeAppUi::ConstructL(CCoeAppUi* aPrevious)

   173 	{

   174 	iStack=new(ELeave) CCoeControlStack;

   175 	iViewManager=CCoeViewManager::NewL(*iCoeEnv,*this,aPrevious);

   176 	iExtra=new(ELeave) CExtra;

   177 	iExtra->iOuter=aPrevious;

   178 	if (!aPrevious)

   179 		return;

   180 	aPrevious->iExtra->iInner=this;

   181 	CCoeControlStack* previousStack=aPrevious->iStack;

   182 	TInt pos=0;

   183 	const TInt count=previousStack->Count();

   184 	while (pos<count)

   185 		{

   186 		SStackedControl stacked=(*previousStack)[pos++];

   187 		if (!(stacked.iFlags&ECoeStackFlagSharable))

   188 			continue;

   189 		stacked.iFlags&=(~ECoeStackFlagOwnershipTransfered);

   190 		iStack->AppendL(stacked);

   191 		}

   192 	}

   193 

   194 /** Handles events sent to the application by the window server. 

   195 

   196 This function is called whenever the window server sends key or pointer events 

   197 or some other special events to the application. It calls one of a number of 

   198 functions, according to the type of event.

   199 

   200 For key events, it calls CCoeControl::OfferKeyEventL() for each control 

   201 on the control stack, beginning with the control at the top (position 0) until 

   202 a control consumes it. If no control on the stack consumes the key event, the app UI's  

   203 HandleKeyEventL() is called. Note that CCoeControl::OfferKeyEventL() is not 

   204 called for controls whose ECoeStackFlagRefusesAllKeys flag is set.

   205 

   206 For pointer events, CCoeControl::ProcessPointerEventL() is called 

   207 on the control specified in aDestination.

   208 

   209 For pointer buffer ready events, ProcessPointerBufferReadyL() is called 

   210 on the control specified in aDestination.

   211 

   212 For other events, for instance focus change events, this function 

   213 calls one of the following CCoeAppUi private virtual functions: 

   214 

   215 - HandleForegroundEventL()

   216 - HandleSwitchOnEventL()

   217 - HandleSystemEventL()

   218 - HandleScreenDeviceChangedL()

   219 - HandleApplicationSpecificEventL(). 

   220 

   221 All these functions have empty implementations in this class, and are implemented by 

   222 derived classes, if required.

   223 

   224 @param aEvent A window server event.

   225 @param aDestination The control associated with the event. This is only relevant 

   226 for pointer events.

   227 @see CCoeAppUi::HandleWsEventL() */

   228 EXPORT_C void CCoeAppUi::HandleWsEventL(const TWsEvent& aEvent,CCoeControl* aDestination)

   229 	{

   230 	TInt type=aEvent.Type();

   231 	switch (type)

   232 		{

   233 	case EEventKey:

   234 	case EEventKeyUp:

   235 	case EEventKeyDown:

   236 		if (iStack->OfferKeyL(*aEvent.Key(),(TEventCode)type)==EKeyWasNotConsumed)

   237 			HandleKeyEventL(*aEvent.Key(),(TEventCode)type);

   238 		break;

   239 	case EEventPointer:

   240 		aDestination->ProcessPointerEventL(*aEvent.Pointer());

   241 		break;

   242 	case EEventPointerBufferReady:

   243 		aDestination->ProcessPointerBufferReadyL();

   244 		break;

   245 	case EEventFocusLost:

   246 	case EEventFocusGained:

   247 		{

   248 		TBool foreground=(type==EEventFocusGained);

   249 		if (foreground)

   250 			{

   251 			iCoeEnv->NotifyForegroundObserversOfGainingForeground();

   252 			}

   253 		else

   254 			{

   255 			iCoeEnv->NotifyForegroundObserversOfLosingForeground();

   256 			}

   257 		CCoeControl* topFocusable=TopFocusableControl();

   258 		HandleForegroundEventL(foreground);

   259 		if (!topFocusable)

   260 			SetAndDrawFocus(foreground);

   261 		else if(IsControlOnStack(topFocusable))

   262 			{

   263 			TBool isFocused=topFocusable->IsFocused();

   264 			if ((foreground && !isFocused) || (!foreground && isFocused))

   265 				topFocusable->SetFocus(foreground,EDrawNow);

   266 			}

   267 		break;

   268 		}

   269 	case EEventSwitchOn:

   270 		HandleSwitchOnEventL(aDestination);

   271 		break;

   272 	case EEventUser:

   273 		{

   274 		TApaSystemEvent data(*(TApaSystemEvent*)(aEvent.EventData()));

   275 		// EApaSystemEventSecureShutdown must be sent with event-type EEventPowerMgmt to be valid

   276 		if(data<KApaSystemEventsWithPowerMgmtCapabilityStart || data>KApaSystemEventsWithPowerMgmtCapabilityEnd)

   277 			HandleSystemEventL(aEvent);

   278 		break;

   279 		}

   280 	case EEventPowerMgmt:

   281 		HandleSystemEventL(aEvent);

   282 		break;

   283 	case EEventMessageReady:

   284 		{

   285 		TUid messageUid;

   286 		TPtr8 messageParameters(NULL, 0, 0);

   287 		iCoeEnv->GetMessageNotifyingObserversLC(aEvent.Handle(), messageUid, messageParameters, aEvent);

   288 		CleanupStack::PopAndDestroy(); // stuff left on cleanup-stack by GetMessageNotifyingObserversLC

   289 		}

   290 		break;

   291 	case EEventScreenDeviceChanged:

   292 		HandleScreenDeviceChangedL();

   293 		break;

   294 		

   295 	default:

   296 		if (type>EEventUser)

   297 			{

   298 			HandleApplicationSpecificEventL(type,aEvent);

   299 			iCoeEnv->NotifyResourceObserversOfChangeInResource();

   300 			}

   301 		break;

   302 		}

   303 	}

   304 

   305 /**Monitor function for passing all windows events to registered monitor observers for optional inspection

   306 @param aEvent The windows server event that has occured

   307 */

   308 void CCoeAppUi::MonitorWsEvent(const TWsEvent& aEvent)

   309 	{

   310 	iCoeEnv->NotifyMessageMonitorObserversOfEvent(aEvent);

   311 	}

   312 		

   313 /** Handles key events. 

   314 

   315 This function is called by HandleWsEventL() if a key event occurred but 

   316 none of the controls in the app UI's control stack consumed it.

   317 

   318 Key events are sent to the application by the window server. A key press generates 

   319 three separate key events in the order EEventKeyDown, EEventKey, and EEventKeyUp. 

   320 Controls and app UIs are usually only interested in EEventKey events. 

   321 

   322 This default implementation simply returns EKeyWasNotConsumed. It may need to be 

   323 overridden if the derived app UI needs to handle certain key events itself. For 

   324 example, in some applications, arrow keys may be used to navigate between views. 

   325 In this case, the app UI should override this function to consume the arrow keys.

   326 

   327 @param aKeyEvent The key event details, including the key code and any modifiers.

   328 @param aType The type of key event, for instance standard, key up or key down.

   329 @return This indicates whether or not the key event was consumed by the app UI. 

   330 

   331 @publishedAll 

   332 @released */

   333 EXPORT_C TKeyResponse CCoeAppUi::HandleKeyEventL(const TKeyEvent& /*aKeyEvent*/,TEventCode /*aType*/)

   334 	{

   335 	return EKeyWasNotConsumed;

   336 	}

   337 

   338 

   339 /** Handles changes in keyboard focus when the application is brought to the 

   340 foreground, or put into the background.

   341 

   342 This function is called from HandleWsEventL() when an EEventFocusLost or 

   343 EEventFocusGained event occurs.

   344 

   345 This default implementation is empty.

   346 

   347 @param aForeground ETrue if the application is being brought to the 

   348 foreground, EFalse if it is being put into the background. */

   349 EXPORT_C void CCoeAppUi::HandleForegroundEventL(TBool /*aForeground*/)

   350 	{

   351 	}

   352 

   353 

   354 /** Handles the special switch on event.

   355 

   356 This function is called by HandleWsEventL() if the device is switched on. 

   357 This default implementation is empty.

   358 

   359 @param aDestination The control associated with the event. */

   360 EXPORT_C void CCoeAppUi::HandleSwitchOnEventL(CCoeControl* /*aDestination*/)

   361 	{

   362 	}

   363 

   364 

   365 /** Handles system events generated by the window server.

   366 

   367 This method should be overridden by the UI layer like @c CEikAppUi but not by individual applications. 

   368 Application events (has a positive value greater than EEventUser) will be sent to 

   369 @c HandleApplicationSpecificEventL.

   370 

   371 Unrecognized events should be forwarded to the base class.

   372 

   373 @param aEvent The window server event that occurred. */

   374 EXPORT_C void CCoeAppUi::HandleSystemEventL(const TWsEvent& /*aEvent*/)

   375 	{

   376 	}

   377 

   378 /** Handles an application-specific event.

   379 

   380 This function is called from HandleWsEventL() when the app UI receives a window 

   381 server event that is not in the standard range (in other words, it has a positive value 

   382 greater than EEventUser). 

   383 

   384 This default implementation is empty.

   385 

   386 @param aType The application-specific event value, greater than EEventUser.

   387 @param aEvent The window server event that occurred. */

   388 EXPORT_C void CCoeAppUi::HandleApplicationSpecificEventL(TInt /*aType*/,const TWsEvent& /*aEvent*/)

   389 	{

   390 	}

   391 

   392 /** Handles a change to the application's run-time resources for all controls on 

   393 the app UI's control stack.

   394 

   395 These are resources which are shared across the environment, such as colours, fonts or ZoomFactor.

   396 

   397 @param aType Specifies a resource type. */

   398 EXPORT_C void CCoeAppUi::HandleStackedControlsResourceChange(TInt aType)

   399 	{

   400 	TInt count=iStack->Count();

   401 	for(TInt i=0;i<count;i++)

   402 		{

   403 		CCoeControl* control = (*iStack)[i].iControl;

   404 		if (control && control->DrawableWindow())

   405 			{

   406 			if(aType == KUidValueCoeZoomChangeEvent)

   407 				{

   408 				TRAP_IGNORE(control->SetZoomFactorL(iCoeEnv->ZoomFactor().ZoomFactor()));//this method calls CCoeControl::HandleResourceChange()

   409 				}

   410 			else

   411 				{

   412 				control->HandleResourceChange(aType);	

   413 				}

   414 			}

   415 		

   416 		// There is a possibility that HandleResourceChange modifies the 

   417 		// number of controls on the stack (by adding or removing controls)

   418 		TInt newCount = iStack->Count();

   419 		if (newCount != count)

   420 			{

   421 			// We must make sure that we update i to ensure that we don't skip

   422 			// any control on the stack

   423 			// 1) If controls have been added then we assume that they already use the correct resources

   424 			//    so there isn't any need to update i no matter at which position they have been inserted

   425 			//    (there is a risk we update them unnecessarily but this shouldn't be a problem)

   426 			// 2) If controls have been removed we need to update i because they could have been removed 

   427 			//    at a position <= i in which case we would skip a few controls if we didn't update i

   428 			//    (as before there is a risk we update some controls twice if the removed controls were

   429 			//    at a position > i).

   430 			i = Max(-1, i + Min(0, newCount - count));   

   431 			count = newCount;

   432 			}

   433 		}

   434 	}

   435 

   436 //

   437 // Returns ETrue if aControl is present on this appUi's control stack

   438 //

   439 TBool CCoeAppUi::IsControlOnStack(CCoeControl* aControl) const

   440 	{

   441 	const TInt pos=(iStack? FindPos(iStack,aControl) : KErrNotFound);

   442 	return (pos!=KErrNotFound);

   443 	}

   444 	

   445 //

   446 // Sets the current control stack group id to aGroupId. Only if a stacked control is part of the 

   447 // current group does it play a part in the normal operation of the control stack.

   448 //

   449 // @since App-Framework_6.1

   450 //

   451 void CCoeAppUi::SetCurrentControlStackGroupId(TInt aGroupId)

   452 	{

   453 	iStack->SetCurrentGroupId(aGroupId);

   454 	}

   455 

   456 

   457 void CCoeAppUi::NotifyFontChange(const CCoeFontProvider& aFontProvider) 

   458     { 

   459     const CCoeFontProvider* fontProvider = &aFontProvider; 

   460     

   461     if(fontProvider == &iCoeEnv->DefaultFontProvider()) 

   462             fontProvider = NULL; 

   463             

   464     const TInt count = iStack->Count(); 

   465     for(TInt i = 0; i < count; i++) 

   466         { 

   467         CCoeControl* control = (*iStack)[i].iControl; 

   468         if (control && control->DrawableWindow()) 

   469             { 

   470             control->HandleResourceChange(KUidValueCoeFontChangeEvent); 

   471             control->NotifyFontChange(fontProvider); 

   472             } 

   473         } 

   474     } 

   475     

   476 /** Notify all CCoeFontProvider's that the global logical-to-pixel mapping has changed in 

   477 	CCoeControlStaticSettings

   478 	

   479 	@internalTechnology

   480 */

   481 void CCoeAppUi::RefetchPixelMappingL()

   482 	{

   483 	const TInt count = iStack->Count(); 

   484     for(TInt i = 0; i < count; i++) 

   485         { 

   486         CCoeControl* control = (*iStack)[i].iControl; 

   487         if (control && control->DrawableWindow()) 

   488             { 

   489             control->RefetchPixelMappingL(); 

   490             control->HandleResourceChange(KUidValueCoeFontChangeEvent);

   491     		control->RequestRelayout(NULL);

   492             } 

   493         } 	

   494 	}

   495 

   496 /** Returns a list of help contexts appropriate to the current state of the application.

   497 

   498 The array is generated from the help contexts for all visible controls on the app UI's 

   499 control stack, and from the app UI itself (via CCoeAppUi::HelpContextL()).

   500 

   501 @return A list of pointers to relevant help contexts. */

   502 EXPORT_C CArrayFix<TCoeHelpContext>* CCoeAppUi::AppHelpContextL() const

   503 	{

   504 	CArrayFix<TCoeHelpContext>* contexts=new(ELeave) CArrayFixFlat<TCoeHelpContext>(1);

   505 	CleanupStack::PushL(contexts);

   506 	// walk the control stack for active contexts

   507 	TInt count=iStack->Count();

   508 	for (TInt ii=0;ii<count;ii++)

   509 		{

   510 		SStackedControl stacked=(*iStack)[ii];

   511 		if ( !(iStack->IsGroupIdCurrent(stacked.iGroupId)) )

   512 			continue;

   513 		CCoeControl* ctrl=stacked.iControl;

   514 		if (ctrl->IsVisible())

   515 			{

   516 			TCoeHelpContext help;

   517 			ctrl->GetHelpContext(help);

   518 			if (!help.IsNull())

   519 				contexts->AppendL(help);

   520 			}

   521 		}

   522 	// ...then get any from the appui

   523 	CArrayFix<TCoeHelpContext>* appContexts=HelpContextL();

   524 	if (appContexts)

   525 		{

   526 		CleanupStack::PushL(appContexts);

   527 		count=appContexts->Count();

   528 		for (TInt ii=0;ii<count;ii++)

   529 			contexts->AppendL((*appContexts)[ii]);

   530 		CleanupStack::PopAndDestroy(); // appContexts

   531 		}

   532 	CleanupStack::Pop(); // contexts

   533 	return contexts;

   534 	}

   535 

   536 

   537 /** Sets the keyboard focus of a control and draws it.

   538 

   539 This is called by HandleWsEventL() when it receives a focus change event 

   540 and can also be called when a new control is moved to the top of the control 

   541 stack.

   542 

   543 This default implementation is empty. It is intended that an implementation 

   544 should set the value of a focus flag within the control to the value given by 

   545 aFocus. This flag indicates whether or not the control has keyboard focus. 

   546 The function should then draw or change the appearance of the control to indicate 

   547 whether or not it has focus.

   548 

   549 @param aFocus ETrue sets the control as having keyboard focus. EFalse sets 

   550 the control as not having keyboard focus. */

   551 EXPORT_C void CCoeAppUi::SetAndDrawFocus(TBool /*aFocus*/)

   552 	{

   553 	}

   554 

   555 

   556 /** Gets a list of help contexts for the app UI.

   557 

   558 This default implementation returns NULL.

   559 

   560 @return The array of help contexts. 

   561 

   562 @publishedAll

   563 @released  */

   564 EXPORT_C CArrayFix<TCoeHelpContext>* CCoeAppUi::HelpContextL() const

   565 	{

   566 	return NULL;

   567 	}

   568 

   569 /** Inserts a control into the app UI's control stack.

   570 

   571 Use the other AddToStackL() overload if the app UI uses multiple views.

   572 

   573 @param aControl The control to add to the stack.

   574 @param aPriority An optional control stack priority. The default value is 

   575 ECoeStackPriorityDefault. Higher priority controls are offered key events before lower 

   576 priority controls.

   577 @param aStackingFlags The control's event handling behaviour. 

   578 The possible values are defined in coeaui.h, beginning with ECoeStackFlagStandard. */

   579 EXPORT_C void CCoeAppUi::AddToStackL(CCoeControl* aControl,TInt aPriority,TInt aStackingFlags)

   580 	{

   581 	DoAddToStackL(iStack,aControl,aPriority,aStackingFlags);

   582 	if (aStackingFlags&ECoeStackFlagSharable)

   583 		{

   584 		const TBool ownershipTransfered=(aStackingFlags&ECoeStackFlagOwnershipTransfered);

   585 		aStackingFlags&=(~ECoeStackFlagOwnershipTransfered);

   586 #if defined(STRICT_INNER_AND_OUTER_CHECKING)

   587 		if (!ownershipTransfered)

   588 #endif

   589 			{

   590 			for (CCoeAppUi* appUi=iExtra->iOuter; appUi!=NULL; appUi=appUi->iExtra->iOuter)

   591 				{

   592 				appUi->DoAddToStackL(appUi->iStack,aControl,aPriority,aStackingFlags);

   593 				}

   594 			}

   595 #if defined(STRICT_INNER_AND_OUTER_CHECKING)

   596 		__ASSERT_ALWAYS(iExtra->iInner==NULL, Panic(ECoePanicInnerAppUiNotNull3));

   597 #else

   598 		for (CCoeAppUi* appUi=iExtra->iInner; appUi!=NULL; appUi=appUi->iExtra->iInner)

   599 			{

   600 			appUi->DoAddToStackL(appUi->iStack,aControl,aPriority,aStackingFlags);

   601 			}

   602 #endif

   603 		}

   604 	}

   605 

   606 /** Removes a control from the app UI's control stack.

   607 

   608 This function also handles any focus changes that may occur.

   609 

   610 @param aControl The control to remove from the stack. */

   611 EXPORT_C void CCoeAppUi::RemoveFromStack(CCoeControl* aControl)

   612 	{

   613 	DoRemoveFromStack(iStack,aControl);

   614 	CCoeAppUi* appUi;

   615 	if (iExtra)

   616 		{

   617 		for (appUi=iExtra->iOuter; appUi!=NULL; appUi=appUi->iExtra->iOuter)

   618 			{

   619 			appUi->DoRemoveFromStack(appUi->iStack,aControl,ERemoveUnconditionally);

   620 			}

   621 #if !defined(STRICT_INNER_AND_OUTER_CHECKING)

   622 		for (appUi=iExtra->iInner; appUi!=NULL; appUi=appUi->iExtra->iInner)

   623 			{

   624 			appUi->DoRemoveFromStack(appUi->iStack,aControl,ERemoveUnconditionally);

   625 			}

   626 #endif

   627 		}

   628 	}

   629 

   630 /** Handles changes to the control stack.

   631 

   632 This function ensures that the focusable control with the highest priority 

   633 on the control stack has keyboard focus.

   634 

   635 It may need to be called when a control's flag values are modified, by calling 

   636 UpdateStackedControlFlags(). It is called automatically when a control is added 

   637 to or removed from the stack. */

   638 EXPORT_C void CCoeAppUi::HandleStackChanged()

   639 	{

   640 	CCoeControl* toFocus=TopFocusableControl();

   641 	CCoeControl* focused=TopFocusedControl();

   642 	if (toFocus!=focused)

   643 		{

   644 		SetFocusToControl(focused,EFalse);

   645 		SetFocusToControl(toFocus,ETrue);

   646 		}

   647 	else if (!toFocus)

   648 		SetAndDrawFocus(ETrue);

   649 	}

   650 

   651 /** Tests whether the application is displaying a control between the given control 

   652 stack priorities. 

   653 

   654 @param aLowerPriority Lower bound.

   655 @param aHigherPriority Upper bound.

   656 @return ETrue if the application is currently displaying a control 

   657 which has a control stack priority between (but not including) 

   658 aLowerPriority and aHigherPriority. EFalse if not. */

   659 EXPORT_C TBool CCoeAppUi::IsDisplayingControlBetweenPriorities(TInt aLowerPriority, TInt aHigherPriority) const

   660 	{

   661 	TBool ret=EFalse;

   662 	const TInt count=iStack->Count();

   663 	for (TInt ii=0; ii<count; ii++)

   664 		{

   665 		SStackedControl sC=(*iStack)[ii];

   666 		if ( !(iStack->IsGroupIdCurrent(sC.iGroupId)) )

   667 			continue;

   668 		if (sC.iPriority>aLowerPriority && sC.iPriority<aHigherPriority)

   669 			{

   670 			if (sC.iControl->IsVisible())

   671 				{

   672 				ret=ETrue;

   673 				break;

   674 				}

   675 			}

   676 		}

   677 	return ret;

   678 	}

   679 

   680 /** Tests whether the application is displaying a menu bar or dialog.

   681 

   682 @return ETrue if the application is currently displaying a menu bar or a dialog. 

   683 EFalse if not. */

   684 EXPORT_C TBool CCoeAppUi::IsDisplayingMenuOrDialog() const

   685 	{

   686 	return IsDisplayingControlBetweenPriorities(ECoeStackPriorityMenu-1, ECoeStackPriorityCba) ||

   687 		   IsDisplayingControlBetweenPriorities(ECoeStackPriorityCba, ECoeStackPriorityAlert+1);

   688 	}

   689 

   690 /** Tests whether the application is displaying a dialog.

   691 

   692 @return ETrue if the application is currently displaying a dialog. 

   693 EFalse if not. */

   694 EXPORT_C TBool CCoeAppUi::IsDisplayingDialog() const

   695 	{

   696 	return IsDisplayingControlBetweenPriorities(ECoeStackPriorityDialog-1, ECoeStackPriorityCba) ||

   697 		   IsDisplayingControlBetweenPriorities(ECoeStackPriorityCba, ECoeStackPriorityAlert+1);

   698 	}

   699 

   700 /** Returns the input capabilities of the control with focus.

   701 

   702 Classes that override CCoeAppUi::HandleKeyEventL() should also override this 

   703 virtual function. The TCoeInputCapabilities object returned should have 

   704 attributes that match the behaviour of the HandleKeyEventL() function. 

   705 

   706 Overriding app UIs should do a base-call and "merge" 

   707 the returned input capabilities with its own input capabilities. If the overriding 

   708 InputCapabilities() function needs to get the input capabilities of any top-level 

   709 control, it should do so by calling CCoeControl::RecursivelyMergedInputCapabilities() 

   710 on that control.

   711 

   712 @return The types of input which can be consumed by the focussed control. */

   713 EXPORT_C TCoeInputCapabilities CCoeAppUi::InputCapabilities() const

   714 	{

   715 	// this only traverses the top focused control and its component-controls - should it go down the control-stack?

   716 	TCoeInputCapabilities inputCapabilities(TCoeInputCapabilities::ENone);

   717 	CCoeControl* topFocusedControl=TopFocusedControl();

   718 	if (topFocusedControl!=NULL)

   719 		{

   720 		topFocusedControl->RecursivelyMergeInputCapabilities(inputCapabilities);

   721 		}

   722 	return inputCapabilities;

   723 	}

   724 

   725 void CCoeAppUi::SetFocusToControl(CCoeControl* aControl,TBool aFocus)

   726 	{

   727 	if (aControl)

   728 		aControl->SetFocus(aFocus,EDrawNow);

   729 	else

   730 		SetAndDrawFocus(aFocus);

   731 	}

   732 

   733 /** Returns the top control of this appui which currently has the focus.

   734 

   735 @return Returns the top control of this AppUi which currently has the focus. If none of the 

   736 controls has focus it returns NULL.

   737 

   738 @internalTechnology */

   739 EXPORT_C CCoeControl* CCoeAppUi::TopFocusedControl() const

   740 	{

   741 	if (iStack)

   742 		{

   743 		TInt pos=0;

   744 		const TInt count=iStack->Count();

   745 		while (pos<count)

   746 			{

   747 			SStackedControl stacked=(*iStack)[pos++];

   748 			if ( !(iStack->IsGroupIdCurrent(stacked.iGroupId)) )

   749 				continue;

   750 			CCoeControl* const control=stacked.iControl;

   751 			if (control->IsFocused())

   752 				return(control);

   753 			}

   754 		}

   755 

   756 	return(NULL);

   757 	}

   758 

   759 CCoeControl* CCoeAppUi::TopFocusableControl() const

   760 	{

   761 	TInt pos=0;

   762 	const TInt count=iStack->Count();

   763 	while (pos<count)

   764 		{

   765 		SStackedControl& stacked=(*iStack)[pos++];

   766 		if ( !(iStack->IsGroupIdCurrent(stacked.iGroupId)) )

   767 			continue;

   768 		if (!(stacked.iFlags&ECoeStackFlagRefusesFocus))

   769 			return(stacked.iControl);

   770 		}

   771 

   772 	return(NULL);

   773 	}

   774 

   775 TInt CCoeAppUi::FindPos(CCoeControlStack* aStack,CCoeControl* aControl) const

   776 	{

   777 	TInt pos=0;

   778 	const TInt count=aStack->Count();

   779 	FOREVER

   780 		{

   781 		if (pos==count)

   782 			return(KErrNotFound);

   783 		if ((*aStack)[pos].iControl==aControl)

   784 			break;

   785 		pos++;

   786 		}

   787 	return(pos);

   788 	}

   789 

   790 /** Updates the flag values for a control on the control stack.

   791 

   792 The mask defines which flags are modified, while aFlags defines the values they 

   793 are set to.

   794 

   795 @param aControl The control to update.

   796 @param aFlags Contains the required value for each of the flag bits whose bit 

   797 is set in aMask.

   798 @param aMask Contains a set bit for each flag bit to modify.

   799 @panic CONE 4 The specified control is not on the stack. */

   800 EXPORT_C void CCoeAppUi::UpdateStackedControlFlags(CCoeControl* aControl,TInt aFlags,TInt aMask)

   801 	{

   802 	DoUpdateStackedControlFlags(iStack,aControl,aFlags,aMask);

   803 	}

   804 

   805 void CCoeAppUi::DoAddToStackL(CCoeControlStack* aStack,CCoeControl* aControl,TInt aPriority,TInt aStackingFlags)

   806 	{

   807 	if (IsControlOnStack(aControl))

   808 		return;

   809 	

   810 	DoAddToStackL(aStack,aControl,aPriority,aStackingFlags,KAppUiControlStackGroupId);

   811 	}

   812 

   813 void CCoeAppUi::DoAddToStackL(CCoeControlStack* aStack,CCoeControl* aControl,TInt aPriority,TInt aStackingFlags,TInt aGroupId)

   814 	{

   815 	SStackedControl newStacked;

   816 	newStacked.iControl=aControl;

   817 	newStacked.iPriority=aPriority;

   818 	newStacked.iFlags=aStackingFlags;

   819 	newStacked.iGroupId=aGroupId;

   820 	TInt pos=0;

   821 	const TInt count=aStack->Count();

   822 	while (pos<count)

   823 		{

   824 		if (aPriority>=(*aStack)[pos].iPriority)

   825 			break;

   826 		pos++;

   827 		}

   828 	aStack->InsertL(pos,newStacked);

   829 	if (pos<aStack->iKeyIndex)

   830 		aStack->iKeyIndex++;

   831 	HandleStackChanged();

   832 	}

   833 

   834 void CCoeAppUi::DoRemoveFromStack(CCoeControlStack* aStack,CCoeControl* aControl,TRemoveCondition aRemoveCondition)

   835 	{

   836 	if (!aStack)

   837 		return; // whole stack in process of destruction

   838 	TInt pos=FindPos(aStack,aControl);

   839 	if (pos>=0)

   840 		{

   841 		SStackedControl stacked=(*aStack)[pos];

   842 		if ((aRemoveCondition!=ERemoveOnlyIfSharable) || (stacked.iFlags&ECoeStackFlagSharable))

   843 			{

   844 			aStack->Delete(pos);

   845 			if (stacked.iFlags&ECoeStackFlagOwnershipTransfered)

   846 				delete stacked.iControl;

   847 			if (pos<aStack->iKeyIndex)

   848 				aStack->iKeyIndex--;

   849 			HandleStackChanged();

   850 			}

   851 		}

   852 	}

   853 

   854 void CCoeAppUi::DoUpdateStackedControlFlags(CCoeControlStack* aStack,CCoeControl* aControl,TInt aFlags,TInt aMask)

   855 	{

   856 	TInt pos=FindPos(aStack,aControl);

   857 	if (pos<0)

   858 		Panic(ECoePanicNoSuchControlInStack);

   859 	SStackedControl& stacked=(*aStack)[pos];

   860 	stacked.iFlags&=(~aMask);

   861 	stacked.iFlags|=(aFlags&aMask);

   862 	if ((stacked.iFlags&(ECoeStackFlagRefusesAllKeys|ECoeStackFlagRefusesFocus))==(ECoeStackFlagRefusesAllKeys|ECoeStackFlagRefusesFocus))

   863 		return; // else promote control to start of section of equi-priority controls

   864 	TInt startPos=pos;

   865 	while (startPos--)

   866 		{

   867 		if ((*aStack)[startPos].iPriority!=stacked.iPriority)

   868 			break;

   869 		}

   870 	if (++startPos==pos)

   871 		return;

   872 	SStackedControl copy=stacked;

   873 	aStack->Delete(pos);

   874 	TRAP_IGNORE(aStack->InsertL(startPos,copy)); // bound to succeed

   875 	}

   876 

   877 /** Activates an application view. 

   878 

   879 A leave occurs if view activation fails.

   880 

   881 @param aViewId Identifier of the view to activate. */

   882 EXPORT_C void CCoeAppUi::ActivateViewL(const TVwsViewId& aViewId)

   883 	{

   884 	iViewManager->ActivateViewL(aViewId);

   885 	}

   886 

   887 /** Activates an application view and passes a message to it.

   888 

   889 A leave occurs if view activation fails.

   890 

   891 Notes:

   892 

   893 Activation works synchronously so that in general, this method returns when 

   894 the view is activated.

   895 

   896 An application defines and publishes the message UIDs that it recognises. 

   897 For example, a contacts application might activate an email editor view, passing 

   898 an email address as a custom message. To do this, the contacts application 

   899 must use a message UID, and descriptor encoding that the email application 

   900 has published as being recognisable.

   901 

   902 @param aViewId Identifies the view to activate.

   903 @param aCustomMessageId Specifies the message type.

   904 @param aCustomMessage The message to pass to the activated view. */

   905 EXPORT_C void CCoeAppUi::ActivateViewL(const TVwsViewId& aViewId,TUid aCustomMessageId,const TDesC8& aCustomMessage)

   906 	{

   907 	iViewManager->ActivateViewL(aViewId,aCustomMessageId,aCustomMessage);

   908 	}

   909 

   910 

   911 /** Activates the top view for this app UI. 

   912 

   913 This is the most recently active view, if any. Otherwise, it activates the default view.

   914 If there is no default view, it activates the first registered view.

   915 

   916 @publishedPartner

   917 @released */

   918 EXPORT_C void CCoeAppUi::ActivateTopViewL()

   919 	{

   920 	iViewManager->ActivateTopViewL();

   921 	}

   922 

   923 /** Checks whether the view-server client that initiated the current view-switch matches the security-policy given in the parameter.

   924 

   925 This function leaves with KErrUnknown if called outside of an implementation of MCoeView's ViewConstructL or of MCoeView's ViewActivatedL.

   926 

   927 @see TSecurityPolicy

   928 

   929 @param aSecurityPolicy The TSecurityPolicy object which the client that initiated the current view switch must match.

   930 @param aDiagnostic A string that will be emitted along with any diagnostic message

   931 							that may be issued if the policy check fails.

   932 							This string should be enclosed in the __PLATSEC_DIAGNOSTIC_STRING macro

   933 							which enables it to be easily removed from the system.

   934 @return EFalse (zero) if the security-policy does not match the client that initiated the current view switch, other-wise returns "true", i.e. a non-zero value. */

   935 EXPORT_C TBool CCoeAppUi::CheckSourceOfViewSwitchL(const TSecurityPolicy& aSecurityPolicy,const char* aDiagnostic/*=NULL*/) const

   936 	{

   937 	return iViewManager->CheckSourceOfViewSwitchL(aSecurityPolicy,aDiagnostic);

   938 	}

   939 

   940 /** Deactivates the active view. 

   941 

   942 Deactivating the active view is necessary before exiting if the app UI has an active view.

   943 In most cases, DeactivateActiveViewIfOwnerMatch should be used instead of this function.

   944 

   945 @publishedAll

   946 @released 

   947 @see DeactivateActiveViewIfOwnerMatch */

   948 

   949 EXPORT_C void CCoeAppUi::DeactivateActiveViewL()

   950 	{

   951 	iViewManager->DeactivateActiveViewL();

   952 	}

   953 /** Deactivates the active view if the current view is owned by this application.

   954  

   955  Deactivating the active view is necessary before exiting if the app UI has an active view.

   956  This function is called by the UI framework during application closure.

   957  

   958  @publishedAll

   959  @released */

   960 EXPORT_C void CCoeAppUi::DeactivateActiveViewIfOwnerMatchL()

   961 	{

   962 	iViewManager->DeactivateActiveViewIfOwnerMatchL();

   963 	}

   964  

   965 

   966 /** Gets the ID of the app UI's currently active view. 

   967 

   968 @param aViewId On return, contains the ID of the currently active view. This is 

   969 unchanged if there is no active view.

   970 @return KErrNone if this app UI has an active view, KErrNotFound if it does not. */

   971 EXPORT_C TInt CCoeAppUi::GetActiveViewId(TVwsViewId& aViewId) const

   972 	{

   973 	return iViewManager->GetActiveViewId(aViewId);

   974 	}

   975 

   976 

   977 /** 

   978 @publishedPartner

   979 @deprecated

   980 */

   981 EXPORT_C void CCoeAppUi::RegisterViewAndAddStackL(MCoeView& aView)

   982 	{

   983 	iViewManager->RegisterViewL(aView);

   984 	}

   985 

   986 /** Registers a view with the view server.

   987 

   988 All views should be registered in the app UI's ConstructL().

   989 

   990 @param aView The view to be registered. */

   991 EXPORT_C void CCoeAppUi::RegisterViewL(MCoeView& aView)

   992 	{

   993 	iViewManager->RegisterViewL(aView);

   994 	}

   995 

   996 

   997 /** Registers a pseudo-view for the application identified by aAppUid.

   998 

   999 The view server is notified that a view exists for the application, which 

  1000 allows it to participate in the view switching mechanism, even though it does 

  1001 not implement any views.

  1002 

  1003 Activating the application view means bringing the application into the foreground.

  1004 

  1005 @param aAppUid The ID of the application for which a view should be registered.

  1006 @publishedAll

  1007 @released */

  1008 EXPORT_C void CCoeAppUi::RegisterApplicationViewL(TUid aAppUid)

  1009 	{

  1010 	iViewManager->RegisterApplicationViewL(aAppUid);

  1011 	}

  1012 

  1013 /** Deregisters the application view from the view architecture.

  1014 

  1015 @publishedAll

  1016 @released */

  1017 EXPORT_C void CCoeAppUi::DeregisterApplicationView()

  1018 	{

  1019 	if (iViewManager)

  1020 		{

  1021 		iViewManager->DeregisterApplicationView();

  1022 		}

  1023 	}

  1024 

  1025 /** Sets one of the app UI's views as the default. 

  1026 

  1027 The default view should be constructed, drawn, registered and set as the 

  1028 default as early as possible in the app UI's ConstructL() function. 

  1029 

  1030 The meaning of the default view varies depending on the UI. It is normally 

  1031 the view that is displayed when the application is launched. It may also 

  1032 be the view that is displayed when the application is brought to the 

  1033 foreground.

  1034 

  1035 @param aView The view to set as the default. */

  1036 EXPORT_C void CCoeAppUi::SetDefaultViewL(const MCoeView& aView)

  1037 	{

  1038 	iViewManager->SetDefaultViewL(aView);

  1039 	}

  1040 

  1041 

  1042 /** Sets the application view to be the default view. 

  1043 

  1044 In debug builds, this panics if no application view has been added for this app UI.

  1045 

  1046 @internalTechnology */

  1047 EXPORT_C void CCoeAppUi::SetApplicationViewAsDefaultL()

  1048 	{

  1049 	iViewManager->SetApplicationViewAsDefaultL();

  1050 	}

  1051 

  1052 /** Ensures that at least one view is registered for the app UI. 

  1053 

  1054 It adds an application view as the default if no views have been added,

  1055 so that the application can participate in the view switching mechanism. 

  1056 It also sets a default view if none has been set. 

  1057 

  1058 This is called by the UI framework during application construction.

  1059 

  1060 @param aAppUid The application's 3rd UID.

  1061 @publishedPartner

  1062 @released */

  1063 EXPORT_C void CCoeAppUi::CheckInitializeViewsL(TUid aAppUid)

  1064 	{

  1065 	iViewManager->CheckInitializeViewsL(aAppUid);

  1066 	}

  1067 

  1068 /** Gets this app UI's default view ID.

  1069 

  1070 @param aViewId On return, contains the ID of the app UI's default view.

  1071 This is unchanged if there is no default view.

  1072 @return KErrNone if this app UI has a default view, KErrNotFound if 

  1073 it doesn't.*/

  1074 EXPORT_C TInt CCoeAppUi::GetDefaultViewId(TVwsViewId& aViewId) const

  1075 	{

  1076 	return iViewManager->GetDefaultViewId(aViewId);

  1077 	}

  1078 

  1079 

  1080 /**

  1081 @publishedPartner

  1082 @deprecated

  1083 */

  1084 EXPORT_C void CCoeAppUi::DeregisterViewAndRemoveStack(const MCoeView& aView)

  1085 	{

  1086 	if (iViewManager)

  1087 		{

  1088 		iViewManager->DeregisterView(aView);

  1089 		}

  1090 	}

  1091 

  1092 /** Deregisters a view. 

  1093 

  1094 All views must be deregistered before the application exits. This is

  1095 usually done in the app UI's destructor.

  1096 

  1097 It has no effect if the specified view does not exist.

  1098 

  1099 @param aView The view to be deregistered. */

  1100 EXPORT_C void CCoeAppUi::DeregisterView(const MCoeView& aView)

  1101 	{

  1102 	if (iViewManager)

  1103 		{

  1104 		iViewManager->DeregisterView(aView);

  1105 		}

  1106 	}

  1107 

  1108 /** Inserts a control into the app UI's control stack.

  1109 

  1110 @param aView The view that contains the control.

  1111 @param aControl The control to add to the stack. This may itself be a view.

  1112 @param aPriority An optional control stack priority. The default value is 

  1113 ECoeStackPriorityDefault. Higher priority controls are offered key events before lower 

  1114 priority controls. 

  1115 @param aStackingFlags The control's event handling behaviour. 

  1116 The possible values are defined in coeaui.h, beginning with ECoeStackFlagStandard. */

  1117 EXPORT_C void CCoeAppUi::AddToStackL(const MCoeView& aView,CCoeControl* aControl,TInt aPriority,TInt aStackingFlags)

  1118 	{

  1119 	DoAddToStackL(iStack,aControl,aPriority,aStackingFlags,aView.ViewId().iViewUid.iUid);

  1120 	}

  1121 

  1122 

  1123 /**

  1124 @publishedAll 

  1125 @deprecated

  1126 */

  1127 EXPORT_C void CCoeAppUi::AddToViewStackL(const MCoeView& aView,CCoeControl* aControl,TInt aPriority,TInt aStackingFlags)

  1128 	{

  1129 	DoAddToStackL(iStack,aControl,aPriority,aStackingFlags,aView.ViewId().iViewUid.iUid);

  1130 	}

  1131 

  1132 

  1133 /**

  1134 @publishedAll 

  1135 @deprecated