com.esri.arcgis.framework
Class MultiItem

java.lang.Object
  com.esri.arcgis.framework.MultiItem

All Implemented Interfaces:

com.esri.arcgis.interop.RemoteObjRef, IMultiItem, Serializable

public class MultiItem
extends Object
implements com.esri.arcgis.interop.RemoteObjRef, IMultiItem

MultiItem CoType.

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.

Product Availability

Available with ArcGIS Desktop.

Supported Platforms

Windows

See Also:

Serialized Form

Constructor Summary

MultiItem(Object obj)
Construct a MultiItem using a reference to such an object returned from ArcGIS Engine or Server.

Method Summary

boolean	equals(Object o) Compare this object with another
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.
int	hashCode() the hashcode for this object
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.

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

MultiItem

public MultiItem(Object obj)
          throws IOException

Construct a MultiItem using a reference to such an object returned from ArcGIS Engine or Server. This is semantically equivalent to casting obj to MultiItem.
Casting to this class from the return value of a method will not work, as this class represents an abstract class in ArcObjects.
*
MultiItem o = (MultiItem)obj; // will not work

MultiItem o = new MultiItem(obj); // Use this constructor instead
* @param obj an object returned from ArcGIS Engine or Server

Throws:

IOException - if there are interop problems MultiItem theMultiItem = (MultiItem) obj;

Method Detail

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

getName

public 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

Specified by:

getName in interface IMultiItem

Returns:

The name

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

getCaption

public 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

Specified by:

getCaption in interface IMultiItem

Returns:

The name

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

getMessage

public 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

Specified by:

getMessage in interface IMultiItem

Returns:

The message

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

getHelpFile

public 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

Specified by:

getHelpFile in interface IMultiItem

Returns:

The helpFile

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

getHelpContextID

public 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

Specified by:

getHelpContextID in interface IMultiItem

Returns:

The iD

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

onPopup

public 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

Specified by:

onPopup in interface IMultiItem

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

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

Specified by:

getItemCaption in interface IMultiItem

Parameters:

index - The index (in)

Returns:

The itemName

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

getItemBitmap

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

Specified by:

getItemBitmap in interface IMultiItem

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

public 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

Specified by:

onItemClick in interface IMultiItem

Parameters:

index - The index (in)

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

isItemChecked

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

Specified by:

isItemChecked in interface IMultiItem

Parameters:

index - The index (in)

Returns:

The bChecked

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

isItemEnabled

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

Specified by:

isItemEnabled in interface IMultiItem

Parameters:

index - The index (in)

Returns:

The bEnabled

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.