The layout! proc-macro

The layout! proc-macro is used to create a layout from a string. The string describes a layout rule that base on the following format:

"parameter:value , parameter:value , ... parameter:value"

or

"parameter=value , parameter=value , ... parameter=value"

Where parameter refects the following LayoutBuilder method and can be one of the following:

ParameterAlias
(short)		LayoutBuilder
method		Value typeDescription
x.x(...)numerical or percentage"X" coordonate
y.y(...)numerical or percentage"Y" coordonate
leftl.left_anchor(...)numerical or percentageleft anchor for the control
(the space between parent left margin and control)
rightr.right_anchor(...)numerical or percentageright anchor for the control
(the space between parent right margin and control)
topt.top_anchor(...)numerical or percentagetop anchor for the control
(the space between parent top margin and control)
bottomb.bottom_anchor(...)numerical or percentagebottom anchor for the control
(the space between parent bottom margin and control)
widthw.width(...)numerical or percentagethe width of the control
heighth.height(...)numerical or percentagethe height of the control
dockd.dock(...)docking valuethe way the entire control is docked on its parent
aligna.alignment(...)alignment valuethe way the entire control is aligned against the margins of its parent
pivotp.pivot(...)pivoting directionthe way the entire control is aligned against the point represented by (x,y) - the pivot

Remarks

  • Key aliases can be use to provide a shorter format for a layout. In other words, the following two formats are identical: width:30,height:30 and w:30,h:30
  • A numerical value is represented by an integer (positive and negative) number between -30000 and 30000. Example: x:100 --> X will be 100. Using a value outside accepted interval ([-30000..30000]) will reject the layout.
  • A percentage value is represented by a floating value (positive and negative) succeded by the character % between -300% and 300%. Example: x:12.75% --> X will be converted to a numerical value that is equal to the width of its parent multiplied by 0.1275. Using a value outside accepted interval ([-300%..300%]) will reject the layout. Percentage values can be use to ensure that if a parent size is changed, its children change their size with it.
  • All layout parameters are case insensitive (meaning that 'left=10' and 'LEFT=10' have the same meaning)

Dock values

Dock values can be one of the following:

ValueAliasEnum variantDescription
leftlDock::LeftThe control is docked at the left edge of its parent. The width parameter is required.
rightrDock::RightThe control is docked at the right edge of its parent. The width parameter is required.
toptDock::TopThe control is docked at the top edge of its parent. The height parameter is required.
bottombDock::BottomThe control is docked at the bottom edge of its parent. The height parameter is required.
fillfDock::FillThe control fills the entire space of its parent.

Remarks:

  • Dock value aliases can be use to provide a shorter format for a layout. In other words: dock:left is the same with dock:l or d:l

Examples

  1. Dock the control at the left edge of its parent and set its width to 10:

    layout!("dock:left, width:10")

    or

    layout!("d:l, w:10")

    or (via LayoutBuilder method)

    LayoutBuilder::new().dock(Dock::Left).width(10).build()

  2. Dock the control at the bottom edge of its parent and set its height to 20:

    layout!("dock:bottom, height:20")

    or

    layout!("d:b, h:20")

    or (via LayoutBuilder method)

    LayoutBuilder::new().dock(Dock::Bottom).height(20).build()

  3. Fill the entire space of its parent:

    layout!("dock:fill")

    or

    layout!("d:f")

    or (via LayoutBuilder method)

    LayoutBuilder::new().dock(Dock::Fill).build()

    or (via Layout structure)

    Layout::fill()

Align values

Alt text for image
ValueAlias
topleftlefttop, tl, lt, top-left
topcentert, tc, ct, top-center
toprightrighttop, tr, rt, top-right
centerrightr, cr, rc, center-right
bottomrightrightbottom, br, rb, bottom-right
bottomcenterb, bc, cb, bottom-center
bottomleftleftbottom, lb, bl, bottom-left
centerleftl, cl, lc, center-left
centerc

Remarks:

  • Align value aliases can be use to provide a shorter format for a layout. In other words: dock:topleft is the same with align:tl or align:lt or a:tl

Pivot values

Pivot values have the same name as the align values, but they refer to the direction of width and height from a specific point (denoted by "X" and "Y" parameters). Pivot parameter is used to compute top-left and bottom-right corner of a control that is described using a (X,Y) point and a size (width, height). The following table ilustrate how this values are computed:

ValueAliasTop-Left cornerBottom-Right corner
top-leftlefttop, tl, lt(x,y)(x+width,y+height)
top-centertop, t(x-width/2,y)(x+width/2,y+height)
top-rightrighttop, tr, rt(x-width,y)(x,y+height)
center-rightright, r(x-width,y-height/2)(x,y+height/2)
bottom-rightrightbottom, br, rb(x-width,y-height)(x,y)
bottom-centerbottom, b(x-width/2,y-height)(x+width/2,y)
bottom-leftleftbottom, lb, bl(x,y-height)(x+width,y)
center-leftleft, l(x,y-height/2)(x+width,y+height/2)
centercenter, c(x-width/2,y-height/2)(x+width/2,y+height/2)

Remarks:

  • Align value aliases can be use to provide a shorter format for a layout. In other words: align:center is the same with align:c or a:c