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 ALFLAYOUTMANAGER

    20 #define ALFLAYOUTMANAGER

    21 

    22 #include <osn/osndefines.h>

    23 #include <osn/osntypes.h>

    24 #include <memory>

    25 #include <alf/ialflayoutmanager.h>

    26 #include <alf/alflayout.h>

    27 

    28 using std::auto_ptr;

    29 

    30 namespace Alf

    31     {

    32 class IAlfWidgetControl;

    33 class AlfLayoutManagerImpl;

    34 class IAlfLayoutPreferences;

    35 

    36 

    37 /**

    38  * @class AlfLayoutManager alflayoutmanager.h "alf/alflayoutmanager.h"

    39  * The interface for layout managers

    40  *

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

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

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

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

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

    46  *

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

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

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

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

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

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

    53  * width among the children.

    54  *

    55  * @code

    56  * // Create layout manager interface.

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

    58  *

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

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

    61  *

    62  * if(layoutPreferences != 0)

    63  *     {

    64  *     TAlfXYMetric preferredSize;

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

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

    67  *     }

    68  * @endcode

    69  *

    70  * @lib alfwidgetmodel.lib

    71  * @since S60 ?S60_version

    72  * @status Draft

    73  * @interfaces IAlfLayoutManager, IAlfLayoutPreferences

    74  */

    75 class AlfLayoutManager : public IAlfLayoutManager

    76     {

    77 public:

    78 

    79     /**

    80      * layout manager constructor

    81      *

    82      * @param aLayoutType type of layout used by this manager.

    83      */

    84     OSN_IMPORT AlfLayoutManager(TAlfLayoutType aLayoutType);

    85         

    86     /**

    87      * virtual destructor

    88      */

    89     OSN_IMPORT virtual ~AlfLayoutManager();

    90     

    91 public:

    92 

    93     /**

    94      * @return the owner control of the layoutmanager.

    95      */        

    96     OSN_IMPORT CAlfWidgetControl& owner() const;

    97 

    98     /**

    99      * returns the control at aIndex.

   100      *

   101      * @param aIndex index for the control.

   102      * @return control at aIndex

   103      */

   104     OSN_IMPORT CAlfWidgetControl* getControl(int aIndex) const;

   105     

   106     /**

   107      * returns the count of controls inside layoutmanager.

   108      *

   109      * @return count of controls inside layoutmanager

   110      */

   111     OSN_IMPORT int count() const;

   112     

   113 public:

   114     //from IAlfLayoutManager

   115         

   116     /**

   117      * creates the layout used by this layoutmanager.

   118      *

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

   120      * @param aParentLayout parent for the created layout

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

   122      * @exception osncore::AlfVisualException Thrown with error code osncore::EInvalidVisual if aLayoutIndex is out of bounds.     

   123      * @exception osncore::AlfVisualException Thrown with error code osncore::ECanNotCreateVisual if the layout creation failed.

   124      */    

   125     OSN_IMPORT virtual void createLayout(CAlfWidgetControl& aOwner,

   126         CAlfLayout* aParentLayout, int aLayoutIndex);

   127             

   128     /**

   129      * from IAlfLayoutManager

   130      * Returns the layout used by this layoutmanager.

   131      *

   132      * @return layout used by this layoutmanager.

   133      * @exception osncore::AlfVisualException Thrown with error code osncore::EInvalidVisual if layout is not created.

   134      */

   135     OSN_IMPORT virtual CAlfLayout& getLayout() const;

   136     

   137     /**

   138      * from IAlfLayoutManager

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

   140      * must be updated

   141      * 

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

   143      * @exception osncore::AlfVisualException Thrown with error code osncore::EInvalidVisual if layout is not created.

   144      *

   145      */

   146     OSN_IMPORT virtual void updateChildLayout(CAlfWidgetControl* aControl);

   147     

   148     /**

   149      * from IAlfLayoutManager

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

   151      * must be updated.

   152      * @exception osncore::AlfVisualException Thrown with error code osncore::EInvalidVisual if layout is not created.     

   153      */

   154     OSN_IMPORT virtual void updateChildrenLayout();

   155     

   156     /**

   157      * from IAlfLayoutManager

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

   159      * removed from the layout.

   160      * 

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

   162      * @exception osncore::AlfVisualException Thrown with error code osncore::EInvalidVisual if layout is not created.     

   163      */    

   164     OSN_IMPORT virtual void childRemoved(CAlfWidgetControl* aControl);

   165     

   166 protected:

   167     /**

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

   169      * must be updated. Called in updateChildLayout for the updated control

   170      * and in updateChildrenLayout for all the controls in the layout.

   171      * 

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

   173      */

   174     OSN_IMPORT virtual void doUpdateChildLayout(CAlfWidgetControl* aControl);

   175     

   176     /**

   177      * returns the rect of the control.

   178      *

   179      * @param aControl, control, which size is queried.

   180      * @param aRect will receive the rect of aControl, if return value is true.

   181      * @return true, if control rect was fetched, false, if the control hasn't 

   182      * got a visualization.

   183      */    

   184     OSN_IMPORT bool controlRect(

   185         CAlfWidgetControl& aControl, TAlfRealRect& aRect);

   186         

   187     /**

   188      * sets the size and position to the control

   189      *

   190      * @param aControl, control, which size and position is being set.

   191      * @param aRect, rect for aControl

   192      */        

   193     OSN_IMPORT void setControlRect(

   194         CAlfWidgetControl& aControl, const TAlfRealRect &aRect);

   195 

   196     /**

   197      * sets the position to the control

   198      *

   199      * @param aControl, control, which position is being set.

   200      * @param aPos, position for aControl

   201      */

   202     OSN_IMPORT void setControlPosition(

   203         CAlfWidgetControl& aControl, const TAlfRealPoint& aPos);

   204         

   205     /**

   206      * sets the size to control

   207      *

   208      * @param aControl, control, which size is being set.

   209      * @param aSize, new size for aControl.

   210      */        

   211     OSN_IMPORT void setControlSize(

   212         CAlfWidgetControl& aControl, const TAlfRealPoint &aSize);

   213     

   214     /**

   215      * returns layout preferences for aControl

   216      *

   217      * @return layout preferences for aControl.

   218      */

   219     OSN_IMPORT const IAlfLayoutPreferences* getLayoutPreferences(

   220         CAlfWidgetControl* aControl) const;

   221 

   222 public:

   223 // from base class IAlfInterfaceBase

   224     

   225     /**

   226      * Interface getter. 

   227      * @see IAlfInterfaceBase::MakeInterface

   228      *

   229      * @since S60 ?S60_version

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

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

   232      *         supported or available.

   233      */    

   234     OSN_IMPORT virtual IAlfInterfaceBase* makeInterface( const IfId& aType );

   235 private: // data

   236 

   237     auto_ptr<AlfLayoutManagerImpl> mData;

   238     

   239     };

   240 

   241     } // namespace Alf

   242 

   243 #endif // ALFLAYOUTMANAGER