class ApplicationWindowBase in Tinman.Engine.Application

Abstract base class for IApplicationWindow implementations.

abstract class	ApplicationWindowBase	extends	Disposable
		implements	IApplicationWindow
		base of	ApplicationWindow

Remarks

To implement an application window, the following steps are necessary:

• Implement all abstract members.
• Use KeyCodeMap (preferably in the constructor) to establish a mapping between key codes of the native API and the KeyboardKey enumeration.
• Setup event handlers using the native API and call into the On* handler methods.

When implementing a top-level application window, the following no-op virtual members should be overridden:

• IsTopLevel
• NativeHandle
• NativeHandleType
• RecreateNativeWindow
• Resize
• Restore
• State
• Title

Protected / Attributes

ClientRect

Returns the bounds of the application windows client area.

protected abstract property	ClientRect { get }
type	Box2I
value		The client area rectangle, in screen coordinates.

dirty

Can be set to true in order to make the next call to ProcessSystemMessages return true once.

protected field	dirty
type	bool

MouseButtons

Returns the states of the mouse buttons.

protected abstract property	MouseButtons { get }
type	int32
value		The mouse button state bitmask: 1: left 2: right 4: middle

MouseClip

The mouse cursor clip rectangle.

protected abstract property	MouseClip { get set }
type	Box2I
value		The clip rectangle, in screen coordinates.

mousePosition

Relative position of mouse cursor in application window client area.

protected field	mousePosition
type	Vec2I

MousePosition

Position of the mouse cursor.

protected abstract property	MousePosition { get set }
type	Vec2I
value		The mouse cursor position, in screen coordinates.

MouseVisible

Shows or hides the mouse cursor when hovering the application window.

protected abstract property	MouseVisible { set }
type	bool
value		true to show the mouse cursor, false to hide it.

Protected / Constructors

ApplicationWindowBase

Creates a new instance of ApplicationWindow.

protected constructor

ApplicationWindowBase ()

Protected / Methods

DisposeResources

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

protected override method	DisposeResources ()
overrides	Disposable.DisposeResources

Remarks:

This method will be called as soon as all ownership references to this instance have been relinquished by calls to the Dispose method.

The system may garbage collect an instance of IDisposable iff there are no more references to it. In this case, the DisposeResources will be called, in order to avoid dangling resources. However, it is not advisable to rely on the garbage collection of the system, as the behaviour may differ significantly between environments. Instead, ownership rules should be obeyed, which effectively removes the need for automatic garbage collection.

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

InitializeBegin

Begins to initialize this object.

protected method	InitializeBegin ()
type	bool
returns			true if initialization must be performed, false if initialization has already been performed.
inherited	Disposable.InitializeBegin

InitializeRequired

Has this object been initialized?

protected method	InitializeRequired ()
type	bool
returns			true if Initialize has already been called, false if not.
inherited	Disposable.InitializeRequired

KeyCodeMap

Maps the given native virtual keycode to the specified KeyboardKey value.

protected method	KeyCodeMap (int32 keyCode, KeyboardKey key)
params	keyCode		The native virtual keycode.
	key		The KeyboardKey value.

KeyCodeMap_Win32

Creates the virtual keycode mapping for the WIN32 API.

protected method

KeyCodeMap_Win32 ()

See also:

KeyCodeMap

MouseCursorSet

Sets the mouse cursor for the window.

protected abstract method	MouseCursorSet (MouseCursor mouseCursor)
params	mouseCursor		The new mouse cursor.

MouseTrack

This method ensures that events are generated when the mouse cursor leaves the window.

protected abstract method

MouseTrack ()

OnButton

A mouse button event has been received.

protected method	OnButton (MouseButton button, bool pressed)
params	button		The mouse button.
	pressed		Pressed or released?

OnChar

A character value has been typed in.

protected method	OnChar (char keyChar)
params	keyChar		The character value.

OnKey

A keyboard key has been pressed or released.

protected method	OnKey (int32 keyCode, bool pressed)
params	keyCode		The native virtual keycode.
	pressed		true if the key has been pressed, false if it has been released.

OnMessage_Win32

Processes a window message of the WIN32 API and calls the required handler methods.

