class Widget in Tinman.AddOns.Widgets

Abstract base class for IWidget implementations.

class	Widget	extends	Initializable
		implements	IWidget
		base of	CanvasWidget
			ModelWidget
			TerrainViewWidget
			TestWidget
			Tutorial
			TutorialBrowser

Remarks

The default implementation of Render prepares 2D rendering and calls Render2D.

The default implementation of Render2D just calls Render2D on the root GUI container (if present) and then returns.

Configuration

Config

The configurator object for this type.

public static property	Config { get }
type	IConfigurator<IWidget>
value	[not-null]	The configurator object.

ToConfig

Returns the configuration value that describes this object.

public virtual method	ToConfig ()
type	ConfigValue
returns		[not-null]	The configuration value.
implements	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.

Public / Attributes

ActualBounds

Returns the actual pixel bounds of this widget.

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

Bounds

The pixel bounds of this widget.

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

Remarks:

Defaults to FullScreen.

LifecycleState

Returns the lifecycle state of this object.

public override property	LifecycleState { get }
type	LifecycleState
value		The lifecycle state.
inherited	Initializable.LifecycleState

MouseCursor

The mouse cursor to show for this widget.

public virtual property	MouseCursor { get }
type	MouseCursor
value		The mouse cursor
implements	IWidget.MouseCursor

NonUserInterfaceBounds

Returns the central part of the actual pixel bounds of this widget which is not occluded by the widget user interface.

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

See also:

IWidget.AddUserInterface

SettingsAuto

Specifies the behaviour for automatically loading and saving of widget settings.

public property	SettingsAuto { get set }
type	int32
value		A combination of the following bit flags: 1: load settings when after widget has been initialized. 2: save settings when widget consumes Closing.

Remarks:

Defaults to 3.

SettingsPath

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

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

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?

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

See also:

IApplicationWindow.MouseCaptured

UserInterfaceCenterOffset

Computes an offset for the screen center that can be used to compensate for the GUI overlay of this widget.

public property	UserInterfaceCenterOffset { get }
type	Vec2F
value		The screen center offset, in pixels.

See also:

CameraViewport.CenterOffset

Public / Constructors

Widget

Creates a new instance of Widget.

public constructor

Widget ()

Public / Methods

AcquireTry

Acquires a strong reference to this disposable object.

[OwnerReturn, ThreadSafe]
public method	AcquireTry ()
type	IDisposable
returns			this if a new strong reference has been acquired, null if this object is already being disposed.
inherited	Disposable.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.

public 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.
implements	IWidget.AddUserInterface

ConsumeInput

Consumes the given user input event.

public method	ConsumeInput (InputEvent inputEvent)
type	bool
params	inputEvent		The user input event.
returns			true if the input event has been consumed, false if not.
implements	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]
public method	Dispose ()
inherited	Disposable.Dispose

Remarks:

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

GraphicsAttach

Attaches this component to the given Graphics context.

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

Remarks:

All graphics-related resources should be created here.

GraphicsDetach

Detaches this user interface component from its Graphics context.

public virtual method	GraphicsDetach ()
implements	IGraphicsComponent.GraphicsDetach

Remarks:

All graphics-related resources should be disposed here.

GraphicsResize

The screen size has changed.

public method	GraphicsResize (Vec2I screenSize)
params	screenSize		The new screen size, in pixels.
implements	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

public method	Initialize ()
inherited	Initializable.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.

public virtual method	InputAttach (IInputState input)
params	input	[not-null]	The input state object.
implements	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.

public virtual method	InputDetach ()
implements	IInputConsumerEx.InputDetach

JsonDeserialize

Restores the object state from the given JSON value.

public virtual method	JsonDeserialize (JsonValue value)
params	value	[not-null]	The input JSON value.
implements	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.

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

Render

Performs rendering.

public virtual method	Render ()
implements	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.

public virtual method	Render2D (Graphics g)
params	g	[not-null]	The graphics object to use.
implements	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.

