com.esri.arcgis.systemUI
Interface IMultiItem

All Superinterfaces:

Serializable

All Known Implementing Classes:

ControlsMapBookmarksMultiItem, IMultiItemProxy, MultiItem, RasterTableShowMultiItem

public interface IMultiItem
extends Serializable

Provides access to members that define a multiItem.

Description

A MultiItem can be used when items on a menu can't be determined prior to runtime or the items need to be modified based on the state of the system. A good example of this is the menu items at the bottom of the File menu representing the most recently used files. The IMultiItem interface allows a single object to act like several adjacent menu items. During runtime, the framework will notify MultiItem commands when their host menu is about to be shown. At this point, all the commands implementing IMultiItem can query the system to determine how many items should be represented and how each should appear.

When To Use

If you want to create a custom multiItem, you must implement the IMultiItem interface in your class code. This interface allows you to assign properties such as caption, bitmap, enabled state, and checked state to each item. It also defines what action happens when an item in the multiItem is clicked. You do not implement the ICommand interface when creating a MultiItem.

You may also want to implement the IMultiItemEx interface in order to assign message, helpfile and helpcontextid properties to each item.

You should also create a custom menu with your custom multiItem on it since multiItems can only appear on menus. MultiItems are never added to the commands list in the Customize dialog so you need to use a custom menu to provide access to the multiItem in the application.

Product Availability

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

See Also:

IMenuDef

Method Summary

String	getCaption() The caption of the multiItem.
int	getHelpContextID() The help context ID associated with this multiItem.
String	getHelpFile() The name of the help file associated with this multiItem.
int	getItemBitmap(int index) The bitmap for the item at the specified index.
String	getItemCaption(int index) The caption of the item at the specified index.
String	getMessage() The status bar message for all items on the multiItem.
String	getName() The name of the multiItem.
boolean	isItemChecked(int index) Indicates if item at the specified index is checked.
boolean	isItemEnabled(int index) Indicates if the item at the specified index is enabled.
void	onItemClick(int index) Occurs when the item at the specified index is clicked.
int	onPopup(Object hook) Occurs when the menu that contains the multiItem is about to be displayed.

Method Detail

getName

String getName()
               throws IOException,
                      AutomationException

The name of the multiItem.

Remarks

The Name property of a multiItem is a programmatic identifying name string. By convention, a multiItem's name should include its category name. The format of the Name string should be <Category>_<Caption>.

When implementing IMultiItem to create a custom multiItem, use the Name property to set the internal name of this multiItem.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Returns:

The name

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

getCaption

String getCaption()
                  throws IOException,
                         AutomationException

The caption of the multiItem.

Remarks

When implementing IMultiItem to create a custom multiItem, use the Caption property to set the caption of the multiItem.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Returns:

The name

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

getMessage

String getMessage()
                  throws IOException,
                         AutomationException

The status bar message for all items on the multiItem.

Remarks

When implementing IMultiItem to create a custom multiItem, use the Message property to set the message string that appears in the statusbar of the application when the mouse passes over any of the items in this multiItem.

This assigns the same message to all of the items in the MultiItem. If you want a separate message for each item, then you should use the IMultiItem.ItemMessage property.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Returns:

The message

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

getHelpFile

String getHelpFile()
                   throws IOException,
                          AutomationException

The name of the help file associated with this multiItem.

Description

The HelpFile property is used to specify the name of the help file that contains the context sensitive help topic for your custom MulitItem.

This assigns the same HelpFile to all of the items in the MulitItem. If you want each item to have a separate HelpFile then you should use the IMultiItemEx.ItemHelpFile property instead.

Remarks

If you set both the HelpFile and HelpContextID properties, then an end-user of your multiItem can use the "What's This?" command in ArcMap or ArcCatalog to get help on your commands. Note, if you want your What's This help to look and behave the same as the standard ArcGIS commands, then you should create a WinHelp file instead of a HTMLHelp file.

If you have a WinHelp file (*.hlp), set IMultiItemHelpFile to the name of the help file containing the topic that describes the multiItem and set IMultiItem_HelpContextID to the topic ID's mapped numeric value. The topic ID is the so-called # footnote in the RTF file you include in your WinHelp file. You can use Help Workshop to add this numeric value by opening the HPJ file, clicking Map and then clicking Add (to add the mapping for an individual topic). See the help topic "To enable a program to display an individual Help topic" in the Help Workshop's help file.

