<class layout
  x_offset      =0=number
  y_offset      =0=number
  add_width_to_x_offset=false=boolean
  add_height_to_y_offset=false=boolean
  x_spacer      =0=number
  y_spacer      =0=number
  add_width_to_x_spacer=false=boolean
  add_height_to_y_spacer=false=boolean
  item_width    =100=number
  item_height   =100=number
  force_item_size=false=boolean
  origin_x      =opt=number
  origin_y      =opt=number
  _other_unkeyed=opt=wob=ekind.code="_add_to_environment"
/>

See also: biz, , menu

Introduction

The layout class is used to arrange items on a web page. Given a set of items as its vector fields, it arranges them in an order depending on the attribute values. The content of a layout is the set of objects which are to be arranged. These may consist of biz, ui_view, or hypertext objects, or any other object which can be represented in html. (Objects other than a biz or ui_view will be wrapped in a ui_view for purposes of positioning.) A layout may also contain other layouts.

The layout arranges hierarchies as well as flat lists of items: when presented with a hierarchical set of items to arrange, it will first arrange an item, then arrange its children recursively, then return to arrange the next item on the level of the parent. This is accomplished by using an additional layout object which arranges the children, which is called by the layout of the parent. Thus, complex arrangements may be created by using a different subclass of layout for the children than the parent. A typical use case for layout of hierarchical content would be items in a menu.

Usage Examples

Example 1: Defaults

The layout class assumes that the programmer will provide sufficient input to generate a useful result, but doesn't require any attributes:

<layout>
  <p>One</p>
  <p>Two</p>
  <p>Three</p>
</layout>

Technically, this will generate valid HTML. However, what it will actually do is lay out the three paragraphs on top of each other and shove them in the upper left corner of the page. (It isn't pretty.) In order to get useful functionality, the layout must have an origin, and some properties that cause it to make things not appear on top of each other.

Example 2: Rows

If we want to arrange these three items in a row, we could specify that we want to add the width of the items to the x_spacer, which is the space between objects horizontally. This would cause each object to be positioned to the right of its predecessor, as follows:

<layout add_width_to_x_spacer=true>
  <p>One</p>
  <p>Two</p>
  <p>Three</p>
</layout>

An easier method for doing this would be to use the row subclass:

layout.<row>
  <p>One</p>
  <p>Two</p>
  <p>Three</p>
</row>

This would yield the same result. Indeed, all the row subclass does is set different default values for the standard layout engine.

Example 3: Columns

If we want to arrange these three items in a column, we could specify that we want to add the height of the items to the y_spacer, which is the space between objects vertically. This would cause each object to be positioned below its predecessor, as follows:

<layout add_height_to_y_spacer=true>
  <p>One</p>
  <p>Two</p>
  <p>Three</p>
</layout>

One

Two

three

An easier method for doing this would be to use the column subclass:

layout.<column>
  <p>One</p>
  <p>Two</p>
  <p>Three</p>
</column>

As before, this would yield the same result.

Using Layouts With Biz Objects

Objects of class biz accept an optional layout as their _layout attribute. The biz object contains method <arrange/> which synchronizes the content of the biz object with the content of its layout object, and then calls the <arrange/> method on its layout object. See the biz documentation for further details.

Example 4: A biz.menu Layout

biz.<menu _layout=layout.<row/> >
  biz.<menu_item label="A1" task=<echo "You clicked A1"/> > 
    biz.<menu_item label="B1" task=<echo "You clicked B1"/> /> 
    biz.<menu_item label="B2" task=<echo "You clicked B2"/> >
      biz.<menu_item label="C1" task=<echo "You clicked C1"/>  />
    </menu_item>
    biz.<menu_item label="B3" task=<echo "You clicked B3"/> />
  </menu_item>
  biz.<menu_item label="A2" task=<echo "You clicked A2"/> />
</menu>

Related documentation

Origin

Items are arranged in order from first to last in the order in which they are listed in the vector keys, so the first item listed will appear in the upper left. The origin is the x,y location on the page at which the upper left corner of the arranged items will appear.

The origin can be set manually using the origin_x and origin_y attributes. However, this isn't always necessary. If the first item (.0) of an instance of layout is a ui_view or a biz, and it has an x,y location already, the layout will use that x,y if origin_x and origin_y are not set. (If they are set, .0 will not be searched for coordinates.) Also, this may be overriden by passing origin_x and origin_y attributes to the arrange method.

a wob

Parameter key	Default value	Type
origin_x	opt	number

The x coordinate of the layout's origin, if desired.

a wob

Parameter key	Default value	Type
origin_y	opt	number

The y coordinate of the layout's origin, if desired.

Setting Width and Height

Width and height are required for the items to be arranged. Because of this, if an item to be arranged does not have width and height, they will be set for it. If the item does not have a container such as a ui_view object to contain its width and height, one will be created for it. You may also optionally force all arranged objects to have the same size.

a wob

Parameter key	Default value	Type
item_width	100	number

This is the width which will be used for items which don't have one, or if you set force_item_size to true.

a wob

Parameter key	Default value	Type
item_height	100	number

This is the height which will be used for items which don't have one, or if you set force_item_size to true.

a wob

Parameter key	Default value	Type
force_item_size	false	boolean

If this is true, all items will be set to have width and height as specified in item_width and item_height.

Arranging Peers

When the layout arranges its objects, it places the first object at the origin x,y, and each successive object's location is determined in relation to the location of its predecessor.

a wob

Parameter key	Default value	Type
x_spacer	0	number

Sets the number of pixels which will be added to the x coordinate of an object when determining the location of its successive peer. Thus, if arranging objects A and B, object A is at x coordinate 100, and x_spacer is 5, object B's x coordinate would be 105.

a wob

Parameter key	Default value	Type
y_spacer	0	number

Sets the number of pixels which will be added to the y coordinate of an object when determining the location of its successive peer. Thus, if arranging objects A and B, object A is at y coordinate 100, and y_spacer is 5, object B's y coordinate would be 105.

a wob

Parameter key	Default value	Type
add_width_to_x_spacer	false	boolean

Setting this to true causes the width of an object to be added to its X coordinate and the x_spacer when determining the location of its successive peer. In other words, it makes successive objects appear to the right of the previous. Thus, if arranging objects A and B, object A is at x coordinate 100 and has width 30, and x_spacer is 5, object B's x coordinate would be 135.

a wob

Parameter key	Default value	Type
add_height_to_y_spacer	false	boolean

Setting this to true causes the height of an object to be added to its Y coordinate and the y_spacer when determining the location of its successive peer. In other words, it makes successive objects appear below the previous. Thus, if arranging objects A and B, object A is at y coordinate 100 and has height 30, and y_spacer is 5, object B's y coordinate would be 135.

Arranging Children

When the layout prepares to arrange child objects, it determines the origin of the child set in relation to the parent object of the child set. For example, if a layout is arranging objects A, B, and C, and item B has two children B1 and B2, when the layout of A, B, and C attempts to call the layout of B1 and B2 to arrange them, the origin of the layout of B1 and B2 will be determined as an offset from the x,y coordinates of B.

a wob

Parameter key	Default value	Type
x_offset	0	number

Sets the number of pixels which will be added to the x coordinate of the parent object when passing this location to the layout of the child objects as its origin. For example, if this is 5, then the child objects will be arranged with an origin that is 5 pixels below the x coordinate of the parent object.

a wob

Parameter key	Default value	Type
y_offset	0	number

Sets the number of pixels which will be added to the x coordinate of the parent object when passing this location to the layout of the child objects as its origin.

a wob

Parameter key	Default value	Type
add_width_to_x_offset	false	boolean

Setting this to true causes the width of the parent object to be added to the x coordinate of the parent object and the x_offset when passing this location to the layout of the child objects as its origin. In other words, this makes child objects appear to the right of their parent object. For example, if the x coordiante of the parent object is 100, the width of the parent object is 50, the x_offset is 5, and add_width_to_x_offset is true, then the origin_x that will be passed to the child objects' layout will be 155: that is, five pixels to the right of the right side of the parent object.

a wob

Parameter key	Default value	Type
add_height_to_y_offset	false	boolean

Setting this to true causes the height of the parent object to be added to the y coordinate of the parent object and the y_offset when passing this location to the layout of the child objects as its origin. In other words, this makes child objects appear below their parent object. For example, if the y coordiante of the parent object is 100, the height of the parent object is 50, the y_offset is 5, and add_height_to_y_offset is true, then the origin_y that will be passed to the child objects' layout will be 155: that is, five pixels below the bottom of the parent object.

© Copyright 2007 Clear Methods, Inc.