REBOL [
	Title: "Easy VID Tutorial"
	Author: "Carl Sassenrath"
	Date: 7-Apr-2001 ;1-Oct-2000
	Version: 1.1.2
]

flash "Fetching image..."
read-thru/to http://www.rebol.com/view/demos/palms.jpg %palms.jpg
unview

content: {Easy VID - REBOL Visual Interface Dialect

===Introduction to VID

With REBOL/View it's easy and quick to create your own user
interfaces. The purpose of this tutorial is to teach you the
basic concepts or REBOL/View interfaces in about 20 minutes.

VID is REBOL's Visual Interface Dialect.  A dialect is an
extension of the REBOL language that makes it easier to express
or describe information, actions, or interfaces.  VID is a
dialect that provides a powerful method of describing user
interfaces.

VID is simple to learn and provides a smooth learning curve from
basic user interfaces to sophisticated distributed computing
applications.

---Creating VID Interfaces

VID interfaces are written in plain text. You can use any text
editor to create and edit your VID script. Save your script
as a text file, and run it with REBOL/View.

!Note: Using a word processor like Word or Wordpad is not
recommended because files are not normally saved as text.
If you use a word processor, be sure to save the output
file as text, not as a document (.doc) file.

===Minimal VID Example

Here is a minimal VID example.  It creates a window that
displays a short text message.  Only one line of code
is required:

	view layout [text "Hello REBOL World!"]

You can type this line at the REBOL console prompt, or save
it in a text file and run it with REBOL.  If you save it
as a file, the script will also need a REBOL header. The
header tells REBOL that the file contains a script. Here
is an example of the script file with a header:

	REBOL [Title: "Example VID Script"]

	view layout [text "VID Example!"]

You can also add buttons and other gadgets to the script. The
example below displays a text, list of files, and a button:

	view layout [
		h2 "File List:"
		text-list data read %.
		button "Great!"
	]

!Click on the examples above to see how they will appear on your
screen.  Click on their close box to remove them.  All of the
examples that follow can be viewed this way.

===Two Basic Functions

Two functions are used to create graphical user interfaces
in REBOL: VIEW and LAYOUT.

The LAYOUT function creates a set of graphical objects.  These
objects are called faces.  You describe faces with words and
values that are put into a block and passed to the LAYOUT function.

The VIEW function displays faces that were previously created by
LAYOUT. The example below shows how the result of
the LAYOUT function is passed to the VIEW function, and the
interface is displayed.

	view layout [
		text "Layout passes its result to View for display."
		button "Ok"
	]

Click on the above example to view it.

!Note: the block provided to a layout is not normal REBOL code,
it is a dialect of REBOL.  Using a dialect makes it much easier
to express user interfaces.

===Styles

Styles describe faces.  The examples above use the text and
button styles to specify a text line and a button. REBOL has
40 predefined face styles. You can also create your own custom
styles.  Here are a few example styles:

	view layout [
		h1 "Style Examples"
		box brick 240x2
		vtext bold "There are 40 styles built into REBOL."
		button "Great"
		toggle "Press" "Down"
		rotary "Click" "Several" "Times"
		choice "Choose" "Multiple" "Items"
		text-list 120x80 "this is" "a list" "of text"
		across
		check
		radio radio
		led
		arrow
		below
		field "Text Entry"
	]

The words like backdrop, banner, box, text, and button are styles.

===Facets

Facets let you modify a style.  For instance, you can change the
color, size, text, font, image, edge, background, special
effects, and many other facets of a style.

Facets follow the style name.  Here is an example that shows
how you modify the text style to be bold and navy blue:

	view layout [txt bold navy "Facets are easy to use."]

The words bold and navy are not styles.  They are facets that
modify a style. Facets can appear in any order so you don't
have to remember which goes first.  For example, the line
above could be written as:

	view layout [txt "Facets are easy to use." navy bold]

Many facets that can be specified.  Here is an example that
creates bold red text centered in a black box.

	view layout [txt 300 bold red black center "Red Text"]

You can create facets that produce special effects, such
as a gradient colored backdrop behind the text:

	view layout [
		vtext bold "Wild Thing" effect [gradient 200.0.0 0.0.200]
	]

===Custom Styles

Custom styles are shortcuts that save time.  When you define a
custom style, the facets you need go into the new style.  This
reduces what you need to specify each time you use the style,
and it allows you to modify the look of your interface by
changing the style definitions.

For example, here is a layout that defines a style for red
buttons.  The style word defines the new style, followed by
the old style name and its facets.

	view layout [
		style red-btn button red
		text "Testing red button style:"
		red-btn "Test"
		red-btn "Red"
	]

So, if you wanted to create a text style for big, bold,
underlined, yellow, typewriter text:

	view layout [
		style yell tt 220 bold underline yellow font-size 16
		yell "Hello"
		yell "This is big old text."
		yell "Goodbye"
	]


===Note About Examples

!From this point forward, all examples will assume that
the view and layout functions are provided.  Only the layout
block contents will be shown.  To use these examples in your
scripts, you will need to put them in a layout block, as was
shown earlier.

For example, code that is written as:

	view layout [button red "Test it"]

will now appear as:

	button red "Test it"

===Face Sizes

The size of a face depends on its style.  Most styles, such as
buttons, toggles, boxes, checks, text-lists, and fields, have a
convenient default size.  Here are some examples.

	button "Button"
	toggle "Toggle"
	box blue
	field
	text-list

If no size is given, text will automatically compute its size,
and images will use whatever their source size is:

	text "Short text line"
	text "This is a much longer line of text than that above."
	image %palms.jpg

You can change the size of any face by providing a size facet.
The size can be an integer or a pair.  An integer specifies
the width of the face.  A pair specifies both width and height.
Images will be stretched to fit the size.

	button 200 "Big Button"
	button 200x100 "Huge Button"
	image %palms.jpg 50x50
	image %palms.jpg 150x50

===Color Facets

Most styles have a default color.  For example the body of
buttons will default to a teal color.  To modify the color of
a face, provide a color facet:

	button blue "Blue Button"
	h2 red "Red Heading"
	image %palms.jpg orange

Colors can also be specifed as tuples. Each tuple contains three
numbers: the red, green, and blue components of the color. Each
component can range from 0 to 255. For example:

	button 200.0.200 "Red + Blue = Magenta" 200
	image %palms.jpg 0.200.200 "Green + Blue"

Some face styles also allow more than one color.  The effect of
the color depends on the style.  For text styles the first color
will be used for the text and the second color for the background
of the text:

	txt "Yellow on red background" yellow red
	banner "White on Navy Blue" white navy

For other styles, the body of the face is the first color, and
the second color will be used as its alternate.

	button "Multicolor" olive red
	toggle "Multicolor" blue orange

===Text Facets

Most faces will accept text to be displayed.  Even graphical
faces can display text.  For example, the box and image faces
will display text if it is provided:

	box blue "Box Face"
	image %palms.jpg "Image Face"

Most button faces will accept more than one text string. The
strings will be shown as alternates as the face is selected.

	button "Up" "Down"
	toggle "Off" "On"
	rotary "Red" "Green" "Blue" "Yellow"
	choice "Monday" "Tuesday" "Wednesday" "Thursday" "Friday"
	text-list "Monday" "Tuesday" "Wednesday" "Thursday" "Friday"

When other datatypes need to be displayed as text, use the form
function to convert them first:

	button 200 form now
	field form first read %.

===Normal Text Style

Normal text is light on dark and can include a number of facets
to set the font, style, color, shadow, spacing, tabbing, and
other attributes.

	text "Normal"
	text "Bold" bold
	text "Italic" italic
	text "Underline" underline
	text "Bold italic underline" bold italic underline
	text "Big" font-size 32
	text "Serif style text" font-name font-serif
	text "Spaced text" font [space: 5x0]

Text also includes these predefined styles:

	banner "Banner" 200
	vh1 "Video Heading 1"
	vh2 "Video Heading 2"
	vh3 "Video Heading 3"
	label "Label"

===Document Text Style

Document text is dark on light and can also include a number of
facets to set the font, style, color, shadow, spacing, tabbing,
and other attributes.

	txt "Normal"
	txt "Bold" bold
	txt "Italic" italic
	txt "Underline" underline
	txt "Bold italic underline" bold italic underline
	txt "Big" font-size 32
	txt "Serif style text" font-name font-serif
	txt "Spaced text" font [space: 5x0]

Document text also includes these predefined styles:

	title "Centered title" 200
	h1 "Heading 1"
	h2 "Heading 2"
	h3 "Heading 3"
	h4 "Heading 4"
	tt "Typewriter text"
	code "Code text"

===Text Entry Fields

Text input fields accept text until the enter or tab key is
pressed.  A text input field can be created with:

	field

To make the field larger or smaller, provide a width:

	field 30
	field 300

Fields will scroll when necessary.

Larger amounts of text can be entered in an area.  Areas also
accept an enter key and will break lines.

	area

You can also specify the area size:

	area 160x200

To force the text in an area to wrap rather than scroll
horizontally, provide the wrap option:

	area wrap

===Text Lists

Text lists are easy to create.  Here is an example.

	text-list "Eureka" "Ukiah" "Mendocino"

You can also provide it as a block:

	text-list data ["Eureka" "Ukiah" "Mendocino"]

Almost any type of block can be provided. Here is a list
of all the files in your current directory:

	text-list data read %.

Here is a list of all the words REBOL has scanned:

	text-list data first system/words

===Images

By default an image will be scaled to fit within a face.

	image 60x60 %palms.jpg
	image %palms.jpg red

Images can be framed in a number of ways:

	image 100x100 %palms.jpg frame blue
	image 100x100 %palms.jpg bevel
	image 100x100 %palms.jpg ibevel red 6x6

Most other faces can accept an image as well as text:

	box 100x100 %palms.jpg
	button "Button" %palms.jpg purple
	toggle "Toggle" %palms.jpg blue red
	field bold "This is a field." %palms.jpg effect [brighten 100]

The image can be provided as a filename, URL, or image data.

===Backdrops

A backdrop can be a color, an effect, an image, or a combination
of the three.  For example a backdrop color would be written as:

	backdrop navy
	banner "Color Backdrop" gold

To create a backdrop effect provide it on the line:

	backdrop effect [gradient 1x1 0.0.100 100.0.0]
	banner "Gradient Backdrop" gold

A backdrop image can be a file, URL, or image data:

	backdrop %palms.jpg
	banner "Image Backdrop" red

The backdrop image can be colorized:

	backdrop %palms.jpg blue
	banner "Blue Image Backdrop"

The image can include an effect:

	backdrop %palms.jpg effect [fit gradcol 1x1 100.0.0 0.0.250]
	banner "Gradient Image Backdrop"

===Effect Facets

A range of effects are supported for faces.  All of these
effects are performed directly on the face when it is rendered.
Here are examples of a few possible effects:

	style palms image 80x60 %palms.jpg 
	palms effect [flip 1x1]
	palms effect [rotate 90]
	palms effect [reflect 1x1]
	palms effect [crop 0x50 120x60 fit]
	palms effect [grayscale]
	palms effect [invert]
	palms effect [difference 200.0.0]
	palms effect [tint 80]
	return
	palms effect [contrast 50]
	palms effect [brighten 50]
	palms effect [sharpen]
	palms effect [blur]
	palms effect [colorize 200.0.0]
	palms effect [gradcol 1x1 150.0.0 0.0.150]
	palms effect [gradmul 0x1 0.100.0]
	palms effect [grayscale emboss]

Effects can be used in combination to create other interesting
results.  However, keep in mind that the computations are
performed in real time.  If complex combinations are required,
a temporary image should be created with the to-image function.

===Actions

An action can be associated with almost any face. To do so,
follow the face style with a block:

	button "Test" [print "test"]

The block is used as the body of a function that is passed
the face and the current value (if the face has one).  For
example:

	toggle "Toggle" [print value]
	rotary "A" "B" "C" [print value]
	text "Click Here" [print face/text]

If a second block is provide, it is used for the alternate
actions (right key):

	button "Click Here" [print "action"] [print "alt-action"]

Use variables to modify the contents or state of other faces.
For example, the slider will update the progress bar:

	slider 200x16 [p1/data: value show p1]
	p1: progress

!More on actions needed...

===More to Come

!Much more to come.  These still need to be covered in this
tutorial:

	text-list data [
		sensor
		key
		check
		radio
		led
		arrow
		slider
		progress
		icon
		panel
		list
	]
}

