1 /****************************************************************************

     2 **

     3 ** Copyright (C) 2008-2010 Nokia Corporation and/or its subsidiary(-ies).

     4 ** All rights reserved.

     5 ** Contact: Nokia Corporation (developer.feedback@nokia.com)

     6 **

     7 ** This file is part of the HbWidgets module of the UI Extensions for Mobile.

     8 **

     9 ** GNU Lesser General Public License Usage

    10 ** This file may be used under the terms of the GNU Lesser General Public

    11 ** License version 2.1 as published by the Free Software Foundation and

    12 ** appearing in the file LICENSE.LGPL included in the packaging of this file.

    13 ** Please review the following information to ensure the GNU Lesser General

    14 ** Public License version 2.1 requirements will be met:

    15 ** http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.

    16 **

    17 ** In addition, as a special exception, Nokia gives you certain additional

    18 ** rights.  These rights are described in the Nokia Qt LGPL Exception

    19 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.

    20 **

    21 ** If you have questions regarding the use of this file, please contact

    22 ** Nokia at developer.feedback@nokia.com.

    23 **

    24 ****************************************************************************/

    25 

    26 #include "hbdevicemessageboxsymbian.h"

    27 

    28 #include <hbsymbianvariant.h>

    29 #include <hbdevicedialogsymbian.h>

    30 #include <hbdeleteguardsymbian_p.h>

    31 

    32 #define ARG_UNUSED(x) (void)x;

    33 

    34 enum TMessageBoxPanic {

    35     ETypePanic,

    36     EPropertyPanic,

    37     EButtonIdPanic

    38 };

    39 

    40 NONSHARABLE_CLASS(TMessageBoxProperty)

    41 {

    42 public:

    43     enum TType {

    44         EIntProperty,

    45         EStringProperty

    46     };

    47     TMessageBoxProperty(){mValue.mString = 0;}

    48     void Init(TType aId);

    49     ~TMessageBoxProperty();

    50     const TPtrC StringValue() const;

    51     TInt IntValue() const;

    52     void SetL(const TDesC &aValue);

    53     void Set(TInt aValue);

    54     bool Modified() const{return mFlags.mModified;}

    55     void SetModified(bool aModified){mFlags.mModified = aModified;}

    56     bool Valid() const{return mFlags.mValid;}

    57     void SetValid(bool aValid){mFlags.mValid = aValid;}

    58     TType Type() const{return mType;}

    59     void SetType(TType aType){mType = aType;}

    60 private:

    61     TType mType;

    62     union {

    63         TInt mInt;

    64         HBufC *mString;

    65     } mValue;

    66     struct {

    67         bool mValid:1; // property value has has been set

    68         bool mModified:1; // property has been modified

    69     } mFlags;

    70 };

    71 

    72 NONSHARABLE_CLASS(CHbDeviceMessageBoxPrivate)  : public CBase, public MHbDeviceDialogObserver

    73 {

    74 public:

    75     enum TPropertyId {

    76         EFirstIntProperty,

    77         EType = EFirstIntProperty,

    78         EIconAlignment,

    79         EIconVisible,

    80         ETimeout,

    81         EDismissPolicy,

    82         EAcceptNull,

    83         ERejectNull,

    84         ELastIntProperty = ERejectNull,

    85         EFirstStringProperty,

    86         EText = EFirstStringProperty,

    87         EIconName,

    88         EAcceptText,

    89         ERejectText,

    90         EAnimationDefinition,

    91         ELastStringProperty = EAnimationDefinition,

    92         ENumProperties

    93     };

    94 

    95     void ConstructL(CHbDeviceMessageBoxSymbian::TType aType,

    96         MHbDeviceMessageBoxObserver *aObserver);

    97     ~CHbDeviceMessageBoxPrivate();

    98     void InitProperties(CHbDeviceMessageBoxSymbian::TType aType);

    99     bool PropertiesModified(TInt aIgnoreMask) const;

   100     void SetPropertyValueL(TPropertyId aId, const TDesC &aValue);

   101     void SetPropertyValue(TPropertyId aId, TInt aValue);

   102     void SetButtonNull(CHbDeviceMessageBoxSymbian::TButtonId aButtonId, bool aValue);

   103     void SetButtonTextL(CHbDeviceMessageBoxSymbian::TButtonId aButtonId, const TDesC &aValue);

   104     void SendToServerL(bool aShow = false);

   105     void Close();

   106     bool WaitForClosed();

   107     static const TPtrC PropertyName(TPropertyId aId);

   108     static TPropertyId ButtonPropertyId(TPropertyId aId, CHbDeviceMessageBoxSymbian::TButtonId aButtonId);

   109 

   110 public: // MHbDeviceDialogObserver

   111     void DataReceived(CHbSymbianVariantMap& aData);

   112     void DeviceDialogClosed(TInt aCompletionCode);

   113 

   114 public: // data

   115 

   116     CHbDeviceMessageBoxSymbian *q;

   117     TMessageBoxProperty mProperties[ENumProperties];

   118     CHbDeviceDialogSymbian *mDeviceDialog;

   119     bool mShowCalled;

   120     CHbDeviceMessageBoxSymbian::TButtonId mReceivedButton;

   121     MHbDeviceMessageBoxObserver *mObserver;

   122     bool *mDeleted;

   123     CActiveSchedulerWait mActiveSchedulerWait;

   124 };

   125 

   126 // Panic application

   127 static void Panic(TInt aCode)

   128 {

   129     _LIT(KCategory, "CHbDeviceMessageBoxSymbian");

   130     User::Panic(KCategory, aCode);

   131 }

   132 

   133 // Initialize property

   134 void TMessageBoxProperty::Init(TType aType)

   135 {

   136     if (mType == EStringProperty) {

   137         delete mValue.mString;

   138         // NULL string property denotes an empty string

   139         mValue.mString = 0;

   140     } else {

   141         mValue.mInt = 0;

   142     }

   143     mType = aType;

   144     mFlags.mValid = false;

   145     mFlags.mModified = false;

   146 }

   147 

   148 // Destructor

   149 TMessageBoxProperty::~TMessageBoxProperty()

   150 {

   151     if (mType == EStringProperty) {

   152         delete mValue.mString;

   153     }

   154 }

   155 

   156 // Get string value

   157 const TPtrC TMessageBoxProperty::StringValue() const

   158 {

   159     __ASSERT_DEBUG(mType == EStringProperty, Panic(EPropertyPanic));

   160 

   161     if (mValue.mString) {

   162         return TPtrC(*mValue.mString);

   163     } else {

   164         return TPtrC(KNullDesC);

   165     }

   166 }

   167 

   168 // Get integer value

   169 TInt TMessageBoxProperty::IntValue() const

   170 {

   171     __ASSERT_DEBUG(mType == EIntProperty, Panic(EPropertyPanic));

   172 

   173     return mValue.mInt;

   174 }

   175 

   176 // Set string value

   177 void TMessageBoxProperty::SetL(const TDesC &aValue)

   178 {

   179     __ASSERT_DEBUG(mType == EStringProperty, Panic(EPropertyPanic));

   180 

   181     // Check that value changes

   182     if (mValue.mString && *mValue.mString == aValue) {

   183         return;

   184     }

   185     HBufC *newValue = HBufC::NewL(aValue.Length());

   186     *newValue = aValue;

   187     delete mValue.mString;

   188     mValue.mString = newValue;

   189     mFlags.mValid = true;

   190     mFlags.mModified = true;

   191 }

   192 

   193 // Set integer value

   194 void TMessageBoxProperty::Set(TInt aValue)

   195 {

   196     __ASSERT_DEBUG(mType == EIntProperty, Panic(EPropertyPanic));

   197 

   198     mFlags.mValid = true;

   199 

   200     if (mValue.mInt == aValue) {

   201         return;

   202     }

   203     mValue.mInt = aValue;

   204     mFlags.mModified = true;

   205 }

   206 

   207 // Construct private

   208 void CHbDeviceMessageBoxPrivate::ConstructL(CHbDeviceMessageBoxSymbian::TType aType,

   209     MHbDeviceMessageBoxObserver *aObserver)

   210 {

   211     mDeviceDialog = CHbDeviceDialogSymbian::NewL();

   212 

   213     mReceivedButton = CHbDeviceMessageBoxSymbian::EInvalidButton;

   214     mObserver = aObserver;

   215 

   216     InitProperties(aType);

   217 }

   218 

   219 // Destructor

   220 CHbDeviceMessageBoxPrivate::~CHbDeviceMessageBoxPrivate()

   221 {

   222     // If no observer, remove observer from device dialog. This leaves the

   223     // dialog widget executing at server when client closes connection.

   224     if (!mObserver) {

   225         mDeviceDialog->SetObserver(0);

   226     }

   227     delete mDeviceDialog;

   228 

   229     // Set object deleted flag

   230     if (mDeleted) {

   231         // Mark the object as deleted.

   232         *mDeleted = true;

   233         mDeleted = 0;

   234     }

   235 }

   236 

   237 // Initialize properties

   238 void CHbDeviceMessageBoxPrivate::InitProperties(CHbDeviceMessageBoxSymbian::TType aType)

   239 {

   240     // Initialize all properties to default values

   241     for(int i = 0; i < ENumProperties; i++) {

   242         TMessageBoxProperty &property = mProperties[i];

   243         property.Init(i >= EFirstStringProperty ?

   244             TMessageBoxProperty::EStringProperty : TMessageBoxProperty::EIntProperty);

   245     }

   246 

   247     // Set properties to default values

   248     mProperties[EType].Set(aType);

   249     const TInt alignCenter = 0x0080 | 0x0004; // Qt::AlignCenter

   250     mProperties[EIconAlignment].Set(alignCenter);

   251     mProperties[EIconVisible].Set(ETrue);

   252 

   253     switch(aType) {

   254     case CHbDeviceMessageBoxSymbian::EInformation:

   255     case CHbDeviceMessageBoxSymbian::EWarning: {

   256         const TInt KStandardTimeout = 3000; // 3s

   257         mProperties[ETimeout].Set(KStandardTimeout);

   258         const TInt KTapAnywhere = 0x03; // HbPopup::TapAnywhere

   259         mProperties[EDismissPolicy].Set(KTapAnywhere);

   260 

   261         // Plugin sets accept button by default

   262         mProperties[ERejectNull].Set(true);

   263         mProperties[ERejectNull].SetModified(false);

   264         mProperties[ERejectNull].SetValid(false);

   265         break;

   266     }

   267     case CHbDeviceMessageBoxSymbian::EQuestion: {

   268         const TInt KNoTimeout = 0;

   269         mProperties[ETimeout].Set(KNoTimeout);

   270         const TInt KNoDismiss = 0; // HbPopup::NoDismiss

   271         mProperties[EDismissPolicy].Set(KNoDismiss);

   272         break;

   273     }

   274     default:

   275         Panic(ETypePanic);

   276     }

   277 }

   278 

   279 bool CHbDeviceMessageBoxPrivate::PropertiesModified(TInt aIgnoreMask) const

   280 {

   281     for(int i = 0; i < ENumProperties; i++) {

   282         if (mProperties[i].Modified() && (aIgnoreMask & 1) == 0) {

   283             return true;

   284         }

   285         aIgnoreMask >>= 1;

   286     }

   287     return false;

   288 }

   289 

   290 // Set string property value

   291 void CHbDeviceMessageBoxPrivate::SetPropertyValueL(TPropertyId aId, const TDesC &aValue)

   292 {

   293     mProperties[aId].SetL(aValue);

   294 }

   295 

   296 // Set int property value

   297 void CHbDeviceMessageBoxPrivate::SetPropertyValue(TPropertyId aId, TInt aValue)

   298 {

   299     mProperties[aId].Set(aValue);

   300 }

   301 

   302 // Set button null property value

   303 void CHbDeviceMessageBoxPrivate::SetButtonNull(CHbDeviceMessageBoxSymbian::TButtonId aButtonId,

   304     bool aValue)

   305 {

   306     TPropertyId id = ButtonPropertyId(EAcceptNull, aButtonId);

   307     mProperties[id].Set(aValue);

   308 }

   309 

   310 // Set button text property

   311 void CHbDeviceMessageBoxPrivate::SetButtonTextL(

   312     CHbDeviceMessageBoxSymbian::TButtonId aButtonId, const TDesC &aValue)

   313 {

   314     TPropertyId id = ButtonPropertyId(EAcceptText, aButtonId);

   315     mProperties[id].SetL(aValue);

   316 }

   317 

   318 // Send properties to server. Show or update.

   319 void CHbDeviceMessageBoxPrivate::SendToServerL(bool aShow)

   320 {

   321     // If this is update but ShowL() has not been called, return.

   322     if (!aShow && !mShowCalled) {

   323       return;

   324     }

   325 

   326     // Accept and reject button exists property gates sending button text.

   327     // If button exists but button text is not sent, the plugin uses a default

   328     // button.

   329     int ignoreMask = mProperties[EAcceptNull].IntValue() ? (1 << EAcceptText) : 0;

   330     ignoreMask |= mProperties[ERejectNull].IntValue() ? (1 << ERejectText) : 0;

   331 

   332 

   333     // If this is update but no properties have been mofified, return

   334     if (!aShow && !PropertiesModified(ignoreMask)) {

   335         return;

   336     }

   337 

   338     CHbSymbianVariantMap *parameters = CHbSymbianVariantMap::NewL();

   339     CleanupStack::PushL(parameters);

   340 

   341     for(int i = 0; i < ENumProperties; i++) {

   342         TMessageBoxProperty &property = mProperties[i];

   343         // ShowL() send all valid properties. Update only sends modified properties.

   344         bool sendProperty = aShow ? property.Valid() : property.Modified();

   345         if (sendProperty && (ignoreMask & 1) == 0) {

   346             CHbSymbianVariant* parameter;

   347             if (property.Type() == TMessageBoxProperty::EIntProperty) {

   348                 TInt value = property.IntValue();

   349                 parameter = CHbSymbianVariant::NewL(&value, CHbSymbianVariant::EInt);

   350             } else {

   351                 TPtrC value = property.StringValue();

   352                 parameter = CHbSymbianVariant::NewL(&value, CHbSymbianVariant::EDes);

   353             }

   354             CleanupStack::PushL(parameter);

   355             User::LeaveIfError(parameters->Add(

   356                 PropertyName(static_cast<TPropertyId>(i)), parameter));

   357             CleanupStack::Pop(); // parameter

   358             property.SetModified(false);

   359         }

   360         ignoreMask >>= 1;

   361     }

   362 

   363     _LIT(KDeviceDialogType, "com.nokia.hb.devicemessagebox/1.0");

   364     TInt error;

   365     if (aShow) {

   366         mReceivedButton = CHbDeviceMessageBoxSymbian::EInvalidButton;

   367         error = mDeviceDialog->Show(KDeviceDialogType, *parameters, this);

   368         User::LeaveIfError(error);

   369         mShowCalled = true;

   370     } else {

   371         error = mDeviceDialog->Update(*parameters);

   372         User::LeaveIfError(error);

   373     }

   374     CleanupStack::PopAndDestroy(); // parameters

   375 }

   376 

   377 // Close message box

   378 void CHbDeviceMessageBoxPrivate::Close()

   379 {

   380     mDeviceDialog->Cancel();

   381 }

   382 

   383 // Wait for message box to close

   384 bool CHbDeviceMessageBoxPrivate::WaitForClosed()

   385 {

   386     // Returns true if object was not deleted during wait

   387     if (!mShowCalled) {

   388         return true;

   389     }

   390     RHbDeleteGuardSymbian guard;

   391     guard.OpenAndPushL(&mDeleted);

   392     mActiveSchedulerWait.Start();

   393     return !guard.PopAndClose();

   394 }

   395 

   396 // Get property name

   397 const TPtrC CHbDeviceMessageBoxPrivate::PropertyName(TPropertyId aId)

   398 {

   399     static const wchar_t * const names[] = {

   400         L"type",

   401         L"iconAlignment",

   402         L"iconVisible",

   403         L"timeout",

   404         L"dismissPolicy",

   405         L"primaryActionNull",

   406         L"secondaryActionNull",

   407         L"text",

   408         L"iconName",

   409         L"primaryActionText",

   410         L"secondaryActionText",

   411         L"animationDefinition"

   412     };

   413     __ASSERT_DEBUG(aId >= 0 && aId < sizeof(names)/sizeof(names[0]), Panic(EPropertyPanic));

   414 

   415     return TPtrC((const TUint16 *)names[aId]);

   416 }

   417 

   418 // Modify property id according to button

   419 CHbDeviceMessageBoxPrivate::TPropertyId CHbDeviceMessageBoxPrivate::ButtonPropertyId(

   420     TPropertyId aId, CHbDeviceMessageBoxSymbian::TButtonId aButtonId)

   421 {

   422     __ASSERT_DEBUG(aButtonId == CHbDeviceMessageBoxSymbian::EAcceptButton ||

   423         aButtonId == CHbDeviceMessageBoxSymbian::ERejectButton, Panic(EButtonIdPanic));

   424     switch(aId) {

   425     case EAcceptNull:

   426         return aButtonId == CHbDeviceMessageBoxSymbian::EAcceptButton ? EAcceptNull : ERejectNull;

   427     case EAcceptText:

   428         return aButtonId == CHbDeviceMessageBoxSymbian::EAcceptButton ? EAcceptText : ERejectText;

   429     default:

   430         Panic(EPropertyPanic);

   431         return aId; // suppress warning

   432     }

   433 }

   434 

   435 // Observer, data received from device message box

   436 void CHbDeviceMessageBoxPrivate::DataReceived(CHbSymbianVariantMap& aData)

   437 {

   438     _LIT(KKey, "act");

   439     const CHbSymbianVariant* variant = aData.Get(KKey);

   440     if (variant) {

   441         const TDesC *value = variant->Value<const TDesC>();

   442         if (value) {

   443             _LIT(KPrimary, "p");

   444             if (*value == KPrimary) {

   445                 mReceivedButton = CHbDeviceMessageBoxSymbian::EAcceptButton;

   446             } else {

   447                 mReceivedButton = CHbDeviceMessageBoxSymbian::ERejectButton;

   448             }

   449         }

   450     }

   451 }

   452 

   453 // Observer, device message box closed

   454 void CHbDeviceMessageBoxPrivate::DeviceDialogClosed(TInt aCompletionCode)

   455 {

   456     ARG_UNUSED(aCompletionCode)

   457 

   458     mShowCalled = false;

   459     if (mObserver) {

   460         RHbDeleteGuardSymbian guard;

   461         guard.OpenAndPushL(&mDeleted);

   462         mObserver->MessageBoxClosed(q, mReceivedButton);

   463         if (guard.PopAndClose()) {

   464             return; // observer callback deleted this object. Do not touch it anymore.

   465         }

   466     }

   467     if (mActiveSchedulerWait.IsStarted()) {

   468         mActiveSchedulerWait.AsyncStop();

   469     }

   470 }

   471 

   472 /*!

   473     \class CHbDeviceMessageBoxSymbian

   474     \brief CHbDeviceMessageBoxSymbian is a Symbian implementation of HbDeviceMessageBox.

   475 

   476     CHbDeviceMessageBoxSymbian is intended for use by servers that don't run Qt event loop

   477     and cannot use HbDeviceMessageBox.

   478 

   479     It displays a message box with text, icon or animation and two optional buttons,

   480     accept and reject.

   481 

   482     It provides a similar interface as HbDeviceMessageBox. The main

   483     differences are:

   484     - Signals are replaced by an observer interface

   485     - HbAction/QAction is replaced by button information.

   486     - Function parameters whose type is a Qt or Hb enumeration are replaced by an integer.

   487       As suitable default values are set at construction, it is assumed that application rarely

   488       needs to use these.

   489 

   490     Device message box is a modal dialog. It is shown on top of applications by device dialog

   491     server. CHbDeviceMessageBoxSymbian is a client of the server.

   492 

   493     Three predefined message boxes are provided or a custom one can be constructed using the API.

   494     Predefined message boxes are:

   495     - Information

   496     - Question

   497     - Warning

   498 

   499     ShowL() displays a message box asynchronously. The function returns immediately. The launched

   500     dialog can be updated by setters and then calling UpdateL(). Closing can be observed by a

   501     callback. Because each UpdateL() after the ShowL() requires interprocess communication,

   502     it's advisable to fully construct the device message box before displaying it.

   503 

   504     A device message box is launched synchronously by ExecL() function. The function returns when

   505     the dialog is closed and return value indicates the button selected. The function uses

   506     active scheduler wait to wait for the message box to close. ExecL() should be used

   507     carefully as application event processing continues during the wait and program state may

   508     change, e.g. objects may get deleted. Preferred way is to use asynchoronous ShowL() instead.

   509 

   510     Device message box is closed when user dismisses it, when Close()

   511     is called, timeout triggers or system closes the dialog. Default return value is a reject

   512     button. The default is returned in all other cases than user pressing an accept button.

   513 

   514     Static convenience functions are provided for ease of use. Message boxes created by these

   515     static functions contain a default set of properties depending on the message box type and their

   516     contents cannot be updated while the message box executes.

   517 

   518     Supported animation formats are following:

   519     - GIF (.gif)

   520     - MNG (.mng)

   521         - Frame animations

   522 

   523     Sample code:

   524 

   525     \code

   526     // Launch an information message box and continue execution while it is on display

   527 

   528     CHbDeviceMessageBoxSymbian* messageBox = CHbDeviceMessageBoxSymbian::NewL(

   529         CHbDeviceMessageBoxSymbian::EInformation);

   530     CleanupStack::PushL(messageBox);

   531     _LIT(KText, "Connection established");

   532     messageBox->SetTextL(KText);

   533     messageBox->ShowL();

   534     CleanupStack::PopAndDestroy(); // messageBox

   535     \endcode

   536 

   537     \code

   538     // Above example using a static helper function

   539 

   540     _LIT(KText, "Connection established");

   541     CHbDeviceMessageBoxSymbian::InformationL(KText);

   542     \endcode

   543 

   544     \code

   545     // Ask from user whether to accept connection. Use default buttons (Yes and No). Beware that

   546     // Symbian event loop executes while QuestionL() is executing. For example application may exit.

   547 

   548     _LIT(KText, "Accept connection ?");

   549     CHbDeviceMessageBoxSymbian::TButtonId selection =

   550         CHbDeviceMessageBoxSymbian::QuestionL(KText, KNullDesC, KNullDesC);

   551     if (selection == CHbDeviceMessageBoxSymbian::EAcceptButton) {

   552         // user pressed yes

   553     }

   554     \endcode

   555 

   556     \code

   557     // Modify default properties of the message box.

   558 

   559     iMessageBox = CHbDeviceMessageBoxSymbian::NewL(CHbDeviceMessageBoxSymbian::EQuestion);

   560     _LIT(KText, "Accept connection ?");

   561     iMessageBox->SetTextL(KText);

   562     _LIT(KIconName, "qtg_small_smiley_wondering");

   563     iMessageBox->SetIconNameL(KIconName);

   564     const TInt KAlignLeft = 0x0001; // Qt::AlignLeft

   565     const TInt KAlignTop = 0x0020; // Qt::AlignTop;

   566     iMessageBox->SetIconAlignment(KAlignLeft | KAlignTop);

   567 

   568     _LIT(KAcceptText, "Yes");

   569     iMessageBox->SetButtonTextL(CHbDeviceMessageBoxSymbian::EAcceptButton, KAcceptText);

   570     _LIT(KRejectText, "No");

   571     iMessageBox->SetButtonTextL(CHbDeviceMessageBoxSymbian::ERejectButton, KRejectText);

   572 

   573     iMessageBox->ShowL();

   574     \endcode

   575 

   576     Creating a frame animation.

   577 

   578     Create an animation definition file:

   579     \code

   580     <animations>

   581         <icon name="frame_anim_looping" playmode="loop">

   582             <frame duration="100">c:\icon1.svg</frame>

   583             <frame duration="200">c:\icon2.svg</frame>

   584             <frame duration="300">c:\icon3.svg</frame>

   585             </icon>

   586     </animations>

   587     \endcode

   588 

   589     Create HbDeviceMessageBox in a way described before and

   590     set definition file and animation's logical name.

   591 

   592     \code

   593     _LIT(KAnimationDefinitionXML, "C:\animation.axml");

   594     _LITK(KLogicalIconName, "frame_anim_looping");

   595 

   596     iMessageBox->SetAnimationDefinitionL(KAnimationDefinitionXML);

   597     iMessageBox->SetIconNameL(KIconName);

   598     iMessageBox->ShowL();

   599     \endcode

   600 

   601     \sa HbDeviceMessageBox, HbMessageBox, MHbDeviceMessageBoxObserver

   602 

   603     @proto

   604     @hbwidgets

   605 */

   606 

   607 /*!

   608     \enum CHbDeviceMessageBoxSymbian::TType

   609     Predefined device message boxes.

   610 */

   611 /*!

   612     \var CHbDeviceMessageBoxSymbian::TType CHbDeviceMessageBoxSymbian::EInformation

   613     Information message box.

   614 */

   615 /*!

   616     \var CHbDeviceMessageBoxSymbian::TType CHbDeviceMessageBoxSymbian::EQuestion

   617     Question message box.

   618 */

   619 /*!

   620     \var CHbDeviceMessageBoxSymbian::TType CHbDeviceMessageBoxSymbian::EWarning

   621     Warning message box.

   622 */

   623 

   624 /*!

   625     \enum CHbDeviceMessageBoxSymbian::TButtonId

   626     Selects message box button.

   627 */

   628 /*!

   629     \var CHbDeviceMessageBoxSymbian::TButtonId CHbDeviceMessageBoxSymbian::EAcceptButton

   630     Accept button.

   631 */

   632 /*!

   633     \var CHbDeviceMessageBoxSymbian::TButtonId CHbDeviceMessageBoxSymbian::ERejectButton

   634     Reject button.

   635 */

   636 

   637 /*!

   638     \class MHbDeviceMessageBoxObserver

   639     \brief Interface to observe CHbDeviceMessageBoxSymbian.

   640 

   641     \sa CHbDeviceMessageBoxSymbian

   642 */

   643 

   644 /*!

   645     \fn virtual void MHbDeviceMessageBoxObserver::MessageBoxClosed(

   646         const CHbDeviceMessageBoxSymbian *aMessageBox,

   647         CHbDeviceMessageBoxSymbian::TButtonId aButton) = 0

   648 

   649     Call back function to observe device message box closing.

   650 

   651     \param aMessageBox Pointer to object that launched the closing device message box.

   652     \param aButton Button that was pressed.

   653 

   654     \sa CHbDeviceMessageBoxSymbian::SetObserver()

   655 */

   656 

   657 // Constructor

   658 CHbDeviceMessageBoxSymbian::CHbDeviceMessageBoxSymbian()

   659 {

   660 }

   661 

   662 // Destructor

   663 EXPORT_C CHbDeviceMessageBoxSymbian::~CHbDeviceMessageBoxSymbian()

   664 {

   665     delete d;

   666 }

   667 

   668 /*!

   669     Factory function. Returns pointer to a device message box.

   670 

   671     \param aType Selects a template for the message box. Information, question or warning.

   672     \param aObserver Observer for message box close event

   673 */

   674 EXPORT_C CHbDeviceMessageBoxSymbian* CHbDeviceMessageBoxSymbian::NewL(TType aType,

   675     MHbDeviceMessageBoxObserver *aObserver)

   676 {

   677     ARG_UNUSED(aObserver)

   678     CHbDeviceMessageBoxSymbian *messageBox = new (ELeave) CHbDeviceMessageBoxSymbian;

   679     CleanupStack::PushL(messageBox);

   680     CHbDeviceMessageBoxPrivate *mboxPrivate = new (ELeave) CHbDeviceMessageBoxPrivate;

   681     mboxPrivate->q = messageBox;

   682     CleanupStack::PushL(mboxPrivate);

   683     mboxPrivate->ConstructL(aType, aObserver);

   684     messageBox->d = mboxPrivate;

   685     CleanupStack::Pop(2); // messageBox, mboxPrivate

   686     messageBox->SetObserver(aObserver);

   687     return messageBox;

   688 }

   689 

   690 /*!

   691     Static convenience function to create and show a question device message box. Waits for

   692     the message box to close and returns button selected. If message box was closed for other

   693     reason than button press, returns EInvalidButton.

   694 

   695     <b> Beware that Symbian event processing is running while the function executes. For example

   696     application may have exited when the function returns.</b>

   697 

   698 

   699     \param aText Message box text.

   700     \param aAcceptButtonText Accept button text. If text is empty, default text is used.

   701     \param aRejectButtonText Reject button text. If text is empty, default text is used.

   702 */

   703 EXPORT_C CHbDeviceMessageBoxSymbian::TButtonId CHbDeviceMessageBoxSymbian::QuestionL(

   704     const TDesC& aText, const TDesC& aAcceptButtonText, const TDesC& aRejectButtonText)

   705 {

   706     CHbDeviceMessageBoxSymbian* messageBox = NewL(EQuestion);

   707     CleanupStack::PushL(messageBox);

   708     messageBox->SetTextL(aText);

   709     if (aAcceptButtonText.Length()) {

   710         messageBox->SetButtonTextL(EAcceptButton, aAcceptButtonText);

   711     }

   712     if (aRejectButtonText.Length()) {

   713         messageBox->SetButtonTextL(ERejectButton, aRejectButtonText);

   714     }

   715     TButtonId buttonId = messageBox->ExecL();

   716     CleanupStack::PopAndDestroy(); // messageBox

   717     return buttonId;

   718 }

   719 

   720 /*!

   721     Static convenience function to create and show an information device message box.

   722 

   723     \param aText Message box text.

   724 */

   725 EXPORT_C void CHbDeviceMessageBoxSymbian::InformationL(const TDesC& aText)

   726 {

   727     CHbDeviceMessageBoxSymbian* messageBox = NewL(EInformation);

   728     CleanupStack::PushL(messageBox);

   729     messageBox->SetTextL(aText);

   730     messageBox->ShowL();

   731     CleanupStack::PopAndDestroy(); // messageBox

   732 }

   733 

   734 /*!

   735     Static convenience function to create and show a warning device message box.

   736 

   737     \param aText Message box text.

   738 */

   739 EXPORT_C void CHbDeviceMessageBoxSymbian::WarningL(const TDesC& aText)

   740 {

   741     CHbDeviceMessageBoxSymbian* messageBox = NewL(EWarning);

   742     CleanupStack::PushL(messageBox);

   743     messageBox->SetTextL(aText);

   744     messageBox->ShowL();

   745     CleanupStack::PopAndDestroy(); // messageBox

   746 }

   747 

   748 /*!

   749     Shows a device message box asyncronously. Function launches the message box and returns immediately.

   750     Closing of the message box can be observer with MHbDeviceMessageBoxObserver.

   751     CHbDeviceMessageBoxSymbian object can be used to launch several message boxes. A new one

   752     is launched every time ShowL() is called. Observer receives events for the latest message box launched.

   753 

   754     \sa SetObserver(), UpdateL()

   755 */

   756 EXPORT_C void CHbDeviceMessageBoxSymbian::ShowL()

   757 {

   758     d->SendToServerL(true);

   759 }

   760 

   761 /*!

   762     Updates a device message box asyncronously. Message box that was launched with a lates ShowL()

   763     is updated. Properties that were modified since the last ShowL() or UpdateL() are sent to

   764     device dialog server. Fails if no message box has not been launched.

   765 

   766     \sa ShowL()

   767 */

   768 EXPORT_C void CHbDeviceMessageBoxSymbian::UpdateL()

   769 {

   770     d->SendToServerL(false);

   771 }

   772 

   773 /*!

   774     Closes a device message box.

   775 

   776     \sa ShowL()

   777 */

   778 EXPORT_C void CHbDeviceMessageBoxSymbian::Close()

   779 {

   780     d->Close();

   781 }

   782 

   783 /*!

   784     Shows a device message box synchronously. Function launches the message box and waits for it

   785     to close. Returns a button that was selected. If message box was closed for other reason

   786     than button press, returns EInvalidButton.

   787 

   788     <b> Beware that Symbian event processing is running while the function executes. For example

   789     application may have exited when the function returns.</b>

   790 

   791     \sa ShowL()

   792 */

   793 EXPORT_C CHbDeviceMessageBoxSymbian::TButtonId CHbDeviceMessageBoxSymbian::ExecL()

   794 {

   795     TButtonId buttonId = EInvalidButton;

   796     ShowL();

   797     if (d->WaitForClosed()) {

   798         buttonId = d->mReceivedButton;

   799     } else {

   800         // This object has been deleted during wait, don't touch it

   801     }

   802     return buttonId;

   803 }

   804 

   805 /*!

   806     Sets message box type. All message box properties are reset to a default values for the type.

   807     A ShowL() must be called to launch a message box after SetTypeL() has been called.

   808 

   809     \param aType Message box type.

   810 

   811     \sa Type()

   812 */

   813 EXPORT_C void CHbDeviceMessageBoxSymbian::SetTypeL(TType aType)

   814 {

   815     d->InitProperties(aType);

   816     d->mShowCalled = false;

   817 }

   818 

   819 /*!

   820     Returns message box type.

   821 

   822     \sa SetTypeL()

   823 */

   824 EXPORT_C CHbDeviceMessageBoxSymbian::TType CHbDeviceMessageBoxSymbian::Type() const

   825 {

   826     return static_cast<TType>(

   827         d->mProperties[CHbDeviceMessageBoxPrivate::EType].IntValue());

   828 }

   829 

   830 /*!

   831     Sets message box text. The message box gets updated next time ShowL() or UpdateL()

   832     is called.

   833 

   834     \param aText Message box text.

   835 

   836     \sa Text()

   837 */

   838 EXPORT_C void CHbDeviceMessageBoxSymbian::SetTextL(const TDesC& aText)

   839 {

   840     d->SetPropertyValueL(CHbDeviceMessageBoxPrivate::EText, aText);

   841 }

   842 

   843 /*!

   844     Returns message box text.

   845 

   846     \sa SetTextL()

   847 */

   848 EXPORT_C const TPtrC CHbDeviceMessageBoxSymbian::Text() const

   849 {

   850     return d->mProperties[CHbDeviceMessageBoxPrivate::EText].StringValue();

   851 }

   852 

   853 /*!

   854     Sets message box icon name or animation logical name. The message box gets updated next time ShowL() or UpdateL()

   855     is called.

   856 

   857     \param aIconName Icon name. Icon can be from Hb resources or themes. Or can be a file in

   858     a file system.

   859 

   860     \sa IconName()

   861 */

   862 EXPORT_C void CHbDeviceMessageBoxSymbian::SetIconNameL(const TDesC& aIconName)

   863 {

   864     d->SetPropertyValueL(CHbDeviceMessageBoxPrivate::EIconName, aIconName);

   865 }

   866 

   867 /*!

   868     Returns name and path of the icon shown on dialog or animation's logical name.

   869 

   870     \sa SetIconNameL()

   871 */

   872 EXPORT_C const TPtrC CHbDeviceMessageBoxSymbian::IconName() const

   873 {

   874     return d->mProperties[CHbDeviceMessageBoxPrivate::EIconName].StringValue();

   875 }

   876 

   877 /*!

   878     Sets message box animation definition name.  The message box gets updated next time ShowL() or UpdateL()

   879     is called.

   880 

   881     Supported animation formats are following:

   882     - GIF (.gif)

   883     - MNG (.mng)

   884         - Frame animations

   885 

   886     \param aAnimationDefinition Animation definition file name. Definition can be from Hb resources or themes.

   887     Or can be a file in a file system. The definition must be stored to a place where it can be accessed by

   888     device dialog service.

   889 

   890     \sa AnimationDefinition() SetIconNameL() HbIconAnimationManager::addDefinitionFile()

   891 */

   892 EXPORT_C void CHbDeviceMessageBoxSymbian::SetAnimationDefinitionL(const TDesC& aAnimationDefinition)

   893 {

   894 	d->SetPropertyValueL(CHbDeviceMessageBoxPrivate::EAnimationDefinition, aAnimationDefinition);

   895 }

   896 

   897 /*!

   898     Returns device message box animation definition name.

   899 

   900     \sa SetAnimationDefinitionL()

   901 */

   902 EXPORT_C TPtrC CHbDeviceMessageBoxSymbian::AnimationDefinition() const

   903 {

   904 	return d->mProperties[CHbDeviceMessageBoxPrivate::EAnimationDefinition].StringValue();

   905 }

   906 

   907 /*!

   908     Sets message box icon alignment. The message box gets updated next time ShowL() or UpdateL()

   909     is called.

   910 

   911     \param aQtAlignment Icon alignment. Values are Qt::Alignment flags.

   912 

   913     \sa Qt::Alignment, IconAlignment()

   914 */

   915 /*!

   916     \deprecated void CHbDeviceMessageBoxSymbian::SetIconAlignmentL(TInt aQtAlignment)

   917     is deprecated. Replaced by

   918     void CHbDeviceMessageBoxSymbian::SetIconAlignment(TInt aQtAlignment).

   919 

   920 */

   921 EXPORT_C void CHbDeviceMessageBoxSymbian::SetIconAlignmentL(TInt aQtAlignment)

   922 {

   923     d->SetPropertyValue(CHbDeviceMessageBoxPrivate::EIconAlignment, aQtAlignment);

   924 }

   925 

   926 /*!

   927     Sets message box icon alignment. The message box gets updated next time ShowL() or UpdateL()

   928     is called.

   929 

   930     \param aQtAlignment Icon alignment. Values are Qt::Alignment flags.

   931 

   932     \sa Qt::Alignment, IconAlignment()

   933 */

   934 EXPORT_C void CHbDeviceMessageBoxSymbian::SetIconAlignment(TInt aQtAlignment)

   935 {

   936     d->SetPropertyValue(CHbDeviceMessageBoxPrivate::EIconAlignment, aQtAlignment);

   937 }

   938 

   939 /*!

   940     Returns message box icon alignment. Returned values are Qt::Alignment flags.

   941 

   942     \sa Qt::Alignment, SetIconAlignment()

   943 */

   944 EXPORT_C TInt CHbDeviceMessageBoxSymbian::IconAlignment() const

   945 {

   946     return d->mProperties[CHbDeviceMessageBoxPrivate::EIconAlignment].IntValue();

   947 }

   948 

   949 /*!

   950     Sets message box icon visibility. The message box gets updated next time ShowL() or UpdateL()

   951     is called.

   952 

   953     \param aVisible Icon visibility.

   954 

   955     \sa IconVisible()

   956 */

   957 EXPORT_C void CHbDeviceMessageBoxSymbian::SetIconVisible(TBool aVisible)

   958 {

   959     d->SetPropertyValue(CHbDeviceMessageBoxPrivate::EIconVisible, aVisible);

   960 }

   961 

   962 /*!

   963     Returns message box icon visibility.

   964 

   965     \sa SetIconVisible()

   966 */

   967 EXPORT_C TBool CHbDeviceMessageBoxSymbian::IconVisible() const

   968 {

   969     return d->mProperties[CHbDeviceMessageBoxPrivate::EIconVisible].IntValue();

   970 }

   971 

   972 /*!

   973     Sets message box timeout. The message box gets updated next time ShowL() or UpdateL()

   974     is called.

   975 

   976     \param aTimeout Timeout in milliseconds. Zero denotes no timeout.

   977 

   978     \sa Timeout()

   979 */

   980 /*!

   981     \deprecated void CHbDeviceMessageBoxSymbian::SetTimeoutL(TInt aTimeout)

   982     is deprecated. Replaced by

   983     void CHbDeviceMessageBoxSymbian::SetTimeout(TInt aTimeout).

   984 

   985 */

   986 EXPORT_C void CHbDeviceMessageBoxSymbian::SetTimeoutL(TInt aTimeout)

   987 {

   988     d->SetPropertyValue(CHbDeviceMessageBoxPrivate::ETimeout, aTimeout);

   989 }

   990 

   991 /*!

   992     Sets message box timeout. The message box gets updated next time ShowL() or UpdateL()

   993     is called.

   994 

   995     \param aTimeout Timeout in milliseconds. Zero denotes no timeout.

   996 

   997     \sa Timeout()

   998 */

   999 EXPORT_C void CHbDeviceMessageBoxSymbian::SetTimeout(TInt aTimeout)

  1000 {

  1001     d->SetPropertyValue(CHbDeviceMessageBoxPrivate::ETimeout, aTimeout);

  1002 }

  1003 

  1004 /*!

  1005     Returns message box timeout value in milliseconds.

  1006 

  1007     \sa SetTimeout()

  1008 */

  1009 EXPORT_C TInt CHbDeviceMessageBoxSymbian::Timeout() const

  1010 {

  1011     return d->mProperties[CHbDeviceMessageBoxPrivate::ETimeout].IntValue();

  1012 }

  1013 

  1014 /*!

  1015     Sets message box dismiss policy. The message box gets updated next time ShowL() or UpdateL()

  1016     is called.

  1017 

  1018     \param aHbPopupDismissPolicy Dismiss policy. Values are HbPopup::DismissPolicy flags.

  1019 

  1020     \sa HbPopup::DismissPolicy, DismissPolicy()

  1021 */

  1022 /*!

  1023     \deprecated void CHbDeviceMessageBoxSymbian::SetDismissPolicyL(TInt aHbPopupDismissPolicy)

  1024     is deprecated. Replaced by

  1025     void CHbDeviceMessageBoxSymbian::SetDismissPolicy(TInt aHbPopupDismissPolicy).

  1026 

  1027 */

  1028 EXPORT_C void CHbDeviceMessageBoxSymbian::SetDismissPolicyL(TInt aHbPopupDismissPolicy)

  1029 {

  1030     d->SetPropertyValue(CHbDeviceMessageBoxPrivate::EDismissPolicy,

  1031         aHbPopupDismissPolicy);

  1032 }

  1033 

  1034 /*!

  1035     Sets message box dismiss policy. The message box gets updated next time ShowL() or UpdateL()

  1036     is called.

  1037 

  1038     \param aHbPopupDismissPolicy Dismiss policy. Values are HbPopup::DismissPolicy flags.

  1039 

  1040     \sa HbPopup::DismissPolicy, DismissPolicy()

  1041 */

  1042 EXPORT_C void CHbDeviceMessageBoxSymbian::SetDismissPolicy(TInt aHbPopupDismissPolicy)

  1043 {

  1044     d->SetPropertyValue(CHbDeviceMessageBoxPrivate::EDismissPolicy,

  1045         aHbPopupDismissPolicy);

  1046 }

  1047 

  1048 /*!

  1049     Returns message box dismiss policy. Returned values are HbPopup::DismissPolicy flags.

  1050 

  1051     \sa HbPopup::DismissPolicy, SetDismissPolicy()

  1052 */

  1053 EXPORT_C TInt CHbDeviceMessageBoxSymbian::DismissPolicy() const

  1054 {

  1055     return d->mProperties[CHbDeviceMessageBoxPrivate::EDismissPolicy].IntValue();

  1056 }

  1057 

  1058 /*!

  1059     Sets message box button text. The message box gets updated next time ShowL() or UpdateL()

  1060     is called.

  1061 

  1062     \param aButton Selects the button.

  1063     \param aText Button text.

  1064 

  1065     \sa ButtonText()

  1066 */

  1067 EXPORT_C void CHbDeviceMessageBoxSymbian::SetButtonTextL(TButtonId aButton, const TDesC& aText)

  1068 {

  1069     d->SetButtonTextL(aButton, aText);

  1070 }

  1071 

  1072 /*!

  1073     Returns message box button text.

  1074 

  1075     \param aButton Selects the button.

  1076 

  1077     \sa SetButtonTextL()

  1078 */

  1079 EXPORT_C const TPtrC CHbDeviceMessageBoxSymbian::ButtonText(TButtonId aButton) const

  1080 {

  1081     CHbDeviceMessageBoxPrivate::TPropertyId id =

  1082         CHbDeviceMessageBoxPrivate::ButtonPropertyId(

  1083             CHbDeviceMessageBoxPrivate::EAcceptText, aButton);

  1084     return d->mProperties[id].StringValue();

  1085 }

  1086 

  1087 /*!

  1088     Sets message box button presence. The message box gets updated next time ShowL() or UpdateL()

  1089     is called.

  1090 

  1091     \param aButton Selects the button.

  1092     \param aEnable True enables (makes visible) message box button.

  1093 

  1094     \sa HasButton()

  1095 */

  1096 /*!

  1097     \deprecated void CHbDeviceMessageBoxSymbian::SetButtonL(TButtonId aButton, TBool aEnable)

  1098     is deprecated. Replaced by

  1099     void CHbDeviceMessageBoxSymbian::SetButton(TButtonId aButton, TBool aEnable).

  1100 

  1101 */

  1102 EXPORT_C void CHbDeviceMessageBoxSymbian::SetButtonL(TButtonId aButton, TBool aEnable)

  1103 {

  1104     d->SetButtonNull(aButton, !aEnable);

  1105 }

  1106 

  1107 /*!

  1108     Sets message box button presence. The message box gets updated next time ShowL() or UpdateL()

  1109     is called.

  1110 

  1111     \param aButton Selects the button.

  1112     \param aEnable True enables (makes visible) message box button.

  1113 

  1114     \sa HasButton()

  1115 */

  1116 EXPORT_C void CHbDeviceMessageBoxSymbian::SetButton(TButtonId aButton, TBool aEnable)

  1117 {

  1118     d->SetButtonNull(aButton, !aEnable);

  1119 }

  1120 

  1121 /*!

  1122     Returns message box button presence.

  1123 

  1124     \param aButton Selects the button.

  1125 

  1126     \sa SetButton()

  1127 */

  1128 EXPORT_C TBool CHbDeviceMessageBoxSymbian::HasButton(TButtonId aButton) const

  1129 {

  1130     CHbDeviceMessageBoxPrivate::TPropertyId id =

  1131         CHbDeviceMessageBoxPrivate::ButtonPropertyId(

  1132             CHbDeviceMessageBoxPrivate::EAcceptNull, aButton);

  1133     return !d->mProperties[id].IntValue();

  1134 }