Etudes for Microsoft Word Programmers

Home ] Up ] Etude 2.1. Built-in Toolbars ] Etude 2.2. Custom Toolbars ] Etude 2.3. Built-in Icons ] Etude 2.4. Icon Instruments ] Etude 2.5. Modifying Toolbars ]


Etude 2.2. Custom Toolbars

Far too many people spend their lives reading the menu instead of enjoying the banquet.

Unknown author.
http://www.websters-online-dictionary.org/definition/menu

 

If you need a toolbar with "non-button" controls, you need VBA. In this etude we investigate the "programming way" of creating toolbars, adding toolbar controls and handling events. Basic types of toolbar controls and their methods and properties are investigated as well. The next two etudes - etude 2.3 "Built-in Icons" and etude 2.4 "Icon Instruments" - are dedicated to icons.

Resources

Template "AhToolBars.dot", 21 Kb, ZIP [download].

It is high time to study the basic types of Microsoft Office toolbar controls and their methods and properties.

Types of Microsoft Word (Office) Controls

Control type (value of CommandBarControl.Type property)  could be one of the constants listed in the following table. When the user creates a toolbar "visually" (see the previous etude 2.1 "Built-in Toolbars") then only msoControlButton and msoControlPopup are used. Other controls could be created only using the "programming way", i.e. VBA.

Constant

Type

msoControlActiveX

ActiveX Control

msoControlButton

msoControlButtonDropdown

msoControlButtonPopup

msoControlComboBox

msoControlCustom

Reserved for future use.

msoControlDropdown

msoControlEdit

msoControlExpandingGrid

msoControlGauge

msoControlGenericDropdown

Reserved for future use.

msoControlGraphicCombo

msoControlGraphicDropdown

msoControlGraphicPopup

Reserved for future use.

msoControlGrid

msoControlLabel

Reserved for future use.

msoControlOCXDropDown

msoControlPane

Pane control

msoControlPopup

msoControlSplitButtonMRUPopup

msoControlSplitButtonPopup

msoControlSplitDropdown

msoControlSplitExpandingGrid

Reserved for future use.

 

Control Methods and Properties

The control has a set of attributes and methods that allow to manipulate buttons, lists and menu items.

Any controls has a "Visible" property and an "Enabled" property.

The CopyFace and PasteFace methods are used to change the control's icon using the clipboard. The FaceId property is used for built-in icons.

The "OnAction" property is a string which contains the name of macros to call "on action". To change the control's functionality a user should set the property "OnAction" to the name of the required subroutine (macros).

Buttons

The property "State" represents the button state.

Control object properties and methods are described in the following table.

Property/Method

Description

CopyFace

Copies the control's icon to the clipboard.

PasteFace

Pastes the control's icon from the clipboard. If the clipboard is empty, an error occur.

FaceId

Sets the built-in icon to the control. Not all FaceId values correspond to the built-in icons.

Id

Sets the built-in functionality to the control. For example id = 23 corresponds to the "File\Open" command.

State

Represents the state of the control. Can be one of the MsoButtonState enumeration constants: msoButtonDown, msoButtonMixed, or msoButtonUp.

Style

Represents the style of the control. Can be one of the MsoButtonStyle enumeration constants: msoButtonAutomatic, msoButtonIcon, msoButtonCaption, msoButtonIconAndCaption, msoButtonIconAndCaptionBelow, msoButtonIconAndWrapCaption, msoButtonIconAndWrapCaptionBelow, msoButtonWrapCaption.

OnAction

Sets the procedure which is called "on action" (when the user presses the button, selects menu item or changes the edit control text).

Visible

Manages the control visibility.

Enabled

Represents whether the control or tollbar is enabled or not. Disabled toolbar name is not displayed in the toolbar's list.

List and Edit Controls

Lists and Edit controls can be created only by means of programming. Their properties and methods are described in the following table.

Property/Method

Description

Add

Adds a control to the toolbar.

Parameter Type can be one of the MsoControlType enumeration constants: msoControlEdit  (edit control), msoControlDropdown (dropdown list) or msoControlComboBox  (combo box).

AddItem

Adds list or combo box item.

Caption

Represents the caption of the control. The caption is displayed only if Style property is set to msoComboLabel.

Style

Represents the style of the control's caption. Can be one of the MsoComboStyle enumeration constants: msoComboLabel (the caption is displayed) or msoComboNormal (the caption is not displayed).

OnAction

Sets the name of the procedure which is called when a control event occurs (button is pressed or list item is selected or edit control text is changed and Enter button is pressed).

 

Menus and Toolbars

