Using toolbars in MDI applications

This section describes some techniques you can use to customize the behavior of your toolbars and save and restore toolbar settings. For information about how to define and use menus and toolbars, see Working with Menus and Toolbars in Users Guide.

Customizing toolbar behavior

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:

m_test.m_file.m_new.Enabled = FALSE

Using alternate icons

The enabled and disabled states of each toolbar button are normally indicated by a pair of contrasting color and greyscale icons. For greater contrast between the enabled and disabled states, you can apply an alternate set of icons to the toolbar buttons, by setting the PBTOOLBARDISABLEMODE environment variable on your system to 1 .

Hiding toolbar buttons

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

m_test.m_file.m_open.Visible = FALSE

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:

m_test.m_file.m_open.ToolBarItemVisible = FALSE

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:

m_test.m_file.currentitem = m_test.m_file.m_new

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 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:

// Create the toolbar NVO
u_toolbar = create u_toolbar
// Restore the toolbar positions
u_toolbar.Restore(this,"toolbar.ini",   this.ClassName())

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:

// Save the toolbar 
stateu_toolbar.Save(this, "toolbar.ini", ClassName())
// Destroy the toolbar NVOdestroy u_toolbar

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:

// Store the toolbar settings for the passed window
integer index, row, offset, x, y, w, h
boolean visible
string visstring, alignstring, title
toolbaralignment alignmentFOR index = 1 to 16 

// Try to get the attributes for the bar.   
IF win.GetToolbar(index, visible, alignment, &
   title)= 1 THEN   
   // Convert visible to a string
   CHOOSE CASE visible
   CASE true
      visstring = "true"
   CASE false   
      visstring = "false"   
   END CHOOSE// Convert alignment to a string   

   CHOOSE CASE alignment      
   CASE AlignAtLeft!      
      alignstring = "left"
   CASE AlignAtTop!
      alignstring = "top"      
   CASE AlignAtRight!      
      alignstring = "right"      
   CASE AlignAtBottom!      
      alignstring = "bottom"      
   CASE Floating!      
      alignstring = "floating"
   END CHOOSE

   // Save the basic attributes   
   SetProfileString(file, section +  &      
      String(index), "visible", visstring)         
   SetProfileString(file, section +  &
      String(index), "alignment", alignstring)   
   SetProfileString(file, section +  &
      String(index), "title", title)

   // Save the fixed position
   win.GetToolbarPos(index, row, offset)
   SetProfileString(file, section +  &
      String(index), "row", String(row))
   SetProfileString(file, section +  &
      String(index), "offset", String(offset))

   // Save the floating position
   win.GetToolbarPos(index, x, y, w, h)
   SetProfileString(file, section +  &
      String(index), "x", String(x))
   SetProfileString(file, section +  &
      String(index), "y", String(y))
   SetProfileString(file, section +  &
      String(index), "w", String(w))

   SetProfileString(file, section +  &
      String(index), "h", String(h))
   END IF
NEXT

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:

// Restore toolbar settings for the passed window

integer index, row, offset, x, y, w, h
boolean visible
string visstring, alignstring, title
toolbaralignment alignment

FOR index = 1 to 16
  // Try to get the attributes for the bar.
  IF win.GetToolbar(index, visible, alignment, &
    title)= 1 THEN
    // Try to get the attributes from the .ini
    // file
    visstring = ProfileString(file, section +  &
      String(index), "visible", "")
    IF visstring > "" THEN
      // Get all of the attributes
      alignstring = ProfileString(file, section +  &
        String(index), "alignment", "left")
      title = ProfileString(file, section +  &
        String(index), "title", "(Untitled)")
      row = Integer(ProfileString(file, section +  &
        String(index), "row", "1"))
      offset = Integer(ProfileString(file, &
        section + String(index), "offset", "0"))
      x = Integer(ProfileString(file, section +  &
        String(index), "x", "0"))
      y = Integer(ProfileString(file, section +  &
        String(index), "y", "0"))
      w = Integer(ProfileString(file, section +  &
        String(index), "w", "0"))
      h = Integer(ProfileString(file, section +  &
        String(index), "h", "0"))

      // Convert visstring to a boolean
      CHOOSE CASE visstring
      CASE "true"
        visible = true
      CASE "false"
        visible = false
      END CHOOSE

      // Convert alignstring to toolbaralignment
      CHOOSE CASE alignstring
      CASE "left"
        alignment = AlignAtLeft!
      CASE "top"
        alignment = AlignAtTop!
      CASE "right"
        alignment = AlignAtRight!
      CASE "bottom"
        alignment = AlignAtBottom!
      CASE "floating"
        alignment = Floating!
      END CHOOSE

      // Set the new position
      win.SetToolbar(index, visible, alignment, title)
      win.SetToolbarPos(index, row, offset, false)
      win.SetToolbarPos(index, x, y, w, h)
    END IF
  END IF
NEXT