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

equal deleted inserted replaced

-:923ff622b8b9
+:4633027730f5
 if (sendProperty) {
 CHbSymbianVariant* parameter;
 if (i == EAcceptText || i == ERejectText) {
 HBufC *actionData = CreateActionDataLC(property.IsNullAction(), property.StringValue());
 parameter = CHbSymbianVariant::NewL(actionData, CHbSymbianVariant::EDes);
-CleanupStack::PopAndDestroy(); // actionData
+CleanupStack::PopAndDestroy(actionData);
 } else if (property.Type() == TMessageBoxProperty::EIntProperty) {
 TInt value = property.IntValue();
 parameter = CHbSymbianVariant::NewL(&value, CHbSymbianVariant::EInt);
 } else {
 TPtrC value = property.StringValue();
 parameter = CHbSymbianVariant::NewL(&value, CHbSymbianVariant::EDes);
 }
 CleanupStack::PushL(parameter);
 User::LeaveIfError(parameters->Add(
 PropertyName(static_cast<TPropertyId>(i)), parameter));
-CleanupStack::Pop(); // parameter
+CleanupStack::Pop(parameter);
 property.SetModified(false);
 }
 }
 _LIT(KDeviceDialogType, "com.nokia.hb.devicemessagebox/1.0");
 error = mDeviceDialog->Update(*parameters);
 if (error != KErrNone) {
 User::Leave(error); // error can be positive or negative
 }
 }
