About

The module implements a complex GUI element that represents a layout and implementing standard expected window features.

Explore API:

Usage

The Window by itself it's an abstract GUIElement and Component that implements a core logic but left final integration with Unity and object configuration to developer of custom implementation.

This made to provide you with maximum flexibility in features development and prevent pre-definition of window instance high-level features.

If you are looking for ready to use implementation, take a look on Classic window sub-module.
It provides you with WindowUIController that implements the Window class with full integration with Unity as well as provides you with extra GUI controllers to window instance management.

As workspace element

The window is AWorkspaceGUIElement and exists in bounds of certain WorkspaceLayout. That allows you to define work zones for instances separating screen on different zones.

You may configure Window's behavior during interaction with its parental workspace bounds with window's properties like a:

ClampToScreenBorder
DynamicSizeIfClamped

Read more: Workspaces.

Isolation principles

Any window exists considers by the engine as an isolated GUI root. That makes tree of elements isolated from other roots.
This means that GUI elements occurring in separated windows *(or alternative root-like implementation)* not affect the state of a system of your window.

The only difference is a window depending on each other with the WindowLayer bond, like a windows collection bonded with Runtime Workspace features.
In such system events and messages may be relayed trough virtual hierarchy, due to expectation of the layout to work as a single GUI instance. Explore related documentation to find out details.

Read more Runtime Workspace

Windows Runtime Registry

The module provides you with a service that manages entire started windows, they integration into the engine and execution logic.

WindowsRuntimeRegister is a singleton instance that never is null during the call. The object works as a host for entire Window derived component using game objects.

Important to know:

The object establishes Window rendering environment during its Awake.
The object holds entire spawned Window instances as children.
The object always allocated as part of DoNotDestroy scene and not destroying during scene change.

Warning: Object destroy will cause destroying of entire ran windows. Avoid this operation in normal cases and consider the object as a stand-alone service preforming duties of the engine.

Explore API: Doloro.UIEngine2.Window.WindowsRuntimeRegister

Layering

They engine allows to gather Window instances into layers. Usage of the feature allows to create a complex tree-like hierarchy of windows for the engine backstage. In such hierarchy child windows will follow core operations of parental instance.

This allows to create a behavior when some parental layout window with a list of children considers by the engine as a single instance.
In case of Close \ Hide or performing any other core operations the children will receive the same orders and will follow the state of the window.

Warning: Note that layering by itself ONLY makes windows depended on a core logic level.

Layering not overrides any high-level handlers like a Position or Size properties to turn the layout of bonded windows to a single instance.
It also not affects Unity objects hierarchy.

The windows stay stand-alone game objects that can be handled according with your implementation of engine features configuration.

Tip: to implement highest-level dependencies one window from another affecting GUI visual results you may consider usage of Runtime Workspace and Tabs features.

Explore API: Doloro.UIEngine2.Window.WindowsLayer

API

Current subject highlights most important API members Window management.
Full list you may find in class documentation by the following link:
Doloro.UIEngine2.Window

Methods

Current subject reviews most common using methods you should know.

Method	Description
`Open`	Registering the window into the system. The handler immediately calls `AGUIElement.Focus` after call of `OnOpening` message handler and `Opened` event. Allows to reopen a window with `WindowStateOptions.Closed` `WindowState`. Warning To be integrated into windows' engine a window must be opened. Even if it exists at scene it does not mean it considers opened. Solutions like a Classic window encapsulates the opening process for you while any custom implementation must decide opening behavior explicitly along with common features logic.
`Open (Window parent)`	Specific handler for multi-windows layouts. Opening the window with the bond to another window. Automatically morphs the parent `Window` into the `WindowsLayer` in case the window not morphed yet. Forces child windows to follow parent window events and allows to access them via `WindowsLayer` service API.
`Open (WindowsLayer parent)`	Specific handler for multi-windows layouts. Comparing to previous variant skips layers pre-processing and works directly with the `WindowsLayer` instance.
`Hide`	Hiding window. The window continues to operate background tasks and can be restored by `Open` or `Focus` call.
`Close`	Releases instance from engine processing. - Closed window can't be operated via the API but the instance stays for continue management options. - Closed window may be reopened with the `Open` handler. Warning Solutions like a Classic window built above the core logic encapsulates GC operation and destroys game object that leads destroying of `Window` reference.

Properties

Current subject reviews most common using properties you should know.

Property	Description
`WindowState`	Property that represents current state of the window instance.
`LayoutMode`	Property allows to manage layout rendering mode.
`BackgroundTaskCallMode`	Defines background tasks management behavior.
`MinSize` & `MaxSize`	Properties that allows to define allowed layout size. Axis value less or equal to 0 means that the layout is not clamped.
`Position` & `Size`	Allows to get or define layout transform. Warning Always use if instead on manual transform management.
`ClampToScreenBorder`	If true than not allows the window rect to cross bounds defined with the `LayoutMode`.
`DynamicSizeIfClamped`	Works in case the `ClampToScreenBorder` is on. Dynamically change window size and position when the window collides the bound. The size is temporal and will be returned to origin one in case the free space occurred. Size change follow `MinSize` & `MaxSize` values.
`RawSize`	Suitable when you work with enabled `DynamicSizeIfClamped` feature. Allows you to get origin size instead of real one.
`RawPosition`	Suitable when you work with enabled `DynamicSizeIfClamped` feature. Allows you to get origin position instead of real one.

Messages handlers

The Window class allows you to extend its logic with implementation of messages handlers to react on window states change.

