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

class ApplicationWindow in Tinman.Engine.Application

Default implementation of the IApplicationWindow interface.

class ApplicationWindow extends ApplicationWindowBase

Private / Constructors

ApplicationWindow

Creates a new instance of ApplicationWindow.

[Internal]
public constructor ApplicationWindow (IntPtr windowHandle)
params windowHandle The native window handle.

Private / Methods

Win32_Message

Processes a window message of the WIN32 API.

[Internal]
public method Win32_Message (int32 msg, int32 wParam, int32 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.

Public / Attributes

ClientSize

The current size of the application windows client area.

public virtual property ClientSize { get }
type Vec2I
value The size of the window client area.
inherited ApplicationWindowBase.ClientSize

InputSettings

The current settings for processing raw input events.

public property InputSettings { get set }
type InputSettings
value The input settings.
inherited ApplicationWindowBase.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.
inherited ApplicationWindowBase.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.
inherited ApplicationWindowBase.IsMouseInside

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 AcquireBase).
inherited Disposable.IsSoleOwnership

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.
inherited ApplicationWindowBase.MouseCaptured

Remarks:

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

MouseCursor

The mouse cursor to show inside the application window.

public property MouseCursor { get set }
type MouseCursor
value The mouse cursor.
inherited ApplicationWindowBase.MouseCursor

Remarks:

The default value is Default.

NativeHandle

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

public override property NativeHandle { get }
type IntPtr
value The raw handle value.
implements ApplicationWindowBase.NativeHandle

Remarks:

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

OnInput

Returns the source for input event.

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

State

Returns the current state of the application window.

public virtual property State { get }
type WindowState
value The current state.
inherited ApplicationWindowBase.State

Title

The current window title.

public virtual property Title { get set }
type string
value The window title or null.
inherited ApplicationWindowBase.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 / Constructors

Create

Creates a new top-level window.

[OwnerReturn]
public static method Create (string title, Vec2I clientSize)
type IApplicationWindow
params title The window title.
  clientSize The client size. If the size is Zero, the window will cover the screen.
returns [not-null] The application window.

Public / Methods

Acquire

Acquires a strong reference to this disposable object.

[OwnerReturn, Pure]
public method Acquire (bool allowNull = false)
type IApplicationWindow
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 ApplicationWindowBase.Acquire

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.

Exceptions:

AcquireBase

Acquires a strong reference to this disposable object.

[OwnerReturn, Pure]
public 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 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.

Exceptions:

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 override method Focus ()
type bool
returns true if the input focus has been acquired, false if not.
implements ApplicationWindowBase.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.
inherited ApplicationWindowBase.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.
inherited ApplicationWindowBase.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.
inherited ApplicationWindowBase.ProcessSystemMessages

RecreateNativeWindowIfNecessary

Re-creates the underlying native window, if necessary.

public method RecreateNativeWindowIfNecessary ()
inherited ApplicationWindowBase.RecreateNativeWindowIfNecessary

See also:

INativeWindowRecreate.RecreateNativeWindowIsNecessary

RecreateNativeWindowIsNecessary

The underlying native window needs to be re-created.

public method RecreateNativeWindowIsNecessary ()
inherited ApplicationWindowBase.RecreateNativeWindowIsNecessary

See also:

INativeWindowRecreate.RecreateNativeWindowIfNecessary

RequestClose

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

public method RequestClose ()
inherited ApplicationWindowBase.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. Set to Zero to enable full-screen mode. Use any non-zero value to enter windowed mode.
inherited ApplicationWindowBase.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.

Protected / Attributes

ClientRect

Returns the bounds of the application windows client area.

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

dirty

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

protected field dirty
type bool
inherited ApplicationWindowBase.dirty

mousePosition

Relative position of mouse cursor in application window client area.

protected field mousePosition
type Vec2I
inherited ApplicationWindowBase.mousePosition

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

DoRecreateNativeWindow

[EmptyBody]
protected virtual method DoRecreateNativeWindow ()

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.
inherited ApplicationWindowBase.KeyCodeMap

MouseCursorSet

protected override method MouseCursorSet (MouseCursor mouseCursor)
params mouseCursor
implements ApplicationWindowBase.MouseCursorSet

OnButton

protected method OnButton (MouseButton button, bool pressed)
params button
  pressed
inherited ApplicationWindowBase.OnButton

OnChar

A character value has been typed in.

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

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.
inherited ApplicationWindowBase.OnKey

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.
inherited ApplicationWindowBase.OnMouseLeave

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.
inherited ApplicationWindowBase.OnMouseMove

OnWindowBoundsChanged

The bounds of the application window have changed.

protected method OnWindowBoundsChanged ()
inherited ApplicationWindowBase.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.
inherited ApplicationWindowBase.OnWindowFocus

RecreateNativeWindow

[EmptyBody]
protected override sealed method RecreateNativeWindow ()
overrides ApplicationWindowBase.RecreateNativeWindow

SendInputEvent

Sends an input event to all registered listeners.

protected method SendInputEvent (InputEvent inputEvent)
params inputEvent The input event to send.
inherited ApplicationWindowBase.SendInputEvent