com.esri.arcgis.editor
Interface IEditor

All Superinterfaces:
Serializable
All Known Subinterfaces:
IEditor2, IEditor3
All Known Implementing Classes:
Editor, IEditor2Proxy, IEditor3Proxy, IEditorProxy

public interface IEditor
extends Serializable

Provides access to members that control the behavior of the editor.

Superseded By

IEditor3

When To Use

The IEditor interface is the main interface used to control the actions of the editor. For example, use the members in this interface to start and stop an edit session, create and manage edit operations, and set the editor's current task.

Product Availability

Available with ArcGIS Desktop.

See Also:
ISnapEnvironment, IEditProperties, IEditTask.activate(com.esri.arcgis.editor.IEditor, com.esri.arcgis.editor.IEditTask), IEditor, IEditLayers, IEditTask.deactivate(), IEditAttributeProperties, IEditEvents2, IEditTask.onFinishSketch(), IDatasetEdit, IMap, IDatasetEditInfo, IEditTask.onDeleteSketch(), IEditTask.getName(), IEditEvents, IApplication, Editor, IEditSketch

Method Summary
 void abortOperation()
          Aborts an edit operation.
 IGeometry createSearchShape(IPoint point)
          Creates a geometry using the point and the current search tolerance.
 void delayEvents(boolean delay)
          Used to batch operations together and minimize notifications.
 void enableUndoRedo(boolean enabled)
          Enable/disable the undo/redo capabilities.
 IExtension findExtension(IUID extensionID)
          Finds the extension given an id.
 IEditTask getCurrentTask()
          The current edit task.
 IScreenDisplay getDisplay()
          Reference to the current display.
 IEnumFeature getEditSelection()
          The selected features which are editable.
 int getEditState()
          The editor's current edit state.
 IWorkspace getEditWorkspace()
          Reference to the workspace being edited.
 IPoint getLocation()
          The last known location of the mouse.
 IMap getMap()
          Reference to the map being edited.
 IApplication getParent()
          Reference to the parent application.
 IWorkspace getScratchWorkspace()
          Reference to the editor's scratch workspace.
 IAnchorPoint getSelectionAnchor()
          The selection anchor point.
 int getSelectionCount()
          The number of selected features which are editable.
 IEditTask getTask(int index)
          An edit task by index.
 int getTaskCount()
          The number of edit tasks.
 boolean hasEdits()
          Indicates whether edits have been made during the session.
 void invertAgent(IPoint loc, int hdc)
          Draws the editor's snapping agent.
 void redoOperation()
          Redo an edit operation.
 IEnumFeature searchSelection(IPoint point)
          Searches the edit selection using the given location.
 void setCurrentTaskByRef(IEditTask task)
          The current edit task.
 void startEditing(IWorkspace workspace)
          Starts an edit session.
 void startOperation()
          Starts an edit operation.
 void stopEditing(boolean saveChanges)
          Stops an edit session.
 void stopOperation(String menuText)
          Stops an edit operation.
 void undoOperation()
          Undo an edit operation.
 

Method Detail

getParent

IApplication getParent()
                       throws IOException,
                              AutomationException
Reference to the parent application.

Description

Returns a reference to the application that created the editor.

Remarks

The Parent property provides a convenient way to get a reference to the application that created the Editor object. Edit tasks often use this property since they are only passed an IEditor reference and not an IApplication reference. For example, for an edit task to work with the Map's selection environment, the task will have to access properties belonging to IMXApplication .

Product Availability

Available with ArcGIS Desktop.

Supported Platforms

Windows

Returns:
A reference to a com.esri.arcgis.framework.IApplication
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
See Also:
IApplication, IEditor.getEditState()

getEditState

int getEditState()
                 throws IOException,
                        AutomationException
The editor's current edit state.

Description

The EditState property communicates the current state of the editor.

Remarks

EditState uses the esriEditState Constants enumeration to indicate the editor's current state. Valid states are:

esriStateNotEditing 0
esriStateEditing 1
esriStateEditingUnfocused 2


A good example of using this property is setting the Enabled property on ICommand .

Product Availability

Available with ArcGIS Desktop.

Supported Platforms

Windows

Returns:
A com.esri.arcgis.editor.esriEditState constant
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
See Also:
esriEditState

getMap

IMap getMap()
            throws IOException,
                   AutomationException
Reference to the map being edited.

Remarks

