Unigine::EngineWindow Class

Then, by using methods of the EngineWindow class, you can specify the window appearance (for example, set a title, an icon, change opacity, add borders, and so on), and properties (whether the window can be nested, or whether it can become a group), define its style (system or engine), change the window state (whether it is shown/hidden, minimized/maximized, focused, etc.), manage window intersections and events.

Setting Up Position and Size#

In UNIGINE, the window size and position coordinates are measured in both units and pixels:

The size and position in units don't depend on the DPI scale and always remain the same. You can change the window and client area size via setSize and setClientSize , adjust the minimum and maximum size and set the window and client position via the corresponding methods. All of them work with units.
The size and position in pixels are calculated by multiplying the size in units by the current DPI scale. You can get it using one of the RenderSize-related methods/properties (e.g., getRenderSize , and so on). When the DPI scale is 100%, 1 unit corresponds to 1 pixel.

Notice
DPI scaling is applied only when the auto_dpi_scalingflag is enabled. You can check the current flag value via the console or by using WindowManager::isAutoDpiScaling .
To determine how the OS handles the DPI scale, specify the DPI awareness mode.

You should consider this information when resizing textures, calculating mouse intersections, etc. The window size and position should be set individually, depending on the situation.

Notice

If necessary, you can convert the size and position coordinates from units to pixels and visa versa:

Use one of the toRenderSize or toUnitSize to convert the size.
Use globalToLocalUnitPosition to transform the coordinates in pixels into units or localUnitToGlobalPosition to do the opposite.

In the following example, the positions of the window and client area (in units) change to the mouse cursor when you press the P or C respectively:

Source code (C++)

#include <UnigineEngine.h>
#include <UnigineLogic.h>
#include <UnigineWindowManager.h>

using namespace Unigine;
using namespace Math;

EngineWindowViewportPtr system_viewport;

int AppSystemLogic::init()
{

	// create a separate window viewport
	system_viewport = EngineWindowViewport::create("Separate System Viewport", 400, 350);
	// specify an intial position
	system_viewport->setPosition(ivec2(30, 30));

	// render the window viewport
	system_viewport->show();

	return 1;
}

int AppSystemLogic::update()
{

	// change the window position to the mouse cursor when pressing 'P' 
	if (Input::isKeyDown(Input::KEY_P))
	{

		if (system_viewport.isDeleted() == false)
			system_viewport->setPosition(mouse_pos);
	}

	// change the client area position to the mouse cursor when pressing 'C' 
	if (Input::isKeyDown(Input::KEY_C))
	{
		if (system_viewport.isDeleted() == false)
			system_viewport->setClientPosition(mouse_pos);
	}

	return 1;
}

Check also the WindowSandbox and WindowSize samples — they print the full information on the window size and DPI.

Adjusting Visual Representation#

The window visual representation includes all available window parameters such as title and title bar, icon, borders, opacity, and window style (the engine or system one).

Here are some window examples:

Source code (C++)

#include <UnigineEngine.h>
#include <UnigineLogic.h>
#include <UnigineWindowManager.h>

using namespace Unigine;
using namespace Math;

EngineWindowViewportPtr system_viewport;

EngineWindowViewportPtr system_viewport_borderless;
EngineWindowViewportPtr engine_viewport_borderless;
EngineWindowViewportPtr engine_viewport;

int AppSystemLogic::init()
{
	// create a separate system viewport
	system_viewport = EngineWindowViewport::create("Window", 200, 200);
	// specify an intial position
	system_viewport->setPosition(ivec2(30, 30));

	// change the size
	system_viewport->setSize(ivec2(400, 350));

	// render the window viewport
	system_viewport->show();

	// create a separate system viewport with borders and title bar disabled
	system_viewport_borderless = EngineWindowViewport::create(400, 350);
	system_viewport_borderless->setPosition(ivec2(460, 30));
	system_viewport_borderless->setSize(ivec2(400, 350));
	// disable borders
	system_viewport_borderless->setBordersEnabled(false);
	// disable a title bar
	system_viewport_borderless->setTitleBarEnabled(false);
	system_viewport_borderless->show();

	// create a separate engine viewport with no borders
	engine_viewport_borderless = EngineWindowViewport::create("Window", 400, 350);
	engine_viewport_borderless->setPosition(ivec2(460, 30));
	engine_viewport_borderless->setEngineStyle(true);
	engine_viewport_borderless->setSize(ivec2(400, 350));
	// disable borders
	engine_viewport_borderless->setBordersEnabled(false);
	engine_viewport_borderless->show();

	// create a separate engine viewport with borders
	engine_viewport = EngineWindowViewport::create("Window", 400, 350);
	engine_viewport->setPosition(ivec2(460, 30));
	engine_viewport->setEngineStyle(true);
	engine_viewport->setSize(ivec2(400, 350));
	engine_viewport->show();

	return 1;
}

A system-style window	A window (either system or engine style), borders and title bar disabled
An engine-style window, borders disabled	An engine-style window, borders enabled

The system and engine style windows have the same component layout except the sizing border: in the engine style, it is in the visual part of the window.

The ability to customize the window style makes it possible to create a standard set of window settings for different systems and frameworks.

Check the WindowVisual sample in UNIGINE SDK for more details.

Setting Up Order#

In the following example, the order of the window under the cursor changes when you press the specific button: T to make the window appear on top of all other windows, A to always render the window above the other windows.

Source code (C++)

#include "AppSystemLogic.h"
#include <UnigineEngine.h>
#include <UnigineLogic.h>
#include <UnigineWindowManager.h>

using namespace Unigine;
using namespace Math;

EngineWindowPtr current_window;

EngineWindowViewportPtr system_viewport;

EngineWindowViewportPtr system_viewport_borderless;
EngineWindowViewportPtr engine_viewport_borderless;
EngineWindowViewportPtr engine_viewport;

