Providing toolbars

To make your MDI application easier to use, you can add toolbars
with buttons that users can click as a shortcut for choosing an
item from a menu. You can associate a toolbar with the MDI frame
and a toolbar with the active sheet. This screen shows New, Print,
and Exit buttons on the toolbar associated with the Frame (the FrameBar),
and window management buttons on the toolbar associated with the
sheet (the SheetBar):

How toolbars work

Toolbars you add to an MDI application behave like the toolbars
provided in the PowerBuilder development environment:

• Users can choose to display
  or not display text in a toolbar, use PowerTips, float the toolbar,
  move the toolbar around the frame, and dock it underneath or beside
  any other toolbar. No coding is required to support these basic
  toolbar operations.
• Toolbar buttons map directly to menu items. Clicking
  a toolbar button is the same as clicking its corresponding menu
  item (or pressing the accelerator key for that item).
• Toolbars work only in MDI frame and MDI sheet windows.
  If you open a non-MDI window with a menu that has a toolbar, the
  toolbar will not display.
• If both the sheet and the frame have toolbars and
  the sheet is open, then the menu that is displayed is the menu for
  the sheet, but both toolbars appear and are operative.
• If the currently active sheet does not have a menu,
  then the menu and toolbar for the frame remain in place and are
  operative. This can be confusing to your user, because the displayed
  menu is not for the active sheet. If any sheet has a menu, then
  all sheets should probably have a menu.

Menus can have multiple toolbars

A single menu can have more than one toolbar. When you associate
a menu that has multiple toolbars with an MDI frame or sheet, PowerBuilder displays
all the toolbars when you open the window. This screen shows a sheet
open in a frame, with one FrameBar and two Sheetbars:

You can work with the toolbars independently. For example,
you can float any of the toolbars, move them around the frame, and
dock them at different locations within the frame.

The button associated with a menu item can appear on only
one toolbar at a time. To indicate which toolbar a menu item’s
button belongs to, you set the ToolbarItemBarIndex property for
the menu item. All items that have the same index number appear
on the same toolbar.

Adding toolbars to an MDI application

PowerBuilder provides an easy way for you to add toolbars to
an MDI application: when you are defining an item in the Menu painter
for a menu that will be associated with either an MDI frame window
or an MDI sheet, you simply specify that you want the menu item
to display in the toolbar with a specific picture. During execution, PowerBuilder automatically
generates a toolbar for the MDI frame window or sheet containing
the menu. The toolbar associated with the MDI frame is called the FrameBar.
The toolbar associated with the active sheet is called the SheetBar.

To add toolbars to an MDI window:

1. In the Menu painter, specify the display
   characteristics of the menu items you want to display in the toolbar.

   For details, see “Setting toolbar properties
   in the Menu painter”.

2. (Optional) In the Menu painter, specify drop-down
   toolbars for menu items.

3. In the Window painter, associate the menu with
   the window and turn on the display of the toolbar.

4. (Optional) In the Window painter, specify other
   properties, such as the size and location of a floating toolbar,
   on the Toolbar property page.

Setting toolbar properties in the Menu painter

In the Menu painter, you specify which menu items you want
to display in the toolbar, the text for the toolbar button and tip,
the pictures to use to represent the menu items, and other characteristics
of the toolbar.

To specify the display characteristics of a toolbar
item:

1. Open the menu in the Menu painter and select
   the menu item you want to display in the toolbar.

2. Select the Toolbar property page and set properties
   of the toolbar item as shown in Table 5-1.

   Table 5-1: Toolbar properties in the Menu
   painter

   Property	What to specify
   ToolbarItemText	Specify two different text values for the toolbar button and PowerTip with a comma-delimited string, as follows: PowerBuilder <i>Text in button, PowerTip</i> 1 <i>Text in button, PowerTip</i>
   ToolbarItemName	Choose a stock picture from the drop-down list or browse to select a BMP file. If you choose a stock picture, PowerBuilder uses the up version when the item is not clicked and the down version when the item is clicked (the up version appears raised and the down version appears indented). If you are specifying a file, the picture should be 16 pixels wide and 15 pixels high.
   ToolbarItemDownName	Specify a different picture to display when the item is clicked (optional).
   ToolbarItemVisible	Clear if you want the toolbar button to be hidden. The default is visible.
   ToolbarItemDown	Check if you want the down version of the button to display initially.
   ToolbarItemSpace	Specify any integer if you want to leave space before the picture in the toolbar. Experiment with values to get the spacing the way you want it. If you leave the value 0, there will be no spacing before the picture. (Spacing is used only when the toolbar is not displaying text.)
   ToolbarItemOrder	Specify the order in which the item displays in the toolbar. If you leave the value 0, PowerBuilder places the item in the order in which it goes through the menu to build the toolbar.
   ToolbarItemBarIndex	Specify a number other than 1 if you want multiple toolbars to display for this menu. The number you specify determines which toolbar the current menu item appears on. All items that have the same index number appear on the same toolbar.

