PlugIn
ReferencesA general purpose utility plug-in that can contain one or more commands.
Constructors
PlugIn
#protected PlugIn()
Properties
If true, Rhino will display a warning dialog when load-protected plug-ins are attempting to load. If false, load-protected plug-ins will silently not load.
Returns the description of the plug-in, as found in the plug-in's assembly attributes.
Returns the number of installed Rhino plug-ins.
obsoleteUse LoadTime virtual property instead
Plug-ins are typically loaded on demand when they are first needed. You can change this behavior to load the plug-in at during different stages in time by overriding this property.
LocalPlugInName
#Optionally override this to provide a localized plug-in name
Returns the name of the plug-in, as found in the plug-in's assembly attributes.
Get the plug-in's settings directory. This is the directory where the plug-in's persistent settings files are saved. This directory will be located in the user's profile folder. Note, this does not verify the directory exists.
Get the plug-in's "all users" settings directory. This directory will be located in the system's program data folder. Note, this does not verify the directory exists.
Returns the version of the plug-in, as found in the plug-in's assembly attributes.
Methods
AskUserForLicense
#protected bool AskUserForLicense(LicenseBuildType productBuildType, bool standAlone, string textMask, object parentWindow, ValidateProductKeyDelegate validateProductKeyDelegate, OnLeaseChangedDelegate onLeaseChangedDelegate)
Parameters:
| productBuildType (LicenseBuildType) | |
| standAlone (bool) | |
| textMask (string) | |
| parentWindow (object) | |
| validateProductKeyDelegate (ValidateProductKeyDelegate) | |
| onLeaseChangedDelegate (OnLeaseChangedDelegate) |
Parameters:
| name (string) |
CreateCommands
#protected virtual void CreateCommands()
Called right after plug-in is created and is responsible for creating all of the commands in a given plug-in. The base class implementation Constructs an instance of every publicly exported command class in your plug-in's assembly.
Called by Rhino if AddToHelpMenu is true and menu item associated with this plug-in is selected.
Parameters:
| windowHandle (nint) | Native Window handle of the active Rhino interface. |
Returns: true = Help displayed successfully, false = Error displaying help
DocumentPropertiesDialogPages
#Override this function if you want to extend the document properties sections of the options dialog. This function is called whenever the user brings up the Options dialog.
Parameters:
| doc (RhinoDoc) | document that the pages are set up for |
| pages (List<OptionsDialogPage>) | list of pages to add your custom options dialog page(s) to. |
Finds the plug-in instance that was loaded from a given assembly.
Parameters:
| pluginAssembly (Assembly) | The plug-in assembly. You can get the assembly instance at runtime with the Type.Assembly instance property. |
Returns: The assembly plug-in instance if successful. Otherwise, null.
Finds the plug-in instance that was loaded from a given plug-in Id.
Parameters:
| plugInId (Guid) | The plug-in Id. |
Returns: The plug-in instance if successful. Otherwise, null.
public static void FlushSettingsSavedQueue()
All of the commands associated with this plug-in.
Gets names of all "non-test" commands for a given plug-in.
Parameters:
| pluginId (Guid) | The plug-in ID. |
Returns: An array with all plug-in names. This can be empty, but not null.
Returns the names of all installed Rhino plug-ins.
Returns: The names if successful.
public static string[] GetInstalledPlugInNames(PlugInType typeFilter, bool loaded, bool unloaded, bool localizedPlugInName)
Gets a list of installed plug-in names. The list can be restricted by some filters.
Parameters:
| typeFilter (PlugInType) | The enumeration flags that determine which types of plug-ins are included. |
| loaded (bool) | true if loaded plug-ins are returned. |
| unloaded (bool) | true if unloaded plug-ins are returned. |
| localizedPlugInName (bool) | If true localized plug-in names are returned otherwise; English names are returned. |
Returns: An array of installed plug-in names. This can be empty, but not null.
Gets a list of installed plug-in names. The list can be restricted by some filters.
Parameters:
| typeFilter (PlugInType) | The enumeration flags that determine which types of plug-ins are included. |
| loaded (bool) | true if loaded plug-ins are returned. |
| unloaded (bool) | true if unloaded plug-ins are returned. |
Returns: An array of installed plug-in names. This can be empty, but not null.
Get a list of all registered plug-in's regardless of if they are loaded or not.
Returns: Dictionary with plug-in ID as key and localized plug-in name as value
Get a list of all registered plug-in's regardless of if they are loaded or not.
Parameters:
| localizedPlugInName (bool) | If true then the localize plug-in name is returned otherwise; the English name is used. |
Returns: Dictionary with plug-in ID as key and plug-in name as value
GetLicense
#protected bool GetLicense(LicenseBuildType productBuildType, ValidateProductKeyDelegate validateProductKeyDelegate, OnLeaseChangedDelegate leaseChangedDelegate)
Verifies that there is a valid product license for your plug-in, using the Rhino licensing system. If the plug-in is installed as a standalone node, the locally installed license will be validated. If the plug-in is installed as a network node, a loaner license will be requested by the system's assigned Zoo server. If the Zoo server finds and returns a license, then this license will be validated. If no license is found, then the user will be prompted to provide a license key, which will be validated.
Parameters:
| productBuildType (LicenseBuildType) | The product build contentType required by your plug-in. |
| validateProductKeyDelegate (ValidateProductKeyDelegate) | Since the Rhino licensing system knows nothing about your product license, you will need to validate the product license provided by the Rhino licensing system. This is done by supplying a callback function, or delegate, that can be called to perform the validation. |
| leaseChangedDelegate (OnLeaseChangedDelegate) | Called by the ZooClient when the cloud zoo lease is changed. |
Returns: true if a valid license was found. false otherwise.
GetLicense
#protected bool GetLicense(LicenseCapabilities licenseCapabilities, string textMask, ValidateProductKeyDelegate validateProductKeyDelegate, OnLeaseChangedDelegate leaseChangedDelegate)
Verifies that there is a valid product license for your plug-in, using the Rhino licensing system. If the plug-in is installed as a standalone node, the locally installed license will be validated. If the plug-in is installed as a network node, a loaner license will be requested by the system's assigned Zoo server. If the Zoo server finds and returns a license, then this license will be validated. If no license is found, then the user will be prompted to provide a license key, which will be validated.
Parameters:
| licenseCapabilities (LicenseCapabilities) | In the event that a license was not found, or if the user wants to change the way your plug-in is licenses, then provide what capabilities your license has by using this enumeration flag. |
| textMask (string) | In the event that the user needs to be asked for a license, then you can provide a text mask, which helps the user to distinguish between proper and improper user input of your license code. Note, if you do not want to use a text mask, then pass in a null value for this parameter. For more information on text masks, search MSDN for the System.Windows.Forms.MaskedTextBox class. |
| validateProductKeyDelegate (ValidateProductKeyDelegate) | Since the Rhino licensing system knows nothing about your product license, you will need to validate the product license provided by the Rhino licensing system. This is done by supplying a callback function, or delegate, that can be called to perform the validation. |
| leaseChangedDelegate (OnLeaseChangedDelegate) | Called by the ZooClient when the cloud zoo lease is changed. |
Returns: true if a valid license was found. false otherwise.
Get the customer name and organization used when entering the product license.
Get load protection state for a plug-in
Returns detailed information about an installed Rhino plug-in.
Parameters:
| pluginId (Guid) | The id of the plug-in. |
Returns: Detailed information about an installed Rhino plug-in if successful, null otherwise.
Returns the plug-in's icon in bitmap form.
Parameters:
| size (Size) | The desired size in pixels. |
Returns: The icon if successful, null otherwise.
Attempt to get a plugiin id from just the filename of a plug-in
Parameters:
| filename (string) | plug-in filename |
Returns: id on success; Guid.Empty if no plug-in could be found
Gets the id of an installed plug-in giving the plug-in's name.
Parameters:
| pluginName (string) | The name of the installed plug-in. |
Returns: The id if successful.
Gets the id of an installed plug-in giving the plug-in's file path.
Parameters:
| pluginPath (string) | The path to the installed plug-in. |
Returns: The id if successful.
Returns true if this renderer can render the texture natively without needing it to be baked into a bitmap, false otherwise. By default, returns false for all textures.
Parameters:
| texture (RenderTexture) |
public static void LoadComputeExtensionPlugins()
Used by compute's startup code to load plug-ins that have registered custom endpoints
Loads an installed plug-in.
Loads an installed plug-in.
Parameters:
| pluginId (Guid) | The id of the installed plug-in. |
Returns: true if successful, false otherwise.
Attempt to load a plug-in at a path. Loaded plug-ins are remembered by Rhino between sessions, so this function can also be considered a plug-in installation routine
Gets a plug-in name for an installed plug-in given the path to that plug-in.
Parameters:
| pluginPath (string) | The path of the plug-in. |
Returns: The plug-in name.
ObjectPropertiesPages
#obsoleteUse ObjectPropertiesPages(ObjectPropertiesPageCollection collection) instead
Override this function is you want to extend the object properties dialog
Parameters:
| pages (List<ObjectPropertiesPage>) |
ObjectPropertiesPages
#Override this function is you want to extend the object properties dialog. This method will be called each time a new document is created for each instance of a object properties panel. On Windows there will be a single panel per document but on Mac there may be many properties panel per document.
Parameters:
| collection (ObjectPropertiesPageCollection) | Add custom pages by calling collection.Add |
OnLoad
#Is called when the plug-in is being loaded.
Parameters:
| errorMessage (ref string) | If a load error is returned and this string is set. This string is the error message that will be reported back to the user. |
Returns: An appropriate load return code.
The default implementation returns LoadReturnCode.Success.
OnShutdown
#protected virtual void OnShutdown()
OptionsDialogPages
#Override this function if you want to extend the options dialog. This function is called whenever the user brings up the Options dialog.
Parameters:
| pages (List<OptionsDialogPage>) | list of pages to add your custom options dialog page(s) to. |
Gets the path to an installed plug-in given the id of that plug-in
Parameters:
| pluginId (Guid) |
Gets the path to an installed plug-in given the name of that plug-in
Parameters:
| pluginName (string) |
Verifies that a Rhino plug-in is installed.
public static void RaiseOnPlugInSettingsSavedEvent()
Raise any pending OnPlugInSettingsSaved events, the events are normally queued while a command is running and fired while Rhino is in an idle state. Calling this method will raise any pending changed events regardless of Rhino's current idle state or if a command is running.
ReadDocument
#protected virtual void ReadDocument(RhinoDoc doc, BinaryArchiveReader archive, FileReadOptions options)
Called whenever a Rhino document is being loaded and plug-in user data was encountered written by a plug-in with this plug-in's GUID.
Parameters:
| doc (RhinoDoc) | A Rhino document that is being loaded. |
| archive (BinaryArchiveReader) | OpenNURBS file archive object Rhino is using to read this file. Use BinaryArchiveReader.Read*() functions to read plug-in data. If any BinaryArchive.Read*() functions throws an exception then archive.ReadErrorOccurve will be true and you should immediately return. |
| options (FileReadOptions) | Describes what is being written. |
ResetMessageBoxes
#protected virtual void ResetMessageBoxes()
Returns, or releases, a product license that was obtained from the Rhino licensing system. Note, most plug-ins do not need to call this as the Rhino licensing system will return all licenses when Rhino shuts down.
Parameters:
| plugInId (Guid) |
public void SaveSettings()
Write settings to disk which will raise a SettingsSaved event.
SetLicenseCapabilities
#protected void SetLicenseCapabilities(string textMask, LicenseCapabilities capabilities, Guid licenseId)
Parameters:
| textMask (string) | |
| capabilities (LicenseCapabilities) | |
| licenseId (Guid) |
Set load protection state for a certain plug-in
ShouldCallWriteDocument
#Called whenever a Rhino is about to save a .3dm file. If you want to save plug-in document data when a model is saved in a version 5 .3dm file, then you must override this function to return true and you must override WriteDocument().
Parameters:
| options (FileWriteOptions) | The file write options, such as "include preview image" and "include render meshes". |
Returns: true if the plug-in wants to save document user data in the version 5 .3dm file. The default returns false.
WriteDocument
#protected virtual void WriteDocument(RhinoDoc doc, BinaryArchiveWriter archive, FileWriteOptions options)
Called when Rhino is saving a .3dm file to allow the plug-in to save document user data.
Parameters:
| doc (RhinoDoc) | The Rhino document instance that is being saved. |
| archive (BinaryArchiveWriter) | OpenNURBS file archive object Rhino is using to write the file. Use BinaryArchiveWriter.Write*() functions to write plug-in data. OR use the ArchivableDictionary If any BinaryArchiveWriter.Write*() functions throw an exception, then archive.WriteErrorOccured will be true and you should immediately return. Setting archive.WriteErrorOccured to true will cause Rhino to stop saving the file. |
| options (FileWriteOptions) | The file write options, such as "include preview image" and "include render meshes". |
Events
This event is raised when an instance of Rhino has modified the external settings file associated with this plug-in's Settings property.
This event is raised when a 3dm file is loaded with unknown user data, and the plug-in to handle it could not be loaded.