Layout Terminology
From Adobe Open Source Wiki
(Difference between revisions)
| Line 5: | Line 5: | ||
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 <code>value</code>) | 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 <code>value</code>) | ||
| − | == | + | == 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 layout attributes can be found in <adobe/layout_attributes.hpp>. | ||
| Line 150: | Line 144: | ||
: 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. | : 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 | + | == Widget-Specific Layout Attributes == |
=== Containers === | === 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 ==== | ==== group ==== | ||
| Line 255: | Line 251: | ||
: Whether or not this window shows up in the 'brushed metal' look | : 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. | : ''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 ===== | ||
| + | |||
| + | * [[#placement|placement]]: place_row | ||
| + | * [[#create|create]]: false | ||
| + | |||
| + | ===== Additional Attributes ===== | ||
| + | |||
| + | none. | ||
| + | |||
| + | ==== column ==== | ||
| + | |||
| + | ===== Layout Attribute Defaults ===== | ||
| + | |||
| + | * [[#placement|placement]]: place_column | ||
| + | * [[#create|create]]: false | ||
| + | |||
| + | ===== Additional Attributes ===== | ||
| + | |||
| + | none. | ||
| + | |||
| + | ==== overlay ==== | ||
| + | |||
| + | ===== Layout Attribute Defaults ===== | ||
| + | |||
| + | * [[#placement|placement]]: place_overlay | ||
| + | * [[#create|create]]: false | ||
| + | |||
| + | ===== Additional Attributes ===== | ||
| + | |||
| + | none. | ||
=== Leaf Widgets === | === Leaf Widgets === | ||
Revision as of 23:32, 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)
Contents |
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
- 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
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.
