ApplicationWindow

Description

abstract class Tinman.Engine.Application.ApplicationWindow

Derived from

Disposable abstract
IApplicationWindow

Extended by

ApplicationWindow_WinAPI

Abstract base class for IApplicationWindow implementations.

To create a new top-level window, use Create or an IApplicationWindowFactory. To wrap an embedded native window or control, create a subclass and perform callbacks from the native windows message loop. For the latter case, several built-in implementations exist:

  • Tinman.AddOns.WinForms.ApplicationControl (C#)

  • Tinman.AddOns.WPF.ApplicationControlWpf (C#)

  • Tinman::AddOns::MFC::CApplicationControlMfc (C++)

To implement a new application window subclass, 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, these no-op members should be overridden:

The following platform-dependent helper methods may be used to implement the above:

Public / Constructors

Create

[OwnerReturn]
public static method Create → (4)

title opt : string = null

The window title or null to use the default title.

clientSize opt : Vec2I = default(Vec2I)

The initial client size (see IApplicationWindow.Resize).

flags opt : NativeHandleFlags = NativeHandleFlags.Any

The native handle types and features of the window that are acceptable to the caller, for example IGraphicsContextFactory.WindowFlags.

onProcessSystemMessages opt : EventDelegateGeneric<IApplicationWindow> = null

Optional delegate that will be invoked when IApplicationWindow.ProcessSystemMessages is called.

returns → IApplicationWindow

The application window.

Creates a new top-level window by delegating to IApplicationWindowFactory.CreateApplicationWindow of a suitable registered IApplicationWindowFactory instance.

TinmanException

If none of the registered factories was able to create a window or if TinmanEnginePrivileges.WindowOpen is not granted.

See also

ApplicationWindow.CreateNull

Create​Null

[OwnerReturn]
public static method CreateNull → (4)

title opt : string = null

The window title or null to use the default title.

clientSize opt : Vec2I = default(Vec2I)

The initial client size (see IApplicationWindow.Resize).

flags opt : NativeHandleFlags = NativeHandleFlags.Any

The native handle types and features of the window that are acceptable to the caller, for example IGraphicsContextFactory.WindowFlags.

onProcessSystemMessages opt : EventDelegateGeneric<IApplicationWindow> = null

Optional delegate that will be invoked when IApplicationWindow.ProcessSystemMessages is called.

returns → IApplicationWindow

The application window or null iff none of the registered factories was able to create a window or if TinmanEnginePrivileges.WindowOpen is not granted.

Creates a new top-level window by delegating to IApplicationWindowFactory.CreateApplicationWindow of a suitable registered IApplicationWindowFactory instance.

See also

ApplicationWindow.Create

Public / Attributes

Debug​Mouse​Position​Hack

[DebugHelper] [ShutdownClear]
public static attribute DebugMousePositionHack → (int32)

Enables or disables the code hack for the problem when the mouse position cannot be set.

Under some circumstances (for example, in a Remote Desktop session on Windows or when running X11 / Wayland in WSL2), trying to set the mouse position has no effect, although the system API reports success. As result, all user controls that depend on relative mouse movement become unusable. When the code hack is enabled, these controls do not reposition the mouse, which uglifies the user experience on the one hand but still provides a workable solution on the other hand.

See also

ApplicationWindow.NeedsMousePositionHack

Is​Recreate​Native​Window

public attribute IsRecreateNativeWindow → (get)

value : bool

true if the native window is being re-created, false if not.

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

Needs​Mouse​Position​Hack

public static attribute NeedsMousePositionHack → (get)

value : bool

true if the mouse position hack is needed, because setting the mouse position does not work in the current environment,
false if the mouse position hack is not needed.

Returns whether the mouse position hack is needed.

See also

ApplicationWindow.DebugMousePositionHack

Protected / Constructors

Application​Window

protected constructor ApplicationWindow → ()

Creates a new instance of ApplicationWindow.

Protected / Methods

Key​Code​Map

protected method KeyCodeMap → (2)

keyCode in : int32

The native virtual keycode.

key in : KeyboardKey

The KeyboardKey value.

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

Key​Code​Map_​Win​API

protected method KeyCodeMap_WinAPI → ()

Creates the virtual keycode mapping for the WIN32 API.

See also

ApplicationWindow.KeyCodeMap

Mouse​Capture

protected virtual method MouseCapture → (1)

how in : int32

Depicts how to capture the mouse:
< 0 : to release the previously captured mouse,
= 0 : to update the mouse capture,
> 0 : to capture the mouse

This method captures the mouse.

While captured, the mouse cursor is invisible and the application window receives relative mouse movement. The default implementation uses ClientRect, MouseClip, MousePosition and MouseVisible to emulate that behaviour. Subclasses should override this method if they can provide a dedicated relative mouse input mode.

Mouse​Cursor​Set

protected abstract method MouseCursorSet → (1)

mouseCursor in : MouseCursor

The new mouse cursor.

Sets the mouse cursor for the window.

Mouse​Track

[EmptyBody]
protected virtual method MouseTrack → ()

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

On​Button

protected method OnButton → (2)

button in : MouseButton

The mouse button.

pressed in : bool

Pressed or released?

A mouse button event has been received.

On​Char

protected method OnChar → (1)

codePoint in : int32

The character value, given as a Unicode code point.

A character value has been typed in.

On​Closing

protected method OnClosing → ()

The application is requested to close.

On​Key

protected method OnKey → (2)

keyCode in : int32

The native virtual keycode.

pressed in : bool

true if the key has been pressed, false if it has been released.

A keyboard key has been pressed or released.

On​Message_​Win​API

protected method OnMessage_WinAPI → (4)

msg in : int32

Message code.

wParam in : int64

Message WPARAM.

lParam in : int64

Message LPARAM.

stream ref : UnicodeStream<CharSetTrait_UTF_16, CharSetTrait_UTF_32>

The Unicode stream to use for WM_CHAR.

returns → bool

true if the message has been consumed, false if not.

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

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

See also

ApplicationWindow.OnButton
ApplicationWindow.OnChar
ApplicationWindow.OnClosing
ApplicationWindow.OnKey
ApplicationWindow.OnMouseLeave
ApplicationWindow.OnMouseMove
ApplicationWindow.OnResolution
ApplicationWindow.OnWindowBoundsChanged
ApplicationWindow.OnWindowFocus

On​Mouse​Leave

protected method OnMouseLeave → ()

returns → bool

true if the InputEventType.MouseLeave event has been sent, false if not.

The mouse cursor has left the application window client area.

On​Mouse​Move

protected method OnMouseMove → (4)

positionX in : int32

X-coordinate of new position of mouse cursor in application window client area or relative movement along the X-axis.

positionY in : int32

Y-coordinate of new position of mouse cursor in application window client area or relative movement along the Y-axis:

wheel in : int32

The mouse wheel movement.

relative opt : bool = false

If true, positionX in and positionY in represent relative amounts. Otherwise, they represent absolute positions.

The mouse has moved.

On​Resolution

protected method OnResolution → (1)

resolution in : int32

The new DPI resolution.

Updates the window DPI resolution.

See also

IApplicationWindow.Resolution

On​Window​Bounds​Changed

protected virtual method OnWindowBoundsChanged → ()

The bounds of the application window have changed.

On​Window​Focus

protected method OnWindowFocus → (1)

focused in : bool

true if the window has gained focus, false if it has lost it.

The application window has gained or lost focus.

Recreate​Native​Window

[EmptyBody]
protected virtual method RecreateNativeWindow → ()

Re-creates the native window.

RenderException

If a graphics subsystem error has occurred.

Text​Input​Activate

[EmptyBody]
protected virtual method TextInputActivate → (1)

active in : bool

true to activate text input,
false to deactivate text input

Enables or disables text input for this application window.

Protected / Attributes

Client​Rect

protected abstract attribute ClientRect → (get)

value : Box2I

The client area rectangle, in screen coordinates.

Returns the bounds of the application windows client area.

dirty

protected attribute dirty → (bool)

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

Mouse​Buttons

protected abstract attribute MouseButtons → (get)

value : int32

The mouse button state bitmask:
1 : left
2 : right
4 : middle

Returns the states of the mouse buttons.

Mouse​Clip

protected abstract attribute MouseClip → (get,set)

value : Box2I

The clip rectangle in screen coordinates or Box2I.Empty for no clip rectangle.

The mouse cursor clip rectangle.

mouse​Position

protected attribute mousePosition → (Vec2I)

Relative position of mouse cursor in application window client area.

Mouse​Position

protected abstract attribute MousePosition → (get,set)

value : Vec2I

The mouse cursor position, in screen coordinates.

Position of the mouse cursor.

Mouse​Visible

protected abstract attribute MouseVisible → (set)

value : bool

true to show the mouse cursor, false to hide it.

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

To​String​Type

protected abstract attribute ToStringType → (get)

value : string

[not-empty]
The implementation type identifier.

Returns a machine-readable and human-understandable identifier for the implementation type of this application window, to be used by object.ToString.

Logging

Logger

public static readonly attribute Logger → (ILogger)

The logger object of this class.