com.esri.arcgis.controls
Interface IToolbarPalette

All Superinterfaces:

Serializable

All Known Implementing Classes:

ToolbarPalette

public interface IToolbarPalette
extends Serializable

Provides access to members that control palette items.

Description

A ToolbarPalette supplies the implementation of a palette item that can host commands and tools. A ToolbarPalette cannot host ToolControl ToolbarMenu or MultiItem objects. A ToolbarPalette can either be hosted on the ToolbarControl or can appear as a popup palette.

A ToolbarPalette can be built in two ways. Firstly, an object implementing IPaletteDef can be passed to the IToolbarControl::AddItem method which creates a ToolbarPalette object and populates it from the palette definition. Secondly, the properties and methods on the IToolbarPalette interface can be used to build a palette.

Product Availability

Available with ArcGIS Engine.

Method Summary

int	addItem(Object item, int subType, int index) Adds an item to the ToolbarPalette.
int	find(Object item) Returns the index of the first item containing the given command.
IToolbarItem	getActiveItem() The palette item currently displayed on the ToolbarControl.
String	getCaption() The caption used by the ToolbarPalette.
ICommandPool	getCommandPool() The CommandPool used by the ToolbarPalette.
int	getCount() The number of items on the ToolbarPalette.
Object	getHook() The object that is passed as a hook to the OnCreate event of each item's command.
int	getIconSize() Indicates the size in pixels of icons displayed on the ToolbarPalette.
IToolbarItem	getItem(int index) Returns the item at the specified index from the ToolbarPalette.
Picture	getMouseIcon() Custom mouse icon used if MousePointer is 99.
int	getMousePointer() The mouse pointer displayed over the ToolbarPalette.
boolean	isAlignLeft() Indicates if the ToolbarPalette displays aligned to the left or right.
boolean	isCustomize() Indicates if the ToolbarPalette is in customize mode.
boolean	isThemedDrawing() Indicates if the ToolbarPalette uses themed drawing.
boolean	isToolTips() Indicates if the items tooltips are shown.
void	moveItem(int startIndex, int finalIndex) Moves an item from one index to another.
void	popupPalette(int x, int y, int hWndParent) Pops up the ToolbarPalette at the position specified.
void	remove(int index) Removes the item at the specified index from the ToolbarPalette.
void	removeAll() Removes all items from the ToolbarPalette.
void	setAlignLeft(boolean pVal) Indicates if the ToolbarPalette displays aligned to the left or right.
void	setCaption(String pVal) The caption used by the ToolbarPalette.
void	setCommandPoolByRef(ICommandPool ppCommandPool) The CommandPool used by the ToolbarPalette.
void	setCustomize(boolean newVal) Indicates if the ToolbarPalette is in customize mode.
void	setHook(Object hook) Sets the object that is passed as a hook to the OnCreate event of each item's command.
void	setIconSize(int pVal) Indicates the size in pixels of icons displayed on the ToolbarPalette.
void	setMouseIconByRef(Picture ppMouseIcon) Custom mouse icon used if MousePointer is 99.
void	setMousePointer(int pVal) The mouse pointer displayed over the ToolbarPalette.
void	setThemedDrawing(boolean pVal) Indicates if the ToolbarPalette uses themed drawing.
void	setToolTips(boolean pVal) Indicates if the items tooltips are shown.

Method Detail

setCommandPoolByRef

void setCommandPoolByRef(ICommandPool ppCommandPool)
                         throws IOException,
                                AutomationException

The CommandPool used by the ToolbarPalette.

Product Availability

Available with ArcGIS Engine.

Parameters:

ppCommandPool - A reference to a com.esri.arcgis.controls.ICommandPool (in)

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

getCommandPool

ICommandPool getCommandPool()
                            throws IOException,
                                   AutomationException

The CommandPool used by the ToolbarPalette.

Description

The CommandPool manages the collection of commands used by the ToolbarPalette. If the ToolbarPalette is added to the ToolbarControl the CommandPool will be shared with the IToolbarControl::CommandPool, otherwise a new CommandPool is created with a Hook property set to Nothing. If the ToolbarPalette is to be a popup palette, set the CommandPool to the IToolbarControl::CommandPool in order to share CommandPools.

Product Availability

Available with ArcGIS Engine.

Returns:

A reference to a com.esri.arcgis.controls.ICommandPool

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

popupPalette

void popupPalette(int x,
                  int y,
                  int hWndParent)
                  throws IOException,
                         AutomationException

Pops up the ToolbarPalette at the position specified.

Description

Creates a popup palette of the ToolbarPalette at the specified coordinates, supplied in pixels, relative to the top left of the parent window handle hWndParent .

The PopupPalette method is called automatically if the ToolbarPalette is hosted on the ToolbarControl, and the user has clicked on the palette item. In such cases the ToolbarPalette pops up just below the item.