Menu items can have drop-down toolbars

A menu item can have a toolbar button associated with it that
displays a drop-down toolbar. When the user clicks on the
button, PowerBuilder displays a drop-down toolbar that shows all of
the toolbar buttons for menu items defined at the next level. For
example, if you define a drop-down toolbar for the File menu item,
the drop-down toolbar will show the buttons defined for the items
on the File menu (such as New, Open, Close, and Exit).

PowerBuilder displays a drop-down toolbar at runtime by default
if the Object Type of the menu item is MenuCascade. You can specify
programmatically whether submenu items display in a drop-down toolbar
or as normal toolbar items by setting the DropDown property of the
menu item. For example, if you want a descendent menu item to have
a drop-down toolbar, but not its ancestor, clear the DropDown check
box on the ancestor’s Toolbar property page, and set the
DropDown property of the descendent menu item to TRUE in
a script.

To specify a drop-down toolbar for a menu item:

1. In the Menu painter, select the menu item
   for which you want to add a drop-down toolbar.

2. On the Toolbar property page, change the Object
   Type to MenuCascade.

3. (Optional) Specify the number of columns you
   want to display in the Columns box.

   The default is a single column. If there are many items on
   the submenu, as there are on the toolbar item for inserting controls
   in the Window painter, you will probably want to specify three or
   four columns.

Setting toolbar properties in the Window painter

In the Window painter, you associate the menu with the MDI
window on the window’s General property page. The window
displays the toolbar by default. If you do not want the toolbar
to display, clear the ToolbarVisible check
box on the window’s Toolbar property page. You can also
specify the toolbar’s alignment and position on this property
page.

Setting toolbar properties in the Application painter

You can specify global properties for all toolbars in your
application on the Toolbar property page in the Application painter
or by setting properties of the Application object in a script.
Typically you set these in the application’s Open event,
but you can set them anywhere.

Table 5-2: Toolbar properties in the Application painter

Property	Meaning
ToolbarFrameTitle	The text that displays as the title for the FrameBar when it is floating.
ToolbarSheetTitle	The text that displays as the title for the SheetBar when it is floating.
ToolbarPopMenuText	(String) Text to display on the pop-up menu for toolbars (see below).
ToolbarUserControl	(Boolean) If TRUE (default), users can use the toolbar pop-up menu to hide or show the toolbars, move toolbars, or show text. If FALSE, users cannot manipulate the toolbar.
ToolbarText	(Boolean) If TRUE, text displays in the buttons. If FALSE (the default), text does not display.
ToolbarTips	(Boolean) If TRUE (default), PowerTips display when text is not displayed in the buttons. If FALSE, PowerTips do not display.

Specifying the text in the toolbar’s
pop-up menu

By default, PowerBuilder provides a pop-up menu for the toolbar,
which users can use to manipulate the toolbar. It is similar to
the pop-up menu you use to manipulate the PowerBar and PainterBar.

You can change the text that displays in this menu (but you
cannot change the functionality of the menu items in the menu).
Typically, you do this when you are building an application in a
language other than English. You change the text as follows:

• The first two items in the pop-up menu display the
  titles set in ToolbarFrameTitle and ToolbarSheetTitle (defaults:
  FrameBar and SheetBar).
• The remaining text items are specified by the property ToolbarPopMenuText.
  To specify values for this property, use a comma-delimited
  list of values to replace the text “Left,” “Top,” “Right,” “Bottom,” “Floating,” “Show
  Text,” and “Show PowerTips”:
  PowerBuilder

  toolbarPopMenuText = "<i>left, top, right, bottom, floating, showText,<br /> showPowerTips</i>"

  1	toolbarPopMenuText = "<i>left, top, right, bottom, floating, showText,<br />   showPowerTips</i>"

For example, to change the text for the toolbar pop-up menu
to German and have hot keys underlined for each, you would specify
the following:

Using toolbars in MDI applications

This section describes some techniques you can use to customize
the behavior of your toolbars.

Disabling toolbar buttons

