Creating Content in REBOL/View

A Quick Primer to the Consumer Interface Dialect (CID)

V1.2, Carl Sassenrath, 2-2-2000

---

Purpose

This guide is intended for those who want to become quickly productive in creating content in REBOL/View without the need to become an expert on REBOL first. If you've written HTML pages directly, then you should find this just as easy.

---

Writing Scripts

You do not need a deep understanding of REBOL to create graphical content as long as you stay within the Consumer Interface Dialect (CID). That's because as a dialect CID accepts simple descriptions and converts them to their underlying graphical objects. It is provided as a standard part of every REBOL/View system to help you create content in a style that is appropriate for consumer presentation. Other REBOL graphical dialects will also be available, such as a desktop interface dialect, slideshow dialect, animation dialect, videogame dialect, etc. In addition, you can create your own dialects for specific purposes.

All REBOL applications are written as scripts. You can create a script from any text editor, even the notepad. However, care should be taken if you use word processors (like MS Word) because you will need to save the script as text, not as a document.

All scripts begin with a header that provides the title of the script and other information, such as your name, the file name, a short description, and more. Every script must begin with a header to be recognized by REBOL. When you understand this script header, you will be well on your way to writing actual scripts.

Here's an example:

REBOL [
    Title: "Example Script"
    Author: "Carl"
    File: %example.r
    Purpose: {
        Just to show an example of a REBOL
        header that has a few lines.
    }
]

In addition, there can be many other details specified in a header, such as the date, version, copyrights, and more. See the REBOL User's Guide for more detail.

The header illustrates the most important elements of scripting:

Block Brackets [1 2 3]	The [ and ] are used to group items in REBOL. You can group any kind of items within these block brackets. If you forget a beginning or ending bracket, you'll get an error message.
Quoted Strings "text"	Short strings use a normal quote character. The string may not be longer than a single line. If it is, you should use long strings, as described below. Short and long strings are interchangeable, it's up to you to decide which you want to use.
File Names %file.r	The % indicates that what follows is a filename. This is required to prevent confusion between file names and words. If you forget the %, you may get an error message that tells you that the word is not known.
Long Strings {text}	Long strings use the { and } and can be any number of lines. Don't forget the ending } or an error will occur. A long string can include a quote (") within it.
Words word:	Words that are followed by colons (:) are being defined. In the above example the title, author, file, and purpose are being defined. If a word is simply being used, not defined, then no colon is required.

The items in this table are called datatypes, and there are several others that are available to you. Rather than describe them all here, they will be explained as they are encountered in the examples below.

The header example also shows that scripts are free format. You can put as much or as little as you want on a line, you can indent lines for clarity, and you can add spaces or extra lines anywhere you want. These variations makes no difference in how the lines are interpreted.

---

A Simple Script

Here is an example of the simplest script that produces a graphical result on the screen:

REBOL [Title: "Simple Example"]

view layout 640x480 [text "REBOL with a cause"]

Use a text editor to type this example into a file. Be sure to include the quotes and brackets.

Save the file as example.r on your disk, then double click on its icon (or run it from the shell) to start it. You should see a page pop up with the "REBOL with a cause" text in white. Of course, this assumes that you've already installed REBOL/View on your computer. If you made a mistake, an error message will be shown in the console window. Compare your script with that above to make sure that it is the same.

The first line of this script is the header, as explained above. The second line indicates that you want to view a layout of a given size (640 wide by 480 high) that has particular content.

Modify your script to specify a new color for the text:

REBOL [Title: "Simple Example"]

view layout 640x480 [text "REBOL with a cause" 255.0.0]

Here the color is specified as three numbers separated by periods that indicate the amount of red, green, and blue. The color 255.0.0 would be bright red. Save the script, and run it to see.

These examples have shown the use of two new datatypes:

Pairs 100x200	Pairs are used to specify locations on a page or sizes of page items. The first number is the horizontal position or width. The second number is the vertical position or height. Examples: 100x50 640x480 1280x800
Colors 100.50.20	Colors are written as three numbers (tuples) which can each range between zero and 255. They are ordered as red, green, and blue. So 0.0.255 is bright blue. Examples: red: 255.0.0 green: 0.255.0 yellow: 255.255.0 orange: 255.150.50

If you make a mistake in writing these datatypes, an error will be displayed in the console window. For instance, if you write a color as 400.0.0, you will see the message:

** Syntax Error: Invalid tuple -- 400.0.0.

---

Graphic Styles

The example above displayed just a line of text, but many other graphical styles can also be specified. For instance, you can put a button on the page instead of the text by writing:

view layout 640x480 [button "Click Here"]

(Note that, for the sake of brevity, the REBOL header is not shown in this or the following examples.)

Instead of a button, you can show an image:

view layout 640x480 [image %lake.jpg]

The words text, button, and image indicate different types of graphical styles to be displayed. In addition to displaying each style separately, they can be combined into a single page with:

view layout 640x480 [
    text "REBOL with a Cause"
    button "Click Here"
    image %lake.jpg
]

There are other types of predefined styles that can be shown. These are currently available (and this will be expanded in future releases):

Text	Normal text.
Title	Larger text used for titles.
Subtitle	Text used for subtitles.
Label	Text used to label items on a page. Differs from other text in how it is positioned.
Image	A JPEG, GIF, or BMP image.
Frame	An image with a border edge around it.
Backdrop	An image that expands over the entire page.
Backtile	An image this replicated to cover the entire page.
Button	A simple button.
Toggle	A button with on/off state.
Rotary	A button with multiple states.
Field	A single line textual input field.
Area	A multiline textual input field.

In addition to these styles, you can add your own. See the stylize section below.

Here is an example using multiple styles in the same window:

view layout 640x480 [
    backdrop %texture.jpg

    title "Current News"

    subtitle "Today's Headlines"
    text {
        This is multiple lines of text long
        and it will be wrapped on the page into
        a single paragraph of text.
    }

    image %photo.jpg

    subtitle "Tomorrow's Headlines"
    text {
        This is multiple lines of text long
        and it will be wrapped on the page into
        a single paragraph of text.
    }

    button "Update"
    button "Cancel"
]

This would display a window of text, an image, and two buttons on top of a graphical texture.

---

Style Attributes

A style can be modified to give it a different look. There are five general attributes that you can specify for a style. They are listed below:

Text	The textual contents to be displayed. The string used for text areas, buttons, fields, etc.
Image	Filename of a graphic (JPEG, GIF, or BMP) to be used for images, backdrops, and buttons. Must have a % to show that it's a filename.
Size	The width and height of the button as a pair. For instance, 100x24 would be 100 wide and 24 high.
Color	The color of the primary portion of an item. This is the color of the characters for text, the color of the body for button, and the color to colorize an image.
Action	An action to take when the item is selected. Can be used with all styles, including not only buttons, but also text and images.

For instance, the button defined above can be colored blue with the line:

button "Blue Button" 0.0.255

(Assume that the view layout 640x280 is supplied before all these examples.)

The 0.0.255 number specifies that the color of the button is blue. Similarly, to change the default size of a button and make it 200 wide by 24 high instead:

button "Big Button" 200x24

Or, if you want the button to have an image within it:

button "Image Button" %texture.jpg

You can also combine all of these attributes to modify the size, image, and color of a button at the same time:

button "All in One" 200x24 %texture.jpg 0.0.255

The attributes can appear in any order, so the above line could also be written as:

button "All in One" 0.0.255 %texture.jpg 200x24 

Other styles, such as text and images, can also have attributes provided. In the example below, every style is given additional attributes:

view layout 640x480 [
    backdrop %texture.jpg 250.150.50
    title "Bright Red Text" 255.0.0
    image %face.jpg 100x100 0.0.255
    text "A line of text" 0.255.255 50x24
]

There are some styles, such as text that may have additional attributes, such as their alignment, edge, or alternate text. This is covered below.

---

Page Layout

As shown above the layout function is used to create a layout of a specified size. It expects two arguments:

layout size description

The first argument is the size of the area to use for this layout. Normally, it is the size of the full page, but it can be smaller (in the case of a sub-layout used within another layout) or larger (for a layout that may scroll within another layout).

The layout description is a block of styles and their attributes as introduced in the above sections. For example, the line:

layout 100x50 [text "Short Line"]

creates a layout that is 100 wide by 50 high and contains a single line of text.

The appearance of each layout is determined by the order in which styles are specified within the description. For instance, if you specify an image followed by a button:

image %clock.jpg
button "Time"
button "Alarm"

The image will be displayed with the "Time" button underneath it and the "Alarm" button beneath that. If you wrote it:

button "Time"
button "Alarm"
image %clock.jpg

The buttons would come before the image.

Instead of proceeding downward, you can specify that styles are positioned from left to right:

across
button "Time"
button "Alarm"

These two buttons will be positioned horizontally across the page.

To return to a downward layout:

down
button "Day"
button "Hour"

Spacing between the button is automatic. If you want to insert more space between them, you can specify:

button "Time"
pad 10
button "Alarm"

This will add ten pixels to the normal offset between the buttons. The direction of that offset will be determined by down and across. That is, if you're heading downward and you pad with ten pixels, the ten pixels will be downward.

In addition, you can set the automatic spacing that is placed between every style with:

space 20x15
button "Time"
button "Alarm"

This specifies that the spacing between styles will be 20 when in downward layout and 15 when in horizontal layout.

The layout of the page starts at the top left and proceeds downward. The position from which it begins is normally 10x10, but that can be changed with:

origin 100x50

This sets graphics to begin at the 100x50 position.

You can also locate a style at an particular position on the page at any time. To do so you use:

at 50x100
text "Now at position 50x100"

