/*
* Copyright (c) 2009 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: Discreet popup
*
*/
#ifndef C_AKNDISCREETPOPUP_H
#define C_AKNDISCREETPOPUP_H
#include <coemain.h>
#include <AknsConstants.h>
#include <coecobs.h>
class CAknDiscreetPopupControl;
class MEikCommandObserver;
class CGulIcon;
class CAknDiscreetPopupServerHandler;
/**
* Discreet popup is used for notifying user of system generated or user
* activated events without blocking the flow of usage.
*
* The popup duration can be
* 1) Short (by default). It is used when the user can expect a note to appear,
* like confirmations, and when the nature of the message is positive,
* i.e. the attempted operation was successful. The duration is 1.5 seconds.
* 2) Long (KAknDiscreetPopupDurationLong flag). It is used when the note may
* appear spontaneously, i.e. without user action, or if the message content
* is not what the user probably expected (e.g. an error).
* The duration is 3.0 seconds.
*
* @lib avkon
* @since S60 v5.2
*/
NONSHARABLE_CLASS( CAknDiscreetPopup ) : public CCoeStatic,
public MCoeControlObserver
{
public:
/**
* Destructor.
*/
~CAknDiscreetPopup();
/**
* Displays a local discreet popup which is created according
* to given parameters.Local discreet popup is an application-specific
* discreet popup that is visible when the parent application is active
* and visible.
*
* Title text is the only compulsory parameter.
* Icon can be provided either
* 1) By providing CGulIcon object with aIcon parameter or
* 2) By providing icon skin id and bitmap file information.
* If CGulIcon object is provided, skin and bitmap information is ignored.
* Popup can inform its command observer that it has been tapped
* through MEikCommandObserver interface.
*
* Possible discreet popup flags are:
*
* KAknDiscreetPopupDurationLong for long discreet popup duration.
* Default duration is short.
*
* KAknDiscreetPopupConfirmationTone - popup plays the confirmation tone.
* KAknDiscreetPopupWarningTone - popup plays the warning tone.
* KAknDiscreetPopupErrorTone - popup plays the error tone.
* By default no tone is played.
*
* @since S60 v5.2
* @param aTitle First line of text.
* @param aText Second line of text.
* @param aIcon Icon.
* @param aSkinId Icon skin item id.
* @param aBitmapFile Icon bitmap file.
* @param aBitmapId Icon bitmap id.
* @param aMaskId Icon mask id.
* @param aFlags Popup flags.
* @param aCommand Popup command id.
* @param aCommandObserver Popup command observer.
* @return Unique id for popup.
* @panic EAknPanicNotSupported The method is called from application
* without existing CCoeEnv.
*/
IMPORT_C static TInt ShowLocalPopupL(
const TDesC& aTitle,
const TDesC& aText = KNullDesC,
CGulIcon* aIcon = NULL,
const TAknsItemID& aSkinId = KAknsIIDNone,
const TDesC& aBitmapFile = KNullDesC,
const TInt aBitmapId = 0,
const TInt aMaskId = 0,
const TInt aFlags = 0,
const TInt aCommand = 0,
MEikCommandObserver* aCommandObserver = NULL );
/**
* Displays a local discreet popup which is created according
* to given resource id.Local discreet popup is an application-specific
* discreet popup that is visible when the parent application is active
* and visible.
*
* Popup can inform its command observer that it has been tapped
* through MEikCommandObserver interface.
*
* @param aResourceId Discreet popup resource id.
* @param aCommand Popup command id.
* @param aCommandObserver Popup command observer.
* @return Unique id for popup.
* @panic EAknPanicNotSupported The method is called from application
* without existing CCoeEnv.
*/
IMPORT_C static TInt ShowLocalPopupL(
const TInt aResourceId,
const TInt aCommand = 0,
MEikCommandObserver* aCommandObserver = NULL );
/**
* Displays a global discreet popup which is created according
* to given parameters. Global discreet notifications remains
* visible when user navigates from application to another.
*
* Title text is the only compulsory parameter.
*
* Possible discreet popup flags are:
*
* KAknDiscreetPopupDurationLong for long discreet popup duration.
* Default duration is short.
*
* KAknDiscreetPopupConfirmationTone - popup plays the confirmation tone.
* KAknDiscreetPopupWarningTone - popup plays the warning tone.
* KAknDiscreetPopupErrorTone - popup plays the error tone.
* By default no tone is played.
*
* Note: If caller does not have an existing control environment (CCoeEnv),
* CAknDiscreetPopup::InitL should be called to initialize discreet popup
* before calling this method. In addition, CAknDiscreetPopup::Release
* should be called when there is no need for discreet popup anymore.
* Otherwise all allocated resources will not be freed.
*
* @since S60 v5.2
* @param aTitle First line of text.
* @param aText Second line of text.
* @param aSkinId Icon skin item id.
* @param aBitmapFile Icon bitmap file.
* @param aBitmapId Icon bitmap id.
* @param aMaskId Icon mask id.
* @param aFlags Popup flags.
* @param aCommand Popup command id.
* @param aCommandObserver Popup command observer.
* @param aAppUid Application uid to be launched.
* @param aViewUid Application view uid to be activated.
* @return Unique id for popup.
*/
IMPORT_C static TInt ShowGlobalPopupL(
const TDesC& aTitle,
const TDesC& aText = KNullDesC,
const TAknsItemID& aSkinId = KAknsIIDNone,
const TDesC& aBitmapFile = KNullDesC,
const TInt aBitmapId = 0,
const TInt aMaskId = 0,
const TInt aFlags = 0,
const TInt aCommandId = 0,
MEikCommandObserver* aCommandObserver = NULL,
const TUid& aAppUid = TUid::Null(),
const TUid& aViewUid = TUid::Null() );
/**
* Displays a global discreet popup which is created according
* to given resource id. Global discreet notifications remains
* visible when user navigates from application to another.
*
* Note: If caller does not have an existing control environment (CCoeEnv),
* CAknDiscreetPopup::InitL should be called to initialize discreet popup
* before calling this method. In addition, CAknDiscreetPopup::Release
* should be called when there is no need for discreet popup anymore.
* Otherwise all allocated resources will not be freed.
*
* @since S60 v5.2
* @param aResourceId Discreet popup resource id.
* @param aResourceFile Discreet popup resource file path.
* @param aCommand Popup command id.
* @param aCommandObserver Popup command observer.
* @param aAppUid Application uid to be launched.
* @param aViewUid Application view uid to be activated.
* @return Unique id for popup.
*/
IMPORT_C static TInt ShowGlobalPopupL(
const TInt aResourceId,
const TDesC& aResourceFile,
const TInt aCommandId = 0,
MEikCommandObserver* aCommandObserver = NULL,
const TUid& aAppUid = TUid::Null(),
const TUid& aViewUid = TUid::Null() );
/**
* Initializes discreet popup when discreet popup
* is launched in application with no existing CCoeEnv.
* Note: This method is intended only for usage of those applications
* that do not have an existing control environment (CCoeEnv) and should
* be called only once.
*
* @panic EAknPanicNotSupported
* The method is called from application with existing CCoeEnv.
*/
IMPORT_C static void InitL();
/**
* Releases discreet popup resources when discreet popup
* is launched in application with no existing CCoeEnv.
* Note: This method is intended only for usage of those applications
* that do not have an existing control environment (CCoeEnv) and should
* be called only once when the application terminates.
*
* @panic EAknPanicNotSupported
* The method is called from application with existing CCoeEnv.
*/
IMPORT_C static void Release();
private:
/**
* C++ constructor.
*/
CAknDiscreetPopup();
/**
* C++ constructor.
*/
CAknDiscreetPopup( TBool aUseCoeEnv );
/**
* Symbian second-phase constructor.
*/
void ConstructL();
/**
* Provides the discreet popup singleton.
*
* @return Discreet popup instance.
*/
static CAknDiscreetPopup* InstanceL();
/**
* Launches the local popup.
*
* @param aTitle First line of text.
* @param aText Second line of text.
* @param aIcon Icon.
* @param aSkinId Icon skin item id.
* @param aBitmapFile Icon bitmap file.
* @param aBitmapId Icon bitmap id.
* @param aMaskId Icon mask id.
* @param aFlags Popup flags.
* @param aCommand Popup command id.
* @param aCommandObserver Popup command observer.
* @return Unique id for popup.
*/
TInt DoShowLocalL(
const TDesC& aTitle,
const TDesC& aText,
CGulIcon* aIcon,
const TAknsItemID& aSkinId,
const TDesC& aBitmapFile,
const TInt& aBitmapId,
const TInt& aMaskId,
const TInt& aFlags,
const TInt& aCommand,
MEikCommandObserver* aCommandObserver );
/**
* Launches the local popup, if the queues are empty.
* If not, the popup is added to a queue.
*
* @param aResourceId Discreet popup resource id.
* @param aCommand Popup command id.
* @param aCommandObserver Popup command observer.
* @return Unique id for popup.
*/
TInt DoShowLocalL(
const TInt& aResourceId,
const TDesC& aResourceFile,
const TInt& aCommand,
MEikCommandObserver* aCommandObserver );
/**
* Launches the global popup.
*
* @param aTitle First line of text.
* @param aText Second line of text.
* @param aSkinId Icon skin item id.
* @param aBitmapFile Icon bitmap file.
* @param aBitmapId Icon bitmap id.
* @param aMaskId Icon mask id.
* @param aFlags Popup flags.
* @param aCommand Popup command id.
* @param aCommandObserver Popup command observer.
* @param aAppUid Application uid to be launched.
* @param aViewUid Application view uid to be activated.
* @return Unique id for popup.
*/
TInt DoShowGlobalL(
const TDesC& aTitle,
const TDesC& aText,
const TAknsItemID& aSkinId,
const TDesC& aBitmapFile,
const TInt& aBitmapId,
const TInt& aMaskId,
const TInt& aFlags,
const TInt& aCommandId,
MEikCommandObserver* aCommandObserver,
const TUid& aAppUid,
const TUid& aViewUid );
/**
* Launches the global popup.
*
* @param aResourceId Discreet popup resource id.
* @param aResourceFile Discreet popup resource file path.
* @param aCommand Popup command id.
* @param aCommandObserver Popup command observer.
* @param aAppUid Application uid to be launched.
* @param aViewUid Application view uid to be activated.
* @return Unique id for popup.
*/
TInt DoShowGlobalL(
const TInt& aResourceId,
const TDesC& aResourceFile,
const TInt& aCommandId,
MEikCommandObserver* aCommandObserver,
const TUid& aAppUid,
const TUid& aViewUid );
/**
* This method shows the created popup control.
*
* @param aControl Created popup control.
*/
void ShowPopupL( CAknDiscreetPopupControl* aControl );
/**
* This method deletes the popup and removes it from
* CAknDiscreetPopup popup list.
*
* @param aControl Closed popup control.
*/
void DeletePopup( CAknDiscreetPopupControl* aControl );
/**
* Returns next available popup id.
*
* @return Next available popup id.
*/
TInt NextPopupId();
/**
* Checks if popup id is already in use among local popups.
*
* @return ETrue if popup id is already in use.
*/
TBool PopupIdInUse( const TInt& aPopupId );
// from base class MCoeControlObserver
/**
* Handles an event from an observed control.
*
* @param aControl The control that sent the event.
* @param aEventType The event type.
*/
void HandleControlEventL( CCoeControl* aControl, TCoeEvent aEventType );
private: // data
/**
* Local popup array.
*/
RPointerArray<CAknDiscreetPopupControl> iLocalPopups;
/**
* Ui server handler.
* Own.
*/
CAknDiscreetPopupServerHandler* iServerHandler;
/**
* ETrue if CoeEnv exists.
*/
TBool iUseCoeEnv;
};
#endif // C_AKNDISCREETPOPUP_H