com.esri.arcgis.systemUI
Class IMultiItemProxy

java.lang.Object
  com.esri.arcgis.interop.Dispatch
      com.esri.arcgis.systemUI.IMultiItemProxy

All Implemented Interfaces:

IMultiItem, Externalizable, Serializable

public class IMultiItemProxy
extends com.esri.arcgis.interop.Dispatch
implements IMultiItem, 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, Serialized Form

Field Summary

boolean

noncastable

Fields inherited from class com.esri.arcgis.interop.Dispatch

DISPATCH_METHOD, DISPATCH_PROPERTYGET, DISPATCH_PROPERTYPUT, DISPATCH_PROPERTYPUTREF, objRef

Constructor Summary

	IMultiItemProxy()
	IMultiItemProxy(Object obj)
protected	IMultiItemProxy(Object obj, String iid)

Method Summary

void	addListener(String iidStr, Object theListener, Object theSource)
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.
void	removeListener(String iidStr, Object theListener)

Methods inherited from class com.esri.arcgis.interop.Dispatch

bindUsingMoniker, constructVtblPosTable, convertToNative, cookieForListener, createDispatch, createObjrefMonikerDisplayName, equals, getActiveObject, getActiveObject, getDefaultProperty, getDispatchIdOfName, getLastErrorCode, getMtsObjectContext, getObjRef, getPropertyByName, getPropertyByName, getVtblPos, hashCode, initDispatch, invoke, invokeMethodByName, invokeMethodByName, invokeMethodByName, invokePropertyGetByName, invokePropertyPutByName, invokePropertyPutByRefByName, isNativeMode, isObjRef, optimizedVtblInvoke, queryInterface, readExternal, release, setNativeMode, setPropertyByName, toString, vtblInvoke, writeExternal

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

noncastable

public boolean noncastable

Constructor Detail

IMultiItemProxy

public IMultiItemProxy()

IMultiItemProxy

public IMultiItemProxy(Object obj)
                throws IOException

Throws:

IOException

IMultiItemProxy

protected IMultiItemProxy(Object obj,
                          String iid)
                   throws IOException

Throws:

IOException

Method Detail

addListener

public void addListener(String iidStr,
                        Object theListener,
                        Object theSource)
                 throws IOException

Overrides:

addListener in class com.esri.arcgis.interop.Dispatch

Throws:

IOException

removeListener

public void removeListener(String iidStr,
                           Object theListener)
                    throws IOException

Overrides:

removeListener in class com.esri.arcgis.interop.Dispatch

Throws:

IOException

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.