Menus and toolbars can be created in "visual" mode as well as in "program" mode. The basic properties and methods for menu, submenu and their elements are described in the following table.

Property/Method

Description

Add

Adds a menu (menubar = True) or toolbar to the CommandBars collection.

Protection

Sets a protection type to the menu or toolbar. Can be one of the MsoBarProtection enumeration constants:

msoBarNoChangeDock, msoBarNoChangeVisible, msoBarNoCustomize, msoBarNoHorizontalDock, msoBarNoMove, msoBarNoProtection, msoBarNoResize, msoBarNoVerticalDock.

Position

Sets a menu or toolbar position relative to the main application window. Can be one of the MsoBarPosition enumeration constants:

msoBarLeft, msoBarTop, msoBarRight, msoBarBottom, msoBarFloating, msoBarPopup  (for popup menus).

 

Menu Items

The basic properties and methods for menu items are described in the following table.

Property/Method

Description

Add

Adds a menu item. Can be one of the MsoControlType enumeration constants:

msoControlButton  (button)
msoControlEdit  (edit control),
msoControlDropdown  (dropdown list),
msoControlComboBox  (combo box).

AddItem

Adds an element to the list.

Style

Represents the style of the control's caption. Can be one of the MsoComboStyle enumeration constants: msoComboLabel (the caption is displayed) or msoComboNormal (the caption is not displayed).

OnAction

Sets the name of the procedure which is called when the user selects the menu item.

 

Functional Specification

Task

The task is to create the template "AhToolBars.dot", in which the macros for working with toolbars are accommodated. The toolbar "AhToolBars" should provide access to the operations of creation and removal of the custom toolbar "Toolbar1", which should contain the controls of the following types - msoControlComboBox, msoControlDropdown, msoControlPopup, msoControlEdit and msoControlButton. Other types of controls are used in the built-in Microsoft Word toolbars, but unfortunately are not supported neither visually nor programmatically.

Toolbar "AhToolBars"

The toolbar "AhToolbars " looks like this:

Button

Macro

Description

Help

AhToolBarsHelp

Brief prompt on the toolbar buttons

Create

AhToolBarCreate

Creates custom toolbar "Toolbar1".

Delete

AhToolBarDelete

Deletes custom toolbar "Toolbar1".

Brief Prompt

Brief prompt on the toolbar buttons looks like this:

Creating Custom Toolbar

Pressing "Create" button results in the creation of a new custom toolbar "Toolbar1" which contains different types of the controls.

The "Toolbar1" toolbar looks like this:

 

Deleting Custom Toolbar

Pressing "Delete" button results in the deletion of the custom toolbar "Toolbar1".

Implementation - Template "AhToolbars.dot"

The operations of creating and deleting of custom toolbar are implemented in the  "AhToolbars.dot" template. The toolbar "AhToolbars" represents a simple interface to these operations.

Constants

'
' File AhToolBars.dot|AhToolBars
'
' Etudes for Microsoft Word Programmers.
' Etude 2.2. Custom Toolbars.
'
' First published on http://www.transcriber.ru
'
' © 2000-2008. Evgeny Akhundzhanov. All rights reserved worldwide.
'
Option Explicit
'
' Constants
'
Const cStrToolbarName As String = "Toolbar1"
Const ciInsertIndex As Long = 1

Subroutine AhToolbarsHelp

'
' AhToolbarsHelp
'
Sub AhToolbarsHelp()
        MsgBox "Etudes for Microsoft Word Programmers." & vbCrLf & _
        "Etude 2.2. Custom Toolbars with msoControl(ComboBox, Dropdown, Popup, Edit, Button)." & vbCrLf & _
        "http://www.transcriber.ru" & vbCrLf & vbCrLf & _
        "Create - creates custom toolbar" & vbCrLf & _
       
"Delete - deletes custom toolbar"
End Sub

Subroutine AhToolbarCreate

'
' AhToolbarCreate
'
Sub AhToolbarCreate()
    AhToolbarDelete
    CommandBars.Add(Name:=cStrToolbarName).Visible = True
    AhToolBarAddControls

End Sub

Subroutine AhToolbarDelete

'
'
AhToolbarDelete - Удаление панели инструментов "Toolbar1".
'
Sub AhToolbarDelete()
    On Error Resume Next
    CommandBars(cStrToolbarName).Delete

End Sub

Subroutine AhComboBox

When the user selects an element from the combo box, the AhComboBox macros is called. The ListIndex property of the control represents the list index and the Text  property represents the list item text.

When the user enters text to the edit control and presses the Enter button, the ListIndex property value is zero.

Here is the macro that handles the 'combo box' events.