protected method	OnMessage_Win32 (int32 msg, int64 wParam, int64 lParam)
type	bool
params	msg		Message code.
	wParam		Message WPARAM.
	lParam		Message LPARAM.
returns			true if the message has been consumed, false if not.

Remarks:

If this method returns true, the WIN32 window procedure should return 0.

OnMouseLeave

The mouse cursor has left the application window client area.

protected method	OnMouseLeave ()
type	bool
returns			true if the MouseLeave event has been sent, false if not.

OnMouseMove

The mouse has moved.

protected method	OnMouseMove (int32 positionX, int32 positionY, int32 wheel)
params	positionX		X-coordinate of new position of mouse cursor in application window client area.
	positionY		Y-coordinate of new position of mouse cursor in application window client area.
	wheel		The mouse wheel movement.

OnWindowBoundsChanged

The bounds of the application window have changed.

protected virtual method

OnWindowBoundsChanged ()

OnWindowFocus

The application window has gained or lost focus.

protected method	OnWindowFocus (bool focussed)
params	focussed		true if the window has gained focus, false if it has lost it.

RecreateNativeWindow

Re-creates the native window.

[EmptyBody]
protected virtual method	RecreateNativeWindow ()

See also:

recreateNativeWindow

Exceptions:

• RenderException:
  If a graphics subsystem error has occurred.

Public / Attributes

ClientSize

The current size of the application window client area.

public property	ClientSize { get }
type	Vec2I
value		The size of the window client area.
implements	INativeWindow.ClientSize

InputSettings

The current settings for processing raw input events.

public property	InputSettings { get set }
type	InputSettings
value		The input settings.
implements	IApplicationWindow.InputSettings

Remarks:

Defaults to Default.

IsFocused

Does the application window currently have the input focus?

public property	IsFocused { get }
type	bool
value		true if the application has the input focus, false if not.
implements	IApplicationWindow.IsFocused

IsMouseInside

Is the mouse cursor currently inside the windows client area?

public property	IsMouseInside { get }
type	bool
value		true if the mouse cursor is inside the client area, false if it is outside.
implements	IApplicationWindow.IsMouseInside

IsRecreateNativeWindow

Is the native window being re-created in a call to RecreateNativeWindowIfNecessary?

public property	IsRecreateNativeWindow { get }
type	bool
value		true if the native window is being re-created, false if not.

IsSoleOwnership

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

[ThreadSafe]
public 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 AcquireThrow).
inherited	Disposable.IsSoleOwnership

IsTopLevel

Is this a top-level window?

public virtual property	IsTopLevel { get }
type	bool
value		true if this is a top-level window, false if not, for example a control embedded in some GUI form.
implements	IApplicationWindow.IsTopLevel

Remarks:

Top-level windows can be put into full-screen mode and can be maximized.

LifecycleState

Returns the lifecycle state of this object.

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

MouseCaptured

Is the mouse currently captured by the application window?

public property	MouseCaptured { get set }
type	bool
value		true if the mouse is currently captured, false if not.
implements	IApplicationWindow.MouseCaptured

Remarks:

While the mouse cursor is captured, the application exhibits the following behaviour:

• The mouse cursor is not visible and cannot leave the application window, therefore it is not possible to accidentally transfer input focus to another window.
• The mouse cursor is locked at the center of the application window client area. This way unbounded relative mouse movement can be consumed.

MouseCursor

The mouse cursor to show inside the application window.

public property	MouseCursor { get set }
type	MouseCursor
value		The mouse cursor.
implements	IApplicationWindow.MouseCursor

Remarks:

The default value is Default.

NativeHandle

Returns the raw handle value of the native resource that is contained in this object.

public virtual property	NativeHandle { get }
type	IntPtr
value		The raw handle value.
implements	INativeHandle.NativeHandle

Remarks:

The documentation of the implementing class will contain information on how to interpret the raw handle value.

NativeHandleType

Returns the native handle type of this window.

public virtual property	NativeHandleType { get }
type	NativeHandleType
value		The native handle type.
implements	INativeWindow.NativeHandleType

Remarks:

The handle type depicts how to interpret NativeHandle.

OnInput

Returns the source for input event.

public property	OnInput { get }
type	IEventGeneric<InputEvent>
value	[not-null]	The input event source.
implements	IApplicationWindow.OnInput

State

