Using Visio UIObject Objects to Customize the Visio User Interface | Developing Microsoft Visio Solutions (Pro-Documentation)

3 4

You customize the Microsoft Visio user interface from a program by working with UIObject objects. Just as you get Document objects to work with open documents in a Visio instance, you get objects to work with the menus, toolbars, and accelerators in the Visio user interface.

The following illustration shows the UIObject objects in the Visio object model.

Figure 22-1. <b>UIObject</b> objects in the Visio object model.

Figure 22-1 UIObject objects in the Visio object model.

Many objects in the Visio object model correspond to items you see in a Visio instance. For example, a Menu object can represent the Visio Edit menu, and a MenuItem object can represent the Copy command located on that menu, a custom item that runs a macro or add-on, or an anchor for a hierarchical menu (sometimes called a submenu).

Note

Beginning with Visio 2002, you can no longer customize the status bar in Visio using the StatusBars collection or StatusBar objects of the UIObject object. The StatusBars collection and StatusBar objects are no longer supported in Visio 2002. However, you can still show or hide the status bar using the Application.ShowStatusBar property.

UIObject objects differ from other objects in the Visio object model in that there is no single " UIObject " property that returns a UIObject object. Instead, the properties BuiltInMenus, CustomMenus, BuiltInToolbars, and CustomToolbars each return a UIObject object that represents a different part of the user interface (menus and accelerators in the case of BuiltInMenus or CustomMenus, and toolbars in the case of BuiltInToolbars or CustomToolbars).

To modify a copy of the built-in Visio user interface, use the BuiltInMenus or BuiltInToolbars property of the Application object to obtain a UIObject object. For example, to modify a copy of the built-in Visio menus and obtain a UIObject object that represents Visio menus and accelerators, start with this code:

 Dim uiObj As Visio.UIObject Set uiObj = Visio.Application.BuiltInMenus

To get a UIObject object that represents a copy of the built-in Visio toolbars, use this code:

 Dim uiObj As Visio.UIObject Set uiObj = Visio.Application.BuiltInToolbars(0)

To modify a custom user interface, use the CustomMenus or CustomToolbars property of the Application object or of any Document object to obtain a reference to the appropriate UIObject object. You should also use these properties to determine whether a custom user interface is in effect first.

For example, to get a UIObject object that represents the custom toolbars for the Application object:

 Dim uiObj As Visio.UIObject Set uiObj = Application.CustomToolbars 'Returns Nothing if the application has no custom toolbars.

To get a UIObject object that represents the custom menus for a Document object:

 Dim uiObj As Visio.UIObject Set uiObj = ThisDocument.CustomMenus 'Returns Nothing if document has no custom menus

A UIObject object that represents menus (whether built-in or custom) has two properties that return collections: MenuSets and AccelTables. A UIObject object that represents toolbars (again, whether built-in or custom) has a ToolbarSets property that returns a collection.

Note

Unlike most other Visio object collections, collections that represent UIObject objects are indexed starting with zero (0). Specify an index of 0 with the collection's Item property to get the first item in any of the following collections: AccelTables, AccelItems, MenuSets, Menus, MenuItems, ToolbarSets, Toolbars, or ToolbarItems.

The UIObject branch of the Visio object model is fairly elaborate, so it's important to understand the various objects and their relationships to each other before attempting to customize them. The following topics in this section describe the hierarchy of objects that represent Visio menus, accelerators, and toolbars.

About Menu Objects

Different window contexts display different sets of menus, such as a drawing window, ShapeSheet window, or stencil window. For example, different menu items are displayed when a drawing window is active than when a stencil window is active. The following table lists the menu objects in the Visio object model.

Menu objects in the Visio object model

Object	Description
MenuSets	The collection of all possible Visio menu sets. To get a MenuSets collection, get the MenuSets property of a UIObject object that represents menus and accelerators.
MenuSet	The set of menus available in a given window context. For example, a MenuSet object could represent the set of menus available when a drawing window is active. To get a MenuSet object, use the ItemAtID property of a MenuSets collection and specify the ID of the context you want. For a table of contexts and other identifiers that can be used with ItemAtID, see the Microsoft Visio Developer Reference (on the Help menu, click Developer Reference). All MenuSet objects correspond to a given window context except for a MenuSet object that represents a shortcut menu (the menu that appears when you right-click something such as a shape, page, or stencil window, sometimes called a right-click menu or context-sensitive menu).

Object

Description

MenuSets

