diff -r 923ff622b8b9 -r 4633027730f5 src/hbwidgets/devicedialogs/hbdevicemessageboxsymbian.cpp --- a/src/hbwidgets/devicedialogs/hbdevicemessageboxsymbian.cpp Tue Jul 06 14:36:53 2010 +0300 +++ b/src/hbwidgets/devicedialogs/hbdevicemessageboxsymbian.cpp Wed Aug 18 10:05:37 2010 +0300 @@ -385,7 +385,7 @@ 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); @@ -396,7 +396,7 @@ CleanupStack::PushL(parameter); User::LeaveIfError(parameters->Add( PropertyName(static_cast(i)), parameter)); - CleanupStack::Pop(); // parameter + CleanupStack::Pop(parameter); property.SetModified(false); } } @@ -416,7 +416,7 @@ User::Leave(error); // error can be positive or negative } } - CleanupStack::PopAndDestroy(); // parameters + CleanupStack::PopAndDestroy(parameters); } // Close message box @@ -551,7 +551,7 @@ 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. @@ -559,11 +559,17 @@ 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. - Predefined message boxes are: - - Information - - Question - - Warning + Four types of message boxes are predefined. The type determines a set of default properties that + are set on construction. Below is a table listing types and their default properties. + + + + + + + + +
HbDeviceMessageBox types and default properties
TypeIconButtonsTimeoutDismiss policySound
ENoneNo icon"Ok" buttonStandard timeoutTap anywhereNo sound
EInformationInfo icon"Ok" buttonStandard timeoutTap anywhereInfo sound
EWarningWarning icon"Ok" buttonStandard timeoutTap anywhereWarn sound
EQuestionQuestion icon"Yes" and "No" buttonsNo timeoutButton pressQuestion sound
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 @@ -585,7 +591,7 @@ 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 @@ -673,11 +679,11 @@ /*! \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 @@ -743,7 +749,7 @@ /*! 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, @@ -757,7 +763,7 @@ 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; } @@ -765,7 +771,7 @@ /*! 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. Beware that Symbian event processing is running while the function executes. For example application may have exited when the function returns. @@ -788,14 +794,14 @@ 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. Beware that Symbian event processing is running while the function executes. For example application may have exited when the function returns. @@ -815,12 +821,13 @@ } 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. */ @@ -830,11 +837,12 @@ 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. */ @@ -844,7 +852,7 @@ CleanupStack::PushL(messageBox); messageBox->SetTextL(aText); messageBox->ShowL(); - CleanupStack::PopAndDestroy(); // messageBox + CleanupStack::PopAndDestroy(messageBox); } /*! @@ -873,9 +881,10 @@ } /*! - 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() { @@ -885,7 +894,7 @@ /*! 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. Beware that Symbian event processing is running while the function executes. For example application may have exited when the function returns. @@ -906,11 +915,12 @@ /*! 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) { @@ -930,12 +940,11 @@ } /*! - Sets message box text. The message box gets updated next time ShowL() or UpdateL() - is called. + Sets message box text. \param aText Message box text. - \sa Text() + \sa Text(), ShowL(), UpdateL() */ EXPORT_C void CHbDeviceMessageBoxSymbian::SetTextL(const TDesC& aText) { @@ -953,13 +962,12 @@ } /*! - Sets message box icon name or animation logical name. The message box gets updated next time ShowL() or UpdateL() - is called. + Sets message box 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 CHbDeviceMessageBoxSymbian::SetIconNameL(const TDesC& aIconName) { @@ -977,19 +985,18 @@ } /*! - Sets message box animation definition name. The message box gets updated next time ShowL() or UpdateL() - is called. + Sets message box animation definition name. - Supported animation formats are following: + Supported icon animation formats are following: - GIF (.gif) - MNG (.mng) - - Frame animations + - 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) { @@ -1007,12 +1014,11 @@ } /*! - Sets message box icon visibility. The message box gets updated next time ShowL() or UpdateL() - is called. + Sets message box icon visibility. \param aVisible Icon visibility. - \sa IconVisible() + \sa IconVisible(), ShowL(), UpdateL() */ EXPORT_C void CHbDeviceMessageBoxSymbian::SetIconVisible(TBool aVisible) { @@ -1020,7 +1026,8 @@ } /*! - Returns message box icon visibility. + Returns message box icon visibility. Default value is true for message box + types other than ENone. \sa SetIconVisible() */ @@ -1030,12 +1037,11 @@ } /*! - Sets message box timeout. The message box gets updated next time ShowL() or UpdateL() - is called. + Sets message box timeout. \param aTimeout Timeout in milliseconds. Zero denotes no timeout. - \sa Timeout() + \sa Timeout(), ShowL(), UpdateL() */ EXPORT_C void CHbDeviceMessageBoxSymbian::SetTimeout(TInt aTimeout) { @@ -1043,7 +1049,9 @@ } /*! - 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() */ @@ -1053,12 +1061,11 @@ } /*! - Sets message box dismiss policy. The message box gets updated next time ShowL() or UpdateL() - is called. + Sets message box dismiss policy. \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) { @@ -1068,6 +1075,8 @@ /*! 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() */ @@ -1077,13 +1086,12 @@ } /*! - Sets message box button text. The message box gets updated next time ShowL() or UpdateL() - is called. + Sets message box button text. \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) { @@ -1091,7 +1099,8 @@ } /*! - 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. @@ -1106,13 +1115,12 @@ } /*! - Sets message box button presence. The message box gets updated next time ShowL() or UpdateL() - is called. + Sets message box button presence. \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) { @@ -1120,11 +1128,12 @@ } /*! - 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 { @@ -1137,11 +1146,12 @@ /*! Sets message box buttons to standard buttons. - \param aButtons Message box buttons. A combination of flags, - eg. HbMessageBox::Yes | HbMessageBox::No. Button flags are scanned starting from lsb. - First button found goes to accept position and so forth. + \param aButtons Message box buttons. A combination of flags, eg. + HbMessageBox::Yes | HbMessageBox::No. + 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) { @@ -1150,10 +1160,10 @@ /*! 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 {