int AppSystemLogic::init()
{
	// create a separate system viewport
	system_viewport = EngineWindowViewport::create("Window", 200, 200);
	// specify an intial position
	system_viewport->setPosition(ivec2(30, 30));

	// change the size
	system_viewport->setSize(ivec2(400, 350));

	// render the window viewport
	system_viewport->show();

	// create a separate system viewport with borders and title bar disabled
	system_viewport_borderless = EngineWindowViewport::create(400, 350);
	system_viewport_borderless->setPosition(ivec2(460, 30));
	system_viewport_borderless->setSize(ivec2(400, 350));
	// disable borders
	system_viewport_borderless->setBordersEnabled(false);
	// disable a title bar
	system_viewport_borderless->setTitleBarEnabled(false);
	system_viewport_borderless->show();

	// create a separate engine viewport with no borders
	engine_viewport_borderless = EngineWindowViewport::create("Window", 400, 350);
	engine_viewport_borderless->setPosition(ivec2(460, 30));
	engine_viewport_borderless->setEngineStyle(true);
	engine_viewport_borderless->setSize(ivec2(400, 350));
	// disable borders
	engine_viewport_borderless->setBordersEnabled(false);
	engine_viewport_borderless->show();

	// create a separate engine viewport with borders
	engine_viewport = EngineWindowViewport::create("Window", 400, 350);
	engine_viewport->setPosition(ivec2(460, 30));
	engine_viewport->setEngineStyle(true);
	engine_viewport->setSize(ivec2(400, 350));
	engine_viewport->show();

	return 1;
}

int AppSystemLogic::update()
{
	// get the current mouse position
	ivec2 mouse_pos = Input::getMousePosition();

	// make the window under the cursor appear on top when pressing 'T'
	if (Input::isKeyDown(Input::KEY_T))
	{
		current_window = WindowManager::getUnderCursorWindow();
		if (current_window.isDeleted() == false)
			current_window->toTop();
	}

	// set the window under the cursor to be always on top when pressing 'A'
	if (Input::isKeyDown(Input::KEY_A))
	{
		current_window = WindowManager::getUnderCursorWindow();
		if (current_window.isDeleted() == false)
			current_window->setAlwaysOnTop(true);
	}

	return 1;
}

Check the WindowOrder sample in UNIGINE SDK for more details.

Changing Behavior#

With the set of behavior-related functions, you can do the following:

Force the engine to stop operating while the engine window is opened.
Ignore or allow using the OS methods for windows closing.
Specify whether the window is resizable.
Specify the sizing border size.
Control rendering of the engine window - show, hide, focus, minimize, maximize, restore, or close.

Check the WindowBehavior and WindowSandbox samples in UNIGINE SDK for more details.

Working with Modal Windows#

The following example demonstrates how to create modal windows and add modal children to the main window. Additionally, the main window includes a message that informs the user whether they can close the window or not.

Source code (C++)

#include "AppSystemLogic.h"
#include <UnigineEngine.h>
#include <UnigineLogic.h>
#include <UnigineWindowManager.h>

using namespace Unigine;
using namespace Math;

WidgetLabelPtr label;
EngineWindowViewportPtr main_window;

int AppSystemLogic::init()
{
	// main window
	main_window = WindowManager::getMainWindow();
	main_window->setSize(ivec2(1600, 900));
	main_window->setPosition(ivec2(30, 30));
	main_window->setCanBeNested(false);
	main_window->setCanCreateGroup(false);

	// add an info label to the main window
	label = WidgetLabel::create("");
	label->setFontOutline(1);
	label->setLifetime(Widget::LIFETIME_WINDOW);
	label->setFontColor(vec4_red);
	main_window->addChild(label, Gui::ALIGN_LEFT);

	// first modal window of the main window
	EngineWindowViewportPtr main_modal_0 = EngineWindowViewport::create("Modal for Main 0", 600, 650);
	main_modal_0->setPosition(ivec2(50, 250));
	main_modal_0->setCanBeNested(false);
	main_modal_0->setCanCreateGroup(false);
	main_modal_0->show();
	main_modal_0->setModal(main_window);

	// second modal window of the main window
	EngineWindowViewportPtr main_modal_1 = EngineWindowViewport::create("Modal for Main 1", 900, 650);
	main_modal_1->setPosition(ivec2(700, 250));
	main_modal_1->setCanBeNested(false);
	main_modal_1->setCanCreateGroup(false);
	main_modal_1->show();
	main_modal_1->setModal(main_window);

	return 1;
}

int AppSystemLogic::update()
{
	String text;

	// check if the modal children of the main window are still opened 
	if (main_window->isModalParent())
		text += "You CANNOT close this window. Please close modal children first.\n";
	else
		text += "You CAN close this window.\n";

	// render the info label
	label->setText(text);

	return 1;
}

Check the WindowModal sample in UNIGINE SDK for more details.

Methods:

Name	Description View: Sort by:
getGui	Returns the current parent Gui for a window.
getDisplayIndex	Returns the current number of the display, on which the window is currently displayed.
isNested	Returns the current value indicating if this is a nested window or group of windows.
isSeparate	Returns the current value indicating if this is a separate window or group of windows.
getSelfGui	Returns the current Gui instance for a window.
setPosition	Setter and Getter for position of the top left corner of the window in the screen coordinates.
getPosition
setClientPosition	Setter and Getter for position of the top left corner of the client (the window content area without the top bar and borders) in the screen coordinates.
getClientPosition
getClientLocalPosition	Returns the current position of the top left corner of the client (the window content area without the top bar and borders) relative to the window position.
setSize	Setter and Getter for engine window size in units (including the sizing border).
getSize
setClientSize	Setter and Getter for size of the window client (content) area in units.
getClientSize
setMinSize	Setter and Getter for minimum possible window size in units when resizing the window.
getMinSize
setMaxSize	Setter and Getter for maximum possible window size in units when resizing the window.
getMaxSize
setTitle	Setter and Getter for text of the title for the window.
getTitle	Setter and Getter for text of the title for the window.
setOpacity	Setter and Getter for opacity for the window.
getOpacity	Setter and Getter for opacity for the window.
setBordersEnabled	Setter and Getter for value indicating if the borders are enabled for the engine window.
isBordersEnabled
setBorderSize	Setter and Getter for engine window border size.
getBorderSize	Setter and Getter for engine window border size.
setResizable	Setter and Getter for value indicating if the engine window is resizable by the mouse.
isResizable
isShown	Returns the current value indicating if the engine window is rendered.
isHidden	Returns the current value indicating if the engine window isn't rendered.
isFocused	Returns the current value indicating if the engine window is in focus.
isMinimized	Returns the current value indicating if the engine window is minimized.
isMaximized	Returns the current value indicating if the engine window is maximized.
getOrder	Returns the current order of the window.
getParentGroup	Returns the current group into which the current window is nested, or NULL if it is a separate window.
getGlobalParentGroup	Returns the current top group of the hierarchy into which the current window is nested, or NULL if it is a separate window.
getNumDroppedItems	Returns the current total number of files and/or folders dropped to the window.
getNumModalWindows	Returns the current total number of modal windows for this window.
getModalParent	Returns the current modal parent of the window.
isModalParent	Returns the current value indicating if the window is parent for any modal window.
isModal	Returns the current value indicating if the window is modal.
setIgnoreSystemClose	Setter and Getter for value indicating if closing the window using the OS methods is ignored (ALT+F4 or cross in the top-right corner of the window).
isIgnoreSystemClose
setHoldEngine	Setter and Getter for value indicating if the engine operation can't be stopped while this window is open.
isHoldEngine
getID	Returns the current ID of the engine window, which is unchanged during the whole lifecycle of the window.
setAlwaysOnTop	Setter and Getter for value indicating if the window is always rendered above the other windows.
isAlwaysOnTop
isHiddenByTab	Returns the current value indicating if the window is overlapped by any other tab (either by switching to another tab or resizing this window to have zero client area).
setCanCreateGroup	Setter and Getter for value indicating if the engine window can become a group.
isCanCreateGroup
setCanBeNested	Setter and Getter for value indicating if the engine window can be used as a nested window.
isCanBeNested
isSystemFocused	Returns the current value indicating if the engine window is currently in focus.
setSizingBorderSize	Setter and Getter for size of the border in the widget that is manipulated to resize the window.
getSizingBorderSize
setEngineStyle	Setter and Getter for value indicating if the engine style or the default system style is set for the engine window.
isEngineStyle
setSystemStyle	Setter and Getter for value indicating if the default system style or the engine style is set for the engine window.
isSystemStyle
setTitleBarHeight	Setter and Getter for height of the window title bar.
getTitleBarHeight	Setter and Getter for height of the window title bar.
setTitleBarEnabled	Setter and Getter for value indicating if the title bar is enabled for the engine window.
isTitleBarEnabled
getTypeName	Returns the current name of the engine window type as a string.
getType	Returns the current type of the engine window.
getDpiScale	Returns the current DPI scale applied to the elements inside the window.
getDpi	Returns the current DPI level for the window.
getMaxRenderSize	Returns the current maximum window size in pixels.
getMinRenderSize	Returns the current minimum window size in pixels.
getClientRenderSize	Returns the current client area size in pixels.
getRenderSize	Returns the current engine window frame size in pixels.
getEventUnstack	The event triggered when when the window is unstacked.
getEventStack	The event triggered when the window is stacked.
getEventUnstackMove	The event triggered when the window is unstacked and moved.
getEventItemDrop	The event triggered when an item is dropped to the window.
getEventClose	The event triggered when the window is closed.
getEventRestored	The event triggered when the window is restored.
getEventMaximized	The event triggered when the window is maximized.
getEventMinimized	The event triggered when the window is minimized.
getEventHidden	The event triggered when the window is hidden.
getEventShown	The event triggered when the window is shown.
getEventMouseLeave	The event triggered when the mouse leaves the window area.
getEventMouseEnter	The event triggered when the mouse enters the window area.
getEventUnfocused	The event triggered when the window loses the focus.
getEventFocused	The event triggered when the window gains the focus.
getEventResized	The event triggered when the window is resized.
getEventMoved	The event triggered when the window is moved.
getEventFuncSwap	The event triggered before calling the window swap.
getEventFuncEndRender	The event triggered after the window rendering has ended.
getEventFuncEndRenderGui	The event triggered after the GUI rendering has ended.
getEventFuncBeginRenderGui	The event triggered when the GUI rendering has begun.
getEventFuncRender	The event triggered after the window rendering function.
getEventFuncBeginRender	The event triggered when the window rendering has begun.
getEventFuncUpdate	The event triggered after the window update.
getEventWindowEvent	The event triggered on the window event.
moveToCenter	Positions the window so that the client center coincides with the center of the current display.
setMinAndMaxSize	Sets the minimum and maximum possible window size when resizing the window.
setIcon	Sets the icon for the window.
getIcon	Returns the icon for the engine window.
show	Enables rendering of the engine window.
hide	Disables rendering of the engine window.
setFocus	Sets the focus to the window.
setSystemFocus	Sets the focus to the engine window.
minimize	Minimizes the engine window to an iconic representation.
maximize	Makes the engine window as large as possible.
restore	Restores the size and position of the minimized or maximized engine window via the system proxy.
getHitTestResult	Returns a value indicating in which area of the engine window the mouse is located.
getHitTestResultName	Returns the string representation of the hit test result value.
toTop	Makes the window appear on top of all other windows.
isGlobalChildOf	Returns the value specifying if the current window is a part of a hierarchy of the specified window.
updateGuiHierarchy	Updates the hierarchy for all widgets — the widgets are arranged, expanded to the required sizes and then their positions are updated.
getDroppedItem	Returns the absolute path to the file or folder dropped to the window.
screenshot	Creates a screenshot after the rendering stage is completed.
setModal	Sets the current window modal to the specified parent window.
addModalWindow	Adds the argument window as modal to the current window.
removeModalWindow	Removes the argument modal window from this window.
getModalWindow	Returns the modal window for this window by its index.
unstack	Removes the current window from a parent group.
close	Deletes the window if this window is not a modal parent or a member of a fixed group.
getIntersection	Returns the value indicating if the mouse is hovering over the window.
getClientIntersection	Returns the value indicating if the mouse is hovering over the client area of the window.
getClient9Area	Returns the area over which the mouse hovers, one of the nine areas into which the window is segmented.
get9AreaName	Returns the name of the screen segment as a string.
globalToLocalUnitPosition	Transforms the global screen coordinates in pixels into units relative to the window client area.
localUnitToGlobalPosition	Transforms the position in units relative to the window client area into the global screen coordinates in pixels.
toRenderSize	Transforms the unit value to the pixel value.
toUnitSize	Transforms the pixel value to the unit value.
toRenderSize	Transforms the unit value to the pixel value.
toUnitSize	Transforms the pixel value to the unit value.

