Overview  Package   Class  Tree  Deprecated  Index  Help 
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES    
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.esri.arcgis.framework
Interface ICommandItem

All Superinterfaces:
Serializable
All Known Implementing Classes:
CommandBar, CommandItem, ICommandItemProxy
public interface ICommandItem
extends Serializable

Provides access to members that define a command item.

When To Use

A CommandItem is any item on a commandbar. For example, buttons, tools, and menu items that appear on commandbars are all commanditems. The ICommandItem interface allows you to get or set the properties of the commanditem such as caption, button image, statusbar message, tooltip, display style, help context ID, and more. The ICommandItem interface also provides methods to execute, delete, refresh, and reset the commanditem. Use ICommandBars::Find, ICommandBar::Find, or ICommandBar::Item to obtain a reference to a particular commanditem.

Product Availability

Available with ArcGIS Desktop.

See Also:
ICommandBars.find(java.lang.Object, boolean, boolean), ICommandBar.find(java.lang.Object, boolean), ICommandBar.getItem(int), ICommandBar.createMacroItem(String, java.lang.Object, String, java.lang.Object), ICommandBar.popup(int, int), ICommandBar.add(com.esri.arcgis.system.IUID, java.lang.Object)

Method Summary
 void delete()
          Removes this object from the commandbar.
 void execute()
          Causes the command to execute.
 String getAction()
          The name of the VBA macro this command should run when pressed.
 String getCaption()
          The caption of this command item.
 String getCategory()
          The name of the category with which this command item is associated.
 ICommand getCommand()
          A reference to the internal command object.
 Object getFaceID()
          The bitmap that is used as the icon on this command item.
 int getHelpContextID()
          The help context ID associated with this command item.
 String getHelpFile()
          The help file associated with this command item.
 IUID getID()
          The unique integer ID associated with this command item.
 int getIndex()
          The positional index of this command item within its menu or toolbar.
 String getMessage()
          The status bar message for this command item.
 String getName()
          The name of this command item.
 ICommandBar getParent()
          The menu or toolbar that this command item currently resides on.
 int getStyle()
          The display style of this command item.
 String getTag()
          The tag for this command item.
 String getTooltip()
          The tooltip for this command item.
 int getType()
          The type of this command item.
 boolean isBuiltIn()
          Indicates whether this command item is built-in or if it was implemented through VBA.
 boolean isGroup()
          Indicates if this command item begins a menu or toolbar group.
 void refresh()
          Causes the command to be redrawn.
 void reset()
          Restores this command item's properties to that of the original.
 void setAction(String macro)
          The name of the VBA macro this command should run when pressed.
 void setCaption(String name)
          The caption of this command item.
 void setFaceID(Object faceID)
          The bitmap that is used as the icon on this command item.
 void setGroup(boolean group)
          Indicates if this command item begins a menu or toolbar group.
 void setHelpContextID(int contextID)
          The help context ID associated with this command item.
 void setHelpFile(String helpFile)
          The help file associated with this command item.
 void setMessage(String message)
          The status bar message for this command item.
 void setName(String name)
          The name of this command item.
 void setStyle(int style)
          The display style of this command item.
 void setTag(String tag)
          The tag for this command item.
 void setTooltip(String tooltip)
          The tooltip for this command item.
 

Method Detail

getAction

String getAction()
                 throws IOException,
                        AutomationException
The name of the VBA macro this command should run when pressed.

Description

Action is a string representing the full name of the VBA macro that is to be executed when the command item is clicked. The name of the macro must include the name of the VBA project in which this macro is located.

Remarks

Here are some examples of the syntax of the value for the Action property.

Macro called MyMacro in ThisDocument in Normal template:
"Normal.ThisDocument.MyMacro"

Macro called MyMacro in Module1 in Normal template:
"Normal.Module1.MyMacro"

Macro called MyMacro in ThisDocument in the current document:
"Project.ThisDocument.MyMacro"

Macro called MyMacro in Module1 in the current document:
"Project.Module1.MyMacro"

Macro called MyMacro in ThisDocument in a base template:
"TemplateProject.ThisDocument.MyMacro"

Macro called MyMacro in Module1 in a base template:
"TemplateProject.Module1.MyMacro"

Note: This property only applies to macro items.

Product Availability

Available with ArcGIS Desktop.

Supported Platforms

Windows

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

setAction

void setAction(String macro)
               throws IOException,
                      AutomationException
The name of the VBA macro this command should run when pressed.

Description

Action is a string representing the full name of the VBA macro that is to be executed when the command item is clicked. The name of the macro must include the name of the VBA project in which this macro is located.

Product Availability

Available with ArcGIS Desktop.

Supported Platforms

Windows

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

isBuiltIn

boolean isBuiltIn()
                  throws IOException,
                         AutomationException
Indicates whether this command item is built-in or if it was implemented through VBA.

Description

Returns True if the command is a COM command that was created by implementing ICommand and compiling into a DLL. Returns False if the command is a UIControl or a VBA macro.

Product Availability

Available with ArcGIS Desktop.

