Documentation for TOOLBAR VID widget

Author: Henrik Mikael Kristensen
Date: $date

Contents:

Some features described may not yet be implemented or finished.

About TOOLBAR

Toolbar is a new layout function for creating a MacOSX or Windows style toolbar for VID. The basic idea is that it shaves off a lot of the labour in creation of a flexible toolbar, by allowing you to build one in a few lines of code.

Also Toolbar helps with a number of additional features, such as configurable looks and layout, much of it is borrowed from MacOSX and some can also be seen in the toolbar configuration method used in Mozilla Firefox. Some of these features are yet to be implemented, but much of the framework required for it is ready.

TOOLBAR is currently in version 0.0.10 and is released under the BSD License.

Demonstration of Usage

This section will be written later. For now you can try the demos:

Basic test:

http://www.hmkdesign.dk/rebol/toolbar/toolbar-demo.r

Demonstrating SWITCH?:

http://www.hmkdesign.dk/rebol/toolbar/toolbar-demo-2.r

Building a Toolbar

To get it:

do http://www.hmkdesign.dk/rebol/toolbar/toolbar.r

This will load the extension into the VID style. Now you can begin creating toolbars from VID!

Building a Toolbar Layout

Building a Toolbar layout comes in two stages:

1. First you build a data store which contain all buttons that you plan to make available for the toolbar. This is a block! stored in DATA-STORE.
2. Then you create a block! in DATA, which contains the word names of buttons that will actually be displayed and in which order. This block can contain additional words to separate buttons or to add spring spacers.

This might seem a bit elaborate, but this is to accommodate features that will be implemented in upcoming versions of TOOLBAR.

The DATA-STORE block, is structured as a word/block pair, the word being the name of the element and the block containing the specs for the element.

Creating a Data Store

The structure is as so:

data-store: [
  <name1> [<type> <specs>]
  <name2> [<type> <specs>]
  <name3> [<type> <specs>]
]

The type can be either face or image:

For faces, you can provide an ordinary layout block in specs.

For images, you provide a reference to a previously loaded image bitmap. The images can be of any size and they will be centered appropriately for each element in the toolbar. The toolbar automatically scales to fit the images used.

The specs contains the string to be shown below the icon or face, the action to be done when clicking on a button.

An example of a data store:

data-store: [
  print  [image "Print" print-image [do-print]]
  open   [image "Open" open-image [do-open]]
  close  [image "Close" close-image [do-close]]
  search [face "Search" [field 100 [do-search]]]
]

This provides that you already have defined PRINT-IMAGE, OPEN-IMAGE and CLOSE-IMAGE as loaded images somewhere in your code.

Creating the Data for the Toolbar

Now that you have a data-store you can display the elements in your toolbar. This is done through the DATA block. The order that you put the names in, defines the order the elements will be displayed in the toolbar.

[print close open]

This will display the PRINT, CLOSE and OPEN buttons next to each-other. Notice you don't have to have all elements from the data store listed in this block.

By changing the order:

[print open close]

And issuing an UPDATE, will redraw the toolbar with the new order.

You can freely redefine DATA in code, just remember to issue an UPDATE afterwards.

DATA can contain a few other words to help with additional layout:

	divider	This provides a vertical divider between elements.
	spacer	This provides a spring spacer that will fit between the width of the toolbar. This makes it possible to right align toolbar elements.
	disabled	By using this word next to a button word, you can disable the button. When disabled, it blocks mouse events and is grayed out.

Example using the extra words:

[
  print
  divider
  open disabled
  close
  spacer
  search
]

Full Example

Prepare network.png, open.png, remove.png and info.png before the layout. These images are downloaded in the first demo mentioned at the top of this document.

view layout [
  tb: toolbar 600 with [
    data-store: [
      network [image network.png "Network Information" []] 
      open [image open.png "Open" []] 
      remove [image remove.png "Remove" [print now]] 
      face [face "Search" [field 100]] 
      info [image help.gif "Information" []] 
      more [image info.png "More" []]
    ]
    data: [
      network 
      divider 
      open disabled 
      open 
      spacer 
      remove 
      remove disabled 
      divider 
      face 
      divider 
      info 
      spacer 
      more
    ]
  ]
]

This will result in the following toolbar:

Building a Switch Toolbar

TOOLBAR can be used to create a switch toolbar, which has an active element. When clicking on a different element, that element becomes active.

This type of toolbar is common in Preferences applications, such as seen in most MacOSX applications and in Mozilla Firefox.

To make TOOLBAR behave like this, set SWITCH? to TRUE.

Full Example

The method is the same for creating a switch toolbar as for a normal toolbar, so we'll settle for a full example.

Prepare network.png, user.png and mail.png before the layout. These images are downloaded in the second demo mentioned at the top of this document.

