com.esri.arcgis.systemUI
Interface IToolControl

All Superinterfaces:
Serializable
All Known Implementing Classes:
ControlsEditingTargetToolControl, ControlsEditingTaskToolControl, ControlsFlickerRateToolControl, ControlsGlobeLayerListToolControl, ControlsLayerListToolControl, ControlsMapZoomToolControl, ControlsNetworkAnalystLayerToolControl, ControlsPageZoomToolControl, ControlsSchematicEditTargetControl, ControlsSchematicLayoutToolControl

public interface IToolControl
extends Serializable

Provides access to members that define a toolcontrol.

Description

A ToolControl is a Command that acts like a combobox or editbox. Comboboxes let you choose an option from a drop-down list. For example, in ArcMap, you can choose which layer(s) you are selecting features from when working with a map. Editboxes are editable textboxes where you can type in text.

Remarks

When implementing IToolControl to create a custom tool, use the hWnd property to pass window handle of your control to the application.

For example, if you want your ToolControl to be a simple ComboBox control, put a ComboBox control on a form and then pass the hWnd of the ComboBox control to the ToolControl. If you want your ToolControl to be more complex such as a ComboBox with a label, you can put the ComboBox and Label in a Frame control or PictureBox control, and then pass the hWnd of the Frame or PictureBox to the ToolControl.

Only one instance of a ToolControl can exist within an application framework at any given time. This is because the hWnd property is passed as window handle to the control. To prevent a user from dragging two instances of a ToolControl into an application framework set the ICommand::Category property to an empty string. This will prevent the ToolControl from appearing in the customize dialog.

There is a conflict between ToolControl and MessageBox in .NET. The problem appears when you make the ToolControl the parent of the MessageBox. If you make the application itself the parent of the MessageBox the problem goes away.

Use the following code as a workaround for this issue (C#):

[ DllImport( "User32.dll", EntryPoint="MessageBox", CharSet=CharSet.Auto )]
public static extern int MsgBox( int hWnd, String text, String caption, uint type );

and then:

MsgBox(m_app.hWnd, "Test box", "", 0);

where m_app is the member variable for the current Application.

When To Use

The IToolControl interface is implemented by Command objects that act as combobox controls, editbox controls, or other types of controls that can be added to a toolbar. A Command that implements IToolControl passes its window handle to the application. To create a custom ToolControl you would implement both the ICommand and IToolControl interfaces in your class code.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

See Also:
ICommand

Method Summary
 int getHWnd()
          The handle of the control.
 boolean onDrop(int barType)
          Indicates if the drag-drop operation is valid.
 void onFocus(ICompletionNotify complete)
          Occurs when the control gains focus.
 

Method Detail

getHWnd

int getHWnd()
            throws IOException,
                   AutomationException
The handle of the control.

Remarks

When implementing IToolControl to create a custom tool, use the hWnd property to pass window handle of the control to the application.

For example, if you want your ToolControl to be a simple ComboBox control, put a ComboBox control on a form and then pass the hWnd of the ComboBox control to the ToolControl. If you want you ToolControl to be more complex such as a ComboBox with a label, you can put the ComboBox and Label in a Frame control or PictureBox control, and then pass the hWnd of the Frame or PictureBox to the ToolControl.

Only one instance of a ToolControl can exist within an application framework at any give time. This
is because the hWnd property is passed a window handle to the control. To prevent a user from dragging two instances of a ToolControl into an application framework set the ICommand::Category property to an empty string. This will prevent the ToolControl from appearing in the customzie dialog.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Returns:
The hWnd (A COM typedef)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

onFocus

void onFocus(ICompletionNotify complete)
             throws IOException,
                    AutomationException
Occurs when the control gains focus.

Description

complete is a reference to a ICompletionNotify object. The ToolControl object uses this complete object to indicate when it's finished.

Remarks

When the ToolControl object gains focus, an ICompletionNotify object is passed to the ToolControl as the complete parameter in the OnFocus method. In your code in the OnFocus method, you would set a variable to the complete object.

The ToolControl needs to call the ICompletionNotify::SetComplete method when it's finished to let the application know that the control should lose focus.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Parameters:
complete - A reference to a com.esri.arcgis.systemUI.ICompletionNotify (in)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
See Also:
ICompletionNotify

onDrop

boolean onDrop(int barType)
               throws IOException,
                      AutomationException
Indicates if the drag-drop operation is valid.

Description

barType specifies which type of commandbar on which this ToolControl can be dropped. Use one of the esriCmdBarType constants.

Remarks

In most cases, a ToolControl should only be used on a toolbar.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

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