com.esri.arcgis.framework
Interface ICommandBars

All Superinterfaces:
Serializable
All Known Implementing Classes:
CommandBars, ICommandBarsProxy

public interface ICommandBars
extends Serializable

Provides access to members that work on the collection of commandbars.

Remarks

Note, all programmatic customizations are temporary. If you execute VBA code to create a new commandbar, these changes are temporary. If you programmatically customize ArcMap, these changes will only appear while the current document is open in the current ArcMap session. Programmatic changes are never saved in the document or templates. Once you close that document or shutdown ArcMap, the changes are removed. If you are customizing ArcCatalog, these changes will only appear during the current ArcCatalog session.

When To Use

CommandBars is a collection of all the toolbars available to a document. The ICommandBars interface allows you to set properties for all the commandbars and to create, find, or hide commandbars. Use IDocument::CommandBars to get a reference to the commandbars collection.

Product Availability

Available with ArcGIS Desktop.

See Also:
IDocument.getCommandBars()

Method Summary
 ICommandBar create(String name, int barType)
          Creates a new blank toolbar or shortcut menu.
 ICommandItem find(Object identifier, boolean noRecurse, boolean noCreate)
          Searches for the item specified by identifier.
 void hideAllToolbars()
          Hides all visible bars.
 boolean isLargeIcons()
          Indicates if large icons should be shown.
 boolean isShowToolTips()
          Indicates if tooltips should be shown.
 void setLargeIcons(boolean bLarge)
          Indicates if large icons should be shown.
 void setShowToolTips(boolean bShow)
          Indicates if tooltips should be shown.
 

Method Detail

setShowToolTips

void setShowToolTips(boolean bShow)
                     throws IOException,
                            AutomationException
Indicates if tooltips should be shown.

Remarks

Use this setting to specify whether ToolTips will appear on all the toolbars in the ArcGIS applications when you pause the mouse over a button on a command bar.

This is the same setting as the 'Show ToolTips on toolbars' check box on the Options tab of the Customize dailog box in the ArcGIS applications.

Product Availability

Available with ArcGIS Desktop.

Supported Platforms

Windows

Parameters:
bShow - The bShow (in)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

isShowToolTips

boolean isShowToolTips()
                       throws IOException,
                              AutomationException
Indicates if tooltips should be shown.

Remarks

Use this setting to specify whether ToolTips will appear on all the toolbars in the ArcGIS applications when you pause the mouse over a button on a command bar.

This is the same setting as the 'Show ToolTips on toolbars' check box on the Options tab of the Customize dailog box in the ArcGIS applications.

Product Availability

Available with ArcGIS Desktop.

Supported Platforms

Windows

Returns:
The bShow
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

setLargeIcons

void setLargeIcons(boolean bLarge)
                   throws IOException,
                          AutomationException
Indicates if large icons should be shown.

Remarks

Use the LargeIcons property to specify the size of icons displayed on the buttons on all the command bars in the application. Use True if you want large icons or use False for normal size icons.

This is the same setting as the Large Icons check box on the Options tab of the Customize dailog box in the ArcGIS applications.

Product Availability

Available with ArcGIS Desktop.

Supported Platforms

Windows

Parameters:
bLarge - The bLarge (in)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

isLargeIcons

boolean isLargeIcons()
                     throws IOException,
                            AutomationException
Indicates if large icons should be shown.

Remarks

Use the LargeIcons property to specify the size of icons displayed on the buttons on all the command bars in the application. Use True if you want large icons or use False for normal size icons.

This is the same setting as the Large Icons check box on the Options tab of the Customize dailog box in the ArcGIS applications.

Product Availability

Available with ArcGIS Desktop.

Supported Platforms

Windows

Returns:
The bLarge
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

create

ICommandBar create(String name,
                   int barType)
                   throws IOException,
                          AutomationException
Creates a new blank toolbar or shortcut menu.

Description

Name is a string representing the name of the new toolbar or shortcut menu.

barType specifies which type of commandbar to create. Use one of the esriCmdBarType constants.

Remarks

The Create method creates a new VBA command bar in a visible, floating state.

To create new menu in VBA, use the ICommandBar CreateMenu method instead of the ICommandBars Create method.

If you want to create a new command bar in a development environment other than VBA, you should implement either IToolBarDef or IMenuDef instead of using the ICommandBars Create method.

Note, all programmatic customizations are temporary. If you execute VBA code to create a new commandbar, these changes are temporary. If you programmatically customize ArcMap, these changes will only appear while the current document is open in the current ArcMap session. Programmatic changes are never saved in the document or templates. Once you close that document or shutdown ArcMap, the changes are removed. If you are customizing ArcCatalog, these changes will only appear during the current ArcCatalog session.

