Software Development Kit - User Manual

interface IWidgetGui in Tinman.Engine.Widgets

Provides a graphical user interface for IWidget s.

interface IWidgetGui extends IDisposable
  base of WidgetGui


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:




The pixel bounds of th widget GUI.

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


Returns the identifier of the current dialog.

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


Is there a current dialog?

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


Does the widget GUI have input focus?

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


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

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


Returns the lifecycle state of this object.

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


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


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


Returns the root container of the widget GUI.

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



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


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.



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:



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:



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


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


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:



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.


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


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

Implementing methods must not throw any exceptions.


Clears the input focus of the widget GUI.

method FocusClear ()


Attaches this component to the given Graphics context.

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


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.


Detaches this user interface component from its Graphics context.

method GraphicsDetach ()
inherited IGraphicsComponent.GraphicsDetach


All graphics-related resources should be disposed here.


The screen size has changed.

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


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.


Restores the object state from the given JSON value.

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


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


Serializes the object state to an JSON value.

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


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:



Removes a panel from the widget GUI.

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

See also:



Performs 2D rendering.

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


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

Usually, Render2D is called from within Render.


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