The collection of all possible Visio menu sets. To get a MenuSets collection, get the MenuSets property of a UIObject object that represents menus and accelerators.

MenuSet

The set of menus available in a given window context. For example, a MenuSet object could represent the set of menus available when a drawing window is active. To get a MenuSet object, use the ItemAtID property of a MenuSets collection and specify the ID of the context you want. For a table of contexts and other identifiers that can be used with ItemAtID, see the Microsoft Visio Developer Reference (on the Help menu, click Developer Reference).

All MenuSet objects correspond to a given window context except for a MenuSet object that represents a shortcut menu (the menu that appears when you right-click something such as a shape, page, or stencil window, sometimes called a right-click menu or context-sensitive menu).

Note

Beginning with Visio 2000, the Position property of a MenuSet object specifies whether the menu bar it represents is docked (left, right, top, or bottom) on floating. The RowIndex property specifies where the menu bar appears relative to other bars displayed in the Visio window. For details about these properties, search for them by name in the Microsoft Visio Developer Reference (on the Help menu, click Developer Reference).

Menus	A collection of menus in a menu set. For example, the items in a Menus collection might represent the File, Edit, and Tools menus. To get a Menus collection, get the Menus property of a MenuSet object.
Menu	A menu. For example, the items in a Menu object that represents a File menu might be Open, Close, and Edit. To get a Menu object, use the Item property of a Menus collection with the index of the menu you want. Menus are indexed in the order they appear: from left to right or from top to bottom in a Visio instance. For example, in most window contexts, the File menu has an index of zero (0). To add a Menu object, use the Add or AddAt method of a Menus collection.
MenuItems	A collection of menu items on a Visio menu. To get a MenuItems collection, get the MenuItems property of a Menu object.
MenuItem	A menu item, or command, on a Visio menu. To get a MenuItem object, use the Item property of the MenuItems collection with the index of the menu item you want. Menu items are indexed in the order they appear: from top to bottom on the menu. For example, the Undo command on the Visio Edit menu has an index of zero (0). To add a MenuItem object, use the Add or AddAt method of the MenuItems collection. The CmdNum property of a MenuItem object specifies a valid command ID, as declared in the Visio type library, or 0 if the item is a separator in a menu. If the menu item runs a program, its AddonName property specifies the name of a macro or program to run when the user chooses the menu item; its AddonArgs property specifies arguments to pass. If a Visio menu item has a hierarchical menu, then the MenuItem object that represents the hierarchical menu has a MenuItems collection with MenuItem objects. The CmdNum property of such a MenuItem object should be set to visCmdHierarchical, and the remaining properties and methods that can be used are: Caption, Index, MenuItems, Parent, and Delete. All other properties and methods will be ignored.

Beginning with Visio 2000, both Menu and MenuItem objects have the following method and properties:

IconFileName method which specifies a custom icon file to be displayed for an item
FaceID property which specifies an icon to be displayed with the item on the menu
Style property which specifies whether to display the icon and text or text only
State property which specifies whether the item appears "pressed" (if it has an icon) or checked (if it has only text)
Enabled property that specifies whether the command is dimmed

For details about this method and these properties, search for them by name in the Microsoft Visio Developer Reference (on the Help menu, click Developer Reference).

About Accelerator Objects

An accelerator is a combination of keys that, when pressed, execute a command. For example, the accelerator for the Copy menu item is CTRL+C, and the accelerator for the Paste menu item is CTRL+V. The following table lists the accelerator objects in the Visio object model.

Accelerator objects in the Visio object model

Object	Description
AccelTables	The collection of all Visio accelerator tables. Different accelerators are used in different window contexts. To get an AccelTables collection, get the AccelTables property of a UIObject object.
AccelTable	The table of accelerators available for a given window context. The AccelTable objects exist only for window contexts, such as the drawing window, not for shortcut menus. To get an AccelTable object, use the ItemAtID property of an AccelTables collection and specify the ID of the context you want.
AccelItems	A collection of accelerators in an accelerator table. To get an AccelItems collection, get the AccelItems property of an AccelTable object.
AccelItem	A single accelerator item. Accelerator items, such as CTRL+C (Copy) and CTRL+V (Paste), are available when a drawing window is active. To get an AccelItem object, use the Item property of an AccelItems collection with the index of the menu you want.

Note

Beginning with Visio 2000, the AccelItem object now has AddonName and AddonArgs properties. This means you can bind a Microsoft Visual Basic for Applications (VBA) macro or add-on to an accelerator. In earlier versions of Visio, only built-in commands could be bound to accelerators.

