1 /*

     2 * Copyright (c) 2006-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:   Defines CHuiLayout class. Layouts are visuals that manage 

    15 *                the placement of a set of child visuals.

    16 *

    17 */

    18 

    19 

    20 

    21 #ifndef __HUILAYOUT_H__

    22 #define __HUILAYOUT_H__

    23 

    24 

    25 #include <e32base.h>

    26 #include <uiacceltk/HuiVisual.h>

    27 #include <uiacceltk/huimetric.h>

    28 

    29 /* Forward declarations */

    30 class CHuiEnv;

    31 class CHuiControl;

    32 

    33 

    34 /** Layout types. */

    35 enum THuiLayoutType

    36     {

    37     EHuiLayoutTypeLayout,

    38     EHuiLayoutTypeFlow,

    39     EHuiLayoutTypeGrid,

    40     EHuiLayoutTypeApp,

    41     EHuiLayoutTypeAnchor

    42     };

    43 

    44 /**

    45  * Layouts are visuals that manage the placement of a set of child visuals

    46  * (or other layouts).

    47  *

    48  * Layouts are responsible for setting the positions and sizes of their

    49  * child visuals. Each layout can define a position, a size, or both

    50  * (or neither) for their children.

    51  *

    52  * Layouts use the children's ordinal numbers to determine where each of

    53  * them should be placed. For example, a grid layout could define that the

    54  * top row contains children with ordinals 0..3, from left to right. The

    55  * second row could then contain the children 4..7. When the order of the

    56  * child visuals changes within their parent layout, the parent layout

    57  * will recalculate the positions and sizes of the affected children.

    58  *

    59  * When the size of a layout changes, it will immediately recalculate the

    60  * layout of its children. The transition time that is specified in the

    61  * size transition of the layout is used when setting the targets of the

    62  * children's new positions and sizes.

    63  *

    64  * Layouts are able to notify their controls when their size is changed.

    65  * These notifications are needed because the size of a layout is not known

    66  * until the display is refreshed. This means that the <strong>size of a layout

    67  * is not available when your controls ConstructL is executed</strong>, unless

    68  * it is explicitly set. The notifications are also handy because they allow

    69  * the controls to respond to dynamic screen size changes. So unless if the

    70  * whole screen is not used for the layout, the notifications are the only way

    71  * to do calculations based on the layout size.

    72  *

    73  * To make the control receive layout update notifications call:

    74  *

    75  * <code>

    76  * layout->SetFlags(EHuiVisualFlagLayoutUpdateNotification);

    77  * </code>

    78  *

    79  * .. and override VisualLayoutUpdated() method in your control.

    80  *

    81  * @see SetSize()

    82  * @see SetFlags()

    83  * @see CHuiControl::VisualLayoutUpdated()

    84  *

    85  * Each layout defines its own local coordinate system used for interpreting

    86  * the positions and sizes of its child visuals. The base unit of the 

    87  * coordinate system is defined with the SetBaseUnit() method, which sets a

    88  * THuiXYMetric to use as the basis for all coordinate calculations. The default

    89  * metric is [1px, 1px] which corresponds to pixels on the display.

    90  *

    91  * The local coordinate system of a layout can be mirrored horizontally and/or

    92  * vertically by using a negative magnitude in the relevant THuiMetric of the

    93  * base unit. Note that this will only affect the local coordinate system 

    94  * of the layout: the contents of the child visuals or child layouts will not 

    95  * be mirrored. Visual mirroring should be done with a CHuiTransformation,

    96  * and child layouts can be mirrored by further application of the negative

    97  * base unit metrics. In order to enable a layout to automatically mirror the 

    98  * horizontal component of the base unit based on locale mirroring, set the visual flag 

    99  * @c EHuiVisualFlagAutomaticLocaleMirroringEnabled, note that it is necessary

   100  * to set this flag for each layout for which this feature is required.

   101  *

   102  * To create to a fully scalable UI, the appropriate base unit metrics and

   103  * layout visuals must be used. For example, the EHuiUnitS60 metric unit is

   104  * dependent on the platform-specified measurement units for layout. 

   105  * CHuiGridLayout and CHuiAnchorLayout provide support for pixel-independent 

   106  * placement of their children.

   107  *

   108  * @see CHuiAnchorLayout

   109  * @see CHuiGridLayout

   110  *

   111  * Applications that need more complex layouts should derive their own

   112  * CHuiLayout based classes that implement the necessary layout calculations.

   113  * In many cases, however, a combination of some of the built-in layout classes

   114  * such as anchor and grid layouts will be sufficient.

   115  */

   116 class CHuiLayout : public CHuiVisual

   117     {

   118 public:

   119 

   120     enum TExpansionFlags

   121         {

   122         /** Not expanding in any direction. */

   123         EExpandNone = 0,

   124 

   125         /** Expands horizontally. */

   126         EExpandHorizontally = 1,

   127 

   128         /** Expands vertically. */

   129         EExpandVertically = 2

   130         };

   131 

   132 

   133     /** @beginAPI */

   134 

   135     /* Constructors and destructor. */

   136 

   137     /**

   138      * Construct a new basic layout and give its ownership to a control.

   139      * Note that CHuiLayout has no real layout functionality: its children

   140      * must be laid out manually.

   141      *

   142      * @param aOwnerControl  Owner control.

   143      * @param aParentLayout  Parent layout for the new layout.

   144      */

   145     IMPORT_C static CHuiLayout* AddNewL(CHuiControl& aOwnerControl,

   146                                         CHuiLayout* aParentLayout = 0);

   147 

   148     /**

   149      * Constructor.

   150      */

   151     IMPORT_C CHuiLayout(MHuiVisualOwner& aOwner);

   152 

   153     /**

   154      * Destructor.

   155      */

   156     IMPORT_C ~CHuiLayout();

   157 

   158     /**

   159      * Second-phase constructor from CHuiVisual, must be called in deriving class

   160      */

   161     IMPORT_C void ConstructL();

   162 

   163 

   164 

   165     /* Methods. */

   166 

   167     /**

   168      * From CHuiVisual. Removes this layout from its owner and and destroys the layout.

   169      * Also removes the entire hierarchy of child visuals and destroys all

   170      * of them.

   171      */

   172     IMPORT_C void RemoveAndDestroyAllD();

   173 

   174     /**

   175      * From CHuiVisual. Finds a visual whose tag descriptor contains a specific tag.

   176      * Checks self first, then looks through the child visuals.

   177      *

   178      * CHuiLayout::FindTag() extends upon the basic implementation

   179      * in CHuiVisual::FindTag() by adding recursive visual hierarchy

   180      * searching.

   181      *

   182      * @param aTag  Tag to look for. If this tag is found as a part of a

   183      *              visual's colon-separated tag descriptor, it is treated

   184      *              as a match and the visual is returned.

   185      *              The tag to look for cannot contain separator characters (:).

   186      *

   187      * @return  Visual whose tag descriptor matches the tag. <code>NULL</code>,

   188      *          if no such visual could be found. If a visual is returned,

   189      *          it will either be this visual or one of its descendants.

   190      *

   191      * @see CHuiVisual::Tag()

   192      * @see CHuiVisual::SetTagL()

   193      * @see CHuiVisual::IsTagged()

   194      * @see CHuiVisual::FindTag()

   195      */

   196     IMPORT_C CHuiVisual* FindTag(const TDesC8& aTag);

   197 

   198     /**

   199      * Append a new visual to the layout. If the visual is already a member of

   200      * some other layout, it will be removed from the old layout first.

   201      *

   202      * @param aVisual  Visual to append.

   203      * @param aLayoutTransitionTime How long the transition should take visually, in milliseconds.     

   204      *

   205      * @todo  Add a method for appending multiple visuals in one set, so that

   206      *        they only cause a single layout update.

   207      */

   208     IMPORT_C void AppendL(CHuiVisual* aVisual, TInt aLayoutTransitionTime = 0);

   209 

   210     /**

   211      * Insert a new visual to the layout, at specified position (position 0 is the first,

   212      * Count() -1 is the last). If the visual is already a member of

   213      * some other layout, it will be removed from the old layout first.

   214      *

   215      * @param aVisual  Visual to append.

   216      * @param TInt     Position to insert. This is the new ordinal number of the visual.

   217      * @param aLayoutTransitionTime How long the transition should take visually, in milliseconds.     

   218      */

   219     IMPORT_C void InsertL(CHuiVisual* aVisual, TInt aPosition, TInt aLayoutTransitionTime = 0);

   220 

   221     /**

   222      * Remove a visual from the layout.

   223      *

   224      * @param aVisual  Visual to remove.

   225      * @param aLayoutTransitionTime How long the transition should take visually, in milliseconds.     

   226      * @todo  Add a method for removing multiple visuals in one set, so that

   227      *        they only cause a single layout update.

   228      */

   229     IMPORT_C void Remove(CHuiVisual* aVisual, TInt aLayoutTransitionTime = 0);

   230 

   231     /**

   232      * From CHuiVisual. Returns the number of child visuals in the layout.

   233      */

   234     IMPORT_C TInt Count() const;

   235 

   236     /**

   237      * From CHuiVisual. Returns a child visual.

   238      *

   239      * @param aIndex  Index of the child visual.

   240      *

   241      * @return  Reference to a child visual.

   242      */

   243     IMPORT_C CHuiVisual& Visual(TInt aIndex) const;

   244 

   245     /**

   246      * Finds a visual's index.

   247      *

   248      * @param aVisual  Visual to look for.

   249      *

   250      * @return  Index of the visual, or <code>KErrNotFound</code>.

   251      */

   252     IMPORT_C TInt FindVisual(const CHuiVisual* aVisual) const;

   253 

   254     

   255      /**

   256      * From CHuiVisual. Sets the position of the layout.

   257      * @param aPos             Target position, in the local coordinate system as

   258      *                         defined by the parent layout (or the display, 

   259      *                         if there is no parent).

   260      * @param aTransitionTime  Transition time in milliseconds.

   261      */

   262     IMPORT_C void SetPos(const THuiRealPoint& aPos, TInt aTransitionTime = 0);

   263 

   264     /**

   265      * From CHuiVisual. Change the size of the layout. Children's positions and sizes are

   266      * updated accordingly. Each layout class is responsible for determining

   267      * how to update children's layout.

   268      *

   269      * @param aSize                 Size to set the layout to.

   270      * @param aLayoutTransitionTime How long the transition should take visually, in milliseconds.     

   271      */

   272     IMPORT_C void SetSize(const THuiRealSize& aSize, TInt aTransitionTime = 0);

   273 

   274     /**

   275      * From CHuiVisual. Update the layout of all children. Subclasses can call this to

   276      * recalculate the layout of all children.

   277      *

   278      * @param aTransitionTime  Time for layout transition.

   279      */

   280     IMPORT_C void UpdateChildrenLayout(TInt aTransitionTime = 0);

   281 

   282 

   283     /**

   284      * New virtual method. Update the layout of one child visual.

   285      *

   286      * @param aIndex           Child visual index.

   287      * @param aTransitionTime  Time for layout transition.

   288      */

   289     IMPORT_C virtual void UpdateChildLayout(TInt aIndex, TInt aTransitionTime = 0);

   290 

   291     /**

   292      * Sets the inner padding of the layout. This is typically the amount

   293      * of empty space between child visuals in the layout.

   294      *

   295      * @param aInnerPadding  Inner padding (e.g., column, row separation).

   296      */

   297     IMPORT_C void SetInnerPadding(const TPoint& aInnerPadding);

   298 

   299     /**

   300      * Sets the inner padding of the layout. This is typically the amount

   301      * of empty space between child visuals in the layout. 

   302      *

   303      * @note as paddings are relative to the layout visual, if relative units are required, 

   304      * it is advisable to use EHuiUnitRelativeToMySize so that the paddings are relative

   305      * to the size of this layout visual

   306      *

   307      * @param aInnerPadding  Inner padding, using metrics.

   308      */

   309     IMPORT_C void SetInnerPadding(const THuiXYMetric& aInnerPadding);

   310 

   311     /**

   312      * Returns the current inner padding.

   313      */

   314     IMPORT_C const THuiXYMetric& InnerPadding() const;

   315 

   316     /**

   317      * Returns the inner horizontal padding. 

   318      * @deprecated This is useless, use InnerPaddingInBaseUnits() instead.

   319      */

   320     IMPORT_C TInt HorizontalInnerPadding() const;

   321 

   322     /**

   323      * Returns the inner vertical padding.

   324      * @deprecated This is useless, use InnerPaddingInBaseUnits() instead.

   325      */

   326     IMPORT_C TInt VerticalInnerPadding() const;

   327 

   328     /**

   329      * Returns the inner padding converted to the base units of this layout.

   330      * These can be summed with the positions and sizes of the layout's children.

   331      */

   332     IMPORT_C THuiRealPoint InnerPaddingInBaseUnits() const __SOFTFP;

   333 

   334     /**

   335      * Enables or disables scrolling in the layout. An offset

   336      * for the origin of the layout can be defined using 

   337      * ScrollOffset() - method and manipulating the THuiTimedPoint

   338      * returned by that method.

   339      * 

   340      * Scroll offset, unlike other layout parameters, is not directly applied 

   341      * to layout children when UpdateChildrenLayout() is called. Instead, the 

   342      * scroll offset is taken into consideration when individual child visual 

   343      * display rectangles are calculated. This way the scroll offset is directly 

   344      * applied to dirty rectangle calculations as well as to visual content

   345      * rectangle calculations when visuals are drawn.

   346      *

   347      * @param aScrolling  <code>ETrue</code> to enable scrolling,

   348      *                    <code>EFalse</code> to disable.

   349      */

   350     IMPORT_C void EnableScrollingL(TBool aScrolling = ETrue);

   351 

   352     /**

   353      * Indicates whether scrolling is enabled in this layout.

   354      * @see EnableScrolling()

   355      *

   356      * @return ETrue if scrolling is enabled, EFalse otherwise.

   357      */

   358     IMPORT_C TBool Scrolling() const;

   359 

   360     /**

   361      * Returns the scroll offset of the layout. The scroll offset is in

   362      * layout's base units. The scroll offset has to be enabled before this 

   363      * method is called.

   364      * @see EnableScrollingL()

   365      *

   366      * @return  Reference to timed point that defines the scroll offset.

   367      *

   368      * @panic THuiPanic::ELayoutNotScrolling  Scrolling is not enabled.

   369      */

   370     IMPORT_C THuiTimedPoint& ScrollOffset();

   371     IMPORT_C const THuiTimedPoint& ScrollOffset() const;

   372     

   373     /**

   374      * Specifies the scroll offset of this layout. The scroll offset

   375      * is defined in layout's base units. The scroll offset has to be 

   376      * enabled before this method is called.

   377      * @see BaseUnit()

   378      * @see EnableScrollingL()

   379      *

   380      * @param aOffset Offset in layout's base units.

   381      * @param aTransitionTime Time when the offset is to be reached in milliseconds.

   382      */

   383     IMPORT_C void SetScrollOffsetInBaseUnits(const THuiRealPoint& aOffset, TInt aTransitionTime = 0);

   384 

   385     /**

   386      * Determines the virtual size of the layout. The virtual size may be

   387      * larger than the actual size. The virtual size is updated automatically

   388      * when the layout's children are positioned.

   389      *

   390      * @return  Virtual size.

   391      *

   392      * @panic THuiPanic::ELayoutNotScrolling  Scrolling is not enabled.

   393      */

   394     IMPORT_C TSize VirtualSize() const;

   395 

   396     /**

   397      * Layout is calculated according the ordinals. The effective ordinal

   398      * may not be the same as the real child ordinal, because some visuals

   399      * are laid out manually.

   400      *

   401      * @return  Effective ordinal for the child visual.

   402      *

   403      * @panic  THuiPanic::ELayoutChildVisualNotFound  aVisual is not a child

   404      *         of this layout.

   405      */

   406     IMPORT_C TInt EffectiveLayoutOrdinal(const CHuiVisual& aVisual) const;

   407 

   408     /**

   409      * Moves the given child visual to specific position in the layout's list

   410      * of child visuals. Affects the drawing order (last child is drawn last),

   411      * and possibly the final laid out position and size of the visual.

   412      * This is due to that many layout implementations calculate the

   413      * positioning of their children based on child's order number

   414      * in the list.

   415      *

   416      * Causes layout recalculation.

   417      *

   418      * @param aVisual    Child visual to move.

   419      * @param aPosition  New position (and ordinal number)

   420      * 					 in the child list (0 = first, Count()-1 = last).

   421      * @param aLayoutTransitionTime How long the transition should take visually, in milliseconds.

   422      * @see MoveVisualToBack()

   423      * @see MoveVisualToFront()

   424      */

   425     IMPORT_C void Reorder(CHuiVisual& aVisual, TInt aPosition, TInt aLayoutTransitionTime = 0);

   426 

   427     /**

   428      * Moves a child visual to the front of the other children. In other words

   429      * the visual is drawn last (on top of the other child visuals). In practise

   430      * this affects the order of the visuals whithin this layout so that the

   431      * visual is moved at the end of the list.

   432      *

   433      * Causes layout recalculation.

   434      *

   435      * @param aVisual  Child visual to move.

   436      * @see MoveVisualToBack()

   437      * @see Reorder()

   438      * @param aLayoutTransitionTime How long the transition should take visually, in milliseconds.     

   439      *

   440      * @see MoveVisualToFront() - Use this instead!

   441      */

   442     IMPORT_C void MoveVisualToFront(CHuiVisual& aVisual, TInt aLayoutTransitionTime = 0);

   443 

   444 

   445     /**

   446      * Moves a child visual behind the other children (in drawing order).

   447      * In other words the visual is drawn first (the other child visuals will

   448      * be drawn on top of this visual).

   449      *

   450      * In practise this affects the order

   451      * of the visuals whithin this layout so that the visual is moved at

   452      * the beginning of the list (ordinal 0).

   453      *

   454      * @param aVisual  Child visual to move.

   455      * @param aLayoutTransitionTime How long the transition should take visually, in milliseconds.     

   456      * @see MoveVisualToFront()

   457      * @see Reorder()

   458      */

   459     IMPORT_C void MoveVisualToBack(CHuiVisual& aVisual, TInt aLayoutTransitionTime = 0);

   460 

   461     /**

   462      * Notifies children of the change in the environment's skin.

   463      */

   464     IMPORT_C void NotifySkinChangedL();

   465 

   466     /**

   467      * Sets the transition time for the recalculation of this layout's

   468      * contents. This is used when a visual is added or removed or when

   469      * the order of the children is changed.

   470      *

   471      * You need to set the EHuiVisualFlagManualTransitionTime flag of this

   472      * visual before this setting has any effect. This flag overrides the

   473      * layout transition time hierarchy and uses a local value instead.

   474      *

   475      * @param aTransitionTime  Transition time in milliseconds.

   476      *

   477      * @see CHuiLayout::SetTransitionTime()     

   478      * @see CHuiVisual::SetFlag()     

   479      * @see EHuiVisualFlagManualTransitionTime

   480      */

   481     IMPORT_C void SetTransitionTime(TInt aTransitionTime);

   482 

   483     /**

   484      * Returns the transition time of this layout.

   485      *

   486      * @return  Transition time in milliseconds, or

   487      *          KHuiLayoutDefaultTransitionTime.

   488      *

   489      * @see CHuiLayout::SetTransitionTime()

   490      * @see CHuiVisual::SetFlag()     

   491      * @see EHuiVisualFlagManualTransitionTime     

   492      */

   493     IMPORT_C TInt TransitionTime() const;

   494 

   495     /**

   496      * Determines the layout ordinal for a child visual. The child's placement

   497      * depends on the ordinal number.

   498      *

   499      * @param aIndex  Index of the child visual.

   500      */

   501     IMPORT_C virtual TInt ChildOrdinal(TInt aIndex);

   502 

   503 	/**

   504 	 * From CHuiVisual. Prepares all children of this layout for 

   505 	 * drawing. The preparation is done in drawing 

   506 	 * order.

   507 	 * 

   508 	 * Actually this default implementation is not

   509 	 * leaving, since it traps the prepare errors

   510 	 * inside and handles the errors by calling

   511 	 * the visual owners "prepare draw failed" 

   512 	 * -callback.

   513 	 * 

   514 	 * @return ETrue if the prepare succeeded, or EFail if 

   515 	 * the prepare failed. Failing to prepare a draw 

   516 	 * terminates the screen refresh and drawing 

   517 	 * for the current frame.

   518 	 * 

   519 	 * @see MHuiVisualOwner::VisualPrepareDrawFailed()

   520 	 */

   521 	IMPORT_C TBool PrepareDrawL();	

   522     /**

   523      * From CHuiVisual. Draws (renders) this layout. 

   524      * 

   525      * The default implementataion applies transformations 

   526      * (affects the positions of the layout), draws brushes

   527      * and of course children.

   528      * 

   529      * Layout clipping is not affected by transformation.

   530      * 

   531      * @todo Clipping doesn't work if there is a transformation?

   532      * @todo No need to draw children that won't be visible.

   533      */

   534     IMPORT_C void Draw(CHuiGc& aGc) const;

   535 

   536     /**

   537      * From CHuiVisual. Called to inform the display that a dirty region has to be defined.

   538      *

   539      * Forward the notification request to all the child visuals.

   540      * Scrolling causes changed reports from the layout itself.

   541      */

   542     IMPORT_C void ReportChanged();

   543 

   544     /** From CHuiVisual */

   545     IMPORT_C void ClearChanged();

   546 

   547     /** From CHuiVisual */

   548     IMPORT_C TBool Changed() const;

   549 

   550     /** From CHuiVisual */

   551     IMPORT_C void DumpTree() const;

   552 

   553     /**

   554      * Defines the base unit used for positioning and sizing children

   555      * within this layout. For example, the actual X position of a child is 

   556      * determined by <tt>aBaseUnit.iX * childX</tt>. The effect of the 

   557      * base unit is limited to the children of this layout -- the 

   558      * grandchildren use the base units of their parents, not this base unit.

   559      * 

   560      * @note It is recommended to use EHuiUnitNormalized if proportional base units are 

   561      * required. For example, EHuiUnitRelativeToMySize would not make sense as a base 

   562      * unit.

   563      *

   564      * @param aMetric  Metric that will be used for both X and Y axes.

   565      */

   566     IMPORT_C void SetBaseUnit(const THuiMetric& aBaseUnit);

   567 

   568     /**

   569      * Defines the base unit used for positioning and sizing children

   570      * within this layout. For example, the actual X position of a child is 

   571      * determined by <tt>aBaseUnit.iX * childX</tt>. The effect of the 

   572      * base unit is limited to the children of this layout -- the 

   573      * grandchildren use the base units of their parents, not this base unit.

   574      * 

   575      * @param aMetric  Metric to use as the base unit.

   576      */

   577     IMPORT_C void SetBaseUnit(const THuiXYMetric& aBaseUnit);

   578     

   579     /**

   580      * Returns the layout's base measurement unit. The positions and sizes

   581      * of the children of this layout are interpreted as multiples of this

   582      * base unit.  For example, the actual X position of a child is 

   583      * determined by <tt>aBaseUnit.iX * childX</tt>. 

   584      *

   585      * The effect of the base unit is limited to the children of this layout 

   586      * -- the grandchildren use the base units of their parents, not this 

   587      * base unit.

   588      *

   589      * @note that if the visual flag @c EHuiVisualFlagAutomaticLocaleMirroringEnabled

   590      * is set, the value returned by this method will change based on the current platform

   591      * locale mirroring in the X-axis. So for example if the current layout is mirrored, then

   592      * the value returned by this method will have the X magnitude set to the negative

   593      * of the value that was set using @c SetBaseUnit.

   594      *

   595      * @return Metric used as the base unit for child coordinates and sizes.

   596      */

   597     IMPORT_C virtual THuiXYMetric BaseUnit() const;

   598 

   599 

   600     /** @endAPI */

   601 

   602 

   603     /**

   604      * Calculate the bounding rectangle for the layout. The rectangle is

   605      * calculated in the base units of the layout, i.e. it is calculated

   606      * using unconverted the child coordinates and sizes.

   607      *

   608      * @return  Bounding rectangle: the smallest rectangle inside which

   609      *          all the children of this layout can fit.

   610      */

   611     THuiRealRect BoundingRect() const;

   612 

   613     /**

   614      * Calculate the size of the inner area (bounds without outer padding).

   615      * The size is calculated in the base units of this layout, so that

   616      * children can be positioned within the layout based on this size.

   617      *

   618      * @return  Width and height of the inner area, in base units of 

   619      *          this layout.

   620      */

   621     IMPORT_C THuiRealSize InnerSize() const __SOFTFP;

   622     

   623     /**

   624      * Calculates the top left corner of the inner area (bounds without

   625      * outer padding). The point is calculated in the base units of this

   626      * layout, so that the children can be positioned within the layout

   627      * based on this point.

   628      *

   629      * @return  Top left corner point of the inner area, in base units

   630      *          of this layout.

   631      */

   632     IMPORT_C THuiRealPoint InnerTopLeft() const __SOFTFP; 

   633 

   634     /** @beginAPI */

   635 

   636     /**

   637      * New virtual method. Determines the size of a child visual according to the layout.

   638      * The child size is determined using the base units of the layout.

   639      * Derived layout classes should refer to InnerSize() and InnerTopLeft()

   640      * to determine the area suitable for placing children into.

   641      *

   642      * @param aOrdinal  Layout ordinal of the child visual.

   643      * @param aSize     New target size for the child. This goes to 

   644      *                  CHuiVisual::SetSize() with no conversions.

   645      *

   646      * @return  <code>ETrue</code>, if a new size was determined. Otherwise,

   647      *          <code>EFalse</code> is returned and no size changes are

   648      *          needed.

   649      */

   650     IMPORT_C virtual TBool ChildSize(TInt aOrdinal, TSize& aSize);

   651 

   652     /**

   653      * New virtual method. Determines the position of a child visual according to the layout.

   654      * The child position is determined using the base units of the layout.

   655      * Derived layout classes should refer to InnerSize() and InnerTopLeft()

   656      * to determine the area suitable for placing children into.

   657      *

   658      * @param aOrdinal  Layout ordinal of the child visual.

   659      * @param aPos      New position for the child. This goes to 

   660      *                  CHuiVisual::SetPos() with no conversions.

   661      *

   662      * @return  <code>ETrue</code>, if a new position was determined.

   663      *          Otherwise, <code>EFalse</code> is returned and no position

   664      *          changes are needed.

   665      */

   666     IMPORT_C virtual TBool ChildPos(TInt aOrdinal, TPoint& aPos);

   667 

   668 

   669     enum EHuiLayoutChildRect

   670         {

   671         THuiLayoutChildRectNotImplemented = -1,

   672         THuiLayoutChildRectUpdateNotNeeded = 0,

   673         THuiLayoutChildRectPosUpdateNeeded = 1,

   674         THuiLayoutChildRectSizeUpdateNeeded = 2,

   675         THuiLayoutChildRectLayoutUpdateNeeded = THuiLayoutChildRectPosUpdateNeeded | THuiLayoutChildRectSizeUpdateNeeded

   676         };

   677         

   678     /**

   679      * New virtual method.  Determines the position and size of a child visual according to the layout.

   680      * The child position is determined using the base units of the layout.

   681      * Derived layout classes should refer to InnerSize() and InnerTopLeft()

   682      * to determine the area suitable for placing children into.

   683      *

   684      * @param aOrdinal  Layout ordinal of the child visual.

   685      * @param aRect      New position for the child. This is used to set

   686      *                          the child size and position with no conversions.

   687      *

   688      * @return one of the values belonging to EHuiLayoutChildRect as follows:

   689      *      THuiLayoutChildRectNotImplemented -  method not implemented, ChildPos and ChildSize to be called as previously

   690      *      THuiLayoutChildRectUpdateNotNeeded - method is implemented, but aRect was not calculated; child pos/size are not modified

   691      *      THuiLayoutChildRectPosUpdateNeeded - method is implemented, but only iTl was calculated (pos)

   692      *      THuiLayoutChildRectSizeUpdateNeeded - method is implemented, but only size was calculated (iTl will be returned as 0)

   693      *      THuiLayoutChildRectLayoutUpdateNeeded - method is implemented and aRect was calculated

   694      *

   695      */

   696     IMPORT_C virtual TInt ChildRect(TInt aOrdinal, THuiRealRect& aRect);

   697 

   698 

   699     /** @endAPI */

   700 

   701 

   702 public: // From CHuiVisual. 

   703 

   704 

   705     IMPORT_C TReal32 BrushOpacity() const __SOFTFP;

   706 

   707     IMPORT_C THuiRealRect BrushRect() const __SOFTFP;

   708 

   709     IMPORT_C CHuiSkin& BrushSkin() const;

   710 

   711 protected:

   712      /**

   713      * From CHuiVisual. Overridden by subclasses to draw the content of the visual.

   714      * By default DrawSelf does not draw anything.

   715      */

   716     IMPORT_C void DrawSelf(CHuiGc& aGc, const TRect& aDisplayRect) const;

   717 

   718     /**

   719      * Calculate the metric reference for this layout, relative to this layout's 

   720      * base units.

   721      *

   722      * @param aLayout this parameter is no longer used, an alternative method is provided that does not take this parameter

   723      * @param aMetric the metric for which we need a reference value

   724      */

   725     IMPORT_C THuiRealPoint MetricReferenceForLayoutInPixels(const CHuiLayout* aLayout, const THuiXYMetric& aMetric) const __SOFTFP;

   726     IMPORT_C THuiRealPoint MetricReferenceForLayoutInPixels(const THuiXYMetric& aMetric) const __SOFTFP;

   727     

   728     IMPORT_C void ExpandRectWithContent(TRect& aRect) const;

   729 

   730     /** ! From HuiVisual */

   731     IMPORT_C void VisualExtension(const TUid& aExtensionUid, TAny** aExtensionParams);

   732 

   733     TBool EffectIsAppliedToChildren() const;

   734 

   735 public: // RnD utilities from CHuiVisual

   736     IMPORT_C void GetInstanceName(TDes& aName) const;

   737     IMPORT_C void GetClassName(TDes& aName) const;

   738     IMPORT_C TType Type() const;

   739     IMPORT_C TInt SessionId() const;

   740     IMPORT_C void SetSessionId(TInt aSessionId);

   741 

   742 private:

   743      

   744     TBool HasActiveChilderen() const;

   745     void DrawStoredBitmap(CHuiGc &aGc) const;

   746 protected:

   747     struct THuiLayoutPrivateData;

   748     THuiLayoutPrivateData* iHuiLayoutPrivateData; // owned

   749     };

   750 

   751 #endif  // __HUILAYOUT_H__