1 /*

     2 * Copyright (c) 2007 Nokia Corporation and/or its subsidiary(-ies). 

     3 * All rights reserved.

     4 * This component and the accompanying materials are made available

     5 * under the terms of "Eclipse Public License v1.0"

     6 * which accompanies this distribution, and is available

     7 * at the URL "http://www.eclipse.org/legal/epl-v10.html".

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description:  Visual class for alfred widget model.

    15       This class queries the visual by name and ID.

    16 *

    17 */

    18 

    19 

    20 #ifndef ALFREFERENCETOVISUAL_H

    21 #define ALFREFERENCETOVISUAL_H

    22 

    23 //INCLUDES

    24 #include <osn/osndefines.h>

    25 #include <osn/ustring.h>

    26 // FORWARD DECLARATIONS

    27 class CAlfControl;

    28 class CAlfVisual;

    29 

    30 

    31 using namespace osncore;

    32 

    33 namespace Alf

    34     {

    35 class CAlfWidgetControl;

    36 

    37 /** @class AlfReferenceToVisual alfreferencetovisual.h "alf/alfreferencetovisual.h"

    38  * A class for finding a specific visual according to

    39  * the name of the visual, name of the parent element,

    40  * and the associated data ID. The number of visual

    41  * trees created by an element may depend on the data.

    42  * Therefore, the visual structure is not always known

    43  * beforehand. CAlfControl::FindElement() and MAlfElement::FindVisual

    44  * can be used to find elements and visuals even in dynamic

    45  * conditions.

    46  *

    47  *  @lib alfwidgetmodel.lib

    48  *  @since S60 ?S60_version

    49  *  @status Draft

    50  */

    51 class AlfReferenceToVisual

    52     {

    53 public:

    54 

    55     /**

    56      * constructor.

    57      *

    58 	 * @exception std::bad_alloc     

    59      * @since S60 ?S60_version

    60      * @param aElementName The name of the element that is responsible

    61     *      for creating the visual.

    62      * @param aVisualName The name of the visual.

    63      * @param aUseDataID Deprecated and not used. The given data ID is always

    64      * used when resolving the visual. Only if the visual is not found with

    65      * the given data ID, then the data ID zero is tested for global visuals.

    66      * @return New object.

    67      */

    68     OSN_IMPORT static AlfReferenceToVisual* create(

    69         const char* aElementName,const char* aVisualName, bool aUseDataID);

    70 

    71     /** Destructor. No derived classes, therefore not virtual. */

    72     OSN_IMPORT ~AlfReferenceToVisual();

    73 

    74 

    75     /**

    76      * Find the referenced visual according to the given data ID.

    77      *

    78      * @exception osncore::AlfVisualException Thrown with the error code osncore::ECommonError\n 

    79      *										  when some operation performed on visual fails.

    80      * @since S60 ?S60_version

    81      * @param aControl  The control containing the associated element.

    82      * @param aDataID  The data ID used to create the visual. The caller

    83      *      is responsible for determining what data ID

    84      *      is related to this reference. If the visual is not found with

    85      * the given data ID, then the data ID zero is tried for global visuals.

    86      * @return The resolved visual.

    87      */

    88     OSN_IMPORT CAlfVisual* resolve(CAlfWidgetControl& aControl, unsigned int aDataID);

    89 

    90     /**

    91      * Finds the referenced visual according to given pointer to visual

    92      *

    93         * @since S60 ?S60_version

    94         * @param aControl      The control containing the associated element.

    95         * @param aSourceVisual  Pointer to visual that needs to be queried.

    96         */

    97     OSN_IMPORT CAlfVisual* resolve(CAlfWidgetControl &aControl, CAlfVisual* aSourceVisual);

    98 private:

    99     /**

   100      * constructor

   101      */

   102     AlfReferenceToVisual(const char* aElementName,const char* aVisualName, bool aUseDataID);

   103 

   104 private:

   105     // The element name. Owned.

   106     UString mElementName;

   107     // The visual name. Owned.

   108     UString mVisualName;

   109     // The associated data ID.

   110     bool mUseDataID;

   111     };

   112 

   113     } // namespace Alf

   114 

   115 #endif //ALFREFERENCETOVISUAL_H

   116