DocumentMethods
ReferencesThis class exposes common operations that are performed on documents. Always consider using a method in this class instead of a more low-level one.
Methods
AddDependency
#Add a listen object with a specific dependency to this document at the given location.
Parameters:
| location (PointF) | Location for Listen object. |
| actions (ActionList = null) | Optional list of undo actions to populate. If null, an undo record will be added. |
Returns: Listen instance if successful.
AddDependency
#Add a dependency via an already constructed Listen object.
Parameters:
| location (PointF) | |
| listen (Listen) | |
| actions (ActionList = null) |
CanCreateChain
#Gets whether the specified objects can be turned into a chain.
Parameters:
| objects (IEnumerable<IDocumentObject>) | |
| whyNot (out string) |
CanCreateCluster
#Gets whether the specified objects can be turned into a cluster.
Parameters:
| objects (IEnumerable<IDocumentObject>) | |
| whyNot (out string) |
ChainObjects
#Attempt to chain a set of objects. Only consecutively selected components which are connected only to their neighbours can be chained.
Parameters:
| objects (IDocumentObject[]) | Objects to chain. |
| actions (ActionList = null) | Optional list of undo actions to populate. If null, an undo record will be added. |
Returns: Created chain or null.
ChainSelection
#Attempt to chain the current selection. Only consecutively selected components which are connected only to their neighbours can be chained.
Parameters:
| actions (ActionList = null) | Optional list of undo actions to populate. If null, an undo record will be added. |
ClusterObjects
#Parameters:
| objects (IDocumentObject[]) | |
| actions (ActionList = null) | Optional list of undo actions to populate. If null, an undo record will be added. |
ClusterSelection
#Move all selected objects into a cluster. A cluster operation requires that the selection topology is either singleton or convex. Note that this method does not cause a new solution, nor any viewport or canvas updates.
Parameters:
| actions (ActionList = null) | Optional list of undo actions to populate. If null, an undo record will be added. |
Returns: The created cluster or null if no cluster could be created.
CopySelection
#Perform a copy to clipboard operation on the selected objects.
Parameters:
| clipboard (ClipboardKind) | Clipboard type. This method does not allow for ClipboardKind.Instance clipboards. If you want instance clipboards, you must use your own DocumentIO instance. |
Returns: True if this method successfully changed the document state.
CutSelection
#Perform a cut to clipboard operation on the selected objects. Note that this method does not cause a new solution, nor any viewport or canvas updates.
Parameters:
| clipboard (ClipboardKind) | |
| actions (ActionList = null) |
Returns: True if this method successfully changed the document state.
DeleteObjectData
#Delete all persistent data in all specified objects.
Parameters:
| objects (IDocumentObject[] = null) | |
| actions (ActionList = null) |
Returns: Number of objects whose persistent data was deleted.
DeleteObjects
#public int DeleteObjects(IDocumentObject[] objects = null, WireEnds[] wires = null, ActionList actions = null)
Delete all specified objects. Note that deletion completely isolates objects from their neighbours. As such, the objects are not really fit to be inserted into a different document afterwards.
Parameters:
| objects (IDocumentObject[] = null) | |
| wires (WireEnds[] = null) | |
| actions (ActionList = null) |
Returns: Number of deleted objects.
DeleteSelection
#Delete all selected objects and wires.
Parameters:
| actions (ActionList = null) | Optional list of undo actions to populate. If null, an undo record will be added. |
Returns: Number of deleted objects and wires.
DeleteSelectionData
#Delete all persiustent data in all selected objects.
Parameters:
| actions (ActionList = null) | Optional list of undo actions to populate. If null, an undo record will be added. |
Returns: Number of object whose persistent data was deleted.
DeselectAll
#Deselect all objects. Note that this method does not cause a new solution, nor any viewport or canvas updates.
Returns: The number of objects whose states was changed.
DisableObjects
#Disables all specified objects. Note that this method does not cause a new solution, nor any viewport or canvas updates.
Parameters:
| objects (IDocumentObject[]) | |
| actions (ActionList = null) |
Returns: The number of objects whose states was changed.
DisableSelected
#Disables all objects in the current selection. Note that this method does not cause a new solution, nor any viewport or canvas updates.
Parameters:
| actions (ActionList = null) | Optional list of undo actions to populate. If null, an undo record will be added. |
Returns: The number of objects whose states was changed.
DropObject
#Add an undoable object at the specified location.
Parameters:
| obj ((Guid id, string init)) | Object id of object and optional initialisation code. |
| location (PointF) | Location cue. |
| actions (ActionList = null) | Optional list of undo actions to populate. If null, an undo record will be added. |
DropObject
#Add an undoable object at the specified location.
Parameters:
| obj (Guid) | Object id of object. |
| location (PointF) | Location cue. |
| actions (ActionList = null) | Optional list of undo actions to populate. If null, an undo record will be added. |
DropObject
#Add an existing undoable object at a specific location.
Parameters:
| obj (IDocumentObject) | Object instance to add. |
| location (PointF) | Location cue. |
| actions (ActionList = null) | Optional list of undo actions to populate. If null, an undo record will be added. |
DropObject
#public bool DropObject(IDocumentObject obj, PointF location, IParameter sourceCue, IParameter targetCue, ActionList actions = null)
Add an existing undoable object at a specific location.
Parameters:
| obj (IDocumentObject) | Object instance to add. |
| location (PointF) | Location cue. |
| sourceCue (IParameter) | If supplied and sensible, the new object will be connected to this source parameter. |
| targetCue (IParameter) | If supplied and sensible, the new object will be connected to this target parameter. |
| actions (ActionList = null) | Optional list of undo actions to populate. If null, an undo record will be added. |
DropSnippet
#Add an undoable snippet at a specific location.
Parameters:
| snippet (Snippet) | Snippet to add. |
| location (PointF) | Location cue. |
| actions (ActionList = null) | Optional list of undo actions to populate. If null, an undo record will be added. |
EnableObjects
#Enables all specified objects. Note that this method does not cause a new solution, nor any viewport or canvas updates.
Parameters:
| objects (IDocumentObject[]) | |
| actions (ActionList = null) |
Returns: The number of objects whose states was changed.
EnableSelected
#Enables all objects in the current selection. Note that this method does not cause a new solution, nor any viewport or canvas updates.
Parameters:
| actions (ActionList = null) | Optional list of undo actions to populate. If null, an undo record will be added. |
Returns: The number of objects whose states was changed.
GroupObjects
#public GroupObject GroupObjects(IDocumentObject[] objects, string name = null, Family? colour = null, ActionList actions = null)
Put all supplied objects into a group.
Parameters:
| objects (IDocumentObject[]) | |
| name (string = null) | |
| colour (OpenColor.Family? = null) | |
| actions (ActionList = null) |
Returns: A group containing the selected objects, or null if there was no selection.
GroupSelection
#public GroupObject GroupSelection(string name = null, Family? colour = null, ActionList actions = null)
Put all selected objects into a named group. Note that this method does not cause a new solution, nor any viewport or canvas updates.
Parameters:
| name (string = null) | Group name to assign. |
| colour (OpenColor.Family? = null) | Optional colour override. |
| actions (ActionList = null) | Optional list of undo actions to populate. If null, an undo record will be added. |
Returns: A group containing the selected objects, or null if there was no selection.
GrowSelection
#Grow the selection one level to the left and/or right. Note that this method does not cause a new solution, nor any viewport or canvas updates.
HideObjects
#Disables the display of all specified objects. Note that this method does not cause a new solution, nor any viewport or canvas updates.
Parameters:
| objects (IDocumentObject[]) | Objects to show. |
| actions (ActionList = null) | Optional list of undo actions to populate. If null, an undo record will be added. |
Returns: Number of objects whose state was changed.
HideSelected
#Disables the display of all objects in the current selection. Note that this method does not cause a new solution, nor any viewport or canvas updates.
Parameters:
| actions (ActionList = null) | Optional list of undo actions to populate. If null, an undo record will be added. |
Returns: The number of objects whose states was changed.
HideSelectedInputs
#Disables the display of all input parameters in the current selection. Note that this method does not cause a new solution, nor any viewport or canvas updates.
Parameters:
| actions (ActionList = null) | Optional list of undo actions to populate. If null, an undo record will be added. |
Returns: The number of inputs whose states was changed.
HideSelectedOutputs
#Disables the display of all output parameters in the current selection. Note that this method does not cause a new solution, nor any viewport or canvas updates.
Parameters:
| actions (ActionList = null) | Optional list of undo actions to populate. If null, an undo record will be added. |
Returns: The number of outputs whose states was changed.
InvertSelection
#Invert the selection. Note that this method does not cause a new solution, nor any viewport or canvas updates.
Returns: The number of objects whose states was changed.
IsolateObject
#public void IsolateObject(IDocumentObject obj, bool pins, bool inputs, bool outputs, ActionList actions = null)
Isolate an object. Note that this method modifies the document state without adding any undo record. If you wish to isolate objects in an undo-able fashion, you should use the Document.Methods class instead.
Parameters:
| obj (IDocumentObject) | |
| pins (bool) | |
| inputs (bool) | |
| outputs (bool) | |
| actions (ActionList = null) |
IsolateObject
#public void IsolateObject(IDocumentObject obj, bool pins, bool inputs, bool outputs, HashSet<Guid> omit, ActionList actions = null)
Isolate an object. Note that this method modifies the document state without adding any undo record. If you wish to isolate objects in an undo-able fashion, you should use the Document.Methods class instead.
Parameters:
| obj (IDocumentObject) | |
| pins (bool) | |
| inputs (bool) | |
| outputs (bool) | |
| omit (HashSet<Guid>) | |
| actions (ActionList = null) |
MakeRoom
#Make room in the document by inflating a rectangle from the to the dimensions and moving nearby objects away to avoid overlaps. Each displaced object retains, at most, the spacing it had to its (original) neighbour before the expansion; this is capped at the horizontal/vertical alignment gap from SnappingSettings.Current. Objects strictly to the left of
before are never moved.Parameters:
| before (RectangleF) | The initial space taken up by the growing space. |
| after (RectangleF) | The final grown space. |
| actions (ActionList = null) | Optional list of undo actions to populate. If null, an undo record will be added. |
MigrateObjects
#public Dictionary<Guid, Guid> MigrateObjects(IEnumerable<IDocumentObject> objects, PointF location, ActionList actions = null)
Add a list of objects (possibly from another document) to this document. The objects will be removed from the other document without any undo records. InstanceIDs will be changed if they conflict with objects already in this document.
Parameters:
| objects (IEnumerable<IDocumentObject>) | Object to add. |
| location (PointF) | Centre of compound bounds. |
| actions (ActionList = null) | Optional list of undo actions to populate. If null, an undo record will be added. |
Returns: A instance ID map encoding all instance ID changes.
MoveSelection
#Move all selected objects.
PasteFromClipboard
#public bool PasteFromClipboard(ClipboardKind clipboard, PasteBehaviour behaviour, ActionList actions = null)
Perform a paste from clipboard operation. Note that this method does not cause a new solution, nor any viewport or canvas updates.
Parameters:
| clipboard (ClipboardKind) | |
| behaviour (PasteBehaviour) | |
| actions (ActionList = null) |
Returns: True if this method successfully changed the document state.
PasteGrasshopper1XmlFromClipboard
#Try and paste the Grasshopper 1.0 xml archive on the OS clipboard into the document. Objects with dedicated migrators are converted, components without one become interop components, and the wires among the pasted objects are preserved.
Parameters:
| actions (ActionList = null) |
Returns: True on success, false on failure.
RestorePlaceholders
#Replace every placeholder in this document whose original object can now be deserialised, typically because a missing plugin was just installed. This includes the placeholders inside clusters hosted by this document, at any nesting depth. Placeholders which still fail to deserialise are left alone; they lose nothing and may succeed on a later attempt. Instance ids are stable across each swap, so the wires of surviving neighbours need no repair.
Parameters:
| actions (ActionList = null) | Optional list of undo actions to populate. If null, an undo record will be added. |
Returns: Number of restored objects, including those inside clusters.
SelectAll
#Select all objects. Note that this method does not cause a new solution, nor any viewport or canvas updates.
Returns: The number of objects whose states was changed.
SetColourOverrideObjects
#public int SetColourOverrideObjects(IDocumentObject[] objects, Colour colour = null, ActionList actions = null)
Set the display colour override from all specified objects. Note that this method does not cause a new solution, nor any viewport or canvas updates.
Parameters:
| objects (IDocumentObject[]) | Objects to override. |
| colour (Colour = null) | Colour override, or leave null to clear the colour override. |
| actions (ActionList = null) | Optional list of undo actions to populate. If null, an undo record will be added. |
Returns: The number of objects whose states was changed.
SetColourOverrideSelected
#Set the display colour override on all selected objects. Note that this method does not cause a new solution, nor any viewport or canvas updates.
Parameters:
| colour (Colour = null) | Colour override, or leave null to clear the colour override. |
| actions (ActionList = null) | Optional list of undo actions to populate. If null, an undo record will be added. |
Returns: The number of objects whose states was changed.
ShiftSelection
#Shift the selection one level to the left or right. Note that this method does not cause a new solution, nor any viewport or canvas updates.
Parameters:
| upstream (bool) | If true, sources to the current selection will be selected. |
Returns: The number of objects whose states was changed.
ShowDependencyGraph
#public void ShowDependencyGraph()
Show the dependency graph leading up to this document in a modal dialog. If this document has no dependencies this method returns immediately.
ShowObjects
#Enables the display of all specified objects. Note that this method does not cause a new solution, nor any viewport or canvas updates.
Parameters:
| objects (IDocumentObject[]) | Objects to show. |
| actions (ActionList = null) | Optional list of undo actions to populate. If null, an undo record will be added. |
Returns: Number of objects whose state was changed.
ShowSelected
#Enables the display of all objects in the current selection. Note that this method does not cause a new solution, nor any viewport or canvas updates.
Parameters:
| actions (ActionList = null) | Optional list of undo actions to populate. If null, an undo record will be added. |
Returns: The number of objects whose states was changed.
ShowSelectedInputs
#Enables the display of all input parameters in the current selection. Note that this method does not cause a new solution, nor any viewport or canvas updates.
Parameters:
| actions (ActionList = null) | Optional list of undo actions to populate. If null, an undo record will be added. |
Returns: The number of inputs whose states was changed.
ShowSelectedOutputs
#Enables the display of all output parameters in the current selection. Note that this method does not cause a new solution, nor any viewport or canvas updates.
Parameters:
| actions (ActionList = null) | Optional list of undo actions to populate. If null, an undo record will be added. |
Returns: The number of outputs whose states was changed.
SplitWire
#public bool SplitWire(IParameter source, IParameter target, string name, PointF location, out Shout shout, out Listen listen, ActionList actions = null)
Insert a Shout+Listen pair into an existing wire.
Parameters:
| source (IParameter) | Source parameter. |
| target (IParameter) | Target parameter. |
| name (string) | Name of shout object. |
| location (PointF) | Location for insertion. |
| shout (out Shout) | Newly created shout object. |
| listen (out Listen) | Newly created listen object. |
| actions (ActionList = null) | Optional list of undo actions to populate. If null, an undo record will be added. |
ToggleDisplayObjects
#Toggle the display of all specified objects. Note that this method does not cause a new solution, nor any viewport or canvas updates.
Parameters:
| objects (IDocumentObject[]) | Objects to show. |
| actions (ActionList = null) | Optional list of undo actions to populate. If null, an undo record will be added. |
Returns: Number of objects whose state was changed.
ToggleDisplaySelected
#Toggle the display of all objects in the current selection. Note that this method does not cause a new solution, nor any viewport or canvas updates.
Parameters:
| actions (ActionList = null) | Optional list of undo actions to populate. If null, an undo record will be added. |
Returns: The number of objects whose states was changed.