com.esri.arcgis.controls
Class CommandPool

java.lang.Object
  com.esri.arcgis.controls.CommandPool

All Implemented Interfaces:

ICommandPool, ICommandPool2, ICommandPoolEdit, com.esri.arcgis.interop.RemoteObjRef, ISupportErrorInfo, Serializable

public class CommandPool
extends Object
implements com.esri.arcgis.interop.RemoteObjRef, ICommandPool, ICommandPool2, ICommandPoolEdit, ISupportErrorInfo

A collection of commands used by the ToolbarControl.

Description

The CommandPool is used for managing the collection of commands used by the ToolbarControl, a ToolbarMenu, a ToolbarPalette, or the commands shared between several ToolbarControl's. The ToolbarControl manages its CommandPool itself in order to maintain its command items. If a ToolbarMenu or ToolbarPalette are added to a ToolbarControl they will automatically share the same CommandPool as the ToolbarControl. If a ToolbarMenu or ToolbarPalette are used standalone they will mange their own CommandPool.

Remarks

The CommandPool is used for managing the collection of Command objects (including Tool and ToolControl objects) objects used by the ToolbarControl. Normally, the CommandPool is entirely managed by the ToolbarControl, a ToolbarMenu or a ToolbarPalette in order to maintain to its command items.

The main job of the CommandPool is to create Command objects from valid UID's and prevent multiple instances of the same Command being created. This ensures that if the same Command is added to multiple ToolbarControl's, there will be only one actual instance of that Command in the CommandPool. When a Command is added by passing the ICommandPoolEdit::AddCommand method a valid UID, the first time that UID is supplied, a brand new Command is created and the CommandPool gives this a UsageCount of 1. If another ToolbarControl passes the ICommandPoolEdit::AddCommand the same UID the CommandPool will return the existing Command and will increment the UsageCount to 2.

By default each ToolbarControl has its own CommandPool. To ensure Commands are shared amongst multiple ToolbarControls the same CommandPool object must be set into each ToolbarControl. ToolbarMenu and ToolbarPalette objects also use a CommandPool. If a ToolbarMenu or ToolbarPalette is added to a ToolbarControl it will automatically share the same CommandPool as the ToolbarControl.

Other tasks performed by the CommandPool are:

• Managing Command objects added by passing the ICommandPoolEdit::AddCommand method an ICommand. In such cases when the UID is missing the CommandPool will look for duplicate Commands.
• Managing Command objects added by passing the ICommandPoolEdit::AddUID a valid UID with a SubType property set to 0, when the Command supports ICommandSubType. In such cases the CommandPool will create multiple Command objects for each available SubType.
• The CommandPool passes each Command's OnCreate method a hook. The hook can be any object that implements an IDispatch interface, but is typically the ToolbarControl. The ICommandPool::Created property indicates whether ICommand::OnCreate has been called.
  

Product Availability

Available with ArcGIS Engine.

See Also:

Serialized Form

Constructor Summary

CommandPool()
Constructs a CommandPool using ArcGIS Engine.

CommandPool(Object obj)
Deprecated. As of ArcGIS 9.2, replaced by normal Java casts.
CommandPool theCommandPool = (CommandPool) obj;

Method Summary

void	addCommand(ICommand command, IUID pUID) Adds the specified command to the command pool.
IArray	addUID(IUID uID) Adds the given UID to the command pool and returns an array of command objects.
void	callOnCreate(ICommand pCommand) Calls the specified command OnCreate method if the Hook is set and OnCreate has not already been called.
boolean	created(ICommand command) Indicates if the commands OnCreate method has been called.
boolean	equals(Object o) Compare this object with another
boolean	exists(ICommand command) Indicates if the given command exists in the command pool.
ICommand	findByUID(IUID uID) Searches the command pool for the given UID.
static String	getClsid() getClsid.
ICommand	getCommand(int index) The command at the given index.
int	getCount() The number of commands in the command pool.
Object	getHook() The object that is passed as a hook to the OnCreate method on the command.
IUID	getUID(ICommand command) The UID of the given command.
int	getUsageCount(ICommand command) The number of items using the given command.
int	hashCode() the hashcode for this object
void	interfaceSupportsErrorInfo(GUID riid) interfaceSupportsErrorInfo
void	remove(ICommand command) Decrements the usage count of the command.
void	removeAll() Removes all commands from the command pool, regardless of each commands usage count.
void	setHook(Object pHook) Sets the object that is passed as a hook to the OnCreate method on the command.
boolean	translateAcceleratorKey(int keyCode) Translates the specified keyCode, if a corresponding accelerator exists.

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface com.esri.arcgis.interop.RemoteObjRef

getJintegraDispatch, release

Constructor Detail

CommandPool

public CommandPool()
            throws IOException,
                   UnknownHostException

Constructs a CommandPool using ArcGIS Engine.

Throws:

IOException - if there are interop problems

UnknownHostException - if there are interop problems

