com.esri.arcgis.controls
Interface ISymbologyControl

All Superinterfaces:

Serializable

All Known Implementing Classes:

ISymbologyControlProxy, SymbologyBean, SymbologyControl

public interface ISymbologyControl
extends Serializable

Provides access to members that control the SymbologyControl.

Description

The ISymbologyControl interface is a starting point for any tasks related to the SymbologyControl, such as setting general appearance, loading symbology from within server style files and setting the style class.

Product Availability

Available with ArcGIS Engine.

Method Summary

void	aboutBox() Displays a dialog of information about the SymbologyControl.
void	clear() Clears all symbols and files from the SymbologyControl.
boolean	esri_isEnabled() Indicates whether the SymbologyControl can respond to user generated events.
void	esri_setEnabled(boolean enabled) Indicates whether the SymbologyControl can respond to user generated events.
int	getAppearance() The appearance of the SymbologyControl.
int	getBackColor() Background color of the SymbologyControl.
int	getBorderStyle() The border style of the SymbologyControl.
Object	getCustomProperty() A property to associate data with the SymbologyControl.
int	getDisplayStyle() The display style of the SymbologyControl.
int	getHWnd() Handle to the window associated with the SymbologyControl.
int	getKeyIntercept() A property that specifies interception of key strokes that are normally handled by the container.
Picture	getMouseIcon() Custom mouse icon used if MousePointer is 99.
int	getMousePointer() The mouse pointer displayed over the SymbologyControl.
Object	getObject() A property that returns the underlying control.
int	getStyleClass() The style class used by the SymbologyControl.
ISymbologyStyleClass	getStyleClass2(int styleClass) Returns the specified style class from the SymbologyControl.
IStyleGalleryItem	hitTest(int x, int y) Returns the item at the specified x and y coordinates.
boolean	isShowContextMenu() Indicates if the SymbologyControl displays a context menu.
void	loadDesktopStyleFile(String fileName) Loads a desktop style file into the SymbologyControl.
void	loadStyleFile(String fileName) Loads a server style file into the SymbologyControl.
void	removeFile(String fileName) Removes a file from the SymbologyControl.
void	setAppearance(int appearance) The appearance of the SymbologyControl.
void	setBackColor(int backColor) Background color of the SymbologyControl.
void	setBorderStyle(int borderStyle) The border style of the SymbologyControl.
void	setCustomProperty(Object property) A property to associate data with the SymbologyControl.
void	setDisplayStyle(int style) The display style of the SymbologyControl.
void	setKeyIntercept(int intercept) A property that specifies interception of key strokes that are normally handled by the container.
void	setMouseIconByRef(Picture mouseIcon) Custom mouse icon used if MousePointer is 99.
void	setMousePointer(int mousePointer) The mouse pointer displayed over the SymbologyControl.
void	setShowContextMenu(boolean show) Indicates if the SymbologyControl displays a context menu.
void	setStyleClass(int styleClass) The style class used by the SymbologyControl.

Method Detail

setBackColor

void setBackColor(int backColor)
                  throws IOException,
                         AutomationException

Background color of the SymbologyControl.

Product Availability

Available with ArcGIS Engine.

Parameters:

backColor - The backColor (A COM typedef) (in)

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

getBackColor

int getBackColor()
                 throws IOException,
                        AutomationException

Background color of the SymbologyControl.

Description

Returns or sets the Background Color of the SymbologyControl. Internally the OLE_Color is stored as a long integer where the value may be calculated for any RGB combination as follows:

OLE_Color = (Red) + (Green * 256) + (Blue * 256 * 256)

Where Red, Green and Blue are Long Integers within the range 0 - 255.

Product Availability

Available with ArcGIS Engine.

Returns:

The backColor (A COM typedef)

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

setMousePointer

void setMousePointer(int mousePointer)
                     throws IOException,
                            AutomationException

The mouse pointer displayed over the SymbologyControl.

Product Availability

Available with ArcGIS Engine.

Parameters:

mousePointer - A com.esri.arcgis.controls.esriControlsMousePointer constant (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 SymbologyControl.

Description

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

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.

setMouseIconByRef

void setMouseIconByRef(Picture mouseIcon)
                       throws IOException,
                              AutomationException

Custom mouse icon used if MousePointer is 99.

Product Availability

Available with ArcGIS Engine.

Parameters:

mouseIcon - 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).