If the ToolbarPalette is a standalone popup palette use the SetHook method, and optionally share the CommandPool with an existing one within the application.

Product Availability

Available with ArcGIS Engine.

Parameters:

x - The x (in)

y - The y (in)

hWndParent - The hWndParent (in)

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

setHook

void setHook(Object hook)
             throws IOException,
                    AutomationException

Sets the object that is passed as a hook to the OnCreate event of each item's command.

Description

The Hook is a shortcut to ICommandPoolEdit::Hook on the CommandPool. If the ToolbarPalette is an item on the ToolbarControl the Hook is shared and initialized by the ToolbarControl. If the ToolbarPalette is a standalone popup palette use the SetHook method, and optionally share the CommandPool with an existing one within the application.

Product Availability

Available with ArcGIS Engine.

Parameters:

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

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

getHook

Object getHook()
               throws IOException,
                      AutomationException

The object that is passed as a hook to the OnCreate event of each item's command.

Description

The Hook is a shortcut to ICommandPoolEdit::Hook on the CommandPool.

Product Availability

Available with ArcGIS Engine.

Returns:

A reference to another Automation Object (IDispatch)

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

moveItem

void moveItem(int startIndex,
              int finalIndex)
              throws IOException,
                     AutomationException

Moves an item from one index to another.

Description

Moves the item at the specified startIndex, to the position at the specified finalIndex. If no finalIndex is supplied the item is moved to the end of the ToolbarPalette.

Product Availability

Available with ArcGIS Engine.

Parameters:

startIndex - The startIndex (in)

finalIndex - The finalIndex (in)

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

addItem

int addItem(Object item,
            int subType,
            int index)
            throws IOException,
                   AutomationException

Adds an item to the ToolbarPalette.

Description

A ToolbarPalette supplies the implementation of a palette item that can host commands and tools. A ToolbarPalette cannot host ToolbarMenu, ToolControl or MultiItem objects.

Takes the specified command, palette or toolset and creates new items that are appended to the ToolbarPalette with their Command set, and returns the index of the first item added. Specifiy the command, palette or toolset as either a IUid, ProgID, ICommand, IPaletteDef or IToolBarDef. Any items within the IToolBarDef that are not supported will not be added to the ToolbarPalette.

Supply a subType when passing an ICommandSubType . If no subType is supplied and the command is passed as a IUid or ProgID then ICommandSubType::GetCount determines the number of item's to be added to the ToolbarPalette. A subType must be supplied when passing an ICommandSubType as an ICommand, or the method will fail. By default subType is 0.

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

Remarks

AddItem checks to see if the supplied command or the commands used by the palette already exists in the CommandPool used by the ToolbarPalette. 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 commands and menus as either Uid objects or ProgID's. Only supply commands as ICommand or IPaletteDef 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 command or palette as an ICommand or IPaletteDef object has the following limitation: Multiple instances of the same command can be added to the CommandPool , and each IToolbarItem::Command will point to a different command object.

Product Availability

Available with ArcGIS Engine.

Parameters:

item - A Variant (in)

subType - The subType (in, optional, pass 0 if not required)

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

Returns:

The insertIndex

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

remove

void remove(int index)
            throws IOException,
                   AutomationException

Removes the item at the specified index from the ToolbarPalette.

Description

Removes the item at the specified index from the ToolbarPalette. The item at the top of the palette as an index of 0.

Remarks

The Remove method will automatically find the IToolbarItem::Command in the CommandPool and decrement the ICommandPool::UsageCount by 1. If the ICommandPool::UsageCount reaches 0 the command will be released from the CommandPool.

Product Availability

Available with ArcGIS Engine.

Parameters:

index - The index (in)

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

removeAll

void removeAll()
               throws IOException,
                      AutomationException

Removes all items from the ToolbarPalette.

Description

This method removes all items from the ToolbarPalette.

Remarks

For each item removed the RemoveAll method will automatically find the IToolbarItem::Command in the CommandPool and decrement the ICommandPool::UsageCount by 1. If the ICommandPool::UsageCount reaches 0 the command will be released from the CommandPool.

Product Availability

Available with ArcGIS Engine.

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

setCaption

void setCaption(String pVal)
                throws IOException,
                       AutomationException

The caption used by the ToolbarPalette.

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.

getCaption

String getCaption()
                  throws IOException,
                         AutomationException

The caption used by the ToolbarPalette.

Description

The Caption of the ToolbarPalette. The Caption is displayed on the ToolbarControl when the IToolbarItem::Style is set to esriCommandStyleIconAndText.

Product Availability

Available with ArcGIS Engine.

Returns:

The pVal

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

getCount

int getCount()
             throws IOException,
                    AutomationException

The number of items on the ToolbarPalette.

Description

