TINMAN 3D / REALTIME TERRAIN
Software Development Kit - User Manual

interface IWidgetGui in Tinman.Engine.Widgets

Provides a graphical user interface for IWidget s.

interface IWidgetGui extends IDisposable
  IGraphicsComponent
  IInputConsumer
  IJsonizable
  INonUserInterfaceBounds
  IRenderable2D
  IUpdateableFrameTime
  base of WidgetGui

Remarks

The widget GUI covers the whole screen and provides two collapsible work areas: Controls and Editors. These are placed at the right resp. left edge of the screen. The center part of the widget GUI may be used to present dialogs (both modal and non-modal), for example: confirmation dialogs (modal), file chooser (modal), help browser (non-modal). Toolbar button may be added to the top edge of the screen.

+---------------------------------------------+
| .---------.  _______ _______   .----------. |
| | Editors | |Button1|Button2|  | Controls | |
| |=========|                    |==========| |
| | panel 1 |    .----------.    | panel A  | |
| |---------|    |  Dialog  |    |----------| |
| | panel 2 |    |==========|    | panel B  | |
| |---------|    | This OK? |    |----------| |
| | ...     |    |----------|    | ...      | |
| |---------|    | yes | no |    |----------| |
| | panel 9 |    °----------°    | panel Z  | |
| °---------°                    °----------° |
+---------------------------------------------+

See also:

IWidgetGuiConsumer

Attributes

Bounds

The pixel bounds of th widget GUI.

property Bounds { get }
type Box2I
value [not-null] The pixel bounds.

DialogIdentifier

Returns the identifier of the current dialog.

property DialogIdentifier { get }
type string
value The dialog identifier or null iff there is no current dialog.

HasDialog

Is there a current dialog?

property HasDialog { get }
type bool
value true if there is a current dialog, false if not.

IsFocussed

Does the widget GUI have input focus?

property IsFocussed { get }
type bool
value true if the widget GUI has input focus, false if not.

IsSoleOwnership

Will this object be disposed upon the next call to Dispose?

[ThreadSafe]
property IsSoleOwnership { get }
type bool
value true if the object will be disposed when Dispose is called,
false if the object will not be disposed, because some other code is still holding shared ownership (see AcquireBase).
inherited IDisposable.IsSoleOwnership

LifecycleState

Returns the lifecycle state of this object.

property LifecycleState { get }
type LifecycleState
value The lifecycle state.
inherited ILifecycleState.LifecycleState

NonUserInterfaceBounds

Returns the screen region that is not occluded by any opaque user-interface components.

property NonUserInterfaceBounds { get }
type Box2I
value The non-UI pixel bounds.
inherited INonUserInterfaceBounds.NonUserInterfaceBounds

Remarks:

If there is not user-interface, the screen region is returned.

Root

Returns the root container of the widget GUI.

property Root { get }
type Component
value [not-null] The root container.

Methods

AcquireBase

Acquires a strong reference to this disposable object.

[OwnerReturn, Pure]
method AcquireBase (bool allowNull = false)
type IDisposable
params allowNull Depicts what to do when this object is no longer valid:
true: return null
false: throw an exception
returns The strong reference to this disposable object or null iff allowNull is true and this object is no longer valid.
inherited IDisposable.AcquireBase

Remarks:

The object will not be actually disposed by calls to IDisposable when there is at least one strong reference left. Code that calls this method is responsible for calling the IDisposable method accordingly.

This method is not intended to be used in performance-critical code. It should only be used to high-level resource management.

Using this method usually requires type casting. Subclasses may additionally implement IDisposableGeneric, in order to provide some syntactic sugar for that.

Exceptions:

ButtonAdd

Adds a toolbar button to the widget GUI.

method ButtonAdd ([Owner] PushButton button)
params button [not-null] The button to add to the toolbar.

See also:

ButtonRemove

ButtonRemove

Removes a toolbar button from the widget GUI.

method ButtonRemove (PushButton button)
params button [not-null] The button to remove from the toolbar.

See also:

ButtonAdd

ConsumeInput

Consumes the given user input event.

method ConsumeInput (InputEvent inputEvent)
type bool
params inputEvent The user input event.
returns true if the input event has been consumed, false if not.
inherited IInputConsumer.ConsumeInput

Remarks:

Input events are provided to an IInputConsumer object only if it has the input focus (see FocusGained and FocusLost). Mouse events are provided when the mouse cursor is inside of the input bounds (MouseEnter and MouseLeave). The Closing event can be provided at any time.

  1. FocusGained: gained input focus
  2. Keyboard events:
  3. Mouse events:
    1. MouseEnter
    2. Mouse events:
    3. MouseLeave
  4. FocusLost: lost input focus
  5. Closing: user request to shut down

DialogHide

Hides the current dialog by cancelling it.

method DialogHide (string identifier = null)
type string
params identifier The identifier of the current dialog. If equal to the value that has been passed to DialogShow, the dialog will be cancelled. If null, the current dialog will be cancelled regardless of its identifier. Defaults to null.
returns The dialog identifier of the dialog that has been cancelled or null.

See also:

DialogResultCode.Cancel

DialogShow

Shows a dialog in the center part of the widget GUI.

method DialogShow ([Owner] WidgetDialog dialog, WidgetDialogFlags flags, string identifier = null)
params dialog [not-null] The widget dialog to show.
  flags The widget dialog flags.
  identifier Optional dialog identifier. If null, 'dialog' will be used. Defaults to null.

Dispose

Releases all resources held by this object if there are no more strong references to it, decrements the reference counter by one otherwise.

[Dispose, OwnerThis, ThreadSafe]
method Dispose ()
inherited IDisposable.Dispose

Remarks:

The Dispose method silently returns if the object has already been disposed.

Implementing methods must not throw any exceptions.

FocusClear

Clears the input focus of the widget GUI.

method FocusClear ()

GraphicsAttach

Attaches this component to the given Graphics context.

method GraphicsAttach (Graphics graphics)
params graphics [not-null] The graphics context.
inherited IGraphicsComponent.GraphicsAttach

Remarks:

All graphics-related resources should be created here.

Do not use the screen size of graphics here, as it may not be valid (see Graphics for details). Instead, use the screen size that is provided by GraphicsResize.

GraphicsDetach

Detaches this user interface component from its Graphics context.

method GraphicsDetach ()
inherited IGraphicsComponent.GraphicsDetach

Remarks:

All graphics-related resources should be disposed here.

GraphicsResize

The screen size has changed.

method GraphicsResize (Vec2I screenSize)
params screenSize The new screen size, in pixels.
inherited IGraphicsComponent.GraphicsResize

HelpSetup

Sets up the help system.

method HelpSetup (Path documentIndex, InputClick helpAction = default(InputClick), IHelpProvider provider = null)
params documentIndex The document index of the help system content. See Content for details. If null, the help system will be disabled.
  helpAction The input action for triggering the help system. Defaults to None.
  provider Optional IHelpProvider object. Defaults to null.

JsonDeserialize

Restores the object state from the given JSON value.

method JsonDeserialize (JsonValue value)
params value [not-null] The input JSON value.
inherited IJsonizable.JsonDeserialize

Remarks:

Implementations of this method must be able to consume malformed JSON values, without corrupting the object state.

JsonSerialize

Serializes the object state to an JSON value.

method JsonSerialize (JsonValue value)
params value [not-null] The output JSON value.
inherited IJsonizable.JsonSerialize

PanelAdd

Adds a panel to the widget GUI.

method PanelAdd (WidgetGuiSlot slot, [Owner] Panel panel, int32 size = 0, int32 limit = 0, InputClick action = default(InputClick))
type Panel
params slot The widget GUI slot where the given panel will be put.
  panel [not-null] The panel to add.
  size [>=0] The minimum width of panel in the widget GUI slot. Defaults to 0.
  limit [>=0] The maximum width of panel in the widget GUI slot or 0 for no limit. Defaults to 0.
  action The input action of the panel. Defaults to None.
returns panel

See also:

PanelRemove

PanelRemove

Removes a panel from the widget GUI.

method PanelRemove (Panel panel)
params panel [not-null] The panel to remove.

See also:

PanelAdd

Render2D

Performs 2D rendering.

method Render2D (Graphics g)
params g [not-null] The graphics object to use.
inherited IRenderable2D.Render2D

Remarks:

When this method is called, the given Graphics object has already been initialized for 2D rendering:

Usually, Render2D is called from within Render.

UpdateFrameTime

This method is called once per application frame.

method UpdateFrameTime (float32 time)
type bool
params time [>0] The amount of time that has elapsed since the last frame, in seconds.
returns true if the object needs to be presented again, false if the current presentation is still valid.
inherited IUpdateableFrameTime.UpdateFrameTime