--- a/src/hbwidgets/devicedialogs/hbdevicenotificationdialogsymbian.cpp Thu Sep 02 20:44:51 2010 +0300
+++ b/src/hbwidgets/devicedialogs/hbdevicenotificationdialogsymbian.cpp Fri Sep 17 08:32:10 2010 +0300
@@ -43,6 +43,12 @@
public MHbDeviceDialogObserver
{
public:
+ struct TIntProperty{
+ TInt iValue;
+ TBool iChanged;
+ };
+
+public:
CHbDeviceNotificationDialogSymbianPrivate();
virtual ~CHbDeviceNotificationDialogSymbianPrivate();
@@ -67,14 +73,15 @@
CHbSymbianVariantMap* iVariantMap;
CHbDeviceNotificationDialogSymbian* q;
- TBool iEnable;
- TInt iTimeout;
- TInt iShowLevel;
- CHbDeviceNotificationDialogSymbian::TextWrapping iWrap;
+ TIntProperty iEnable;
+ TIntProperty iTimeout;
+ TIntProperty iShowLevel;
+ TIntProperty iWrap;
};
CHbDeviceNotificationDialogSymbianPrivate::CHbDeviceNotificationDialogSymbianPrivate()
- {
+ {
+ iTimeout.iValue = 3000; // HbPopup::StandardTimeout
}
CHbDeviceNotificationDialogSymbianPrivate::~CHbDeviceNotificationDialogSymbianPrivate()
@@ -98,11 +105,17 @@
void CHbDeviceNotificationDialogSymbianPrivate::ShowL()
{
- AddVariantL(KKeyTouchActivation, &iEnable, CHbSymbianVariant::EBool);
- AddVariantL(KKeyTimeOut, &iTimeout, CHbSymbianVariant::EInt);
- AddVariantL(KKeyTitleTextWrapping, &iWrap, CHbSymbianVariant::EInt);
- if (iShowLevel) { // send only if non-default
- AddVariantL(KKeyShowLevel, &iShowLevel, CHbSymbianVariant::EInt);
+ if (iEnable.iChanged) {
+ AddVariantL(KKeyTouchActivation, &iEnable.iValue, CHbSymbianVariant::EBool);
+ }
+ if (iTimeout.iChanged) {
+ 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);
@@ -113,9 +126,15 @@
void CHbDeviceNotificationDialogSymbianPrivate::UpdateL()
{
- AddVariantL(KKeyTouchActivation, &iEnable, CHbSymbianVariant::EBool);
- AddVariantL(KKeyTimeOut, &iTimeout, CHbSymbianVariant::EInt);
- AddVariantL(KKeyTitleTextWrapping, &iWrap, CHbSymbianVariant::EInt);
+ if (iEnable.iChanged) {
+ AddVariantL(KKeyTouchActivation, &iEnable, CHbSymbianVariant::EBool);
+ }
+ 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
@@ -171,68 +190,79 @@
// 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.
- \a aDialog - Pointer to dialog instance which received closed event.
- \a aCompletionCode - Result of the dialog completion.
+ This callback is called when notification dialog has closed.
+ \a aDialog is a pointer to a dialog instance which received closed event.
+ \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
- HbDeviceNotificationDialog can not be used.
+ <b>This class is Symbian only. Not available on other platforms.</b>
+
+ CHbDeviceNotificationDialogSymbian is intended for use by servers that don't run Qt event loop
+ and cannot use HbDeviceNotificationDialog.
- CHbDeviceNotificationDialogSymbian provides similar interface and functionality as HbDeviceNotificationDialog.
- Main difference is that signals are replaced by an observer interface CHbDeviceNotificationDialogSymbianObserver.
+ See HbDeviceNotificationDialog documentation to find out more about device notification
+ dialogs.
+
+ CHbDeviceNotificationDialogSymbian provides similar interface and functionality as
+ HbDeviceNotificationDialog. Main difference is that signals are replaced by an observer
+ interface CHbDeviceNotificationDialogSymbianObserver.
- For the content CHbDeviceNotificationDialogSymbian provides two rows of text, an image or an animation and for the usage
- 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.
+ 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.
- Two timeout constants are provided for setting the dialog timeout: KHbShortNotificationDialogTimeout and
- KHbLongNotificationDialogTimeout. The first is equivalent to HbPopup::ConfirmationNoteTimeout and the latter
- is equivalent to HbPopup::StandardTimeout.
-
+ 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
@@ -241,22 +271,23 @@
\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
- HbDeviceNotificationDialog instance is destroyed when the call returns. Ownership and handling of the
- dialog is transferred to HbDeviceDialog framework. Also dialog can not be closed nor updated.
+ When using convenience methods, it is not possible to receive user interaction events,
+ because the HbDeviceNotificationDialog instance is destroyed when the call returns.
- Below is an example of receiving user interaction events from device notification dialog. With following example
- user is able to receive activated and close events. Note that dialog is cancelled, if it goes out of scope.
+ Below is an example of receiving user interaction events from device notification dialog.
+ With following example user is able to receive activated and close events.
+ 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
{
@@ -295,17 +326,8 @@
iDialog->ShowL();
}
\endcode
-
- CHbDeviceNotificationDialogSymbian supports.
- 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:
+ Following example sets an icon animation into a notification dialog.
\code
Create an animation definition file.
@@ -328,12 +350,27 @@
iDialog->SetIconNameL(KLogicalIconName);
iDialog->ShowL();
\endcode
- \sa HbIconAnimationManager::addDefinitionFile
- \note Animation definition files must be stored to a place where they
- can be accessed.
-
- \stable
- \hbwidgets
+
+ \sa HbDeviceNotificationDialog, MHbDeviceNotificationDialogObserver
+*/
+
+/*!
+ \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.
*/
/*!
@@ -360,8 +397,9 @@
/*!
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)
{
@@ -375,9 +413,10 @@
/*!
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 aTitle - title shown on dialog.
+
+ \param aIconName Path and name of icon to show on dialog.
+ \param aText Dialog text.
+ \param aTitle Title text.
*/
EXPORT_C void CHbDeviceNotificationDialogSymbian::NotificationL(const TDesC &aIconName, const TDesC& aText, const TDesC& aTitle)
{
@@ -391,12 +430,12 @@
}
/*!
- 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)
{
@@ -405,8 +444,7 @@
/*!
- Get name and path of the icon shown on dialog or animation's logical name.
- If not set, returns empty iconName.
+ Returns icon or animation name. Default is empty.
\sa SetIconNameL
*/
@@ -421,13 +459,18 @@
}
/*!
- Sets notification dialog's animation definition name. The dialogs get updated next when time ShowL() or UpdateL()
- is called.
+ Sets dialog animation definition file name.
- \param aAnimationDefinition Animation definition file name. Definition can be from Hb resources or themes.
- Or can be a file in a file system.
+ Supported icon animation formats are following:
+ - GIF (.gif)
+ - 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)
{
@@ -435,7 +478,7 @@
}
/*!
- Returns an animation definition set for a dialog. If not set, return string.
+ Returns dialog animation definition file name.
\sa SetAnimationDefinitionL()
*/
@@ -451,10 +494,11 @@
/*!
- Set and update text on dialog. Text is not set, if Show() or Update()
- is not called.
- \param aText - text shown on dialog.
- \sa ShowL(), UpdateL()
+ Sets dialog text.
+
+ \param aText Dialog text.
+
+ \sa Text(), ShowL(), UpdateL()
*/
EXPORT_C void CHbDeviceNotificationDialogSymbian::SetTextL(const TDesC& aText)
{
@@ -462,7 +506,7 @@
}
/*!
- Get text shown on dialog. If not set, returns empty string.
+ Returns dialog text.
\sa SetTextL()
*/
@@ -477,10 +521,11 @@
}
/*!
- Set and update title on dialog. Title is not set, if Show() or Update()
- is not called.
- \param aTitle - title shown on dialog.
- \sa ShowL(), UpdateL()
+ Sets title text.
+
+ \param aTitle Title text.
+
+ \sa Title(), ShowL(), UpdateL()
*/
EXPORT_C void CHbDeviceNotificationDialogSymbian::SetTitleL(const TDesC& aTitle)
{
@@ -488,7 +533,7 @@
}
/*!
- Get title shown on dialog. If not set, returns empty string.
+ Returns title text.
\sa SetTitleL()
*/
@@ -504,82 +549,91 @@
}
/*!
- Enable user interaction on dialog. Setting is not set, if Show() or Update()
- is not called.
- \param aEnable - When enabled, activation event is notified via observer interface.
+ Enables user interaction on dialog.
- Default value is false.
- \sa ShowL(), UpdateL(), MCHbDeviceNotificationDialogSymbianObserver.
+ \param aEnable True enables activation event notification via observer interface.
+
+ \sa IsTouchActivating(), 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()
- is not called.
- \param aTimeout - Set timeout for dialog.
+ Set dialog timeout.
- Default value is KHbLongNotificationDialogTimeout (3000 ms).
- \sa ShowL(), UpdateL()
+ \param aTimeout Dialog timeout in milliseconds.
+
+ \sa Timeout(), 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()
- is not called.
- \param aWrapping - Defines title text wrapping.
+ Sets title text wrapping. The title can wrap only if there is no text for the dialog.
+ The title can wrap to a maximum of two lines. SetTextL() also changes title text wrapping.
+
- Default value is CHbDeviceNotificationDialogSymbian::TextNoWrap.
- \sa ShowL(), UpdateL()
+ \param aWrapping Title text wrapping.
+
+ \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();
- \endcode
+ Shows a notification dialog and returns immediately without waiting for it to close.
+ 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()
{
@@ -587,12 +641,11 @@
}
/*!
- Update the dialog. Show must be called before update can be used.
- \code
- // example to update already showing dialog.
- iNotificationDialog->SetTitleL("Update title");
- iNotificationDialog->UpdateL();
- \endcode
+ Updates changed properties to a showing notification dialog via interprocess
+ communication. Has no effect if ShowL() has not been called or the dialog has
+ closed already.
+
+ \sa ShowL()
*/
EXPORT_C void CHbDeviceNotificationDialogSymbian::UpdateL()
@@ -601,8 +654,7 @@
}
/*!
- Close the dialog. Method has no effect if convenience methods
- are used to show device notification dialog.
+ Closes a device notification dialog.
*/
EXPORT_C void CHbDeviceNotificationDialogSymbian::Close()
{
@@ -625,7 +677,4 @@
d = new (ELeave) CHbDeviceNotificationDialogSymbianPrivate;
d->ConstructL(this);
d->iObserver = aObserver;
- EnableTouchActivation(EFalse);
- SetTimeout(KHbLongNotificationDialogTimeout);
- SetTitleTextWrapping(CHbDeviceNotificationDialogSymbian::TextWordWrap);
}