com.esri.arcgis.controls
Interface ICommandPoolEdit

All Superinterfaces:

Serializable

All Known Implementing Classes:

CommandPool

public interface ICommandPoolEdit
extends Serializable

Provides access to members that control the command pool.

Description

The ICommandPoolEdit interface is used to manage the collection of commands used by the ToolbarControl, a ToolbarMenu, a ToolbarPalette, or the commands shared between several ToolbarControl's. Use the ICommandPoolEdit interface to add and remove commands in the CommandPool and to call the ICommand::OnCreate method.

Remarks

The ICommandPoolEdit methods are normally called by the ToolbarControl, ToolbarMenu and ToolbarPalette objects to mange the command's used by their items. Typically, the Hook property will be set to a ToolbarControl. The ToolbarControl will ensure that the CallOnCreate method is called on the first IToolbarControl::Update, once the IToolbarControl::Buddy property has been set.

Product Availability

Available with ArcGIS Engine.

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.
Object	getHook() The object that is passed as a hook to the OnCreate method on the command.
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.

Method Detail

addCommand

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.

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

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.

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

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.

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

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.

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

callOnCreate

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.

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

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.

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

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.

Returns:

A reference to another Automation Object (IDispatch)

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.