interface IWidget in Tinman.AddOns.Widgets

Base interface for generic application widgets.

interface	IWidget	extends	IConfigurable
			IGraphicsComponent
			IInitializable
			IInputConsumerEx
			IJsonizable
			IRenderable
			IRenderable2D
			IUpdateableFrameTime
			IUpdateableGui
		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.

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 central part of the actual pixel bounds of this widget which is not occluded by the widget user interface.

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

See also:

AddUserInterface

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 must be set before Initialize is called on the widget. Afterwards, the settings path cannot be changed.

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

AcquireTry

Acquires a strong reference to this disposable object.

[OwnerReturn, ThreadSafe]
method	AcquireTry ()
type	IDisposable
returns			this if a new strong reference has been acquired, null if this object is already being disposed.
inherited	IDisposable.AcquireTry

Remarks:

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

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

AddUserInterface

Adds a GUI panel to this widget.

method	AddUserInterface (WidgetSlot slot, [Owner] Panel panel)
params	slot		The widget GUI slot where the given GUI panel will be put.
	panel	[not-null]	The GUI panel to add.

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:
   • Pressed: key has been pressed down.
   • Released: key has been released.
   • Clicked: key has been clicked.
   • Character: a character has been typed.
3. Mouse events:
   1. MouseEnter
   2. Mouse events:
      • Pressed
      • Released
      • Clicked
      • MouseMove
   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.

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.

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

Remarks:

The given screen size is equal to the value of ScreenSize of the Graphics object that has been passed to GraphicsAttach earlier.

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.

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

Render

Performs rendering.

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.

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:

• The render bounds have been specified (see Bounds).
• The Begin method has already been called.
• Clipping and translation have been applied, so that (0|0) refers to the top-left pixel of the target rectangle and ScreenSize returns the target rectangle size. The target rectangle and the clipping rectangle can be different.

Usually, Render2D is called from within Render.

RenderPrepare

Prepares rendering.

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.

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.

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.

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

method	UpdateGui ()
inherited	IUpdateableGui.UpdateGui

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)
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.
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)
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.
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.

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.

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.