EngineWindow Class

Enums

HITTEST#

Name	Description
HITTEST_INVALID = -1	The hittest result is invalid.
HITTEST_NORMAL = 0	Client area of the window.
HITTEST_DRAGGABLE = 1	Area of the window, by clicking onto which the window can be moved.
HITTEST_RESIZE_TOPLEFT = 2	Area of the window that can be dragged to resize the window to the top and/or left direction.
HITTEST_RESIZE_TOP = 3	Area of the window that can be dragged to resize the window to the top direction.
HITTEST_RESIZE_TOPRIGHT = 4	Area of the window that can be dragged to resize the window to the top and/or right direction.
HITTEST_RESIZE_RIGHT = 5	Area of the window that can be dragged to resize the window to the right direction.
HITTEST_RESIZE_BOTTOMRIGHT = 6	Area of the window that can be dragged to resize the window to the bottom and/or right direction.
HITTEST_RESIZE_BOTTOM = 7	Area of the window that can be dragged to resize the window to the bottom direction.
HITTEST_RESIZE_BOTTOMLEFT = 8	Area of the window that can be dragged to resize the window to the bottom and/or left direction.
HITTEST_RESIZE_LEFT = 9	Area of the window that can be dragged to resize the window to the left direction.

FLAGS#

Name	Description
FLAGS_SHOWN = 1 << 0	Window is rendered.
FLAGS_FIXED_SIZE = 1 << 1	Window size is fixed.
FLAGS_HOLD_ENGINE = 1 << 2	Engine can't stop operating while this window is open.
FLAGS_MAIN = 1 << 3	Main window.
FLAGS_CONSOLE_USAGE = 1 << 4	Usage of the console for the window is enabled.
FLAGS_PROFILER_USAGE = 1 << 5	Usage of the profiler for the window is enabled.
FLAGS_VISUALIZER_USAGE = 1 << 6	Usage of the visualizer for the window is enabled.

AREA#

Name	Description
AREA_NONE = 0	None of the areas of the window split into 9 parts is selected.
AREA_TOP_LEFT = 1	Top left area of the window split into 9 parts.
AREA_TOP_CENTER = 2	Top center area of the window split into 9 parts.
AREA_TOP_RIGHT = 3	Top right area of the window split into 9 parts.
AREA_CENTER_LEFT = 4	Center left area of the window split into 9 parts.
AREA_CENTER_CENTER = 5	Center area of the window split into 9 parts.
AREA_CENTER_RIGHT = 6	Center right area of the window split into 9 parts.
AREA_BOTTOM_LEFT = 7	Bottom left area of the window split into 9 parts.
AREA_BOTTOM_CENTER = 8	Bottom center area of the window split into 9 parts.
AREA_BOTTOM_RIGHT = 9	Bottom right area of the window split into 9 parts.

TYPE#

Name	Description
ENGINE_WINDOW = 0	Engine window.
ENGINE_WINDOW_VIEWPORT = 1	Engine viewport window.
ENGINE_WINDOW_GROUP = 2	Engine window group.
NUM_ENGINE_WINDOWS = 3	Total number of engine windows.

Members

void setPosition ( const Math::ivec2& position ) #

Sets a new position of the top left corner of the window in the screen coordinates. In case of several displays, the position is relative to the main display.

NoticeThis method should be applied to a separate or parent window, using this method for a nested window is not allowed.

Arguments

const Math::ivec2& position - The window screen position (coordinates of the top left corner).

Math::ivec2 getPosition() const#

Returns the current position of the top left corner of the window in the screen coordinates. In case of several displays, the position is relative to the main display.

NoticeThis method should be applied to a separate or parent window, using this method for a nested window is not allowed.

Return value

Current window screen position (coordinates of the top left corner).

void setClientPosition ( const Math::ivec2& position ) #

Sets a new position of the top left corner of the client (the window content area without the top bar and borders) in the screen coordinates. In case of several displays, the position is relative to the main display.

NoticeThis method should be applied to a separate or parent window, using this method for a nested window is not allowed.

Arguments

const Math::ivec2& position - The screen position of the client (coordinates of the top left corner).

Math::ivec2 getClientPosition() const#

Returns the current position of the top left corner of the client (the window content area without the top bar and borders) in the screen coordinates. In case of several displays, the position is relative to the main display.

NoticeThis method should be applied to a separate or parent window, using this method for a nested window is not allowed.

Return value

Current screen position of the client (coordinates of the top left corner).

Math::ivec2 getClientLocalPosition() const#

Returns the current position of the top left corner of the client (the window content area without the top bar and borders) relative to the window position.

Return value

Current screen position of the client (coordinates of the top left corner) relative to the window position.

void setSize ( const Math::ivec2& size ) #

Sets a new engine window size in units (including the sizing border).

NoticeThis method is for a separate or parent window, using this method for a nested window is not allowed (when requesting the current value, it will return the value of the global parent group).

Arguments

const Math::ivec2& size - The engine window size in units (including the sizing border).

Math::ivec2 getSize() const#

Returns the current engine window size in units (including the sizing border).

NoticeThis method is for a separate or parent window, using this method for a nested window is not allowed (when requesting the current value, it will return the value of the global parent group).

Return value

Current engine window size in units (including the sizing border).

void setClientSize ( const Math::ivec2& size ) #

Sets a new size of the window client (content) area in units.

Arguments

const Math::ivec2& size - The

Math::ivec2 getClientSize() const#

Returns the current size of the window client (content) area in units.

Return value

Current

void setMinSize ( const Math::ivec2& size ) #

Sets a new minimum possible window size in units when resizing the window. If the value is more than the current maximum size, use the setMinAndMaxSize() method, to change both values at once. Otherwise the value will be clamped to the current maximum size.

NoticeThis method should be applied to a separate or parent window, using this method for a nested window is not allowed (it will return zero values).

