This page has been translated automatically.
UnigineScript
The Language
Core Library
Engine Library
Node-Related Classes
GUI-Related Classes
Plugins Library
High-Level Systems
Samples
Usage Examples
C++ API
API Reference
Integration Samples
Usage Examples
C++ Plugins
Migration
Migrating to UNIGINE 2.0
C++ API Migration
Migrating from UNIGINE 2.0 to UNIGINE 2.1
Warning! This version of documentation is OUTDATED, as it describes an older SDK version! Please switch to the documentation for the latest SDK version.
Warning! This version of documentation describes an old SDK version which is no longer supported! Please upgrade to the latest SDK version.

engine.app Functions

This set of functions controls the appearance of the Unigine application window, its update parameters and handles window input from the keyboard and mouse.

See Also

int APP_AXIS_X

Description

A mouse wheel is scrolled horizontally (along the X axis; a horizontal mouse wheel is required).

int APP_AXIS_Y

Description

A mouse wheel is scrolled vertically (along the Y axis; a vertical mouse wheel is used).

int APP_BUTTON_AUX_0

Description

Detected activity belongs to the first auxiliary mouse button.

int APP_BUTTON_AUX_1

Description

Detected activity belongs to the second auxiliary mouse button.

int APP_BUTTON_AUX_2

Description

Detected activity belongs to the third auxiliary mouse button.

int APP_BUTTON_AUX_3

Description

Detected activity belongs to the fourth auxiliary mouse button.

int APP_BUTTON_DCLICK

Description

A mouse button is double-clicked.

int APP_BUTTON_LEFT

Description

Detected activity belongs to the left mouse button.

int APP_BUTTON_MIDDLE

Description

Detected activity belongs to the middle mouse button (scrolling wheel).

int APP_BUTTON_RIGHT

Description

Detected activity belongs to the right mouse button.

int APP_KEY_ALT

Description

The ALT key is pressed.

int APP_KEY_BACKSPACE

Description

The BACKSPACE key is pressed.

int APP_KEY_CAPS

Description

The CAPS LOCK key is pressed.

int APP_KEY_CMD

Description

The Command key on Mac OS X is pressed.

int APP_KEY_CTRL

Description

The CTRL key is pressed.

int APP_KEY_DELETE

Description

The DELETE key is pressed.

int APP_KEY_DOWN

Description

The DOWN ARROW key is pressed.

int APP_KEY_END

Description

The END key is pressed.

int APP_KEY_ESC

Description

The ESC key is pressed.

int APP_KEY_F1

Description

The F1 key is pressed.

int APP_KEY_F10

Description

The F10 key is pressed.

int APP_KEY_F11

Description

The F11 key is pressed.

int APP_KEY_F12

Description

The F12 key is pressed.

int APP_KEY_F2

Description

The F2 key is pressed.

int APP_KEY_F3

Description

The F3 key is pressed.

int APP_KEY_F4

Description

The F4 key is pressed.

int APP_KEY_F5

Description

The F5 key is pressed.

int APP_KEY_F6

Description

The F6 key is pressed.

int APP_KEY_F7

Description

The F7 key is pressed.

int APP_KEY_F8

Description

The F8 key is pressed.

int APP_KEY_F9

Description

The F9 key is pressed.

int APP_KEY_HOME

Description

The HOME key is pressed.

int APP_KEY_INSERT

Description

The INSERT key is pressed.

int APP_KEY_LEFT

Description

The LEFT ARROW key is pressed.

int APP_KEY_NUM

Description

The NUM LOCK key is pressed.

int APP_KEY_PGDOWN

Description

The PAGE DOWN key is pressed.

int APP_KEY_PGUP

Description

The PAGE UP key is pressed.

int APP_KEY_RETURN

Description

The ENTER / RETURN key is pressed.

int APP_KEY_RIGHT

Description

The RIGHT ARROW key is pressed.

int APP_KEY_SCROLL

Description

The SCROLL LOCK key is pressed.

int APP_KEY_SHIFT

Description

The SHIFT key is pressed.

int APP_KEY_TAB

Description

The TAB key is pressed.

int APP_KEY_UP

Description

The UP ARROW key is pressed.

int APP_NUM_AXES

Description

Number of axes, along which a mouse wheel can be scrolled.

int APP_NUM_KEYS

Description

Detected number of keyboard keys.

int engine.app.clearKeyState (int key)

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

Arguments

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

Return value

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

int engine.app.clearMouseAxis (int axis)

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

Arguments

Return value

Mouse axis delta regarding the last mouse axis position, integer value.

int engine.app.clearMouseButtonState (int button)

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

Arguments

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.

