--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/classicui_plat/discreet_popup_api/inc/akndiscreetpopup.h Tue Feb 02 01:00:49 2010 +0200
@@ -0,0 +1,407 @@
+/*
+* 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