Widget Reference [Widget Library]

Author:

Sean Parent, Adobe Systems Incorporated

Foster Brereton, Adobe Systems Incorporated

Date:

January 7, 2005

Abstract

This document serves as a reference guide for the widgets one can define for the current implementation of Adobe Begin.

Table of Contents

1. Widget Set Overview
2. Views Reference
   1. Common View Attributes
   2. View Classes
      1. bevel_button
         1. button_beveled
         2. checkbox_beveled
         3. radio_button_beveled
         4. popup_beveled
      2. button
      3. checkbox
      4. edit_number
      5. edit_text
      6. link
      7. popup
      8. progress_bar
      9. radio_button
      10. separator
      11. slider
      12. static_text
3. Containers Reference
   1. Common Container Attributes
   2. Container Classes
      1. Root-Level Containers
         1. dialog
         2. palette
      2. Nestable Containers
         1. column
         2. group
         3. overlay
         4. panel
         5. row
         6. tab_group

Widget Set Overview

The widget set is best split into two categories: views and containers.

A View is a "leaf node" widget like a button or a separator. A view cannot contain any views inside of it. Views define interface elements presented to the user.

Containers are also views (and inherit all the attributes of a view), but can have subviews within themselves, including other containers. Containment denotes the layout relationships between subviews. Containers do not necessarily add interface elements to the dialog (though they can).

There is also a set of root container classes. Only one root container is allowed per dialog, and it must be the topmost container in the defintion, otherwise the resulting dialog is undefined.

Views Reference

Common View Attributes

attribute	type	default	description
indent	number	0	Cross-stream indentation in pixels.
horizontal	alignment	align_left
vertical	alignment	align_top
guide_mask	array	[ ]	guides to suppress - current values are guide_baseline, guide_label.
name	string	""	displayed name of view
bind	name	empty	attached Adam cell
bind_indirect	name	empty	Adam cell containing the name of the Adam cell to attach
touch	array	[ ]	Adam cells to touch when set
identifier	name	empty	identifier for this widget
size	enumeration	@size_normal	Valid values are one of @size_mini, @size_small, @size_normal. Specifies the size of the text used for the widget.
focus	name	empty	attaches Adam cell to keyboard focus (identifier is value)

View Classes

bevel_button

The bevel button is a multi-use widget, and can emulate several other types of widgets. In fact, you cannot specify a bevel_button directly, but must invoke it as emulating another widget. The possible bevel_button variants are:

• button_beveled
• checkbox_beveled
• radio_button_beveled
• popup_beveled

attribute	type	default	description
name	string	""	Name of the button
value_on	anything	n/a	Value to set the bound cell to when clicking the button in the off/neutral state. Useful when behaving as a radio button and checkbox.
value_off	anything	n/a	value to set the bound cell to when clicking the button in the on state. Useful when behaving as a radio button and checkbox.
popup_bind	name	empty	name of cell to which bevel button is bound. Useful when behaving as a popup.
items	array	[ ]	Specifies menu contents. Useful when behaving as a popup.
items[]	dictionary	{ }	Single menu item specification. Useful when behaving as a popup.
items[].name	string	""	Name of a given menu item. Useful when behaving as a popup.
items[].value	name	empty	Value to set the popup_bind cell to when this item is selected. Useful when behaving as a popup.
popup_placement	enumeration	@right	Valid values are one of @right or @down. Arrow direction and menu location. Useful when behaving as a popup.
bevel_thickness	enumeration	@normal	Valid values are one of @small, @normal, @large, @rounded. Specifies bevel button bevel style

button

attribute	type	default	description
default	boolean	false	set to true for default button behavior
cancel	boolean	false	set to true for cancel button behavior
action	enumeration	required	Valid values are one of @reset, @cancel, or @dialog. Action for button to perform in the default state
bind_output	name	empty	If set, imposes value to the bound cell. bind_output and action are mutually exclusive. If both are set for a widget then bind_output will take precedence.
value	string	""	When the action is @dialog, specifies the name of the subdialog to open. When bind_output is set, it is the value imposed onto the cell.
items	array	[ ]	Specifies alternate namings of button based on modifier key states
items[]	dictionary	{ }	Alternate button state specification
items[].name	string	""	Name of button for given modifier key state
items[].action	enumeration	required	Valid values are one of @reset, @cancel, or @dialog. Action button for given modifier key state
items[].value	string	""	When the action is @dialog for this state, specifies the name of the subdialog to open
items[].modifiers	enumeration	no modifiers	Valid values are some name which is a combination of "opt", "ctl", "cmd" in that order. Specification of the button modifier keys that need to be held down for this state to be in effect. For example, @optctl would set the state to this one when the option and control keys are pressed. Note that the order matters, so @optctl is valid while @ctlopt is not.