Variable engine.app.dialogFile (string title, string name, string filter = 0, string 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

  • string title - Title of the dialog window.
  • string name - Full path to file, whose directory will be opened as the initial one.
  • string filter - Filter string, which sets the acceptable file extensions. The argument accepts dot-separated file extensions, for example: .tga.jpg.png.tif.psd.
    Notice
    If you send 0, the All Files (*.*) filter will be used.
  • string flags - Dialog file flags. The argument accepts one of the following strings:
    • o - the Open file dialog window will be created.
    • s - the Save file dialog window will be crated.
    Notice
    By default, the Open file dialog window is created.

Return value

Full path to the selected file if the Open (or Save) button of the dialog window is pressed; otherwise, 0.

Examples

Source code (UnigineScript)
// create a system file dialog
log.message("dialog result = %s\n",typeinfo(engine.app.dialogFile("test title",engine.getDataPath()+"test/icon.png")));
If you choose, for example, the D:\test.cpp file and press Open, the function will return the following:
Output
dialog res = string: "D:\test.cpp"

int engine.app.dialogMessage (string title, string str, string 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

  • string title - Title of the dialog window.
  • string str - Content of the dialog window.
  • string 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.

string engine.app.getClipboard ()

Retrieves the contents of the system clipboard.

Return value

Contents of the system clipboard.

float engine.app.getFTime ()

Returns time spent between a previous update and a current one.

Return value

Frame duration.

float engine.app.getFps ()

Returns a value of the application FPS counter.

Return value

FPS counter value.

int engine.app.getHeight ()

Returns the current video height.

Return value

Current video height.

float engine.app.getIFps ()

Returns an inverse value of the application FPS counter.

Return value

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

string engine.app.getKeyName (int key)

Returns a name of a given key.

Arguments

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

Return value

Key name.

int engine.app.getKeyState (int key)

Returns a key state.

Arguments

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

Return value

1 if the key is pressed; otherwise, 0.

int engine.app.getMouseAxis (int axis)

Returns the current mouse position delta along the specified axis.

Arguments

Return value

Mouse axis delta regarding the last mouse axis position, integer value.

int engine.app.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:
  1. APP_BUTTON_LEFT = 1 << 0
  2. APP_BUTTON_MIDDLE
  3. APP_BUTTON_RIGHT
  4. APP_BUTTON_DCLICK
  5. APP_BUTTON_AUX_0
  6. APP_BUTTON_AUX_1
  7. APP_BUTTON_AUX_2
  8. APP_BUTTON_AUX_3

Return value

Current states of all mouse buttons.

string engine.app.getMouseButtonName (int button)

Returns a name of a given button.

Arguments

Return value

Button name.

int engine.app.getMouseButtonState (int button)

Returns a button state.

Arguments

Return value

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

int engine.app.getMouseGrab ()

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

Return value

1 if the mouse pointer cannot leave the application window; otherwise, 0.

int engine.app.getMouseShow ()

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

Return value

1 if the OS mouse pointer is displayed; otherwise, 0.

int engine.app.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 engine.app.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.

int engine.app.getNumTouches ()

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

Return value

Number of touches.

int engine.app.getPositionX ()

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

Return value

X coordinate of the upper-left corner.

int engine.app.getPositionY ()

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

Return value

Y coordinate of the upper-left corner.

int engine.app.getTouchX (int touch)

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

Arguments

  • int touch - Number of the touch.

Return value

X coordinate of the touch.

int engine.app.getTouchY (int touch)

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

Arguments

  • int touch - Number of the touch.

Return value

Y coordinate of the touch.

int engine.app.getUpdate ()

Returns a value indicating whether the application is updating when the window is hidden.

Return value

1 if it keeps updating; otherwise, 0.

int engine.app.getWidth ()

Returns the current video width.

Return value

Current video width.

void engine.app.setClipboard (string contents)

Updates the contents of the system clipboard.

Arguments

  • string contents - Contents to set.

void engine.app.setFilter (float filter)

Filters the FPS counter value. By the value of 0, filtering is disabled and the current FPS value is always shown. The default is 0.9 (10 percent of the current FPS is taken into account).

Arguments

  • float filter - Filter in range [0;1).

int engine.app.setIcon (Image icon)

Set icon for the application.

Arguments

  • Image icon - Icon image.

Return value

Positive integer on success, otherwise, 0.

void engine.app.setKeyState (int key, int state)

Simulates pressing or unpressing of the specified keys.

Arguments

  • int key - Keys to change state (any of APP_KEY_* variables).
  • int state - 1 to press the key; 0 otherwise.

void engine.app.setMouseAxis (int axis, int value)

Sets the mouse position delta along the specified axis.

Arguments

  • int axis - Mouse axis. Possible values are APP_AXIS_X, APP_AXIS_Y.
  • int value - Mouse axis delta, integer value.

void engine.app.setMouseButton (int button)

Simulates pressing of the specified mouse buttons.

Arguments

  • int button - Mouse buttons to be pressed (any of APP_BUTTON_* variables).

int engine.app.setMouseCursor (Image image, int x = 0, int y = 0)

Sets a custom image to be used for an application cursor. The image should be of:
  • Square size
  • RGBA8 format

Arguments

  • Image image - Image of the cursor to be used.
  • int x - Horizontal position of the cursor's hot spot.
  • int y - Vertical position of the cursor's hot spot.

Return value

1 if the cursor image is successfully set; otherwise, 0.

void engine.app.setMouseGrab (int mode)

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

Arguments

  • int mode - Positive integer if the mouse pointer cannot leave the application window; otherwise, 0.

void engine.app.setMouseShow (int mode)

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

Arguments

  • int mode - Positive integer if the OS mouse pointer should be displayed; otherwise, 0.

void engine.app.setMouse (int x, int y)

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

Arguments

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

int engine.app.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 engine.app.setTitle (string title)

Sets a title for the application window.

Arguments

  • string title - Title to set.

Return value

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

int engine.app.setUpdate (int mode)

This function controls whether the application will be updating when the window is hidden.

Arguments

  • int mode - Positive integer if the the application should update if the window is hidden; otherwise, 0.

Return value

Positive integer on success, otherwise, 0.

void engine.app.startFps ()

Starts the FPS counter if it was stopped.
Notice
Number of calls to this function should correspond to the number of calls to the engine.app.stopFps() function.

void engine.app.stopFps ()

Stops the FPS counter.
Notice
Number of calls to this function should correspond to the number of calls to the engine.app.startFps() function.
Last update: 2017-07-03
Build: ()