TOOLBAR

Purpose:

Edits the properties of a toolbar.

Syntax:

TOOLBAR(

toolbar, button, method, fg, bg, actionkey, insert, redraw, "label", "command", "message")

toolbar

-

An integer, the target toolbar:

1:

Main Worksheet toolbar

2:

Activated Window toolbar.

3:

Data cursor toolbar

6:

Drawing toolbar

button

-

An integer, the location, counted from left, starting from 1. Set to -1 to place a button as the last button on the toolbar.

method

-

An integer, the the method for rendering the buttons on the screen:

1:

BIT MAPPED. Button is rendered using either its pre-installed bitmap or the filename specified by "label".

2:

DRAWN. Button is rendered using its pre-installed drawn figure.

4:

WRITTEN. Button is a string, supplied by "label."

8:

NONE. The button is removed from the screen.

fg  

-

Optional. An integer, the foreground color. Color mapping varies, depending on method. Set to -1 to specify the default.

bg

-

Optional. An integer, the background color. Color mapping varies, depending on method. Set to -1 to specify the default.

actionkey

-

Optional. An integer. Returns a single character code to the application. Keys are integer key codes, based on ASCII. Non-ASCII keys are private to the application. Action keys are used internally in the application and are mentioned here for completeness, but "command" strings (below) are the preferred method of customization.

insert

-

Optional. An integer, the new button insertion mode for the location specified by button.

0:

Overwrite the existing button at the specified location.

1:

Insert the new button at the specified location (default).

redraw

-

Optional. An integer, the button redraw mode.

0:

Do not redraw.

1:

Redraw immediately (default).

"label"  

-

A string to label the button under the WRITTEN rendering method. For BIT MAPPED (method 1), this is the path to a loadable bitmap file.

"command"

-

A string. This is the action taken when the button is pressed. Valid strings include any commands that can be executed in the current state of the application.

"message"  

-

Optional. A string. This help message is displayed on the status line when the mouse is held over the button. Defaults to the button label.

Example:

toolbar(1, -1, 4, LRED, " Noise ", "gnorm(1000,1)")

 

Adds a button called "Noise", to the end of the main Worksheet toolbar. When pressed, the button creates a 1000 point random noise series in the current Window.

 

toolbar(1, -1, 8)

 

removes the button.

Example:

Add a button called "Stats", to the main worksheet toolbar, which pops up the "Summary Statistics" menu:

 

toolbar(1, 8, 4, RED, " Stats", '_MF("statsum.men")')

 

Likewise, you can convert the "style" button to a menu of choices:

 

toolbar(1,5,2, " ", '_MF("gviews.men")')

Example:

toolbar(1, -1, 1, gethome + "data\charts.png", "grand(7, 1);bars;bargap(0);rainbow", "Bars")

 

Adds a bitmap button to the end of the main Worksheet toolbar. When pressed, the button creates a 7 point bar chart in the current Window.

Remarks:

"Command", if present, overrides actionkey. An empty command string (" ") will allow the actionkey, if any, to take precedence.

 

BITMAPPED rendering may not be available on all platforms.

 

It is possible to install buttons that are inappropriate to the state of the worksheet (e.g., a button to fetch new data, which would be fine on the main Worksheet toolbar, would be inappropriate to the data cursor toolbar).

 

If a toolbar button function requires quotes, use double quotes, then surround the entire string with single quotes.

 

To make a toolbar button permanent, add the toolbar function to the splmain() routine in the file dadisp.spl. For example, in dadisp.spl:

 

// dadisp.spl

splmain()

{

    toolbar(1, 8, 4, LRED, " Stats", '_MF("statsum.men")'); 

}

 

The button now appears on the toolbar for every DADiSP session.

 

See $INITWKS for a macro that executes when a Worksheet is loaded. $INITWKS can be used to customize specific Worksheets with automatically loading toolbar buttons.

See Also:

$DEINITWKS

$INITWKS