Documentation for: rebgui-image.r

Usage document for %rebgui-image.r

1. Introduction to %rebgui-image.r

rebgui-image.r is an introduction to the ease of gui creation with RebGUI, highlighting one widget, image.

2. rebgui-image At a Glance

No setup is required, just do it.

>> do %rebgui-image.r
 

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

3. Using %rebgui-image.r

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

3.1. Running %rebgui-image.r

From the library with:

 >> do http://www.rebol.org/cgi-bin/cgiwrap/rebol/download-a-script.r?script-name=rebgui-image.r
 

 >> do %rebgui-image.r
 

4. What you can learn

This script is an introduction to the display function and image widget of RebGUI.
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.

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

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.

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

4.2. The image widget

This short example highlights the ease of using the image widget in RebGUI. Being a short example, it does no real justice to the full power of image and RebGUI widgets.

When running, you can hover over the image for a tooltip, or click the image to execute an action block, which closes the window.

4.2.1. tip

RebGUI has support for tooltips on all widgets. The widgets actually come with tooltips that you can use while developing with RebGUI.

4.2.2. examine

Once rebgui.r is loaded, you have access to an examine function. This helper utility will display the details about a widget.

 >> examine image
 USAGE:
     image %logo.png
     image logo
     image logo effect [crop 10x10 50x50]

 DESCRIPTION:
     An image.

 ATTRIBUTES:
     size            -1x-1
     effect          fit
     options         block!
     init            function!
 

4.2.3. Sizing

A quick note about the image default size -1x-1. RebGUI can be completely liquid in terms of resizing windows and smooth, reasonable placement of widgets. In this case, image defaults to -1 by -1 units, or in RebGUI speak...figure out a reasonable size when rendered...in the context of the widgets around the image and other concerns.

Another quick note. RebGUI doesn't really count things in 'pixels', it counts in 'units'. Very powerful. It allows the function request-ui to give the power of many aspects of the user interface to the user. More on this in the %rebgui-sizing.r example script.

4.2.4. 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.3. What you can change.

For early experiments with your local copy, try using other images. You don't have to, but you can also specify sizes. You could change the tip, or maybe the action block. For the next example, how about an effect with a size and an exploratory action.

   image 50x12 logo.gif  effect [fit  gradmul green blue]
     tip "Click to print face details"  [help face]
 

When clicked, something like this is produced on the console window

 >> do %rebgui-image.r
 Script: "RebGUI image Example" (4-Jun-2007)
 FACE is an object of value:
    type            word!     image
    offset          pair!     16x16
    size            pair!     200x48
    span            none!     none
    pane            none!     none
    text            none!     none
    color           none!     none
    image           image!    size: 100x24
    effect          block!    length: 4
    data            none!     none
    edge            none!     none
    font            none!     none
    para            none!     none
    feel            object!   [redraw detect over engage]
    saved-area      none!     none
    rate            none!     none
    show?           logic!    true
    options         block!    length: 0
    parent-face     object!   [type offset size span pane text color image effec...
    old-offset      pair!     16x16
    old-size        pair!     200x48
    line-list       none!     none
    changes         none!     none
    face-flags      integer!  1
    action          object!   [on-alt-click on-away on-click on-dbl-click on-edi...
    rebind          none!     none
    init            none!     none
    tip             string!   "Click will print face details"
 

5. What can break

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