About Toolbar Objects

Different sets of toolbars are displayed in different window contexts. For example, when a ShapeSheet window is active, different toolbars are displayed than when a drawing window is active. The following table lists the toolbar objects in the Visio object model.

Tip

Beginning with Visio 2000, you can attach a custom toolbar to a Visio document by using the Attach button on the Toolbars tab in the Customize dialog box (on the Tools menu, click Customize). For more about creating and attaching toolbars, see the Microsoft Visio Help.

Toolbar objects in the Visio object model

Object	Description
ToolbarSets	The collection of all possible Visio toolbar sets. To get a ToolbarSets collection, get the ToolbarSets property of a UIObject object that represents toolbars. Use the Application object's ShowToolbar property to control whether Visio toolbars are visible.
ToolbarSet	The set of toolbars available in a given window context. For example, a ToolbarSet object could represent the set of toolbars available when a ShapeSheet window is active. To get a ToolbarSet object, use the ItemAtID property of a ToolbarSets collection and specify the ID of the context you want.
Toolbars	A collection of Visio toolbars in a toolbar set. To get a Toolbars collection, get the Toolbars property of a ToolbarSet object.
Toolbar	A Visio toolbar. To get a Toolbar object, use the Item property of a Toolbars collection with the index of the toolbar you want. Built-intoolbars are indexed by the order in which they would initially be docked in the Visio window if all built-in toolbars were visible. Custom toolbars are indexed in the order they are added to the collection. To add a toolbar, use the Add or AddAt method of a Toolbars collection. The Caption property of the Toolbar object represents the caption that appears on the hierarchical menu for the Toolbars menu item (View menu), or when the toolbar is floating.

Note

Beginning with Visio 2000, the Position property of a Toolbar object specifies whether the toolbar it represents is docked (left, right, top, or bottom) or floating. The RowIndex property specifies where the toolbar appears relative to others displayed in the Visio window. For details about these properties, search for them by name in the Microsoft Visio Developer Reference (on the Help menu, click Developer Reference).

ToolbarItems	A collection of toolbar items in a Visio toolbar. To get a ToolbarItems collection, get the ToolbarItems property of a Toolbar object.
ToolbarItem	A control on a Visio toolbar. To get a ToolbarItem object, use the Item property of the ToolbarItems collection with the index of the toolbar item you want. Toolbar items are indexed in the order that they appear on the toolbar (left to right, or top to bottom, starting with index 0). To add a toolbar item, use the Add or AddAt method of a ToolbarItems collection.

Note

In Visio 2000, ToolbarItem objects have a Style property that specifies whether to display the icon and text or text only. ToolbarItem objects also have a State property that specifies whether the item appears "pushed" (if it has an icon) or checked (if it has only text). For details about these properties, search for them by name in the Microsoft Visio Developer Reference.

Planning User Interface Changes

As you begin designing your custom user interface, you need to answer the following questions:

Will you be customizing a copy of the built-in Microsoft Visio user interface or an existing custom user interface? This determines how you obtain a UIObject object, change it, and how you restore the original interface when your solution finishes running.
Should the custom user interface be available only for certain Visio documents, or for all documents in a Visio instance? This determines its scope, the context in which your custom user interface is available.
Should the custom user interface be available only when a document is active, throughout a single Visio instance, or each time a user starts Visio? This determines its persistence, the length of time in which your custom user interface is available.

Customizing a copy of the built-in Visio UI versus an existing custom UI

Before you customize a Visio user interface, first determine whether the current user interface is the built-in Visio user interface or a custom user interface. If it's a custom user interface, good software design suggests that you should modify the existing interface for your solution and then restore it to its original condition, rather than starting from scratch with the built-in Visio user interface.

When you retrieve the built-in Visio menus or toolbars, you are actually retrieving a copy, or a snapshot, of the built-in Visio user interface that you can manipulate. The original built-in Visio user interface remains untouched, so you can restore it later. When you retrieve a custom user interface, you are retrieving the custom user interface that is currently active (including any custom toolbars the user might have added), not a copy.

To determine which user interface is in use, check the CustomMenus and CustomToolbars properties of all the Document objects in the Documents collection. Then check the same properties of the Application object. If an object is not using a custom user interface, both properties return Nothing, and you can simply retrieve a copy of the built-in Visio user interface.