Multiple maps may be present within the application but only one may be edited at a time. When StartEditing is called, an edit session begins on the focus map. Users may change the focus map at any time; use this property to get a reference to the map being edited.

Product Availability

Available with ArcGIS Desktop.

Supported Platforms

Windows

Returns:
A reference to a com.esri.arcgis.carto.IMap
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
See Also:
IMap

getDisplay

IScreenDisplay getDisplay()
                          throws IOException,
                                 AutomationException
Reference to the current display.

Remarks

Operations such as drawing and coordinate conversion require a display object. The Display property conveniently hands back the display object that should be used for all edit operations. Which display object does this property give back?

When working in the data view there are several display objects: the map itself has one and so do each of the magnifier windows. IScreenDisplay is a special type of display that dispatches draw requests to all of the display objects available. In data view, the editor hands back a reference to IAppDisplay because it expects that you want to draw in all of the available views. For example, the editor's tools draw the edit sketch using IAppDisplay so that it will appear on the map as well as in all the magnifier windows.

In layout view there are again several display objects. Each map has its own display object and so does the layout object itself. In this case, the editor hands back the display object associated with the current edit map. In this case, the editor expects that you only want to draw things in the current edit map.

Product Availability

Available with ArcGIS Desktop.

Supported Platforms

Windows

Returns:
A reference to a com.esri.arcgis.display.IScreenDisplay
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

getEditWorkspace

IWorkspace getEditWorkspace()
                            throws IOException,
                                   AutomationException
Reference to the workspace being edited.

Remarks

The EditWorkspace property returns a reference to the workspace being edited, only one workspace is editable at a time. StartEditing sets this property as it has a required IWorkspace parameter. The following example shows one possible way to use the EditWorkspace property.

Product Availability

Available with ArcGIS Desktop.

Supported Platforms

Windows

Returns:
A reference to a com.esri.arcgis.geodatabase.IWorkspace
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

getScratchWorkspace

IWorkspace getScratchWorkspace()
                               throws IOException,
                                      AutomationException
Reference to the editor's scratch workspace.

Remarks

During an edit session, the editor creates and manages a temporary workspace where it stores information about features. For example, when resolving conflicts in SDE, the editor uses this workspace to store conflicting features. Similarly, when editing shapefiles, the editor writes feature delta tables to this workspace.

Product Availability

Available with ArcGIS Desktop.

Supported Platforms

Windows

Returns:
A reference to a com.esri.arcgis.geodatabase.IWorkspace
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

startEditing

void startEditing(IWorkspace workspace)
                  throws IOException,
                         AutomationException
Starts an edit session.

Description


Remarks

Data from multiple workspaces may be loaded into a single map. However, the editor can only edit one workspace at a time. For this reason, when calling StartEditing, you must specify the workspace you wish to edit and this workspace must be represented in the focus map. If no feature layers from the workspace are present in the focus map, StartEditing will fail.

StartEditing may also fail if the data is read-only or if it is non versioned SDE data.

Any references to features, cursors, or other geodatabase classes that you intend to use in the edit session should be acquired inside the edit session.

Product Availability

Available with ArcGIS Desktop.

Supported Platforms

Windows

Parameters:
workspace - A reference to a com.esri.arcgis.geodatabase.IWorkspace (in)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

stopEditing

void stopEditing(boolean saveChanges)
                 throws IOException,
                        AutomationException
Stops an edit session.

Remarks

Call this function to complete an edit session. The required Boolean parameter controls whether modifications made to features will be saved or discarded. To save your changes, use TRUE ; to discard them, use FALSE . StopEditing also clears all snap agents and unselects all selected features.

Product Availability

Available with ArcGIS Desktop.

Supported Platforms

Windows

Parameters:
saveChanges - The saveChanges (in)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

hasEdits

boolean hasEdits()
                 throws IOException,
                        AutomationException
Indicates whether edits have been made during the session.

Remarks

This property reports whether or not any edits have been made in the current edit session. For example, if this property returns False, then StopEditing can be called and passed the False parameter automatically; you do not have to ask the user if they want to save their edits because you know there are none.

 If Not pEditor.HasEdits Then


pEditor.StopEditing False
Else
'
'Code to prompt for Save Changes (Yes/No)
'
End If

Product Availability

Available with ArcGIS Desktop.

Supported Platforms

Windows

Returns:
The hasEdits
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

startOperation