The layout then resumes from that position.

---

Actions

Actions can be attached to styles. An action is REBOL code that is evaluated when its style has been selected by the user (clicked on with the mouse). For instance, to create a button that sends email when you click it:

button "Send" [send luke@rebol.com "use the force"]

Actions are provided within blocks [ ] of code that perform useful operations. The more you know about REBOL, the more powerful the types of action blocks you can create. The most common action is to display some other layout, and that can be done with a block such as:

button "Next" [view next-page]

This will switch to view the layout for that page. The way you name pages is described in the section below.

Actions can be provided for more than just buttons. You can also make text and images perform an action when selected by the mouse.

---

Multiple Pages

Most applications involve more than one layout. For instance, if your application has several pages, it may use separate layouts for each. On the other hand, it is also possible to use the same layout for each.

When you create multiple layouts, you give them names in order to refer to them again. For instance, your first layout could be called "connection-page":

connection-page: layout 640x480 [
    title "Connect to Network"
    button "Next" [view purpose-page]
    button "Cancel" [quit]
]

This could be followed by other layout descriptions, such as "purpose-page":

purpose-page: layout 640x480 [
    title "Purpose"
    text {
        This system gives you all the information
        you need to run your fringe area localizer
        without disrupting the quantum fluxgate.
    }
    button "Back" [view connection-page]
]

To display the first page:

view connection-page

If you click on the "next" button, it will switch to the purpose-page. Notice that you switch back and forth between the layouts using view. The buttons on both pages use view to get to the other page.

---

Layout Variables

As described above, the positions of styles within a layout are determined automatically. This is helpful, because you don't need to specify the coordinates for every item. However, there will be times when you may need to know your current location on the page. For instance, you may want to return to it later in the layout to add more detail.

You can obtain the current location by defining a word to hold it, followed by the word mark, or any other location altering word, such as at, pad, down, across, and space.

layout 640x480 [
	title "Example"
	image-pos: mark
	image %street.jpg
	at image-pos
	text "This text will lay over the street image."
]

Here the word image-pos is set to the current location where the image will begin. Once the image has been placed, the image-pos word is used with at to return to the location to write the text string.

Note that you can perform math operations on this value to make adjustments. In the example above, you could write:

at (image-pos + 10x10)

Here the layout continues at the previous position plus an offset.

---

Face Variables

The location variables above are only set when they appear before a location relative word such as pad or space. If a defining word is placed before a style, the face for that style will be stored in the word.

A face is the underlying REBOL object that is used to manage each graphical element on the screen. Each style is implemented with a face and each can have many attributes.

The advantage of setting a face to a word is that you can access and alter it later. Here is a simple example:

layout 640x480 [
	error-msg: text "" 200.0.0
]

...

error-msg/text: "Error has happened"
show error-msg

The text face created in the layout is assigned to the error-msg word. Later within the script, the text of that face is changed to a new string, and the face is refreshed with the show function.

This is how you can obtain the values for fields and areas. (A field and an area are input boxes displayed on the screen in which the user can type and edit text.) For instance:

layout 640x480 [
	item: field ""
	description: area ""
]

...

print item/text
print description/text

Here the text for both input fields is printed to the console. It can also be modified:

item/text: "Recorder"
description/text: "Audio recording deck"
show item
show description

Note that the show must be done to update the fields in the display.

---

View Options

By default the view function opens a window that is 640x480 in size. However, you can open any size window by providing the size refinement:

view/size pane 800x600 

You can also change the location of the window with the offset refinement:

view/offset pane 10x10

and you can do both:

view/offset/size pane 10x10 800x600

---

Stylize

In addition to the predefined styles you can create your own special styles. To do this requires more detailed knowledge of faces and their attributes. However, most style changes are quite simple.

The general format for stylize is:

stylize [
	new-style old-style [additions]
	...
]

Here a new-style is defined by starting with a old-style, and specifying new attributes for the style. You can repeat this format for multiple new styles in the same block. Here's an actual example:

stylize [
	box image [size: 200x200]
	red-text text [font: [color: 255.50.50]]
]

This defines a new style called box and one called red-text. The box is the same style as image, except that its default size is 200x200. It could then be used in a layout such as:

layout [
	box "A Box"
]

If you wanted the box style to have a four pixel edge that is yellow:

stylize [
	box image [
		size: 200x200
		edge: [size: 4x4 color: 255.255.0]
	]
]

This example makes a green button style that uses a colorized image for the button:

stylize [
	grn-btn button [
		body: [image: load %btnback.jpg effect: [fit colorize 0.100.0]]
	]
]

There is a wide range of other attributes that can be specified. See the REBOL/View documentation for more detail. Notice that style definitions do not require the make statement for subobjects within the new style.

---

Future Developments

CID, the consumer interface dialect, is still in its alpha development stage. There are numerous other styles of graphical gadgets that remain to be added. Over the next few weeks, these features will become available.