Arguments

const Math::ivec2& size - The minimum possible size of the window.

Math::ivec2 getMinSize() const#

Returns the current minimum possible window size in units when resizing the window. If the value is more than the current maximum size, use the setMinAndMaxSize() method, to change both values at once. Otherwise the value will be clamped to the current maximum size.

NoticeThis method should be applied to a separate or parent window, using this method for a nested window is not allowed (it will return zero values).

Return value

Current minimum possible size of the window.

void setMaxSize ( const Math::ivec2& size ) #

Sets a new maximum possible window size in units when resizing the window. If the value is less than the current minimum size, use the setMinAndMaxSize() method, to change both values at once. Otherwise the value will be clamped to the current minimum size.

NoticeThis method should be applied to a separate or parent window, using this method for a nested window is not allowed.

Arguments

const Math::ivec2& size - The maximum possible size of the window.

Math::ivec2 getMaxSize() const#

Returns the current maximum possible window size in units when resizing the window. If the value is less than the current minimum size, use the setMinAndMaxSize() method, to change both values at once. Otherwise the value will be clamped to the current minimum size.

NoticeThis method should be applied to a separate or parent window, using this method for a nested window is not allowed.

Return value

Current maximum possible size of the window.

void setTitle ( const char * title ) #

Sets a new text of the title for the window. For a separate window, the title is set via system proxy in the title bar only; for a nested window, it is also set in the tab of the parent group.

Arguments

const char * title - The title of the window.

const char * getTitle() const#

Returns the current text of the title for the window. For a separate window, the title is set via system proxy in the title bar only; for a nested window, it is also set in the tab of the parent group.

Return value

Current title of the window.

void setOpacity ( float opacity ) #

Sets a new opacity for the window.

NoticeThis method should be applied to a separate or parent window, using this method for a nested window is not allowed (it will always return 1.0f).

Arguments

float opacity - The opacity for the window.

float getOpacity() const#

Returns the current opacity for the window.

NoticeThis method should be applied to a separate or parent window, using this method for a nested window is not allowed (it will always return 1.0f).

Return value

Current opacity for the window.

void setBordersEnabled ( bool enabled ) #

Sets a new value indicating if the borders are enabled for the engine window.

NoticeThis method should be applied to a separate or parent window, using this method for a nested window is not allowed (it will return false).

Arguments

bool enabled - Set true to enable borders for the window; false - to disable it.

bool isBordersEnabled() const#

Returns the current value indicating if the borders are enabled for the engine window.

NoticeThis method should be applied to a separate or parent window, using this method for a nested window is not allowed (it will return false).

Return value

true if borders for the window is enabled; otherwise false.

void setBorderSize ( int size ) #

Sets a new engine window border size.

Notice

This value is applied to the windows in the engine style only. For system-style windows system settings are applied.
This method should be applied to a separate or parent window, using this method for a nested window is not allowed (it will return 0).

Arguments

int size - The engine window border size.

int getBorderSize() const#

Returns the current engine window border size.

Notice

This value is applied to the windows in the engine style only. For system-style windows system settings are applied.
This method should be applied to a separate or parent window, using this method for a nested window is not allowed (it will return 0).

Return value

Current engine window border size.

void setResizable ( bool resizable ) #

Sets a new value indicating if the engine window is resizable by the mouse.

NoticeThis method should be applied to a separate or parent window, using this method for a nested window is not allowed (it will return false).

Arguments

bool resizable - Set true to enable the option of making the engine window resizable by the mouse; false - to disable it.

bool isResizable() const#

Returns the current value indicating if the engine window is resizable by the mouse.

NoticeThis method should be applied to a separate or parent window, using this method for a nested window is not allowed (it will return false).

Return value

true if the option of making the engine window resizable by the mouse is enabled; otherwise false.

bool isShown() const#

Returns the current value indicating if the engine window is rendered.

NoticeThis method should be applied to a separate or parent window, for a nested window it will return the value of the global parent group.

Return value

true if the engine window is rendered; otherwise false.

bool isHidden() const#

Returns the current value indicating if the engine window isn't rendered.

NoticeThis method should be applied to a separate or parent window, for a nested window it will return the value of the global parent group.

Return value

true if the engine window isn't rendered; otherwise false.

bool isFocused() const#

Returns the current value indicating if the engine window is in focus.

NoticeThis method should be applied to a separate or parent window, for a nested window it will return the value of the global parent group.

Return value

true if the engine window is in focus; otherwise false.

bool isMinimized() const#

Returns the current value indicating if the engine window is minimized.

NoticeThis method should be applied to a separate or parent window, for a nested window it will return the value of the global parent group.

Return value

true if the engine window is minimized; otherwise false.

bool isMaximized() const#

Returns the current value indicating if the engine window is maximized.

NoticeThis method should be applied to a separate or parent window, for a nested window it will return the value of the global parent group.

Return value

true if the engine window is maximized; otherwise false.

int getOrder() const#

Returns the current order of the window. This value allows comparing which window is closer to the viewer (a relatively smaller value).

NoticeThis method should be applied to a separate or parent window, for a nested window it will return the value of the global parent group.

NoticeThis method should be applied to a separate or parent window, for a nested window it will return 0.

Return value

Current total number of modal windows.

Ptr<EngineWindow> getModalParent() const#

Returns the current modal parent of the window. The concept of modal assumes that if a window has modal children, it cannot be closed. Any other interaction with a parent window is possible.

NoticeThis method should be applied to a separate or parent window, for a nested window it will return nullptr.

Return value

Current modal parent of the window.

bool isModalParent() const#

Returns the current value indicating if the window is parent for any modal window. The concept of modal assumes that if a window has modal children, it cannot be closed. Any other interaction with a parent window is possible.

NoticeThis method should be applied to a separate or parent window, for a nested window it will return false.

Return value

true if the window is parent for any modal window; otherwise false.

bool isModal() const#

Returns the current value indicating if the window is modal. The concept of modal assumes that if a window has modal children, it cannot be closed. Any other interaction with a parent window is possible.

NoticeThis method should be applied to a separate or parent window, for a nested window it will return false.

Return value

