com.esri.arcgis.controls
Class CommandPool

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

All Implemented Interfaces:

ICommandPool, ICommandPool2, ICommandPoolEdit, ISupportErrorInfo, java.io.Serializable

public class CommandPool

extends java.lang.Object

implements ICommandPool, ICommandPool2, ICommandPoolEdit, ISupportErrorInfo

A collection of commands used by the ToolbarControl.

Product Availability

Available with ArcGIS Engine.

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.
  

See Also:

Serialized Form

Constructor Summary

CommandPool()
Constructs a CommandPool using ArcGIS Engine.

CommandPool(java.lang.Object obj)
Deprecated. As of ArcGIS 9.2, replaced by normal Java casts.

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(java.lang.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.
ICommandPool	getAsICommandPool() Deprecated. No replacement. The object reference can be directly used where the implemented interface is needed.
ICommandPool2	getAsICommandPool2() Deprecated. No replacement. The object reference can be directly used where the implemented interface is needed.
ICommandPoolEdit	getAsICommandPoolEdit() Deprecated. No replacement. The object reference can be directly used where the implemented interface is needed.
ISupportErrorInfo	getAsISupportErrorInfo() Deprecated. No replacement. The object reference can be directly used where the implemented interface is needed.
static java.lang.String	getClsid()
ICommand	getCommand(int index) The command at the given index.
int	getCount() The number of commands in the command pool.
java.lang.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) Supported Platforms
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(java.lang.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

Constructor Detail

CommandPool

public CommandPool()
            throws java.io.IOException,
                   java.net.UnknownHostException

Constructs a CommandPool using ArcGIS Engine.

Throws:

java.io.IOException - if there are interop problems

java.net.UnknownHostException - if there are interop problems

CommandPool

public CommandPool(java.lang.Object obj)
            throws java.io.IOException

Deprecated. As of ArcGIS 9.2, replaced by normal Java casts.

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.
CommandPool theCommandPool = (CommandPool) obj;

Parameters:

obj - an object returned from ArcGIS Engine or Server

Throws:

java.io.IOException - if there are interop problems

Method Detail

getClsid

public static java.lang.String getClsid()

getAsICommandPool

public ICommandPool getAsICommandPool()

Deprecated. No replacement. The object reference can be directly used where the implemented interface is needed.

getAsICommandPool2

public ICommandPool2 getAsICommandPool2()

Deprecated. No replacement. The object reference can be directly used where the implemented interface is needed.

getAsICommandPoolEdit

public ICommandPoolEdit getAsICommandPoolEdit()

Deprecated. No replacement. The object reference can be directly used where the implemented interface is needed.

getAsISupportErrorInfo

public ISupportErrorInfo getAsISupportErrorInfo()

Deprecated. No replacement. The object reference can be directly used where the implemented interface is needed.

equals

public boolean equals(java.lang.Object o)

Compare this object with another

hashCode

public int hashCode()

the hashcode for this object

getCount

public int getCount()
             throws java.io.IOException,
                    AutomationException

Description copied from interface: ICommandPool

The number of commands in the command pool.

Description

Returns the number of commands in the CommandPool.

Specified by:

getCount in interface ICommandPool

Returns:

The pVal

Throws:

java.io.IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

getUsageCount

public int getUsageCount(ICommand command)
                  throws java.io.IOException,
                         AutomationException

Description copied from interface: ICommandPool

The number of items using the given command.

Description

The UsageCount is normally managed by the ToolbarControl, and returns the number of times an instance of a Command is shared. When a command is added by passing the ICommandPoolEdit::AddCommand or ICommndPoolEdit::AddUID method a valid UID object, the first time that UID is supplied, a brand new Command is created and the CommandPool gives this a UsageCount of 1. The second time the same UID is passed in, the CommandPool will return the existing Command and will increment the UsageCount to 2.

Using the ICommndPoolEdit::Remove method will decrement the UsageCount by 1. When the UsageCount reaches 0 the Command is released from the CommandPool.

Specified by:

getUsageCount in interface ICommandPool

Parameters:

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

Returns:

The pVal

Throws:

AutomationException - If the ArcObject component throws an exception.

java.io.IOException - If there are interop problems.

exists

public boolean exists(ICommand command)
               throws java.io.IOException,
                      AutomationException

Description copied from interface: ICommandPool

Indicates if the given command exists in the command pool.

Description

Indicates whether the specified command exists in the CommandPool.

Specified by:

exists in interface ICommandPool

Parameters:

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

Returns:

The res

Throws:

AutomationException - If the ArcObject component throws an exception.

java.io.IOException - If there are interop problems.

findByUID

public ICommand findByUID(IUID uID)
                   throws java.io.IOException,
                          AutomationException

Description copied from interface: ICommandPool

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.

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:

AutomationException - If the ArcObject component throws an exception.

java.io.IOException - If there are interop problems.

getUID

public IUID getUID(ICommand command)
            throws java.io.IOException,
                   AutomationException

Description copied from interface: ICommandPool

The UID of the given command. May return nothing.

Description

Returns the UID of the specified command. The method will return Nothing if the command object has been added to the CommadPool using either the AddCommand or IToolbarControl::AddItem, IToolbarMenu::AddItem or IToolbarPalette::AddItem methods without a UID or ProgID supplied.

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:

java.io.IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

getCommand

public ICommand getCommand(int index)
                    throws java.io.IOException,
                           AutomationException

Description copied from interface: ICommandPool

The command at the given index.

Description

Returns the command at the specified index in the CommandPool. The index is related to the order commands are added to the CommandPool and not to the display order of any IToolbarItem objects using the commands.

Remarks

To loop through the CommandPool's command collection use the Command property in conjunction with the Count property.

Specified by:

getCommand in interface ICommandPool

Parameters:

index - The index (in)

Returns:

A reference to a com.esri.arcgis.systemUI.ICommand

Throws:

AutomationException - If the ArcObject component throws an exception.

java.io.IOException - If there are interop problems.

created

public boolean created(ICommand command)
                throws java.io.IOException,
                       AutomationException

Description copied from interface: ICommandPool

Indicates if the commands OnCreate method has been called.

Description

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

Specified by:

created in interface ICommandPool

Parameters:

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

Returns:

The pVal

Throws:

AutomationException - If the ArcObject component throws an exception.

java.io.IOException - If there are interop problems.

translateAcceleratorKey

public boolean translateAcceleratorKey(int keyCode)
                                throws java.io.IOException,
                                       AutomationException

Description copied from interface: ICommandPool2

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".

Specified by:

translateAcceleratorKey in interface ICommandPool2

Parameters:

keyCode - The keyCode (in)

Returns:

The bHandled

Throws:

AutomationException - If the ArcObject component throws an exception.

java.io.IOException - If there are interop problems.

addCommand

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

Description copied from interface: ICommandPoolEdit

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.

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:

java.io.IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

addUID

public IArray addUID(IUID uID)
              throws java.io.IOException,
                     AutomationException

Description copied from interface: ICommandPoolEdit

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.

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:

java.io.IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

remove

public void remove(ICommand command)
            throws java.io.IOException,
                   AutomationException

Description copied from interface: ICommandPoolEdit

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.

Specified by:

remove in interface ICommandPoolEdit

Parameters:

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

Throws:

java.io.IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

removeAll

public void removeAll()
               throws java.io.IOException,
                      AutomationException

Description copied from interface: ICommandPoolEdit

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.

Specified by:

removeAll in interface ICommandPoolEdit

Throws:

AutomationException - If the ArcObject component throws an exception.

java.io.IOException - If there are interop problems.

callOnCreate

public void callOnCreate(ICommand pCommand)
                  throws java.io.IOException,
                         AutomationException

Description copied from interface: ICommandPoolEdit

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.

Specified by:

callOnCreate in interface ICommandPoolEdit

Parameters:

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

Throws:

AutomationException - If the ArcObject component throws an exception.

java.io.IOException - If there are interop problems.

setHook

public void setHook(java.lang.Object pHook)
             throws java.io.IOException,
                    AutomationException

Description copied from interface: ICommandPoolEdit

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

Specified by:

setHook in interface ICommandPoolEdit

Parameters:

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

Throws:

AutomationException - If the ArcObject component throws an exception.

java.io.IOException - If there are interop problems.

getHook

public java.lang.Object getHook()
                         throws java.io.IOException,
                                AutomationException

Description copied from interface: ICommandPoolEdit

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.

Specified by:

getHook in interface ICommandPoolEdit

Returns:

A reference to another Automation Object (IDispatch)

Throws:

AutomationException - If the ArcObject component throws an exception.

java.io.IOException - If there are interop problems.

interfaceSupportsErrorInfo

public void interfaceSupportsErrorInfo(GUID riid)
                                throws java.io.IOException,
                                       AutomationException

Description copied from interface: ISupportErrorInfo

Supported Platforms

Windows, Solaris, Linux

Description

Indicates whether the interface supports IErrorInfo.

Specified by:

interfaceSupportsErrorInfo in interface ISupportErrorInfo

Parameters:

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

Throws:

AutomationException - If the ArcObject component throws an exception.

java.io.IOException - If there are interop problems.