checkbox

attribute	type	default	description
value	any	required	Value to impose upon the cell when the checkbox is clicked; also the value the cell must be set to in order for the checkbox to display selected.
touch	array of cell names	[ ]	When a checkbox is hit, specifies the other cells that should be made recently changed as well

edit_number

attribute	type	default	description
digits	number	5	specifies width as approximate number of characters
display_disable	bool	false	When field is disabled, this will replace the edit text field with a static text field
touch	array of cell names	[ ]	When a field is modified, specifies the other cells that should be made recently changed as well
format	string or name	"#.00"	printf style format for Adam cell containing format
units	array	[ ]	Specifies unit popup contents (See adobe::unit_t)

edit_text

attribute	type	default	description
characters	number	10	Specifies width as approximate number of characters (columns)
lines	int	1	Number of lines (rows) tall the edit text field should be
monospaced	bool	false	Specifies whether or not to use a monospaced 10-point font in this control
scrollable	bool	false	Specifies whether or not to attach horizontal and vertical scrollers to this text field.
password	bool	false	Specifies whether or not to hide the characters entered into this text field.

link

attribute	type	default	description
count	number	2	number of prongs drawn in linkage
value_on	any	n/a	Value that must be set in cell for link to be displayed
value_off	any	n/a	Value to impose upon bound cell when the link is clicked on

popup

attribute	type	default	description
items	array	[ ]	array of menu item elements
items[]	dictionary	n/a	menu item element
items[].name	string	n/a	name of menu item
items[].value	any	n/a	value of menu item

progress_bar

attribute	type	default	description
format	dictionary	{ }	Semantic specification of the progress bar
format.first	long	0	minimum value allowed
format.last	long	100	maximum value allowed
format.interval	long	1	Step value for increments between first and last
is_indeterminate	bool	false	Specifies an indeterminate (aka barber-pole) progress bar style
is_relevance	bool	false	Specifies an relevance bar style
orientation	identifier	@horizontal	Could also be @vertical. Specifies the direction of the progress bar.

radio_button

attribute	type	default	description
value	any	required	Value to impose upon the cell when the button is clicked; also the value the cell must be set to in order for the button to display selected.
touch	array of cell names	[ ]	When a radio button is hit, specifies the other cells that should be made recently changed as well

separator

attribute	type	default	description
orientation	enumeration	@horizontal	(could also be @vertical). Specifies the direction of the separator's growth. Alignment for that direction will be set to align_fill.

slider

attribute	type	default	description
format	dictionary	{ }	Semantic specification of the slider
format.first	long	0	minimum value allowed
format.last	long	100	maximum value allowed
format.interval	long	1	Step value for increments between first and last

static_text

attribute	type	default	description
wrap	boolean	false	if true, text is wrapped to available space

Containers Reference

Common Container Attributes

attribute	type	default	description
placement	placement	place_column
child_horizontal	alignment	align_left
child_vertical	alignment	align_top
spacing	number or array	space_normal

Container Classes

dialog

This is a root container class.

attribute	type	default	description
placement	placement	place_row	different default than container
metal	bool	false	Allows for the metallic look on a dialog
grow	bool	false	allows for the dialog to be resized by the user

palette

This is a root container class.

attribute	type	default	description
metal	bool	false	Allows for the metallic look on a dialog
grow	bool	false	allows for the dialog to be resized by the user

column

attribute	type	default	description
placement	placement	place_column	a simple column container

group

attribute	type	default	description
name	string	""	Name of this group

overlay

attribute	type	default	description
placement	placement	place_overlay	a simple overlay container
horizontal	alignment	align_fill
vertical	alignment	align_fill

panel

attribute	type	default	description

row

attribute	type	default	description
placement	placement	place_row	a simple row container

tab_group

attribute	type	default	description
items[]	dictionary	required	tab specification
items[].name	string	required	name of the tab
items[].value	any	n/a	value of the tab