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

class ApplicationWindow in Tinman.Engine.Application

Default implementation of the IApplicationWindow interface that represents a native window.

class ApplicationWindow extends ApplicationWindowBase

Remarks

The returned INativeHandle can be interpreted as follows:

To create a new top-level window, use Create. To wrap an embedded native window (for example an MFC control), create a subclass and perform callbacks from the native windows message loop, for example by calling OnMessage_Win32.

Protected / Attributes

ClientRect

Returns the bounds of the application windows client area.

protected override sealed 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

MouseButtons

Returns the states of the mouse buttons.

protected override sealed property MouseButtons { get }
type int32
value The mouse button state bitmask:
1: left
2: right
4: middle
implements ApplicationWindowBase.MouseButtons

MouseClip

The mouse cursor clip rectangle.

protected override sealed property MouseClip { get set }
type Box2I
value The clip rectangle, in screen coordinates.
implements ApplicationWindowBase.MouseClip

mousePosition

Relative position of mouse cursor in application window client area.

protected field mousePosition
type Vec2I
inherited ApplicationWindowBase.mousePosition

MousePosition

Position of the mouse cursor.

protected override sealed property MousePosition { get set }
type Vec2I
value The mouse cursor position, in screen coordinates.
implements ApplicationWindowBase.MousePosition

MouseVisible

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

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

windowHandle

The native window handle.

protected field windowHandle
type IntPtr

Protected / Constructors

ApplicationWindow

Creates a new instance of ApplicationWindow.

protected constructor ApplicationWindow (IntPtr windowHandle)
params windowHandle The native window handle.

Exceptions:

Protected / Methods

DisposeResources

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

protected override method DisposeResources ()
inherited 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.

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

KeyCodeMap_Win32

Creates the virtual keycode mapping for the WIN32 API.

protected method KeyCodeMap_Win32 ()
inherited ApplicationWindowBase.KeyCodeMap_Win32

See also:

ApplicationWindowBase.KeyCodeMap

MouseCursorSet

Sets the mouse cursor for the window.

protected override sealed method MouseCursorSet (MouseCursor mouseCursor)
params mouseCursor The new mouse cursor.
implements ApplicationWindowBase.MouseCursorSet

MouseTrack

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

protected override sealed method MouseTrack ()
implements ApplicationWindowBase.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?
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

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

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

Re-creates the native window.

[EmptyBody]
protected virtual method RecreateNativeWindow ()
inherited ApplicationWindowBase.RecreateNativeWindow

See also:

ApplicationWindowBase.recreateNativeWindow

Exceptions:

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

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

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.
inherited ApplicationWindowBase.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.
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 sealed 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, EventDelegateGeneric<IApplicationWindow> onProcessSystemMessages = null)
type IApplicationWindow
params title The window title.
  clientSize The initial client size (see Resize)
  onProcessSystemMessages Optional delegate that will be invoked when ProcessSystemMessages is called. This is intended for special use-cases, for example when mixing a top-level application window with WinForms: then, the System.Windows.Forms.Application.DoEvents method must be called in addition to the plain WIN32 message loop of the top-level window. Defaults to null.
returns [not-null] The application window.

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

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:

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 sealed 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 (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.
inherited ApplicationWindowBase.RecreateNativeWindowIfNecessary

See also:

INativeWindowRecreate.RecreateNativeWindowIsNecessary

Exceptions:

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.
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 (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 be enter full-screen mode, if possible (see Fullscreen).
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.
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 ()
inherited ApplicationWindowBase.Restore

Remarks:

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