REBOL/View Developer's Guide

    REBOL/View Version 1.0
    Updated 5-April-2001
    REBOL Technologies WWW.REBOL.COM
    Send corrections to docs@rebol.com

Note: Images used in this document are encoded in PNG format. If you cannot see the images, your Web browser software may be too old. Try another web browser, or contact us if the problem persists.

1. Introduction

By their nature, graphical user interfaces (GUI) are more descriptive than they are functional. In REBOL, the Visual Interface Dialect (VID) provides an efficient method of describing GUIs. VID is implemented as a layer that rides on top of the REBOL/View graphical compositing system. VID provides shortcut expressions that are automatically translated into View objects and functions. You can seamlessly combine VID and View code and data for great power and flexibility.

2. Layout Concepts

A VID layout is a block of words and values that is used to describe a GUI. It provides the names, attributes, and operations that are used to display text areas, buttons, checkboxes, input fields, slider bars, and more. The format of the VID layout block is organized according to the rules of VID.

2.1. Layout Structure
A layout block consists of:

Keywords Layout keywords that describe face positioning and other layout attributes.

Styles Face styles that are used to specify the faces that are displayed. These can be predefined styles like TITLE, BUTTON, FIELD, TEXT, or your own custom styles.

Facets Attributes that describe variations in the style of a face, such as the size, color, alignment, border, or image.

Variables Definitions that hold either faces or layout positions. These variables can be used later to access face objects or to affect face positions.

Styledefs New style definitions that are to be used within the layout. Single styles or entire stylesheets can be provided.

These elements can be mixed and matched in whatever order is necessary to create a layout.

2.2. Simple Examples
The easiest way to learn VID layouts is by example. The single line below creates and displays a window that contains the obligatory "Hello World!" example:
	view layout [title "Hello World!"]
The layout block contains the VID description of what to display. The block is a dialect, not normal REBOL, and it is passed to the LAYOUT function to create the faces for the layout. The result of the LAYOUT function is passed to the VIEW function to display it on your screen:

The TITLE word is a predefined style and is followed by values and attributes that affect that style. In the example above, a string value provides the title text.
VID provides more than 40 predefined styles. For example, you can replace the TITLE style with the video BANNER style:
	view layout [banner "Hello World!!!"]
The result becomes:

Within a layout, multiple styles can be provided. Each style creates another element of the interface. The example below shows a video heading (vh2), followed by text, then by a button:
	view layout [
		vh2 "Layout Definition:"
		text "Layouts describe graphical user interfaces."
		button "Remember"
	]
This example would appear as:

Thousands of effects and variations are possible within a layout by specifying style attributes called facets. These attributes follow the style word. Here is an example that shows how an elaborate layout can be created in a few lines of VID code:
	view layout [
		backdrop effect [gradient 1x1 180.0.0 0.0.100]
		vh2 "Layout Definition:" 200x22 yellow
			effect [gradmul 1x0 50.50.50 128.128.128]
		vtext bold italic "Layouts describe graphical user interfaces."
		button "Remember" effect [gradient 0.0.0]
	]
The result would be:

Layouts can specify as many faces as your interface requires. For example, this layout uses styles, a backdrop, a heading, text labels, text input fields, and buttons:
	view layout [
		style lab label 100 right
		across
		vh2 "Provide Your Information:" gold return
		lab "User Name:" field return
		lab "Email Address:" field return
		lab "Date/Time:" field form now return
		lab "Files:" text-list data load %. return
		lab
		button 96 "Save"
		button 96 "Cancel"
		return
	]
This layout creates:

The example shows how multiple styles can be specified within a layout.

3. Layout Function

The LAYOUT function takes a layout block as an argument and returns a layout face as a result. The block describes the layout according to the rules of the Visual Interface Dialect. The block is evaluated and a face is returned.
The result of LAYOUT is can be passed directly to the VIEW function, but it can also be set to a variable or returned as the result of a function. The line:
	view layout block
can also be written as:
	window: layout block
	view window
The result of the layout function is a face and can be used in other layouts. More on this later.

3.1. Layout Refinements
In most cases, the LAYOUT function is called without refinements; however, these refinements are available when necessary:

/size A PAIR! that specifies the size of the resulting face. This forces the face to be of a fixed size before the layout is performed. The default is to size the face dynamically based on the placement of items within the layout.

/offset A PAIR! that provides the offset to where the window will be displayed within its parent face (often the screen).

/styles A stylesheet block that was created with the STYLIZE function. A stylesheet defines custom styles used within the layout. This is equivalent to the STYLES keyword within a layout.

/origin A PAIR! that sets the pixel offset to the first face within the layout. This is equivalent to the ORIGIN keyword within a layout.

/parent Specifies the style of the top-level face that is produced from the layout. The parent can be specified as a style name or as an actual instance of the style.

/options Specifies the VIEW options when the face is displayed with the VIEW function. See the VIEW function for details.

4. Keywords

Here is a summary of the layout keywords that describe face positioning and other layout attributes. These are reserved words. These words cannot be used for style names or for variables within a layout.

across Set auto-layout to horizontal direction.

at Locate a face to an absolute position.

backcolor Set the color of the background.

below Set auto-layout to vertical direction.

do Evaluate a block.

guide Set a guide line.

indent Indent horizontally.

offset Set the output face position.

origin Specify the layout starting position.

pad Insert extra spacing.

return Return to the current guide position.

style Define a custom style.

styles Use styles from a stylesheet.

space Set the auto-spacing used between faces.

size Set the output face size.

tabs Set tab stops.

tab Advance to next tab position.

Each of these keywords is described in more detail in sections of this document.

5. Face Styles

Face styles are used to specify the faces that are displayed. These can be predefined styles, or they can be your own custom styles.

5.1. Predefined Styles
Predefined styles are part of VID and can be used in three ways.

You can use any predefined style as-is and it will provide its default look and feel.

You can specify variations on a style by providing facets such as color, size, font, effects, etc.

You can use a style as the basis for defining a new custom style.

The predefined styles are listed below. For more information about each of these styles, refer to the Styles chapter (a separate document).

title Document title heading.

h1 Top level heading used for documents.

h2 Heading use for document sections.

h3 Heading used for subsections.

h4 Heading used below subsections.

h5 Heading used below subsections.

banner Title heading with video style.

vh1 Section heading used for video style.

vh2 Section heading used for video style.

vh3 Section heading used for video style.

text Document body text.

txt An alias for TEXT style above.

vtext Inverse video body text.

tt The teletype font for fixed width text.

code Same as TT except defaults to bold.

label Used for specifying GUI text labels.

field Text entry field.

info Same as FIELD style, but read-only.

area Text editing area for paragraph entry.

sensor An invisible face that senses mouse events.

image Display a JPEG, BMP, PNG, or GIF image.

box A shortcut for drawing a rectangular box.

backdrop Scale an image over the entire layout window.

backtile Tile an image over the entire layout window.

icon Display a thumbnail sized image with text caption.

led An indicator light.

anim Display an animated image.

button A button that goes down on a click.

toggle Similar to BUTTON but has a dual state.

rotary Similar to BUTTON but allows multiple states.

choice A pop-up button that displays multiple choices.

check A check box.

radio A rounded radio button.

arrow An arrow button with a beveled edge.

progress A sliding progress bar.

slider A slider bar.

panel A sub-layout.

list An iterated sub-layout.

text-list A simple form of the LIST style.

key Keyboard shortcut.

Here is an example that shows most of these custom styles:
	title "Document Title"
	h1 "Heading 1"
	h2 "Heading 2"
	h3 "Heading 3"
	h4 "Heading 4"
	h5 "Heading 5"
	banner "Video Title"
	vh1 "Video heading 1"
	vh2 "Video heading 2"
	vh3 "Video heading 3"
	text "Document body text"
	tt "The teletype font for fixed width text"
	code "Same as TT except defaults to bold"
	vtext "Inverse video body text"
	txt "An alias for BODY style above"
	label "Used for specifying GUI text labels"
	lbl "The video equivalent of LABEL"
	field "Text entry field"
	info "Same as FIELD style, but read-only"
	area "Text editing area for paragraph entry"
	do [if not exists? %nyc.jpg [write/binary %nyc.jpg read/binary %../nyc.jpg]]
	image %nyc.jpg 100x100
	box blue
	icon %nyc.jpg "NYC"
	led
	button "Button"
	toggle "Toggle"
	rotary "Rotary"
	choice "Choice"
	check
	radio
	arrow
	progress
	slider 200x16
	text-list "A simple form of the LIST style"