true if the window is modal; otherwise false.

void setIgnoreSystemClose ( bool close ) #

Sets a new value indicating if closing the window using the OS methods is ignored (ALT+F4 or cross in the top-right corner of the window).

Arguments

bool close - Set true to enable ignoring OS methods for closing the window; false - to disable it.

NoticeThis method should be applied to a separate or parent window, using this method for a nested window is not allowed (it will return the value of the global parent group).

Arguments

bool top - Set true to enable the window is always on top; false - to disable it.

bool isAlwaysOnTop() const#

Returns the current value indicating if the window is always rendered above the other windows.

NoticeThis method should be applied to a separate or parent window, using this method for a nested window is not allowed (it will return the value of the global parent group).

NoticeThis method should be applied to a separate or parent window, for a nested window it will return the value of the global parent group.

Return value

true if the engine window is in focus; otherwise false.

void setSizingBorderSize ( int size ) #

Sets a new size of the border in the widget that is manipulated to resize the window.

Notice
						This method should not be applied to a system-style window with enabled borders, as the system settings cannot be changed (for an unmodified system-style window (i.e. with the enabled border size), the system value is applied).
This method should not be applied to nested windows (it will return 0).

					

Arguments

int size - The size of the border in the widget that is manipulated to resize the window, in pixels.

int getSizingBorderSize() const#

Returns the current size of the border in the widget that is manipulated to resize the window.

Notice
						This method should not be applied to a system-style window with enabled borders, as the system settings cannot be changed (for an unmodified system-style window (i.e. with the enabled border size), the system value is applied).
This method should not be applied to nested windows (it will return 0).

					

Return value

Current size of the border in the widget that is manipulated to resize the window, in pixels.

void setEngineStyle ( bool style ) #

Sets a new value indicating if the engine style or the default system style is set for the engine window.

NoticeThis method should be applied to a separate or parent window, using this method for a nested window is not allowed (it will return true).

Arguments

bool style - Set true to enable the engine style for the engine window; false - to disable it.

bool isEngineStyle() const#

Returns the current value indicating if the engine style or the default system style is set for the engine window.

NoticeThis method should be applied to a separate or parent window, using this method for a nested window is not allowed (it will return true).

Return value

true if the engine style for the engine window is enabled; otherwise false.

void setSystemStyle ( bool style ) #

Sets a new value indicating if the default system style or the engine style is set for the engine window.

NoticeThis method should be applied to a separate or parent window, using this method for a nested window is not allowed (it will return true).

Arguments

bool style - Set true to enable the default system style for the engine window; false - to disable it.

bool isSystemStyle() const#

Returns the current value indicating if the default system style or the engine style is set for the engine window.

NoticeThis method should be applied to a separate or parent window, using this method for a nested window is not allowed (it will return true).

Return value

true if the default system style for the engine window is enabled; otherwise false.

void setTitleBarHeight ( int height ) #

Sets a new height of the window title bar.

Notice

This value is applied to the windows in the engine style only. For system-style windows system settings are applied.
This method can be applied to a separate or parent window, using this method for a nested window is not allowed (it will return 0).

Arguments

int height - The engine window title bar height.

int getTitleBarHeight() const#

Returns the current height of the window title bar.

Notice

This value is applied to the windows in the engine style only. For system-style windows system settings are applied.
This method can be applied to a separate or parent window, using this method for a nested window is not allowed (it will return 0).

Return value

Current engine window title bar height.

void setTitleBarEnabled ( bool enabled ) #

Sets a new value indicating if the title bar is enabled for the engine window.

Notice

This value is applied to the windows in the engine style only. For system-style windows system settings are applied.
This method should be applied to a separate or parent window, using this method for a nested window is not allowed (it will return 0).

Arguments

bool enabled - Set true to enable the title bar for the engine window; false - to disable it.

bool isTitleBarEnabled() const#

Returns the current value indicating if the title bar is enabled for the engine window.

Notice

This value is applied to the windows in the engine style only. For system-style windows system settings are applied.
This method should be applied to a separate or parent window, using this method for a nested window is not allowed (it will return 0).

// implement the WindowEvent event handler
void windowevent_event_handler(const Ptr<WindowEvent> & event)
{
	Log::message("\Handling WindowEvent event\n");
}


//////////////////////////////////////////////////////////////////////////////
//  1. Multiple subscriptions can be linked to an instance of the EventConnections 
//  class that you can use later to remove all these subscriptions at once
//////////////////////////////////////////////////////////////////////////////

// create an instance of the EventConnections class
EventConnections windowevent_event_connections;

// link to this instance when subscribing to an event (subscription to various events can be linked)
publisher->getEventWindowEvent().connect(windowevent_event_connections, windowevent_event_handler);

// other subscriptions are also linked to this EventConnections instance 
// (e.g. you can subscribe using lambdas)
publisher->getEventWindowEvent().connect(windowevent_event_connections, [](const Ptr<WindowEvent> & event) { 
		Log::message("\Handling WindowEvent event (lambda).\n");
	}
);

// ...

// later all of these linked subscriptions can be removed with a single line
windowevent_event_connections.disconnectAll();

//////////////////////////////////////////////////////////////////////////////
//  2. You can subscribe and unsubscribe via an instance of the EventConnection 
//  class. And toggle this particular connection off and on, when necessary.
//////////////////////////////////////////////////////////////////////////////

// create an instance of the EventConnection class
EventConnection windowevent_event_connection;

// subscribe to the WindowEvent event with a handler function keeping the connection
publisher->getEventWindowEvent().connect(windowevent_event_connection, windowevent_event_handler);

// ...

// you can temporarily disable a particular event connection to perform certain actions
windowevent_event_connection.setEnabled(false);

// ... actions to be performed

// and enable it back when necessary
windowevent_event_connection.setEnabled(true);

// ...

// remove subscription to the WindowEvent event via the connection
windowevent_event_connection.disconnect();

//////////////////////////////////////////////////////////////////////////////
//  3. You can add EventConnection/EventConnections instance as a member of the
//  class that handles the event. In this case all linked subscriptions will be 
//  automatically removed when class destructor is called
//////////////////////////////////////////////////////////////////////////////

