Class EditorToolBaseForm

The base form used for krypton tool plug ins.

Inheritance
object
MarshalByRefObject
Component
Control
ScrollableControl
ContainerControl
Form
EditorToolBaseForm
Implements
Inherited Members
Namespace: Gorgon.Editor.UI.Views
Assembly: Gorgon.Editor.API.dll
Syntax
public class EditorToolBaseForm : Form, IDropTarget, ISynchronizeInvoke, IWin32Window, IBindableComponent, IComponent, IDisposable, IContainerControl
Remarks

Developers who use to create tool plug ins for the editor should use this form as the base for their UI. It provides functionality to make setting up and rendering easier, and will perform any necessary clean up on behalf of the developer.

Constructors

| Edit this page View Source

EditorToolBaseForm()

Initializes a new instance of the EditorToolBaseForm class.

Declaration
public EditorToolBaseForm()

Properties

| Edit this page View Source

GraphicsContext

Property to return the graphics context for the application.

Declaration
[Browsable(false)]
protected IGraphicsContext GraphicsContext { get; }
Property Value
Type Description
IGraphicsContext
| Edit this page View Source

IsDesignTime

Property to return whether the form is in designer mode or not.

Declaration
[Browsable(false)]
protected bool IsDesignTime { get; }
Property Value
Type Description
bool
| Edit this page View Source

RenderControl

Property to set or return the control that will receive the rendering output from the swap chain.

Declaration
[Browsable(true)]
public Control RenderControl { get; set; }
Property Value
Type Description
Control
Remarks

This property can only be set through the designer. Setting it at runtime will do nothing.

| Edit this page View Source

Renderer

Property to return the currently active tool renderer.

Declaration
[Browsable(false)]
protected IToolRenderer Renderer { get; }
Property Value
Type Description
IToolRenderer
| Edit this page View Source

SwapChain

Property to return the swap chain for the tool render panel.

Declaration
[Browsable(false)]
protected GorgonSwapChain SwapChain { get; }
Property Value
Type Description
GorgonSwapChain

Methods

| Edit this page View Source

AddRenderer(string, IToolRenderer)

Function to register a new renderer with the view.

Declaration
protected void AddRenderer(string name, IToolRenderer renderer)
Parameters
Type Name Description
string name

The name of the renderer.
IToolRenderer renderer

The renderer to register.
Remarks

Some tool plug ins will require the rendered view to change depending on state. For example, a specific tool is selected and the view needs to switch to a portion of the tool UI. In such cases it is not practical to have a single renderer performing all manner of state changes, so this method provides a means of passing different renderer instances to the view.

Developers of the tool plug ins should register these renderers in the OnSetupGraphics(IGraphicsContext, GorgonSwapChain) method so that the renderers are available right away. Failure to do so can lead to broken rendering.

Exceptions
Type Condition
ArgumentNullException

Thrown when the name, or the renderer parameter is null.
ArgumentEmptyException

Thrown when the name parameter is empty.
ArgumentException

Thrown if a renderer is already registered with the same name.
See Also
| Edit this page View Source

Dispose(bool)

Clean up any resources being used.

Declaration
protected override void Dispose(bool disposing)
Parameters
Type Name Description
bool disposing

true if managed resources should be disposed; otherwise, false.
Overrides
| Edit this page View Source

HasRenderer(string)

Function to determine if a renderer with the specified name is registered.

Declaration
protected bool HasRenderer(string name)
Parameters
Type Name Description
string name

The name of the renderer to evaluate.
Returns
Type Description
bool

true if the renderer is registered, false if not.
| Edit this page View Source

OnAfterRender()

Function called after rendering ends.

Declaration
protected virtual void OnAfterRender()
Remarks

Developers can use this method to perform operations immediately after rendering the tool UI.

| Edit this page View Source

OnBeforeRender()

Function called before rendering begins.

Declaration
protected virtual void OnBeforeRender()
Remarks

Developers can use this method to perform last minute updates prior to rendering the tool UI.

| Edit this page View Source

OnFormClosing(FormClosingEventArgs)

Raises the FormClosing event.

Declaration
protected override void OnFormClosing(FormClosingEventArgs e)
Parameters
Type Name Description
FormClosingEventArgs e

A FormClosingEventArgs that contains the event data.
Overrides
| Edit this page View Source

OnLoad(EventArgs)

Raises the Load event.

Declaration
protected override void OnLoad(EventArgs e)
Parameters
Type Name Description
EventArgs e

An EventArgs that contains the event data.
Overrides
| Edit this page View Source

OnPropertyChanged(string)

Function called when a property was changed on the data context.

Declaration
protected virtual void OnPropertyChanged(string propertyName)
Parameters
Type Name Description
string propertyName

The name of the property that was changed.
Remarks

Developers should override this method when detecting property changes on the data context instead of assigning their own event handlers.

| Edit this page View Source

OnPropertyChanging(string)

Function called when a property is changing on the data context.

