com.esri.arcgis.controls
Class CommandPool

java.lang.Object
  extended by 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:

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.