Returns the current state of the application window.

public virtual property	State { get }
type	WindowState
value		The current state.
implements	IApplicationWindow.State

Title

The current window title.

public virtual property	Title { get set }
type	string
value		The window title or null.
implements	IApplicationWindow.Title

Remarks:

If the title of an application window cannot be set by code (e.g. it is not a top-level window), the title will remain unchanged.

Public / Methods

Acquire

Acquires a strong reference to this disposable object.

[OwnerReturn, Pure]
public method	Acquire ()
type	IApplicationWindow
returns			The strong reference to this disposable object or null iff this object is no longer valid.

Remarks:

The object will not be actually disposed by calls to Dispose when there is at least one strong reference left. Code that calls this 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.

AcquireBase

Acquires a strong reference to this disposable object.

[OwnerReturn, Pure]
public method	AcquireBase ()
type	IDisposable
returns			The strong reference to this disposable object or null iff this object is no longer valid.
inherited	Disposable.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.

AcquireThrow

Acquires a strong reference to this disposable object.

[OwnerReturn, Pure]
public method	AcquireThrow ()
type	IDisposable
returns		[not-null]	The strong reference to this disposable object.
inherited	Disposable.AcquireThrow

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.

Exceptions:

• TinmanException:
  If this object is no longer valid.

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.

Implementing methods must not throw any exceptions.

Focus

Tries to acquire input focus.

public abstract method	Focus ()
type	bool
returns			true if the input focus has been acquired, false if not.
overrides	IApplicationWindow.Focus

IsDown

Is the given keyboard key pressed down?

[Pure]
public method	IsDown (KeyboardKey key)
type	bool
params	key		The keyboard key.
returns			true if the key is pressed down, false if not.
implements	IInputState.IsDown

---

Is the given mouse button pressed down?

[Pure]
public method	IsDown (MouseButton button)
type	bool
params	button		The mouse button.
returns			true if the button is pressed down, false if not.
implements	IInputState.IsDown

ProcessSystemMessages

Processes all system messages for this window.

public virtual method	ProcessSystemMessages ()
type	bool
returns			true if the window client area is dirty, false if not.
implements	IApplicationWindow.ProcessSystemMessages

RecreateNativeWindowIfNecessary

Re-creates the underlying native window, if necessary.

public method	RecreateNativeWindowIfNecessary (string token)
params	token	[not-null]	A user-defined token that describes the calling code. For equal tokens, the underlying native window will never be re-created.
implements	INativeWindowRecreate.RecreateNativeWindowIfNecessary

See also:

INativeWindowRecreate.RecreateNativeWindowIsNecessary

Exceptions:

• RenderException:
  If a graphics subsystem error has occurred.

RecreateNativeWindowIsNecessary

The underlying native window needs to be re-created.

public method	RecreateNativeWindowIsNecessary (string token)
params	token	[not-null]	A user-defined token that describes the calling code. For equal tokens, the underlying native window will never be re-created.
implements	INativeWindowRecreate.RecreateNativeWindowIsNecessary

See also:

INativeWindowRecreate.RecreateNativeWindowIfNecessary

RequestClose

Requests to close the application by feeding it with an Closing input event.

public method	RequestClose ()
implements	IRequestClose.RequestClose

Resize

Tries to change the current size of the application windows client area.

public virtual method	Resize (Vec2I size)
params	size		The new size of the window client area (see Normal. If X or Y is negative, the window will be maximized, if possible (see Maximized). If X or Y is zero, the window will enter full-screen mode, if possible (see Fullscreen).
implements	IApplicationWindow.Resize

Remarks:

If the client size of an application window cannot be set by code (e.g. it is not a top-level window), the client size will remain unchanged and the State property will be Normal.
If full-screen mode is not available, the window will be maximized instead, if possible.

Restore

Restores the previous window state.

public virtual method	Restore ()
implements	IApplicationWindow.Restore

Remarks:

Depending on the current window state (see State), the Restore performs the following actions:

• Fullscreen:
  The window is restored to the state it had before entering full-screen mode, which may be normal or maximized mode.
• Maximized:
  The window is restored to the most recent size and position it had in normal mode.
• Hidden:
  The window is restored to the most recent size and position it had in normal mode.
• Normal:
  The method returns silently.