// Class handling the event
class SomeClass
{
public:
	// instance of the EventConnections class as a class member
	EventConnections e_connections;

	// A WindowEvent event handler implemented as a class member
	void event_handler(const Ptr<WindowEvent> & event)
	{
		Log::message("\Handling WindowEvent event\n");
		// ...
	}
};

SomeClass *sc = new SomeClass();

// ...

// specify a class instance in case a handler method belongs to some class
publisher->getEventWindowEvent().connect(sc->e_connections, sc, &SomeClass::event_handler);

// ...

// handler class instance is deleted with all its subscriptions removed automatically
delete sc;


//////////////////////////////////////////////////////////////////////////////
//   4. Subscribe to an event saving a particular connection ID
//   and unsubscribe later by this ID
//////////////////////////////////////////////////////////////////////////////
// instance of the EventConnections class to manage event connections
EventConnections e_connections;

// define a particular connection ID to be used to unsubscribe later
EventConnectionId windowevent_handler_id;

// subscribe to the WindowEvent event with a lambda handler function and keeping connection ID
windowevent_handler_id = publisher->getEventWindowEvent().connect(e_connections, [](const Ptr<WindowEvent> & event) { 
		Log::message("\Handling WindowEvent event (lambda).\n");
	}
);

// remove the subscription later using the ID
publisher->getEventWindowEvent().disconnect(windowevent_handler_id);


//////////////////////////////////////////////////////////////////////////////
//   5. Ignoring all WindowEvent events when necessary
//////////////////////////////////////////////////////////////////////////////

// you can temporarily disable the event to perform certain actions without triggering it
publisher->getEventWindowEvent().setEnabled(false);

// ... actions to be performed

// and enable it back when necessary
publisher->getEventWindowEvent().setEnabled(true);

Return value

Event reference.

void moveToCenter ( ) #

Positions the window so that the client center coincides with the center of the current display.

NoticeThis method should be applied to a separate or parent window, using this method for a nested window is not allowed.

void setMinAndMaxSize ( const Math::ivec2 & min_size, const Math::ivec2 & max_size ) #

Sets the minimum and maximum possible window size when resizing the window.

NoticeThis method should be applied to a separate or parent window, using this method for a nested window is not allowed.

Arguments

const Math::ivec2 & min_size - The minimum possible size of the window.
const Math::ivec2 & max_size - The maximum possible size of the window.

int setIcon ( const Ptr<Image> & image ) #

Sets the icon for the window.

Arguments

const Ptr<Image> & image - The icon for the window.

Return value

1 if the specified icon is successfully set for the window, otherwise 0.

int getIcon ( ) const#

Returns the icon for the engine window.

Return value

The icon for the window.1 if the icon for the window is returned successfully, otherwise 0.

void show ( ) #

Enables rendering of the engine window.

NoticeThis method should be applied to a separate or parent window, using this method for a nested window is not allowed.

void hide ( ) #

Disables rendering of the engine window.

NoticeThis method should be applied to a separate or parent window, using this method for a nested window is not allowed.

void setFocus ( ) #

Sets the focus to the window.

void setSystemFocus ( ) #

Sets the focus to the engine window.

Notice

This method is applied to a separate or parent window, for nested windows use setFocus().

void minimize ( ) #

Minimizes the engine window to an iconic representation.

NoticeThis method should be applied to a separate or parent window, using this method for a nested window is not allowed.

void maximize ( ) #

Makes the engine window as large as possible.

NoticeThis method should be applied to a separate or parent window, using this method for a nested window is not allowed.

void restore ( ) #

Restores the size and position of the minimized or maximized engine window via the system proxy.

NoticeThis method should be applied to a separate or parent window, using this method for a nested window is not allowed.

EngineWindow::HITTEST getHitTestResult ( const Math::ivec2 & global_pos ) #

Returns a value indicating in which area of the engine window the mouse is located.

NoticeThis method is used for interaction with system windows only, i.e. it cannot be used for nested windows.

Arguments

const Math::ivec2 & global_pos - Global coordinates of the hit-test point.

Return value

Value indicating the window area, one of the HITTEST_* values.

const char * getHitTestResultName ( EngineWindow::HITTEST hit_test ) const#

Returns the string representation of the hit test result value.

Arguments

EngineWindow::HITTEST hit_test - Value indicating the window area, one of the HITTEST_* values.

Return value

The string representation of the hit test result value (e.g., HITTEST_RESIZE_RIGHT is RESIZE RIGHT).

void toTop ( ) #

Makes the window appear on top of all other windows.

NoticeThis method should be applied to a separate or parent window, using this method for a nested window is not allowed.

bool isGlobalChildOf ( const Ptr<EngineWindowGroup> & group ) #

Returns the value specifying if the current window is a part of a hierarchy of the specified window.

Arguments

const Ptr<EngineWindowGroup> & group - Window to be checked.

Return value

true if the current window is globally a child of the specified one, otherwise false.

void updateGuiHierarchy ( ) #

Updates the hierarchy for all widgets — the widgets are arranged, expanded to the required sizes and then their positions are updated. Updating the hierarchy may be required, for example, for getting the screen position immediately after the widget has been added to the hierarchy. For a separate window, the hierarchy in self gui is updated; for a nested window, the hierarchy in self gui of the global parent group is updated.

const char * getDroppedItem ( int index ) const#

Returns the absolute path to the file or folder dropped to the window.

Arguments

int index - Index of the dropped file or folder.

Return value

Absolute path to the dropped file or folder.

void screenshot ( const char * path ) #

Creates a screenshot after the rendering stage is completed.

NoticeThis method should be applied to a separate or parent window, using this method for a nested window is not allowed.

Arguments

const char * path - Path to save the screenshot.

void setModal ( const Ptr<EngineWindow> & parent_window ) #

Sets the current window modal to the specified parent window. Both the parent and the child windows must be separate. The concept of modal assumes that if a window has modal children, it cannot be closed. Any other interaction with a parent window is possible.

NoticeThis method should be applied to a separate or parent window, a nested window can't be a parent for a modal window.

Arguments

const Ptr<EngineWindow> & parent_window - Parent window.

void addModalWindow ( const Ptr<EngineWindow> & window ) #