If a custom user interface is already in use, you should decide whether you want to replace the custom user interface with your own, or just add your custom user interface items to it. If the custom user interface is attached to the document, you will probably want to apply changes to it directly. However, if the custom user interface is at the application level, you should use the Clone method to create a copy of that user interface, and apply your changes to the copy instead. Otherwise, those changes will still be visible after the user has closed the document.

The following example demonstrates how to retrieve the currently active user interface for your document without replacing the application-level custom user interface, if any. You would write additional code to add your custom user interface items.

 'Check if there are document custom menus. If ThisDocument.CustomMenus Is Nothing Then       'Check if there are Visio custom menus.       If Visio.Application.CustomMenus Is Nothing Then             'Use the built-in menus.             Set visUIObj = Visio.Application.BuiltInMenus       Else             'Use the Visio custom menus.             Set visUIObj = Visio.Application.CustomMenus.Clone       End If Else       'Use the file custom menus       Set visUIObj = ThisDocument.CustomMenus End If

For details about the CustomMenus and CustomToolbars properties, see the Microsoft Visio Developer Reference (on the Help menu, click Developer Reference).

Controlling the scope of your UI

Just as you can get a UIObject object from the Document or Application object, you can also apply your custom user interface changes to the Document or Application object by using its SetCustomMenus or SetCustomToolbars method. The scope you want determines the object to which you apply your changes. You can choose to make your custom user interface available on an application or document level. To use a custom user interface regardless of which document is open, apply your custom user interface to the Application object.

To use a custom user interface on a document level, that is, while a document is active, apply your custom user interface to a Document object. This is the way you'll typically work when programming in Microsoft Visual Basic for Applications (VBA).

The following example shows how to set custom menus for the ThisDocument object:

 Dim uiObj as Visio.UIObject 'Get a copy of the built-in Visio menus. Set uiObj = Visio.Application.BuiltInMenus ... 'Make custom UI changes. 'Set custom menus for ThisDocument. ThisDocument.SetCustomMenus uiObj

Controlling the persistence of your UI

The approach you use to customize the Visio user interface depends on the extent of the changes you intend to make and the development environment in which you are programming. Depending on the scope of your user interface changes, you might want your changes to persist while a document is active, throughout a single Visio instance, or each time the user starts Visio.

UI persistence while a document is active
A document can have a custom user interface that takes precedence over the Visio user interface (custom or built-in) while the document is active. For example, when a user creates a document from a particular template, you can add a toolbar button that runs a wizard to help the user create a drawing. As soon as the user closes the document, the Visio instance reverts to the previous user interface.

When you are customizing the Visio user interface from VBA, you usually work on a document level; therefore, you can set the custom user interface for the ThisDocument object.
UI persistence during a single Visio instance
If you want your custom user interface to persist during a single Visio instance, set the custom user interface for the Application object from a VBA macro or stand-alone program.
UI persistence each time the user starts Visio
If you want your user interface changes to replace the Visio user interface on a more permanent basis, you can set the custom user interface for the Application object each time a user starts Visio, or create a custom user interface file.

After you create a custom user interface file, you apply it to the user interface by setting the CustomMenusFile or CustomToolbarsFile property for the Application object. Your custom user interface file loads each time the user starts Visio, until you specify a different file or restore the built-in Visio user interface. For details, see Putting custom UI changes into effect later in this chapter.

Making User Interface Changes

After you decide which UIObject object you want to work with and the scope and persistence of your custom user interface, you can begin to make the interface changes. To get to the item that you want to remove or to get to the location where you want to add an item, you must navigate the Microsoft Visio object model. To do this, first get a UIObject object; then a menu, accelerator, or toolbar; and then the specific items that you want to change. After you make your user interface changes, you must apply the customized UIObject object somewhere so that your user interface takes effect.

Getting a MenuSet, ToolbarSet, or AccelTable object

To get a MenuSet, ToolbarSet, or AccelTable object, use the ItemAtID property of the appropriate collection and specify the ID of the object you want. For a list of constants you can use with the ItemAtID property, see the Microsoft Visio Developer Reference (on the Help menu, click Developer Referenc e).

For example, the following code fragment uses the constant visUIObjSetDrawing to get a MenuSet object that represents the drawing window menus:

 Dim uiObj As Visio.UIObject Dim menuSetObj As Visio.MenuSet 'Get a UIObject object that represents a copy of the built-in Visio menus. Set uiObj = Visio.Application.BuiltInMenus 'Get the drawing window menu set. Set menuSetObj = _       uiObj.MenuSets.ItemAtId(visUIObjSetDrawing)

