Totally Objects - ToolBars - Version 5.5 [1.0]

Introduction

This document explains how to use the ToolBars product from Totally Objects for IBM Smalltalk. It is assumed that the reader is familiar with building windows using widgets and managing callbacks: these concepts are explained in the VAST manuals..

Installing the ToolBars Product

This Totally Objects product has been packaged as a number of configuration maps. To import them into your library select 'Browse Configuration Maps' from the 'Tools' menu of the 'System Transcript'. In the 'Configuration Maps Browser' select 'Import...' from the 'Names' menu and select the file 'tobtb5-5_1-0-*.dat'. You should then select the configuration maps you require.

The configuration maps you have imported contains three applications.

To load the application select Version 5.5 [1.0.*] of 'Totally Objects, ToolBars' in the 'Configuration Maps Browser'. Select the applications that you wish to load and select 'Load' from the 'Applications' menu. Alternatively, load the configuration maps that contain the combination of applications you require.

Overview

Toolbars are added to a window by placing them within a docking area. The docking area can be configured to allow the toolbars that it contains to be dragged and organized by the user. Each toolbar can contain a number of buttons of which there are three types: Each of the buttons can be given an image (a CgIcon or a CgPixmap) and a text label. Additionally a second 'focus' image can be assigned; this will show when the mouse is over the button. The buttons can also be configured so the label is on multiple lines and is to the right or below the image.

The API

Methods in the API are placed in the category named 'TobTB-API'. Callbacks are in the category named 'TobTB-API (Callbacks)'. A description of each of these methods and the callbacks is given in the tables below.

CwWidget

Method

Description

createTobTBDockingArea:argBlock:

Creates a TobTBDockingAreaWidget (a docking drea) in the receiver.

TobTBDockingAreaWidget

Method

Description

areBarsMoveable, areBarsMoveable:

Gets and sets a Boolean value showing whether users can drag the toolbars within the docking area. When true, toolbars have a vertical 'thumb' line on the left-hand side.

barsFixed, barsMoveable

Equivalent to #areBarsMoveable: using the arguments false and true respectively.

createTobTBBar:argBlock:

Creates a TobTBBarWidget (a toolbar) in the receiver.

moveDownARow:, moveLeftwardsInRow:, moveRightwardsInRow:, moveUpARow:

Moves the argument (which must be a TobTBBarWidget that has been created in the receiver) between or within rows.

menu, menu:

Gets and sets a pop-up menu for the docking area. The value can be either a CwMenu, a CwRowColumn or nil.

Callback

Description

#barMovedDownCallback

Called whenever a toolbar is moved down within the docking area. The callData is an instance of TobTBToolBarMovedCallbackData which can be sent the message #toolBar to determine which toolbar was moved.

#barMovedLeftCallback

The same as #barMovedDownCallback but called when a toolbar is moved left.

#barMovedRightCallback

The same as #barMovedDownCallback but called when a toolbar is moved right.

#barMovedUpCallback

The same as #barMovedDownCallback but called when a toolbar is moved up.

#barsMoveableCallback

Called whenever the toolbars are toggled between being fixed or moveable.

TobTBBarWidget

Method

Description

createTobTBMenuButton:argBlock:

Creates a TobTBMenuButtonWidget (a Menu Button) in the receiver.

createTobTBPushAndMenuButton:argBlock:

Creates a createTobTBPushAndMenuButton: (a Combination Button) in the receiver.

createTobTBPushButton:argBlock:

Creates a TobTBPushButtonWidget (a Push Button) in the receiver.

fontList, fontList:

Gets and sets the fontList for the toolbar. When set, each button on the toolbar will have its fontList set.

labelString, labelString:

Gets and sets a label (a String) for the toolbar. Currently this value is not used in the representation of the toolbar.

setTextFont:

Equivalent to #fontList:. Included for compatibility.

uniformWidth, uniformWidth:

Gets and sets a Boolean value indicating whether buttons will be responsible for calculating their own width, or all buttons should resized to the widest button on the toolbar.

Methods common to TobTBMenuButtonWidget, TobTBPushButtonWidget and TobTBPushAndMenuButtonWidget (in addition to those found in CwWidget, CwExtendedWidget and CwExtendedComposite)

Method

Description

focusImage, focusImage:

Gets and sets an image that will be shown when the mouse moves over the button. It can be either a CgPixmap, a CgIcon or nil (in which case the image will not change when the mouse is over the button).

fontList, fontList:

Gets and sets the fontList for the button.

hasSeparator, hasSeparator:

Gets and sets a Boolean value indicating whether the button should be followed by an engraved vertical line.

image, image:

Gets and sets an image that will be shown on the button. It can be either a CgPixmap, a CgIcon or nil (in which case no image will be shown).

imageCropFrame, imageCropFrame:

Gets and sets a Rectangle that will be used to crop the image and focusImage. A value of nil is the same as a Rectangle with origin 0 @ 0 and height and width the same as the image (so the focus image will be cropped if necessary to be the same size as the image). This is useful if the image for many button are stored within the same pixmap.

labelBelow, labelRight

Positions the labelString either below or to the right of the image.

labelLines, labelLines:

Gets and sets an Integer number of lines over which the label will be shown. The default value is 1.

labelPosition, labelPosition:

Gets and sets an EsAtom (which can be either ##below or ##right) corresponding to the position of the labelString with respect to the image.

labelString, labelString:

Gets and sets a String to use as the buttons label. If this value is nil then no label is shown.

menu, menu:

Gets and sets a pop-up menu for the button. The value can be either a CwMenu, a CwRowColumn or nil.

mnemonic, mnemonic:

Gets and sets a Character corresponding to the 'Alt' key shortcut for the button. The first corresponding Character in the labelString (if any) will be underlined. If this value is nil then no mnemonic is assigned.

TobTBMenuButtonWidget

Method

Description

pullDownMenu, pullDownMenu:

Gets and sets a pull-down menu that will be shown whenever the button is pressed. The value can be either a CwMenu, a CwRowColumn or nil.

Callback

Description

aboutToPullDownMenuCallback

Called just before the pull-down menu is pulled down.

pulledDownMenuCallback

Called just after the pull-down menu is pulled down.

TobTBPushAndMenuButtonWidget

Method

Description

pullDownMenu, pullDownMenu:

Gets and sets a pull-down menu that will be shown whenever the button is pressed. The value can be either a CwMenu, a CwRowColumn or nil.

Callback

Description

aboutToPullDownMenuCallback

Called just before the pull-down menu is pulled down.

pressedCallback

Called when the button is pressed.

pulledDownMenuCallback

Called just after the pull-down menu is pulled down.

releasedCallback

Called when the button is released.

TobTBPushButtonWidget

Callback

Description

pressedCallback

Called when the button is pressed.

releasedCallback

Called when the button is released.

The Examples

TobTBExampleWindow

This window can be opened by executing:

Key Points

TobTBPartExampleWindow

This window can be opened by executing:

Although it is not difficult to build the toolbars using widgets, you may wish to integrate them into your windows built with parts.

Key Points


Further Information