The Grasshopper Cluster object.
Constructors
GH_Cluster
#public GH_Cluster()
Fields
m_attributes
protected IGH_Attributes m_attributes
Properties
Attributes
Gets or sets the attributes that are associated with this object. Only set custom attributes if you know what you are doing.
Implements: Attributes
Category
Gets or sets the Category in which this object belongs. If HasCategory() returns false, this field has no meaning.
Implements: Category
DataComparison
Gets or sets the data matching algorithm for this component
Implements: DataComparison
Description
Gets or sets the description of the object. This field typically remains fixed during the lifetime of an object.
Implements: Description
DocumentId
#Gets or sets the ID of the internal cluster document. If there is no internal document, the ID returned will be Guid.Empty. Do not use the setter unless you know what you are doing.
EnableCaching
#Gets whether cluster caching is enabled. This is an application wide setting modified by the "TestClusterCache" command. It's primary aim is to reduce computational overhead on Rhino Compute servers.
FilePath
#Gets the filepath that points to the cluster file. If this cluster does not reference a file, the FilePath will be null.
Implements: HasCategory
HasSubCategory
Gets whether or not the SubCategory field has been set.
Implements: HasSubCategory
HelpDescription
Override this method if you want the help topic content to be more than the Component description.
Icon_24x24
public Bitmap Icon_24x24 { get; }
The icon associated with this object.
Implements: Icon_24x24
Icon_24x24_Locked
public Bitmap Icon_24x24_Locked { get; }
The greyscale icon of this object.
Implements: Icon_24x24_Locked
IconCapableUI
By default the NickName menu item supports the Icon Mode override toggle. If your UI is not capable of displaying icons, then override this property and return False.
IconDisplayMode
Gets the current display mode of the object.
Implements: IconDisplayMode
InConstructor
Gets the constructor flag for this instance. If InConstructor = True, it means the component is still registering parameters and the layout is not yet complete.
Implements: InConstructor
InstanceDescription
Overrides: GH_InstanceDescription.InstanceDescription
Implements: InstanceGuid
Internal_Icon_24x24
[EditorBrowsable(EditorBrowsableState.Never)]
[Browsable(false)]
protected virtual Bitmap Internal_Icon_24x24 { get; }
Override this function to supply a custom icon. The result of this property is cached, so don't worry if icon retrieval is not very fast.
IsDataProvider
Components are never Data providers. Only the output parameters can be considered to be providers.
Overrides: GH_ActiveObject.IsDataProvider
IsValidPrincipalParameterIndex
Gets whether the MasterParameterIndex property identifies a valid parameter.
Implements: IsValidMasterParameterIndex
Keywords
Gets a list of additional keywords that describe the object. Typically this list is empty but you can override this property to aid in object searches.
Implements: Keywords
Message
Gets or sets a custom message to be displayed underneath the component. This message is not serialized and should be assigned on every solution anew.
Implements: Message
MutableNickName
Gets or sets a value that enables Nick name changes through the menu. The default is TRUE.
Implements: MutableNickName
Name
Gets or sets the name of the object. This field typically remains fixed during the lifetime of an object.
Implements: Name
NickName
Gets or sets the nickname of the object. This field can be changed by the user.
Implements: NickName
Obsolete
Gets whether this object is obsolete. Default implementation returns true if the class name contains the string "OBSOLETE" or if this class has been decorated with the ObsoleteAttribute. You are free to override this if you want, but I suggest adding the ObsoleteAttribute instead.
Implements: Obsolete
Params
Gets the parameter manager object for this component.
Implements: Params
Phase
Gets or sets the solution phase this object is currenly in.
Implements: Phase
PrincipalParameterIndex
Gets or sets the principal parameter index override. Negative indices or indices larger than or equal to the input parameter count will be ignored and regular principal parameter detection will kick in.
Implements: MasterParameterIndex
ProcessorTime
Gets the total processor time (profiler) spend by this component and all input parameters.
Overrides: GH_ActiveObject.ProcessorTime
RunCount
Gets a value indicating how many times the SolveInstance method was called on this component during the last solution. This property will return -1 if no valid runcount is available.
Implements: RunCount
RuntimeMessageLevel
Returns the worst case runtime warning level of me and all my parameters
Overrides: GH_ActiveObject.RuntimeMessageLevel
SubCategory
Gets or sets the SubCategory in which this object belongs. If HasSubCategory() returns false, this field has no meaning.
Implements: SubCategory
Methods
AddRuntimeMessage
Add a new message to this object. Valid message type flags are Warning and Error. If the Message string is empty or zero-length no message is added.
Parameters:
| level (GH_RuntimeMessageLevel) | Type of message. Only Warnings and Errors are recorded. |
| text (string) | Content of message. |
Implements: AddRuntimeMessage
AfterSolveInstance
protected virtual void AfterSolveInstance()
Override this method if you want to be called after the last call to SolveInstance.
AppendRenderGeometry
[EditorBrowsable(EditorBrowsableState.Never)]
public virtual void AppendRenderGeometry(GH_RenderArgs args)
Append all geometry associated with this component to a render queue.
Parameters:
| args (GH_RenderArgs) |
Implements: AppendRenderGeometry
AssignInitCodeToInputParameter
Utility function for parsing and assigning init codes. This only works for standard parameter types.
AssignNewPassword
#Assign a new password to this cluster.
Parameters:
| oldPassword (string) | Current password. If the cluster has no password yet any string will do. |
| newPassword (string) | New password to assign. Pass in an empty string to remove password protection. |
Returns: True on success, false on failure. This function only returns false if the oldPassword is incorrect.
BakeGeometry
#Overrides: GH_Component.BakeGeometry
BakeGeometry
#Parameters:
| doc (RhinoDoc) | |
| att (ObjectAttributes) | |
| objectIds (List<Guid>) |
Overrides: GH_Component.BakeGeometry
BeforeSolveInstance
protected virtual void BeforeSolveInstance()
Override this method if you want to be called before the first call to SolveInstance.
ClearData
public override void ClearData()
Clear the data inside this component and all output parameters.
Overrides: GH_ActiveObject.ClearData
ClearRuntimeMessages
public sealed override void ClearRuntimeMessages()
Clears all runtime messages in me and my parameters
Overrides: GH_ActiveObject.ClearRuntimeMessages
CollectData
public override void CollectData()
Calls CollectData on all input parameters and makes sure the Component and all associated parameters are left in a valid state.
Overrides: GH_ActiveObject.CollectData
ComputeData
public override void ComputeData()
Compute all data and fill out all output parameters.
Overrides: GH_ActiveObject.ComputeData
CopyFrom
Copy all fields (except the instance ID) from another instance description.
Parameters:
| other (IGH_InstanceDescription) | Object to mimic. |
CreateFromDocument
#Recreate this cluster based on the provided document. The document will not be copied so it should be a unique instance reference. The document should have input and output hooks otherwise the cluster will have no input or output parameters.
Parameters:
| document (GH_Document) | Document to wrap. The document will not be copied, so be sure you supply a fresh one. |
| location (Point) | Location for cluster object. This is typically the center of the boundingbox of the document. |
CreateFromDocument
#Recreate this cluster based on the provided document. The document will not be copied so it should be a unique instance reference. The document should have input and output hooks otherwise the cluster will have no input or output parameters.
Parameters:
| document (GH_Document) | Document to wrap. The document will not be copied, so be sure you supply a fresh one. |
CreateFromFilePath
#Recreate this cluster based on a provided filepath.
Parameters:
| path (string) | File to load from. |
CreateFromSelection
#public void CreateFromSelection(GH_Document sourceDocument, bool deleteOriginalObjects, bool reconnectSources, bool reconnectRecipients)
Recreate this cluster based on the selected objects in the provided document. The selection in the document will be copied so you do not have to supply a unique doc. The luster will be inserted into the provided document.
Parameters:
| sourceDocument (GH_Document) | Document to cluster. |
| deleteOriginalObjects (bool) | If true, the original objects will be deleted from the document. |
| reconnectSources (bool) | If true, cluster inputs will be reconnected to the same sources as the original objects. |
| reconnectRecipients (bool) | If true, cluster outputs will be reconnected to the same recipients as the original objects. |
DependsOn
Returns True is any one of my input parameters depends on the source.
Parameters:
| potentialSource (IGH_ActiveObject) | Source to test for dependency. |
Overrides: GH_ActiveObject.DependsOn
DestroyIconCache
protected void DestroyIconCache()
Call this method to erase the existing icon cache. You must call this if you want to change the display icon of an object.
DisplayClusterPropertiesEditor
#public void DisplayClusterPropertiesEditor()
Document
#Gets the cluster document. If the cluster has a password, you'll need to supply it.
Parameters:
| password (string) | Cluster password. Without a correct password null will be returned. |
Returns: The cluster document or null on failure or incorrect password.
DocumentContextChanged
#Parameters:
| document (GH_Document) | |
| context (GH_DocumentContext) |
Overrides: GH_Component.DocumentContextChanged
DocumentModified
#[EditorBrowsable(EditorBrowsableState.Never)]
public void DocumentModified(GH_Document modifiedDocument)
Parameters:
| modifiedDocument (GH_Document) |
Implements: DocumentModified
DoKeysMatch
#Test two keys.
EditClusterAsSeparateDocument
#public void EditClusterAsSeparateDocument()
ExpireDownStreamObjects
protected override void ExpireDownStreamObjects()
Expire all objects that depend on any of the output parameters.
Overrides: GH_ActiveObject.ExpireDownStreamObjects
ExpirePreview
Call this function when you suspect that the preview has expired for this object. This will cause the display cache to be eradicated.
Parameters:
| redraw (bool) |
Implements: ExpirePreview
ExplodeCluster
#public void ExplodeCluster()
Explode this cluster back into the document that contains it.
GenerateDefaultHTML
Creates the default component help topic, including all parameter lists.
Remarks: This formatter does not include the this-is-an-autogenerated-topic message
GenerateParameterHelp
Create an HTML string that lists names and descriptions for input and output parameters.
GenerateParameterHelp
Generate HTML string for a single parameter.
Parameters:
| param (IGH_Param) |
GetValue
Get a boolean value from the component value table.
GetValue
Get a color value from the component value table.
GetValue
Get a double value from the component value table.
GetValue
Get an integer value from the component value table.
GetValue
Get a string value from the component value table.
HtmlHelp_Source
Return a String which contains HTML formatted source for the help topic. If you want to pass a URL that points to a remote page, then prefix the URL with a GOTO: tag, like so: GOTO:http://www.YourWebAddressHere.com
Remarks: You can use the GUI.GH_HtmlFormatter class to generate an HTML page which conforms to Grasshopper Help standards
Returns: The HTML default help topic for this component including all parameters
Overrides: GH_DocumentObject.HtmlHelp_Source
InstanceGuidsChanged
#[EditorBrowsable(EditorBrowsableState.Never)]
public void InstanceGuidsChanged(SortedDictionary<Guid, Guid> map)
Whenever the InstanceIDs of objects were changed, the cluster needs to be informed.
Parameters:
| map (SortedDictionary<Guid, Guid>) | InstanceId map of before and after keys/values. |
Implements: InstanceGuidsChanged
IsolateObject
public override void IsolateObject()
Sever the connections of all input and output parameters.
Overrides: GH_DocumentObject.IsolateObject
IsPasswordValid
#Tests whether a given password is valid. If there is no password defined for this cluster every password is considered valid.
Parameters:
| password (string) | Password to test. |
Returns: True on success, false on failure.
MovedBetweenDocuments
Overrides the MovedBetweenDocuments method and delegates the call to all parameters.
Parameters:
| oldDocument (GH_Document) | Document that used to own this object. |
| newDocument (GH_Document) | Document that now owns ths object. |
Overrides: GH_DocumentObject.MovedBetweenDocuments
NewInstanceGuid
public void NewInstanceGuid()
Generate a new random instance GUID
Implements: NewInstanceGuid
NewInstanceGuid
Set the instance ID to be a specific GUID. This is very dangerous, only use this function if you're 6"4' and your first name is David.
Parameters:
| UUID (Guid) |
Implements: NewInstanceGuid
OnAttributesChanged
public void OnAttributesChanged()
Raises the AttributesChanged event on the toplevel object.
Implements: OnAttributesChanged
OnDisplayExpired
Raises the DisplayExpired event on the toplevel object.
Parameters:
| redraw (bool) | If True, the canvas will be immediately redrawn. |
Implements: OnDisplayExpired
OnObjectChanged
Parameters:
| e (GH_ObjectChangedEventArgs) |
Implements: OnObjectChanged
OnObjectChanged
Parameters:
| eventType (GH_ObjectEventType) | |
| tag (object) |
Implements: OnObjectChanged
OnObjectChanged
Parameters:
| eventType (GH_ObjectEventType) |
Implements: OnObjectChanged
Implements: OnObjectChanged
OnObjectChanged
Parameters:
| customEvent (string) |
Implements: OnObjectChanged
OnPingDocument
Raise the PingDocument Event on the toplevel object and try to find the document which owns this object.
Returns: The document which owns this object if successful, or nothing if no document owns this object.
Implements: OnPingDocument
OnPreviewExpired
Raises the PreviewExpired event on the toplevel object.
Parameters:
| redraw (bool) | If True, the viewports will be immediately redrawn. |
Implements: OnPreviewExpired
OnSolutionExpired
Raises the SolutionExpired event on the toplevel object. You probably want to call ExpireSolution() instead of this method directly.
Parameters:
| recompute (bool) | If True, the solution will be immediately recalculated. |
Implements: OnSolutionExpired
PostConstructor
protected virtual void PostConstructor()
The PostConstructor is called from within each constructor. DO NOT OVERRIDE THIS unless you know what you are doing.
ReadFull
GH_InstanceDescription does not by default serialize all fields. Use this function to read all fields from the archive. This method is compatible with the default Write()/Read() operations.
Parameters:
| reader (GH_IReader) | Writer for deserialization. |
Returns: True on success, false on failure.
ReadGhClusterFile
#Read all cluster data from a *.ghcluster file.
Parameters:
| path (string) | Path to read from, should be a *.ghcluster file. |
Returns: True on success, false on failure.
RecordUndoEvent
Record a specific object change undo event.
Parameters:
| undoName (string) | Name of undo record. |
| action (IGH_UndoAction) | Undo action to record. |
Returns: The ID of the newly added record or Guid.Empty on failure.
Implements: RecordUndoEvent
RecordUndoEvent
Record a generic object change undo event.
Parameters:
| undoName (string) | Name of undo record. |
Returns: The ID of the newly added record or Guid.Empty on failure.
Implements: RecordUndoEvent
Parameters:
| record (GH_UndoRecord) | Record to push. |
Implements: RecordUndoEvent
RegisterInputParams
#Parameters:
| pManager (GH_Component.GH_InputParamManager) |
Overrides: GH_Component.RegisterInputParams
RegisterOutputParams
#Parameters:
| pManager (GH_Component.GH_OutputParamManager) |
Overrides: GH_Component.RegisterOutputParams
RegisterRemoteIDs
Registers all my input parameters with the UUID_LookUpTable
Parameters:
| table (GH_GuidTable) |
Overrides: GH_ActiveObject.RegisterRemoteIDs
RequestPassword
#Display a window which requests a password from the user. If this cluster has no password, this method returns True immediately.
Parameters:
| prompt (string) | Message to display. |
Returns: True if the user entered a valid password, false if not.
RuntimeMessages
Gets the list of cached runtime messages that were recorded during solver-time processes. For components, the set of runtime messages also includes input and output parameters.
Parameters:
| level (GH_RuntimeMessageLevel) | Runtime message type to retrieve. |
Returns: A list of runtime message strings.
Overrides: GH_ActiveObject.RuntimeMessages
SDKCompliancy
Test whether this object is compliant with a given Rhino version.
Parameters:
| exeVersion (int) | Rhino major release (4, 5, ...). |
| exeServiceRelease (int) | Rhino minor (service) release. |
Returns: True if this object is compliant with the given Rhino release.
Implements: SDKCompliancy
SetIconOverride
public void SetIconOverride(Bitmap customIcon)
Set a new custom icon override for this object.
Parameters:
| customIcon (Bitmap) | Icon override. Should be a 24x24 image. |
SetValue
Set a named value. This value will be serialized with the component.
SetValue
Set a named value. This value will be serialized with the component.
SetValue
Set a named value. This value will be serialized with the component.
SetValue
Set a named value. This value will be serialized with the component.
SetValue
Set a named value. This value will be serialized with the component.
TriggerAutoSave
public void TriggerAutoSave()
Triggers the AutoSave function on the owner document with the object_changed flag.
Implements: TriggerAutoSave
TriggerAutoSave
Triggers the AutoSave function on the owner document with a custom flag.
Parameters:
| trigger (GH_AutoSaveTrigger) | Reason for the autosave operation. It is possible that a user has decided to avoid autosave events for specific types, so if you can, try and provide a correct trigger flag. |
| id (Guid) | ID of autosave event. Consecutive autosave requests with the same ID will be ignored. |
Implements: TriggerAutoSave
TriggerAutoSave
Triggers the AutoSave function on the owner document with a custom flag.
Parameters:
| trigger (GH_AutoSaveTrigger) | Reason for the autosave operation. It is possible that a user has decided to avoid autosave events for specific types, so if you can, try and provide a correct trigger flag. |
Implements: TriggerAutoSave
TriggerAutoSave
Triggers the AutoSave function on the owner document with the object_changed flag.
Parameters:
| id (Guid) | ID of autosave event. Consecutive autosave requests with the same ID will be ignored. |
Implements: TriggerAutoSave
UpdateDocument
#Update this cluster to use a new document. Input and Output parameters will be maintained whenever possible. This function is very low-level, if you're in doubt about whether to use it or not, ask on https://discourse.mcneel.com/ for further information.
Parameters:
| document (GH_Document) | New cluster document. |
ValuesChanged
protected virtual void ValuesChanged()
Override this method if you want to respond to changes to the value table. The base implementation is empty, so you don't have to call it.
VariableParameterMaintenance
#public void VariableParameterMaintenance()
Implements: VariableParameterMaintenance
WriteFull
GH_InstanceDescription does not by default serialize all fields. Use this function to write all fields to the archive. This method is compatible with the default Write()/Read() operations.
Parameters:
| writer (GH_IWriter) | Writer for serialization. |
Returns: True on success, false on failure.
Events
AttributesChanged
Raised whenever the number or kind of attributes changes. This event is handled by GH_Documents who subsequently wipe their attribute caches.
Implements: AttributesChanged
DisplayExpired
Raised whenever the display (on the Canvas) of a certain object becomes invalid.
Implements: DisplayExpired
ObjectChanged
Implements: ObjectChanged
PingDocument
Raised whenever an object needs to know which GH_Document it belongs to.
Implements: PingDocument
PreviewExpired
Raised whenever the display (in the Rhino viewports) of a certain object becomes invalid.
Implements: PreviewExpired
SolutionExpired
Raised whenever the solution of a certain object becomes invalid.
Implements: SolutionExpired