Declaration
protected virtual void OnPropertyChanging(string propertyName)
Parameters
Type Name Description
string propertyName

The name of the property that is changing.
Remarks

Developers should override this method when detecting property changes on the data context instead of assigning their own event handlers.

| Edit this page View Source

OnRenderWindowDragDrop(DragEventArgs)

Function to handle a drag drop event on the render control.

Declaration
protected virtual void OnRenderWindowDragDrop(DragEventArgs e)
Parameters
Type Name Description
DragEventArgs e

The event arguments.
Remarks

Tool plug in developers can override this method to handle a drop event when an item is dropped into the rendering area on the view.

| Edit this page View Source

OnRenderWindowDragEnter(DragEventArgs)

Function to handle a drag enter event on the render control.

Declaration
protected virtual void OnRenderWindowDragEnter(DragEventArgs e)
Parameters
Type Name Description
DragEventArgs e

The event arguments.
Remarks

Tool plug in developers can override this method to handle a drag enter event when an item is dragged into the rendering area on the view.

| Edit this page View Source

OnRenderWindowDragOver(DragEventArgs)

Function to handle a drag over event on the render control.

Declaration
protected virtual void OnRenderWindowDragOver(DragEventArgs e)
Parameters
Type Name Description
DragEventArgs e

The event arguments.
Remarks

Tool plug in developers can override this method to handle a drag over event when an item is dragged over the rendering area on the view.

| Edit this page View Source

OnResetDataContext()

Function called when the view should be reset by a null data context.

Declaration
protected virtual void OnResetDataContext()
Remarks

Developers should override this method to return the form back to its original state.

| Edit this page View Source

OnSetDataContext(IEditorTool)

Function to assign the data context to this object.

Declaration
protected void OnSetDataContext(IEditorTool dataContext)
Parameters
Type Name Description
IEditorTool dataContext

The data context to assign.
Remarks

Applications must call this method when setting their own data context. Otherwise, some functionality will not work.

| Edit this page View Source

OnSetupGraphics(IGraphicsContext, GorgonSwapChain)

Function to perform custom graphics set up.

Declaration
protected virtual void OnSetupGraphics(IGraphicsContext graphicsContext, GorgonSwapChain swapChain)
Parameters
Type Name Description
IGraphicsContext graphicsContext

The graphics context for the application.
GorgonSwapChain swapChain

The swap chain used to render into the UI.
Remarks

This method allows tool plug in implementors to setup additional functionality for custom graphics rendering.

Resources created by this method should be cleaned up in the OnShutdownGraphics() method.

See Also
| Edit this page View Source

OnShutdownGraphics()

Function to perform clean up when graphics operations are shutting down.

Declaration
protected virtual void OnShutdownGraphics()
Remarks

Any resources created in the OnSetupGraphics(IGraphicsContext, GorgonSwapChain) method must be disposed of here.

| Edit this page View Source

OnSwitchRenderer(IToolRenderer)

Function called when the renderer is switched.

Declaration
protected virtual void OnSwitchRenderer(IToolRenderer renderer)
Parameters
Type Name Description
IToolRenderer renderer

The current renderer.
| Edit this page View Source

OnUnassignEvents()

Function to unassign events for the data context.

Declaration
protected virtual void OnUnassignEvents()
Remarks

If the developer assigns events to the data context, child data contexts, or other event capable controls, they should unassign the events here to avoid event leakage.

| Edit this page View Source

SetupGraphics(IGraphicsContext, bool)

Function to set up the graphics interface for this window.

Declaration
public void SetupGraphics(IGraphicsContext context, bool allowBackgroundRendering = true)
Parameters
Type Name Description
IGraphicsContext context

The application graphics context provided by the plug in.
bool allowBackgroundRendering

[Optional] true to allow the graphics functionality to render even if the form does not have focus, false to pause rendering.
Remarks

This method will initialize the graphics sub system for the control (if required) so that users may use the Gorgon drawing functionality in their tool plug in. The method should be called immediately after creating the form to reduce any possibility of issues.

Implementors who wish to perform their own graphics initialization may override the OnSetupGraphics(IGraphicsContext, GorgonSwapChain) method for setup, and OnShutdownGraphics() method for clean up.

Prior to calling this method, the RenderControl property must be set or an exception will be thrown.

Exceptions
Type Condition
ArgumentNullException

Thrown when the context parameter is null.
GorgonException

Thrown if the RenderControl property is not set to a non-null value.
| Edit this page View Source

SwitchRenderer(string)

Function to switch to another registered renderer.

Declaration
protected void SwitchRenderer(string name)
Parameters
Type Name Description
string name

The name of the renderer to switch to.
Remarks

Developers will this method to switch between renderer types (if multiple renderers are used) to denote editor state.

Exceptions
Type Condition
ArgumentNullException

Thrown when the name parameter is null.
ArgumentEmptyException

Thrown when the name parameter is empty.
ArgumentException

Thrown if no renderer with the specified name was found.

Implements

Extension Methods