'
' AhComboBox
'
Sub AhComboBox()
Dim ctrl As CommandBarControl
    For Each ctrl In CommandBars(cStrToolbarName).Controls
        If ctrl.OnAction = "AhComboBox" Then
            MsgBox "AhComboBox Event. Index = " & ctrl.ListIndex & " Text = " & ctrl.Text
        End If
    Next ctrl
End Sub

Subroutine AhListBox

When the user selects an element from the dropdown list, the AhListBox macros is called. The ListIndex property of the control represents the list index and the Text  property represents the list item text.

Here is the macro that handles the 'list box' events.

'
' AhListBox
'
Sub AhListBox()
Dim ctrl As CommandBarControl
    For Each ctrl In CommandBars(cStrToolbarName).Controls
        If ctrl.OnAction = "AhListBox" Then
            MsgBox "AhListBox Event. Index = " & ctrl.ListIndex & " Text = " & ctrl.Text
        End If
    Next ctrl
End Sub

Subroutine AhPopup

Here is the macro that handles the 'menu' events.

'
' AhPopup
'
Sub AhPopup()
Dim ctrl As CommandBarControl
    For Each ctrl In CommandBars(cStrToolbarName).Controls
        If ctrl.OnAction = "AhPopup" Then
            ' This is unusable. Prevents menu from displaying items.
            ' MsgBox "AhPopup Event."
        End If
    Next ctrl

End Sub

Subroutines AhPopupMenuItemXXX

When the user selects an item from the menu, the AhPopupMenuItemXXX macros is called.

Here is the macro that handles the 'menu item' events.

'
' AhPopupMenuItem1
'
Sub AhPopupMenuItem1()
    MsgBox "AhPopupMenuItem1"
End Sub
'
' AhPopupMenuItem2
'
Sub AhPopupMenuItem2()
    MsgBox "AhPopupMenuItem2"
End Sub
'
' AhPopupMenuItem3
'
Sub AhPopupMenuItem3()
    MsgBox "AhPopupMenuItem3"
End Sub

Subroutine AhEdit

When the user enters text to the edit controls and presses Enter button, the AhEdit macros is called. The Text property is used to get the text from the edit control.

Here is the macro that handles the 'menu item' events.

'
' AhEdit
'
Sub AhEdit()
Dim ctrl As CommandBarControl
    For Each ctrl In CommandBars(cStrToolbarName).Controls
        If ctrl.OnAction = "AhEdit" Then
            MsgBox "AhEdit = " & ctrl.Text
        End If
    Next ctrl
End Sub

Subroutine AhButton

When the user presses the button, the AhButton macros is called.

Here is the macro that handles the 'button' events.

'
' AhButton
'
Sub AhButton()
    MsgBox "AhButton: Button was pressed"
End Sub
'
' AhButton2
'
Sub AhButton2()
    MsgBox "AhButton2: Button was pressed"
End Sub

Subroutine AhToolBarAddControls

The AhToolBarAddControls macro adds controls to the toolbar. Note that elements are created in the reversed order. This guarantees that the index of the element that was created last is always equal to 1.

