Creating Optional Areas in VDA Tools

Application Developer Guide > Building VDA Tools > Creating Optional Areas in VDA Tools

You can make specific areas in a VDA Tool optional and provide a menu that allows the user to show or hide these optional areas. For example, the WzSurface VDA Tool contains three optional areas: the Buttonbar, the Controls area, and the Message area. Using the Options menu, the user can choose to hide or show any combination of these areas.

The following sections discuss the steps required to create optional areas in VDA Tools.

Modify the Menu Structure

Add the Option menu code to the menu structure for the VDA Tool. To do this, edit the VDA Tool menu file. For instance, for WzSurface, this file is called wzsurfacemenus.pro.

The Option menu code, shown below, should be inserted immediately before the code for the Windows menu:

NAME: ['OptionsMenu', 'OptionsMenu'],$

MENUBUTTON: '',$

MENU:{,CALLBACK:'WoGMBOptionsButtonBarCB',$

NAME: 'OptionsButtonBar',$

TOGGLE: '', $

CALLBACK:'WoGMBOptionsControlsAreaCB', $

NAME: 'OptionsControlsArea',$

TOGGLE: '', $

CALLBACK:'WoGMBOptionsMessageAreaCB', $

NAME: 'OptionsMessageArea',$

TOGGLE: '' $

}, $

Adjust the Menu Pane Number

For existing VDA Tools, in the main VDA Tool procedure file (e.g.,
wzsurface.pro), increment by one the pane number that is saved for the WINDOW_MENU attribute.

For example,

tmp = TmSetAttribute(tool_name, 'MENUBAR', 'WINDOW_MENU', 6)

should be changed to:

tmp = TmSetAttribute(tool_name, 'MENUBAR', 'WINDOW_MENU', 7)

Set the Status of the Option Menu Toggles

Set the status of the menu toggles to the correct state by getting the current toggle settings and resetting them accordingly. This step is needed because it is possible that these values were saved in a previous session and then restored.

The following code fragment is taken from wzsurface.pro. It shows how TmGetAttribute is used to get the current status (shown or hidden) for the Buttonbar, Controls area, and Message area. The returned values are then used in WoMenuBarSetToggle to reset the Option menu toggles.

status = [ $

TmGetAttribute(tool_name, 'TM', 'BUTTONBAR_STATUS', $
Default=1), $

TmGetAttribute(tool_name, 'TM', 'CONTROLS_STATUS', $
Default=1), $

TmGetAttribute(tool_name, 'TM', 'MESSAGE_STATUS', $
Default=1) $

WoMenuBarSetToggle, tool_name, [7, 7, 7], [1, 2, 3], status

Call WoGMBOptionsInit

After creating all the optional areas in the VDA Tool (e.g., for WzSurface, this includes the Buttonbar, Controls area, and Message area), call the routine WoGMBOptionsInit:

WoGMBOptionsInit, tool_name

This routine checks the *_STATUS attributes and hides those areas that should not appear when the VDA Tool is managed.

Implementation for Optional Message Area

The WoMessage routine is equipped to automatically handle the unregistering of the message area.

Implementation for Optional Button Bar

There are two requirements for creating an optional button bar. First, the button bar and the status area (tool tips) must be in a single form that can be unmanaged. Second, the parent of the form must also be a form with attachments to the other widgets in the tool.

For example, if the original code is:

bblayout = WwLayout(layout, /Form, Top=bar, /Left, /Right)

tb  = WoButtonBar(bblayout , tool_name, /Top, /Graphics, $
/Left, /Right)

The following modifications must be made, where the button bar and status area are children of a form, which is in turn the child of a form.

bbtoplayout = WwLayout(layout, /Form, Top=bar, /Left, /Right)

Create a top-level form.

bblayout = WwLayout(bbtoplayout, /Form, /Top, /Left, /Right)

Create a child form that can be unmanaged.

tb = WoButtonBar(bblayout, tool_name, /Top, /Graphics, $
/Left, /Right)

Attach the button bar to bblayout.

s = TmSetAttribute(tool_name, 'TM', 'BUTTONBAR_ID', bblayout)

Attach the status area to bblayout.

All attachments from other widgets must be made to bbtoplayout. Specifically the drawing area and controls areas should have a top attachment to bbtoplayout.

Implementation for Optional Controls Area

An optional controls area is created much like the optional button bar. First, the controls area must be in a layout that can be unmanaged. Second, like with the button bar, the parent of the form must also be a form with attachments to the other widgets in the tool.

The following lines of code demonstrate the correct way to create an optional controls area:

ctltopLayout = WwLayout(layout, /Form, Top=bbtoplayout, $
Bottom=ms, /Left)

Create the top-level layout.

controlsLayout = WwLayout(ctltopLayout, /Form, /Frame, $
/Top, /Bottom, /Left, /Right)

Create a child form that can be unmanaged.

save_wid = WwGetValue(controlsLayout, /Parent)

While it looks like the WwGetValue call returns ctltopLayout it really returns the widget ID for the frame widget that was created. If the second WwLayout call above did not have the Frame keyword, the call to WwGetValue would not have been necessary, and the controlsLayout widget ID could be used in the following assignment statement.

s = TmSetAttribute(tool_name, 'TM', 'CONTROLS_ID', save_wid)

Version 2017.1