This will appear as:

5.2. Facets
All of the styles above can be provided with additional information to vary their size, color, text, alignment, background, and more. This is described in detail in the Facets section below.

5.3. Custom Styles
Any of the styles listed above can be used as the base style for creating your own custom style. This is covered in the Style Definition section later in this document.

6. Style Facets

Within a layout, each face is specified by a style word that identifies the look and feel of the face. Each style word can be followed by optional facet attributes that further modify the face. Facets can control the text, size, color, images, actions, and most other aspects of a face.
All facets are optional. For example, the example below shows how you can create a button with a variety of facets. The facets can be provided alone or in combination.
	button
	button "Easy"
	button "Easy" 40x40
	button "Easy" oldrab
	button "Easy" [print "Fun"]
	button "Easy" 40x40 maroon [print "Fun"]
The resulting face looks like:

Facets can appear in any order. You don't need to keep track of which goes first. All of these mean the same thing:
	button "Easy" 40x40 navy [print "Fun"]
	button navy "Easy" 40x40 [print "Fun"]
	button 40x40 navy "Easy" [print "Fun"]
	button [print "Fun"] navy 40x40 "Easy" 
They produce:

6.1. Text Facets
Text string facets provide the text used for all faces. The text can be written as a short string in quotes, a long multiline string in braces, or provided as a variable or function that contains the string.
	text "Example string"
	
	text {This is a long, multilined textsection that is put in a braced
	string and will be displayed on the page.}

	text text-doc

	text read %file.txt
For some faces styles, more than one string can be provided. For instance, a choice button accepts multiple strings:
	choice "Steak" "Eggs" "Salad"
6.2. Size Facets
The size of a face can be specified as a pair that provides the width and height of the face in pixels:
	image %nyc.jpg 100x200
	text "example" 200x200
	button "test" 50x24
	
The width of a face can also be expressed an integer, leaving the height to be computed automatically:
	text "example" 200
	button "test" 50
6.3. Color Facets
A color is written as a tuple that provides the red, green, and blue components of the color.
	image %nyc.jpg 250.250.0
	text "example" 0.0.200
	button "test" 100.0.0
The are also about 40 predefined colors in REBOL that can be used:
	text red "Warning"
	text blue "Cool down"
	text green / 2 "Ok"
Notice in the last case how the color can be reduced by dividing it by two.
Some faces accept multiple colors. For instance:
	toggle "Test" red green

	rotary "Stop" red "Caution" yellow "Go" green
6.4. Image Facets
An image can be provided as a filename, a URL, or as image data.
	image %nyc.jpg
	image http://www.rebol.com/view/nyc.jpg
	button "Test" %nyc.jpg
An image can also be loaded and used as a variable:
	town: %nyc.jpg

	image town
	image 30x30 town
	icon town "NYC"
6.5. Action Facets
An action is specified as a block. The action makes a face "hot". When a user clicks on the face, the block will be evaluated.
	image %nyc.jpg [print "hello"]
	text "example" [print "there"]
	button "Test" [print "user"]
	
Some styles accept a second block that is used as an alternate action (right-click action). For example:
	text "Click Here" [print "left click"] [print "right click"]