'
' AhToolBarAddControls
'
Sub AhToolBarAddControls()
 
    '
    ' combo box
    '
    CommandBars(cStrToolbarName).Controls.Add Type:=msoControlComboBox, Before:=ciInsertIndex
    With CommandBars(cStrToolbarName).Controls.Item(ciInsertIndex)
        .Caption = "CTRL_ComboBox"
        .TooltipText = "CTRL_ComboBox_ToolTip"
        .Width = .Width * 2
        .AddItem "Combo Item 1", 1
        .AddItem "Combo Item 2", 2
        .AddItem "Combo Item 3", 3
        .OnAction = "AhComboBox"
    End With
   
    '
    ' list box
    '
    CommandBars(cStrToolbarName).Controls.Add Type:=msoControlDropdown, Before:=ciInsertIndex
    With CommandBars(cStrToolbarName).Controls.Item(ciInsertIndex)
        .Caption = "CTRL_Dropdown"
        .TooltipText = "CTRL_Dropdown_ToolTip"
        .Width = .Width * 2
        .AddItem "List Item 1", 1
        .AddItem "List Item 2", 2
        .AddItem "List Item 3", 3
        .OnAction = "AhListBox"
    End With
   
    '
    ' popup menu
    '
    CommandBars(cStrToolbarName).Controls.Add Type:=msoControlPopup, Before:=ciInsertIndex
    With CommandBars(cStrToolbarName).Controls.Item(ciInsertIndex)
        .Caption = "Popup Menu"
        .TooltipText = "CTRL_PopupMenu_ToolTip"
        .OnAction = "AhPopup"
        '
        ' adding items to the menu
        '
        With .Controls.Add(Type:=msoControlButton)
            .Caption = "Menu item 1"
            .OnAction = "AhPopupMenuItem1"
            .Style = msoButtonIconAndCaption
            .FaceId = 51
        End With
        With .Controls.Add(Type:=msoControlButton)
            .Caption = "Menu item 2"
            .OnAction = "AhPopupMenuItem2"
            .Style = msoButtonIconAndCaption
            .FaceId = 52
        End With
        With .Controls.Add(Type:=msoControlButton)
            .Caption = "Menu item 3"
            .OnAction = "AhPopupMenuItem3"
            .Style = msoButtonIconAndCaption
            .FaceId = 53
        End With
    End With
   
    '
    ' edit control
    '
    CommandBars(cStrToolbarName).Controls.Add Type:=msoControlEdit, Before:=ciInsertIndex
    With CommandBars(cStrToolbarName).Controls.Item(ciInsertIndex)
        .Caption = "CTRL_Edit"
        .TooltipText = "CTRL_Edit_ToolTip"
        .OnAction = "AhEdit"
        ' .Width = .Width * 2
    End With
    
    '
    ' button
    '
    CommandBars(cStrToolbarName).Controls.Add Type:=msoControlButton, Before:=ciInsertIndex
    With CommandBars(cStrToolbarName).Controls.Item(ciInsertIndex)
        .Caption = "Button"
        .TooltipText = "CTRL_Button_ToolTip"
        .OnAction = "AhButton"
        .Width = .Width * 2
        .Style = msoButtonCaption
    End With
   
    '
    ' button with icon
    '
    CommandBars(cStrToolbarName).Controls.Add Type:=msoControlButton, Before:=ciInsertIndex
    With CommandBars(cStrToolbarName).Controls.Item(ciInsertIndex)
        .Caption = "Button with Icon"
        .TooltipText = "CTRL_Button_with_icon_ToolTip"
        .OnAction = "AhButton2"
        .Width = .Width * 2
        .Style = msoButtonIconAndCaption
        .FaceId = 51

    End With
 
    '
    ' Ah! 11-Nov-2005. These types unfortunately failed in MS Word 2000.
    ' Ah! 18-Jan-2006. These types unfortunately failed in MS Word 2003.
    '
    ' CommandBars(cStrToolbarName).Controls.Add Type:=msoControlGauge
    ' CommandBars(cStrToolbarName).Controls.Add Type:=msoControlButtonDropdown
    ' CommandBars(cStrToolbarName).Controls.Add Type:=msoControlButtonPopup
    ' CommandBars(cStrToolbarName).Controls.Add Type:=msoControlExpandingGrid
    ' CommandBars(cStrToolbarName).Controls.Add Type:=msoControlGraphicCombo
    ' CommandBars(cStrToolbarName).Controls.Add Type:=msoControlGraphicDropdown
    ' CommandBars(cStrToolbarName).Controls.Add Type:=msoControlGrid
    ' CommandBars(cStrToolbarName).Controls.Add Type:=msoControlSplitButtonPopup
   
End Sub

Conclusions

Despite the fact that the built-in Microsoft Word toolbars use all spectrum of the toolbar controls, VBA can create only the following types of controls:

  • button (msoControlButton)
  • popup menu (msoControlPopup)
  • edit control (msoControlEdit)
  • dropdown list (msoControlDropdown)
  • combo box (msoControlComboBox)

The properties and methods of the toolbar controls are investigated in this etude. The macros for creation, removal and using of custom toolbar and its controls are created.

The "AhToolbars.dot" template is created on the basis of specification. It contains macros for working with custom toolbars. The toolbar "AhToolbars" provides a simple interface to the operations of creation and removal of the custom toolbar.

Tasks

Task 1

Create custom menu (msoControlPopup)  with dropdown lists or combo boxes menu items.

 

Task 2

Create dynamic menu which has some set of items ("DOC Action 1", "DOC Action 2" и "DOC Action 3") for documents with ".DOC" extension and another set of items ("RTF Action 1" и "RTF Action 2") for documents with ".RTF" extension. For all other extensions the menu should be empty and disabled. Menu items should be automatically updated when the focus (active document) is changed.

 

 


Etudes for Microsoft Word Programmers. Etude 2.2.


Unless otherwise noted, all materials on this site are
© 2000-2009 Evgeny Akhundzhanov, All Rights Reserved Worldwide
Microsoft is in no way affiliated with, nor offers endorsement of, this site.
www.transcriber.ru | E-mail the Author