Unigine::App Class

Header:

#include <UnigineApp.h>

The App class contains functions to control the Unigine application graphic context, which includes:

Update parameters
Events of the controls (keyboard, mouse)
FPS
Window parameters (height, width, name, etc.)

The class is used, for example, when you need to get and manage user input.

Usage Example#

The following examples perform:

Changing parameters of the application window (such as title, icon). The specified changes are applied after application start-up. It means that the window with default settings will appear first. If you need the custom settings are applied before the application window is displayed, you should implement your own class inherited from the App class.
Processing user inputs.
Updating the application in background.

Changing Window Parameters#

AppSystemLogic.cpp

Source code (C++)

#include "AppSystemLogic.h"

#include <UnigineApp.h>
#include <UnigineImage.h>

using namespace Unigine;


int AppSystemLogic::init() {

	// set a custom icon for the application window
	ImagePtr icon = Image::create("textures/window_icon.png");
	App::setIcon(icon);

	// set a custom title for the application window
	App::setTitle("Custom Window Title");

	return 1;
}

int AppSystemLogic::update() {
	
	// get an image for the mouse pointer
	ImagePtr mouse = Image::create();
	mouse->load("textures/mouse_pointer.png");
	// resize the image to make it square
	mouse->resize(mouse->getWidth(),mouse->getWidth());
	if (mouse->isLoaded() && mouse->getFormat() == Image::FORMAT_RGBA8)
	{
		// set the image for the OS mouse pointer
		App::setMouseCursor(mouse->getPixels(), mouse->getWidth());
		// show the OS mouse pointer
		App::setMouseShow(1);
	}
	
	return 1;
}

Processing User Inputs#

AppWorldLogic.cpp

Source code (C++)

#include "AppWorldLogic.h"

#include <UnigineApp.h>
#include <UnigineWorld.h>
#include <UnigineGame.h>
#include <UnigineGui.h>
#include <UnigineNode.h>
#include <UniginePlayers.h>

using namespace Unigine;

// declare a player pointer
PlayerPersecutorPtr player;

int AppWorldLogic::init() {
	
	// update the application constantly
	App::setBackgroundUpdate(1);
	// get a node
	NodePtr node = World::getNodeByName("material_ball");
	// create a new persecutor
	player = PlayerPersecutor::create();
	// set the obtainde node as the target one
	player->setTarget(node);
	// set player's settings
	player->setAnchor(Math::vec3(0, 0, 0.45f));
	player->setPhiAngle(-130.0f);
	player->setMinDistance(0.3f);
	player->setMaxDistance(20.0f);
	player->setDistance(5.0f);
	player->setFov(35.0f);
	// set the player to the Game Camera viewport
	Game::setPlayer(player);

	return 1;
}

int AppWorldLogic::update() {

	// change the distance between the player and the target node on mouse wheel scrolling
	int scroll_delta = App::getMouseAxis(App::AXIS_Y);
	if (scroll_delta != 0) {
		float f_scroll_delta = scroll_delta / 30.0f;
		player->setDistance(player->getDistance() - f_scroll_delta);
	}

	// zoom the camera in or out when the right mouse button is pressed and the mouse is moved backward/forward
	if (App::getMouseButton() == App::BUTTON_RIGHT) {
		float mouse_delta = (Gui::get()->getMouseDY() + Gui::get()->getMouseDX()) / 500.0f;
		player->setDistance(player->getDistance() - mouse_delta);
	}

	return 1;
}

int AppWorldLogic::shutdown() {
	
	// clear the player pointer
	player.clear();

	return 1;
}

Methods:

Name	Description View: Sort by:
isActive	Returns a value indicating if the current application is active (i.e. in focus).
isLegacyMode	Returns a value indicating if rendering during the Engine's initialization stage is disabled for the application.
setButtonPressFunc	Application event which is called when pressing the button.
setButtonReleaseFunc	Application event which is called when releasing the button.
setClipboard	Updates the contents of the system clipboard.
getClipboard	Retrieves the contents of the system clipboard.
getHandle	Returns a pointer to the application handle.
isDone	Returns a value indicating if the application is closed.
isInitialized	Returns a value indicating if the application is initialized.
getFlags	Returns the video mode flags set for the application.
getFps	Returns the application FPS counter value.
getMinFps	Returns the minimum FPS counter value for the last 600 frames.
getMaxFps	Returns the maximum FPS counter value for the last 600 frames.
getMeanFps	Returns the average FPS counter value for the last 600 frames.
setHeight	Sets the new height for the application window.
getHeight	Returns the current height of the application window.
setIcon	Sets an icon for the application window.
getIFps	Returns an inverse value of the application FPS counter.
getKeyName	Returns a name of the given key.
setKeyPressFunc	Application event which is called on pressing the key.
setKeyPressUnicodeFunc	Application event which is called on pressing the unicode key.
setKeyReleaseFunc	Application event which is called on releasing the key.
setKeyState	Sets the keyboard key state (pressed or not pressed).
getKeyState	Returns the keyboard key state (pressed or not pressed).
setMouse	Sets a mouse pointer to the specified position in the coordinate system of the application window.
setMouseAxis	Sets the mouse wheel delta along the specified axis.
getMouseAxis	Returns the current mouse wheel delta along the specified axis.
setMouseButton	Simulates pressing of the specified mouse buttons.
getMouseButton	Returns the current states of all mouse buttons.
getMouseButtonName	Returns a name of the given button.
getMouseButtonState	Returns a state of the specified button (pressed or not pressed).
setMouseGrab	Sets a value indicating if the mouse pointer is bound to the application window.
isMouseGrab	Returns a value indicating if the mouse pointer is bound to the application window.
getMouseX	Returns the current X coordinate of the mouse pointer in the coordinate system of the application window.
getMouseY	Returns the current Y coordinate of the mouse pointer in the coordinate system of the application window.
getName	Returns a name of the graphics API used for application rendering.
getNumTouches	Returns the number of touches.
setPosition	Sets the window position.
getPositionX	Returns the X coordinate of the upper-left corner of the window.
getPositionY	Returns the Y coordinate of the upper-left corner of the window.
setTitle	Sets a title for the application window.
getTouchX	Returns the X coordinate of the touch in the coordinate system of the application window.
getTouchY	Returns the Y coordinate of the touch in the coordinate system of the application window.
setBackgroundUpdate	Sets the value indicating whether the application window is updated when the window is hidden or out of focus (rendering frames in background).
isBackgroundUpdate	Returns a value indicating whether the application window is updated when the window is hidden or out of focus.
setVideoMode	Sets a video mode and initializes the application.
getVideoModeName	Returns the name of the current video mode.
setWidth	Sets the new width of the application window.
getWidth	Returns the current application window width.
buttonPress	Application notifies the engine that the specified mouse button is pressed.
buttonRelease	Application notifies the engine that the specified mouse button is released.
clearKeyState	Returns the key state and clears it to 0 (not pressed).
clearMouseAxis	Returns the current mouse wheel position delta and clears it to 0.
clearMouseButtonState	Returns the button state and clears it to 0 (not pressed).
dialogFile	Creates a system modal file dialog.
dialogMessage	Creates a system modal message dialog.
exit	The engine requests to exit the application.
keyPress	Application notifies the engine that the specified key on a keyboard is pressed.
keyPressUnicode	Application notifies the engine that the specified key is pressed.
keyRelease	Application notifies the engine that the specified key on a keyboard is released.
startFps	Starts the FPS counter if it was stopped.
stopFps	Stops the FPS counter.
setMouseCursorHide	Sets a value indicating if the mouse cursor should be hidden.
isMouseCursorHide	Returns a value indicating if the mouse cursor is hidden in the current frame.
setMouseCursorSystem	Sets a value indicating if the OS mouse pointer should be displayed.
isMouseCursorSystem	Returns a value indicating if the OS mouse pointer is displayed.
setMouseCursorNeedUpdate	Sets a value indicating that some changes were made to the cursor (e.
isMouseCursorNeedUpdate	Returns a value indicating that changes were made to the cursor (e.
setMouseCursorSkinCustom	Sets a custom image to be used for the mouse cursor.
setMouseCursorSkinSystem	Sets the current OS cursor skin (pointer shapes like select, move, resize, etc.
setMouseCursorSkinDefault	Sets the default Engine cursor skin (pointer shapes like select, move, resize, etc.
setMouseCursorCustom	Sets a custom image for the OS mouse cursor.
clearMouseCursorCustom	Clears the custom mouse cursor set via the setMouseCursorCustom() method.
updateMouseCursor	Updates the mouse cursor.
dialogMessage	Displays a message dialog with the specified title and text.
dialogWarning	Displays a warning dialog with the specified title and text.
dialogError	Displays an error dialog with the specified title and text.
showSystemDialog	Displays a custom system dialog with an arbitrary set of buttons.
dialogOpenFolder	Opens a common dialog enabling the user to specify a folder to open.
dialogOpenFiles	Opens a common dialog enabling the user to specify a list of filenames to open multiple files.
dialogOpenFile	Opens a common dialog enabling the user to specify a filename to open a file.
dialogSaveFile	Opens a common dialog enabling the user to specify a filename to save a file as.
setExternalWindowFocused	Sets a value indicating whether some external window of the application is currently focused.
isExternalWindowFocused	Returns a value indicating whether some external window of the application is currently focused.
setCustomSwapBuffersCallback	Sets a callback to subscribe for an event to take place instead of swapping from the back buffer to the front one.
getCustomSwapBuffersCallback	Returns the current buffer swap callback function set for the application.

Variables:

Name	Description
AXIS_X = 0	A mouse wheel is scrolled horizontally (along the X axis; a horizontal mouse wheel is required).
AXIS_Y = 0	A mouse wheel is scrolled vertically (along the Y axis; a vertical mouse wheel is used).
BREAK_ON_ERROR = 0	Break if an error occurs.
BUTTON_AUX_0 = 0	Detected activity of the first auxiliary mouse button.
BUTTON_AUX_1 = 0	Detected activity of the second auxiliary mouse button.
BUTTON_AUX_2 = 0	Detected activity of the third auxiliary mouse button.
BUTTON_AUX_3 = 0	Detected activity of the fourth auxiliary mouse button.
BUTTON_DCLICK = 0	Left mouse button is double-clicked.
BUTTON_LEFT = 0	Detected activity of the left mouse button.
BUTTON_MIDDLE = 0	Detected activity of the middle mouse button (scrolling wheel).
BUTTON_RIGHT = 0	Detected activity of the right mouse button.
DEBUG_CONTEXT = 0	Debug context is enabled.
FULLSCREEN = 0	Fullscreen mode.
FULLWINDOW = 0	Full window mode.
KEY_ALT = 0	The ALT key is pressed.
KEY_BACKSPACE = 0	The Backspace key is pressed.
KEY_CAPS = 0	The Caps Lock key is pressed.
KEY_CMD = 0	The Command key is pressed (for OS X).
KEY_CTRL = 0	The Ctrl key is pressed.
KEY_DELETE = 0	The Delete key is pressed.
KEY_DOWN = 0	The Down Arrow key is pressed.
KEY_END = 0	The End key is pressed.
KEY_ESC = 0	The Esc key is pressed.
KEY_F1 = 0	The F1 key is pressed.
KEY_F10 = 0	The F10 key is pressed.
KEY_F11 = 0	The F11 key is pressed.
KEY_F12 = 0	The F12 key is pressed.
KEY_F2 = 0	The F2 key is pressed.
KEY_F3 = 0	The F3 key is pressed.
KEY_F4 = 0	The F4 key is pressed.
KEY_F5 = 0	The F5 key is pressed.
KEY_F6 = 0	The F6 key is pressed.
KEY_F7 = 0	The F7 key is pressed.
KEY_F8 = 0	The F8 key is pressed.
KEY_F9 = 0	The F9 key is pressed.
KEY_HOME = 0	The Home key is pressed.
KEY_INSERT = 0	The Insert key is pressed.
KEY_LEFT = 0	The Left Arrow key is pressed.
KEY_NUM = 0	The Num Lock key is pressed.
KEY_PGDOWN = 0	The Page Down key is pressed.
KEY_PGUP = 0	The Page Up key is pressed.
KEY_RETURN = 0	The Enter (Return) key is pressed.
KEY_RIGHT = 0	The Right Arrow key is pressed.
KEY_SCROLL = 0	The Scroll Lock key is pressed.
KEY_SHIFT = 0	The Shift key is pressed.
KEY_TAB = 0	The Tab key is pressed.
KEY_UP = 0	The Page Up key is pressed.
NUM_AXES = 0	Number of axes, along which a mouse wheel can be scrolled.
NUM_KEYS = 0	Detected number of keyboard keys.
NUM_TOUCHES = 0	Number of the detached touches (for touch-screen controls).
RESIZABLE = 0	Resizable window.
VSYNC = 0	Vertical synchronization.
QUAD_BUFFER_CONTEXT = 0	Quad buffer context is enabled.
INDEPENDENT_SIZE_WINDOW = 0	Window size is independent of rendering resolution.

App Class

Members

int isActive ( ) #

Returns a value indicating if the current application is active (i.e. in focus). The function will always return 1, if the window background update mode is set to 1.

NoticeThe sounds will be automatically disabled, if the application is not active.

Return value

1 if application is active; otherwise, 0.

int isLegacyMode ( ) const#

Returns a value indicating if rendering during the Engine's initialization stage is disabled for the application. Engine's boot screen requires rendering to be performed at the Engine's initialization stage. Certain applications do not support rendering in the init() by design. To ensure stable operation for such apps you can disable render-during-init functionality by setting the legacy mode. Thus, the boot screen won't be displayed for these applications.

Return value

1 if rendering during the Engine's initialization stage is disabled for the application; otherwise, 0.

void setButtonPressFunc ( int (*func)(int button) ) #

Application event which is called when pressing the button. The engine will stop event processing if the event function returns 1.

Arguments

int (*func)(int button) - Event function pointer.

void setButtonReleaseFunc ( int (*func)(int button) ) #

Application event which is called when releasing the button. The engine will stop event processing if the event function Returns 1.

Arguments

int (*func)(int button) - Event function pointer.

void setClipboard ( const char * str ) #

Updates the contents of the system clipboard.

Arguments

const char * str - Contents to set.

const char * getClipboard ( ) #

Retrieves the contents of the system clipboard.

Return value

Contents of the system clipboard.

void * getHandle ( ) #

Returns a pointer to the application handle.

Return value

Pointer to the application handle.

int isDone ( ) #

Returns a value indicating if the application is closed.

Return value

1 if the application is closed; otherwise, 0.

int isInitialized ( ) #

Returns a value indicating if the application is initialized.

Return value

1 if the application is initialized; otherwise, 0.

int getFlags ( ) #

Returns the video mode flags set for the application.

Return value

Video mode flags: RESIZABLE, FULLSCREEN, etc.

float getFps ( ) #

Returns the application FPS counter value.

Return value

Application FPS counter value.

float getMinFps ( ) #

Returns the minimum FPS counter value for the last 600 frames.

Return value

Minimum FPS counter value for the last 600 frames.

float getMaxFps ( ) #

Returns the maximum FPS counter value for the last 600 frames.

Return value

Maximum FPS counter value for the last 600 frames.

float getMeanFps ( ) #

Returns the average FPS counter value for the last 600 frames.

Return value

Average FPS counter value for the last 600 frames.

void setHeight ( int value ) #

Sets the new height for the application window. The height is specified for the window inside and doesn't include the window borders.

Notice

If the INDEPENDENT_SIZE_WINDOW flag is set, only render resolution will be changed, leaving the window size unaffected.

Arguments

int value - Application window height, in pixels.

int getHeight ( ) #

Returns the current height of the application window. The returned value is the window inside height without borders.

Return value

Current height of the application window, in pixels.

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

Sets an icon for the application window. The image must be of the square size and RGBA8 format.

Source code (C++)

// create an instance of the Image class
ImagePtr icon = Image::create("window_icon.png");
// set the image as an icon of the application window
App::setIcon(icon);

Arguments

const Ptr<Image> & icon - Image to be set as application's icon.

Return value

1 if the icon is set successfully; otherwise, 0.

float getIFps ( ) #

Returns an inverse value of the application FPS counter.

Return value

Inverse value of the application FPS counter (1/FPS).

const char * getKeyName ( int key ) #

Returns a name of the given key.

Source code (C++)

Log::message("getKeyName() returned: %s\n", App::getKeyName(App::KEY_ALT));
Log::message("getKeyName() returned: %s\n", App::getKeyName(97));

Output

getKeyName() returned: ALT
getKeyName() returned: a

Arguments

int key - Key in one of the following formats:
- Character format (for example, 'a')
- Standard ASCII key code (for example, 97)
- One of KEY_* variables

Return value

Key name.

void setKeyPressFunc ( int (*func)(unsigned int key) ) #

Application event which is called on pressing the key. The engine will stop event processing if the event function returns 1.

Arguments

int (*func)(unsigned int key) - Event function pointer.

void setKeyPressUnicodeFunc ( int (*func)(unsigned int key) ) #

Application event which is called on pressing the unicode key. The engine will stop event processing if the event function returns 1.

Arguments

int (*func)(unsigned int key) - Event function pointer.

void setKeyReleaseFunc ( int (*func)(unsigned int key) ) #

Application event which is called on releasing the key. The engine will stop event processing if the event function returns 1.

Arguments

int (*func)(unsigned int key) - Event function pointer.

void setKeyState ( int key, int state ) #

Sets the keyboard key state (pressed or not pressed).

Source code (C++)

// set the ALT button pressed
App::setKeyState(App::KEY_ALT, 1);
// set the 'a' button pressed
App::setKeyState(97, 1);

Arguments

int key - Key ID. Possible values can be in range [0;255], which are standard ASCII code symbols, or in range [KEY_ESC;KEY_F12], which are used for control buttons. For full list of control buttons see KEY_* variables.
int state - Key state: 1 to set the button pressed; 0 to set the button not pressed.

int getKeyState ( int key ) #

Returns the keyboard key state (pressed or not pressed).

Source code (C++)

if (App::getKeyState(App::KEY_ALT)) Log::message("ALT has been pressed\n");
if (App::getKeyState(97)) Log::message("'a' has been pressed\n");

Arguments

int key - Key ID. Possible values can be in range [0;255], which are standard ASCII code symbols, or in range [KEY_ESC;KEY_F12], which are used for control buttons. For full list of control button see KEY_* variables.

Return value

1 if the key is pressed; otherwise, 0.

void setMouse ( int x, int y ) #

Sets a mouse pointer to the specified position in the coordinate system of the application window.

Source code (C++)

// set a position of the mouse pointer
int mouse_x = App::getWidth() / 2;
int mouse_y = App::getHeight() / 2;

// set the mouse pointer to the position on pressing Esc
if (App::clearKeyState(App::KEY_ESC))
{
	// check if the mouse pointer is bound to the application window
	if (App::isMouseGrab())
		// set the pointer to the position
		App::setMouse(mouse_x, mouse_y);
}

Arguments

int x - X coordinate of the mouse pointer.
int y - Y coordinate of the mouse pointer.

void setMouseAxis ( int axis, int value ) #

Sets the mouse wheel delta along the specified axis. The delta value is changed when scrolling the mouse wheel horizontally (APP_AXIS_X) or vertically (APP_AXIS_Y).

Arguments

int axis - Mouse axis. Possible values are AXIS_X, AXIS_Y.
int value - Mouse wheel delta.

int getMouseAxis ( int axis ) #

Returns the current mouse wheel delta along the specified axis. The delta value is changed when scrolling the mouse wheel horizontally (AXIS_X) or vertically (AXIS_Y).

Source code (C++)

int axis_x = App::getMouseAxis(App::AXIS_X);
int axis_y = App::getMouseAxis(App::AXIS_Y);
if(axis_x > 0) Log::message("Mouse wheel has been scrolled right\n");
if(axis_x < 0) Log::message("Mouse wheel has been scrolled left\n");
if(axis_y > 0) Log::message("Mouse wheel has been scrolled up\n");
if(axis_y < 0) Log::message("Mouse wheel has been scrolled down\n");

Arguments

int axis - Mouse axis. Possible values are AXIS_X, AXIS_Y.

Return value

Mouse wheel delta regarding the last wheel position.

void setMouseButton ( int button ) #

Simulates pressing of the specified mouse buttons.

Source code (C++)

// set the right and middle mouse buttons pressed in addition to already pressed buttons
App::setMouseButton(App::getMouseButton() | App::BUTTON_RIGHT | App::BUTTON_MIDDLE);

Arguments

int button - Mouse buttons to be pressed. Possible values are BUTTON_*.

int getMouseButton ( ) #

Returns the current states of all mouse buttons. Each bit of the returned bit mask will specify the state of the buttons in the following order:

BUTTON_LEFT = 1 << 0
BUTTON_MIDDLE
BUTTON_RIGHT
BUTTON_DCLICK
BUTTON_AUX_0
BUTTON_AUX_1
BUTTON_AUX_2
BUTTON_AUX_3

Return value

A bit mask that stores current states of all mouse buttons (pressed or not pressed).

const char * getMouseButtonName ( int button ) #

Returns a name of the given button.

Arguments

int button - One of BUTTON_* variables.

Return value

Button name.

int getMouseButtonState ( int button ) #

Returns a state of the specified button (pressed or not pressed). If several buttons are specified, the function will return the state of the first pressed button (if any); if no buttons are pressed, the function will return 0.

Source code (C++)

if (App::getMouseButtonState(App::BUTTON_LEFT | App::BUTTON_DCLICK)) Log::message("Left mouse button has been clicked\n");
if (App::getMouseButtonState(App::BUTTON_MIDDLE)) Log::message("Middle mouse button has been clicked\n");

Arguments

int button - One of BUTTON_* variables

Return value

1 if al least one of the specified buttons is pressed; otherwise, 0.

void setMouseGrab ( int grab ) #

Sets a value indicating if the mouse pointer is bound to the application window.

Arguments

int grab - 1 if the mouse cannot leave the application window; otherwise, 0.

bool isMouseGrab ( ) #

Returns a value indicating if the mouse pointer is bound to the application window.

Return value

true if the mouse pointer cannot leave the application window; otherwise, false.

int getMouseX ( ) #

Returns the current X coordinate of the mouse pointer in the coordinate system of the application window.

Return value

X coordinate of the mouse pointer.

int getMouseY ( ) #

Returns the current Y coordinate of the mouse pointer in the coordinate system of the application window.

Return value

Y coordinate of the mouse pointer.

const char * getName ( ) #

Returns a name of the graphics API used for application rendering.

Return value

One of the following values:

opengl for OpenGL
direct3d11 for DirectX 11
NULL if no graphics API is used for application rendering

int getNumTouches ( ) #

Returns the number of touches. The maximum number of touches is 16.

Return value

Number of touches.

int setPosition ( int x, int y ) #

Sets the window position.

Arguments

int x - X coordinate of the upper-left corner of the window.
int y - Y coordinate of the upper-left corner of the window.

Return value

1 if the position of the window is set successfully; otherwise, 0.

int getPositionX ( ) #

Returns the X coordinate of the upper-left corner of the window.

Return value

X coordinate of the upper-left corner of the window.

int getPositionY ( ) #

Returns the Y coordinate of the upper-left corner of the window.

Return value

Y coordinate of the upper-left corner of the window.

int setTitle ( const char * title ) #

Sets a title for the application window.

Arguments

const char * title - Window title.

Return value

1 if the title is set successfully; otherwise, 0.

int getTouchX ( int touch ) #

Returns the X coordinate of the touch in the coordinate system of the application window.

Arguments

int touch - The touch number.

Return value

X coordinate of the touch.

int getTouchY ( int touch ) #

Returns the Y coordinate of the touch in the coordinate system of the application window.

Arguments

int touch - The toucn number.

Return value

Y coordinate of the touch.

void setBackgroundUpdate ( bool update ) #

Sets the value indicating whether the application window is updated when the window is hidden or out of focus (rendering frames in background). By default your UNIGINE application stops rendering frames and updating its main window, when it window goes out of focus (e.g. user switches to another window). Setting the background update mode enables constant rendering regardless of whether the application window is focused or in the background.

Arguments

bool update - Window update mode: true for constantly repeating update cycle (i.e. the application is updated even if the window is hidden or out of focus); otherwise, false.

bool isBackgroundUpdate ( ) #

Returns a value indicating whether the application window is updated when the window is hidden or out of focus.

Return value

true if the update cycle is constantly repeated (i.e. the application is updated even if the window is hidden or out of focus); otherwise, false.

bool setVideoMode ( int width, int height, int flags = 0 ) #

Sets a video mode and initializes the application.

Arguments

int width - Video width in pixels.
int height - Video height in pixels.
int flags - Video mode flags: RESIZABLE, FULLSCREEN, FULLWINDOW, VSYNC, DEBUG_CONTEXT, BREAK_ON_ERROR.

Return value

true if the video mode is set and the application is initialized successfully; otherwise, false.

const char * getVideoModeName ( ) #

Returns the name of the current video mode.

Return value

Returns the name of the current video mode.

void setWidth ( int value ) #

Sets the new width of the application window. The width is specified for the window inside part and doesn't include the window borders.

Notice

If the INDEPENDENT_SIZE_WINDOW flag is set, only render resolution will be changed, leaving the window size unaffected.

Arguments

int value - Window width, in pixels.

int getWidth ( ) #

Returns the current application window width. The returned value is the window inside part width without borders.

Return value

Window width, in pixels.

void buttonPress ( int button ) #

Application notifies the engine that the specified mouse button is pressed.

Arguments

int button - One of the BUTTON_* variables.

void buttonRelease ( int button ) #

Application notifies the engine that the specified mouse button is released.

Arguments

int button - One of the BUTTON_* variables.

int clearKeyState ( int key ) #

Returns the key state and clears it to 0 (not pressed). This function allows returning the key state only once even if it is kept pressed over several frames.

Arguments

int key - Key ID. Possible values can be in range [0;255], which are standard ASCII code symbols, or in range [KEY_ESC;KEY_F12], which are used for control buttons. For full list of control buttons see KEY_* variables.

Return value

1 if the key is pressed, and this function was not called previously in the current frame; otherwise, 0.

int clearMouseAxis ( int axis ) #

Returns the current mouse wheel position delta and clears it to 0.

Arguments

int axis - Mouse wheel axis. Possible values are AXIS_X, AXIS_Y.

Return value

Mouse wheel delta regarding the last mouse wheel position.

int clearMouseButtonState ( int button ) #

Returns the button state and clears it to 0 (not pressed). This function allows returning the button state only once even if it is kept pressed over several frames. The function will return 1 if at least one of the specified buttons is pressed.

Source code (C++)

// the function will return 1 if one of the buttons is pressed;
// the button state will be set to 0
App::clearMouseButtonState(App::BUTTON_LEFT | App::BUTTON_RIGHT);

Arguments

int button - Button. Possible values are BUTTON_*.

Return value

1 if at least one of the buttons is pressed, and this function was not called previously in the current frame; otherwise, 0.

int dialogFile ( const char * title, char * name, int size, const char * filter = 0, const char * flags = 0 ) #

Creates a system modal file dialog. Since the dialog is modal, all other actions are stopped until this function returns a value.

Arguments

const char * title - Title of the dialog window.
char * name - Current file name.
int size - Size of the name buffer.
const char * filter - File extension filter. Accepts dot-separated file extensions, for example: ".tga.jpg.png.tif.psd".
const char * flags - File dialog flags. Accepts a string: "o" - open file dialog; "s" - save file dialog; "d" - directory dialog.

Return value

1 if the OK button is pressed; 0 if the Cancel button is pressed.

int dialogMessage ( const char * title, const char * str, const char * flags = 0 ) #

Creates a system modal message dialog. Since the dialog is modal, all other actions are stopped until this function returns a value.

Notice

If you don't specify flags, the Oc combination will be used by default.

Arguments

const char * title - Title of the dialog window.
const char * str - Content of the dialog window.
const char * flags - Dialog window flags. The argument accepts a string with names of buttons. The following combinations are available:
- Oc or oC - OK, Cancel.
- Yn or yN - Yes, No
- ynC, yNc or Ync - Yes, No, Cancel
Notice
The uppercase letter indicates which button will be in focus.
If you send any other combination, only the OK button will appear in the window.

Return value

The function returns one of the following values:

1 if the OK button has been pressed.
2 if the Yes button has been pressed.
-1 if the No button has been pressed.
0 if the Cancel button has been pressed.

void exit ( ) #

The engine requests to exit the application.

void keyPress ( unsigned int key ) #

Application notifies the engine that the specified key on a keyboard is pressed.

Arguments

unsigned int key - Key ID. Possible values can be in range [0;255], which are standard ASCII code symbols, or in range [KEY_ESC;KEY_F12], which are used for control buttons. For full list of control buttons see KEY_* variables.

void keyPressUnicode ( unsigned int key ) #

Application notifies the engine that the specified key is pressed.

Arguments

unsigned int key - Unicode symbol.

void keyRelease ( unsigned int key ) #

Application notifies the engine that the specified key on a keyboard is released.

Arguments

unsigned int key - Key ID. Possible values can be in range [0;255], which are standard ASCII code symbols, or in range [KEY_ESC;KEY_F12], which are used for control buttons. For full list of control buttons see KEY_* variables.

void startFps ( ) #

Starts the FPS counter if it was stopped. All function calls are placed into a stack, so the number of calls to this function should correspond to the number of calls to the stopFps() function.

void stopFps ( ) #

Stops the FPS counter. This function should be called if application window is hidden or some heavy non-rendering tasks are processing. All function calls are placed into a stack, so the number of calls to this function should correspond to the number of calls to the startFps() function.

void setMouseCursorHide ( bool hide ) #

Sets a value indicating if the mouse cursor should be hidden. Can be used, for example, to hide mouse cursor for a certain element.

NoticeThis method hides the cursor only for one frame. So, you should call it each frame if a longer period is required.

Arguments

bool hide - true to hide the mouse cursor for a single frame, false - to show it.

bool isMouseCursorHide ( ) #

Returns a value indicating if the mouse cursor is hidden in the current frame.

Return value

true if mouse cursor is hidden in the current frame, false - to show it.

void setMouseCursorSystem ( bool system ) #

Sets a value indicating if the OS mouse pointer should be displayed.

Arguments

bool system - true to display the OS mouse pointer; otherwise, false.

bool isMouseCursorSystem ( ) #

Returns a value indicating if the OS mouse pointer is displayed.

Return value

true if the OS mouse pointer is displayed; otherwise, false.

void setMouseCursorNeedUpdate ( bool update ) #

Sets a value indicating that some changes were made to the cursor (e.g., it was shown, hidden, changed to system, etc.) and it has to be updated. Suppose the cursor was modified, for example, by the Interface plugin. After closing the plugin's window the cursor shall not return to its previous state because SDL doesn't even know about the changes. You can use this flag to signalize, that mouse cursor must be updated.

Arguments

bool update - true to signalize that the mouse cursor has to be updated; otherwise, false.

bool isMouseCursorNeedUpdate ( ) #

Returns a value indicating that changes were made to the cursor (e.g., it was shown, hidden, changed to system, etc.) and it has to be updated. Suppose the cursor was modified, for example, by the Interface plugin. After closing the plugin's window the cursor shall not return to its previous state because SDL doesn't even know about the changes. You can use this flag to signalize, that mouse cursor must be updated.

Return value

true if the mouse cursor has to be updated; otherwise, false.

void setMouseCursorSkinCustom ( const Ptr<Image> & image ) #

Sets a custom image to be used for the mouse cursor.

Arguments

const Ptr<Image> & image - Image containing pointer shapes to be set for the mouse cursor (e.g., select, move, resize, etc.).

void setMouseCursorSkinSystem ( ) #

Sets the current OS cursor skin (pointer shapes like select, move, resize, etc.).

void setMouseCursorSkinDefault ( ) #

Sets the default Engine cursor skin (pointer shapes like select, move, resize, etc.).

void setMouseCursorCustom ( const Ptr<Image> & image, int x = 0, int y = 0 ) #

Sets a custom image for the OS mouse cursor. The image must be of the square size and RGBA8 format.

Source code (C++)

// create an instance of the Image class
ImagePtr cursor = Image::create("textures/my_cursor.png");
// set the image as the mouse cursor
App::setMouseCursorCustom(cursor);
// show the OS mouse pointer
App::setMouseShow(1);

Arguments

const Ptr<Image> & image - Cursor image to be set.
int x - X coordinate of the cursor's hot spot.
int y - Y coordinate of the cursor's hot spot.

void clearMouseCursorCustom ( ) #

Clears the custom mouse cursor set via the setMouseCursorCustom() method.

void updateMouseCursor ( ) #

Updates the mouse cursor. This method should be called after making changes to the mouse cursor to apply them all together. After calling this method the cursor shall be updated in the next frame.

bool dialogMessage ( const char * title, const char * message ) #

Displays a message dialog with the specified title and text.

Arguments

const char * title - Title of the message dialog to be displayed.
const char * message - Message text to be displayed.

Return value

true if the message is displayed successfully; otherwise, false.

bool dialogWarning ( const char * title, const char * warning ) #

Displays a warning dialog with the specified title and text.

Arguments

const char * title - Title of the warning dialog to be displayed.
const char * warning - Warning message text to be displayed.

Return value

true if the message is displayed successfully; otherwise, false.

bool dialogError ( const char * title, const char * error ) #

Displays an error dialog with the specified title and text.

Arguments

const char * title - Title of the error dialog to be displayed.
const char * error - Error message text to be displayed.

Return value

true if the message is displayed successfully; otherwise, false.

int showSystemDialog ( const Ptr<SystemDialog> & dialog ) #

Displays a custom system dialog with an arbitrary set of buttons.

Arguments

const Ptr<SystemDialog> & dialog - SystemDialog class instance representing the custom system dialog to be shown.

Return value

number of the dialog button clicked by the user; or -1 if an error has occurred.

const char * dialogOpenFolder ( const char * path ) #

Opens a common dialog enabling the user to specify a folder to open. When the dialog opens the specified default path shall be set displaying the corresponding elements.

Arguments

const char * path - Path to be set by default when the dialog opens.

Return value

Resulting folder name specified by the user.

const char * dialogOpenFolder ( ) #

Opens a common dialog enabling the user to specify a folder to open.

Return value

Resulting folder name specified by the user.

Vector< String > dialogOpenFiles ( const char * path, const char * filter ) #

Opens a common dialog enabling the user to specify a list of filenames to open multiple files. When the dialog opens the specified default path and file filter shall be set displaying the corresponding elements.

Arguments

const char * path - Path to be set by default when the dialog opens.
const char * filter - File name filter string to be set by default when the dialog opens. This filter string determines file type choices to be displayed in the Files of type box.

Return value

Resulting list of filenames specified by the user.

Vector< String > dialogOpenFiles ( const char * path ) #

Opens a common dialog enabling the user to specify a list of filenames to open multiple files. When the dialog opens the specified default path shall be set displaying the corresponding elements.

Arguments

const char * path - Path to be set by default when the dialog opens.

Return value

Resulting list of filenames specified by the user.

Vector< String > dialogOpenFiles ( ) #

Opens a common dialog enabling the user to specify a list of filenames to open multiple files.

Return value

Resulting list of filenames specified by the user.

const char * dialogOpenFile ( const char * path, const char * filter ) #

Opens a common dialog enabling the user to specify a filename to open a file. When the dialog opens the specified default path and file filter shall be set displaying the corresponding elements.