Supported Platforms

Windows

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

getCategory

String getCategory()
                   throws IOException,
                          AutomationException
The name of the category with which this command item is associated.

Description

Category is a string that represents the category of the command on which this command item is based. The category determines where the command will appear in the Commands panel of the Customize dialog.

Product Availability

Available with ArcGIS Desktop.

Supported Platforms

Windows

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

getCommand

ICommand getCommand()
                    throws IOException,
                           AutomationException
A reference to the internal command object.

Description

Returns a reference to the command (Button, Tool, ToolControl, or MultiItem) on which this command item is based.

Product Availability

Available with ArcGIS Desktop.

Supported Platforms

Windows

Returns:
A reference to a com.esri.arcgis.systemUI.ICommand
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
See Also:
ICommand

delete

void delete()
            throws IOException,
                   AutomationException
Removes this object from the commandbar.

Remarks

When you delete a commanditem from a commandbar it is not deleted from the application; it is just removed from the commandbar. You can always add that command back to a commandbar.

Product Availability

Available with ArcGIS Desktop.

Supported Platforms

Windows

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

setFaceID

void setFaceID(Object faceID)
               throws IOException,
                      AutomationException
The bitmap that is used as the icon on this command item.

Description




Product Availability

Available with ArcGIS Desktop.

Supported Platforms

Windows

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

getFaceID

Object getFaceID()
                 throws IOException,
                        AutomationException
The bitmap that is used as the icon on this command item.

Description

The values for FaceID from the built-in icon palette are:

You can also use your own bitmap (.bmp file) with ICommandItem::FaceID. To use your own bitmap, you could create a UserForm in VBA with a Image control on it. Set the Picture property of the Image control to your bitmap.

If you are using your own bitmap, it must be a Bitmap file (.bmp); Icon files (.ico) are not supported. Bitmap files should be 16 X 16 pixels. The color of the upper left pixel of the bitmap is treated as the transparent color. For example, if the upper left pixel of the bitmap is red, then all of the red pixels in the bitmap will be converted to transparent.

Product Availability

Available with ArcGIS Desktop.

Supported Platforms

Windows

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

setGroup

void setGroup(boolean group)
              throws IOException,
                     AutomationException
Indicates if this command item begins a menu or toolbar group.

Product Availability

Available with ArcGIS Desktop.

Supported Platforms

Windows

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

isGroup

boolean isGroup()
                throws IOException,
                       AutomationException
Indicates if this command item begins a menu or toolbar group.

Description

If Group is set to True, the command item is the first item in a group on a toolbar or menu. There will be a separator bar to the left of the command item. If Group is set to False, the command item does not have a separator bar to the left of it.

Product Availability

Available with ArcGIS Desktop.

Supported Platforms

Windows

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

getHelpFile

String getHelpFile()
                   throws IOException,
                          AutomationException
The help file associated with this command item.

Remarks

You cannot set HelpFile for built-in commands. It is not implemented for macro items and UIControls.

Product Availability

Available with ArcGIS Desktop.

Supported Platforms

Windows

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

setHelpFile

void setHelpFile(String helpFile)
                 throws IOException,
                        AutomationException
The help file associated with this command item.

Product Availability

Available with ArcGIS Desktop.

Supported Platforms

Windows

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

getHelpContextID

int getHelpContextID()
                     throws IOException,
                            AutomationException
The help context ID associated with this command item.

Remarks

You cannot set HelpContextID for built-in commands. It is not implemented for macro items and UIControls.

Product Availability

Available with ArcGIS Desktop.

Supported Platforms

Windows

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

setHelpContextID

void setHelpContextID(int contextID)
                      throws IOException,
                             AutomationException
The help context ID associated with this command item.

Product Availability

Available with ArcGIS Desktop.

Supported Platforms

Windows

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

getID

IUID getID()
           throws IOException,
                  AutomationException
The unique integer ID associated with this command item.

Product Availability

Available with ArcGIS Desktop.

Supported Platforms

Windows

Returns:
A reference to a com.esri.arcgis.system.IUID
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
See Also:
IUID

getIndex

int getIndex()
             throws IOException,
                    AutomationException
The positional index of this command item within its menu or toolbar.

Product Availability

Available with ArcGIS Desktop.

Supported Platforms

Windows

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

getName

String getName()
               throws IOException,
                      AutomationException
The name of this command item.

Description

Returns the programmatic identifying name string for the command on which this command item is based. Note, this is usually different from the Caption property of a the command.

Remarks

You can modify Name for VBA macro items but not built-in commands and UIControls. Setting this property for a built-in command or UIControls will return "This method cannot be called on built in commands" run-time error.

Product Availability

Available with ArcGIS Desktop.

Supported Platforms

Windows

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

setName

void setName(String name)
             throws IOException,
                    AutomationException
The name of this command item.

Description

Returns the programmatic identifying name string for the command on which this command item is based. Note, this is usually different from the Caption property of a the command.

Product Availability

Available with ArcGIS Desktop.

Supported Platforms

Windows

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

setCaption

