Difference between revisions of "Layout Terminology"

From Adobe Open Source Wiki
Jump to: navigation, search
(predefined constants)
(predefined constants)
Line 46: Line 46:
 
: The type system for CEL is open. Values are stored in an adobe::any_regular_t which can hold any regular type. Client functions can be introduced that return values of types other than those listed and other functions may process those value.
 
: The type system for CEL is open. Values are stored in an adobe::any_regular_t which can hold any regular type. Client functions can be introduced that return values of types other than those listed and other functions may process those value.
  
=== predefined constants ===
+
=== Predefined Constants ===
 
: There are a number of predefined constants in the layout library - unless otherwise specified the value of the constant is not defined:
 
: There are a number of predefined constants in the layout library - unless otherwise specified the value of the constant is not defined:
 
* align_left
 
* align_left

Revision as of 17:10, 10 December 2008

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). For a more thorough introduction to the common expression language please visit the CEL expression reference documentation. Here is a quick overview of the types available in the CEL and how they are formatted:

empty

a nil-like value. Intended to mean nothing.
e.g., { my_brain: empty }

integer

see number.

float

see number.

number

Stored as double. Format is simply the number
e.g., 42 or 19.2

string

Stored as an adobe::string_t. Format is a sequence of characters encase in single- or double-quotes.
e.g., "string" or 'string'.
Strings placed together concat into a single string.
e.g., "this" 'is' "one" "'string'"
is the same as "this is one 'string'"

name

Stored as an adobe::name_t. Format is a sequence of letters, digits, and '_' prepended with '@'.
e.g., @width or @forty_two

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" }

Other Types

The type system for CEL is open. Values are stored in an adobe::any_regular_t which can hold any regular type. Client functions can be introduced that return values of types other than those listed and other functions may process those value.

Predefined Constants

There are a number of predefined constants in the layout library - unless otherwise specified the value of the constant is not defined:
  • align_left
  • align_right
  • align_center
  • place_row
  • place_column
  • place_overview

The following constants should be defined with values based upon their context within a layout. For example, the value of space_normal should be less inside of a palette or message box then inside of a dialog.

  • space_grouped
  • space_normal
  • space_unrelated

The value of space_grouped should match the spacing defined within the widget set between a widget label and field. For example:

row(spacing: space_grouped) {
    static_text(name: "Label:"); edit_text();
}

should appear identical to:

edit_text(name: "Label:");

[ The space_ variables are not currently defined in the Begin application. ]

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: name
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, below), 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: float
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: float
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: float
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 floats
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" }
]

value_range_format_t

This is a simple filter for limiting a value to one within a range of values. The general notion of a filter should describe a set of valid values (potentially infinite - such as all positive numbers).

Attributes

first
type: float
default: 0
Specifies the first value this range can have
last
type: float
default: 0
Specifies the last value this range can have
interval
type: float
default: 0
Specifies the increment/decrement count to get between first and last. In ASL widget implementations if this value is omitted it will default to last - first (which is actually pretty useless).

Examples in CEL

format: { first: 0, last: 100, interval_count: 50 }

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

Generally the widget extents are not settable through a layout description - but instead are obtained by a call to the widget with the attributes supplied by the description. The terminology is documented here so that in cases where it does make sense to expose through a layout description it is done so consistently.

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: [ ]

width

type: integer
default: 0
Specifies the minimum width requirement for this widget

height

type: integer
default: 0
Specifies the minimum height requirement for this widget

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
type: string
default : ""
Specifies the tooltip text for the widget
Examples in CEL
group(placement: place_row, name: "Horizontal Checkboxes", child_horizontal: align_fill)
{
    // ...
}

optional