To disable a toolbar button, you need to disable the menu
item with which it is associated. Disabling the menu item disables
the toolbar button automatically.

To disable a menu item, you need to set the Enabled property
of the menu item:

Hiding toolbar buttons

To hide a menu item, you set the Visible property of the item:

Hiding a menu item does not cause its toolbar button to disappear
or be disabled. To hide a toolbar button, you need to set the ToolbarItemVisible property
of the menu item:

Hiding a menu item does not cause the toolbar buttons for
the drop-down or cascading menu items at the next level to disappear
or be disabled. You need to hide or disable these buttons individually.

Setting the current item in a drop-down toolbar

When a user clicks on a toolbar button in a drop-down toolbar, PowerBuilder makes
the selected button the current item. This makes it easy for the
user to perform a particular toolbar action repeatedly. You can
also make a particular button the current item programmatically
by setting the CurrentItem property of the MenuCascade object. For
example, to set the current item to the toolbar button for the New
option on the File menu, you could execute this line in a script:

In order for this to work, you would need to specify MenuCascade
as the object type for the File menu in the Menu painter.

Testing for whether a toolbar is moved

Whenever a toolbar moves in an MDI frame window, PowerBuilder triggers the
ToolBarMoved event for the window. In the script for this event,
you can test to see which toolbar has moved and perform some processing.
When the user moves the FrameBar or SheetBar, the ToolbarMoved event
is triggered and the Message.WordParm and Message.LongParm properties
are populated with values that indicate which toolbar was moved:

Table 5-3: Values of Message.WordParm and Message.LongParm properties

Property	Value	Meaning
Message.WordParm	0	FrameBar moved
	1	SheetBar moved
Message.LongParm	0	Moved to left
	1	Moved to top
	2	Moved to right
	3	Moved to bottom
	4	Set to floating

Saving and restoring toolbar settings

You can save and restore the current toolbar settings using
functions that retrieve information about your toolbar settings,
and you can modify these settings.

GetToolbar and GetToolbarPos allow
you to retrieve the current toolbar settings. SetToolbar and SetToolbarPos allow
you to change the toolbar settings. The syntax you use for the GetToolbarPos and SetToolbarPos functions
varies depending on whether the toolbar you are working with is
floating or docked.

Floating toolbars

The position of a floating toolbar is determined by its x
and y coordinates. The size of a floating toolbar is determined
by its width and height.

When you code the GetToolbarPos and SetToolbarPos functions
for a floating toolbar, you need to include arguments for the x
and y coordinates and the width and height.

Docked toolbars

The position of a docked toolbar is determined by its docking
row and its offset from the beginning of the docking row. For toolbars
at the top or bottom, the offset for a docked toolbar is measured
from the left edge. For toolbars at the left or right, the offset
is measured from the top.

By default, the docking row for a toolbar is the same as its
bar index. If you align the toolbar with a different border in the
window, its docking row may change depending on where you place
it.

When you code the GetToolbarPos and SetToolbarPos functions
for a docked toolbar, you need to include arguments for the docking
row and the offset.

Example

The example below shows how to use a custom class user object
to manage toolbar settings. The user object has two functions, one
for saving the current settings and the other for restoring the
settings later on. Because the logic required to save and restore
the settings is handled in the user object (instead of in the window
itself), this logic can easily be used with any window.

The sample code shown below supports both fixed and floating
toolbars.

Script for the window’s Open event When the window opens, the following script restores the toolbar
settings from an initialization file. To restore the settings, it
creates a custom class user object called u_toolbar and calls
the Restore function:

Script for the window’s Close event When the window closes, the following script saves the toolbar
settings by calling the Save function. Once the
settings have been saved, it destroys the user object:

Script for the Save function The Save function has three arguments:

• Win – provides
  the window reference
• File – provides the
  name of the file where the settings should be saved
• Section – identifies
  the section where the settings should be saved

The Save function uses the GetToolbar and GetToolbarPos functions
to retrieve the current toolbar settings. To write the settings
to the initialization file, it uses the SetProfileString function.

The Save function can handle multiple toolbars
for a single menu. It uses the bar index to keep track of information
for each toolbar:

Script for the Restore function The Restore function has the same three arguments
as the Save function. It uses the ProfileString function
to retrieve toolbar settings from the initialization file. Once
the settings have been retrieved, it uses the SetToolbar and SetToolbarPos functions
to restore the toolbar settings.

Like the Save function, the Restore function
can handle multiple toolbars for a single menu. It uses the bar
index to keep track of information for each toolbar:

---