Documention for: rebgui-sizing.r
Created by: btiffin
on: 5-Jun-2007
Last updated by: btiffin on: 5-Jun-2007
Format: html
Downloaded on: 23-Jul-2019

Usage document for %rebgui-sizing.r

1. Introduction to %rebgui-sizing.r
2. rebgui-sizing At a Glance
3. Using %rebgui-sizing.r
3.1. Running %rebgui-sizing.r
4. What you can learn
4.1. issue! trickery
4.2. do-thru
4.2.1. view-root
4.3. RebGUI as Desktop Demo
4.4. spans as issue!
4.4.1. Sizing and span
4.4.2. do-events
4.5. What you can change.
5. What can break
6. REBOL/SDK
7. Credits

1. Introduction to %rebgui-sizing.r

rebgui-sizing.r is an introduction to the ease of resizable gui creation with RebGUI, highlighting one expandable panel widget and subordinates that move out of the way.

gui Graphic User Interface, usually pronounced as gooey
widget A RebGUI graphical element
VID REBOL/View Visual Interface Dialect

2. rebgui-sizing At a Glance

No setup is required, just do it.

>> do %rebgui-sizing.r
 

rebgui-sizing-1.png

rebgui-sizing-2.png

The above images were created running REBOL/View 2.7.5.4.2, RebGUI build #93, GNU/Linux 4.0, KDE Desktop.

3. Using %rebgui-sizing.r

Requires REBOL/View, access to a cached copy of RebGUI or internet access for getting a cached copy.

3.1. Running %rebgui-sizing.r

From the library with:

 >> do http://www.rebol.org/cgi-bin/cgiwrap/rebol/download-a-script.r?script-name=rebgui-sizing.r
 
or locally with:
 >> do %rebgui-sizing.r
 

4. What you can learn

This script is an introduction to the span facet of RebGUI widgets.
Please see the RebGUI home page at Dobeash.com 

Both REBOL/View and RebGUI are available
free of charge from www.rebol.com  and www.dobeash.com 

RebGUI gui building is easy, and offers a flexible 'business polish' to application design. There are many features under the hood. One of those features is resizable windows.

4.1. issue! trickery

In REBOL the "#" starts an issue! datatype. In the REBOL/SDK "#include" is a preprocessor directive that, well, includes files. So the expression

   #include %rebgui.r
 
will act as a preprocessor directive if this program in encapped, but under normal REBOL evaluation will be interpretted as an issue! and a file!. REBOL doesn't care what you do with values, so this syntax doesn't stop the REBOL interpreter.

The next line

   unless value 'ctx-rebgui [do-thru...]
 
will only evaluate the do-thru if the RebGUI context is not defined. Under the SDK and encap the #include will have loaded the rebgui code, so the value will be there. Under normal evaluation REBOL would 'skip over' the #include (issue!) and %rebgui.r (file!), and the context will not be defined, so the do-thru will execute. This is a nice "trick" that lets developers test code with do but then allows proper encapping when building a release package.

4.2. do-thru

This example uses the REBOL/View do-thru feature. do-thru will execute a script from the REBOL/View sandbox (another name for cache). It will retrieve the code from the internet, only if there is not a cached copy.

4.2.1. view-root

REBOL keeps the root directory of the sandbox in view-root. After you have downloaded RebGUI once, you can use

 do view-root/public/www.dobeash.com/RebGUI/rebgui.r
 

If you do develop something with RebGUI, and build it using the REBOL/SDK, you may not have access to do-thru. The RebGUI home site explains all this. This is just an example, and assumes you are using a full fledged REBOL/View, but shows off the #include trick, for when you are ready.

4.3. RebGUI as Desktop Demo

Another way of getting RebGUI is clicking the REBOL/View viewtop Demo RebGUI icon.

4.4. spans as issue!

This short example highlights the use of span facets to control widget resizing and placement during window resizing. Being a short example, it does no real justice to the full power of span and RebGUI widgets. With the proper intelligent placement, span can be used to produce some very professional, resizable layouts with little effort other than planning.

When running, you can resize the window and the first panel with shrink and expand #WH. All the other panels will move up and down #XY with no overlapping widgets.

4.4.1. Sizing and span

Build 93 of RebGUI supports seven different span directives. Some are for initial placement, others come into play during resize events.

The following is taken from the RebGUI User Guide span Directive  but the documentation evolves with RebGUI and the section may not be the same when you read this.

For initial placement

When the display is resized:

It will require a little forethought, but the span directives allow for very nice resizable layouts.

4.4.2. do-events

The standard REBOL event handler is used by RebGUI. do-events is used to start the event handling loop in REBOL. The REBOL/View view function includes a call to this event loop. RebGUI requires it to be called separately, a feature that allows for processing between and around the GUI layout, the display and handling the events.

4.5. What you can change.

For early experiments with your local copy, try changing the span directives. This example script, only allows the first panel to shrink and expand, all other panels just move up/down or left/right.

To see what happens if they are all allowed to shrink and expand, (and the mess this can create) try commenting out the

     ; span: #XY    ; All other panels move in the X and the Y
 
from inside the spec creation loop. This leaves the span at #WH, so all the panels can shrink and expand, but shrink and expand into and over what? The top left corner of each panel is fixed, so they just expand into and over each other. rebgui-sizing-3.png

5. What can break

Without some forethought, the span directives can end up messy. With intelligent design, they can make for very professional, easy to manage, resizable widgets. One of the great powers of using RebGUI for application development.

You will need access to the internet, at least the first time you do-thru rebgui.r.

REBOL/Core will not have the capabilities to run RebGUI, You will need to start up REBOL/View.

6. REBOL/SDK

The RebGUI designer, Ashley Truter has taken great strides to allow the REBOL/SDK to build a RebGUI application that does not require all the REBOL/View features for a lean, mean application. Full information starts at the RebGUI Home 

A note about Mr. Truter, and an apology. The u in Truter is actually ü, a diaeresis. I hold a great deal of respect for Ashley, and not getting his name proper is a something I am looking into fixing. It has to do with getting characters encoded cross-platform. When I type it in Unicode UTF-8 under GNU/Linux, it sometimes gets mungled getting to Windows. Using the ü web entity sometimes doesn't work when there is a text processor involved. Soon I'll have it figured out and this paragraph will disappear.

7. Credits

%rebgui-sizing.r Author: Brian Tiffin
RebGUI Ashley Trüter, Dobeash Software
REBOL/SDK Carl Sassenrath, REBOL Technologies
REBOL/View Carl Sassenrath, REBOL Technologies