Layout Attribute Defaults
Additional Attributes
value
type: regular
default: empty
When the bound cell is set to this value, the optional panel becomes visible
Examples in CEL
optional(bind: @valid_bounds, value: false)
{
    static_text(name: "Error: The image dimensions you have specified are invalid. Please correct
                them", characters: 10);
}

panel

Layout Attribute Defaults
Additional Attributes
value
type: regular
default: empty
When the bound cell is set to this value, the optional panel becomes visible
Examples in CEL
panel(bind: @colorMode, value: @labColorMode, horizontal: align_fill)
{
    // ...
}

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: empty
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.
Examples in CEL
tab_group(vertical: align_fill, horizontal: align_fill,
          items: [
              { name: "Sources", value: @sources },
              { name: "Property Model", value: @model_inspector },
              { name: "Layout Sheet", value: @layout_inspector },
              { name: "Results", value: @results },
              { name: "Errors", value: @errors }
          ])
{
    // ...
}

dialog

Layout Attribute Defaults
Additional Attributes
name
type: string
default: ""
The name of the window to be shown in the its title bar
grow
boolean
default: false
Whether or not this window should have a grow box and is resizeable
metal
boolean
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.
Examples in CEL
dialog(name: "Editor", size: @size_small, placement: place_column,
       grow: true, horizontal: align_fill, vertical: align_fill)
{
    // ...
}

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

Layout Attribute Defaults

no changes.

Additional Attributes
name
type: string
default: ""
The name of the widget.
alt
type: string
default: ""
The text to be used for the widget's tooltip.
default
type: boolean
default: false
Specifies whether or not this button should behave as the default button (including any necessary visual cues.)
cancel
type: boolean
default: false
Specifies whether or not this button should behave as the cancel button (including any necessary visual cues.)
items
type: array of dictionaries
default: [ ]
Describes the various visual states this button can turn to, based on the modifier keys that are held down by the user. Each item is described using a dictionary with the following keys:
name
type: string
default: ""
The name of the widget.
alt
type: string
default: ""
The text to be used for the widget's tooltip.
modifiers
type: name or array of names
valid values: @option, @command, @control
The necessary modifiers must be depressed by the user (either one or many, specified using an array) in order for this state to be shown.
Examples in CEL
button(items: [
           { name: "Evaluate" },
           { name: "Dump", modifiers: @option },
           { name: "Version", modifiers: @command }
       ]);

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
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.
Examples in CEL
checkbox(name: "Whizzy Checkbox", alt: "This is my tooltip info");
checkbox(name: "Make Mixed Control", value_on: @mixed, value_off: false);

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
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
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
Used to specify the maximum digits allowed for the numeric value (the edit text portion) of this widget. The default of 0 implies unlimited length.
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.
Examples in CEL
edit_number(name: "Temperature:", format: "#.##", min_value: -273.15,
            units: [
                { name: "fahrenheit", bind: @celsius, scale: [ 1.8, 32 ] },
                { name: "celsius", bind: @celsius },
                { name: "kelvin", bind: @celsius, scale: [ 1, 273.15 ]  }
            ]);

edit_text

Layout Attribute Defaults

no changes.

Additional Attributes
name
type: string
default: ""
The name of the widget.
alt
type: string
default: ""
The text to be used for the widget's tooltip.
characters
type: integer
default: 10
Used to specify the approximate width of the edit text portion of this widget. Added to this length is the length of the name of the widget to get the minimum width required for this widget.
max_characters
type: integer
default: 0
Used to specify the maximum width of the edit text portion of this widget. The default of 0 implies unlimited length. Only relevant when lines is 1.
lines
type: integer
default: 1
Specifies the height of the widget in number of lines available in the edit text field.
monospaced
type: boolean
default: false
Specifies the use of a monospaced font for this edit text field. Deprecated.
scrollable
type: boolean
default: false
Specifies whether or not the edit text field should be scrollable. Only relevant when lines is greater than 1.
password
type: boolean
default: false
Specifies whether or not the edit text field should hide the actual text within the widget.
Examples in CEL
edit_text(name: "Expression:", characters: 10, horizontal: align_fill);

image

Layout Attribute Defaults

no changes.

Additional Attributes
image
type: string
default: ""
File name of the image to be placed in the widget. The path(s) used for finding this file vary based on how the client specifies resource paths with adobe/future/resources.hpp.
Examples in CEL
image(image: "stop.tga");

label

Layout Attribute Defaults

no changes.

Additional Attributes
name
type: string
default: ""
The name of the widget.
alt
type: string
default: ""
The text to be used for the widget's tooltip.
characters
type: integer
default: 0
Specifies the maximum width of the label (in approximate characters). When the label's content exceeds this width, the label will wrap, automatically increasing its height, so the entire label's contents are visible.
Examples in CEL
static_text(name: "Unfortunately, something drastic has happened. If you would like we can try to
            continue with the operation, but there is a chance you will blow up your computer. Would
            you like to try?", characters: 25);

link

Layout Attribute Defaults

no changes.

Additional Attributes
alt
type: string
default: ""
The text to be used for the widget's tooltip.
count
type: integer
default: 0
The number of horizontal 'link lines' to be displayed by this widget. Each link line will automatically attach itself to the next available baseline guide that can be found.
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.
Examples in CEL
link(count: 3, value_on: false, value_off: true);

list

Note: The list widget is still in its infancy. Expect this documentation to change.

Layout Attribute Defaults
Additional Attributes
column_set
type: array of dictionaries
default: [ ]
Describes the columns to be used in the list. Each column is described using a dictionary with the following keys:
name
type: string
default: ""
The visually displayed name of the column
id
type: name
default: name_t()
Specifies the key to be used to extract data from the model for this particular column
selectable
type: boolean
default: false
Specifies whether or not the data in this column can be selected by the user
mutable
type: boolean
default: false
Specifies whether or not the data in this column can be edited by the user
Examples in CEL
list(column_set: [
         { id: @name, name: "Name", selectable: true, mutable: true },
         { id: @value, name: "Value", selectable: true, mutable: true }
     ]);

popup

The custom meta-item is never explicitly selectable by the user. The only way it can be shown is if the user modifies the value bound to the popup by some other means for which the popup has no corresponding menu item.

Layout Attribute Defaults

no changes.

Additional Attributes
name
type: string
default: ""
The name of the widget.
alt
type: string
default: ""
The text to be used for the widget's tooltip.
custom_item_name
type: string
default: "Custom"
When the value to which this popup is bound does not match any of the possible values in the popup, the 'Custom' meta-item is shown. This string is the actual text used in the display of the custom meta-item.
items
type: name or array of dictionaries
default: [ ]
Describes the items to be listed in the popup. If a name is specified then the popup items are bound to an output of the data model. The value bound to should contain an array of dictionaries as described here. [Note: binding items is currently not implemented in the APL widget set.] Each dictionary in the array has the following keys:
name
type: string
default: ""
The visually displayed name of the item
value
type: regular
default: empty
When the bound cell to the popup is set to this value, this particular item becomes selected.
Examples in CEL
popup(name: "Select One:", custom_item_name: "Not Applicable",
      items: [
            { name: "Eeny", value: "Eeny" },
            { name: "Meeny", value: "Meeny" },
            { name: "Meiny", value: "Meiny" },
            { name: "Moe", value: "Moe" }
         ]);

presets

Note: This is one nasty widget. The reason it is so is because it does not follow the conventions of a widget (typically) being a single view/controller into the model. In the case of a preset widget, it is a view/controller into an arbitrary number of values in the property model. As such, extra levels of setup and hook points are required.

Layout Attribute Defaults

no changes.

Additional Attributes
name
type: string
default: ""
The name of the widget. Note that this name is never seen visually; rather, it is used as the preset file name when presets are saved/loaded from disk.
domain
type: string
default: ""
The domain of the widget, typically the name of the application in which this preset widget resides. Note that this name is never seen visually; rather, it is used as the directory that will contain all the preset widget data files for this application.
alt
type: string
default: ""
The text to be used for the widget's tooltip.
additional_preset_set
type: array of dictionaries
default: [ ]
Sometimes the client application will want to add runtime 'presets' that are not really presets but give the user the ability to copy state already present within the application. Examples of this may be a current list of the open documents and their dimensions. Each item is described using a dictionary with the following keys:
name
type: string
default: ""
The visually displayed category name of the preset set (e.g., "Open Documents")
items
type: array of dictionaries
default: [ ]
Describes the actual presets to be listed in this preset category. Each item is described using a dictionary with the following keys:
name
type: string
default: ""
The visually displayed name of the preset (e.g., "4x6 Portrait")
value
type: dictionary
default: { }
Describes the actual values contained within the preset. The keys in the preset's value must have a one-to-one correspondence to keys found in the current property model. The value associated with those keys are the values to be imbued upon the property model at the time this preset is selected by the user.
bind_output
type: name
default: name_t()
Specifies the feedback cell to go from the property model to the preset. This cell should contain an aggregation of property model cell names and their values as key/value pairs of a dictionary. When a value changes in the model and the preset widget wants to know about the change, the cell named here should have an updated dictionary with the new value for the modified cell.
bind
type: array of arrays
default: [ ]
One of the functions available through the preset widget is the ability to add new presets. When this is done a dialog is presented to the user where they can specify a name for the preset. The user, in that dialog, will also be able to specify exactly which of the property model values they would like to have included in the preset. This parameter allows for the specification of which property model values are allowed in a preset. Specifying an array of identifiers under a single label allows for related values to be added/omitted as a group from the preset.
Please see the CEL example for an example of how this parameter is specified.
localization_set
type: dictionary
default: { }
The preset widget has subdialogs of its own. In order to allow for the client application to override the string values within these widgets, this dictionary can be supplied to the widget. There are a set number of keys for which strings are expected; if the key/value pair is not supplied in the dictionary, a default (English) string will be used.
Please see the CEL example for a list of keys (and possible string values).
Examples in CEL
preset(name: "new_document",
       domain: 'MyApplication',
       alt: "Modify the presets available for this command",
       bind_additional: @additional_preset_set,
       bind_output: @preset_feedback,
       bind: [
                [ [ @resolution, @resolution_indirect ], "Resolution" ],
                [ @background, "Background Contents" ],
                [ @colorMode, "Color Mode" ],
                [ [ @gray_profile, @rgb_profile, @cmyk_profile ], "Color Profile" ],
                [ @bitDepth, "Bit Depth" ],
                [ @aspectRatio, "Pixel Aspect Ratio" ],
                [ [ @pixelWidth, @width_inches, @pixelHeight, @height_inches ], "Dimensions" ]
             ],
       localization_set: {
            add_dialog_group_name: "Include in Preset",
            add_dialog_message: "Choose which values in the dialog you would like to add to the preset you are creating.",
            add_dialog_name: "Add A Preset",
            add_subdialog_cancel_button_alt_text: "Do not add a preset",
            add_subdialog_default_preset_name: "My Preset",
            add_subdialog_ok_button_alt_text: "Add a preset with the current settings",
            category_popup_alt_text: "Select a category of presets from the list",
            category_popup_name: "Category:",
            custom_category_name: "Custom",
            delete_dialog_message: "Choose a preset to delete. This action cannnot be undone.",
            delete_dialog_name: "Delete A Preset",
            delete_subdialog_cancel_button_alt_text: "Do not delete a preset",
            delete_subdialog_ok_button_alt_text: "Delete the currently selected preset",
            file_extension: ".presets.cel",
            menu_item_add_preset: "Add Preset...",
            menu_item_append_preset: "Append Presets...",
            menu_item_delete_preset: "Delete Preset...",
            preset_popup_alt_text: "Select a preset from the list to populate the dialog",
            preset_popup_name: "Preset:",
            subdialog_cancel_button_name: "Cancel",
            subdialog_ok_button_name: "OK",
            top_folder_name: "Adobe",
            user_preset_list_empty_warning: "The user preset list is empty",
            user_presets_category_name: "User Presets"
         });

progress_bar

Layout Attribute Defaults

no changes.

Additional Attributes
is_indeterminate
type: boolean
default: false
Specifies whether or not this progress bar has the "barber pole" spinning style.
is_relevance
type: boolean
default: false
Specifies whether or not this progress bar is a relevance bar.
Note: This is option is ignored on every platform but Mac OS X.
orientation
type: name
valid values: @vertical, @horizontal
default: @horizontal
Specifies the orientation of the progress bar
format
type: dictionary
A range of possible values for this progress bar to have. See #value_range_format_t for more information on the dictionary parameters.
Examples in CEL
progress_bar(orientation: @vertical, format: {first: 0, last: 100, interval: 1});

radio_button

Layout Attribute Defaults

no changes.

Additional Attributes
name
type: string
default: ""
The name of the widget.
alt
type: string
default: ""
The text to be used for the widget's tooltip.
value
type: regular
default: empty
When the value of the cell to which this widget is bound changes to this value, the radio button is selected.
Examples in CEL
radio_button(name: "Radio Button C", value: @c, alt: "Tooltip info!");
radio_button(value: @none);

reveal

Layout Attribute Defaults

no changes.

Additional Attributes
name
type: string
default: ""
The name of the widget.
alt
type: string
default: ""
The text to be used for the widget's tooltip.
value_on
type: regular
default: empty
When the value of the cell to which this widget is bound changes to this value, the reveal widget is 'turned down' or 'on'.
Examples in CEL
reveal(name: "Advanced Settings", alt: "Click to hide or show advanced options");

separator

Layout Attribute Defaults
Additional Attributes
orientation
type: name
valid values: @vertical, @horizontal
default: @horizontal
Specifies the orientation of the separator. Note that if you set the separator to have a vertical orientation, you will also have to set its vertical value to align_fill.
Examples in CEL
separator(vertical: align_center);

slider

Layout Attribute Defaults

no changes.

Additional Attributes
alt
type: string
default: ""
The text to be used for the widget's tooltip.
orientation
type: name
valid values: @vertical, @horizontal
default: @horizontal
Specifies the orientation of the slider.
slider_ticks
type: integer
default: 0
Specifies the number of tick marks to place along the slider's edge.
slider_point
type: name
valid values: @none, @up, @down, @left, @right
default: @none
Specifies if the slider thumb has a point and if so which way it points.
format
type: dictionary
A range of possible values for this slider to have. See #value_range_format_t for more information on the dictionary parameters.
Examples in CEL
slider(bind: @progress_value, format: {first: 0, last: 100, interval: 1});