CommandPool

public CommandPool(Object obj)
            throws IOException

Deprecated. As of ArcGIS 9.2, replaced by normal Java casts.
CommandPool theCommandPool = (CommandPool) obj;

Construct a CommandPool using a reference to such an object returned from ArcGIS Engine or Server. This is semantically equivalent to casting obj to CommandPool.

Parameters:

obj - an object returned from ArcGIS Engine or Server

Throws:

IOException - if there are interop problems

Method Detail

getClsid

public static String getClsid()

getClsid.

equals

public boolean equals(Object o)

Compare this object with another

Overrides:

equals in class Object

hashCode

public int hashCode()

the hashcode for this object

Overrides:

hashCode in class Object

getCount

public int getCount()
             throws IOException,
                    AutomationException

The number of commands in the command pool.

Description

Returns the number of commands in the CommandPool.

Product Availability

Available with ArcGIS Engine.

Specified by:

getCount in interface ICommandPool

Returns:

The pVal

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

getUsageCount

public int getUsageCount(ICommand command)
                  throws IOException,
                         AutomationException

The number of items using the given command.

Product Availability

Available with ArcGIS Engine.

Specified by:

getUsageCount in interface ICommandPool

Parameters:

command - A reference to a com.esri.arcgis.systemUI.ICommand (in)

Returns:

The pVal

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

exists

public boolean exists(ICommand command)
               throws IOException,
                      AutomationException

Indicates if the given command exists in the command pool.

Description

Indicates whether the specified command exists in the CommandPool.

Product Availability

Available with ArcGIS Engine.

Specified by:

exists in interface ICommandPool

Parameters:

command - A reference to a com.esri.arcgis.systemUI.ICommand (in)

Returns:

The res

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

findByUID

public ICommand findByUID(IUID uID)
                   throws IOException,
                          AutomationException

Searches the command pool for the given UID. Returns matching command if the UID is found or nothing.

Description

Searches the CommandPool for the specified UID, and returns the matching Command. Returns Nothing if the UID cannot be found. For commands that implement ICommandSubType, the IUID::SubType must be specified, otherwise Nothing will be returned.

Product Availability

Available with ArcGIS Engine.

Specified by:

findByUID in interface ICommandPool

Parameters:

uID - A reference to a com.esri.arcgis.system.IUID (in)

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.

getUID

public IUID getUID(ICommand command)
            throws IOException,
                   AutomationException

The UID of the given command. May return nothing.

Product Availability

Available with ArcGIS Engine.

Specified by:

getUID in interface ICommandPool

Parameters:

command - A reference to a com.esri.arcgis.systemUI.ICommand (in)

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.

getCommand

public ICommand getCommand(int index)
                    throws IOException,
                           AutomationException

The command at the given index.

Product Availability

Available with ArcGIS Engine.

Specified by:

getCommand in interface ICommandPool

Parameters:

index - The index (in)

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.

created

public boolean created(ICommand command)
                throws IOException,
                       AutomationException

Indicates if the commands OnCreate method has been called.

Description

Indicates if the specified command's ICommand::OnCreate method has been called.

Product Availability

Available with ArcGIS Engine.

Specified by:

created in interface ICommandPool

Parameters:

command - A reference to a com.esri.arcgis.systemUI.ICommand (in)

Returns:

The pVal

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

translateAcceleratorKey

public boolean translateAcceleratorKey(int keyCode)
                                throws IOException,
                                       AutomationException

Translates the specified keyCode, if a corresponding accelerator exists.

Description

Returns whether the specified keyCode is a supported accelerator (shortcut) or access key, defined in an ICommand::Caption property of a Command in the CommandPool. To translate an accelerator key, the ICommand::OnClick method must be called.

For example, a 'Close' command with the caption "&Close\tAlt+F4" has the 'ALT+F4' key combination as its shortcut key, and the 'C' key as its access key.

When using the TranslateAcceleratorKey pass the keyCode of the none system key only. For example, if the accelerator is "Ctrl+K", pass the keyCode for "K" to TranslateAcceleratorKey. The system will automatically check for the system key "Ctrl".

Product Availability

Available with ArcGIS Engine.

Specified by:

translateAcceleratorKey in interface ICommandPool2

Parameters:

keyCode - The keyCode (in)

Returns:

The bHandled

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

addCommand

public void addCommand(ICommand command,
                       IUID pUID)
                throws IOException,
                       AutomationException

Adds the specified command to the command pool. If the command already exists its usage count incremented by 1.

Description

If a UID object is specified and the command object is nothing, the method searches the CommandPool for the given UID. If the UID is found its UsageCount is incremented by 1. If the UID is not found a new command is created and added to the CommandPool with a UsageCount of 1.

If a command object is specified and the UID object is nothing, the command is added to the CommandPool with a UsageCount of 1.

If a UID object and a command object are specified, the method searches the CommandPool for the given UID. If the UID is found its UsageCount is incremented by 1. If the UID is not found the specified command is added to the CommandPool with a UsageCount of 1.

