Current Symbian^3 public API header files (from PDK 3.0.h)
This is the epoc32/include tree with the "platform" subtrees removed, and
all but a selected few mbg and rsg files removed.
/*
* 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 <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