Message	Description
`OnOpening`	Handle all the data that should be loaded once during window start.
`OnHide`	Calling during hiding process before Hidden event.
`OnPreCloseCheck`	Occurs before window closed. Conclude is the window can be closed with returning bool value.
`OnClose`	Occurs during closing process before `Closed` event. Use to finalize window.
`OnFocus`	Focusing window and moving it one the rendering top order. Calling it from hide status in case if hidden.
`OnWindowMovedOnTop`	Occurs when the window has been moved to top of the windows stack.
`OnWindowFocusLost`	Occurs when current active window is changed. Warning Note that this callback not the same as `AGUIElement.OnLostFocus`. The window works as isolated GUI root and not reflect GUI events in bounds of other independent roots.

Background operations

The Window implemented as an isolated GUI engine execution branch that supposed you to use it as an app-in-app. Considering this you may require an option to implement some backstage operation that will perform one or both from two behaviors:

Streaming data to the window and updating content along with it.
Updating environment along with in-window implemented features. Streaming data from the window to other windows or apply to environment.

For such tasks the Window offers you two handlers.

Handler	Call policy	Purpose
`OnBackground`	Each frame. Moderated with `BackgroundTaskCallMode`	Use to perform GUI related operations. The handler calls based on defined `Window.BackgroundTaskCallMode` property policy. Can be called in two variants: - Each frame: in case the behavior implements the window or environment logic. - If Hidden: in case you need to maintain some operations only when the window moved to tray.
`FixedUpdate`	Each physics engine tic	Regular Unity message. Use to perform the physics related actions.

To implement a background behavior in your custom window you enough to override the handlers mentioned above with your custom logic.

public class CustomWindow : Window
{
    // Override opening message to initialize
    // the window execution settings.
    protected override void OnOpening()
    {
        // Defining background tasks call
        // policy.
        // By default, the value is: `Always`
        BackgroundTaskCallMode = YOU_POLICY
    }
 
    // Override background message handler
    // to implement window logic does not bond to the
    // internal GUI elements by itself.
    protected override void OnBackground()
    {
        \\ Implement background task here
    }
}

Classic window

The package supplies you with sub-module that implement Window feature with a tight bond with Unity.

The supplied variant encapsulates module features using and lower requirements to developer to beginner experience level.
Advanced users may consider using the class as example to create a custom implementation most suitable for your in-game features.

Implementation Design Pattern

Sub-module provides collection of pluggable controllers that allows separately adding of core module features along with your need avoiding any unnecessary controls. Such design pattern allows you flexibly adjust instance features along with your gameplay requirements.

Not every game and player requires advanced GUI features when other games can't be built with a primitive solutions.

The sub-module follows this understanding and implements Window features over list of components those can be or not be used over the build. Entire controls are uniform and supposed to be fully compatible with any custom implementation.

Controls

Window UI Controller

Main controller that implements features of the Window component.
Allows to configurate window settings.

Warning: The object with the WindowUIController represents the Window instance. Entire GUI representation of the window must be located under Layout referenced game object.

Explore API: Doloro.UIEngine2.WindowUIController : Window

Layout references

Layout objects	Purpose
Layout	Non-optional property that must define the game object that represents GUI implementation of the window. The object will be managed by internal system during layout operations.
Content	Allows to define hierarchy object that should be used as holder of any GUI element excluding service and design controls of the window. Can be accessed via the `ContentHolder` property.

Behavior settings
Allows to configure specific window behavior.

Option	Purpose
Open during start	In case of `true` will automatically integrate the object into Windows Runtime Registry by `Open` handler call. For most cases the default `true` value is a normal behavior state that should not be changed. In case for some reasons you have to integrate window with a delay set the `false` and call `Open` handler manually lately, when you need.

Layout configuration
In this sub-group of properties, you may define layout clamp options.
By default, window has a free-space value. Minimal size always clamped with the SafeBorder property.

Warning: Note that clamping options not works in case LayoutMode other than Rect if not managed by external system.

You may always unclamp layout via editor controls by pressing Set free over the target property or manually via source by applying 0 clamp size to axis.

Drag Controller

The GUI controller locating as Window child in hierarchy that turns self Graphics into a space that can move a parent window via the drag of the mouse.
Allows to relocate the window over its workspace.

Explore API: Doloro.UIEngine2.WindowDragController

Resize Controller

The GUI controller locating as Window child in hierarchy that turns self Graphics into a space that allows to resize a parent window.

Take a note that you must declare behavior options that defines where the controller located considering the window layout. According with selection options the controller will manage window's layout in different way to provide an expected result.

Explore API: Doloro.UIEngine2.WindowResizeController

State Controller

The GUI controller locating as Window child in hierarchy.
The controller allows to connect several buttons that will manage main Window states.

Button	Purpose
Close	Closes the window by the call.
Layout mode	Pressing toggles `LayoutMode` property between `Rect` and selected mode (`FullScreen` or `FullWorkspace`)
Hide	Click over the button causes call of `Hide` handler over the window.

Explore API: Doloro.UIEngine2.WindowStateController

Example

You may find implementation of layout built around Classic Window sub-module's controller at Classic Window prefab located by the path:
Doloro-GDK \ Doloro-UI-2 \ Resources \ Templates \ Windows \.

Entire package demos using window have built with using of the prefab as a ground or variant.

Prefabs contains 3 drag zones:
1. Header
2. Footer Drag L
3. Footer Drag R
State controller located under the Header game object as a component over Window controls object.
Resize controller located over the Scaling control game object and named according with defined anchor point.

Table of Contents