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:  interface for layout managers

    15 *

    16 */

    17 

    18 

    19 #ifndef I_ALFLAYOUTMANAGER

    20 #define I_ALFLAYOUTMANAGER

    21 

    22 #include <alf/ialfinterfacebase.h>

    23 #include <alf/alftypes.h>

    24 

    25 class CAlfLayout;

    26 class CAlfControl;

    27 

    28 namespace duiuimodel

    29     {

    30 class DuiNode;

    31     }

    32 using namespace duiuimodel;

    33 

    34 namespace Alf

    35     {

    36 

    37 class CAlfWidgetControl;

    38 class AlfCustomInitDataBase;

    39 

    40 namespace ialflayoutmanager

    41     {

    42      static const IfId Ident =

    43         {

    44         0, "ialflayoutmanager"

    45         };

    46     } 

    47 

    48 /**

    49  * The interface for layout managers

    50  *

    51  * Layout manager handles the layouting of child widgets in the container widget.

    52  * It uses IAlfLayoutPreferences-interface (@see IAlfLayoutPreferences) 

    53  * of child widgets as a guide for laying out the widgets. The layoutmanager 

    54  * is set to the IAlfHostApi- interface (@see IAlfHostApi::setBaseLayout)

    55  * createLayout-method should be the first call after creating the layoutmanager. 

    56  *

    57  * Layout manager may also provide information about the layout preferences of its

    58  * children. If this is supported the layout manager will combine the layout preferences

    59  * of its children taking into consideration the technique used to lay out the children

    60  * using the layout manager. This will provide information about the whole display area

    61  * occupied by the layout manager. For instance vertical flow layout manager will provide

    62  * preferred size area of its children by summing their heights and providing the maximum

    63  * width among the children.

    64  *

    65  * @code

    66  * // Create layout manager interface.

    67  * IAlfLayoutManager* layoutManager = IAlfInterfaceBase::makeInterface<IAlfLayoutManager>(control);

    68  *

    69  * // See if layout preferences is supported in the given layout manager.

    70  * IAlfLayoutPreferences* layoutPreferences = IAlfInterfaceBase::makeInterface<IAlfLayoutPreferences>(layoutManager);

    71  *

    72  * if(layoutPreferences != 0)

    73  *     {

    74  *     TAlfXYMetric preferredSize;

    75  *     // This will report the preferred size of the layout by combining together preferred sizes of its children.

    76  *     bool result = layoutPreferences->getPreferredSize(preferredSize);

    77  *     }

    78  * @endcode

    79  *

    80  * @lib alfwidgetmodel.lib

    81  * @since S60 ?S60_version

    82  * @status Draft

    83  */

    84 class IAlfLayoutManager : public IAlfInterfaceBase

    85     {

    86 public:

    87        

    88     static inline const IfId& type()

    89         {       

    90         return ialflayoutmanager::Ident;

    91         }

    92         

    93     virtual inline ~IAlfLayoutManager() {}

    94     

    95     /**

    96      * Creates the layout used by this layoutmanager.

    97      *

    98      * @param aOwner owner-control of the the created layout.

    99      * @param aParentLayout parent for the created layout

   100      * @param aLayoutIndex index, where created visual should be placed in the parent layout.

   101      * @throw AlfVisualException(EInvalidArrayIndex), if aLayoutIndex is out of bounds

   102      *        AlfVisualException(ECanNotCreateVisual), if the layout creation failed.

   103      */    

   104     virtual void createLayout(CAlfWidgetControl& aOwner, 

   105         CAlfLayout* aParentLayout, int aLayoutIndex) = 0;

   106     

   107     /**

   108      * Returns the layout used by this layoutmanager.

   109      *

   110      * @return layout used by this layoutmanager.

   111      * @throw AlfVisualException(EInvalidVisual), if layout is not created.

   112      */

   113     virtual CAlfLayout& getLayout()const  = 0;

   114     

   115     /**

   116      * Notifies the layout manager, that the child control's layout

   117      * must be updated

   118      * 

   119      * @param aControl control, which size has changed.

   120      * @throw AlfVisualException(EInvalidVisual), if layout is not created.

   121      */    

   122     virtual void updateChildLayout(CAlfWidgetControl* aControl) = 0;

   123     

   124     /**

   125      * Notifies the layout manager, that all the child control's layouts

   126      * must be updated.

   127      * @throw AlfVisualException(EInvalidVisual), if layout is not created.

   128      */    

   129     virtual void updateChildrenLayout() = 0;

   130     

   131     /**

   132      * Notifies the layout manager, that the control's has been

   133      * removed from the layout.

   134      * 

   135      * @param aControl control, which has been removed from the layout.

   136      * @throw AlfVisualException(EInvalidVisual), if layout is not created.

   137      */    

   138     virtual void childRemoved(CAlfWidgetControl* aControl) = 0;

   139     

   140 public:

   141 // from base class IAlfInterfaceBase

   142     

   143     /**

   144      * Interface getter. 

   145      * @see IAlfInterfaceBase::MakeInterface

   146      *

   147      * @since S60 ?S60_version

   148      * @param aType The type id of the queried interface.

   149      * @return The queried interface, or NULL if the interface is not

   150      *         supported or available.

   151      */    

   152     virtual IAlfInterfaceBase* makeInterface( const IfId& aType ) = 0;

   153     };

   154     

   155 /**

   156  * Placeholder for information required to instantiate an layoutmanager

   157  * via the widget factory mechanism.

   158  * A pointer to this structure is casted to a void pointer and sent to the

   159  * factory plugin.

   160  * @lib alfwidgetmodel.lib

   161  * @since S60 ?S60_version

   162  */

   163 struct AlfLayoutManagerInitData

   164     {

   165     /**

   166      * Event handler instance ID.This uniquely identifies every event handler instance.

   167      */

   168     char* mLayoutManagerId;

   169     

   170     /**

   171      * Pointer to node in declaration containing information for the widget.

   172      */

   173     DuiNode* mNode;

   174 

   175     /**

   176      * Pointer to custom data passed via factory mechanism

   177      * Not Owned.

   178      */

   179     AlfCustomInitDataBase* mCustomData;

   180     };

   181 

   182 

   183     } // namespace Alf

   184 

   185 #endif // I_ALFLAYOUTMANAGER