Layout Terminology

From Adobe Open Source Wiki
Revision as of 18:00, 2 April 2007 by FosterBrereton (Talk | contribs)

Jump to: navigation, search

This is the layout behavior specifications for the default set of ASL widgets. 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)

Contents

CEL Primer

Values expressed in this document are specified using the Common Expression Language (CEL). Here is a quick overview of the types available in the CEL and how they are formatted:

Integer or Float
Stored as double. Format is simply the number
e.g., 42 or 19.2
String
Stored as a std::string. Format is a sequence of characters encase in single- or double-quotes.
e.g., "string" or 'string'
Identifier
Stored as an adobe::name_t. Format is a sequence of characters prepended with '@'.
e.g., @width or @forty_two
Enumeration
Stored as an enumeration. Predefined constants specified on a per-context basis. Format is the enumeration verbatim in the declaration.
e.g., align_fill or place_column
Boolean
Stored as a bool. Either true or false.
Array
Stored as an adobe::array_t. A homogeneous, sequential collection of values wrapped in braces.
e.g. [ 1, 2, 3 ] or [ @first_item, "second item", 3.14, 'fourth item' ]
Dictionary
Stored as an adobe::dictionary_t. A collection of associated key-value pairs wrapped in brackets. The keys are always of type Identifier (adobe::name_t), though they are not prepended with the '@' (it is implied).
e.g, { name: @value, name2: "second value" } or { spacing: 42, placement: place_overlay, name: "My Dictionary" }
Regular
Stored as an adobe::any_regular_t. A runtime-polymorphic type that can be any regular type under the hood. This includes every basic type listed here.

Associated Structures

These data structures are used by some of the widgets described below. They are available as utility structures to any widget that would like to use them. Note that a widget is not required to use all portions of a structure; it may use just what it requires.

unit_t

unit_t stores attributes pertaining to a specific numerical unit. An example of a numerical unit may be inches or degrees Celsius. Each of the values in this dictionary can be interpreted by the implementation of a widget as the widget sees fit. unit_t is described in CEL as a dictionary, and can have the following keys:

Attributes