void setCaption(String name)
                throws IOException,
                       AutomationException
The caption of this command item.

Description

The Caption property of a command item is a string that appears when the command item is placed on a menu or when the command item's display style property is set to Text Only or Image and Text.

Product Availability

Available with ArcGIS Desktop.

Supported Platforms

Windows

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

getCaption

String getCaption()
                  throws IOException,
                         AutomationException
The caption of this command item.

Description

The Caption property of a command item is a string that appears when the command item is placed on a menu or when the command item's display style property is set to Text Only or Image and Text.

Product Availability

Available with ArcGIS Desktop.

Supported Platforms

Windows

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

getParent

ICommandBar getParent()
                      throws IOException,
                             AutomationException
The menu or toolbar that this command item currently resides on.

Description

Returns a reference to the CommandBar that this command item is on.

Product Availability

Available with ArcGIS Desktop.

Supported Platforms

Windows

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

reset

void reset()
           throws IOException,
                  AutomationException
Restores this command item's properties to that of the original.

Product Availability

Available with ArcGIS Desktop.

Supported Platforms

Windows

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

getStyle

int getStyle()
             throws IOException,
                    AutomationException
The display style of this command item.

Description

The Style of a command item determines whether the command item is displayed on a command bar using its caption, image or both. Refer to the esriCommandStyles constants topic for the values for Style.

When a command is put on a toolbar, the command is displayed with the bitmap only by default; the display type is set to Image Only (Style = esriCommandStyleIconOnly).

When a command is put on a menu, the command is displayed with the bitmap and caption by default; the display type is set to Image and Text (Style = esriCommandStyleIconAndText).

However, if the Bitmap property (ICommand::Bitmap) is not set for this command, then the command will be displayed with the caption only by default when it is put on a toolbar or menu; the display type is set to Text Only (Style = esriCommandStyleTextOnly).

Product Availability

Available with ArcGIS Desktop.

Supported Platforms

Windows

Returns:
A com.esri.arcgis.systemUI.esriCommandStyles constant
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
See Also:
esriCommandStyles

setStyle

void setStyle(int style)
              throws IOException,
                     AutomationException
The display style of this command item.

Product Availability

Available with ArcGIS Desktop.

Supported Platforms

Windows

Parameters:
style - A com.esri.arcgis.systemUI.esriCommandStyles constant (in)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
See Also:
esriCommandStyles

getTag

String getTag()
              throws IOException,
                     AutomationException
The tag for this command item.

Product Availability

Available with ArcGIS Desktop.

Supported Platforms

Windows

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

setTag

void setTag(String tag)
            throws IOException,
                   AutomationException
The tag for this command item.

Product Availability

Available with ArcGIS Desktop.

Supported Platforms

Windows

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

getTooltip

String getTooltip()
                  throws IOException,
                         AutomationException
The tooltip for this command item.

Description

Tooltip is a string that appears in the screen tip when the mouse hovers over the command item.

Remarks

You can modify Tooltip for VBA macro items but not built-in commands and UIControls. Setting this property for a built-in command or UIControls will return "This method cannot be called on built in commands" run-time error.

Product Availability

Available with ArcGIS Desktop.

Supported Platforms

Windows

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

setTooltip

void setTooltip(String tooltip)
                throws IOException,
                       AutomationException
The tooltip for this command item.

Product Availability

Available with ArcGIS Desktop.

Supported Platforms

Windows

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

getType

int getType()
            throws IOException,
                   AutomationException
The type of this command item.

Description

Returns the type of this command item using the esriCommandTypes constants. The command item can be one of the following types:

Product Availability

Available with ArcGIS Desktop.

Supported Platforms

Windows

Returns:
A com.esri.arcgis.framework.esriCommandTypes constant
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
See Also:
esriCommandTypes

getMessage

String getMessage()
                  throws IOException,
                         AutomationException
The status bar message for this command item.

Description

Message is a string that appears as the message in the statusbar of the application when the mouse passes over the command item.

Remarks

You can modify Message for VBA macro items but not built-in commands and UIControls. Setting this property for a built-in command or UIControls will return "This method cannot be called on built in commands" run-time error.

Product Availability

Available with ArcGIS Desktop.

Supported Platforms

Windows

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

setMessage

void setMessage(String message)
                throws IOException,
                       AutomationException
The status bar message for this command item.

Product Availability

Available with ArcGIS Desktop.

Supported Platforms

Windows

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

execute

void execute()
             throws IOException,
                    AutomationException
Causes the command to execute.

Product Availability

Available with ArcGIS Desktop.

Supported Platforms

Windows

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

refresh

void refresh()
             throws IOException,
                    AutomationException
Causes the command to be redrawn.

Description

Causes the command item to be redrawn on the CommandBar in order to correctly display any new property changes.

It is generally unnecessary to explicitly call Refresh; CommandItem updates such as setting the caption, image, and style all automatically call Refresh.

Product Availability

Available with ArcGIS Desktop.

Supported Platforms

Windows

Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
Overview  Package   Class  Tree  Deprecated  Index  Help 
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES    
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD