com.esri.arcgis.controls
Interface IToolbarMenu2

All Superinterfaces:

IToolbarMenu, Serializable

All Known Implementing Classes:

ToolbarMenu

public interface IToolbarMenu2
extends IToolbarMenu, Serializable

Provides access to members that control ToolbarControl menu items.

Description

The IToolbarMenu2 interface provides additional members for tasks related to the apperance of standalone ToolbarMenu objects. The AddMultiItem method allows MultiItem objects to be added to both standalone ToolbarMenu's and ToollbarMenu's on a ToolbarControl.

Product Availability

Available with ArcGIS Engine.

Method Summary

int	addMultiItem(Object multiItem, int index, boolean beginGroup, int style) Adds a multi-item to the ToolbarMenu.
int	getIconSize() The size in pixels of icons displayed on the ToolbarMenu.
Picture	getMouseIcon() Custom mouse icon used if MousePointer is 99.
int	getMousePointer() The mouse pointer displayed over the ToolbarMenu.
boolean	isAlignLeft() Indicates if the ToolbarMenu displays aligned to the left or right.
boolean	isCustomize() Indicates if the ToolbarMenu is in customize mode.
boolean	isThemedDrawing() Indicates if the ToolbarMenu uses themed drawing.
void	setAlignLeft(boolean pVal) Indicates if the ToolbarMenu displays aligned to the left or right.
void	setCustomize(boolean newVal) Indicates if the ToolbarMenu is in customize mode.
void	setIconSize(int pVal) The size in pixels of icons displayed on the ToolbarMenu.
void	setMouseIconByRef(Picture ppMouseIcon) Custom mouse icon used if MousePointer is 99.
void	setMousePointer(int pVal) The mouse pointer displayed over the ToolbarMenu.
void	setThemedDrawing(boolean pVal) Indicates if the ToolbarMenu uses themed drawing.

Methods inherited from interface com.esri.arcgis.controls.IToolbarMenu

addItem, addSubMenu, find, getBitmap, getCaption, getCommandPool, getCount, getHook, getItem, getMenuDef, moveItem, popupMenu, remove, removeAll, setBitmap, setCaption, setCommandPoolByRef, setHook

Method Detail

addMultiItem

int addMultiItem(Object multiItem,
                 int index,
                 boolean beginGroup,
                 int style)
                 throws IOException,
                        AutomationException

Adds a multi-item to the ToolbarMenu.

Description

Takes the specified multi-item and creates new items that are appended to the ToolbarMenu with their Command set, and returns the index of the first item added. Specifiy the multi-item as either a IUID, ProgID, or IMultiItem. To add a sub menu use the AddSubMenu method.

Index determines the position on the ToolbarMenu that the item will be added to. By default this is -1 and represents the end of the ToolbarMenu.

beginGroup determines whether a separator will appear before the item. By default beginGroup is false.

Style determines the style of the item.

Remarks

AddMultiItem checks to see if the supplied command already exists in the CommandPool used by the ToolbarMenu. If the command does not already exist, it is created and added to the CommandPool with a ICommandPool::UsageCount of 1, and is set as the IToolbarItem::Command. If the command already exists in the CommandPool its ICommandPool::UsageCount is incremented by 1 and the command is set as the IToolbarItem::Command. The ICommand::OnCreate method will be called the first time a command is added to the CommandPool .

Where possible always supply multi-items as either Uid objects or ProgID's. Only supply multi-items as IMultiItem objects when a IUID or ProgID does not exist, and the class is compiled as part of the same project using the ToolbarControl. Passing a multi-item as IMultiItem object has the following limitation: Multiple instances of the same multi-item can be added to the CommandPool, and each IToolbarItem::Command will point to a different command object.

Product Availability

Available with ArcGIS Engine.

Parameters:

multiItem - A Variant (in)

index - The index (in, optional, pass -1 if not required)

beginGroup - The beginGroup (in, optional, pass false if not required)

style - A com.esri.arcgis.systemUI.esriCommandStyles constant (in, optional, pass 2 if not required)

Returns:

The itemIndex

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

setCustomize

void setCustomize(boolean newVal)
                  throws IOException,
                         AutomationException

Indicates if the ToolbarMenu is in customize mode.

Product Availability

Available with ArcGIS Engine.

Parameters:

newVal - The newVal (in)

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

isCustomize

boolean isCustomize()
                    throws IOException,
                           AutomationException

Indicates if the ToolbarMenu is in customize mode.

Description

Determines whether a ToolbarMenu is in customize mode at run time. The behavior of the ToolbarMenu changes when in customize mode. This property is false by default.

If the ToolbarMenu has also been added to the ToolbarControl, the ToolbarControl will override the Customize property with the IToolbarControl::Customize property, before the ToolbarMenu is displayed with the IToolbarMenu::PopupMenu method.

Use the left mouse button to select an item on the ToolbarMenu. Either drag the selected item to a new position on the ToolbarMenu as indicated by the black verticle line, or drag and drop the item off the ToolbarMenu to remove item.

Use the right mouse button to select an item and display the customize menu. Use the customize menu to either delete the item or set its IToolbarItem::Style, IToolbarItem::Group or IToolbarItem::GroupSpacing properties.

If the CustomizeDialog is displayed on the screen whilst the ToolbarMenu is in customize mode, new items can be added to the ToolbarMenu by either double clicking on an item in the CustomizeDialog or by dragging and dropping an item from the CustomizeDialog to the ToolbarMenu.

Product Availability

Available with ArcGIS Engine.

Returns:

The newVal

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

isThemedDrawing

boolean isThemedDrawing()
                        throws IOException,
                               AutomationException

Indicates if the ToolbarMenu uses themed drawing.

Description

Determines whether items on the ToolbarMenu display themselves using the current Windows XP theme. This property is false by default, and items display themselves on the ToolbarMenu with the Windows Classic look.

If the ToolbarMenu has also been added to the ToolbarControl, the ToolbarControl will override the ThemedDrawing property with the IToolbarControl2::ThemedDrawing property, before the ToolbarMenu is displayed with the IToolbarMenu::PopupMenu method.

Product Availability

Available with ArcGIS Engine.

Returns:

The pVal

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

setThemedDrawing

void setThemedDrawing(boolean pVal)
                      throws IOException,
                             AutomationException

Indicates if the ToolbarMenu uses themed drawing.

Product Availability

Available with ArcGIS Engine.

Parameters:

pVal - The pVal (in)

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

getMousePointer

int getMousePointer()
                    throws IOException,
                           AutomationException

The mouse pointer displayed over the ToolbarMenu.

Description

Use this property when you want to indicate changes in functionality as the mouse pointer passes over the ToolbarMenu. The esriPointerArrowHourglass setting (11) is useful for indicating that the user should wait for a process or to finish.

If the ToolbarMenu has also been added to the ToolbarControl, the ToolbarControl will override the MousePointer property with the IToolbarControl::MousePointer property, before the ToolbarMenu is displayed with the IToolbarMenu::PopupMenu method.

Product Availability

Available with ArcGIS Engine.

Returns:

A com.esri.arcgis.controls.esriControlsMousePointer constant

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

setMousePointer

void setMousePointer(int pVal)
                     throws IOException,
                            AutomationException

The mouse pointer displayed over the ToolbarMenu.

Product Availability

Available with ArcGIS Engine.

Parameters:

pVal - A com.esri.arcgis.controls.esriControlsMousePointer constant (in)

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

getIconSize

int getIconSize()
                throws IOException,
                       AutomationException

The size in pixels of icons displayed on the ToolbarMenu.

Description

The size in pixels that each item on the ToolbarMenu will display the ICommand::Bitmap property. By default bitmaps are stretched to a size of 16 x 16 pixels. The minimum IconSize allowed is 8.

If the ToolbarMenu has also been added to the ToolbarControl, the ToolbarControl will override the IconSize property with the IToolbarControl2::IconSize property, before the ToolbarMenu is displayed with the IToolbarMenu::PopupMenu method.

Remarks

IconSize may not affect the size of an item on the ToolbarControl that contains an object implementing IToolControl. Whether the ToolControl responds to the resize depends on its implementation.

Product Availability

Available with ArcGIS Engine.

Returns:

The pVal

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

setIconSize

void setIconSize(int pVal)
                 throws IOException,
                        AutomationException

The size in pixels of icons displayed on the ToolbarMenu.

Product Availability

Available with ArcGIS Engine.

Parameters:

pVal - The pVal (in)

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

isAlignLeft

boolean isAlignLeft()
                    throws IOException,
                           AutomationException

Indicates if the ToolbarMenu displays aligned to the left or right.

Description

Determines whether a ToolbarMenu (and any sub menus it contains) when displayed using the IToolbarMenu::PopupMenu method displays in a position aligned to the left of the users mouse click. This property is true by default.

If the ToolbarMenu has also been added to the ToolbarControl, the ToolbarControl will override the AlignLeft property with the IToolbarControl2::AlignLeft property, before the ToolbarMenu is displayed with the IToolbarMenu::PopupMenu method.

Remarks

If a ToolbarMenu is to popup in a position so close to edge of a screen display, that it will not be fully visible, the AlignLeft property will be ignored. The ToolbarMenu will popup aligned in a direction that will ensure it is fully visible.

AlignLeft does not affect the alignment of an ICommand::Caption or an IToolbarMenu::Caption displayed on a ToolbarItem. In order to change the direction text is displayed the RTL (right to left) display environment variable needs changing. The AlignLeft property will override any RTL (right to left) display environment variables that affect the position of drop down menus.

Product Availability

Available with ArcGIS Engine.

Returns:

The pVal

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

setAlignLeft

void setAlignLeft(boolean pVal)
                  throws IOException,
                         AutomationException

Indicates if the ToolbarMenu displays aligned to the left or right.

Product Availability

Available with ArcGIS Engine.

Parameters:

pVal - The pVal (in)

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

setMouseIconByRef

void setMouseIconByRef(Picture ppMouseIcon)
                       throws IOException,
                              AutomationException

Custom mouse icon used if MousePointer is 99.

Product Availability

Available with ArcGIS Engine.

Parameters:

ppMouseIcon - A reference to a com.esri.arcgis.support.ms.stdole.Picture (A com.esri.arcgis.support.ms.stdole.Picture COM typedef) (in)

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

getMouseIcon

Picture getMouseIcon()
                     throws IOException,
                            AutomationException

Custom mouse icon used if MousePointer is 99.

Description

The MouseIcon property provides a custom icon that is used when the MousePointer property is set to esriPointerArrowHourglass (99).

If the ToolbarMenu has also been added to the ToolbarControl, the ToolbarControl will override the MouseIcon property with the IToolbarControl::MouseIcon property, before the ToolbarMenu is displayed with the IToolbarMenu::PopupMenu method.

Remarks

In most development evironments a cursor (.cur) or icon (.ico) file can be loaded. A cursor contains a custom 'hotspot' location and can be any size. The 'hotspot' location for an icon file defaults to the center of the icon. This property cannot be used to load animated cursor (.ani) files.

To programatically create an object implementing IPictureDisp there is the win32 function OleLoadPicture or helper methods depending on the development environment.

Product Availability

Available with ArcGIS Engine.

Returns:

A reference to a com.esri.arcgis.support.ms.stdole.Picture (A com.esri.arcgis.support.ms.stdole.Picture COM typedef)

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.