name
type: string
default: ""
The visually displayed name of the unit
bind
type: identifier
default: name_t()
Distinguishes the common underlying unit for this unit. An example of this would be lengths displayed in inches, centimeters, mm, picas, etc. Though they are different units they all, by linear transformation (see #scale), devolve to a base unit which the user can choose. This identifier is used to group different units together that have the same base unit. This allows for a single collection of units to describe values in different bases (For example, bases of unit length and unit percent.)
format
type: string
default: "#"
Specifies the numeric formatting for this unit. Allows for printf-like formatting for the result of the transformation. Examples "#" (integer values), "#.00" (double-precision floating point values).
increment
type: number
default: 1
The amount this value is to change when the user 'bumps' it (e.g., by scrolling the scroll wheel or using the arrow keys on the keyboard.)
min_value
type: number
default: std::numeric_limits<double>::min()
The lower bound that numbers in this particular unit are allowed to attain. The default value is intended to imply ignoring the value.
max_value
type: number
default: std::numeric_limits<double>::max()
The upper bound that numbers in this particular unit are allowed to attain. The default value is intended to imply ignoring the value.
scale
type: array of two numbers
default: [ 1, 0 ] (identity transformation)
This is the linear transformation used to go from this-unit to the base-unit. The first number is the slope of the linear transformation (m). The second number is the y-intercept of the transformation (b). A default of [ 1, 0 ] results in an identity transformation for the unit values.

Examples in CEL 

units: [
    { name: "fahrenheit", bind: @celsius, scale: [ 1.8, 32 ] },
    { name: "celsius", bind: @celsius },
    { name: "kelvin", bind: @celsius, scale: [ 1, 273.15 ]  }
]

units: [
    { name: 'percent', bind: @width_percent, format: "#.00" },
    { name: 'inches', bind: @width_inches, format: "#.000" },
    { name: 'cm', bind: @width_inches, scale: [ 2.54, 0 ], format: "#.00" },
    { name: 'mm', bind: @width_inches, scale: [ 25.4, 0 ], format: "#.0" },
    { name: 'points', bind: @width_inches, scale: [ 72, 0 ], format: "#.0" },
    { name: 'picas', bind: @width_inches, scale: [ 6, 0 ], format: "#.00" },
    { name: 'columns', bind: @width_inches, scale: [ 1, 0 ], format: "#.000" }
]

General Layout Attributes

The layout engine ("Eve") does not know the difference between a widget destined to be a container (e.g., a window or a panel) versus one that is a leaf node (e.g., a button or a label). To the layout engine everything is a "box" with various attributes. In theory, then, all of the general attributes below could pertain to all of the widgets. Of course, this is nonsensical in some cases (e.g., spacing for a label), but the layout engine does not care, because it does not know that a "label" is a leaf widget any more than it knows a "group" is not (though it actually may be if it has no children). From an implementation standpoint, all nodes in the layout hierarchy have all these attributes, even if some are never used (or make no sense).

Default values in this section are suggestions of sorts. It is possible (and entirely likely) that the layout semantics of various widgets will require a different default for an attribute. For example, the default horizontal alignment of a container is align_default, but that value is changed to align_fill in the case of a panel widget. Overrides of this nature are explicitly iterated in the section on #Widget-Specific Layout Attributes under "Layout Attribute Defaults".

  • 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.

Widget-Specific Layout Attributes

Containers

A container is a widget-context term: as previously mentioned, it really has no meaning as far as the layout engine is concerned. That being said, it is very helpful as a user interface designer to separate those widgets intending to contain child widgets from those that are meant to be leaf nodes. No container should be required to have any children, though for some of them it would be a poor UI decision to do so (e.g., a tab_group with no child panels would not be much of a tab group.)

group

Layout Attribute Defaults
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
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
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
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
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.

Non-Creating Containers

Non-creating containers are unique from regular containers in that they produce no platform-specific widget upon time of creation. They are legitimate nodes in the layout engine tree, and can contain other nodes and be contained themselves. However, when the time comes to create the widgets within the layout, these elements propagate information up and down the layout, but do nothing in and of themselves.

By implication, calling adobe::measure and adobe::place for these "widgets" are no-ops.

row

Layout Attribute Defaults
Additional Attributes

none.

column

Layout Attribute Defaults
Additional Attributes

none.

overlay

Layout Attribute Defaults
Additional Attributes

none.

Leaf Widgets

button

checkbox

(Note: move this to the semantics doc) Checkboxes are not boolean (flag) widgets. There is a third, undetermined state for a checkbox, which is commonly seen as a dash running through the middle of the checkbox itself. When the value of the cell to which the checkbox is bound matches neither value_on or value_off, the checkbox should be seen in this third, undetermined state.

Layout Attribute Defaults

no changes.

Additional Attributes
name
type: string
default: ""
The name of the widget.
alt_text
type: string
default: ""
The text to be used for the widget's tooltip
value_on
type: regular
default: true
When the value of the cell to which this widget is bound changes to this value, the checkbox is checked.
value_off
type: regular
default: false
When the value of the cell to which this widget is bound changes to this value, the checkbox is unchecked.

display_number

Note: There is a design flaw with the display_number implementation. It would be nice if the user were not required to specify a unit array for the display_number, but a problem arises in that the one and only unit thus created will use the name parameter for the display_number as the unit's name. This will cause a duplication of the name of the widget as the unit's label itself, for example: Inches: 5 Inches:

Layout Attribute Defaults

no changes.

Additional Attributes
name
type: string
default: ""
The name of the widget.
alt_text
type: string
default: ""
The text to be used for the widget's tooltip
characters
type: integer
default: 5
Used to specify the approximate width of the numeric value of the display_number widget. Added to this value are the length of the widget label and the width of the longest unit label.
units
type: array of dictionaries
default: [ ]
Describes the units to be used when formatting the number coming in from the property model. This array should contain a collection of unit_t dictionaries; please see the #unit_t documentation for parameter information. Note that display_number collects defaults for all unit values from the parameter set for the widget itself. For example, if format is defined as a parameter to this widget and is not otherwise specified by a unit, the unit will use the value found in the format parameter as its format value. This avoids unnecessary description duplication.
Examples in CEL 
display_number(name: "File Size:", bind: @bytes, format: "#.##",
               units: [
                   { name: "bytes", format: "#", scale: [ 1, 0 ] },
                   { name: "KB", format: "#.###", scale: [ 1024, 0 ] },
                   { name: "MB", scale: [ 1024 * 1024, 0 ] },
                   { name: "GB", scale: [ 1024 * 1024 * 1024, 0 ]  },
                   { name: "TB", scale: [ 1024 * 1024 * 1024 * 1024, 0 ]  }
               ]);

edit_number

Layout Attribute Defaults

no changes.

Additional Attributes
name
type: string
default: ""
The name of the widget.
alt_text
type: string
default: ""
The text to be used for the widget's tooltip
digits
type: integer
default: 10
Used to specify the approximate width of the numeric value (the edit text portion) of this widget.
max_digits
type: integer
default: 0 (implying unlimited length)
Used to specify the maximum digits allowed for the numeric value (the edit text portion) of this widget.
units
type: array of dictionaries
default: [ ]
Describes the units to be used when formatting the number coming in from the property model. This array should contain a collection of unit_t dictionaries; please see the #unit_t documentation for parameter information. Note that edit_number collects defaults for all unit values from the parameter set for the widget itself. For example, if format is defined as a parameter to this widget and is not otherwise specified by a unit, the unit will use the value found in the format parameter as its format value. This avoids unnecessary description duplication.

edit_text

image

label

link

list

panel

popup

presets

progress_bar

radio_button

reveal

separator

slider

Retrieved from "http://stlab.adobe.com/wiki/index.php?title=Layout_Terminology&oldid=1910"
Personal tools
Namespaces

Variants
Actions
Wiki Navigation
Support
Toolbox