VID: Commands

From DocBase

Jump to: navigation, search
This page is obsolete! It describes an older, prototype system.
For newer documents visit: R3 View GUI

Contents

[edit]

Layout commands for VID 3

VID
Visual Interface Dialect, also referred to as a style description dialect.

Along with VID: Styles the REBOL 3 VID dialect includes layout control and other commands.

[edit]

set-word

set-words, a variable name followed immediately by a colon, allow faces to be named. These names can then be used in REBOL code blocks. Please bear in mind that the words defined inside layout blocks are bound to the layout. Gone are the days of global variables for faces. See set-word! or set-words explained. 

view [
   the-area: area
   button "show details" [help the-area]
]

The action block of the button will use the REBOL help function to display a high level view of the face created from the area style word. In this case the set-word the-area: defined the variable the-area. This allows for very powerful and convenient interaction between faces in a REBOL VID application.

There can only be one set-word! variable per face. a: b: c: button "Hello" is not currently allowed.

The variable created with the set-word! is bound to the current layout and stored in an object! called faces. They do not propogate to the user namespace. These values can be accessed using a technique such as; 

view win: layout [
    the-area: area
    button "show details" [help the-area]
]

>> help the-area
No information on the-area (word has no value)
>> help win/faces/the-area
WIN/FACES/THE-AREA is an object of value:
   gob             gob!      make gob! [offset: 20x20 size: 200x100 alpha: 0 dr...
   feel            object!   [on-init: default-options: on-set: on-set-actions:...
   look            object!   [on-init: default-options: on-update: on-update-ac...
   style           word!     area
...rest of output from help...

This is important to remember while exploring REBOL VID from the console or when developing multiple window applications that may need to communicate back and forth.

Need to clarify note about the context of the BINDING AND NAMESPACES
[edit]

ATTACH

This command allows Styles to be connected. A primary example is attaching scrollbars and sliders to other styles. The attach command accepts optional numeric arguments that are the relative offsets to the faces to attach. Without arguments attach will connect the last two defined faces. This is equivalent to attach -1 -2.

Anyone that developed REBOL version 2 VID applications should appreciate the new simplicity.

[edit]

Examples 

view [progress slider attach]

Displays a progress bar and a slider. The ATTACH word, attaches the face to the previous face. When the slider is moved, so does the progress bar. 

view [progress progress slider attach -2]

Will attach the slider to the second progress bar. 

view [progress progress slider attach -3]

Will attach the slider to the first progress bar. 

view [progress progrss slider attach attach -1 -3]

Will attach the slider to both progress bars. The first attach is equivalent to attach -1 -2. 

rebol []
view [
    h1 "Scrolling (SCROLL-PANEL and SCROLLER)"
    group 2 [
          
        tight bottom right    ; stick the panel to the scrollers
        scroll-panel 150x200 [image %Cat.jpg]
        tight only bottom left
        scroller 20x200
        attach                ; attach scroller and scroll-panel
        tight only top right
        scroller 150x20
        attach -3             ; attach with scroll-panel            
    ]
    text "(Hope you like the cat. ;)"
]

The example above includes the tight, only, top, bottom, left and right VID commands. It also shows the h1, text, scroll-panel, scroller visible styles along with the invisible, powerful and critical group style.

Note how the second attach command has the -3 argument. It connects the horizontal scroller to the scroll-panel, which is three faces back. This could also be written as attach -1 -3. See below for information on using names instead of numbers.
[edit]

Attaching face objects

The attach command also accepts face objects. This is perfect for use with the set-word feature of VID. This can help;

  • alleviate counting faces
  • ensure source code of a layout can be moved around without worrying about numeric attach arguments

but

  • it means keeping track of extra words in the layout, which could lead to naming conflicts.

VID lets you choose what is best for you.

[edit]
Examples 
view [p1: progress  p2: progress  s1: slider  attach s1 p1]

As with integer! arguments, if only one argument is given, the missing argument is assumed to be the previous face. 

view [p1: progress  p2: progress  slider  attach p1]

And arguments can be mixed. 

view [progress  p2: progress  s1: slider  attach s1 -3]
Note that the set-words do not effect the count. They are simply variable names for the actual faces.
[edit]

DO

During the creation of a VID layout, the do command allows for evaluation of any REBOL code. The uses are nearly endless, but keep in mind that the code will be evaluated during the layout, not as runtime actions during the GUI event handling.

do expects a 'block! of REBOL code.

Need to explain the context of REBOL bindings for this evaluation and some examples.
[edit]

TIGHT

The tight command controls how the layout flows margins (or space) around the faces that follow.

It can be used alone; to effectively remove all margins, or with a variety of control options.

Being REBOL; some options are datatype!, some options are keyword or you can use a combination of both.

off
resets margin control. It returns the layout flow to normal spacing around faces.
This is actually a logic! value, so off, false and no would all work but off carries the most meaning.
percent!
reduces margins by percentage. tight 100% effectively removes margins. tight 50% makes things half as tight; 50% less margin. Whereas tight 10% will make faces only a little bit tighter together than normal; 10% less margin. For completeness, negative values are allowed. tight -50% will make for a looser layout in terms of spacing; 50% more margin.

positional by name

left
tight left controls the left margin and can include off or percent! options.
right
control the right margin. Example tight right off.
top
control the top margin. Example tight top 75%.
bottom
and the bottom margin. Example tight bottom.
only
restricts influence to the named margins; resetting the others. For example tight only left tightens the left margin and resets all the others to normal. only will come into play in those rare cases where cascade margin control is required. only will accept the other options as well. Examples tight only left 50% for 50% less left margin and all others back to normal. tight 50% ... tight only right ... would flow the layout with half margins on all sides of each face then change to tight layout only on the right and all other margins reset to normal.

tight options can be used in conjuction with each direction.

[edit]

Examples

Removes spacing between two buttons in a group: 

group [tight button button]
Add screenshot to this example later.

It works until you turn it off again with tight off: 

group [tight button button button tight off button]
Add screenshot to this example later.

Notice here that VID finds the largest face in the group and scales other faces to that size. That face is the last button, since the button size added with its margin size makes for the biggest face in the group. VID scales the buttons without margins to fit the new size. Therefore the first three buttons are bigger than the last one.

More examples needed.
[edit]

BACKGROUND

The background command, influences the background of the current face and expects a tuple! in r.g.b.a format, or a block! which will be interpreted with the Draw Dialect.

[edit]

EFFECT

The effect command applies an Effect Dialect block! to the current face.

[edit]

ACTION

The action command determines what code will evaluate when the current face is triggered. The particular style defined in VID will influence what determines the action, but most often it will be a mouse-click, as with button styles.

The action command expects a block! of REBOL code.

This command if often, but not always, the assumed default if a block! datatype is used while creating a face.
[edit]

Examples 

view [
    button "Hello" [print "Hello World!"]
]

and 

view [
   button "Hello" action [print "Hello World!"]
]

are equivalent. Some styles, such as group use an unqualified block! for purposes other than an action block, but these differences are usually obvious and self-evident.


[edit]

SELECTED

The selected command accepts a block! that specifies which, if any, entries in a list will be highlighted. Here the term list would apply to any style that can have highlighted entries. For text-list and icon-list the values in the selected block are assumed to be indexes into the list.

[edit]

Examples

Need to verify that this is implimented. My first test did not highlight the rows
view [
    text-list [
        ["Header col1" "Header col2"]
        ["row1 col1"   "row1 col2"   "value-of row1"]
        ["row2 col1"   "row2 col2"   "value-of row2"]
        ["row3 col1"   "row3 col2"   "value-of row3"]
    ]
    selected [1 3]
]

Would display the text-list with rows 1 and 3 initially selected and highlighted.

the value of a row is the value that is sent on double click and on drag and drop for the row
[edit]

OPTIONS

All styles now support (but don't neccessarily use) a block! of options.

Options are additional adjustments or features you can enable for a style. The format for the block, is the same as for entering the block for an object, in the [word: value] format.

Note that when the options block has been entered, no other values can be entered for this face in the layout.

Please look at the Style Option Reference for each style to see, what can be altered for the style.

[edit]

Examples

The BUTTON style by default supports the ROUNDING feature, to adjust the size of the rounding of the button. 

view [button "Help!" options [rounding: 4]]

This will give this particular button a rounding of 4.

[edit]

ACTION-HANDLER

The action-handler command allows for any-function! to be used for handling actions for a face.

[edit]

Examples

More examples needed.

[edit]

VID References

Retrieved from "http://www.rebol.net/wiki/VID:_Commands"
Personal tools