The following example shows how to use the ICommandBars::Create method to create a new toolbar in Arcmap and add some items to it using the CommandBar::Add method. You would get m_app from the hook in ICommand::OnCreate().

Product Availability

Available with ArcGIS Desktop.

Supported Platforms

Windows

Parameters:
name - The name (in)
barType - A com.esri.arcgis.systemUI.esriCmdBarType constant (in)
Returns:
A reference to a com.esri.arcgis.framework.ICommandBar
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
See Also:
ICommandBar, esriCmdBarType

find

ICommandItem find(Object identifier,
                  boolean noRecurse,
                  boolean noCreate)
                  throws IOException,
                         AutomationException
Searches for the item specified by identifier.

Description

identifier is the unique identifier of the item you want to find. For built-in commands and commandbars, use the UID. For VBA commandbars, macros and UIControls use the name.

noRecurse Use False to search all menus and toolbars for the item; otherwise use True. [Optional]

noCreate Use False if you want the item to get instantiated if it isn't already; otherwise use True. [Optional]

Remarks

Here is the syntax that can be used for identifier for each type of commandbar or command item.

Built-in commands, menus, and toolbars
Use the unique identifier (UID) of the command, menu, or toolbar. The built-in Normal.ArcID module can be used to find the UID's.


 CommandBars.Find(arcid.Standard_Toolbar)

 CommandBars.Find(arcID.File_AddData) 

Instead of using the ArcID module, you can write your own code to get the UID of the object.

To find the CLSID, ProgID, and subtype of an ESRI command, menu, or toolbar refer to the following technical documents:

ArcObjects Developer Help > Technical Documents > ArcMap: Names and IDs of commands and commandbars

ArcObjects Developer Help > Technical Documents > ArcCatalog: Names and IDs of commands and commandbars

Custom VBA toolbars and menus
Use a string that represents the full name of the custom toolbar or menu. The name of the toolbar or menu must include the project or template in which this item was created.


 CommandBars.Find("Normal.MyToolbar")

 CommandBars.Find("Project.MyToolbar")

 CommandBars.Find("Normal.New Menu") 

When you create new menus using the Customize dialog, the first menu you create is named "New Menu", the second menu you create is called "New Menu 1", etc... In the Find method, you need to use the default name of the menu instead of the caption you assigned to it. Here is an example of how custom menu naming works.

If you write code to create a new toolbar or menu then the name of that item will be prefixed by the project or template in which the module was located.

UIControls
Use a string that represents the full name of the UIControl. The name of the UIControl must include the project or template in which this UIControl was created.


  CommandBars.Find("Normal.UIButtonControl1")

  CommandBars.Find("Project.UIToolControl1")

  CommandBars.Find("TemplateProject.UICombboxControl1") 

Macro Items
Use a string that represents the full name of the VBA macro. The name of the macro must include the name of the VBA project and module in which this macro is located. Only Macros that are placed on a toolbar or menu can be found using CommandBars.Find.


  CommandBars.Find("Project.NewMacros.Test")

  CommandBars.Find("Normal.ThisDocument.MyMacro") 

Custom commands, menus, and toolbars
Use the unique identifier (UID) of your custom command, menu, or toolbar. You can create a UID object and set the value of the UID to the CLSID or ProgID of your custom object. For your custom objects, the ProgID is a string composed of the name of your project used to make the command and the class name of the command. For example if you have a Visual Basic project called MyCustomTools and there is a class module for your command called cmdMyZoomTool in that project, then the ProgID for this command would be "MyCustomTools.cmdMyZoomTool". To find the CLSID for this command, you could search the system registry for this ProgID. Note, if you have a command that is a subtype then you also have to set the SubType property on IUID to the subtype value.

Calling During Startup
Do not call Find until the Framework has fully initialized itself as indicated by the IApplicationStatus::Initialized property. For example, custom Extensions may load before the Framework has completely initialized and calling Find at this point may return an error. During startup, use the IApplicationStatusEvents::Initialized event instead of OnOpenDocument or OnNewDocument to receive notification of when it is safe to use this method.

Product Availability

Available with ArcGIS Desktop.

Supported Platforms

Windows

Parameters:
identifier - A Variant (in)
noRecurse - The noRecurse (in, optional, pass false if not required)
noCreate - The noCreate (in, optional, pass false if not required)
Returns:
A reference to a com.esri.arcgis.framework.ICommandItem
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
See Also:
ICommandBar, ICommandBars, ICommandItem

hideAllToolbars

void hideAllToolbars()
                     throws IOException,
                            AutomationException
Hides all visible bars.

Remarks

The HideAllToolbars method has no effect on the Main menu bar. The Main menu bar is always visible in the application.

Product Availability

Available with ArcGIS Desktop.

Supported Platforms

Windows

Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.