The following example uses the constant visUIObjSetShapeSheet to get a ToolbarSet object that represents the ShapeSheet window toolbars:

 Dim uiObj As Visio.UIObject Dim toolbarSetObj As Visio.ToolbarSet 'Get a UIObject object that represents a copy of the built-in  'Visio toolbars. Set uiObj = Visio.Application.BuiltInToolbars(0) 'Get the ShapeSheet window toolbar set. Set toolbarSetObj = _       uiObj.ToolbarSets.ItemAtID(visUIObjSetShapeSheet)

ID constants for window contexts

Constants that you can specify with the ItemAtID property for the most commonly used window contexts are listed in the following table and defined in the Visio type library. For lists of ID constants that represent shortcut menus, palettes, and pop-up windows available for MenuSet, ToolbarSet, and AccelTable objects, see the SetID property in the Microsoft Visio Developer Reference (on the Help menu, click Developer Reference).

ID constants that represent window contexts for the MenuSet, ToolbarSet and AccelTable object

zapf_circle.gif	MenuSet object
zapf_triangle.gif	ToolbarSet object
zapf_square.gif	AccelTable object

ID constant	Context
visUIObjSetDrawing	Drawing window
visUIObjSetStencil	Stencil window
visUIObjSetShapeSheet	ShapeSheet window
visUIObjSetPrintPreview	Print preview window

Adding a menu and a menu item

After getting a UIObject object, you can add or remove items from the user interface. To add items, navigate the UIObject branch in the Visio object model to get the collection that contains the kind of item you want to add, and use that collection's Add or AddAt method.

The following example adds a new menu and menu item that are available when the Visio drawing window is active:

 Dim uiObj As Visio.UIObject Dim menuSetsObj As Visio.MenuSets Dim menuSetObj As Visio.MenuSet Dim menusObj As Visio.Menus Dim menuObj As Visio.Menu Dim menuItemsObj As Visio.MenuItems Dim menuItemObj As Visio.MenuItem 'Get a UIObject object that represents a copy of the built-in  'Visio menus. Set uiObj = Visio.Application.BuiltInMenus 'Get the MenuSets collection. Set menuSetsObj = uiObj.MenuSets 'Get drawing window MenuSet object; get the context. Set menuSetObj= menuSetsObj.ItemAtId(visUIObjSetDrawing) 'Get the Menus collection. Set menusObj = menuSetObj.Menus 'Add a Demo menu before the Window menu. 'A menu without a menu item will not appear. Set menuObj = menusObj.AddAt(7) menuObj.Caption = "Demo"

The first half of this example assumes the Window menu is still in its initial position—eighth from the left on the menu bar. Adding or removing menus can change the position of other menus, however.

The second half of the example, shown below, adds a menu item to the Demo menu and sets the menu item's properties. For details, see Setting properties of an item later in this section.

The following sample code uses the Add method to add one item to the Demo menu that was added in the preceding sample code. When you add an item using the Add method, the item is added to the end of a collection. This example adds only one menu item, so its position is not an issue. However, if you were to add another item using the Add method, it would appear at the bottom of the menu. To control where a menu item appears, use the AddAt method and specify the ordinal position of the item.

Note

You can assign a keyboard shortcut to a menu item by preceding the intended shortcut character with an ampersand (&).

 'Get the MenuItems collection. Set menuItemsObj = menuObj.MenuItems 'Add a MenuItem object to the new Demo menu. Set menuItemObj = menuItemsObj.Add 'Set the properties for the new menu item. menuItemObj.Caption = "Run &Demo Program" menuItemObj.AddonName = "Demo.EXE" menuItemObj.AddonArgs = "/DVS=Fun" 'Tell Visio to use the new UIObject object (custom menus) 'while the document is active. ThisDocument.SetCustomMenus uiObj

The last statement, ThisDocument.SetCustomMenus uiObj tells the Visio instance to use the custom menus while the document is active. The custom user interface changes don't persist after the user closes the document.

Adding a toolbar and a toolbar button