void startOperation()
                    throws IOException,
                           AutomationException
Starts an edit operation.

Remarks

StartOperation and StopOperation mark the beginning and end of an edit operation. Edit operations provide undo/redo capabilites for any action or set of actions (additions, deletions, or modifications) taken on features.
Calling StopOperation creates an edit operation that is added to the top of the operation stack. The operation stack is how ArcMap implements Undo and Redo. When using StartOperation, proper handling of errors, including the use of AbortOperation, is neccessary.

All edits to features that participate in a Topology or Geometric Network must be bracketed within an edit operation.

If you call StartOperation when an edit operation has already been started, you will get an error.

When To Use

Use this to access information about the StartOperation object.

Product Availability

Available with ArcGIS Desktop.

Supported Platforms

Windows

Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
See Also:
IEditor.stopOperation(String)

abortOperation

void abortOperation()
                    throws IOException,
                           AutomationException
Aborts an edit operation.

Remarks

This should be used when you want to test if the results of your edit operation are valid before calling the StopOperation method. If the test you set up fails, you call AbortOperation instead of StopOperation. The changes made after StartOperation was called are undone, and nothing is added to the operation stack.

Product Availability

Available with ArcGIS Desktop.

Supported Platforms

Windows

Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

stopOperation

void stopOperation(String menuText)
                   throws IOException,
                          AutomationException
Stops an edit operation.

Remarks

StartOperation and StopOperation mark the beginning and end of an edit operation. Edit operations provide undo/redo capabilites for any action or set of actions (additions, deletions, or modifications) taken on features.
Calling StopOperation creates an edit operation that is added to the top of the operation stack. The operation stack is how ArcMap implements Undo and Redo. When using StopOperation, proper handling of errors, including the use of AbortOperation, is neccessary.

All edits to features that participate in a Topology or Geometric Network must be bracketed within an edit operation.

Product Availability

Available with ArcGIS Desktop.

Supported Platforms

Windows

Parameters:
menuText - The menuText (in)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
See Also:
IEditor.startOperation()

undoOperation

void undoOperation()
                   throws IOException,
                          AutomationException
Undo an edit operation.

Description

Rolls back all modifications made within an edit operation.

Remarks

Typically, UndoOperation and RedoOperation should be called within the context of an IOperation. Calling either of these directly, may corrupt the OperationStack. Instead, call Undo on IOperationStack to undo the last operation; this also moves the pointer down the stack, to the preceeding operation. UndoOperation is a shortcut to calling IWorkspaceEdit::UndoOperation on the current edit workspace.

Product Availability

Available with ArcGIS Desktop.

Supported Platforms

Windows

Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

redoOperation

void redoOperation()
                   throws IOException,
                          AutomationException
Redo an edit operation.

Remarks

Typically, UndoOperation and RedoOperation should be called within the context of an IOperation. Calling either of these directly, may corrupt the OperationStack. Instead, call Undo on IOperationStack to undo the last operation; this also moves the pointer down the stack, to the preceeding operation. RedoOperation is a shortcut to calling IWorkspaceEdit::RedoOperation on the current edit workspace.

Product Availability

Available with ArcGIS Desktop.

Supported Platforms

Windows

Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

enableUndoRedo

void enableUndoRedo(boolean enabled)
                    throws IOException,
                           AutomationException
Enable/disable the undo/redo capabilities.

Remarks

Use EnableUndoRedo to control whether edits to features can be rolled back. Edits made programmatically must be done within an edit operation in order to roll back an operation. If EnableUndoRedo is False then any changes are committed. To discard those edits the current edit session must be stopped and edits not saved. This method is a shortcut to calling IWorkspaceEdit::EnableUndoRedo on the current edit workspace.

Product Availability

Available with ArcGIS Desktop.

Supported Platforms

Windows

Parameters:
enabled - The enabled (in)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

delayEvents

void delayEvents(boolean delay)
                 throws IOException,
                        AutomationException
Used to batch operations together and minimize notifications.

Remarks

Use DelayEvents to control whether or not the editor triggers event notifications for each change in the editor's selection. For example, instead of the editor calling IEditEvents::OnSelectionChanged every time you select a feature, you may want the editor to only fire this event once--when the entire selection process is complete.
DelayEvents only affects OnSelectionChanged; all other events fire at the appropriate time.

Product Availability

Available with ArcGIS Desktop.

Supported Platforms

Windows

Parameters:
delay - The delay (in)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