6.6. Character Facets
A shortcut key is written as a character (a string with a # before it). If the user presses a shortcut key, the action block will be evaluated as if the user clicked on it.
	image %nyc.jpg #"i" [print "hello"]
	text "example" #"^t" [print "there"]
	button "Test" #" " [print "user"] 
6.7. Face Facet Blocks
Note that facet blocks are most useful when used in conjunction with custom styles.

font A font block is used to specify other details about a font, such as its font name, point size, color, shadow, alignment, spacing, and more:

text "black" font [color: 255.255.255 size: 16 shadow: none]

para A para block specifies the paragraph attributes of a text face. This is where you adjust the spacing between paragraphs, margins, and other values.

text "test" para [origin: 10x10 margin: 10x10]

edge An edge block gives you a way to control the edge around the outside of a face. You can set its color, size, and effect.

image %nyc.jpg edge [size 5x5 color: 100.100.100 effect: [bevel]]

effect An effect block specifies special graphic effects for a face. Many effects are possible, such as gradients, colorize, flip, rotate, crop, multiply, contrast, tint, brighten, and various combinations.

image %nyc.jpg effect [contrast 20] image %nyc.jpg effect [tint 120 brighten 30] button "Test" effect [gradient 0x1 200.0.0]

with The with block allows you to specify any other type of face characteristic using standard REBOL object format.

7. Attribute Keywords

These words control the layout as it is being created. They affect the placement of faces within the layout.

7.1. Size Keyword
SIZE sets the size of the layout face. This must be done at the beginning of a layout before any styles are used. For example, the simple layout:
	size 200x100
	h2 "Size Example"
would appear as:

This is equivalent to the /size refinement in the LAYOUT function. If no size is specified, then the layout is auto-sized based on the styles used within it.

7.2. Offset Keyword
OFFSET specifies the position of the layout face within its parent face (often the screen). This is the same as the /offset refinement in the LAYOUT function.
	offset 10x32
The offset need not be specified in the layout. It can be specified in the View if necessary. The default offset is 25x25.

7.3. Origin Keyword
ORIGIN sets the starting X and Y position of faces in the layout. The origin is specified as the number of pixels from the upper left corner of the layout window. However, the origin also determines the amount of spacing between the last face and the bottom right of the layout. The default origin is 20x20.
The example below uses an origin that is smaller than usual:
	origin 4x2
	text bold "Origin at 4x2"
It creates a display like this:

If an integer is specified for the origin, then both the X and Y positions will be set to that value, as in this example:
	origin 50
	text bold "Origin at 50x50"
The example above produces:

When no pair value is provided, the origin word returns the layout to its original origin position.
	box 34x40 beige
	origin
	text bold "Back at Origin"
Here the text will overlay the box that was created at the origin:

As you can see from the above examples, the origin also has an affect on the size of the resulting face when no size has been provided.
Setting the origin is especially important when creating panels and lists. Frequently the origin in lists is set to zero. For example:
	vh2 "Films:"
	list 144x60 [
		origin 0
		across
		text 60
		text 80
	] data [
		["Back to the Future" "1:45"]
		["Independence Day" "1:55"]
		["Contact" "2:15"]
	]
would produce:

The block provided to the LIST style is a layout with an origin of zero.

8. Auto-Layout Direction

8.1. Below Keyword
BELOW specifies a vertical layout for faces that follow it. It is used along with ACROSS for auto layout of faces.
BELOW is the default layout direction when none is specified. For example:
	button "Button 1"
	button "Button 2"
	button "Button 3"
looks like:

You can switch between BELOW and ACROSS at any time during a layout. When BELOW is used, faces will be positioned below the current face. The example:
	across
	button "Button 1"
	button "Button 2"
	return
	below
	button "Button 3"
	button "Button 4"
produces:

8.2. Across Keyword
ACROSS specifies a horizontal layout for faces that follow it. It is used along with BELOW for auto layout of faces.
When ACROSS is used, faces will be located to the right of the current face. The example:
	across
	button "Button 1"
	button "Button 2"
	button "Button 3"
creates:

You can switch between ACROSS and BELOW at any time during a layout.
	vh2 "Example"
	across
	button "Button 1"
	button "Button 2"
	return
	button "Button 3"
	button "Button 4"
	return
The above example would display:

8.3. Return Keyword
RETURN advances the position to the next row or column, depending on the layout direction. If the layout direction is across, return will start a new row. If the direction is below, return will start a new column.
The example:
	across
	text "Name:" 100x24 right
	field "Your name"
	return
	text "Address:" 100x24 right
	field "Your address"
	return
Produces:

The position of the column is relative to the origin or to a guide.

9. Spacing

9.1. Space Keyword
SPACE sets the auto-spacing to use between faces within the layout. The spacing can be changed at any time within your layout. Either a pair or an integer can be given. If you specify a pair, both the vertical and horizontal spacing is set.
Compare these two cases. The first specifies a small space:
	space 2x4
	button "Button 1"
	button "Button 2"
	return
	button "Button 3"
	button "Button 4"
and produces:

The second uses a larger space:
	space 20x16
	button "Button 1"
	button "Button 2"
	return
	button "Button 3"
	button "Button 4"
that results in:

If the space you specify is an integer, only the spacing in the current direction (across or below) is set. The line would look like:
	space 5
9.2. Pad Keyword
PAD inserts extra spacing between the current position and the position of the next face. The distance can be specified as an integer or a pair. When it is a pair, the space will be added both horizontal and vertically.
	text "Bar below"
	pad 20x4
	box 50x3 maroon
When the PAD is an integer, space is either vertical or horizontal depending on the current direction of auto layout (determined by below and across words).
A PAD used in a BELOW:
	below
	text "Pad"
	pad 40
	text "Below"
has a vertical effect:

and a PAD used in an across:
	across
	text "Pad"
	pad 40
	text "Across"
has a horizontal effect:

Note that negative pad values are also allowed.
	text "Bar above"
	pad 20x-30
	box 50x3 maroon
The bar is now above the text:

9.3. Indent Keyword
INDENT inserts spacing horizontally between the current position and the next face. It is not affected by the auto layout direction.
This example indents 20 pixels for every face after the heading:
	vh1 "About VID"
	indent 20
	text "This section is about VID."
	button "Ok"
	button "Cancel"
The result is:

Negative values can also be used:
	vh1 "About VID"
	indent 20
	text "This section is about VID."
	indent -20
	button "Ok"
	button "Cancel"

10. Aligning Faces

10.1. At Keyword
AT sets an absolute layout position for the face that follows it. Here's a simple example that sets the next position of a layout:
	at 60x30
	vh2 "Simple Example"
that looks like:

Here is an example that places multiple faces on top of each other:
	at 0x0
	backdrop effect [gradient 0x1 gray]
	at 70x70
	box effect [gradient 1x1]
	at 50x50
	box effect [gradient 1x1 200.0.0 0.0.100]
	at 30x30
	vtext bold italic 100 {This is an example of locating
		two faces using absolute positioning.}
	at 20x160
	button 40 "OK"
The result would be:

10.2. Tabs Keyword
TABS specifies the tab spacing that is used when a TAB word is encountered. The direction of the tab (horizontally or vertically) depends on the current direction of the layout as specified by BELOW and ACROSS.
To set the tab spacing an integer provides regular spacing of that amount:
	across
	tabs 150
	vh3 "Buttons:"
	tab
	button "Button 1"
	tab
	button "Button 2"
The result is:

Fixed tab positions can also be provided with a block of integers. In this example two tab-stops are defined to align the result:
	across
	tabs [80 200]
	h2 "Line 1"
	tab field 100
	tab field 100
	return
	h3 "Line 2"
	tab check
	text "Check"
	tab button "Ok"
	return
	h4 "Line 3"
	tab button "Button 1"
	tab button "Button 2"
This produces:

Note that tabs also apply vertically and tabs can be changed at any time in a layout. For example:
	tabs 40
	field "Field 1"
	field "Field 2"
	field "Field 3"
	return
	across
	tabs 100
	button "Button 1"
	button "Button 2"
	button "Button 3"
displays:

10.3. Tab Keyword
TAB skips forward in the current direction (across or below) to the next tab position. Tabs positions are set with the TABS keyword. See the TABS description for more examples
The example:
	across
	tabs 80
	text "Name"  tab field return
	text "Email" tab field return
	text "Phone" tab field return
produces:

10.4. Guide Keyword
GUIDE sets the return margin for face layout. When the RETURN word is used, an invisible guide-line determines where the next face will be placed. Guides can be thought of as virtual borders that align the placement of faces. If the guide has not been set, it defaults to be the origin.
A guide can be created by specifying a position, or if no position is provided, then the current position will be used. This example shows a heading, then creates a guide for the remaining faces:
	across
	vh2 "Guides"
	guide 60x100
	label "Name:" 100x24 right
	field
	return
	label "Address:" 100x24 right
	field
	return
This example creates:

Here is a good example of a problem that is solved by a guide. The layout below creates an undesired effect:
	vh2 "Without A Guide:"
	button "Button 1"
	button "Button 2"
	return
	button "Button 3"
	button "Button 4"
that is shown here:

If a GUIDE is added after the heading:
	vh2 "With A Guide:"
	guide
	button "Button 1"
	button "Button 2"
	return
	button "Button 3"
	button "Button 4"
the buttons will be aligned:

11. Style Definition [rev]

11.1. Custom Styles
You can define your own styles. This is useful if you use a style with the same facets multiple times in your layout. Defining your own style will make it easier to write and easier to modify your script later.
For instance, the code:
	text black 200x24 bold "This"
	text black 200x24 bold "is"
	text black 200x24 bold "an"
	text black 200x24 bold "example"
would be easier to write if a new style called txt where defined:
	txt "This"
	txt "is"
	txt "an"
	txt "example"
The new style can be created in two ways. Styles can be defined in a layout, or they can be created in a stylesheet and applied to a layout.

11.2. Styles in Layouts
To create a style that is defined only within a layout, use the style keyword. In this example, the txt style is created:
    style txt text black 200x24 bold
	txt "This"
	txt "is"
	txt "an"
	txt "example"
The style word is followed by the new style name, a base style to begin with, and a set of facets that modify it. Any facets can be supplied as part of the style, including text, images, and action.
The txt style is only valid within the layout block. It can be used within the block or within any subpanels or lists created by the block. However, if you attempt to use the style outside the block an error will occur.
Any number of custom styles can be added to the layout block.

11.3. Creating Stylesheets
To create custom styles for multiple layouts, you will need to create a stylesheet with the stylize function.
	new-styles: stylize [
	    txt: text black 200x24 bold
	    btn: button 80x24 effect [gradient 0x1 0.80.0]
	    fld: field 100x24
	]
Each new style is written as a set word followed by a base style and list of facets.
To use the stylesheet within a layout, include it with a styles keyword:
	view layout [
	    styles new-styles
		txt "Text"
	    btn "Button"
	    fld "Field"
	]
A layout can contain any number of styles from any combination of stylesheets and styles.

11.4. Style Keyword
STYLE defines a new style that is local to the current layout. The format of the style begins with the new style name and is followed by a normal layout face specification.
	style blue-text text blue center 200
Once a style has been defined, it can be used just like any other style:
	blue-text "Blue Text Here"
It is common to define a new button style in a layout:
	style btn button 80x22 leaf

	btn "Test" [print "Test button pressed"]
	btn "This" [print "This button pressed"]
Predefined styles can be redefined with the STYLE word. For example, this line will redefine the BUTTON style used within a layout:
	style button button green 120x30 
Such changes are local to the layout and do not affect the button style used in other layouts.

11.5. Styles Keyword
STYLES allows you to use a predefined stylesheet in one or more layouts. When a stylesheet is provided, those styles become available to the layout.
A stylesheet is created with the STYLIZE function. Styles are defined similar to a layout, but with the new style name appearing as a variable definition.
	big-styles: stylize [
		btn: button 300x40 navy maroon font-size 16
		fld: field 300x40 bold font-size 16 middle center
		lab: text 300x32 font-size 20 center middle red black
	]
The new styles and their names are encapsulated within the stylesheet and can be used in any layout.
	styles big-styles
	lab "Enter CPU Serial Number:"
	fld "#000-0000"
	lab "Press to Eject CPU:"
	btn "Eject Now"
	btn "Cancel"
Any number of stylesheets can be used within a layout.

12. Other Keywords

12.1. Do Keyword
DO evaluates an expression during the process of making a layout.
	h2 "Introduction:"
	do [
		intro: either exists? %intro.txt [read %intro.txt]["NA"]
	]
	txt intro
Note that the DO is only evaluated once; when the layout is created. It is not evaluated when the layout face is shown.

13. Variables

13.1. Position Variables
When creating a layout, you will sometimes need to know the position of a face on the page. To do this, a position variable can be set before any layout keyword.
For instance, a convenient way to get the current position is with the AT word. If you provide it with no new position, it will simply set a variable to the current position:
	here: at
The variable here will hold the current position.
This can be useful if you need to use a position later in your layout. You may want to lay one face on top of another. Here is an example that places text on top of a transparent box:
	backdrop %nyc.jpg
	banner "Example"
	here: at
	box 200x100 effect [multiply 60]
	at here + 10x10
	vtext bold 200x100 - 20x20 {
	   This text is on top of the smoked
	   glass, regardless of how the screen
	   may layout.  That is the benefit of
	   using a variable to set the position.
	}
13.2. Face Variables
Some of the faces that you use in a layout will need to be changed when the page is being displayed. For instance, the action of a button may trigger a change in text or images that are displayed.
To obtain the face that was created with a style, set a variable just before the style word. For example, here the variable name will refer to the text face that is created:
	name: text "Merlot" 100x30
At another point on the page the text can be changed with a button that modifies the face's contents:
	button "Change" [name/text: "Cabernet"  show name]
When the button is pressed, the text field of the name face will be changed to "Cabernet". The show function is then used to update the face in the window so the change can be seen.

13.3. Avoiding Variable Collisions
For large scripts that have a lot of position and face variables, it may become difficult to manage all of the names and keep them from interfering with each other. A simple solution to this problem is to define pages within objects that have the required variables defined locally to the objects. For instance here is an address book form that keeps all of its variables local:
	make object! [
	    title-name: name: email: phone: none
	    num: 1
	    page1: layout [
	        title-name: title "Person 1:"
	        box 200x3 red
	        across
	        text "Name"  tab name: field return
	        text "Email" tab email: field return
	        text "Phone" tab phone: field return
	        button "Send" [
	            send luke@rebol.com [
	                "Person " num newline
	                name email phone newline
	            ]
	            num: num + 1
	            title-name/text: reform [Person num]
	            clear name/text
	            clear email/text
	            clear phone/text
	            show [title-name name email phone]
	        ]
	    ]
	]
Be sure to add any new variables to the object definition.

14. Layout Dialect Keywords

14.1. Layout Organization
As described in previous documents (soon), the layout dialect consists of:

Layout keywords that describe face positioning and other layout attributes (see below).

Face styles that are used to specify the faces that are displayed. These can be predefined styles (see Predefined Styles document) or custom styles.

Variable definitions that hold either faces or layout positions. These variables can be used later to access face objects or to affect face positions.

New style definitions that are to be used within the layout. Single styles or entire stylesheets can be provided.

This document will describe the layout keywords.
Note that all layout keywords are optional and most keywords can be used multiple times.

14.2. Layout Attributes
These words control the layout as it is being created. They affect the placement of faces within the layout.

Offset
OFFSET specifies the position of the layout face within its parent face (often the screen). (NA prior to Link 0.4.35)
	offset 10x32
The offset need not be specified in the layout. It can be specified in the View if necessary. The default offset is 25x25.

Size
SIZE sets the size of the layout face. This must be done at the beginning of a layout before any styles are used.
	size 800x600
If no size is specified, then the layout is auto-sized based on the styles used within it.

Origin
ORIGIN sets the starting position of faces in the layout. The origin is specified as the number of pixels from the upper left corner of the layout window. The default origin is 20x20.
	origin 100x100
	text "Origin at 100x100"
If an integer is specified, then both the X and Y positions will be set to that value:
	origin 100
	text "Origin at 100x100"
The origin can also be used within a layout to return the layout to the origin position.
	origin
	text "Back at the origin" 
The origin value also determines the amount of spacing between the last face and the bottom right of the layout.
Setting the origin is especially important when creating panels and lists. Frequently the origin in lists is set to zero:
	list 400x80 [
		origin 0
		across
		txt 100
		txt 200
	] data [
		["Bobbie" "Smith"]
		["Barbie" "Jones"]
		["Bettie" "Rebol"]
	]
Space
SPACE sets the auto-spacing to use between faces within the layout. The spacing can be changed at any time within your layout. Either a pair or an integer can be given. If you specify a pair, both the vertical and horizontal spacing is set.
	space 5x8
If you specify an integer, only the spacing in the current direction (across or below) is set.
	space 5
Below
BELOW sets the direction of the layout to be vertical for faces that follow it. That is, the next face will be positioned below the current face. This can be changed at any time during a layout.
	below
	button "Yes"
	button "No"
	button "Cancel"
BELOW is the default layout direction.

Across
ACROSS sets the direction of the layout to be horizontal for faces that follow it. That is, the next face will be position to the right of the current face. This can be changed at any time during a layout.
	across
	button "Yes"
	button "No"
	button "Cancel"
Tabs
TABS specifies the tab spacing that is used when a TAB word is encountered. The direction of the tab (horizontally or vertically) depends on the current direction of the layout as specified by BELOW and ACROSS.
To set the tab spacing an integer provides regular spacing of that amount:
	tabs 160
Fixed tab positions can also be provided with a block of integers:
	tabs [120 280 440 620]
Tabs can be changed at any time in a layout.

Guides
GUIDE sets the return margin for face layout. When the RETURN word is used, the GUIDE will determine where the next face will be placed. They can be thought of as virtual borders that align the placement of faces.
A guide can be created by specifying a position, or if no position is provided, then the current position will be used.
	across
	guide 100x100
	txt "Name:" 100x24 right
	field
	return
	txt "Address:" 100x24 right
	field
	return
14.3. Positioning and Spacing
These words affect the positioning of faces that follow them. Both absolute and relative positioning are supported.

At
AT sets an absolute layout position for the face that follows it.
	at 100x100
	image %face.jpg
With AT you can change the next position of the layout or even place multiple faces on top of each other:
	at 100x100
	box 200x200 navy
	at 110x110
	text "This text is on top of the box face." 180
Pad
PAD inserts extra spacing between the current position and the position of the next face. The distance can be specified as an integer or a pair. When it is a pair, the space will be added both horizontal and vertically.
	text "Image Below"
	pad 10x20
	image %photo.jpg
When the PAD is given an integer, space is either vertical or horizontal depending on the current direction of auto layout (determined by below and across words).
	below
	txt "Word"
	pad 40
	txt "Here"

	across
	txt "Word"
	pad 40
	txt "Here"
Indent
INDENT inserts spacing horizontally between the current position and the next face. It is not affected by the auto layout direction.
	title "About VID"
	indent 20
	body "This section is about VID."
Tab
TAB skips forward in the current direction (across or below) to the next tab position. Tabs positions are set with the TABS keyword.
	across
	tabs 68
	text "Name"  tab field return
	text "Email" tab field return
	text "Phone" tab field return
Return
RETURN advances the position to the next row or column, depending on the layout direction. If the layout direction is across, return will start a new row. If the direction is below, return will start a new column.
	across
	txt "Name:" 100x24 right
	field "Your name"
	return
	txt "Address:" 100x24 right
	field "Your address"
	return
The position of the column is relative to the origin or to a guide.

14.4. Style Definition
Style
STYLE defines a new style that is local to the current layout. The format of the style begins with the new style name and is followed by a normal layout face specification.
	style blue-text text blue center 200
Once a style has been defined, it can be used just like any other style:
	blue-text "Blue Text Here"
It is common to define a new button style in a layout:
	style btn button 80x22 leaf

	btn "Test" [print "Test button pressed"]
	btn "This" [print "This button pressed"]
Predefined styles can be redefined with the STYLE word. For example, this line will redefine the BUTTON style used within a layout:
	style button button green 120x30 
Such changes are local to the layout and do not affect the button style used in other layouts.

Styles
STYLES allows you to use a predefined stylesheet in one or more layouts. When a stylesheet is provided, those styles become available to the layout.
A stylesheet is created with the STYLIZE function. Styles are defined similar to a layout, but with the new style name appearing as a variable definition.
	big-styles: stylize [
		btn: button 300x40 navy maroon font-size 16
		fld: field 300x40 bold font-size 16 middle center
		lab: txt 300x32 font-size 20 center middle red black
	]
The new styles and their names are encapsulated within the stylesheet and can be used in any layout.
	styles big-styles
	lab "Enter CPU Serial Number:"
	fld "#000-0000"
	lab "Press to Eject CPU:"
	btn "Eject Now"
	btn "Cancel"
Any number of stylesheets can be used within a layout.

14.5. Other Keywords
Do
DO evaluates an expression during the process of making a layout.
	h2 "Introduction:"
	do [
		intro: either exists? %intro.txt [read %intro.txt]["NA"]
	]
	txt intro
Note that the DO is only evaluated once; when the layout is created. It is not evaluated when the layout face is shown.
	Copyright 2001 REBOL Technologies

15. Facets

Facets are attributes of a face. Facets include the face's location, size, color, image, font, style, paragraph format, rendering effects, behavior functions, and other details. Some facets are objects themselves, allowing the sharing of attributes several faces.

15.1. View Facets
These are the primary facets used by the View display system to show faces. These facets can be inherited from the SYSTEM/view/face object which is also defined globally as the FACE object.

offset An X-Y PAIR that specifies the horizontal and vertical position of the face. If a face is outside it's parent face it will be clipped. Defaults to 0x0.

size An X-Y PAIR that specifies the width and height of the face. Defaults to 100x100.

span An optional X-Y PAIR that specify the range of a virtual coordinate system to use for the face. This can be used to create resolution independent displays. Normally this is set to NONE.

pane A face or block of sub-faces that are to be displayed within the face. This allows you to create faces that contain faces to any degree.

text The text contents of a face. The attributes of the text are determined by the FONT and PARA facets. Any printable value can be used.

data Used by VID for storing other information about the face. Outside of VID this field can be freely used by programs.

color The color of the face, specified as a TUPLE. When set to NONE the face is transparent. Default value is 128.128.128.

image An IMAGE to use for the face's body. This must be an IMAGE value not a file name. A wide range of image processing effects can be performed on the image with the EFFECT field.

effect A WORD or BLOCK that renders image processing effects on the face image or background. More than one effect can be used at the same time.

edge An OBJECT that specifies the edge of the face. It can include the color, size, and effects used for the edge.

font An OBJECT that specifies the font used for the text. This includes the font name, style, size, color, offset, space, align, and other attributes.

para An OBJECT that describes the paragraph characteristics of the text. It includes the origin, margin, indent, tabs, edit, wrap, and scrolling attributes.

feel An OBJECT that holds the functions that define the behavior of the face. These functions are evaluated during the rendering, selection, and hovering over a face and during events related to the face.

rate An INTEGER or TIME that specifies the rate of time events for a face. This is used for animation or repetitive events (such as holding the mouse down on certain types of user interface styles). An INTEGER indicates the number of events per second. A TIME provides the period between events.

options A BLOCK of optional flags for the face. These are normally used by a top-level view face. Options include NO-TITLE, RESIZE, NO-BORDER, ALL-OVER.

saved-area Enables faster rendering for transparent faces. When a face is transparent on a static (unchanging) backdrop, this field can be set to TRUE to accelerate redrawing. The face can change without requiring the backdrop to be rendered each time. The pixels for the area under the face will be saved into this field, changing it from a TRUE to an IMAGE. This field defaults to NONE.

line-list A BLOCK that is used to track the offsets of text lines when text is being displayed. When more than 200 characters of text are being displayed, this list should be set to NONE when large changes are made to the text. This allows REBOL to recalculate the locations of all TEXT lines.

VID Extensions
VID extends the face definition to include these additional facets. Faces that are created with the LAYOUT or MAKE-FACE functions will include these facets in addition to those described above.

colors A BLOCK of alternate colors used for the face. For example, this field would hold the colors for a button that changes colors on being selected.

texts A BLOCK of alternate text used for the face. For example, buttons that display different text on selection would store that text here.

effects A BLOCK of alternate effects used for a face. For example, a BUTTON style may use a different effect when it is in the down position.

action A BLOCK or FUNCTION that is evaluated when the face has been selected. The type of event that triggers this action depends on the style of the face.

alt-action An alternate BLOCK or FUNCTION that is evaluated on an alternate selection of the face.

keycode A CHAR or BLOCK of shortcut keys for the face. When pressed, these keys will evaluate the ACTION field.

state The event state of buttons. Indicates that the button is still being pressed.

dirty? A LOGIC flag that indicates that the text of the face has been modified. Whenever editing is performed upon a text face, this flag will be set to TRUE.

help An optional string that can be used for displaying information about a button or other type of GUI element. For example, when the mouse pointer hovers over a face, this string can be displayed as help information.

file The FILE path or URL of the image file used for the face. The image file is automatically loaded and cached by VID.

style The style WORD that was used to create the face. For example: BUTTON, FIELD, IMAGE, RADIO, etc.

user-data A field that is available to programs for storing data related to the face. This field is not used by the VID system.

15.2. Edge Facet
The EDGE facet is an object that describes a rectangular frame that borders a face. It is used for creating image frames, button edges, table cell dividers, and other border effects. An edge is specified as an sub-object within the face object.
An EDGE object contains these fields:

color The color of the edge specified as a TUPLE.

size An X-Y PAIR that specifies the thickness of the edge. The x value refers to the thickness of the vertical edges on the left and right, and the Y value refers to the horizontal edges at the top and bottom.

effect A WORD or BLOCK that describes the effect to use for the edge. Edge effects include BEVEL, IBEVEL, BEZEL, IBEZEL, and NUBS.

15.3. Font Facet
The FONT facet is an object that describes the attributes of the text to be used within a face. The font is specified as an sub-object within the face object.
The FONT object contains these fields:

name The name of the font to use for the text. There are three predefined variables for machine independent fonts that have a similar appearance: font-serif (times-like), font-sans-serif (helvetica-like), and font-fixed (courier fixed width). To create machine independent programs, avoid specifying custom fonts. The default is font-sans-serif.

size An INTEGER that specifies the point size of the font. The default size is 12.

style A WORD or BLOCK of words that describe the style of the text. Choices are: BOLD, ITALIC, and UNDERLINE. When set to NONE no styles are used (default).

color A TUPLE that specifies the color of the text. The default color is black (0.0.0).

align A WORD that provides the alignment of the text within the face. Choices are: LEFT, RIGHT, and CENTER.

valign A WORD that indicates the vertical alignment of the text within the face. Choices are: TOP, BOTTOM, and MIDDLE.

offset A PAIR that specifies the offset of the text from the upper left corner of the face. The PARA facet object also has an effect on this offset. Default is 2x2.

space A PAIR that specifies the spacing between characters and between lines. The x value affects the spacing between characters. The y value changes the spacing between lines. Positive values expand the text, negative values condense it. The default is 0x0.

shadow A PAIR that specifies the direction and offset of the drop shadow to use for the text. Positive values project a shadow toward the lower right corner. Negative values project toward the upper left. The default is NONE.

15.4. Para Facet
The PARA facet is an object that controls the formatting of text paragraphs within the face. A para is specified as a sub-object within a face object.
The PARA object contains these fields:

origin An X-Y PAIR that specifies the offset of the text from the upper left corner of a face. The default is 2x2.

margin An X-Y PAIR that specifies the right-most and bottom limits of text display within the face. The position is relative to the bottom right corner of the face. The default is 2x2.

indent An X-Y PAIR that specifies the offset of a the first line of a paragraph. The X value specifies the indentation used for the first line of the paragraph. Positive and negative values may be used. The Y value specifies the spacing between the end of the previous paragraph and the first line of the next paragraph. The Y value has no affect on the first paragraph. The default is 0x0.

scroll An X-Y PAIR used for horizontal and vertical scrolling of text within a face. The scroll amount that modifies the offset of the text relative to the face. The origin and margin values are not affected. The default is 0x0.

tabs An INTEGER or BLOCK of integers that provide the tab spacing used within a paragraph. An INTEGER value indicates a fixed tab size spaced at regular intervals across the text. A BLOCK of integers provides the precise horizontal offset positions of each TAB in order. The default is 40.

wrap? A LOGIC value that indicates that automatic line wrapping should occur. When set to TRUE, text that exceeds the margin will be automatically wrapped to the origin. When set to FALSE, text will not be wrapped.

15.5. Feel Facet
The FEEL facet controls face's behavior in response system events like redraw, mouse input, and keyboard input. The fields of the feel object are all functions that are called by the View system on specific events. A summary of these functions is provided below. See the Face Feeling chapter for details.
The FEEL object contains these fields:

engage The primary function called for the majority of events that occur within a face. The ENGAGE function is called when the mouse pointer is over it's face and either mouse button is pressed. The function will also be called if a mouse button has been pressed and the mouse is moved over the face. In addition, the function is called when time events occur, such as for animation or repetitive selection events.

over This function is called when the mouse pointer passes over the face and no buttons are pressed. This allows code to capture hover events and provide user feedback by changing the appearance of the face. For example, hot text may change the color of the text as the mouse passes over it. This field is separate from ENGAGE because it is not used for most faces. Over actions can occur at a high frequency, so setting the OVER field to NONE allows the system to ignore it.

detect This function is called each time any event passes through a face. This function can be used to process events that are directed toward any subface of the face. For example, the function is used by VID to process keyboard shortcuts. The DETECT function is normally used at the window face or screen face level. Note that the insert-event-func function should be used to trap screen-face global events.

redraw This function is called immediately before a face is displayed. Defining this function allows a face to dynamically modify any of its facets prior to being displayed. When not being used, it is critical that this function be set to NONE to speed up the display.

15.6. Effect Facet
The EFFECT facet can be set to a WORD or a BLOCK that describes image processing operations to be performed on the backdrop of a face. When a block is used, multiple effects can be specified, and they are applied in the order in which they appear within the block. A wide range of hundreds of effects can be produced.

Scaling
fit Scales an image to the size of the face, less the edge of the face if it exists. The image will be scaled both horizontally and vertically to fit within the face.

aspect Similar to FIT, but preserves the perspective of the image. The image is not distorted. If the image does not span the entire face, the remaining portion will be filled with the face background color.

extend Extends an image horizontally, vertically, or both. An image is stretched without affecting its scale. For instance, a button with rounded ends can be resized without affecting the dimensions of the rounded ends. This allows a single button bitmap to be reused over a wide variety of sizes. Two PAIRs are supplied as arguments. The first PAIR specifies the offset where the image should be extended. It can be horizontal, vertical, or both. The second PAIR specifies the number of pixels to extend in either or both directions.

Tiling
tile Repeats the image over the entire face. This allows you to apply textures that span an entire face. The tile offset will be relative to the face.

tile-view Similar to TILE, but the tile offset will be relative to the window face.

Subimages
clip Clips an image to the size of the face. This is normally done when the image is larger than the face, and the remaining effects do not need to be performed on the entire bitmap. The CLIP can be done at anytime in the effect block. For instance a CLIP done before a FLIP will produce a different result than a CLIP done after a FLIP.

crop Extracts a portion of an image. This effect takes two PAIRs: the offset into the image and the size of the area needed. This operation can be used to pick any part of an image to be displayed separately. It allows you to pan and zoom on images.

Translation
flip Flips an image vertically, horizontally, or both. A PAIR is provided as an argument to specify the direction of the flip. The X specifies horizontal and the Y specifies vertical.

rotate Rotates an image. An INTEGER specifies the number of degrees to rotate in the clockwise direction. (Currently only 0, 90, 180, and 270 degree rotations are supported.)

reflect Reflects an image vertically, horizontally, or both. A PAIR is used to indicate the direction of reflection. The X value will reflect horizontally, and the Y value will reflect vertically. Negative and positive values specify which portion of the image is reflected.

Image Processing
invert Inverts the RGB values of an image. (Inversion is in the RGB color space.)

luma Lightens or darkens an image. An INTEGER specifies the degree of the effect. Positive values lighten the image and negative values darken the image.

contrast Modifies the contrast of the image. An INTEGER specifies the degree of the effect. A positive value increases the contrast and a negative value reduces the contrast.

tint Changes the tint of the image. An INTEGER specifies the color phase of the tint.

grayscale Converts a color image to black and white.

colorize Colors an image. A TUPLE specifies the COLOR. The image is automatically converted to grayscale before it is colorized. [Note - IMAGE arg should also be allowed.]

multiply Multiplies each RGB pixel of an image to produce interesting coloration. An INTEGER, TUPLE, or IMAGE can be specified. An INTEGER will multiply each color component of each pixel by that amount. A TUPLE will multiply each of the red, green, and blue components separately. An IMAGE will multiply the red, green, and blue components of an image, allowing you to apply textures to existing images. [Note - how to divide]

difference Computes a difference of RGB pixel values. This can be used to compare two images to detect differences between them. An IMAGE is provided as an argument. Each of its RGB pixel values will be subtracted from the face image.

blur Blurs an image. This effect may be used multiple times to increase the effect.

sharpen Sharpens an image. This effect may be used multiple times to increase the effect.

emboss Applies an emboss effect to the image.

Gradients
gradient Generates a color gradient. A PAIR and two color TUPLEs can be supplied as arguments (optional). The PAIR is used to determine the direction of the gradient. The X value of one specifies horizontal and a Y value of one specifies vertical. Both X and Y can be specified at the same time, producing a gradient in both directions. Negative values reverse the gradient in that direction.

gradcol Colorizes an image to a gradient. Arguments are identical to GRADIENT. The image is colorized according to the colors of the gradient.

gradmul Multiplies an image over a gradient. Arguments are identical to GRADIENT. The image is multiplied according to the colors of the gradient.

Keys
key Creates a transparent image by keying. A TUPLE or INTEGER can specify a chroma or luma key effect. A TUPLE will cause all pixels of the same value to become transparent. An INTEGER will cause all pixels with lesser luma values to become transparent.

shadow Creates a drop shadow on a keyed image. Accepts the same arguments as KEY, but in addition to a creating transparent image it generates a 50 percent drop shadow.

Algorithmic Shapes
A few shapes can be algorithmically generated to reduce the need for images in some frequently used cases.

arrow Generate an arrow image. An optional TUPLE can be used to specify the color of the arrow, otherwise the edge color will be used. The arrow is proportional to the size of the face. The direction of the arrow can be altered with FLIP or ROTATE.

cross Generate an X cross image. This is used for check boxes. An optional TUPLE can be used to specify the color of the cross, otherwise the edge color will be used. The cross is proportional to the size of the face.

oval Generate a oval image. An optional TUPLE can be used to specify the color of outside of the oval, otherwise the edge color will be used. The oval will be proportional to the size of the face.

tab Generate tab buttons with rounded corners. The optional arguments are: a PAIR that specifies the edge to round, a TUPLE that is used as an edge color, an INTEGER that indicates the radius of the curves, and an INTEGER that controls the thickness of the edge.

grid Generate a two dimensional grid of lines. This is a useful backdrop for graphical layout programs. The optional arguments are: a PAIR that specifies the horizontal and vertical spacing of the grid lines, a PAIR that specifies the offset of the first lines, a PAIR that indicates the THICKNESS of the horizontal and vertical lines, and a TUPLE that provides the color of the lines.

draw Draws simple lines, shapes, and fills within a face. See the Draw Dialect document for detailed information.

Keywords	Layout keywords that describe face positioning and other layout attributes.
Styles	Face styles that are used to specify the faces that are displayed. These can be predefined styles like TITLE, BUTTON, FIELD, TEXT, or your own custom styles.
Facets	Attributes that describe variations in the style of a face, such as the size, color, alignment, border, or image.
Variables	Definitions that hold either faces or layout positions. These variables can be used later to access face objects or to affect face positions.
Styledefs	New style definitions that are to be used within the layout. Single styles or entire stylesheets can be provided.

/size	A PAIR! that specifies the size of the resulting face. This forces the face to be of a fixed size before the layout is performed. The default is to size the face dynamically based on the placement of items within the layout.
/offset	A PAIR! that provides the offset to where the window will be displayed within its parent face (often the screen).
/styles	A stylesheet block that was created with the STYLIZE function. A stylesheet defines custom styles used within the layout. This is equivalent to the STYLES keyword within a layout.
/origin	A PAIR! that sets the pixel offset to the first face within the layout. This is equivalent to the ORIGIN keyword within a layout.
/parent	Specifies the style of the top-level face that is produced from the layout. The parent can be specified as a style name or as an actual instance of the style.
/options	Specifies the VIEW options when the face is displayed with the VIEW function. See the VIEW function for details.

across	Set auto-layout to horizontal direction.
at	Locate a face to an absolute position.
backcolor	Set the color of the background.
below	Set auto-layout to vertical direction.
do	Evaluate a block.
guide	Set a guide line.
indent	Indent horizontally.
offset	Set the output face position.
origin	Specify the layout starting position.
pad	Insert extra spacing.
return	Return to the current guide position.
style	Define a custom style.
styles	Use styles from a stylesheet.
space	Set the auto-spacing used between faces.
size	Set the output face size.
tabs	Set tab stops.
tab	Advance to next tab position.

title	Document title heading.
h1	Top level heading used for documents.
h2	Heading use for document sections.
h3	Heading used for subsections.
h4	Heading used below subsections.
h5	Heading used below subsections.
banner	Title heading with video style.
vh1	Section heading used for video style.
vh2	Section heading used for video style.
vh3	Section heading used for video style.
text	Document body text.
txt	An alias for TEXT style above.
vtext	Inverse video body text.
tt	The teletype font for fixed width text.
code	Same as TT except defaults to bold.
label	Used for specifying GUI text labels.
field	Text entry field.
info	Same as FIELD style, but read-only.
area	Text editing area for paragraph entry.
sensor	An invisible face that senses mouse events.
image	Display a JPEG, BMP, PNG, or GIF image.
box	A shortcut for drawing a rectangular box.
backdrop	Scale an image over the entire layout window.
backtile	Tile an image over the entire layout window.
icon	Display a thumbnail sized image with text caption.
led	An indicator light.
anim	Display an animated image.
button	A button that goes down on a click.
toggle	Similar to BUTTON but has a dual state.
rotary	Similar to BUTTON but allows multiple states.
choice	A pop-up button that displays multiple choices.
check	A check box.
radio	A rounded radio button.
arrow	An arrow button with a beveled edge.
progress	A sliding progress bar.
slider	A slider bar.
panel	A sub-layout.
list	An iterated sub-layout.
text-list	A simple form of the LIST style.
key	Keyboard shortcut.

offset	An X-Y PAIR that specifies the horizontal and vertical position of the face. If a face is outside it's parent face it will be clipped. Defaults to 0x0.
size	An X-Y PAIR that specifies the width and height of the face. Defaults to 100x100.
span	An optional X-Y PAIR that specify the range of a virtual coordinate system to use for the face. This can be used to create resolution independent displays. Normally this is set to NONE.
pane	A face or block of sub-faces that are to be displayed within the face. This allows you to create faces that contain faces to any degree.
text	The text contents of a face. The attributes of the text are determined by the FONT and PARA facets. Any printable value can be used.
data	Used by VID for storing other information about the face. Outside of VID this field can be freely used by programs.
color	The color of the face, specified as a TUPLE. When set to NONE the face is transparent. Default value is 128.128.128.
image	An IMAGE to use for the face's body. This must be an IMAGE value not a file name. A wide range of image processing effects can be performed on the image with the EFFECT field.
effect	A WORD or BLOCK that renders image processing effects on the face image or background. More than one effect can be used at the same time.
edge	An OBJECT that specifies the edge of the face. It can include the color, size, and effects used for the edge.
font	An OBJECT that specifies the font used for the text. This includes the font name, style, size, color, offset, space, align, and other attributes.
para	An OBJECT that describes the paragraph characteristics of the text. It includes the origin, margin, indent, tabs, edit, wrap, and scrolling attributes.
feel	An OBJECT that holds the functions that define the behavior of the face. These functions are evaluated during the rendering, selection, and hovering over a face and during events related to the face.
rate	An INTEGER or TIME that specifies the rate of time events for a face. This is used for animation or repetitive events (such as holding the mouse down on certain types of user interface styles). An INTEGER indicates the number of events per second. A TIME provides the period between events.
options	A BLOCK of optional flags for the face. These are normally used by a top-level view face. Options include NO-TITLE, RESIZE, NO-BORDER, ALL-OVER.
saved-area	Enables faster rendering for transparent faces. When a face is transparent on a static (unchanging) backdrop, this field can be set to TRUE to accelerate redrawing. The face can change without requiring the backdrop to be rendered each time. The pixels for the area under the face will be saved into this field, changing it from a TRUE to an IMAGE. This field defaults to NONE.
line-list	A BLOCK that is used to track the offsets of text lines when text is being displayed. When more than 200 characters of text are being displayed, this list should be set to NONE when large changes are made to the text. This allows REBOL to recalculate the locations of all TEXT lines.

colors	A BLOCK of alternate colors used for the face. For example, this field would hold the colors for a button that changes colors on being selected.
texts	A BLOCK of alternate text used for the face. For example, buttons that display different text on selection would store that text here.
effects	A BLOCK of alternate effects used for a face. For example, a BUTTON style may use a different effect when it is in the down position.
action	A BLOCK or FUNCTION that is evaluated when the face has been selected. The type of event that triggers this action depends on the style of the face.
alt-action	An alternate BLOCK or FUNCTION that is evaluated on an alternate selection of the face.
keycode	A CHAR or BLOCK of shortcut keys for the face. When pressed, these keys will evaluate the ACTION field.
state	The event state of buttons. Indicates that the button is still being pressed.
dirty?	A LOGIC flag that indicates that the text of the face has been modified. Whenever editing is performed upon a text face, this flag will be set to TRUE.
help	An optional string that can be used for displaying information about a button or other type of GUI element. For example, when the mouse pointer hovers over a face, this string can be displayed as help information.
file	The FILE path or URL of the image file used for the face. The image file is automatically loaded and cached by VID.
style	The style WORD that was used to create the face. For example: BUTTON, FIELD, IMAGE, RADIO, etc.
user-data	A field that is available to programs for storing data related to the face. This field is not used by the VID system.

color	The color of the edge specified as a TUPLE.
size	An X-Y PAIR that specifies the thickness of the edge. The x value refers to the thickness of the vertical edges on the left and right, and the Y value refers to the horizontal edges at the top and bottom.
effect	A WORD or BLOCK that describes the effect to use for the edge. Edge effects include BEVEL, IBEVEL, BEZEL, IBEZEL, and NUBS.

name	The name of the font to use for the text. There are three predefined variables for machine independent fonts that have a similar appearance: font-serif (times-like), font-sans-serif (helvetica-like), and font-fixed (courier fixed width). To create machine independent programs, avoid specifying custom fonts. The default is font-sans-serif.
size	An INTEGER that specifies the point size of the font. The default size is 12.
style	A WORD or BLOCK of words that describe the style of the text. Choices are: BOLD, ITALIC, and UNDERLINE. When set to NONE no styles are used (default).
color	A TUPLE that specifies the color of the text. The default color is black (0.0.0).
align	A WORD that provides the alignment of the text within the face. Choices are: LEFT, RIGHT, and CENTER.
valign	A WORD that indicates the vertical alignment of the text within the face. Choices are: TOP, BOTTOM, and MIDDLE.
offset	A PAIR that specifies the offset of the text from the upper left corner of the face. The PARA facet object also has an effect on this offset. Default is 2x2.
space	A PAIR that specifies the spacing between characters and between lines. The x value affects the spacing between characters. The y value changes the spacing between lines. Positive values expand the text, negative values condense it. The default is 0x0.
shadow	A PAIR that specifies the direction and offset of the drop shadow to use for the text. Positive values project a shadow toward the lower right corner. Negative values project toward the upper left. The default is NONE.

origin	An X-Y PAIR that specifies the offset of the text from the upper left corner of a face. The default is 2x2.
margin	An X-Y PAIR that specifies the right-most and bottom limits of text display within the face. The position is relative to the bottom right corner of the face. The default is 2x2.
indent	An X-Y PAIR that specifies the offset of a the first line of a paragraph. The X value specifies the indentation used for the first line of the paragraph. Positive and negative values may be used. The Y value specifies the spacing between the end of the previous paragraph and the first line of the next paragraph. The Y value has no affect on the first paragraph. The default is 0x0.
scroll	An X-Y PAIR used for horizontal and vertical scrolling of text within a face. The scroll amount that modifies the offset of the text relative to the face. The origin and margin values are not affected. The default is 0x0.
tabs	An INTEGER or BLOCK of integers that provide the tab spacing used within a paragraph. An INTEGER value indicates a fixed tab size spaced at regular intervals across the text. A BLOCK of integers provides the precise horizontal offset positions of each TAB in order. The default is 40.
wrap?	A LOGIC value that indicates that automatic line wrapping should occur. When set to TRUE, text that exceeds the margin will be automatically wrapped to the origin. When set to FALSE, text will not be wrapped.

engage	The primary function called for the majority of events that occur within a face. The ENGAGE function is called when the mouse pointer is over it's face and either mouse button is pressed. The function will also be called if a mouse button has been pressed and the mouse is moved over the face. In addition, the function is called when time events occur, such as for animation or repetitive selection events.
over	This function is called when the mouse pointer passes over the face and no buttons are pressed. This allows code to capture hover events and provide user feedback by changing the appearance of the face. For example, hot text may change the color of the text as the mouse passes over it. This field is separate from ENGAGE because it is not used for most faces. Over actions can occur at a high frequency, so setting the OVER field to NONE allows the system to ignore it.
detect	This function is called each time any event passes through a face. This function can be used to process events that are directed toward any subface of the face. For example, the function is used by VID to process keyboard shortcuts. The DETECT function is normally used at the window face or screen face level. Note that the insert-event-func function should be used to trap screen-face global events.
redraw	This function is called immediately before a face is displayed. Defining this function allows a face to dynamically modify any of its facets prior to being displayed. When not being used, it is critical that this function be set to NONE to speed up the display.

fit	Scales an image to the size of the face, less the edge of the face if it exists. The image will be scaled both horizontally and vertically to fit within the face.
aspect	Similar to FIT, but preserves the perspective of the image. The image is not distorted. If the image does not span the entire face, the remaining portion will be filled with the face background color.
extend	Extends an image horizontally, vertically, or both. An image is stretched without affecting its scale. For instance, a button with rounded ends can be resized without affecting the dimensions of the rounded ends. This allows a single button bitmap to be reused over a wide variety of sizes. Two PAIRs are supplied as arguments. The first PAIR specifies the offset where the image should be extended. It can be horizontal, vertical, or both. The second PAIR specifies the number of pixels to extend in either or both directions.

tile	Repeats the image over the entire face. This allows you to apply textures that span an entire face. The tile offset will be relative to the face.
tile-view	Similar to TILE, but the tile offset will be relative to the window face.

clip	Clips an image to the size of the face. This is normally done when the image is larger than the face, and the remaining effects do not need to be performed on the entire bitmap. The CLIP can be done at anytime in the effect block. For instance a CLIP done before a FLIP will produce a different result than a CLIP done after a FLIP.
crop	Extracts a portion of an image. This effect takes two PAIRs: the offset into the image and the size of the area needed. This operation can be used to pick any part of an image to be displayed separately. It allows you to pan and zoom on images.

flip	Flips an image vertically, horizontally, or both. A PAIR is provided as an argument to specify the direction of the flip. The X specifies horizontal and the Y specifies vertical.
rotate	Rotates an image. An INTEGER specifies the number of degrees to rotate in the clockwise direction. (Currently only 0, 90, 180, and 270 degree rotations are supported.)
reflect	Reflects an image vertically, horizontally, or both. A PAIR is used to indicate the direction of reflection. The X value will reflect horizontally, and the Y value will reflect vertically. Negative and positive values specify which portion of the image is reflected.

invert	Inverts the RGB values of an image. (Inversion is in the RGB color space.)
luma	Lightens or darkens an image. An INTEGER specifies the degree of the effect. Positive values lighten the image and negative values darken the image.
contrast	Modifies the contrast of the image. An INTEGER specifies the degree of the effect. A positive value increases the contrast and a negative value reduces the contrast.
tint	Changes the tint of the image. An INTEGER specifies the color phase of the tint.
grayscale	Converts a color image to black and white.
colorize	Colors an image. A TUPLE specifies the COLOR. The image is automatically converted to grayscale before it is colorized. [Note - IMAGE arg should also be allowed.]
multiply	Multiplies each RGB pixel of an image to produce interesting coloration. An INTEGER, TUPLE, or IMAGE can be specified. An INTEGER will multiply each color component of each pixel by that amount. A TUPLE will multiply each of the red, green, and blue components separately. An IMAGE will multiply the red, green, and blue components of an image, allowing you to apply textures to existing images. [Note - how to divide]
difference	Computes a difference of RGB pixel values. This can be used to compare two images to detect differences between them. An IMAGE is provided as an argument. Each of its RGB pixel values will be subtracted from the face image.
blur	Blurs an image. This effect may be used multiple times to increase the effect.
sharpen	Sharpens an image. This effect may be used multiple times to increase the effect.
emboss	Applies an emboss effect to the image.

gradient	Generates a color gradient. A PAIR and two color TUPLEs can be supplied as arguments (optional). The PAIR is used to determine the direction of the gradient. The X value of one specifies horizontal and a Y value of one specifies vertical. Both X and Y can be specified at the same time, producing a gradient in both directions. Negative values reverse the gradient in that direction.
gradcol	Colorizes an image to a gradient. Arguments are identical to GRADIENT. The image is colorized according to the colors of the gradient.
gradmul	Multiplies an image over a gradient. Arguments are identical to GRADIENT. The image is multiplied according to the colors of the gradient.

key	Creates a transparent image by keying. A TUPLE or INTEGER can specify a chroma or luma key effect. A TUPLE will cause all pixels of the same value to become transparent. An INTEGER will cause all pixels with lesser luma values to become transparent.
shadow	Creates a drop shadow on a keyed image. Accepts the same arguments as KEY, but in addition to a creating transparent image it generates a 50 percent drop shadow.

arrow	Generate an arrow image. An optional TUPLE can be used to specify the color of the arrow, otherwise the edge color will be used. The arrow is proportional to the size of the face. The direction of the arrow can be altered with FLIP or ROTATE.
cross	Generate an X cross image. This is used for check boxes. An optional TUPLE can be used to specify the color of the cross, otherwise the edge color will be used. The cross is proportional to the size of the face.
oval	Generate a oval image. An optional TUPLE can be used to specify the color of outside of the oval, otherwise the edge color will be used. The oval will be proportional to the size of the face.
tab	Generate tab buttons with rounded corners. The optional arguments are: a PAIR that specifies the edge to round, a TUPLE that is used as an edge color, an INTEGER that indicates the radius of the curves, and an INTEGER that controls the thickness of the edge.
grid	Generate a two dimensional grid of lines. This is a useful backdrop for graphical layout programs. The optional arguments are: a PAIR that specifies the horizontal and vertical spacing of the grid lines, a PAIR that specifies the offset of the first lines, a PAIR that indicates the THICKNESS of the horizontal and vertical lines, and a TUPLE that provides the color of the lines.
draw	Draws simple lines, shapes, and fills within a face. See the Draw Dialect document for detailed information.

REBOL/View Developer's Guide

Contents:

1. Introduction

2. Layout Concepts

2.1. Layout Structure

2.2. Simple Examples

3. Layout Function

3.1. Layout Refinements

4. Keywords

5. Face Styles

5.1. Predefined Styles

5.2. Facets

5.3. Custom Styles

6. Style Facets

6.1. Text Facets

6.2. Size Facets

6.3. Color Facets

6.4. Image Facets

6.5. Action Facets

6.6. Character Facets

6.7. Face Facet Blocks

7. Attribute Keywords

7.1. Size Keyword

7.2. Offset Keyword

7.3. Origin Keyword

8. Auto-Layout Direction

8.1. Below Keyword

8.2. Across Keyword

8.3. Return Keyword

9. Spacing

9.1. Space Keyword

9.2. Pad Keyword

9.3. Indent Keyword

10. Aligning Faces

10.1. At Keyword

10.2. Tabs Keyword

10.3. Tab Keyword

10.4. Guide Keyword

11. Style Definition [rev]

11.1. Custom Styles

11.2. Styles in Layouts

11.3. Creating Stylesheets

11.4. Style Keyword

11.5. Styles Keyword

12. Other Keywords

12.1. Do Keyword

13. Variables

13.1. Position Variables

13.2. Face Variables

13.3. Avoiding Variable Collisions

14. Layout Dialect Keywords

14.1. Layout Organization

14.2. Layout Attributes

Offset

Size

Origin

Space

Below

Across

Tabs

Guides

14.3. Positioning and Spacing

At

Pad

Indent

Tab

Return

14.4. Style Definition

Style

Styles

14.5. Other Keywords

Do

15. Facets

15.1. View Facets

VID Extensions

15.2. Edge Facet

15.3. Font Facet

15.4. Para Facet

15.5. Feel Facet

15.6. Effect Facet