If you have an HTMLHelp file (*.chm) the procedure is similar; specifiy the
.chm file as IMultiItem_HelpFile and the mapped numeric value as
IMultiItem_HelpContextID. Popup topics are problematic with HTMLHelp, but the help topic will display in a default or user-defined window.

As part of your deployment strategy register the name of the WinHelp file (*.hlp) as a new string value in:
HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\Help

Or if you're working with a HTMLHelp file (*.chm) register its name as a new string value in:
HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\HTMLHelp.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Returns:

The helpFile

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

getHelpContextID

int getHelpContextID()
                     throws IOException,
                            AutomationException

The help context ID associated with this multiItem.

Description

The HelpContextID property is used to specify the mapped numeric value of the topic ID of the context sensitive help topic for your custom MulitItem. Specify the name of your help file in the HelpFile property.

This assigns the same HelpContextID to all of the items in the MulitItem. If you want each item to have a separate HelpContextID then you should use the IMultiItemEx.ItemHelpContextID property instead.

Remarks

If you set both the HelpFile and HelpContextID properties, then an end-user of your multiItem can use the "What's This?" command in ArcMap or ArcCatalog to get help on your commands. Note, if you want your What's This help to look and behave the same as the standard ArcGIS commands, then you should create a WinHelp file instead of a HTMLHelp file.

If you have a WinHelp file (*.hlp), set IMultiItemHelpFile to the name of the help file containing the topic that describes the multiItem and set IMultiItem_HelpContextID to the topic ID's mapped numeric value. The topic ID is the so-called # footnote in the RTF file you include in your WinHelp file. You can use Help Workshop to add this numeric value by opening the HPJ file, clicking Map and then clicking Add (to add the mapping for an individual topic). See the help topic "To enable a program to display an individual Help topic" in the Help Workshop's help file.

If you have an HTMLHelp file (*.chm) the procedure is similar; specifiy the
.chm file as IMultiItem_HelpFile and the mapped numeric value as
IMultiItem_HelpContextID. Popup topics are problematic with HTMLHelp, but the help topic will display in a default or user-defined window.

As part of your deployment strategy register the name of the WinHelp file (*.hlp) as a new string value in:
HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\Help

Or if you're working with a HTMLHelp file (*.chm) register its name as a new string value in:
HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\HTMLHelp.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Returns:

The iD

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

onPopup

int onPopup(Object hook)
            throws IOException,
                   AutomationException

Occurs when the menu that contains the multiItem is about to be displayed.

Description

hook is a reference to an IApplication object.

Remarks

The OnPopup method occurs just before the menu containing the MultiItem is displayed. OnPopup provides a hook to the application object that instantiated the MultiItem and is also used to set the number of items in the MultiItem.

When implementing IMultiItem to create a custom multiItem, use the OnPopup method to get a hook to the application. Also, write code to determine how many items will make up this multiItem and return that number using IMultiItem_OnPopup.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Parameters:

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

Returns:

The itemCount

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

See Also:

IApplication

getItemCaption

String getItemCaption(int index)
                      throws IOException,
                             AutomationException

The caption of the item at the specified index.

Product Availability

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

Parameters:

index - The index (in)

Returns:

The itemName

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

getItemBitmap

int getItemBitmap(int index)
                  throws IOException,
                         AutomationException

The bitmap for the item at the specified index.

Product Availability

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

Parameters:

index - The index (in)

Returns:

The bitmap (A COM typedef)

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

onItemClick

void onItemClick(int index)
                 throws IOException,
                        AutomationException

Occurs when the item at the specified index is clicked.

Description

Index specifies the index of the item in the multiItem that was clicked. An Index of -1 means that no item was clicked.

Remarks

When implementing IMultiItem to create a custom multiItem, write code in the OnItemClick method to perform the action when an item in the multiItem is clicked. The index number of the clicked item is passed into this function. If no item was clicked, -1 is passed into this function.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Parameters:

index - The index (in)

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

isItemChecked

boolean isItemChecked(int index)
                      throws IOException,
                             AutomationException

Indicates if item at the specified index is checked.

Product Availability

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

Parameters:

index - The index (in)

Returns:

The bChecked

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

isItemEnabled

boolean isItemEnabled(int index)
                      throws IOException,
                             AutomationException

Indicates if the item at the specified index is enabled.

Product Availability

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

Parameters:

index - The index (in)

Returns:

The bEnabled

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.