getEditSelection

IEnumFeature getEditSelection()
                              throws IOException,
                                     AutomationException
The selected features which are editable.

Description

public void GetMapSelection()
{
//Get a reference to IApplication app in ICommand::OnCreate hook parameter.
IEditor sEditor = app.FindExtensionByName("ESRI Object Editor") as IEditor;
IEnumFeature enumFeature = sEditor.EditSelection;
enumFeature.Reset();
IFeature selFeature = enumFeature.Next();
for (int fCount = 0; fCount < sEditor.SelectionCount; fCount++)
{
IGeometry selGeometry = selFeature.Shape;
'Put code here to do something with the geometry
System.Windows.Forms.MessageBox.Show(selGeometry.GeometryType);
selFeature = enumFeature.Next;
}
}

Remarks

This property returns all of the currently selected features that belong to editable layers. Use this property when creating an editing tool or command that works with the current selection.

Product Availability

Available with ArcGIS Desktop.

Supported Platforms

Windows

Returns:
A reference to a com.esri.arcgis.geodatabase.IEnumFeature
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

getSelectionCount

int getSelectionCount()
                      throws IOException,
                             AutomationException
The number of selected features which are editable.

Remarks

This property returns the Map's total number of selected features belonging to editable layers.

Product Availability

Available with ArcGIS Desktop.

Supported Platforms

Windows

Returns:
The selection
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

findExtension

IExtension findExtension(IUID extensionID)
                         throws IOException,
                                AutomationException
Finds the extension given an id.

Remarks

The FindExtension function provides a hook to the editor's extension objects. All of the extension objects are automatically created/instantiated when the Editor CoClass is created; use FindExtension to get a reference to them.

For example, the AttributeWindow Class is an editor extension. To get a reference to the IAttributeWindow interface use the FindExtension function passing in the GUID of the AttributeWindow Class.

Product Availability

Available with ArcGIS Desktop.

Supported Platforms

Windows

Parameters:
extensionID - A reference to a com.esri.arcgis.system.IUID (in)
Returns:
A reference to a com.esri.arcgis.system.IExtension
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

getTaskCount

int getTaskCount()
                 throws IOException,
                        AutomationException
The number of edit tasks.

Remarks

This property returns the number of tasks the editor currently has loaded. When changing the current task programmatically, use TaskCount with Task and IEditTask::Name to loop through all available tasks and find the correct one. Or alternatively you can use the edit task's unique name and IEditTaskSearch::TaskByUniqueName to find the desired edit task.

Product Availability

Available with ArcGIS Desktop.

Supported Platforms

Windows

Returns:
The count
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
See Also:
IEditor.getTask(int), IEditor.getCurrentTask(), IEditTask.activate(com.esri.arcgis.editor.IEditor, com.esri.arcgis.editor.IEditTask), IEditor.setCurrentTaskByRef(com.esri.arcgis.editor.IEditTask), IEditTask.deactivate(), IEditTask.onFinishSketch(), IEditTask.onDeleteSketch(), IEditTask.getName()

getTask

IEditTask getTask(int index)
                  throws IOException,
                         AutomationException
An edit task by index.

Product Availability

Available with ArcGIS Desktop.

Parameters:
index - The index (in)
Returns:
A reference to a com.esri.arcgis.editor.IEditTask
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

setCurrentTaskByRef

void setCurrentTaskByRef(IEditTask task)
                         throws IOException,
                                AutomationException
The current edit task.

Remarks

Use this property to check or change the editor's current task. After an edit sketch is completed, the current task uses the geometry stored in IEditSketch to perform some action. IEditEvents::OnCurrentTaskChanged is called whenever the editor's current task is changed.

Product Availability

Available with ArcGIS Desktop.

Supported Platforms

Windows

Parameters:
task - A reference to a com.esri.arcgis.editor.IEditTask (in)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
See Also:
IEditor.getTask(int), IEditTask.activate(com.esri.arcgis.editor.IEditor, com.esri.arcgis.editor.IEditTask), IEditTask.deactivate(), IEditTask.onFinishSketch(), IEditTask.onDeleteSketch(), IEditTask.getName(), IEditor.getTaskCount()

getCurrentTask

IEditTask getCurrentTask()
                         throws IOException,
                                AutomationException
The current edit task.

Remarks