You can add a custom toolbar button to one of the built-in toolbars or create an entire custom toolbar. The following procedure demonstrates how to add a toolbar button to a copy of the built-in toolbars for the drawing window context:

 Sub AddToolbarButton( )       'Object variables to be used in the program       Dim uiObj As Visio.UIObject       Dim toolbarSetObj As Visio.ToolbarSet       Dim toolbarItemsObj As Visio.ToolbarItems       Dim objNewToolbarItem As Visio.ToolbarItem       'Get the UIObject object for the toolbars.       Set uiObj = Visio.Application.BuiltInToolbars(0)       'Get the drawing window ToolbarSet object.       Set toolbarSetObj = _             uiObj.ToolbarSets.ItemAtID(visUIObjSetDrawing)       'Get the ToolbarItems collection.       Set toolbarItemsObj = toolbarSetObj.Toolbars(0).ToolbarItems       'Add a new button in the first position.       Set objNewToolbarItem = toolbarItemsObj.AddAt(0)       'Set the properties for the new toolbar button.       objNewToolbarItem.ActionText = "Run Stencil Report Wizard"       objNewToolbarItem.AddonName = "Stndoc.exe"       objNewToolbarItem.CntrlType = visCtrlTypeBUTTON       'Set the icon for the new toolbar button.       objNewToolbarItem.IconFileName "dvs.ico"       'Tell Visio to use the new custom toolbars while the        'document is active.       ThisDocument.SetCustomToolbars uiObj End Sub

Here are some notes about the example:

Set toolbarItemsObj = toolbarSetObj.Toolbars(0).ToolbarItems. Built-in toolbars generally appear in the same order in the collection. In the case of the toolbar set for the drawing window context, the Standard toolbar is at index 0, and the Format toolbar is at index 1. The order in which toolbars appear in the collection does not always correspond to the order in which they appear on the screen, which can be changed by the user or by solutions that use the RowIndex property.

Set objNewToolbarItem = toolbarItemsObj.AddAt(0). Visio orders toolbar items horizontally, so this statement adds the ToolbarItem or button at the leftmost location on the toolbar if the toolbar is docked horizontally; this statement adds the ToolbarItem or button at the topmost location if the toolbar is docked vertically.

objNewToolbarItem.CntrlType = visCtrlTypeBUTTON sets the type of toolbar button to display. Visio includes other constants for built-in Visio toolbar buttons, but custom toolbar buttons can use only visCtrlTypeBUTTON, visCtrlTypeSPLITBUTTON, or visCtrlTypeSPLITBUTTON_MRU_COMMAND.

Note

The Microsoft Office command bars object model supports the creation of custom text boxes, combo boxes, and drop-down list boxes. For details, see Using CommandBar Objects to Customize the Visio User Interface earlier in this chapter.

objNewToolbarItem.IconFileName "dvs.ico" gets the file "dvs.ico" that contains the bitmap for the toolbar to display. Because no path to this file was given, Visio will search for it in folders along the user's Add -ons path, as specified on the File Paths tab of the Options dialog (on the Tools menu, click Options). Alternatively, you can specify a full path and file name to the icon file. It is also possible to use the IconFileName method to extract icon images from executable files. The icon file should contain a 16-by-16-pixel icon.

For details on the IconFileName method, see the Microsoft Visio Developer Reference (on the Help menu, click Developer Reference).

ThisDocument.SetCustomToolbars uiObj uses the custom toolbars while the document is active.

The following procedure demonstrates how to add a floating toolbar named "Test"; this floating toolbar cannot be docked but can be hidden in the drawing window context. The program first checks whether the Visio document or instance is using custom toolbars and assigns a UIObject object to the uiObj variable. The program then gets the Toolbars collection for the drawing window context, adds the new toolbar, and sets its properties.

 Sub AddToolbar()       Dim uiObj As UIObject       Dim toolbarsObj As Toolbars       Dim toolbarObj As Toolbar       Dim toolbarItemsObj As ToolbarItems       Dim toolbarItemObj As ToolbarItem              'Check if the document has custom toolbars.       If ThisDocument.CustomToolbars Is Nothing Then             'Check if the instance is using custom toolbars.             If Visio.Application.CustomToolbars Is Nothing Then                   'Use the built-in toolbars.                   Set uiObj = Visio.Application.BuiltInToolbars(0)             Else                   'Use the application's custom toolbars.                   Set uiObj = Visio.Application.CustomToolbars.Clone             End If       Else             'Use the document's custom toolbars.             Set uiObj = ThisDocument.CustomToolbars       End If              'Get the Toolbars collection for the drawing window context.       Set toolbarsObj = uiObj.ToolbarSets.ItemAtID( _             Visio.visUIObjSetDrawing).Toolbars              'Add a toolbar.       Set toolbarObj = toolbarsObj.Add              With toolbarObj             'Set the toolbar's title.             .Caption = "Test"             'Position the toolbar floating at the              'coordinates 300, 200.             .Position = Visio.visBarFloating             .Left = 300             .Top = 200             'Disallow docking.             .Protection = Visio.visBarNoHorizontalDock _                   + Visio.visBarNoVerticalDock             'Make the new toolbar visible.             .Visible = True             'Allow the user to hide and show the toolbar.             .Enabled = True       End With End Sub