Remarks

In most development evironments the control's property pages can be used to load either a cursor (.cur) or icon (.ico) file. 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.

setBorderStyle

void setBorderStyle(int borderStyle)
                    throws IOException,
                           AutomationException

The border style of the SymbologyControl.

Product Availability

Available with ArcGIS Engine.

Parameters:

borderStyle - A com.esri.arcgis.controls.esriControlsBorderStyle constant (in)

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

getBorderStyle

int getBorderStyle()
                   throws IOException,
                          AutomationException

The border style of the SymbologyControl.

Description

Returns or sets the border style of a SymbologyControl. By default a border is drawn.

Product Availability

Available with ArcGIS Engine.

Returns:

A com.esri.arcgis.controls.esriControlsBorderStyle constant

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

esri_setEnabled

void esri_setEnabled(boolean enabled)
                     throws IOException,
                            AutomationException

Indicates whether the SymbologyControl can respond to user generated events.

Product Availability

Available with ArcGIS Engine.

Parameters:

enabled - The enabled (in)

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

esri_isEnabled

boolean esri_isEnabled()
                       throws IOException,
                              AutomationException

Indicates whether the SymbologyControl can respond to user generated events.

Product Availability

Available with ArcGIS Engine.

Returns:

The enabled

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

setAppearance

void setAppearance(int appearance)
                   throws IOException,
                          AutomationException

The appearance of the SymbologyControl.

Product Availability

Available with ArcGIS Engine.

Parameters:

appearance - A com.esri.arcgis.controls.esriControlsAppearance constant (in)

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

getAppearance

int getAppearance()
                  throws IOException,
                         AutomationException

The appearance of the SymbologyControl.

Description

Returns or sets the paint style of a SymbologyControl to either Flat or 3D. By default the appearance is flat.

Product Availability

Available with ArcGIS Engine.

Returns:

A com.esri.arcgis.controls.esriControlsAppearance constant

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

getHWnd

int getHWnd()
            throws IOException,
                   AutomationException

Handle to the window associated with the SymbologyControl.

Description

The operating environment identifies each window, form and control in an application by assigning it a handle, or hWnd. Many ArcObjects methods and Windows API calls require the hWnd as an argument.

Product Availability

Available with ArcGIS Engine.

Returns:

The hWnd

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

aboutBox

void aboutBox()
              throws IOException,
                     AutomationException

Displays a dialog of information about the SymbologyControl.

Description

The AboutBox method causes a modal dialog box to display on top of the SymbologyControl, containing information about the version and creation date of the SymbologyControl as well as listing relevant legal and copyright information from ESRI.

Product Availability

Available with ArcGIS Engine.

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

setStyleClass

void setStyleClass(int styleClass)
                   throws IOException,
                          AutomationException

The style class used by the SymbologyControl.

Product Availability

Available with ArcGIS Engine.

Parameters:

styleClass - A com.esri.arcgis.controls.esriSymbologyStyleClass constant (in)

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

getStyleClass

int getStyleClass()
                  throws IOException,
                         AutomationException

The style class used by the SymbologyControl.

Description

The SymbologyStyleClass currently displayed in the SymbologyControl. By default marker symbols are displayed.

The end user can set the StyleClass by interacting with the 'Style Class' context menu. The end user can display the 'Style Class' context menu by right clicking on the SymbologyControl when ShowContextMenu is true.

The OnStyleClassChanged event will fire when the StyleClass is set.

Remarks

The following style classes are only supported with an ArcGIS for Desktop installation:

~ esriStyleClassReferenceSystems
~ esriStyleClassMaplexLabels
~ esriStyleClassVectorizationSettings
~ esriStyleClassHatches

Product Availability

Available with ArcGIS Engine.

Returns:

A com.esri.arcgis.controls.esriSymbologyStyleClass constant

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

setDisplayStyle

void setDisplayStyle(int style)
                     throws IOException,
                            AutomationException

The display style of the SymbologyControl.

Product Availability

Available with ArcGIS Engine.

Parameters:

style - A com.esri.arcgis.controls.esriSymbologyDisplayStyle constant (in)

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

getDisplayStyle

int getDisplayStyle()
                    throws IOException,
                           AutomationException

The display style of the SymbologyControl.

Description

Returns or sets the style the items are displayed in the SymbologyControl. By default the DisplayStyle is Icon.

esriDisplayStyleIcon

esriDisplayStyleSmallIcon

esriDisplayStyleReport

esriDisplayStyleList

Product Availability

Available with ArcGIS Engine.

Returns:

A com.esri.arcgis.controls.esriSymbologyDisplayStyle constant

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

setKeyIntercept

void setKeyIntercept(int intercept)
                     throws IOException,
                            AutomationException

A property that specifies interception of key strokes that are normally handled by the container. When intercepted the OnKeyDown and OnKeyUp events will be called. This value can be a combined bit mask of esriKeyIntercept enum values.

Product Availability

Available with ArcGIS Engine.

Parameters:

intercept - The intercept (in)

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

getKeyIntercept

int getKeyIntercept()
                    throws IOException,
                           AutomationException

A property that specifies interception of key strokes that are normally handled by the container. When intercepted the OnKeyDown and OnKeyUp events will be called. This value can be a combined bit mask of esriKeyIntercept enum values.

Description

Returns or sets keys on the keyboard that will be intercepted by the SymbologyControl, triggering the OnKeyDown and OnKeyUp events when pressed. These keys are often hidden from the SymbologyControl by the development environment container. By default the KeyIntercept is set to esriKeyInterceptNone.

Many development environment containers use the up, down, left and right arrow keys to change control focus on a form. These keys can also be useful for navigating around the display. To intercept the arrow keys and the Tab key combine the enum values using a logical OR operation (esriKeyInterceptArrowKeys OR esriKeyInterceptTabKey, which is 1 OR 4 = 5).

Product Availability

Available with ArcGIS Engine.

Returns:

The intercept

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

getCustomProperty

Object getCustomProperty()
                         throws IOException,
                                AutomationException

A property to associate data with the SymbologyControl.

Description

Use the CustomProperty to associate any useful data with the SymbologyControl. This is similar to a 'Tag' property, and can be use to store strings, numbers and objects.

Product Availability

Available with ArcGIS Engine.

Returns:

A Variant

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

setCustomProperty

void setCustomProperty(Object property)
                       throws IOException,
                              AutomationException

A property to associate data with the SymbologyControl.

Product Availability

Available with ArcGIS Engine.

Parameters:

property - A Variant (in)

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

setShowContextMenu

void setShowContextMenu(boolean show)
                        throws IOException,
                               AutomationException

Indicates if the SymbologyControl displays a context menu.

Product Availability

Available with ArcGIS Engine.

Parameters:

show - The show (in)

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

isShowContextMenu

boolean isShowContextMenu()
                          throws IOException,
                                 AutomationException

Indicates if the SymbologyControl displays a context menu.

Description

Determines whether the 'Style Class' context menu will popup when the user right clicks on the control. This property is false by default.

The OnStyleClassChanged event will fire if the user interactively sets the StyleClass property using the 'Style Class' context menu.

Product Availability

Available with ArcGIS Engine.

Returns:

The show

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

getObject

Object getObject()
                 throws IOException,
                        AutomationException

A property that returns the underlying control. This can be used when the control is inside a wrapper object that has been added by a development environment.

Description

In some development environments it is not possible to query interface directly on the control to other COM interfaces, beacuse the control is contained within a wrapper object. To get the real control use the Object property.

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.

hitTest

IStyleGalleryItem hitTest(int x,
                          int y)
                          throws IOException,
                                 AutomationException

Returns the item at the specified x and y coordinates.

Description

Returns the item at the specified x and y coordinates (in pixels). If no item is found, returns Nothing.

Product Availability

Available with ArcGIS Engine.

Parameters:

x - The x (in)

y - The y (in)

Returns:

A reference to a com.esri.arcgis.display.IStyleGalleryItem

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

loadStyleFile

void loadStyleFile(String fileName)
                   throws IOException,
                          AutomationException

Loads a server style file into the SymbologyControl.

Description

