/*

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

* All rights reserved.

* This component and the accompanying materials are made available

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

* which accompanies this distribution, and is available

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

*

* Initial Contributors:

* Nokia Corporation - initial contribution.

*

* Contributors:

*

* Description:  System for managing global popup window priorities

*

*/

#ifndef AKNGLOBALPOPUPPRIORITYCONTROLLER_H

#define AKNGLOBALPOPUPPRIORITYCONTROLLER_H

#include <e32std.h>

#include <coeaui.h>

class MAknFadedComponent;

class TAknPopupFader;

/**

 * AknGlobalPopupPriorityController is the public interface

 * of the Popup Priority Controller system. This system is

 * used in place of other window position, window group position,

 * control stack and fade stack

 * APIs to give correct behavior when prioritised

 * notifiers and other global popups are displayed.

 * The system works by allowing popups to be associated with

 * a priority. When the system is enabled and a popup is shown,

 * the app's window group will be brought forward to a priority

 * of ECoeWinPriorityAlwaysAtFront + (highest shown popup priority).

 * The app's window group is pushed to the background when no

 * popups are displayed.

 * Therefore this system should only be enabled for applications

 * who only display popup windows, ie the notifier host apps.

 * @since 3.2

 * @capability SwEvent is required to display popups at global priorities.

 */

class AknGlobalPopupPriorityController

	{

public:

	/**

	* Enables the Popup Priority Controller in this app.

	* Before this function is called, all other functions in

	* this API have no effect.

	* It is safe to use the other APIs in all apps. They will only

	* have effect where the system is enabled.

 	*/

	IMPORT_C static void EnablePriorityControlL();

	/**

	* Set whether global popups are to be shown or not.

	* If global popups are not allowed, the app's window group

	* will be pushed to the background.

	* Callers will need SwEvent

	* @param aAllow, ETrue if global popups can be shown, EFalse if not.

	*/

	IMPORT_C static void AllowGlobalPopups(TBool aAllow);

	/**

	 * Return whether global popups are to be shown or not.

	 */

	IMPORT_C static TBool GlobalPopupsAllowed();

	/**

	* Sets the priority for a popup control.

	* The priority affects two things, how the popup is displayed

	* in relation to other popups and how the app is displayed in

	* relation to other apps.

	* Popups with higher priority will have their windows placed

	* before popups with lower priority.

	* The app's window group priority will be affected by the

	* highest priority popup shown.

	* If a popup does not have a priority set, it is automatically

	* given the default value of 0. Low priority popups should be

	* given negative priority values. High priority popups should

	* be given positive priority values.

	* @param aPopup, the popup control whose priority is to be set.

	* @param aPriority, the priority of the popup.

	*/

	IMPORT_C static void SetPopupPriorityL(CCoeControl& aPopup, TInt aPriority);

	/**

	* Removes a popup from the set of shown popups and forgets

	* the popup parameters. When a popup is set with any of the

	* other APIs in this class,

	* this function must be called when the popup is deleted.

	* The common popup classes CEikDialog, CAknChoiceList,

	* and CAknPopupList all call this from their destructors, in case

	* their clients set a priority for them.

	*/

	IMPORT_C static void RemovePopupPriority(CCoeControl& aPopup);

	/**

	* Sets whether a popup is shown or not, which can affect the 

	* popup's window priority, the app's window group priority,

	* the control stack and the fade stack.

	* When a popup is shown, it is added to a list of shown popups

	* and its window priority is set according to the position in this

	* list. If the highest priority popup changes, the window

	* group priority for the app is changed according to the new

	* highest priority popup.

	* The highest priority popup will also be activated on the control stack

	* and placed at the top of the fade stack.

	* @param aPopup, the popup which is having its shown status set.

	* @param aShow, ETrue if the popup is being shown, EFalse otherwise.

	*/

	IMPORT_C static void ShowPopup(CCoeControl& aPopup, TBool aShow);

	/**

	* Sets the ordinal position for the Eikon environment's root window group,

	* that will be used when a popup is shown.

	* @param aOrdinalPosition the ordinal position which the window group will

	* use when showing popups. Note, ordinal position only affects windows groups

	* with the same ordinal priority. Since popup priority affects window group

	* ordinal priority, setting the ordinal position will have only a minor effect.

	*/

	IMPORT_C static void SetRootWinOrdinalPosition(TInt aOrdinalPosition);

	/**

	* Adds a sub-popup to a parent popup. For instance a softkey control could

	* be added to a global note popup window.

	* The sub-popup's window and control stack positions will be changed as

	* its parent's positions are changed.

	* A popup may have at most one sub-popup and one parent popup.

	* @param aPopup the parent popup which will be have the sub popup added to it.

	* @param aSubPopup the sub popup which is to follow the control stack and

	* window position behavior of its parent.

	*/

	IMPORT_C static void AddSubPopupL(CCoeControl& aPopup, CCoeControl& aSubPopup);

	/**

	* Puts a popup on the control stack with the specified priority and flags.

	* If the popup (or its ultimate parent if it's a sub-popup) are not the

	* highest priority popup, the control stack flags ECoeStackFlagRefusesAllKeys

	* and ECoeStackFlagRefusesFocus will be added in. This makes the popup behave

	* like a sleeping dialog while in the background. For correct behavior, 

	* the priority and flag parameters should be set as if the popup were in the foreground.

	* This function analogous to CCoeAppUi::AddToStackL, and should be used in place

	* of that for controls which may be used as global popups. When global popups

	* are not enabled, this function forwards the call to CCoeAppUi::AddToStackL.

	* It is still the responsibility of the calling code to remove popups from the

	* control stack using CCoeAppUi::RemoveFromStack.

	* @param aPopup the popup or sub-popup which should be added to the control stack.

	* @param aPriority the control stack priority for this popup

	* @param aStackingFlags the control stack flags for this popup

	*/

	IMPORT_C static void AddPopupToControlStackL(CCoeControl& aPopup,TInt aPriority=ECoeStackPriorityDefault,TInt aStackingFlags=ECoeStackFlagStandard);

	/**

	* Modifies the control stack flags as appropriate for a sleeping popup.

	* This function is analogous to CEikonEnv::RouseSleepingDialog. When global popups

	* are not enabled, this function forwards the call to CEikonEnv::RouseSleepingDialog.

	* @param aPopup the popup which should be roused.

	* @param aRoused whether the popup should be roused or sent back to sleep.

	*/

	IMPORT_C static void RouseSleepingPopup(CCoeControl& aPopup, TBool aRoused);

	/**

	* This allows the global priority controller to control fade such that the

	* top global popup is unfaded, and all other windows are faded.

	* This function is analogous to TAknPopupFader::FadeBehindPopup. When global popups

	* are not enabled, this function forwards the call to TAknPopupFader::FadeBehindPopup.

	* @param aPopup the popup to which the fade parameters apply

	* @param aFader the TAknPopupFader normally used by the popup (nb this is not

	* stored, so can be temporary).

	* @param aFadedComponent the faded component interface, allowing access to the

	* components of the popup.

	* @param aFade whether the screen behind the popup should be faded or not.

	*/

	IMPORT_C static void FadeBehindPopup(CCoeControl& aPopup, TAknPopupFader& aFader, MAknFadedComponent& aFadedComponent, TBool aFade);

	};

#endif