--- a/src/hbcore/devicedialogbase/hbsymbianvariant.cpp Thu Sep 02 20:44:51 2010 +0300
+++ b/src/hbcore/devicedialogbase/hbsymbianvariant.cpp Fri Sep 17 08:32:10 2010 +0300
@@ -27,7 +27,7 @@
_LIT(KPanicSymbianVariantNotSupportedType, "CHbSymbianVariant: Not supported type");
-class CHbSymbianVariantPrivate : public CBase
+NONSHARABLE_CLASS(CHbSymbianVariantPrivate) : public CBase
{
public:
CHbSymbianVariantPrivate();
@@ -247,94 +247,107 @@
};
/*!
- \class CHbSymbianVariant
- \brief CHbSymbianVariant implements QVariant for Symbian.
+ \class CHbSymbianVariant
+ \brief CHbSymbianVariant is a QVariant like union for Symbian data types.
+
+ <b>This class is Symbian only. Not available on other platforms.</b>
+
+ CHbSymbianVariant holds a single value of a single type at a time. CHbSymbianVariant::TType
+ specifies supported data types.
+
+ The class is used to pass parameters to device dialog and indicator plugins. Device dialog
+ and indicator frameworks perform conversion between Qt and Symbian data types. Below list
+ contains a partial list of Symbian data types and corresponding Qt types supported by
+ the class.
- It supports part of the data types supported in QVariant:
- QString (TDesC)
- QChar (TChar)
- QPoint(TPoint)
- QRect(TRect)
- QSize(TSize)
- QByteArray(TDesC8)
- QStringList (MDesCArray)
+ <table>
+ <caption> Symbian/Qt data type analogy</caption>
+ <tr><th>Symbian type</th><th>Qt type</th></tr>
+ <tr><td>TDesC</td><td>QString</td></tr>
+ <tr><td>TChar</td><td>QChar</td></tr>
+ <tr><td>TPoint</td><td>QPoint</td></tr>
+ <tr><td>TRect</td><td>QRect</td></tr>
+ <tr><td>TSize</td><td>QSize</td></tr>
+ <tr><td>TDesC8</td><td>QByteArray</td></tr>
+ <tr><td>MDesCArray</td><td>QStringList</td></tr>
+ <tr><td>CHbSymbianVariantMap</td><td>QVariantMap</td></tr>
+ </table>
- The data passed to the constructor is copied to the CHbSymbianVariant.
-
- \sa CHbSymbianVariantMap, CHbDeviceDialog
- \stable
-
- \hbcore
-
+ \sa CHbSymbianVariantMap, CHbDeviceDialogSymbian, CHbIndicatorSymbian
+
+ \stable
+ \hbcore
*/
/*!
\enum CHbSymbianVariant::TType
- Data types the CHbSymbianVariant can contain
+ Data types CHbSymbianVariant supports.
*/
/*!
- \var CHbSymbianVariant::EInt
- a TInt
+ \var CHbSymbianVariant::TType CHbSymbianVariant::EInt
+ Data type TInt.
*/
/*!
- \var CHbSymbianVariant::EBool
- a TBool
+ \var CHbSymbianVariant::TType CHbSymbianVariant::EBool
+ Data type TBool.
*/
/*!
- \var CHbSymbianVariant::EUint
- a TUint
+ \var CHbSymbianVariant::TType CHbSymbianVariant::EUint
+ Data type TUint.
*/
/*!
- \var CHbSymbianVariant::EReal
- a TReal
+ \var CHbSymbianVariant::TType CHbSymbianVariant::EReal
+ Data type TReal.
*/
/*!
- \var CHbSymbianVariant::ERect
- a TRect
+ \var CHbSymbianVariant::TType CHbSymbianVariant::ERect
+ Data type TRect.
*/
/*!
- \var CHbSymbianVariant::EPoint
- a TPoint
+ \var CHbSymbianVariant::TType CHbSymbianVariant::EPoint
+ Data type TPoint.
*/
/*!
- \var CHbSymbianVariant::ESize
- a TSize
+ \var CHbSymbianVariant::TType CHbSymbianVariant::ESize
+ Data type TSize.
*/
/*!
- \var CHbSymbianVariant::EChar
- a TChar
+ \var CHbSymbianVariant::TType CHbSymbianVariant::EChar
+ Data type TChar.
*/
/*!
- \var CHbSymbianVariant::EDes
- a TDesC
+ \var CHbSymbianVariant::TType CHbSymbianVariant::EDes
+ Data type TDesC.
*/
/*!
- \var CHbSymbianVariant::EBinary
- a TDesC8
+ \var CHbSymbianVariant::TType CHbSymbianVariant::EBinary
+ Data type TDesC8.
*/
/*!
- \var CHbSymbianVariant::EDesArray
- a MDesCArray
+ \var CHbSymbianVariant::TType CHbSymbianVariant::EDesArray
+ Data type MDesCArray.
*/
/*!
- \var CHbSymbianVariant::EVariantMap
- a symbian variant map
+ \var CHbSymbianVariant::TType CHbSymbianVariant::EVariantMap
+ Data type CHbSymbianVariantMap.
*/
/*!
- \fn T * CHbSymbianVariant::Value()
+ \fn T* CHbSymbianVariant::Value() const
- Template class to get variants value casted to the correct pointer type. See the
- CHbSymbianVariant::TType for the supported classes.
+ Template fuction to get variant's value casted to a correct pointer type. See
+ TType for the supported types.
- \sa CHbSymbianVariant::TType
+ \sa TType
*/
/*!
- Creates a new CHbSymbianVariant. Note that if CHbSymbianVariant::EDesArray
- is used the \aData must be casted to MDesCArray pointer when passed to the method.
+ Creates a new CHbSymbianVariant. Data passed to the constructor is copied to the
+ CHbSymbianVariant.
+
+ \param aData Data to copy into the variant. Note: If EDesArray is used, data pointer must be casted to MDesCArray.
+ \param aDataType Type of data.
*/
-
EXPORT_C CHbSymbianVariant* CHbSymbianVariant::NewL(const TAny* aData, TType aDataType)
{
CHbSymbianVariant* variant = new (ELeave) CHbSymbianVariant(aData, aDataType);
@@ -344,11 +357,10 @@
return variant;
}
+/*!
+ Returns type of data stored in CHbSymbianVariant.
-/*!
- Returns the data type stored in CHbSymbianVariant
-
- \sa CHbSymbianVariant::TType
+ \sa TType
*/
EXPORT_C CHbSymbianVariant::TType CHbSymbianVariant::Type() const
{
@@ -356,10 +368,8 @@
}
/*!
- Get TAny pointer to the CHbSymbianVariant data.
- The CHbSymbianVariant::Value() should be used instead of this method.
-
- Ownership is not changed.
+ Returns pointer to data stored by CHbSymbianVariant. Ownership does not changed.
+ Value() should be used instead of this method.
*/
EXPORT_C TAny* CHbSymbianVariant::Data() const
{
@@ -367,9 +377,11 @@
}
/*!
- Set new data to CHbSymbianVariant. Old data is deleted.
+ Copies new data to CHbSymbianVariant. Old data is deleted.
+ Ownership does not changed.
- Ownership is not changed.
+ \param aData Data to copy into the variant. Note: If EDesArray is used, data pointer must be casted to MDesCArray.
+ \param aDataType Type of data.
*/
EXPORT_C void CHbSymbianVariant::SetData(TAny* aData, TType aDataType)
{
@@ -379,8 +391,7 @@
}
}
/*!
- Is the the data in CHbSymbianVariant valid. data is valid if the variant
- is created with valid data and data type
+ Returns true if CHbSymbianVariant holds valid data.
*/
EXPORT_C TBool CHbSymbianVariant::IsValid() const
{
@@ -406,7 +417,7 @@
d->InitializeDataL(aData, aDataType);
}
-class CHbSymbianVariantMapPrivate : public CBase
+NONSHARABLE_CLASS(CHbSymbianVariantMapPrivate) : public CBase
{
public:
CHbSymbianVariantMapPrivate():iKeyArray(NULL),iVariantArray() {
@@ -425,18 +436,19 @@
};
/*!
- \class CHbSymbianVariantMap
- \brief CHbSymbianVariantMap is a container for CHbSymbianVariant objects.
+ \class CHbSymbianVariantMap
+ \brief CHbSymbianVariantMap is QVariantMap style container for CHbSymbianVariant objects.
+
+ <b>This class is Symbian only. Not available on other platforms.</b>
- It replicates QVariantMap functionality to Symbian native programming side.
+ This class is used to pass parameters to/from device dialogs.
- \sa CHbSymbianVariant, CHbDeviceDialog
- \stable
+ \sa CHbSymbianVariant, CHbDeviceDialogSymbian
+ \stable
*/
/*!
- Create a new CHbSymbianVariantMap. Map is empty after creation and
- ready for use.
+ Creates an empty CHbSymbianVariantMap.
*/
EXPORT_C CHbSymbianVariantMap* CHbSymbianVariantMap::NewL()
{
@@ -454,17 +466,22 @@
}
/*!
- Adds a key-value pairing to the map. Takes ownership of the variant,
- key is copied. If key is already in the map, the value connected to the key
- is replaced with the new value. the old value is deleted.
+ Adds a key-value pair into the container. Takes ownership of the variant,
+ key is copied. If key is already in the map, the value connected to the key
+ is replaced with the new value and the old value is deleted.
+
+ \param aKey Key for the value.
+ \param aVariant Value to add.
+
+ \return Returns Symbian error code. On error ownership of \p aKey is returned to caller.
*/
EXPORT_C TInt CHbSymbianVariantMap::Add(const TDesC& aKey, CHbSymbianVariant* aVariant)
{
TInt pos = KErrNotFound;
- TInt result = d->iKeyArray->Find(aKey, pos,ECmpNormal);
+ TInt result = d->iKeyArray->Find(aKey, pos, ECmpNormal);
- // there is already a key-value pairing in the map
- if((result == KErrNone) && (pos >= 0)) {
+ // There is already a key-value pairing in the map
+ if ((result == KErrNone) && (pos >= 0)) {
// for some reason directly deleting the pointer and
// assigning a new one to position does not work
@@ -480,19 +497,22 @@
else {
result = KErrNone;
TRAP(result, d->iKeyArray->AppendL(aKey));
- if(result == KErrNone){
+ if (result == KErrNone){
result = d->iVariantArray.Append(aVariant);
- if(result) {
+ if (result) {
d->iKeyArray->Delete(d->iKeyArray->MdcaCount()-1);
}
}
}
return result;
}
+
/*!
- Deletes value mapped to the key given as parameter \a aKey
+ Deletes value from the container.
- On error returns possible Symbian error code.
+ \param aKey Key for the value.
+
+ \return Returns Symbian error code.
*/
EXPORT_C TInt CHbSymbianVariantMap::Delete(const TDesC& aKey)
{
@@ -509,8 +529,11 @@
}
/*!
- Gets value mapped to the key. CHbSymbianVariantMap keeps the ownership of the object.
- Returns NULL if not found.
+ Gets a value from the container.
+
+ \param aKey Key for the value.
+
+ \return Returns pointer to the value or 0 if not found. Value ownership does not transfer.
*/
EXPORT_C const CHbSymbianVariant* CHbSymbianVariantMap::Get(const TDesC& aKey) const
{
@@ -524,7 +547,7 @@
}
/*!
- Get all keys in the map. CHbSymbianVariantMap keeps the ownership of the object.
+ Returns all keys in the map. CHbSymbianVariantMap keeps ownership of the returned value.
*/
EXPORT_C MDesCArray& CHbSymbianVariantMap::Keys() const
{
@@ -540,4 +563,3 @@
{
d = new (ELeave) CHbSymbianVariantMapPrivate();
}
-