IWidget

Description

interface Tinman.Engine.Widgets.IWidget

Derived from

IDisposable
IUpdateableFrameTime
IGraphicsComponent
IRenderable
IRenderable2D
IInputConsumerEx
IJsonizable
IConfigurable
IWidgetGuiConsumer
IUpdateableGui
IApplicationRunnerConsumer
IProfilerConsumer
INonUserInterfaceBounds
IHelpProvider
ILocalizable

Extended by

Widget abstract

Base interface for general-purpose application widgets.

After creating a IWidget instance, the SettingsPath may be specified while the object is in the LifecycleState.Created state. Calling Initialize will put it into the LifecycleState.Initialized state, where the settings path cannot be changed any more. As best practice, initialization code that does not depend on any settings and does complete quickly should be placed into the constructor, the remaining code should be put into Initialize.

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.

The ILocalizable.Localize2 will store the given labels in an own set that belongs to the widget. The ILocalizable.Localize1 method will delegate to the attached widget GUI (see IWidgetGuiConsumer.WidgetGuiAttach), if a label is not present in that set.

See also

IWidget.Initialize

Public / Methods

Initialize

[ThrowAny]
public method Initialize → ()

returns → bool

true if the object has been initialized,
false if the object has already been initialized before.

Initializes the widget, if necessary.

See also

IWidget.SettingsPath

Screenshot

public method Screenshot → (1)

result in : WidgetScreenshotDelegate

[not-null]
The screenshot pixels will be passed to this delegate.

Takes a screenshot the next time this widget is rendered.

Settings​Load​Try

public method SettingsLoadTry → (1)

name opt : string = null

Name of the JSON configuration file. If null or empty, 'Settings.json' will be used.

returns → bool

true if the settings have been loaded, false if not.

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

See also

IWidget.SettingsPath

Settings​Save​Try

public method SettingsSaveTry → (1)

name opt : string = null

Name of the JSON configuration file. If null or empty, 'Settings.json' will be used.

returns → bool

true if the settings have been saved, false if not.

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

See also

IWidget.SettingsPath

Public / Attributes

Actual​Bounds

public attribute ActualBounds → (get)

value : Box2I

The actual pixel bounds or Box2I.Empty.

Returns the actual pixel bounds of this widget.

Bounds

public attribute Bounds → (get,set)

value : IWidgetBounds

[not-null]
The pixel bounds.

The pixel bounds of this widget.

Defaults to WidgetBounds.FullScreen.

Mouse​Cursor

public attribute MouseCursor → (get)

value : MouseCursor

The mouse cursor

The mouse cursor to show for this widget.

Settings​Path

public attribute SettingsPath → (get,set)

value : Path

Canonical path to the settings directory or null.

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

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

See also

IWidget.SettingsLoadTry
IWidget.SettingsSaveTry

Extensions

Render2​DWith​Setup

public static method Render2DWithSetup → (1)

g in : Graphics

[not-null]
The graphics object to use.

Calls IRenderable2D.Render2D of this IWidget after having performed the necessary setup.

The setup involves these steps:

  1. Call IBeginEnd.Begin on g in.

  2. Set Graphics.Bounds of g in to IWidget.ActualBounds.

  3. Delegate to IRenderable2D.Render2D of this widget, passing g in.

  4. Call IBeginEnd.End on g in.

Run

[OwnerThis]
public static method Run → (5)

source in : string

[not-empty]
The error source to use in case an exception is thrown.

context in : IGraphicsContextFactory

[not-null]
The graphics context factory to use.

window in : IApplicationWindow own

[not-null]
The application window to use.

frameRateLimit opt : int32 = 100

Frame rate limit (see IApplicationInfo.FrameRateLimit).

sleepOnIdle opt : bool = true

Honour ApplicationLoopResult.Idle by sleeping for a short time?

returns → TinmanError

The error in case of a crash, null if the application has ended normally.

Runs this IWidget in a separate window.

Settings​Load

public static method SettingsLoad → (1)

name opt : string = null

Name of the JSON configuration file. If null or empty, 'Settings.json' will be used.

returns → Path

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.

Loads the settings of this widget.

IOException

If an I/O error has occurred while reading the settings file.

ValidatingException

If the contents of the settings file is malformed.

Settings​Save

public static method SettingsSave → (1)

name opt : string = null

Name of the JSON configuration file. If null or empty, 'Settings.json' will be used.

returns → Path

Canonical path of the settings file that has been loaded or null if the widget does not have a settings directory.

Saves the settings of this widget.

IOException

If an I/O error has occurred while writing the settings file.

To​Application

[OwnerReturn] [OwnerThis]
public static method ToApplication → (1)

frameRateLimit opt : int32 = 100

Frame rate limit (see IApplicationInfo.FrameRateLimit).

returns → WidgetApplication

The application object.

Wraps this IWidget in a IApplication object.