Options Pages Best Practices

by John Morse (Last updated:  Wednesday, December 5, 2018)

Overview

One of the things your plug-in may want to do is add options or document property settings pages to Rhino. You can add pages by overriding the PlugIn.OptionsDialogPages and/or PlugIn.DocumentPropertiesDialogPages methods and adding a custom OptionsDialogPage to the provided page list.

You can create options pages in a plug-in using WinForms(Windows), WPF (Windows) or Eto (Windows and Mac).

You can find samples that demonstrate how to create options pages in the Developer Samples repository on GitHub.

Details

When writing options pages, it is important to remember that the page should initialize its content when activated, apply its changes when notified and optionally provide cancel support.

Content Initialization

The OnActivate method is called with active == true when becoming the current, visible page which is the appropriate time to update the page contents.

Applying Changes

It is up to the page author to decide when to apply user changes to the document or runtime environment. If you wish to see the document or Rhino update while making changes, you may apply the changes in real time. It is important to save the original settings prior to making changes if your options page is going to support the cancel mechanism. Typically changes should be queued up and made in the OnApply override, canceling should be performed in the OnCancel override.

Rhino for Windows Behavior

Rhino for Windows contains a single Options/Document Properties dialog box which can be displayed using the Options or DocumentProperties Rhino commands. This dialog box is modal in nature and will call the PlugIn.OptionsDialogPages and PlugIn.DocumentPropertiesDialogPages methods each time it is displayed. It creates the PageControl the first time the page is made current. If your page is never made current, the page control is never created. Rhino will call OnActivate with active == true when a page becomes the active page. When a page is no longer active, the OnActivate method is called with active == false followed by a call to OnApply. If the Rhino Options/Document Properties dialog is closed by cancelling, then OnCancel is called for any page displayed while the modal dialog was visible.

Rhino for Mac Behavior

Rhino for Mac contains File/Settings (Document Properties) and Rhinoceros/Preferences (Options) modeless windows. The main things to consider here are the host windows are modeless and cancel is never called. Since the host winows are independent you will get slightly different behavior for Preferences (Options) panels than you will with File/Settings (Document Properties) panels.

Preferences Window (Options)

The Preferences window will call PlugIn.OptionsDialogPages the first time the window is displayed and will never call it again. The Preferences window is never really closed; it is only hidden or shown. The following is a description of the methods called and when they are called:

  • PageControl is referenced the first time the page is displayed and should return the one and only options page control.
  • OnActivate with active == true is called when:
    • A page becomes the active page.
    • The Options window becomes the active window and a page is active.
  • OnActivate with active == false is called when:
    • The active page changes and a page is no longer the active page.
    • The Options window is deactivated or hidden and a page is the active page.
  • OnApply is called on the active page when:
    • The active page changes and a page is no longer the active page.
    • The Options window is deactivated or hidden and a page is the active page.
File Settings Window (Document Properties)

The File Settings window will call PlugIn.DocumentPropertiesDialogPages the first time the window is displayed and each time a new document is created. The Settings window keeps a list of pages associated with each open document and displays the active page assocated with the current document. The Settings window is never really closed; it is only hidden or shown. The following is a description of the methods called and when they are called:

  • PageControl is referenced the first time the page is displayed for a given document instance and should return the settings page control. It will also get called when a new document is opened or created and a page is the active page.
  • OnActivate with active == true is called when:
    • A page becomes the active page.
    • The Settings window becomes the active window and a page is active.
  • OnActivate with active == false is called when:
    • The active page changes and a page is no longer the active page.
    • The Settings window is deactivated or hidden and a page is the active page.
  • OnApply is called on the active page when:
    • The active page changes and a page is no longer the active page.
    • The Settings window is deactivated or hidden and a page is the active page.