code: text: layo: xview: none
sections: []
layouts: []
space: charset " ^-"
chars: complement charset " ^-^/"

rules: [title some parts]

title: [text-line (title-line: text)]

parts: [
	  newline
	| "===" section
	| "---" subsect
	| "!" note
	| example
	| paragraph
]

text-line: [copy text to newline newline]
indented:  [some space thru newline]
paragraph: [copy para some [chars thru newline] (emit txt para)]
note: [copy para some [chars thru newline] (emit-note para)]
example: [
	copy code some [indented | some newline indented]
	(emit-code code)
]
section: [
	text-line (
		append sections text
		append/only layouts layo: copy page-template
		emit h1 text
	) newline
]
subsect: [text-line (emit h2 text)]

emit: func ['style data] [repend layo [style data]]

emit-code: func [code] [
	remove back tail code
	repend layo ['code 460x-1 trim/auto code 'show-example]
]

emit-note: func [code] [
	remove back tail code
	repend layo ['tnt 460x-1 code]
]

show-example: [
	if xview [xy: xview/offset  unview/only xview]
	xcode: load/all face/text
	if not block? xcode [xcode: reduce [xcode]] ;!!! fix load/all
	if here: select xcode 'layout [xcode: here]
	xview: view/new/offset layout xcode xy
]

page-template: [
	size 500x480 origin 8x8
	backdrop white
	style code tt black silver bold as-is para [origin: margin: 12x8]
		font [colors: [0.0.0 0.80.0]]
	style tnt txt maroon bold
]

parse/all detab content rules

show-page: func [i /local blk][
	i: max 1 min length? sections i
	append clear tl/picked pick sections i show tl
	if blk: pick layouts this-page: i [f-box/pane: layout/offset blk 0x0 show f-box]
]

main: layout [
	across
	h2 title-line return
	space 0
	tl: text-list 160x480 bold black white data sections [
		show-page index? find sections value
	]
	h: at
	f-box: info 500x480
	at h + 456x-24
	across space 4
	arrow left  keycode [up left] [show-page this-page - 1]
	arrow right keycode [down right] [show-page this-page + 1]
	pad -120
	txt form system/script/header/date/date
]
show-page 1
xy: main/offset + 480x100
view main