FCL/sf/mw/hb: comparison src/hbwidgets/devicedialogs/hbdevicenotificationdialogsymbian.cpp

equal deleted inserted replaced

-:e6ad4ef83b23
+:b7da29130b0e
 NONSHARABLE_CLASS(CHbDeviceNotificationDialogSymbianPrivate) : public CBase,
 public MHbDeviceDialogObserver
 {
 public:
+struct TIntProperty{
+TInt iValue;
+TBool iChanged;
+};
+public:
 CHbDeviceNotificationDialogSymbianPrivate();
 virtual ~CHbDeviceNotificationDialogSymbianPrivate();
 public:
 void ShowL();
 MHbDeviceNotificationDialogObserver* iObserver;
 CHbDeviceDialogSymbian *iDeviceDialog;
 CHbSymbianVariantMap* iVariantMap;
 CHbDeviceNotificationDialogSymbian* q;
-TBool iEnable;
+TIntProperty iEnable;
-TInt iTimeout;
+TIntProperty iTimeout;
-TInt iShowLevel;
+TIntProperty iShowLevel;
-CHbDeviceNotificationDialogSymbian::TextWrapping iWrap;
+TIntProperty iWrap;
 };
 CHbDeviceNotificationDialogSymbianPrivate::CHbDeviceNotificationDialogSymbianPrivate()
 {
+iTimeout.iValue = 3000; // HbPopup::StandardTimeout
 }
 CHbDeviceNotificationDialogSymbianPrivate::~CHbDeviceNotificationDialogSymbianPrivate()
 {
 if (!iObserver && q->Timeout() != 0) {
 iVariantMap = CHbSymbianVariantMap::NewL();
 }
 void CHbDeviceNotificationDialogSymbianPrivate::ShowL()
 {
-AddVariantL(KKeyTouchActivation, &iEnable, CHbSymbianVariant::EBool);
+if (iEnable.iChanged) {
-AddVariantL(KKeyTimeOut, &iTimeout, CHbSymbianVariant::EInt);
+AddVariantL(KKeyTouchActivation, &iEnable.iValue, CHbSymbianVariant::EBool);
-AddVariantL(KKeyTitleTextWrapping, &iWrap, CHbSymbianVariant::EInt);
+}
-if (iShowLevel) { // send only if non-default
+if (iTimeout.iChanged) {
-AddVariantL(KKeyShowLevel, &iShowLevel, CHbSymbianVariant::EInt);
+AddVariantL(KKeyTimeOut, &iTimeout.iValue, CHbSymbianVariant::EInt);
+}
+if (iWrap.iChanged) {
+AddVariantL(KKeyTitleTextWrapping, &iWrap.iValue, CHbSymbianVariant::EInt);
+}
+if (iShowLevel.iChanged) {
+AddVariantL(KKeyShowLevel, &iShowLevel.iValue, CHbSymbianVariant::EInt);
 }
 TInt error = iDeviceDialog->Show(KPluginIdentifier, *iVariantMap, this);
 if (error != KErrNone) {
 User::Leave(error); // error can be positive or negative
 }
 }
 void CHbDeviceNotificationDialogSymbianPrivate::UpdateL()
 {
-AddVariantL(KKeyTouchActivation, &iEnable, CHbSymbianVariant::EBool);
+if (iEnable.iChanged) {
-AddVariantL(KKeyTimeOut, &iTimeout, CHbSymbianVariant::EInt);
+AddVariantL(KKeyTouchActivation, &iEnable, CHbSymbianVariant::EBool);
-AddVariantL(KKeyTitleTextWrapping, &iWrap, CHbSymbianVariant::EInt);
+}
+if (iTimeout.iChanged) {
+AddVariantL(KKeyTimeOut, &iTimeout, CHbSymbianVariant::EInt);
+}
+if (iWrap.iChanged) {
+AddVariantL(KKeyTitleTextWrapping, &iWrap, CHbSymbianVariant::EInt);
+}
 TInt error = iDeviceDialog->Update(*iVariantMap);
 if (error != KErrNone) {
 User::Leave(error); // error can be positive or negative
 }
 }
 }
 // Set dialog show level
 void SetShowLevel(CHbDeviceNotificationDialogSymbianPrivate *aDialog, TInt aLevel)
 {
-aDialog->iShowLevel = aLevel;
+aDialog->iShowLevel.iValue = aLevel;
+aDialog->iShowLevel.iChanged = ETrue;
 }
 /*!
 \class MHbDeviceNotificationDialogObserver
 \brief MHbDeviceNotificationDialogObserver is an observer interface for observing CHbDeviceNotificationDialogSymbian.
 */
 /*!
 \fn void MHbDeviceNotificationDialogObserver::NotificationDialogActivated(const CHbDeviceNotificationDialogSymbian* aDialog) = 0;
 This callback is called when notification dialog is activated.
-\a aDialog - Pointer to dialog instance which received activation event.
+\a aDialog is a pointer to a dialog instance which received activation event.
-*/
+\sa CHbDeviceNotificationDialogSymbian::EnableTouchActivation()
+*/
 /*!
 \fn void MHbDeviceNotificationDialogObserver::NotificationDialogClosed(const CHbDeviceNotificationDialogSymbian* aDialog, TInt aCompletionCode) = 0;
-This callback is called when notification dialog is closed.
+This callback is called when notification dialog has closed.
-\a aDialog - Pointer to dialog instance which received closed event.
+\a aDialog is a pointer to a dialog instance which received closed event.
-\a aCompletionCode - Result of the dialog completion.
+\a aCompletionCode can be either Symbian error code or device dialog error code.
 */
 /*!
-\fn void MHbDeviceNotificationDialogObserver::NotificationDialogError(const CHbDeviceNotificationDialogSymbian* aDialog, TInt aError) = 0;
+\stable
+\hbwidgets
-This callback is called when an error has occurred.
-\a aDialog - Pointer to dialog instance which received closed event.
-\a aError - Error code.
-*/
-/*!
 \class CHbDeviceNotificationDialogSymbian
 \brief CHbDeviceNotificationDialogSymbian is a Symbian implementation of HbDeviceNotificationDialog.
-It is a client interface for s60 native application to show a non-modal dialog on top of applications when
+<b>This class is Symbian only. Not available on other platforms.</b>
-HbDeviceNotificationDialog can not be used.
+CHbDeviceNotificationDialogSymbian is intended for use by servers that don't run Qt event loop
-CHbDeviceNotificationDialogSymbian provides similar interface and functionality as HbDeviceNotificationDialog.
+and cannot use HbDeviceNotificationDialog.
-Main difference is that signals are replaced by an observer interface CHbDeviceNotificationDialogSymbianObserver.
+See HbDeviceNotificationDialog documentation to find out more about device notification
-For the content CHbDeviceNotificationDialogSymbian provides two rows of text, an image or an animation and for the usage
+dialogs.
-same rules as for the HbDeviceNotificationDialog apply. Dialog is shown when show() is called. It is recommended that
-the dialog data is initialized before calling ShowL() or UpdateL() methods, because those methods use interprocess communication.
+CHbDeviceNotificationDialogSymbian provides similar interface and functionality as
+HbDeviceNotificationDialog. Main difference is that signals are replaced by an observer
-Two timeout constants are provided for setting the dialog timeout: KHbShortNotificationDialogTimeout and
+interface CHbDeviceNotificationDialogSymbianObserver.
-KHbLongNotificationDialogTimeout. The first is equivalent to HbPopup::ConfirmationNoteTimeout and the latter
-is equivalent to HbPopup::StandardTimeout.
+An asynchronous ShowL() method launches a dialog. Device dialog framework decides when the
+dialog is actually shown. There may be a delay untill dialog appears on display. Close()
+closes a dialog.
+After dialog has been lauched, properties may be updated by setters and calling UpdateL().
+It is recommended that dialog properties are set before calling ShowL() as updating them after
+causes interprocess communication.
+If there is no need to update or receive activation from a launched dialog,
+CHbDeviceNotificationDialogSymbian object can be deleted after ShowL() returns. Device
+dialog framework takes care of displaying the dialog.
+For maintaining consistent look and feel, two timeout constants are provided for setting
+dialog timeout: KHbShortNotificationDialogTimeout and KHbLongNotificationDialogTimeout.
+The first one is equivalent to HbPopup::ConfirmationNoteTimeout and the latter
+to HbPopup::StandardTimeout.
 \code
 Following code snippet creates a device notification dialog containing title, text and icon.
 _LIT(KDialogText, "Dialog text");
 _LIT(KDialogTitle, "Dialog title");
-_LIT(KDialogIcon, "note_info.svg");
+_LIT(KDialogIcon, "qtg_large_info");
 CHbDeviceNotificationDialogSymbian* dialog = CHbDeviceNotificationDialogSymbian::NewL();
 CleanupStack::PushL(dialog);
 dialog->SetTextL(KDialogText);
 dialog->SetTitleL(KDialogTitle);
 dialog->SetIconNameL(KDialogIcon);
-dialog->Show();
+dialog->ShowL();
 CleanupStack::PopAndDestroy(dialog);
 \endcode
 or equivalent dialog can be created using one of the provided convenience methods:
 \code
 _LIT(KDialogText, "Dialog text");
 _LIT(KDialogTitle, "Dialog title");
-_LIT(KDialogIcon, "note_info.svg");
+_LIT(KDialogIcon, "qtg_large_info");
 CHbDeviceNotificationDialogSymbian::Notification(KDialogIcon, KDialogText, KDialogTitle);
 \endcode
-When using convenience methods, it is not possible to receive user interaction events, because the
+When using convenience methods, it is not possible to receive user interaction events,
-HbDeviceNotificationDialog instance is destroyed when the call returns. Ownership and handling of the
+because the HbDeviceNotificationDialog instance is destroyed when the call returns.
-dialog is transferred to HbDeviceDialog framework. Also dialog can not be closed nor updated.
+Below is an example of receiving user interaction events from device notification dialog.
-Below is an example of receiving user interaction events from device notification dialog. With following example
+With following example user is able to receive activated and close events.
-user is able to receive activated and close events. Note that dialog is cancelled, if it goes out of scope.
+Note that in this case the dialog is closed by device dialog framework if
+CHbDeviceNotificationDialogSymbian object is deleted.
 \code
 _LIT(KDialogText, "Dialog text");
 _LIT(KDialogTitle, "Dialog title");
-_LIT(KDialogIcon, "note_info.svg");
+_LIT(KDialogIcon, "qtg_large_info");
 class DialogObserver : public MHbDeviceNotificationDialogObserver
 {
 public:
 DialogObserver() {}
 iDialog->SetTitleL(KDialogTitle);
 iDialog->SetIconNameL(KDialogIcon);
 iDialog->ShowL();
 }
 \endcode
-CHbDeviceNotificationDialogSymbian supports.
+Following example sets an icon animation into a notification dialog.
-Supported formats are the following.
-- GIF (.gif)
-- MNG (.mng)
-- Frame animations
-There is a built-in support for GIF and MNG animations.
-Frame animations can be created by following way:
 \code
 Create an animation definition file.
 <animations>
 iDialog->SetAnimationDefinitionL(KAnimationDefinitionXML);
 iDialog->SetIconNameL(KLogicalIconName);
 iDialog->ShowL();
 \endcode
-\sa HbIconAnimationManager::addDefinitionFile
-\note Animation definition files must be stored to a place where they
+\sa HbDeviceNotificationDialog, MHbDeviceNotificationDialogObserver
-can be accessed.
+*/
-\stable
+/*!
-\hbwidgets
+\enum CHbDeviceNotificationDialogSymbian::TextWrapping
+Title text wrapping.
+\sa Hb::TextWrapping
+*/
+/*!
+\var CHbDeviceNotificationDialogSymbian::TextWrapping CHbDeviceNotificationDialogSymbian::TextNoWrap
+No wrapping.
+*/
+/*!
+\var CHbDeviceNotificationDialogSymbian::TextWrapping CHbDeviceNotificationDialogSymbian::TextWordWrap
+Word wrapping.
+*/
+/*!
+\var CHbDeviceNotificationDialogSymbian::TextWrapping CHbDeviceNotificationDialogSymbian::TextWrapAnywhere
+Wrap anywhere.
 */
 /*!
 Symbian two phase constructor. Returns a pointer to CHbDeviceNotificationDialogSymbian instance.
 \a aObserver Pointer to the observer.
 delete d;
 }
 /*!
 Convenience method for showing notification dialog with icon and title.
-\param aIconName - path and name of the icon shown on dialog.
-\param aTitle - title shown on dialog.
+\param aIconName Path and name of the icon to show on dialog.
+\param aTitle Title text.
 */
 EXPORT_C void CHbDeviceNotificationDialogSymbian::NotificationL(const TDesC& aIconName, const TDesC& aTitle)
 {
 CHbDeviceNotificationDialogSymbian* self = CHbDeviceNotificationDialogSymbian::NewL();
 CleanupStack::PushL(self);
 CleanupStack::PopAndDestroy(self);
 }
 /*!
 Convenience method for showing notification dialog with icon, text and title.
-\param aIconName - path and name of the icon shown on dialog.
-\param aText - text shown on dialog.
+\param aIconName Path and name of icon to show on dialog.
-\param aTitle - title shown on dialog.
+\param aText Dialog text.
+\param aTitle Title text.
 */
 EXPORT_C void CHbDeviceNotificationDialogSymbian::NotificationL(const TDesC &aIconName, const TDesC& aText, const TDesC& aTitle)
 {
 CHbDeviceNotificationDialogSymbian* self = CHbDeviceNotificationDialogSymbian::NewL();
 CleanupStack::PushL(self);
 self->ShowL();
 CleanupStack::PopAndDestroy(self);
 }
 /*!
-Sets message box icon name or animation logical name. The dialog gets updated when method is called.
+Sets dialog icon name or animation logical name.
 \param aIconName Icon name. Icon can be from Hb resources or themes. Or can be a file in
 a file system.
-\sa IconName()
+\sa IconName(), ShowL(), UpdateL()
 */
 EXPORT_C void CHbDeviceNotificationDialogSymbian::SetIconNameL(const TDesC& aIconName)
 {
 d->AddVariantL(KKeyIconName, &aIconName, CHbSymbianVariant::EDes);
 }
 /*!
-Get name and path of the icon shown on dialog or animation's logical name.
+Returns icon or animation name. Default is empty.
-If not set, returns empty iconName.
 \sa SetIconNameL
 */
 EXPORT_C const TPtrC CHbDeviceNotificationDialogSymbian::IconName() const
 {
 }
 return TPtrC(KNullDesC());
 }
 /*!
-Sets notification dialog's animation definition name.  The dialogs get updated next when time ShowL() or UpdateL()
+Sets dialog animation definition file name.
-is called.
+Supported icon animation formats are following:
-\param aAnimationDefinition Animation definition file name. Definition can be from Hb resources or themes.
+- GIF (.gif)
-Or can be a file in a file system.
+- MNG (.mng)
+- Frame animations
-\sa AnimationDefinition()
+\param aAnimationDefinition Animation definition file name. Definition can be from Hb resources or themes.
+Or can be a file in a file system. The definition must be stored to a place where it can be accessed by
+device dialog service.
+\sa AnimationDefinition() SetIconNameL() HbIconAnimationManager::addDefinitionFile(), ShowL(), UpdateL()
 */
 EXPORT_C void CHbDeviceNotificationDialogSymbian::SetAnimationDefinitionL(const TDesC& aAnimationDefinition)
 {
 d->AddVariantL(KKeyAnimationDefinition, &aAnimationDefinition, CHbSymbianVariant::EDes);
 }
 /*!
-Returns an animation definition set for a dialog. If not set, return string.
+Returns dialog animation definition file name.
 \sa SetAnimationDefinitionL()
 */
 EXPORT_C TPtrC CHbDeviceNotificationDialogSymbian::AnimationDefinition() const
 {
 return TPtrC(KNullDesC());
 }
 /*!
-Set and update text on dialog. Text is not set, if Show() or Update()
+Sets dialog text.
-is not called.
-\param aText - text shown on dialog.
+\param aText Dialog text.
-\sa ShowL(), UpdateL()
+\sa Text(), ShowL(), UpdateL()
 */
 EXPORT_C void CHbDeviceNotificationDialogSymbian::SetTextL(const TDesC& aText)
 {
 d->AddVariantL(KKeyText, &aText, CHbSymbianVariant::EDes);
 }
 /*!
-Get text shown on dialog. If not set, returns empty string.
+Returns dialog text.
 \sa SetTextL()
 */
 EXPORT_C const TPtrC CHbDeviceNotificationDialogSymbian::Text() const
 {
 }
 return TPtrC(KNullDesC());
 }
 /*!
-Set and update title on dialog. Title is not set, if Show() or Update()
+Sets title text.
-is not called.
-\param aTitle - title shown on dialog.
+\param aTitle Title text.
-\sa ShowL(), UpdateL()
+\sa Title(), ShowL(), UpdateL()
 */
 EXPORT_C void CHbDeviceNotificationDialogSymbian::SetTitleL(const TDesC& aTitle)
 {
 d->AddVariantL(KKeyTitle, &aTitle, CHbSymbianVariant::EDes);
 }
 /*!
-Get title shown on dialog. If not set, returns empty string.
+Returns title text.
 \sa SetTitleL()
 */
 EXPORT_C const TPtrC CHbDeviceNotificationDialogSymbian::Title() const
 {
 }
 return TPtrC(KNullDesC());
 }
 /*!
-Enable user interaction on dialog. Setting is not set, if Show() or Update()
+Enables user interaction on dialog.
-is not called.
-\param aEnable - When enabled, activation event is notified via observer interface.
+\param aEnable True enables activation event notification via observer interface.
-Default value is false.
+\sa IsTouchActivating(), ShowL(), UpdateL(), MCHbDeviceNotificationDialogSymbianObserver
-\sa ShowL(), UpdateL(), MCHbDeviceNotificationDialogSymbianObserver.
 */
 EXPORT_C void CHbDeviceNotificationDialogSymbian::EnableTouchActivation(TBool aEnable)
 {
-d->iEnable = aEnable;
+d->iEnable.iValue = aEnable;
-}
+d->iEnable.iChanged = ETrue;
+}
-/*!
-Get touch activation setting.
+/*!
+Returns touch activation setting.  Default value is false.
 \sa EnableTouchActivation()
 */
 EXPORT_C TBool CHbDeviceNotificationDialogSymbian::IsTouchActivating() const
 {
-return d->iEnable;
+return d->iEnable.iValue;
 }
 /*!
-Set dialog timeout. Timeout is not set, if Show() or Update()
+Set dialog timeout.
-is not called.
-\param aTimeout - Set timeout for dialog.
+\param aTimeout Dialog timeout in milliseconds.
-Default value is KHbLongNotificationDialogTimeout (3000 ms).
+\sa Timeout(), ShowL(), UpdateL()
-\sa ShowL(), UpdateL()
 */
 EXPORT_C void CHbDeviceNotificationDialogSymbian::SetTimeout(TInt aTimeout)
 {
-d->iTimeout = aTimeout;
+d->iTimeout.iValue = aTimeout;
-}
+d->iTimeout.iChanged = ETrue;
+}
-/*!
-Get timeout setting.
+/*!
+Returns timeout. Default value is KHbLongNotificationDialogTimeout (3000 ms).
 \sa SetTimeout()
 */
 EXPORT_C TInt CHbDeviceNotificationDialogSymbian::Timeout() const
 {
-return d->iTimeout;
+return d->iTimeout.iValue;
 }
 /*!
-Set dialog title text wrapping. Text wrapping is not set, if Show() or Update()
+Sets title text wrapping. The title can wrap only if there is no text for the dialog.
-is not called.
+The title can wrap to a maximum of two lines. SetTextL() also changes title text wrapping.
-\param aWrapping - Defines title text wrapping.
-Default value is CHbDeviceNotificationDialogSymbian::TextNoWrap.
+\param aWrapping Title text wrapping.
-\sa ShowL(), UpdateL()
+\sa TitleTextWrapping(), SetTextL(), ShowL(), UpdateL()
 */
 EXPORT_C void CHbDeviceNotificationDialogSymbian::SetTitleTextWrapping(
 TextWrapping aWrapping)
 {
-d->iWrap = aWrapping;
+d->iWrap.iValue = aWrapping;
-}
+d->iWrap.iChanged = ETrue;
+}
-/*!
-Get title text wrapping setting.
+/*!
+Returns title text wrapping.
+The title can wrap only if dialog text is empty. The title can wrap to a maximum of two lines.
+The default is CHbDeviceNotificationDialogSymbian::TextWordWrap.
 \sa SetTitleTextWrapping()
 */
 EXPORT_C CHbDeviceNotificationDialogSymbian::TextWrapping CHbDeviceNotificationDialogSymbian::TitleTextWrapping() const
 {
-return d->iWrap;
+if (d->iWrap.iChanged) {
-}
+return static_cast<TextWrapping>(d->iWrap.iValue);
+} else {
-/*!
+return Text().Length() == 0 ? TextWordWrap : TextNoWrap;
-Show the dialog.
+}
-\code
+}
-// example to show dialog.
-iNotificationDialog->SetTitleL("Dialog title text");
+/*!
-iNotificationDialog->ShowL();
+Shows a notification dialog and returns immediately without waiting for it to close.
-\endcode
+Closing of the dialog and tapping of dialog is indicated by MHbDeviceNotificationDialogObserver
+callback interface. Dialog can be updated while showing by property setters and then calling
+UpdateL().
+\sa UpdateL(), Close(), MHbDeviceNotificationDialogObserver
 */
 EXPORT_C void CHbDeviceNotificationDialogSymbian::ShowL()
 {
 d->ShowL();
 }
 /*!
-Update the dialog. Show must be called before update can be used.
+Updates changed properties to a showing notification dialog via interprocess
-\code
+communication. Has no effect if ShowL() has not been called or the dialog has
-// example to update already showing dialog.
+closed already.
-iNotificationDialog->SetTitleL("Update title");
-iNotificationDialog->UpdateL();
+\sa ShowL()
-\endcode
 */
 EXPORT_C void CHbDeviceNotificationDialogSymbian::UpdateL()
 {
 d->UpdateL();
 }
 /*!
-Close the dialog. Method has no effect if convenience methods
+Closes a device notification dialog.
-are used to show device notification dialog.
 */
 EXPORT_C void CHbDeviceNotificationDialogSymbian::Close()
 {
 d->Close();
 }
 MHbDeviceNotificationDialogObserver* aObserver)
 {
 d = new (ELeave) CHbDeviceNotificationDialogSymbianPrivate;
 d->ConstructL(this);
 d->iObserver = aObserver;
-EnableTouchActivation(EFalse);
+}
-SetTimeout(KHbLongNotificationDialogTimeout);
-SetTitleTextWrapping(CHbDeviceNotificationDialogSymbian::TextWordWrap);
-}

changeset 28	b7da29130b0e
parent 23	e6ad4ef83b23
child 30	80e4d18b72f5