-CleanupStack::PopAndDestroy(); // parameters
+CleanupStack::PopAndDestroy(parameters);
 }
 // Close message box
 void CHbDeviceMessageBoxPrivate::Close()
 {
 accept and reject.
 It provides a similar interface as HbDeviceMessageBox. The main
 differences are:
 - Signals are replaced by an observer interface
-- HbAction/QAction is replaced by button information.
+- HbAction/QAction is replaced by button text.
 - Function parameters whose type is a Qt or Hb enumeration are replaced by an integer.
 As suitable default values are set at construction, it is assumed that application rarely
 needs to use these.
 Device message box is a modal dialog. It is shown on top of applications by device dialog
 server. CHbDeviceMessageBoxSymbian is a client of the server.
-Three predefined message boxes are provided or a custom one can be constructed using the API.
+Four types of message boxes are predefined. The type determines a set of default properties that
-Predefined message boxes are:
+are set on construction. Below is a table listing types and their default properties.
-- Information
-- Question
+<table border="1">
-- Warning
+<caption><b>HbDeviceMessageBox types and default properties</b></caption>
+<tr><th>Type</th><th>Icon</th><th>Buttons</th><th>Timeout</th><th>Dismiss policy</th><th>Sound</th></tr>
+<tr><td>ENone</td><td>No icon</td><td>"Ok" button</td><td>Standard timeout</td><td>Tap anywhere</td><td>No sound</td></tr>
+<tr><td>EInformation</td><td>Info icon</td><td>"Ok" button</td><td>Standard timeout</td><td>Tap anywhere</td><td>Info sound</td></tr>
+<tr><td>EWarning</td><td>Warning icon</td><td>"Ok" button</td><td>Standard timeout</td><td>Tap anywhere</td><td>Warn sound</td></tr>
+<tr><td>EQuestion</td><td>Question icon</td><td>"Yes" and "No" buttons</td><td>No timeout</td><td>Button press</td><td>Question sound</td></tr>
+</table>
 ShowL() displays a message box asynchronously. The function returns immediately. The launched
 dialog can be updated by setters and then calling UpdateL(). Closing can be observed by a
 callback. Because each UpdateL() after the ShowL() requires interprocess communication,
 it's advisable to fully construct the device message box before displaying it.
 Static convenience functions are provided for ease of use. Message boxes created by these
 static functions contain a default set of properties depending on the message box type and their
 contents cannot be updated while the message box executes.
-Supported animation formats are following:
+Supported icon animation formats are following:
 - GIF (.gif)
 - MNG (.mng)
 - Frame animations
 Sample code:
 @hbwidgets
 */
 /*!
 \enum CHbDeviceMessageBoxSymbian::TType
-Predefined device message boxes.
+Message box type. Determines a set of default properties for the message box.
 */
 /*!
 \var CHbDeviceMessageBoxSymbian::TType CHbDeviceMessageBoxSymbian::ENone
-Message box with no icon and audio defined by default.
+Message box with no icon and audio defined.
 */
 /*!
 \var CHbDeviceMessageBoxSymbian::TType CHbDeviceMessageBoxSymbian::EInformation
 Information message box.
 */
 }
 /*!
 Factory function. Returns pointer to a device message box.
-\param aType Selects a template for the message box. Information, question or warning.
+\param aType Selects a template for the message box. None, information, question or warning.
 \param aObserver Observer for message box close event
 */
 EXPORT_C CHbDeviceMessageBoxSymbian* CHbDeviceMessageBoxSymbian::NewL(TType aType,
 MHbDeviceMessageBoxObserver *aObserver)
 {
 CHbDeviceMessageBoxPrivate *mboxPrivate = new (ELeave) CHbDeviceMessageBoxPrivate;
 mboxPrivate->q = messageBox;
 CleanupStack::PushL(mboxPrivate);
 mboxPrivate->ConstructL(aType, aObserver);
 messageBox->d = mboxPrivate;
-CleanupStack::Pop(2); // messageBox, mboxPrivate
+CleanupStack::Pop(2, messageBox); // mboxPrivate, messageBox
 messageBox->SetObserver(aObserver);
 return messageBox;
 }
 /*!
 Static convenience function to create and show a question device message box. Waits for
 the message box to close and returns button selected. If message box was closed for other
-reason than button press, returns EInvalidButton.
+reason than button press, returns CHbDeviceMessageBoxSymbian::EInvalidButton.
 <b> Beware that Symbian event processing is running while the function executes. For example
 application may have exited when the function returns.</b>
 \param aText Message box text.
 }
 if (aRejectButtonText.Length()) {
 messageBox->SetButtonTextL(ERejectButton, aRejectButtonText);
 }
 TButtonId buttonId = messageBox->ExecL();
-CleanupStack::PopAndDestroy(); // messageBox
+CleanupStack::PopAndDestroy(messageBox);
 return buttonId;
 }
 /*!
 Static convenience function to create and show a question device message box. Waits for
 the message box to close and returns button selected. If message box was closed for other
-reason than button press, returns EInvalidButton.
+reason than button press, returns CHbDeviceMessageBoxSymbian::EInvalidButton.
 <b> Beware that Symbian event processing is running while the function executes. For example
 application may have exited when the function returns.</b>
 \param aText Message box text.
 if (!aStandardButtons) {
 aStandardButtons = 0x00002000|0x00010000; // Yes|No
 }
 messageBox->SetStandardButtons(aStandardButtons);
 TButtonId buttonId = messageBox->ExecL();
-CleanupStack::PopAndDestroy(); // messageBox
+CleanupStack::PopAndDestroy(messageBox);
 return buttonId;
 }
 /*!
-Static convenience function to create and show an information device message box.
+Static convenience function to create and show an information device message box. Returns
+immediately (doesn't wait for the box to close).
 \param aText Message box text.
 */
 EXPORT_C void CHbDeviceMessageBoxSymbian::InformationL(const TDesC& aText)
 {
 CHbDeviceMessageBoxSymbian* messageBox = NewL(EInformation);
 CleanupStack::PushL(messageBox);
 messageBox->SetTextL(aText);
 messageBox->ShowL();
-CleanupStack::PopAndDestroy(); // messageBox
+CleanupStack::PopAndDestroy(messageBox);
 }
 /*!
-Static convenience function to create and show a warning device message box.
+Static convenience function to create and show a warning device message box. Returns
+immediately (doesn't wait for the box to close).
 \param aText Message box text.
 */
 EXPORT_C void CHbDeviceMessageBoxSymbian::WarningL(const TDesC& aText)
 {
 CHbDeviceMessageBoxSymbian* messageBox = NewL(EWarning);
 CleanupStack::PushL(messageBox);
 messageBox->SetTextL(aText);
 messageBox->ShowL();
-CleanupStack::PopAndDestroy(); // messageBox
+CleanupStack::PopAndDestroy(messageBox);
 }
 /*!
 Shows a device message box asyncronously. Function launches the message box and returns immediately.
 Closing of the message box can be observer with MHbDeviceMessageBoxObserver.
 {
 d->SendToServerL(false);
 }
 /*!
-Closes a device message box.
+Closes a device message box. Closing of the message box can be observer with
+MHbDeviceMessageBoxObserver.
-\sa ShowL()
+\sa ShowL(),  SetObserver()
 */
 EXPORT_C void CHbDeviceMessageBoxSymbian::Close()
 {
 d->Close();
 }
 /*!
 Shows a device message box synchronously. Function launches the message box and waits for it
 to close. Returns a button that was selected. If message box was closed for other reason
-than button press, returns EInvalidButton.
+than button press, returns CHbDeviceMessageBoxSymbian::EInvalidButton.
 <b> Beware that Symbian event processing is running while the function executes. For example
 application may have exited when the function returns.</b>
 \sa ShowL()
 return buttonId;
 }
 /*!
 Sets message box type. All message box properties are reset to a default values for the type.
-A ShowL() must be called to launch a message box after SetTypeL() has been called.
+Type of a showing message box cannot be changed on the fly. A ShowL() must be called to launch
+a new message box after SetTypeL() has been called.
 \param aType Message box type.
-\sa Type()
+\sa Type(), ShowL()
 */
 EXPORT_C void CHbDeviceMessageBoxSymbian::SetTypeL(TType aType)
 {
 d->InitProperties(aType);
 d->mShowCalled = false;
 return static_cast<TType>(
 d->mProperties[CHbDeviceMessageBoxPrivate::EType].IntValue());
 }
 /*!
-Sets message box text. The message box gets updated next time ShowL() or UpdateL()
+Sets message box text.
-is called.
 \param aText Message box text.
-\sa Text()
+\sa Text(), ShowL(), UpdateL()
 */
 EXPORT_C void CHbDeviceMessageBoxSymbian::SetTextL(const TDesC& aText)
 {
 d->SetPropertyValueL(CHbDeviceMessageBoxPrivate::EText, aText);
 }
 {
 return d->mProperties[CHbDeviceMessageBoxPrivate::EText].StringValue();
 }
 /*!
-Sets message box icon name or animation logical name. The message box gets updated next time ShowL() or UpdateL()
+Sets message box icon name or animation logical name.
-is called.
 \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 CHbDeviceMessageBoxSymbian::SetIconNameL(const TDesC& aIconName)
 {
 d->SetPropertyValueL(CHbDeviceMessageBoxPrivate::EIconName, aIconName);
 }
 {
 return d->mProperties[CHbDeviceMessageBoxPrivate::EIconName].StringValue();
 }
 /*!
-Sets message box animation definition name.  The message box gets updated next time ShowL() or UpdateL()
+Sets message box animation definition name.
-is called.
+Supported icon animation formats are following:
-Supported animation formats are following:
 - GIF (.gif)
 - MNG (.mng)
 - Frame animations
 \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()
+\sa AnimationDefinition() SetIconNameL() HbIconAnimationManager::addDefinitionFile(), ShowL(), UpdateL()
 */
 EXPORT_C void CHbDeviceMessageBoxSymbian::SetAnimationDefinitionL(const TDesC& aAnimationDefinition)
 {
 	d->SetPropertyValueL(CHbDeviceMessageBoxPrivate::EAnimationDefinition, aAnimationDefinition);
 }
 {
 	return d->mProperties[CHbDeviceMessageBoxPrivate::EAnimationDefinition].StringValue();
 }
 /*!
-Sets message box icon visibility. The message box gets updated next time ShowL() or UpdateL()
+Sets message box icon visibility.
-is called.
 \param aVisible Icon visibility.
-\sa IconVisible()
+\sa IconVisible(), ShowL(), UpdateL()
 */
 EXPORT_C void CHbDeviceMessageBoxSymbian::SetIconVisible(TBool aVisible)
 {
 d->SetPropertyValue(CHbDeviceMessageBoxPrivate::EIconVisible, aVisible);
 }
 /*!
-Returns message box icon visibility.
+Returns message box icon visibility. Default value is true for message box
+types other than ENone.
 \sa SetIconVisible()
 */
 EXPORT_C TBool CHbDeviceMessageBoxSymbian::IconVisible() const
 {
 return d->mProperties[CHbDeviceMessageBoxPrivate::EIconVisible].IntValue();
 }
 /*!
-Sets message box timeout. The message box gets updated next time ShowL() or UpdateL()
+Sets message box timeout.
-is called.
 \param aTimeout Timeout in milliseconds. Zero denotes no timeout.
-\sa Timeout()
+\sa Timeout(), ShowL(), UpdateL()
 */
 EXPORT_C void CHbDeviceMessageBoxSymbian::SetTimeout(TInt aTimeout)
 {
 d->SetPropertyValue(CHbDeviceMessageBoxPrivate::ETimeout, aTimeout);
 }
 /*!
-Returns message box timeout value in milliseconds.
+Returns message box timeout value in milliseconds. Default value depends on message box type.
+Question message box has a default of HbPopup::NoTimeout. All other boxes, the default is
+HbPopup::StandardTimeout.
 \sa SetTimeout()
 */
 EXPORT_C TInt CHbDeviceMessageBoxSymbian::Timeout() const
 {
 return d->mProperties[CHbDeviceMessageBoxPrivate::ETimeout].IntValue();
 }
 /*!
-Sets message box dismiss policy. The message box gets updated next time ShowL() or UpdateL()
+Sets message box dismiss policy.
-is called.
 \param aHbPopupDismissPolicy Dismiss policy. Values are HbPopup::DismissPolicy flags.
-\sa HbPopup::DismissPolicy, DismissPolicy()
+\sa HbPopup::DismissPolicy, DismissPolicy(), ShowL(), UpdateL()
 */
 EXPORT_C void CHbDeviceMessageBoxSymbian::SetDismissPolicy(TInt aHbPopupDismissPolicy)
 {
 d->SetPropertyValue(CHbDeviceMessageBoxPrivate::EDismissPolicy,
 aHbPopupDismissPolicy);
 }
 /*!
 Returns message box dismiss policy. Returned values are HbPopup::DismissPolicy flags.
+Default depends on message box type. Question box has default HbPopup::NoDismiss and
+all other boxes HbPopup::TapAnywhere.
 \sa HbPopup::DismissPolicy, SetDismissPolicy()
 */
 EXPORT_C TInt CHbDeviceMessageBoxSymbian::DismissPolicy() const
 {
 return d->mProperties[CHbDeviceMessageBoxPrivate::EDismissPolicy].IntValue();
 }
 /*!
-Sets message box button text. The message box gets updated next time ShowL() or UpdateL()
+Sets message box button text.
-is called.
 \param aButton Selects the button.
 \param aText Button text.
-\sa ButtonText()
+\sa ButtonText(), SetButton(), ShowL(), UpdateL()
 */
 EXPORT_C void CHbDeviceMessageBoxSymbian::SetButtonTextL(TButtonId aButton, const TDesC& aText)
 {
 d->SetButtonTextL(aButton, aText);
 }
 /*!
-Returns message box button text.
+Returns message box button text. Question message box by default has "Yes" and "No" buttons.
+Other message boxes have a single "Ok" button.
 \param aButton Selects the button.
 \sa SetButtonTextL()
 */
 CHbDeviceMessageBoxPrivate::EAcceptText, aButton);
 return d->mProperties[id].StringValue();
 }
 /*!
-Sets message box button presence. The message box gets updated next time ShowL() or UpdateL()
+Sets message box button presence.
-is called.
 \param aButton Selects the button.
 \param aEnable True enables (makes visible) message box button.
-\sa HasButton()
+\sa HasButton(), SetButtonTextL(), ShowL(), UpdateL()
 */
 EXPORT_C void CHbDeviceMessageBoxSymbian::SetButton(TButtonId aButton, TBool aEnable)
 {
 d->SetButtonNull(aButton, !aEnable);
 }
 /*!
-Returns message box button presence.
+Returns message box button presence. Question message box by default has accept and reject
+buttons. Other message boxes have a single accept button.
 \param aButton Selects the button.
-\sa SetButton()
+\sa SetButton(), ButtonText()
 */
 EXPORT_C TBool CHbDeviceMessageBoxSymbian::HasButton(TButtonId aButton) const
 {
 CHbDeviceMessageBoxPrivate::TPropertyId id =
 CHbDeviceMessageBoxPrivate::ButtonPropertyId(
 }
 /*!
 Sets message box buttons to standard buttons.
-\param aButtons Message box buttons. A combination of flags,
+\param aButtons Message box buttons. A combination of flags, eg.
-eg. HbMessageBox::Yes | HbMessageBox::No. Button flags are scanned starting from lsb.
+HbMessageBox::Yes | HbMessageBox::No.
-First button found goes to accept position and so forth.
+Button flags are scanned starting from lsb. First button found goes to accept position
+and so forth.
-\sa StandardButtons()
+\sa HbMessageBox::StandardButton, StandardButtons(), ShowL(), UpdateL()
 */
 EXPORT_C void CHbDeviceMessageBoxSymbian::SetStandardButtons(TUint aButtons)
 {
 return d->SetStandardButtons(aButtons);
 }
 /*!
 Returns standard buttons set to a message box. A default value for question message box is
-HbMessageBox::Yes|HbMessageBox::No. For all other message box types the default is
+HbMessageBox::Yes | HbMessageBox::No. For all other message box types the default is
 HbMessageBox::Ok.
-\sa SetStandardButtons()
+\sa HbMessageBox::StandardButton, SetStandardButtons()
 */
 EXPORT_C TUint CHbDeviceMessageBoxSymbian::StandardButtons() const
 {
 return d->mProperties[CHbDeviceMessageBoxPrivate::EStandardButtons].IntValue();
 }

changeset 21	4633027730f5
parent 7	923ff622b8b9
child 23	e6ad4ef83b23