Setting properties of an item

After you've added an item, you can set properties that define its behavior and appearance. For example, you can set the Caption property of a menu item to define the text that appears on the menu, or use the FaceID property or IconFileName method of a toolbar or menu item to specify what icon to display.

Two significant properties of a menu item or toolbar item are CmdNum, which specifies the ID of the command associated with the item, and AddonName, which specifies a program or macro to run when the user chooses the menu item or clicks the button. If the program takes command line arguments, they can be specified with the AddonArgs property. For details about the properties and methods of a particular item, search for that item in the Microsoft Visio Developer Reference (on the Help menu, click Developer Reference).

Caption specifies the text that appears on a menu or menu item. If you want to display the accelerator with the menu item, include it as part of the Caption property's text and insert two spaces between the "\a" and the accelerator text. For example:

 "Open...\a  CTRL+O"

In this example, "Open..." is the menu item's caption; "CTRL+O" is the accelerator text; and "\a" left justifies the accelerator text. Adding the accelerator text to the Caption property doesn't add an accelerator, it simply displays it as part of the caption. You add accelerators by using the accelerator objects in the Visio object model.

You can also specify other properties, such as those in the following example:

 menuItemObj.ActionText = "Run Demo 1" 'BACKSPACE key accelItemObj.Key = 8 accelItemObj.Alt = True

ActionText specifies the text that appears on the Edit menu with Undo, Redo, and Repeat for a menu item. It also appears in any error messages or toolbar tool tips that might be displayed.

Key specifies the ASCII key code value for an accelerator. For example, the ASCII key code for the BACKSPACE key is 8, and the ASCII key code for the ESC key is 27. For details about ASCII key codes, see the Microsoft Platform Software Development Kit (SDK) in the MSDN Library. The Alt, Control, and Shift properties modify the Key for an accelerator. To set the properties for an accelerator, set any combination of modifiers to True, specify one key code, and set the item's CmdNum or AddonName property. To activate an accelerator command, press the combination of modifiers and the key that corresponds to the key code.

The CmdNum property specifies the command ID for an item. Every built-in Visio menu item and toolbar item represents a Visio command and has a command ID. For example, the command ID for Show ShapeSheet is visCmdWindowShowShapeSheet ; the command ID for Document Stencil is visCmdWindowShowMasterObjects. For a list of valid command IDs, search for "visCmd" in the Visio type library in the Object Browser in the Visual Basic Editor.

Tip

If you want to hide the Visio user interface but not the Visio window, set the ShowToolbar or ShowStatusBar properties of the Application object to False to hide all toolbars or hide the status bar, respectively.

Removing items from a user interface

You can remove any item from the Visio user interface, whether the item is part of the built-in Visio user interface or a custom item you added. (As an alternative, if you want to make a toolbar or menu item temporarily unavailable, set its Enabled property to False ; this dims the item.)

Removing an item doesn't remove the functionality of that item, just the access to that functionality. Other avenues, such as accelerators, may still be available. For example, if you remove the Copy command from the Edit menu, but not the accelerator (CTRL+C), a user can still use the copy functionality by pressing CTRL+C. You can remove the Show ShapeSheet command from the Window menu, but if the double-click behavior for a shape is to display the ShapeSheet window, that window still appears when that shape is double-clicked.

Tip

Every built-in Visio menu item and toolbar item represents a Visio command and has a command ID. If you want to remove one of these Visio items, you can identify it by its command ID. However, the CmdNum property of a custom menu item or toolbar item that runs a program or macro does not correspond to any Visio command ID, so when you want to delete the item, you cannot identify the item using its command ID. Instead, use the Caption property string of a custom menu or toolbar item to locate the item.

