diff -r 000000000000 -r 2f259fa3e83a classicui_pub/notes_api/inc/AknNoteDialog.h --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/classicui_pub/notes_api/inc/AknNoteDialog.h Tue Feb 02 01:00:49 2010 +0200 @@ -0,0 +1,658 @@ +/* +* 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 "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: +* Provides the CAknDialog-derived interface to Avkon Notes. +* +*/ + + +#ifndef __AKNNOTEDIALOG__ +#define __AKNNOTEDIALOG__ + +#include +#include "avkon.hrh" +class CEikImage; +class CAknKeySoundSystem; +class CAknNoteControl; +class CAknNoteAttributes; +class CAknNoteDialogExtension; + + +/** + * The note dialog. + * + * Displays a note to the user for: + * + * @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:- + * + * @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:- + * + * @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