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 will be the menu
  for the sheet, but both toolbars will appear and be operative.
• If the currently active sheet does not have a menu,
  then the menu and toolbar for the frame remain in place and operative.
  This can be confusing to your user, because the displayed menu will
  not be 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.

2. (Optional) In the Menu painter, specify dropdown
   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:

   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 dropdown listbox 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 dropdown toolbars

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

PowerBuilder displays a dropdown toolbar at execution time by
default if the Object Type of the menu item is MenuCascade. You
can specify programmatically whether submenu items display in a
dropdown 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 dropdown toolbar, but not its ancestor, clear
the DropDown checkbox 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 dropdown toolbar for a menu item:

1. In the Menu painter, select the menu item
   for which you want to add a dropdown 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 don’t want the
toolbar to display, clear the ToolbarVisible checkbox
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).

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 popup menu for toolbars (see below)
ToolbarUserControl	(Boolean) If TRUE (default), users can use the toolbar popup 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
popup menu

By default, PowerBuilder provides a popup menu for the toolbar,
which users can use to manipulate the toolbar (it is similar to
the popup 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 will 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 popup 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 popup 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 dropdown 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 dropdown toolbar

When a user clicks on a toolbar button in a dropdown 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:

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 toolbarsettings

You can save and restore the current toolbar settings using
functions that retrieve information about your toolbar settings
and 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’re 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, which provides
  the window reference
• File, which provides the name of the file where
  the settings should be saved
• Section, which 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 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:

---