Returns the number of items on the ToolbarPalette.

Product Availability

Available with ArcGIS Engine.

Returns:

The pVal

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

getActiveItem

IToolbarItem getActiveItem()
                           throws IOException,
                                  AutomationException

The palette item currently displayed on the ToolbarControl.

Description

The item on the ToolbarPalette that is displayed on the ToolbarControl. By default this is the first item on the ToolbarPalette with an index of 0.

The ActiveItem will be automatically set to the IToolbarControl::CurrentTool when a tool on the ToolbarPalette is set as the current tool.

Product Availability

Available with ArcGIS Engine.

Returns:

A reference to a com.esri.arcgis.controls.IToolbarItem

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

isToolTips

boolean isToolTips()
                   throws IOException,
                          AutomationException

Indicates if the items tooltips are shown.

Description

Determines whether each item on the ToolbarPalette will display the ICommand::Tooltip property when the mouse cursor is held over the item. This property is true by default.

Product Availability

Available with ArcGIS Engine.

Returns:

The pVal

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

setToolTips

void setToolTips(boolean pVal)
                 throws IOException,
                        AutomationException

Indicates if the items tooltips are shown.

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.

getItem

IToolbarItem getItem(int index)
                     throws IOException,
                            AutomationException

Returns the item at the specified index from the ToolbarPalette.

Description

The property is used to access a particular item on the ToolbarPalette. The item at the top of the menu has an index of 0.

Remarks

To loop through a ToolbarPalette item collection use the GetItem method in conjunction with the Count property.

Product Availability

Available with ArcGIS Engine.

Parameters:

index - The index (in)

Returns:

A reference to a com.esri.arcgis.controls.IToolbarItem

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

find

int find(Object item)
         throws IOException,
                AutomationException

Returns the index of the first item containing the given command. Returns -1 if it is not found.

Description

Returns the index of the first item on the ToolbarPalette using the specified IUid, ProgID, ICommand. If the specified command cannot be found -1 is returned.

Remarks

To find an Item on the ToolbarPalette using a Command implementing ICommandSubType pass a UID with its SubType property set.

Product Availability

Available with ArcGIS Engine.

Parameters:

item - A Variant (in)

Returns:

The pVal

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 ToolbarPalette 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 ToolbarPalette is in customize mode.

Description

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

If the ToolbarPalette has also been added to the ToolbarControl, the ToolbarControl will override the Customize property with the IToolbarControl::Customize property, before the ToolbarPalette is displayed with the IToolbarPalette::PopupPalette method.

Use the left mouse button to select an item on the ToolbarPalette. Either drag the selected item to a new position on the ToolbarPalette as indicated by the black verticle line, or drag and drop the item off the ToolbarPalette 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 ToolbarPalette is in customize mode, new items can be added to the ToolbarPalette by either double clicking on an item in the CustomizeDialog or by dragging and dropping an item from the CustomizeDialog to the ToolbarPalette.

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 ToolbarPalette uses themed drawing.

Description

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

If the ToolbarPalette has also been added to the ToolbarControl, the ToolbarControl will override the ThemedDrawing property with the IToolbarControl2::ThemedDrawing property, before the ToolbarPalette is displayed with the IToolbarPalette::PopupPalette 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 ToolbarPalette 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 ToolbarPalette.

Description

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

If the ToolbarPalette has also been added to the ToolbarControl, the ToolbarControl will override the MousePointer property with the IToolbarControl::MousePointer property, before the ToolbarPalette is displayed with the IToolbarPalette::PopupPalette 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 ToolbarPalette.

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

Indicates the size in pixels of icons displayed on the ToolbarPalette.

Description

The size in pixels that each item on the ToolbarPalette 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 ToolbarPalette has also been added to the ToolbarControl, the ToolbarControl will override the IconSize property with the IToolbarControl2::IconSize property, before the ToolbarPalette is displayed with the IToolbarPalette::PopupPalette 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.

setIconSize

void setIconSize(int pVal)
                 throws IOException,
                        AutomationException

Indicates the size in pixels of icons displayed on the ToolbarPalette.

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 ToolbarPalette displays aligned to the left or right.

Description

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

If the ToolbarPalette has also been added to the ToolbarControl, the ToolbarControl will override the AlignLeft property with the IToolbarControl2::AlignLeft property, before the ToolbarPalette is displayed with the IToolbarPalette::PopupPalette method.

Remarks

If a ToolbarPalette 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 ToolbarPalette 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 IToolbarPalette::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 palettes.

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 ToolbarPalette 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 esriPointerCustom (99).

If the ToolbarPalette has also been added to the ToolbarControl, the ToolbarControl will override the MouseIcon property with the IToolbarControl::MouseIcon property, before the ToolbarPalette is displayed with the IToolbarPalette::PopupPalette 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.