Documentation for: rebgui-sizing.r

Usage document for %rebgui-sizing.r

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.

2. rebgui-sizing At a Glance

No setup is required, just do it.

>> do %rebgui-sizing.r
 

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
 

 >> 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
 

The next line

   unless value 'ctx-rebgui [do-thru...]
 

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

• #L Lateral. Align right-hand edge of widget with display (or grouping widget) edge.
• #V Vertical. Align base edge of widget with display (or grouping widget) edge.
• #O Offset (lateral). Move the widget to align with the right-hand display (or grouping widget) edge.

When the display is resized:

• #H Height. Stretch/shrink the widget vertically.
• #W Width. Stretch/shrink the widget horizontally.
• #X X-Offset. Move the widget horizontally.
• #Y Y-Offset. Move the widget vertically.

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
 

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

• The rebol.org Library Team
• Usage document by Brian Tiffin, Library Team Apprentice, Last updated: 5-Jun-2007