Difference between revisions of "Layout Terminology"

From Adobe Open Source Wiki
Jump to: navigation, search
Line 2: Line 2:
 
* Arrays are defined as [ 1, 2, 3 ].
 
* Arrays are defined as [ 1, 2, 3 ].
 
* Dictionaries are defined as { name: value, name2: value2 }
 
* 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 <code>value</code>)
  
 
== Related Structures ==
 
== Related Structures ==
Line 153: Line 155:
  
 
=== group ===
 
=== group ===
 
* MVC type: view
 
  
 
==== Layout Attribute Defaults ====
 
==== Layout Attribute Defaults ====
Line 174: Line 174:
  
 
=== optional_panel ===
 
=== optional_panel ===
 
* MVC type: View
 
  
 
==== Layout Attribute Defaults ====
 
==== Layout Attribute Defaults ====
Line 185: Line 183:
  
 
==== Additional Attributes ====
 
==== Additional Attributes ====
 
; bind
 
: type: name
 
: default: name_t()
 
: Name of cell in property model to which this widget is bound.
 
  
 
; value
 
; value
 
: type: regular
 
: type: regular
 
: default: any_regular_t()
 
: default: any_regular_t()
: When bound cell is set to this value, the optional panel becomes visible
+
: When the bound cell is set to this value, the optional panel becomes visible
  
 
=== panel ===
 
=== 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 ===
 
=== 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 ===
 
=== 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 ==
 
== Leaf Widgets ==

Revision as of 20:47, 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

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