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.

• TobToolBarsWidgetsApp - Contains everything you need to produce the toolbars. Any of your applications that use the toolbars should include this application as a prerequisite.
• TobToolBarsWidgetsExamplesApp - Contains examples toolbars within the Extended Widgets framework.
• TobToolBarsWidgetsPartsExamplesApp - Contains examples toolbars within the Parts framework. Although this product does not have a parts interface, the widgets can be incorporated in windows built using parts.

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

• Menu Buttons - These are similiar to the menu items in menu bar. If you click on them, a menu drops down.
• Push Buttons - These behave similarly to conventional push buttons.
• Combination Buttons - These have two components. A Push Button on the left and a Menu Button (showing a down pointing arrow) on the right.

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

This window can be opened by executing:

TobTBExampleWindow new open

Key Points

• The docking area has a bottom attachment of XmATTACHNONE (see #open). This cause the area to resize dynamically as the toolbars are moved.
• The icons are created using the method CgIcon class>>#fromImage:maskImage: to make the example work across all platforms. These icons could more easily have been created using other class methods of CgIcon, or could be CgPixmaps.

TobTBPartExampleWindow

This window can be opened by executing:

TobTBExampleWindow new openWidget

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

• The docking area is embedded within a Form part at the top of the window (with a text box attached to the bottom of it). This Form will not be visible within the Composition Editor as it has no height. The #aboutToOpenWidget event of this Form has be used to create the docking area.
• The icons are created by putting labels in the composition editor which are given the graphicsDescriptors required.
• The fonts are set by adopting the buttonFontName of the Form. Try changing the buttonFontName using the composition editor to see how this changes the look of the buttons.
• The menus are defined within the composition editor. Make sure you send them the message #createWidget before using them as pulldowns or popups for your buttons.
• Although there is no direct support for Hover Help in this product this functionality can be added to items on a toolbar. Take a look towards then end of the method #createToolBar1: to see how you can do this.

Further Information

If you would like to ask any questions about this product, its operation or its commercial terms, please contact sales@totallyobjects.com.

Copyright (c) 2002 DirectDual Limited (trading as TotallyObjects).

Totally Objects - DirectDual Limited,
34 Compton Avenue,
Gidea Park, Essex,
RM2 6ES, England.
Tel: +44 1708 733295
Fax: +44 1708 783438
sales@totallyobjects.com
DirectDual Limited is an IBM Object Connection member.