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

interface IWidget in Tinman.Engine.Widgets

Base interface for general-purpose application widgets.

interface IWidget extends IApplicationRunnerConsumer
  IConfigurable
  IGraphicsComponent
  IHelpProvider
  IInitializable
  IInputConsumerEx
  IJsonizable
  INonUserInterfaceBounds
  IProfilerConsumer
  IRenderable
  IRenderable2D
  IUpdateableFrameTime
  IUpdateableGui
  IWidgetGuiConsumer
  base of Widget

Remarks

Usually, an IApplication hosts one or more IWidget objects. Application input events are forwarded to widgets unmodified, i.e. the widget is responsible for translating them to its Bounds as necessary (e.g. using a BoundedInput object). Widgets are not required to limit their rendering to their bounds.

Attributes

ActualBounds

Returns the actual pixel bounds of this widget.

property ActualBounds { get }
type Box2I
value The actual pixel bounds or Empty.

Bounds

The pixel bounds of this widget.

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

Remarks:

Defaults to FullScreen.

HelpId

A machine-readable unique identifier for the user help of this component.

property HelpId { get }
type string
value The help ID or null if none.
inherited IHelpProvider.HelpId

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

MouseCursor

The mouse cursor to show for this widget.

property MouseCursor { get }
type MouseCursor
value The mouse cursor

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.

SettingsPath

Path to a directory that this widget can use to store own data and settings.

property SettingsPath { get set }
type Path
value Canonical path to the settings directory or null.

Remarks:

The settings path may only be set before Initialize is called on the widget. Afterwards, the settings path cannot be changed.

See also:

SettingsLoadTry
SettingsSaveTry

ShouldCaptureMouse

Should the mouse be captured, because this input consumer only processes relative input?

property ShouldCaptureMouse { get }
type bool
value true if the mouse should be captured, false if not.
inherited IInputConsumerEx.ShouldCaptureMouse

See also:

IApplicationWindow.MouseCaptured

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:

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

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.

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

Initialize

Initializes the object, if necessary.

method Initialize ()
inherited IInitializable.Initialize

Remarks:

The Initialize method returns silently if the object is already in the state Initialized.

Exceptions:

InputAttach

Attaches this input consumer to the given input state object.

method InputAttach (IInputState input)
params input [not-null] The input state object.
inherited IInputConsumerEx.InputAttach

Remarks:

The input state object provides a snapshot of the input keys and buttons. It should not be used to detect up/down/click events.

InputDetach

Detached this input consumer from its input state object.

method InputDetach ()
inherited IInputConsumerEx.InputDetach

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

ProfilerAttach

Attaches this object to the given profiler.

method ProfilerAttach (IProfiler profiler)
params profiler [not-null] The profiler to attach to.
inherited IProfilerConsumer.ProfilerAttach

ProfilerDetach

Detaches this object from its IProfiler object.

method ProfilerDetach ()
inherited IProfilerConsumer.ProfilerDetach

Render

Performs rendering of the next frame.

method Render ()
inherited IRenderable.Render

Remarks:

Implementing methods must not assume that any specific render state is in place when being called. Instead, the implementing method is responsible for setting up all state that is required for rendering.

Usually, implementing classes receive their current graphics context directly or indirectly from GraphicsContextAttach or GraphicsAttach.

In order to maximize parallelism between the CPU and GPU, only actual rendering (using the current graphics context) should be performed here. All other preparation resp. setup should be done in RenderPrepare instead.

It is not guaranteed that the GPU will have processed all render commands of the last frame when this method is called, in order to render the next one.

See also:

IApplication.GraphicsContextAttach
IGraphicsComponent.GraphicsAttach

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.

RenderPrepare

Prepares rendering of the next frame.

method RenderPrepare ()
inherited IRenderPreparable.RenderPrepare

Remarks:

This method is called before Render, when the graphics context has not yet begun to render the scene.

All setup work that does not require a graphics context (e.g. matrix computation, per-frame visibility determination) should be done here. This can help to maximize parallelism between the CPU and the GPU.

It is expected that the GPU is busy processing the render commands of the last frame, while this method prepares the next one.

RunnerAttach

Provides the enclosing IApplicationRunner.

method RunnerAttach (IApplicationRunner runner)
params runner [not-null] The application runner.
inherited IApplicationRunnerConsumer.RunnerAttach

Remarks:

Calling of this method is optional. Implementations of IApplication should not depend on the availability of an IApplicationRunner context object.

RunnerDetach

Clears the reference to the enclosing IApplicationRunner.

method RunnerDetach ()
inherited IApplicationRunnerConsumer.RunnerDetach

Screenshot

Takes a screenshot the next time this widget is rendered.

method Screenshot (WidgetScreenshotDelegate result)
params result [not-null] The screenshot pixels will be passed to this delegate.