public virtual method	RenderPrepare ()
implements	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.

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

UpdateFrameTime

This method is called once per application frame.

public virtual 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.
implements	IUpdateableFrameTime.UpdateFrameTime

UpdateGui

public virtual method	UpdateGui ()
implements	IUpdateableGui.UpdateGui

Protected / Attributes

components

General purpose list of child components.

[Owner]
protected field	components
type	ObjectList

Remarks:

Subclasses are responsible for initializing this object list.

context

The current IGraphicsContext object or null.

protected field	context
type	IGraphicsContext

See also:

GraphicsAttach
GraphicsDetach

graphics

The current Graphics object or null.

protected field	graphics
type	Graphics

See also:

GraphicsAttach
GraphicsDetach

input

The input state object or InputNone if no input state object has been attached (thus never null).

protected field	input
type	IInputState

See also:

InputAttach
InputDetach

inputModifiers

The current input modifiers.

protected field	inputModifiers
type	InputModifiers

Remarks:

These flags are maintained when ConsumeInput is called.

mouse

Current position of mouse cursor.

protected field	mouse
type	Vec2I

screenLabels

Helper object for placing labels on the screen while avoiding overlaps.

protected field	screenLabels
type	ScreenLabelPlacement

Protected / Methods

Dirty

Marks the widget as dirty.

protected method

Dirty ()

Remarks:

When a widget is dirty, the next call to UpdateFrameTime will always return true and the dirty flag will be cleared.

DisposeManaged

Disposes the managed resources held by a concrete subclass. This method will be called at most once per subclass.

protected override method	DisposeManaged ()
overrides	Disposable.DisposeManaged

Remarks:

This method will only be called when a disposable object is explicitly destroyed by user code calling the Dispose method. It will not be called when the object is collected as garbage by the system.

Overriding methods must call the DisposeManaged method of their base class. The base call should be the last statement.

The DisposeManaged method is called before the DisposeUnmanaged method.

DisposeUnmanaged

Disposes the unmanaged resources held by a concrete subclass. This method will be called exactly once per subclass.

protected virtual method	DisposeUnmanaged ()
inherited	Disposable.DisposeUnmanaged

Remarks:

Overriding methods must call the DisposeUnmanaged method of their base class. The base call should be the last statement.

The DisposeUnmanaged method is called after the DisposeManaged method.

DoConsumeInput

Consumes the given user input event.

[EmptyBody]
protected virtual method	DoConsumeInput (InputEvent inputEvent)
type	bool
params	inputEvent		The user input event.
returns			true if the input event has been consumed, false if not.

Remarks:

The given inputEvent has already been translated to the current widget bounds (see BoundedInput).

DoInitialize

Performs initialization.

protected virtual method	DoInitialize ()
inherited	Initializable.DoInitialize

Remarks:

Overriding methods must call the DoInitialize method of their base class. The base call should be the first statement.

Initialized

This method is called when this object has been initialized completely, i.e. after the DoInitialize call and just before returning from Initialize.

[EmptyBody]
protected override method	Initialized ()
overrides	Initializable.Initialized

Settings

Returns a path into the settings directory of this widget, creating parent directories if necessary.

protected method	Settings (string path)
type	Path
params	path	[not-empty]	Relative path into settings directory.
returns		[not-null]	The canonical settings path.

---

Returns a path into the settings directory of this widget, creating parent directories if necessary.

protected method	Settings (Path path)
type	Path
params	path	[not-null]	Relative path into settings directory.
returns		[not-null]	The canonical settings path.

SizeChanged

The pixel size of this widget has changed.

[EmptyBody]
protected virtual method	SizeChanged (Vec2I size)
params	size		The new pixel size.

Remarks:

This method is called in these cases:

• When GraphicsResize is called.
• When the Bounds property is changed while attached and the resulting pixel bounds have a different size.
• When the UpdateFrameTime method is called while attached and the widget bounds version (see Version) has changed.

Logging

Logger

The logger object of this class.

public static readonly field	Logger
type	ILogger