--- a/epoc32/include/mw/aknnotedialog.h Tue Nov 24 13:55:44 2009 +0000
+++ b/epoc32/include/mw/aknnotedialog.h Tue Mar 16 16:12:26 2010 +0000
@@ -1,1 +1,658 @@
-aknnotedialog.h
+/*
+* Copyright (c) 2002 Nokia Corporation and/or its subsidiary(-ies).
+* All rights reserved.
+* This component and the accompanying materials are made available
+* under the terms of the License "Symbian Foundation License v1.0" to Symbian Foundation members and "Symbian Foundation End User License Agreement v1.0" to non-members
+* which accompanies this distribution, and is available
+* at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".
+*
+* Initial Contributors:
+* Nokia Corporation - initial contribution.
+*
+* Contributors:
+*
+* Description:
+* Provides the CAknDialog-derived interface to Avkon Notes.
+*
+*/
+
+
+#ifndef __AKNNOTEDIALOG__
+#define __AKNNOTEDIALOG__
+
+#include <eikdialg.h>
+#include "avkon.hrh"
+class CEikImage;
+class CAknKeySoundSystem;
+class CAknNoteControl;
+class CAknNoteAttributes;
+class CAknNoteDialogExtension;
+
+
+/**
+ * The note dialog.
+ *
+ * Displays a note to the user for: <UL> <LI> Giving notifications. </LI>
+ * <LI> Asking questions. </LI> <LI> Showing progress. </LI> </UL>
+ *
+ * @see CAknNoteControl, CAknNoteAttributes, CAknText
+ */
+class CAknNoteDialog : public CEikDialog
+{
+
+public:
+
+ /**
+ * The timeout in microseconds for automatically deleting the dialog.
+ */
+ enum TTimeout {
+
+ /**
+ * Deprecated (not used).
+ *
+ * @deprecated
+ */
+ EUndefinedTimeout = 0,
+ /// No timeout
+ ENoTimeout = 0,
+ /// 1.5 seconds
+ EShortTimeout = 1500000,
+ /// 3 seconds
+ ELongTimeout = 3000000,
+ /// 0.5 second
+ EShortestTimeout = 500000
+ };
+
+ /**
+ * The tone played before the dialog is shown.
+ *
+ * Application specific tones may be played by casting the application
+ * defined Sound ID (SID), to @c TTone.
+ */
+ enum TTone {
+
+ /** No tone is played. */
+ ENoTone = 0,
+
+ /** A confirmation tone is played. */
+ EConfirmationTone = EAvkonSIDConfirmationTone,
+
+ /** A warning tone is played. */
+ EWarningTone = EAvkonSIDWarningTone,
+
+ /** An error tone is played. */
+ EErrorTone = EAvkonSIDErrorTone
+ };
+
+public:
+
+ /**
+ * C++ default constructor.
+ *
+ * Initialises the tone to @c ENoTone and the timeout to @c ENoTimeout.
+ *
+ * @see @c TTone, @c TTimeout.
+ */
+ IMPORT_C CAknNoteDialog();
+
+ /**
+ * C++ default constructor.
+ *
+ * Initialises the tone to @c aTone and the timeout to @c aTimeout.
+ *
+ * @param aTone The tone to be played.
+ * @param aTimeout The timeout (microseconds). Default is @c ENoTimeout.
+ * @see @c TTone, @c TTimeout.
+ */
+ IMPORT_C CAknNoteDialog(const TTone& aTone,
+ const TTimeout& aTimeout = ENoTimeout);
+
+ /**
+ * C++ default constructor.
+ *
+ * Initialises the tone to @c aTone and the timeout to @c aTimeout.
+ * Accepts a pointer to @c CEikDialog*. This must be the address of
+ * the dialog pointer. When the dialog deletes itself after a timeout,
+ * the address pointed to by this pointer is set to NULL. The dialog must
+ * not be on the stack, it must be on the heap!
+ *
+ * @param aSelfPtr Pointer to the address of the dialog.
+ * @param aTone = @c ENoTone The tone.
+ * @param aTimeout = @c ENoTimeout The timeout (microseconds).
+ * @see @c TTone, @c TTimeout.
+ */
+ IMPORT_C CAknNoteDialog(CEikDialog** aSelfPtr,
+ const TTone& aTone = ENoTone,
+ const TTimeout& aTimeout = ENoTimeout);
+
+ /**
+ * Destructor.
+ *
+ * Deletes timer and control attributes. If the self pointer is not null,
+ * sets the pointer to point to NULL.
+ */
+ IMPORT_C virtual ~CAknNoteDialog();
+
+ /**
+ * Sets the dialog timeout.
+ *
+ * @see @c TTimeout.
+ * @param aTimeout The dialog timeout.
+ */
+ IMPORT_C void SetTimeout(const TTimeout& aTimeout);
+
+ /**
+ * Sets the dialog tone .
+ *
+ * @see @c TTone.
+ * @param aTone The dialog tone.
+ */
+ IMPORT_C void SetTone(const TTone& aTone);
+
+ /**
+ * Enables or disables text wrapping.
+ *
+ * Enables or disables text wrapping depending on the values
+ * of @c aEnabled (true enables text wrapping). When text wrapping is
+ * disabled a new line in the note dialog starts only after a newline
+ * character in the note text. If a line does not fit into the dialog
+ * width it is clipped (the last character is replaced with an
+ * ellipsis sign).
+ *
+ * This method must be called before @c SetTextL as it only influences
+ * the wrapping of text that it is yet to be set via API.
+ *
+ * @param aEnabled @c ETrue for enabling text wrapping, @c EFalse for
+ * disabling it.
+ */
+ IMPORT_C void SetTextWrapping(TBool aEnabled);
+
+ /**
+ * Enables or disables all text processing done by the dialog.
+ * This includes text wrapping, text truncation
+ * and reordering of bidirectional text.
+ *
+ * By default, it is enabled.
+ *
+ * If text processing is disabled, lines are broken only at explicit
+ * line end characters and they are not truncated, but drawn as long
+ * as they fit. Also, the dialog does not handle reordering of
+ * the bidirectional text.
+ *
+ * This method must be called before the text is set.
+ *
+ * @param aEnabled Enables or disables all text processing.
+ */
+ IMPORT_C void SetTextProcessing(TBool aEnabled);
+
+ /**
+ * Set the dialog image.
+ *
+ * Change the image in the note control. Override the image which was
+ * set in the resource file. The dialog takes ownership of the pointer.
+ * The note image is the big image or icon which is top right.
+ *
+ * @param aImage Pointer to the new image.
+ */
+ IMPORT_C void SetImageL(CEikImage* aImage);
+
+ /**
+ * Sets the dialog icon.
+ *
+ * Changes the number type icon in the note control.
+ *
+ * Overrides the icon which was set in the resource file. The dialog takes
+ * ownership of the pointer The numbertype icon is the small icon which
+ * is bottom left in the note (thumbnail icon).
+ *
+ * @param aIcon Pointer to the icon.
+ */
+ IMPORT_C void SetIconL(CEikImage* aIcon);
+
+ /**
+ * Sets the number in the dialog text.
+ *
+ * Sets a number in the note text. If the text specified in the resource
+ * file or via @c SetTextL() has a \%d in it, e.g. "You have \%d new
+ * messages", this number is inserted at the location specified by \%d.
+ *
+ * @param aNumber The number to be inserted in the text.
+ */
+ IMPORT_C void SetTextNumberL(TInt aNumber);
+
+ /**
+ * Sets the text plurality for the dialog.
+ *
+ * Indicates whether to use plural or singular text. These texts must
+ * have been specified in the resource file.
+ *
+ * @see @c SetTextNumberL().
+ * @param isPlural @c ETrue if plural text should be used,
+ * @c EFalse otherwise.
+ */
+ IMPORT_C void SetTextPluralityL(const TBool isPlural);
+
+ /**
+ * Sets the dialog text.
+ *
+ * This method can set a formatted text,
+ * e.g. "You have 1 new message". It can however set an
+ * unformatted text as well, e.g. "You have \%d messages". The plurality of
+ * the dialog must be previously specified - if not singular
+ * plurality is used unless there was no singular text specified in the
+ * resource file.
+ *
+ * @see @c SetTextNumberL(), @c SetTextPluralityL().
+ * @param aLabel The note text.
+ */
+ IMPORT_C void SetTextL(const TDesC& aLabel);
+
+ /**
+ * From @c CCoeControl.
+ *
+ * Handles key events.
+ *
+ * Any event which is not a key press is forwarded to
+ * @c CEikDialog::OfferKeyEventL.
+ '
+ * Short key press dismiss the note by calling @c StaticDeleteL.
+ *
+ * @see @c StaticDeleteL(), @c TKeyEvent, @c TEventCode.
+ * @param aKeyEvent Key event details.
+ * @param aType Type of event (key down, key press, key release, etc).
+ * @return Indicates whether or not the key event was used
+ * by this control. @c EKeyWasConsumed if the control takes action
+ * on the key event or @c EKeyWasNotConsumed otherwise.
+ */
+ IMPORT_C TKeyResponse OfferKeyEventL(const TKeyEvent& aKeyEvent,
+ TEventCode aType);
+
+ /**
+ * From @c CCoeControl.
+ *
+ * Handles a change to the control's resources of type @c aType
+ * which are shared across the environment, e.g. colors or fonts.
+ *
+ * @param aType Target resource type.
+ */
+ IMPORT_C void HandleResourceChange(TInt aType);
+
+ /**
+ * Do layout and draw the note dialog.
+ *
+ * Needed when changing control components (e.g. the text) dynamically.
+ * This is needed because the size of the dialog might change
+ * (e.g. because of bigger text displayed in more lines, etc.)
+ * Set methods call @c LayoutAndDraw() if there is a change that
+ * might affect the dialog layout (e.g. text becames bigger and hence
+ * requires an extra line).
+ *
+ * Derived classes that implement this kind of methods should call
+ * @c LayoutAndDraw().
+ */
+ IMPORT_C void LayoutAndDraw();
+
+ /**
+ * From @ CEikDialog.
+ *
+ * Executes a dialog.
+ *
+ * Plays a tone (if one was defined) and simulates user activity.
+ * Forwards call to @c CEikDialog::RunLD().
+ *
+ * @return The ID of the button used to dismiss the dialog.
+ */
+ IMPORT_C virtual TInt RunLD();
+
+
+ /**
+ * From @c CEikDialog.
+ *
+ * Exits a sleeping dialog without deleting it.
+ */
+ IMPORT_C void ExitSleepingDialog();
+
+protected:
+
+ /**
+ * From @c CEikDialog.
+ *
+ * Sets the size and the position for the layout.
+ *
+ * The dialog height and width are retrieved from the control
+ * (if it exists already).If it does not exist, then default values
+ * are used. The client rect is obtained from the application UI.
+ * @c AknLayoutUtils::LayoutControl is then executed using the client
+ * rect and the note width and height.
+ *
+ * @see @c AknLayoutUtils::LayoutControl().
+ * @param aSize Not used.
+ */
+ IMPORT_C void SetSizeAndPosition(const TSize& aSize);
+
+ /**
+ * From @c CEikDialog.
+ *
+ * Performs dynamic operations before the layout.
+ *
+ * Called by the Uikon framework before the dialog layout is executed, this
+ * method can be overrwritten to perform specific operations.
+ *
+ * The following operations are performed:- <UL> <LI> The control attributes
+ * are transferred to the control. The local control attributes are copied
+ * into the real control attributes. The local attributes are then deleted.
+ * </LI> <LI> If a timeout has been specified the timer is started. The
+ * callback is StaticDeleteL. </LI> <LI> </LI> </UL>
+ *
+ * @see @c CAknNoteAttributes, @c TTimer, @c SetEditableL().
+ */
+ IMPORT_C void PreLayoutDynInitL(void);
+
+ /**
+ * From @c CEikDialog.
+ *
+ * Performs dynamic operations after the layout.
+ *
+ * Called by the Uikon framework after the dialog layout is executed, this
+ * method can be overrwritten to perform specific operations.
+ *
+ * The following operations are performed:- <UL> <LI> @c StartAnimationL()
+ * is called. </LI> </UL>
+ *
+ * @see @c CAknNoteControl::StartAnimationL().
+ */
+ IMPORT_C void PostLayoutDynInitL();
+
+ /**
+ * Plays a tone.
+ *
+ * The tone must be previously specified. The sound ID is set
+ * depending on the tone type. The tone is played using
+ * @c CAknKeySoundSystem::playSound(). Derived classes must call this
+ * method if they override @c RunLD() and they wish to play a tone.
+ *
+ * @panic EAknPanicNullPointer
+ * @see @c TTone, @c CAknKeySoundSystem, @c CAknNoteDialog::RunLD().
+ */
+ IMPORT_C void PlayTone();
+
+ /**
+ * Indicates that there is user activity.
+ *
+ * Resets timers which are monitoring user inactivity. This will disable
+ * functionality that checks for user inactivity by listening to
+ * these timers.
+ *
+ * Derived classes must call this method if they override @c RunLD()
+ * and they wish to report user activity in order to dismiss applications
+ * such as the screen saver.
+ *
+ * @see @c User::ResetInactivityTime().
+ */
+ IMPORT_C void ReportUserActivity() const;
+
+ /**
+ * Deletes the note dialog.
+ *
+ * Called when the timer completes, this method deletes the dialog. A
+ * @c reinterpret_cast to @c CAknNoteDialog* is performed on aThis. If the
+ * dialog is not a sleeping note then it is deleted. If it is a sleeping
+ * dialog then the timer is stopped, @c OkToExitL() is called with
+ * @c KErrCancel and @c ExitSleepingDialog is executed.
+ *
+ * @see @c TTimer, @c OkToExitL(), @c ExitSleepingDialog().
+ * @param aThis Pointer to the dialog.
+ * @return Always returns @c EFalse.
+ */
+ IMPORT_C static TInt StaticDeleteL(TAny* aThis);
+
+ /**
+ * Gets the control attributes.
+ *
+ * If the control has already been created this method return the
+ * attributes stored inside the control. If not then the local
+ * attributes are returned. The local attributes are transferred to the
+ * control in @c PreLayoutDynInitL().
+ *
+ * Derived classes should use this method when trying to access the control
+ * attributes.
+ *
+ * @return Control attributes.
+ */
+ IMPORT_C CAknNoteAttributes* ControlAttributes();
+
+ /**
+ * Transfers the control attributes from the dialog to the control.
+ *
+ * Must be called by derived classes in @c PreLayoutDynInitL()
+ * if this method is not called then the set of API methods that were
+ * invoked before the control is created will not work.
+ */
+ IMPORT_C void TransferControlAttributes();
+
+ /**
+ * Gets the used sound system.
+ *
+ * Calls @c iEikonEnv->AppUi()->KeySounds() and returns the pointer
+ * returned by the called method. If there is no application UI
+ * return @c NULL.
+ *
+ * @see @c CAknKeySoundSystem, @c CAknAppUi.
+ * @return Pointer to the used @c CAknKeySoundSystem or @c NULL.
+ * @panic EAknPanicNullPointer
+ */
+ IMPORT_C CAknKeySoundSystem* SoundSystem() const;
+
+ /**
+ * Gets the Note control.
+ *
+ * Returns the first control on the active page, which is of type
+ * @c CAknNoteControl. If no control is found (usually because the
+ * control has not been created yet) then this method returns @c NULL.
+ *
+ * Derived classes must use this method to get access to the note
+ * control.
+ *
+ * @return Pointer to the note control or @c NULL.
+ */
+ IMPORT_C CAknNoteControl* NoteControl();
+
+private:
+
+ void DbgCheckSelfPtr(CEikDialog** aSelfPtr);
+
+protected:
+
+ /**
+ * Note timeout timer.
+ */
+ CPeriodic* iTimer;
+
+ /**
+ * Note timeout in microseconds.
+ */
+ TInt iTimeoutInMicroseconds;
+
+ /**
+ * Used for notes that are not modal.
+ * The calling application has no way of knowing
+ * when the note is deleted.
+ */
+ CEikDialog** iSelfPtr;
+
+ /**
+ * The tone to be played.
+ */
+ TTone iTone;
+
+ /**
+ * Note control attributes.
+ */
+ CAknNoteAttributes* iControlAttributes;
+
+private:
+
+ //TInt iSpare;
+ CAknNoteDialogExtension* iNoteExtension;
+
+public:
+
+ /**
+ * Set timeout, tone, resource ID and then initialize and launch
+ * the dialog.
+ *
+ * This method is deprecated and should not be used.
+ *
+ * @deprecated
+ * @param aTimeout Wanted timeout in microseconds.
+ * @param aTone Alarm tone.
+ * @param aResourceID The ID of the wanted resource.
+ * @return Zero, unless it is a waiting dialog. For a waiting dialog,
+ * the return value is the ID of the button that closed the dialog,
+ * or zero if it was the cancel button (@c EEikBidCancel).
+ */
+ IMPORT_C TInt ExecuteDlgLD(const TTimeout aTimeout,
+ const TTone aTone,
+ TInt aResourceID);
+
+ /**
+ * Set tone, resource ID and then initialize and launch
+ * the dialog.
+ *
+ * This method is deprecated and should not be used.
+ *
+ * @deprecated
+ * @param aTone Alarm tone.
+ * @param aResourceID The ID of the wanted resource.
+ * @return Zero, unless it is a waiting dialog. For a waiting dialog,
+ * the return value is the ID of the button that closed the dialog,
+ * or zero if it was the cancel button (@c EEikBidCancel).
+ */
+ IMPORT_C TInt ExecuteDlgLD(const TTone aTone,TInt aResourceID);
+
+ /**
+ * Set note control ID, resource ID and then initialize and launch
+ * the dialog.
+ *
+ * This method is deprecated and should not be used.
+ *
+ * @deprecated
+ * @param aResourceId The ID of the wanted resource.
+ * @param aNoteControlId Not used.
+ * @return Zero, unless it is a waiting dialog. For a waiting dialog,
+ * the return value is the ID of the button that closed the dialog,
+ * or zero if it was the cancel button (@c EEikBidCancel).
+ */
+ IMPORT_C TInt ExecuteDlgLD(TInt aResourceId, TInt aNoteControlId=0);
+
+ /**
+ * Set timeout and tone and run the dialog.
+ *
+ * This method is deprecated and should not be used.
+ *
+ * @deprecated
+ * @param aTimeout Wanted timeout in microseconds.
+ * @param aTone Wanted alarm tone.
+ * @return The ID of the button used to dismiss the dialog.
+ */
+ IMPORT_C TInt RunDlgLD(const TTimeout aTimeout,const TTone aTone);
+
+ /**
+ * Set tone and run the dialog.
+ *
+ * This method is deprecated and should not be used.
+ *
+ * @deprecated
+ * @param aTone Wanted alarm tone.
+ * @return The ID of the button used to dismiss the dialog.
+ */
+ IMPORT_C TInt RunDlgLD(const TTone aTone);
+
+ /**
+ * Run the dialog.
+ *
+ * This method is deprecated and should not be used.
+ *
+ * @deprecated
+ * @return The ID of the button used to dismiss the dialog.
+ */ IMPORT_C TInt RunDlgLD();
+
+ /**
+ * Set NoteControlID and run the dialog.
+ *
+ * This method is deprecated and should not be used.
+ *
+ * @deprecated
+ * @param aNoteControlId Not used.
+ * @return The ID of the button used to dismiss the dialog.
+ */
+ IMPORT_C TInt RunDlgLD(TInt aNoteControlId);
+
+ /**
+ * Sets a new label for the specified dialog.
+ *
+ * This method is deprecated. @c SetTextL() method should be used
+ * instead.
+ *
+ * @param aControlId Not used.
+ * @param aLabel The new label.
+ */
+ IMPORT_C void SetCurrentLabelL(TInt aControlId,const TDesC& aLabel);
+
+private:
+
+ IMPORT_C virtual void CEikDialog_Reserved_1();
+
+ IMPORT_C virtual void CEikDialog_Reserved_2();
+
+private: // new virtual function.
+
+ IMPORT_C virtual void CAknNoteDialog_Reserved();
+
+protected:
+
+ // This method id reserved for CEikAlert usage
+ /**
+ * Sets an indication that memory should not be allocated.
+ *
+ * This method is reserved for CEikAlert usage.
+ */
+ IMPORT_C void SetNoMemoryAllocation();
+
+
+private: // from eikdialog
+
+ IMPORT_C void SizeChanged();
+
+ void SetSkinBackGroundRect();
+
+private:
+
+ void CreateExtensionL();
+
+ static TInt CallbackStartAnimationL(TAny* aThis);
+
+public:
+
+ /**
+ * From @c CCoeControl.
+ *
+ * Processes the pointer event directed to the dialog.
+ *
+ * @param aPointerEvent The pointer event directed to the notedialog.
+ */
+ IMPORT_C virtual void HandlePointerEventL(
+ const TPointerEvent& aPointerEvent);
+
+private:
+
+ /**
+ * From @c CAknControl.
+ */
+ IMPORT_C void* ExtensionInterface( TUid aInterface );
+ };
+
+
+#endif // __AKNNOTEDIALOG__
+
+// End of file
\ No newline at end of file