Use this property to check or change the editor's current task. After an edit sketch is completed, the current task uses the geometry stored in IEditSketch to perform some action. IEditEvents::OnCurrentTaskChanged is called whenever the editor's current task is changed.

Product Availability

Available with ArcGIS Desktop.

Supported Platforms

Windows

Returns:
A reference to a com.esri.arcgis.editor.IEditTask
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
See Also:
IEditor.getTask(int), IEditTask.activate(com.esri.arcgis.editor.IEditor, com.esri.arcgis.editor.IEditTask), IEditTask.deactivate(), IEditTask.onFinishSketch(), IEditTask.onDeleteSketch(), IEditTask.getName(), IEditor.getTaskCount()

createSearchShape

IGeometry createSearchShape(IPoint point)
                            throws IOException,
                                   AutomationException
Creates a geometry using the point and the current search tolerance.

Remarks

CreateSearchShape is a convenient function that helps you select features that fall near a specific point. This function creates a small geometry around the required point parameter that can then be used by a spatial filter to select features. The size of the geometry created around the point is controlled by the focus map's search tolerance (IMxDocument::SearchTolerancePixels).
The returned IGeometry reference is to a new Envelope object.

Product Availability

Available with ArcGIS Desktop.

Supported Platforms

Windows

Parameters:
point - A reference to a com.esri.arcgis.geometry.IPoint (in)
Returns:
A reference to a com.esri.arcgis.geometry.IGeometry
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

searchSelection

IEnumFeature searchSelection(IPoint point)
                             throws IOException,
                                    AutomationException
Searches the edit selection using the given location.

Remarks

SearchSelection is a convenient method that creates a sub-selection of the Map's currently selected features. The sub-selection contains only features that are within close proximity to the input point location. Use SearchSelection when you have a large selection (≥ 25 features) and you want to search for a selected feature that is near a specific point location. For example, use this method when checking if the mouse is positioned over a selected feature. It is considerably quicker to interrogate only features that are near the cursor than to look at all selected features in the Map. Note: with small Map selections (< 25 features), the reverse is true; there is no need to call SearchSelection to reduce the selection as it is already small and likely cached in memory.

Product Availability

Available with ArcGIS Desktop.

Supported Platforms

Windows

Parameters:
point - A reference to a com.esri.arcgis.geometry.IPoint (in)
Returns:
A reference to a com.esri.arcgis.geodatabase.IEnumFeature
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

invertAgent

void invertAgent(IPoint loc,
                 int hdc)
                 throws IOException,
                        AutomationException
Draws the editor's snapping agent.

Remarks

Call InvertAgent to draw the editor's agent at the location specified by the required point parameter. A device handle is also required. The agent is typically used to display the mouse location or a location based on a constraint when adding points to an edit sketch. Call InvertAgent a second time with the same point parameter to draw over and erase the previous agent.

You can change the editor's snap agent symbol using IEditProperties::SnapSymbol .

When To Use



Product Availability

Available with ArcGIS Desktop.

Supported Platforms

Windows

Parameters:
loc - A reference to a com.esri.arcgis.geometry.IPoint (in)
hdc - The hdc (A COM typedef) (in)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
See Also:
IEditProperties.getSnapSymbol()

getSelectionAnchor

IAnchorPoint getSelectionAnchor()
                                throws IOException,
                                       AutomationException
The selection anchor point.

Remarks

Editing tools that require the location of the selection anchor can conveniently get it from the SelectionAnchor property. For example, the editor's Rotate Tool rotates features around the selection anchor.

Product Availability

Available with ArcGIS Desktop.

Supported Platforms

Windows

Returns:
A reference to a com.esri.arcgis.display.IAnchorPoint
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
See Also:
IEditor2.getAuxiliarySelectionAnchor()

getLocation

IPoint getLocation()
                   throws IOException,
                          AutomationException
The last known location of the mouse.

Remarks

This property is set when you right-click on the edit sketch. Once a point has been stored in this property, it remains there until the next time you right-click on the edit sketch.

Use this property when creating custom commands in the sketch context menu that require a point location to perform some operation. For example, the 'Insert Vertex' command use the location property to determine where to add the new vertex.

If you need the location of the sketch tool for a command in the sketch tool context menu, use the ISketchTool::Location property.

Product Availability

Available with ArcGIS Desktop.

Supported Platforms

Windows

Returns:
A reference to a com.esri.arcgis.geometry.IPoint
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
See Also:
ISketchTool, esriSketchConstraint