To remove an item, use the Delete method of that item. For example, the following statements remove the Show ShapeSheet menu item from the Window menu in the drawing window for the running Visio instance:

 Dim uiObj As Visio.UIObject Dim menuSetObj As Visio.MenuSet Dim menuItemsObj As Visio.MenuItems Dim i As Integer Set uiObj = Visio.Application.BuiltInMenus Set menuSetObj = _       uiObj.MenuSets.ItemAtID(visUIObjSetDrawing) 'Get the Window menu. Set menuItemsObj = menuSetObj.Menus(7).MenuItems 'Get the Show ShapeSheet menu item by its CmdNum property. 'This technique works with localized versions of Visio. For i = 0 To menuItemsObj.Count -1       If menuItemsObj(i).CmdNum = _             visCmdWindowShowShapeSheet Then             menuItemsObj(i).Delete             Exit For       End If Next i 'Replace built-in Visio menus with customized set. Visio.Application.SetCustomMenus uiObj

Removing a toolbar item

The following macro shows how to delete the Spelling toolbar button from the built-in Standard toolbar for the drawing window context:

 Sub DeleteToolbarButton( )       Dim uiObj As Visio.UIObject       Dim toolbarSetObj As Visio.ToolbarSet       Dim toolbarItemsObj As Visio.ToolbarItems       Dim toolbarItemObj As Visio.ToolbarItem       'Loop variable       Dim i As Integer       'Get the UIObject object for the toolbars.       Set uiObj = Visio.Application.BuiltInToolbars(0)       'Get the drawing window ToolbarSet object.       Set toolbarSetObj = _       uiObj.ToolbarSets.ItemAtID(visUIObjSetDrawing)       'Get the ToolbarItems collection.       Set toolbarItemsObj = toolbarSetObj.Toolbars(0).ToolbarItems       'Get the Spelling ToolbarItem object.       'Because this code gets the built-in Visio toolbars, you know        'you'll find the Spelling toolbar item; if code got a custom        'toolbar, it might not include the Spelling toolbar        'item.       For i = 0 To toolbarItemsObj.Count - 1             'Get the current ToolbarItem object from the collection.             Set toolbarItemObj = toolbarItemsObj(i)             'Check whether the current toolbar item is the              'Spelling button.              If toolbarItemObj.CmdNum = visCmdToolsSpelling Then                   Exit For             End If       Next i       'Delete the Spelling button.       toolbarItemObj.Delete       'Tell Visio to use the new custom toolbars while the        'document is active.       ThisDocument.SetCustomToolbars uiObj End Sub

Removing an accelerator

The following macro shows how to delete the accelerator for the Visual Basic Editor from the drawing window context.

 Sub DeleteAccelItem( )       Dim uiObj As Visio.UIObject       Dim accelTableObj As Visio.AccelTable       Dim accelItemsObj As Visio.AccelItems       Dim accelItemObj As Visio.AccelItem       Dim i As Integer       'Retrieve the UIObject object for the copy of the built-in menus.       Set uiObj = Visio.Application.BuiltInMenus       'Set accelTableObj to the Drawing menu set.       Set accelTableObj = _       uiObj.AccelTables.ItemAtID(visUIObjSetDrawing)       'Retrieve the accelerator items collection.       Set accelItemsObj = accelTableObj.AccelItems       'Retrieve the accelerator item for the Visual Basic Editor by        'iterating through the accelerator items collection and        'locating the item you want to delete.       For i = 0 To accelItemsObj.Count - 1             Set accelItemObj = accelItemsObj.Item(i)             If accelItemObj.CmdNum = Visio.visCmdToolsRunVBE Then                   Exit For             End If       Next i       'Delete the accelerator.       accelItemObj.Delete       'Tell Visio to use the new custom menus while the        'document is active.       ThisDocument.SetCustomMenus uiObj End Sub

Putting custom UI changes into effect

The final step in the process of customizing the Visio user interface is to set the custom user interface for an object, which applies your user interface to the Visio instance. The modifications your program makes to a UIObject object appear in the Visio instance after this step. To put custom user interface changes into effect, use the SetCustomMenus or SetCustomToolbars methods of the Document or Application object and specify the UIObject object that represents your custom user interface.

For example, the following statement sets custom menus for a document:

 ThisDocument.SetCustomMenus uiObj

To set custom toolbars for all documents in a single Visio instance, use this statement:

 Visio.Application.SetCustomToolbars uiObj

If you directly change a UIObject object that represents the active custom toolbars or custom menus while a Visio instance is running, you must call the UpdateUI method of that UIObject object to make Visio display your changes.

For example:

 'Get the UIObject object for the custom menus. Set uiObj = Visio.Application.CustomMenus ...'Code changes to the custom interface. 'Update the custom interface with changes. uiObj.UpdateUI