Remarks

Typically the AddUID method should be used as the method to add commands that implement the ICommandSubType interface. If the AddCommand method is used the IUID::SubType property must be set.

Product Availability

Available with ArcGIS Engine.

Specified by:

addCommand in interface ICommandPoolEdit

Parameters:

command - A reference to a com.esri.arcgis.systemUI.ICommand (in)

pUID - A reference to a com.esri.arcgis.system.IUID (in)

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

addUID

public IArray addUID(IUID uID)
              throws IOException,
                     AutomationException

Adds the given UID to the command pool and returns an array of command objects.

Description

Adds commands to the CommandPool using the specified UID. The method searches the CommandPool for the specified UID. If the UID is found then that commands UsageCount is incremented by 1. If the UID is not found a new command is created and added to the CommandPool with a UsageCount of 1. The command is returned in an array.

If the specified UID is a command that implements the ICommandSubType interface, the method will return an array of all the commands, and if necessary create the command in the CommandPool. Set the IUID::SubType property to a none zero value to add a specific command defined within the ICommandSubType object.

Product Availability

Available with ArcGIS Engine.

Specified by:

addUID in interface ICommandPoolEdit

Parameters:

uID - A reference to a com.esri.arcgis.system.IUID (in)

Returns:

A reference to a com.esri.arcgis.system.IArray

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

remove

public void remove(ICommand command)
            throws IOException,
                   AutomationException

Decrements the usage count of the command. If this reaches zero the command is removed from the command pool.

Description

Decrements the supplied command UsageCount by 1. If the UsageCount reaches 0 the command is released from the CommandPool and the ICommandPool::Exists property will return false. If the UsageCount is 1 or more the command will remain in the CommandPool. The number of calls to the AddUID and AddCommand methods for a given UID must typically match the number of calls to Remove.

Remarks

Typically the ToolbarControl will manage the commands in the CommandPool as part of IToolbarControl::AddItem and IToolbarControl::Remove methods.

Product Availability

Available with ArcGIS Engine.

Specified by:

remove in interface ICommandPoolEdit

Parameters:

command - A reference to a com.esri.arcgis.systemUI.ICommand (in)

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

removeAll

public void removeAll()
               throws IOException,
                      AutomationException

Removes all commands from the command pool, regardless of each commands usage count.

Description

Removes all of the commands from the CommandPool. The developer must ensure that any IToolbarItem objects using the commands are removed from the ToolbarControl.

Product Availability

Available with ArcGIS Engine.

Specified by:

removeAll in interface ICommandPoolEdit

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

callOnCreate

public void callOnCreate(ICommand pCommand)
                  throws IOException,
                         AutomationException

Calls the specified command OnCreate method if the Hook is set and OnCreate has not already been called.

Description

Calls the ICommand:OnCreate event for the specified command.

When a command is added to the CommandPool, the ICommandPool::Created property is set to false. If the ICommandPoolEdit::Hook property is set, the CallOnCreate method will pass the Hook into the command's ICommand:OnCreate method. The ICommandPool::Created property is then set to true.

To ensure that the ICommand:OnCreate method is called only once during the lifetime of the command object, subsquent calls to the CallOnCreate method will not do anything.

Product Availability

Available with ArcGIS Engine.

Specified by:

callOnCreate in interface ICommandPoolEdit

Parameters:

pCommand - A reference to a com.esri.arcgis.systemUI.ICommand (in)

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

setHook

public void setHook(Object pHook)
             throws IOException,
                    AutomationException

Sets the object that is passed as a hook to the OnCreate method on the command.

Description

Pass the SetHook method an IDispatch object, typically the ToolbarControl, that is passed as a hook to the ICommand::OnCreate method of each command in the CommandPool.

Product Availability

Available with ArcGIS Engine.

Specified by:

setHook in interface ICommandPoolEdit

Parameters:

pHook - A reference to another Automation Object (IDispatch) (in)

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

getHook

public Object getHook()
               throws IOException,
                      AutomationException

The object that is passed as a hook to the OnCreate method on the command.

Description

The Hook is an IDispatch object, typically the ToolbarControl, that is passed as a hook to the ICommand::OnCreate method of each command in the CommandPool.

Product Availability

Available with ArcGIS Engine.

Specified by:

getHook in interface ICommandPoolEdit

Returns:

A reference to another Automation Object (IDispatch)

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

interfaceSupportsErrorInfo

public void interfaceSupportsErrorInfo(GUID riid)
                                throws IOException,
                                       AutomationException

interfaceSupportsErrorInfo

Description

Indicates whether the interface supports IErrorInfo.

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

Supported Platforms

Windows, Solaris, Linux

Specified by:

interfaceSupportsErrorInfo in interface ISupportErrorInfo

Parameters:

riid - A Structure: com.esri.arcgis.support.ms.stdole.GUID (in)

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.