Layout Terminology

Revision as of 20:54, 30 March 2007

This is the layout behavior specifications for the default set of ASL widgets. Default values are specified using the Common Expression Language (CEL). As such:

• Arrays are defined as [ 1, 2, 3 ].
• Dictionaries are defined as { name: value, name2: value2 }

This documentation does not cover the attributes related to the binding of a widget to a property model (bind, bind_out, etc.). This document only deals with the layout behavior of a widget, not its semantics as they pertain to a model/view/controller system. The document will, however, describe some attributes that, while not necessary for layout, are necessary to construct the widget (e.g., optional_panel's value)

Related Structures

Layout Unit

tbd

Interval Range

tbd

General Layout Attributes

• Code for the layout attributes can be found in <adobe/layout_attributes.hpp>.
• Code for the extents can be found in <adobe/extents.hpp>.

Layout Attributes

indent

type: integer

default: 0

The amount of space between the leftmost (or topmost) widget and the end of the left (or top) margin, in pixels.

create

type: boolean

default: true

Determines whether or not this node actually creates a widget using a platform widget implementation. Examples of noncreating containers are row, column, and overlay. This attribute is not settable from within the layout description.

spacing

type: integer or array

default: 10

The amount of space to be put between multiple children of the container. This value can also contain an array, which will be iterated in turn to determine the spacing between two child widgets. Example: spacing: [ 5, 10, 15 ] will yield a container with 5 pixels between child widget 1 and 2, 10 pixels between child widget 2 and 3, and so forth.

placement

type: enumeration

default: place_leaf

The placement of a container's children. Options are:

place_row 

Align the children in a row

place_column 

Align the children in a column

place_overlay 

Align the children in an overlay. An overlay will cause all children to have horizontal and vertical alignments of align_fill. Each child will share the same layout real estate with its siblings. The idea for an container placing its children using place_overlay is so that only one will be visible at a time.

question : What does place_leaf do?

margin

type: integer or array

default: [ 0, 0, 0, 0 ]

margin is the amount of space from the frame of the container to the children within. The margins of a container can only be encroached upon by the outset of a child widget. A child widget's outset is not allowed to be larger than its container's margin (implying the outset of the child would extend into and possibly beyond the frame of the container.) If the container has no margin, then the outset of the child widgets will propagate to become the outsets of the parent container. If this attribute is specified using a single value (e.g., margin: 20) it implies the value should be used for all the container's margins.

horizontal

type: enumeration

default: align_default

Specifies horizontal alignment of the widget. Options are:

align_forward 

Forward alignment

align_reverse 

Reverse alignment

align_center 

Center alignment

align_proportional 

Distributes leftover container space equally among widgets with this alignment specified (todo: verify)

align_forward_fill 

Distributes leftover container space completely to widgets with this alignment specified (todo: verify)

align_reverse_fill 

Distributes leftover container space completely to widgets with this alignment specified (todo: verify)

align_default 

Aligns items from left-to-right in the case of a container with placement place_row, and top-to-bottom in the case of a container with placement place_column.

align_fill 

same as align_forward_fill

align_left_fill 

same as align_forward_fill

align_right_fill 

same as align_reverse_fill

align_top_fill 

same as align_forward_fill

align_bottom_fill 

same as align_reverse_fill

align_left 

same as align_forward

align_right 

same as align_reverse

align_top 

same as align_forward

align_bottom 

same as align_reverse

vertical

type: enumeration

default: align_default

Specifies vertical alignment of the widget. Options are the same as the horizontal attribute.

child_horizontal

type: enumeration

default: align_default

Unless otherwise specified by the child widget itself, this specifies the horizontal alignment of the children of this widget. Options are the same as the horizontal attribute.

child_vertical

type: enumeration

default: align_default

Unless otherwise specified by the child widget itself, this specifies the vetical alignment of the children of this widget. Options are the same as the horizontal attribute.

guide_mask

type: array of enumerations

default: [ ]

guides to suppress - current valid values are:

• guide_baseline
• guide_label

size

type: enumeration

default: size_normal

Specifies the size of the widget. Valid values are:

size_mini 

For palettes

size_small 

For palettes and dialogs (in rare cases)

size_normal 

For dialogs

Widget Extents

outset

type: array

default: [ 0, 0, 0, 0 ]

frame

type: array

default: [ 0, 0, 0, 0 ]

inset

type: array

default: [ 0, 0, 0, 0 ]

guide_set

type: array

default: [ ]

(not settable in the layout description)

width

type: integer

default: 0

Specifies the minimum width requirement for this widget

It is not advised to set this value within a layout description. Instead, allow the widget to obtain its own minimum extents requirements from adobe::measure.

height

type: integer

default: 0

Specifies the minimum height requirement for this widget

It is not advised to set this value within a layout description. Instead, allow the widget to obtain its own minimum extents requirements from adobe::measure.

Specific Layout Attributes (by widget)

Containers

group

Layout Attribute Defaults

• placement: place_column
• margin: 10

Additional Attributes

name

type: string

default: ""

Specifies the label to be put at the top of the group frame

alt_text

type: string

default : ""

Specifies the tooltip text for the widget

optional_panel

Layout Attribute Defaults

• placement: place_column
• horizontal: align_fill
• vertical: align_fill
• guide_mask: [ guide_baseline ]

Additional Attributes

value

type: regular

default: any_regular_t()

When the bound cell is set to this value, the optional panel becomes visible

panel

Layout Attribute Defaults

• placement: place_column
• horizontal: align_fill
• vertical: align_fill
• guide_mask: [ guide_baseline ]

Additional Attributes

value

type: regular

default: any_regular_t()

When the bound cell is set to this value, the optional panel becomes visible

tab_group

Layout Attribute Defaults

• placement: place_overlay
• guide_mask: [ ]
• margin: 10

Additional Attributes

items

type: array of dictionaries

default: [ ]

Describes the tabs of the tab group. Each tab is described using a dictionary with the following keys:

name

type: string

default: ""

The visually displayed name of the tab

value

type: regular

default: any_regular_t()

When the bound cell to the tab group is set to this value, this particular tab becomes selected. Note that this does not hide/show the children of the tab group explicitly. Rather, in order to hide/show children properly, they must be contained within a panel bound to the same cell, and revealing itself by the same regular value.

window

Layout Attribute Defaults

• placement: place_row
• margin: 10
• spacing: 20

Additional Attributes

name

type: string

default: ""

The name of the window to be shown in the its title bar

grow

type: bool

default: false

Whether or not this window should have a grow box and is resizeable

metal

type: bool

default: false

Whether or not this window shows up in the 'brushed metal' look

Note: This is for Mac OS X only; other OSes ignore this value.

Leaf Widgets

button

checkbox

display_number

edit_number

edit_text

image

label

link

list

panel

popup

presets

progress_bar

radio_button

reveal

separator

slider