Loads the contents of the specified server style file (*.ServerStyle) into the SymbologyControl. Each ServerStyleGalleryItem within the server style file is added to a SymbologyStyleClass based on its type. For example, a SimpleFillSymbol will be added to the esriStyleClassFillSymbols SymbologyStyleClass.

Items are 'demand loaded' to the end of a SymbologyStyleClass item collection. This is done to increase performance and means items are only loaded into a SymbologyStyleClass when it is the current StyleClass or when the SymbologyStyleClass is being accessed programmatically. To force items to be loaded into a SymbologyStyleClass when it is not the current StyleClass, use the ISymbologyStyleClass::Update method.

Passing the same server style file to the LoadStyleFile method multiple times within the lifetime of an application, causes the contents of the server style file to be re-loaded into the SymbologyControl.

Remarks

Server Styles are collections of symbols and map elements that are often grouped by functionality. For example, symbols and map elements used by the transportation industry maybe grouped into Transportation Server Style.

Server Styles are stored in files that have a .ServerStyle extension. Esri provides several styles for you to use out of the box. These styles are found under \\install_location\ArcGIS\Styles. You will find commonly used symbols and map elements in ESRI.ServerStyle, and more domain specific style items in relevantly named .ServerStyle files (for example, Transportation.ServerStyle).

A style is composed of several style items. These style items provide access to individual map elements and symbols. Style items are organized into style classes, which are types of style items. A style class may have several groups of items organized into categories. For example, Precipitation is a style item that belongs to the Color Ramps style class and the Default Ramps category.

Product Availability

Available with ArcGIS Engine.

Parameters:

fileName - The fileName (in)

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

loadDesktopStyleFile

void loadDesktopStyleFile(String fileName)
                          throws IOException,
                                 AutomationException

Loads a desktop style file into the SymbologyControl.

Description

Loads the contents of the specified style file (*.Style) into the SymbologyControl. Where possible always use the LoadStyleFile method to load the contents of server style files (*.ServerStyle) into the SymbologyControl, as style files are only supported with an ArcGIS for Desktop installation.

Each StyleGalleryItem within the style file is added to a SymbologyStyleClass based on its type. For example, a SimpleFillSymbol will be added to the esriStyleClassFillSymbols SymbologyStyleClass.

Items are 'demand loaded' to the end of a SymbologyStyleClass item collection. This is done to increase performance and means items are only loaded into a SymbologyStyleClass when it is the current StyleClass, or when the SymbologyStyleClass is being accessed programmatically. To force items to be loaded into a SymbologyStyleClass when it is not the current StyleClass, use the ISymbologyStyleClass::Update method.

Passing the same style file to the LoadDesktopStyleFile method multiple times within the lifetime of an application, causes the contents of the style file to reload into the SymbologyControl.

Remarks

A 'desktop' Style file is similar to a Server Style file, except is has a .Style extension rather than a .ServerStyle extension. Style files are available to ArcGIS for Desktop products only, whereas Server Style files are available to all ArcGIS products.

Product Availability

Available with ArcGIS Engine.

Parameters:

fileName - The fileName (in)

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

getStyleClass2

ISymbologyStyleClass getStyleClass2(int styleClass)
                                    throws IOException,
                                           AutomationException

Returns the specified style class from the SymbologyControl.

Product Availability

Available with ArcGIS Engine.

Parameters:

styleClass - A com.esri.arcgis.controls.esriSymbologyStyleClass constant (in)

Returns:

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

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

removeFile

void removeFile(String fileName)
                throws IOException,
                       AutomationException

Removes a file from the SymbologyControl.

Description

Removes the contents of the specified server style file (*.ServerStyle) or style file (*.Style) from the SymbologyControl. Corresponding items are removed from each SymbologyStyleClass.

Product Availability

Available with ArcGIS Engine.

Parameters:

fileName - The fileName (in)

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

clear

void clear()
           throws IOException,
                  AutomationException

Clears all symbols and files from the SymbologyControl.

Description

Clears all items from the SymbologyControl. Items are removed from each SymbologyStyleClass regardless of whether they were loaded using the LoadStyleFile, LoadDesktopStyleFile or ISymbologyStyleClass::AddItem methods.

Product Availability

Available with ArcGIS Engine.

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.