SettingsLoadTry

Tries to load the settings of this widget, ignoring errors.

method SettingsLoadTry (string name = null)
type bool
params name Name of the JSON configuration file. If null or empty, 'Settings.json' will be used. Defaults to null.
returns true if the settings have been loaded, false if not.

See also:

SettingsPath

SettingsSaveTry

Tries to save the settings of this widget, ignoring errors.

method SettingsSaveTry (string name = null)
type bool
params name Name of the JSON configuration file. If null or empty, 'Settings.json' will be used. Defaults to null.
returns true if the settings have been saved, false if not.

See also:

SettingsPath

ToConfig

Returns the configuration value that describes this object.

method ToConfig ()
type ConfigValue
returns [not-null] The configuration value.
inherited IConfigurable.ToConfig

Remarks:

All configurable objects need to implement this interface. For simple types, it is preferable to delegate to ToValue.

The returned value may be of type Invalid, which means that this object in its current state cannot be described with the configuration API.

Before returning the resulting configuration value, Cache must be called on it, passing this IConfigurable object as parameter.

Exceptions:

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

UpdateGui

Updates GUI components, according to current values in the data model.

method UpdateGui (bool valuesOnly)
params valuesOnly true to update values in the existing GUI structure,
false to rebuild the GUI structure before updating values.
inherited IUpdateableGui.UpdateGui

Remarks:

Implementing method are expected to be fail-safe, i.e. their behaviour is well-defined, even if there is not GUI or the data model is empty. Thus, the UpdateGui method may be called at any time.

This method may be called repeatedly when valuesOnly is true. Implementing methods are expected to perform efficient in this case.

WidgetGuiAttach

Attaches this object to the given WidgetGui instance.

method WidgetGuiAttach (IWidgetGui widgetGui)
params widgetGui [not-null] The WidgetGui instance.
inherited IWidgetGuiConsumer.WidgetGuiAttach

Remarks:

As best practice, implementing classes should create their user interface components in this method and call PanelAdd accordingly.

The calls to WidgetGuiAttach resp. WidgetGuiDetach may be omitted, for example when running without a widget GUI overlay. Implementing classes must take this into account and should not rely on the premise that this method is always called.

WidgetGuiDetach

Detaches this object from its WidgetGui instance.

method WidgetGuiDetach ()
inherited IWidgetGuiConsumer.WidgetGuiDetach

Remarks:

Implementing classes must remove all panels via PanelRemove that they have added to the widget GUI.

Extensions

Run

Runs this IWidget in a separate window.

[OwnerThis]
method Run (string source, IGraphicsContextFactory context, string title = null, Vec2I size = default(Vec2I), int32 frameRateLimit = 100, bool sleepOnIdle = true)
type TinmanError
params source [not-empty] The error source to use in case an exception is thrown.
  context [not-null] The graphics context factory to use.
  title The window title or null.
  size The window client size. If Zero, the window will be full-screen.
  frameRateLimit Frame rate limit (see FrameRateLimit). Defaults to 100.
  sleepOnIdle Honor Idle by sleeping for a short time? Defaults to true.
returns The error in case of a crash, null if the application has ended normally.

Runs this IWidget in a separate window.

[OwnerThis]
method Run (string source, IVectorConst<IGraphicsContextFactory> contexts, string title = null, Vec2I size = default(Vec2I), int32 frameRateLimit = 100, bool sleepOnIdle = true)
type TinmanError
params source [not-empty] The error source to use in case an exception is thrown.
  contexts [not-empty] The graphics context factories to use.
  title The window title or null.
  size The window client size. If Zero, the window will be full-screen.
  frameRateLimit Frame rate limit (see FrameRateLimit). Defaults to 100.
  sleepOnIdle Honor Idle by sleeping for a short time? Defaults to true.
returns The error in case of a crash, null if the application has ended normally.

SettingsLoad

Loads the settings of this widget.

method SettingsLoad (string name = null)
type Path
params name Name of the JSON configuration file. If null or empty, 'Settings.json' will be used. Defaults to null.
returns Canonical path of the settings file that has been loaded or null if there were no previously saved settings or if the widget does not have a settings directory.

Exceptions:

SettingsSave

Saves the settings of this widget.

method SettingsSave (string name = null)
type Path
params name Name of the JSON configuration file. If null or empty, 'Settings.json' will be used. Defaults to null.
returns Canonical path of the settings file that has been loaded or null if the widget does not have a settings directory.

Exceptions:

ToApplication

Wraps this IWidget in an IApplication object.

[OwnerReturn, OwnerThis]
method ToApplication (int32 frameRateLimit = 100)
type WidgetApplication
params frameRateLimit Frame rate limit (see FrameRateLimit). Defaults to 100.
returns [not-null] The application object.