view layout [
  tb: toolbar 500 with [
  switch?: true
  data-store: [
    user  [image "User" user.png []]
    email [image "Email" mail.png []]
    proxy [image "Proxy" network.png []]
  ]
  data: [
    user
    email
    proxy
  ]
  selected: 'proxy
]

Note that when SELECTED is set inside the layout like this, UPDATE will do the action of the selected element immediately. This may not be desirable, if certain values are not set at layout time.

The safer approach is to not use SELECTED inside the layout, and set it afterwards. Then you apply UPDATE:

main: layout [
  tb: toolbar 500 with [
    .... same stuff as before ...
  ]
]

tb/selected: 'proxy
tb/update

view main

Change the Visual Appearance

The toolbar has four display modes:

Icons and Text

Icons Only

Text only

Nothing

For each mode the toolbar is resized vertically to fit the icons and/or text.

Icon and text display can be set with ICONS? and TEXT? respectively.

Changing the Toolbar during Runtime

You can alter the size of the toolbar during runtime.

With the above example, we have a toolbar TB.

tb/size/x: 700
tb/update

This will update the toolbar to the new size and rescale spring spacers.

If you update the size of the toolbar to be less than the minimum required size, the toolbar elements will simply be truncated.

If you want to avoid truncation, read the value of MIN-SIZE after the toolbar has been shown to determine the minimum possible width of the toolbar.

Enabling and Disabling Elements

You can further interact with the toolbar from your program by using the ENABLE and DISABLE functions to enable and disable elements on the toolbar.

tb/disable 'network

tb/enable 'network

Function Reference

update

Use this function every time you change the BUTTONS block or resize the toolbar in your window.

When using SWITCH? and an element word is stored in SELECTED, the action of that element will be done.

Examples

Switch the toolbar element in your program (from the second full example):

tb/selected: 'email
tb/update

Resizing the toolbar:

tb/size/x: 750
tb/update

data-store

Block with a description of the possible contents of the toolbar.

data

Block with a description of the contents of the toolbar in the right order.

frame-padding

The padding around a single element in pixels. Default value is 8 pixels.

padding

The padding around the elements and the edge of the toolbar in pixels. Default value is 2 pixels.

spacing

The horizontal spacing between elements in pixels. Default value is 5 pixels.

text?

Flag

When set to TRUE, text will be displayed in the toolbar. When set to FALSE, they will be hidden.

icons?

Flag

When set to TRUE, icons will be displayed in the toolbar. When set to FALSE, they will be hidden.

colors

This is a block! value with the following word/tuple pairs:

	back-top	The top color of the background gradient.
	back-middle	The middle color of the background gradient.
	back-bottom	The bottom color of the background gradient.
	icon-frame-back	The background color of the frame of a selected element in the toolbar when using SWITCH?.
	lower-edge	The 1 pixel line at the bottom of the toolbar.
	font-color	The color of the font used in the toolbar.

toolbar-font

This object! value contains information on the font used below the icons.

size

This pair! value contains the size of the toolbar, like any other VID face. However, for TOOLBAR, specifying a width is necessary, while the height is not necessary. When the height is not specified, TOOLBAR will adapt the height to the contents. When the height is specified, that height will be used instead of the calculated height.

str-size

string

String to measure (string! value)

Internal function to determine the width of a string using TOOLBAR-FONT.

set-backframe

face

Face to set highlight on (word! value)

This function highlights the icon frame. It's used internally in SWITCH? mode.

unset-backframe

face

Face to remove highlight from (word! value)

This function removes highlighting of the icon frame. It's used internally in SWITCH? mode.

switch?

Flag

When set to TRUE, it's possible to highlight a toolbar element when left-clicking on it, which can be used for currently selected item type toolbars.

selected

When SWITCH? is TRUE, SELECTED can contain a word value for the toolbar element that should be set after using UPDATE.

For example, if you have an image type element in your toolbar named 'open, SELECTED should be set to 'open, if you want the element selected after using UPDATE.

This variable will also be set every time, you left-click an image type element, also only when SWITCH? is TRUE.

When SELECTED is NONE, no element is selected.

elements

Block value with the word values of the elements in the toolbar. Is used internally to get the elements by word.

do-element

word

Name of the element to perform the action on (word! value)

Function to do the action of an element. Note that DO-ELEMENT does not switch the active element when using SWITCH?.

orientation (Not implemented!)

This is a word which describes the orientation of the toolbar:

	up	This displays the toolbar as it should look when placing it at the top of the window. This is the default orientation and the only orientation available at this time. The height of the toolbar is determined by the tallest element in the toolbar.
	left	This displays the toolbar as it should look when placing it at the left side of the window. The width of the toolbar is determined by the widest element in the toolbar.
	right	This displays the toolbar as it should look when placing it at the right side of the window. The width of the toolbar is determined by the widest element in the toolbar.
	down	This displays the toolbar as it should look when placing it at the bottom of the window. The height of the toolbar is determined by the tallest element in the toolbar.

Notice that the orientation does not influence the placement of the toolbar. It is your job to place the toolbar correctly in the window.

Known Bugs

A bug will cause REBOL to crash, if you are opening and then closing an INFORM window from a window with a TOOLBAR in it. The details involve an DETECT function in the FEEL objects for each button, but a solution has not yet been found.