Adds the argument window as modal to the current window. Both the parent and the child windows must be separate. The concept of modal assumes that if a window has modal children, it cannot be closed. Any other interaction with a parent window is possible.

NoticeThis method should be applied to a separate or parent window, a nested window can't be a parent for a modal window.

Arguments

const Ptr<EngineWindow> & window - Window to be added as modal.

void removeModalWindow ( const Ptr<EngineWindow> & window ) #

Removes the argument modal window from this window. The concept of modal assumes that if a window has modal children, it cannot be closed. Any other interaction with a parent window is possible.

NoticeThis method should be applied to a separate or parent window, a nested window can't be a parent for a modal window.

Arguments

const Ptr<EngineWindow> & window - Engine window.

Ptr<EngineWindow> getModalWindow ( int index ) const#

Returns the modal window for this window by its index. The concept of modal assumes that if a window has modal children, it cannot be closed. Any other interaction with a parent window is possible.

NoticeThis method should be applied to a separate or parent window, for a nested window it will return nullptr.

Arguments

int index - Index of the modal window.

Return value

Modal window.

void unstack ( ) #

Removes the current window from a parent group.

void close ( ) #

Deletes the window if this window is not a modal parent or a member of a fixed group. If a window is a member of a fixed group, it cannot be closed (i.e. deleted).

bool getIntersection ( const Math::ivec2 & global_mouse_pos ) const#

Returns the value indicating if the mouse is hovering over the window.

Arguments

const Math::ivec2 & global_mouse_pos - Global screen coordinates of the mouse relative to the main display.

Return value

true if the mouse hovers over the current window, otherwise false.

bool getClientIntersection ( const Math::ivec2 & global_mouse_pos ) const#

Returns the value indicating if the mouse is hovering over the client area of the window.

Source code (C++)

//checks if the mouse is hovering over the main window
WindowManager::getMainWindow()->getClientIntersection(Input::getMousePosition());

Arguments

const Math::ivec2 & global_mouse_pos - Global screen coordinates of the mouse relative to the main display.

Return value

true if the mouse hovers over the client area of the window, otherwise false.

EngineWindow::AREA getClient9Area ( const Math::ivec2 & global_mouse_pos ) const#

Returns the area over which the mouse hovers, one of the nine areas into which the window is segmented.

Arguments

const Math::ivec2 & global_mouse_pos - Global screen coordinates of the mouse relative to the main display.

Return value

One of the nine segments the screen area is split into.

const char * get9AreaName ( EngineWindow::AREA area ) const#

Returns the name of the screen segment as a string.

Arguments

EngineWindow::AREA area - One of the nine segments the screen area is split into.

Return value

The string representation of the segment value (e.g., AREA_TOP_LEFT is TOP LEFT).

Math::ivec2 globalToLocalUnitPosition ( const Math::ivec2 & global_pos ) const#

Transforms the global screen coordinates in pixels into units relative to the window client area.

Arguments

const Math::ivec2 & global_pos - The position in global coordinates.

Return value

The coordinates in units relative to the window client area.

Math::ivec2 localUnitToGlobalPosition ( const Math::ivec2 & unit_pos ) const#

Transforms the position in units relative to the window client area into the global screen coordinates in pixels.

Arguments

const Math::ivec2 & unit_pos - The coordinates in units relative to the window client area.

Return value

The position in global coordinates.

int toRenderSize ( int unit_size ) #

Transforms the unit value to the pixel value.

Arguments

int unit_size - Size in units.

Return value

Size in pixels.

int toUnitSize ( int render_size ) #

Transforms the pixel value to the unit value.

Arguments

int render_size - Size in pixels.

Return value

Size in units.

Math::ivec2 toRenderSize ( const Math::ivec2 & unit_size ) #

Transforms the unit value to the pixel value.

Arguments

const Math::ivec2 & unit_size - Size in units.

Return value

Size in pixels.

Math::ivec2 toUnitSize ( const Math::ivec2 & render_size ) #

Transforms the pixel value to the unit value.

Arguments

const Math::ivec2 & render_size - Size in pixels.

Return value

Size in units.

Last update: 2024-08-16

Help improve this article

Was this article helpful?

Report a problem related to this article

(or select a word/phrase and press Ctrl+Enter)

Unigine::EngineWindow Class

In This Article:

Setting Up Position and Size#

Adjusting Visual Representation#

Setting Up Order#

Changing Behavior#

Working with Modal Windows#

Methods:

See Also#

EngineWindow Class

Enums

HITTEST#

FLAGS#

AREA#

TYPE#

Members

Ptr<Gui> getGui() const#

Return value

int getDisplayIndex() const#

Return value

bool isNested() const#

Return value

bool isSeparate() const#

Return value

Ptr<Gui> getSelfGui() const#

Return value

void setPosition ( const Math::ivec2& position ) #

Arguments

Math::ivec2 getPosition() const#

Return value

void setClientPosition ( const Math::ivec2& position ) #

Arguments

Math::ivec2 getClientPosition() const#

Return value

Math::ivec2 getClientLocalPosition() const#

Return value

void setSize ( const Math::ivec2& size ) #

Arguments

Math::ivec2 getSize() const#

Return value

void setClientSize ( const Math::ivec2& size ) #

Arguments

Math::ivec2 getClientSize() const#

Return value

void setMinSize ( const Math::ivec2& size ) #

Arguments

Math::ivec2 getMinSize() const#

Return value

void setMaxSize ( const Math::ivec2& size ) #

Arguments

Math::ivec2 getMaxSize() const#

Return value

void setTitle ( const char * title ) #

Arguments

const char * getTitle() const#

Return value

void setOpacity ( float opacity ) #

Arguments

float getOpacity() const#

Return value

void setBordersEnabled ( bool enabled ) #

Arguments

bool isBordersEnabled() const#

Return value

void setBorderSize ( int size ) #

Arguments

int getBorderSize() const#

Return value

void setResizable ( bool resizable ) #

Arguments

bool isResizable() const#

Return value

bool isShown() const#

Return value

bool isHidden() const#

Return value

bool isFocused() const#

Return value

bool isMinimized() const#

Return value