Skip to content

User Interface

This section contains all functions that involve directly interacting with the user, be that by showing a window, checking the state of a key, or placing data onto the users clipboard. These handle generic input such as from the keyboard, and also generic output such as an alert box.

Window management notes:

Enums

joystick_control_type

Represents the various types of controls that can appear on a joystick. Note that some of these only work/appear on certain controllers.

joystick_power_level

Represents various charging states of a joystick.

joystick_type

This enum represents the types of joysticks NVGT knows about. DO note that if you have a joystick that's not in this list, it will most likely still work, but you just won't be able to identify it by type.

key_code

This is a complete list of possible keycodes in NVGT, as well as a short description of what they are. These are registered in the key_code enum, meaning you can use this type to pass any value listed here around though it is also safe to use unsigned integers.

Letter keys

Number keys

Special keys

Function keys

Arrow keys

Numpad keys

Modifier keys

Miscellaneous keys

Media keys

Browser and Application keys

Additional keys

key_modifier

This is a complete list of supported key modifiers and their descriptions. These are registered in the key_modifier enum, so you can use that type to pass any value listed here around.

Example:

void main() {
	show_window("Example");
	wait(50); // Give the screen readers enough time to speak the window title before speaking.
	screen_reader_output("Press alt+f4 to close this window.", true);
	while (true) {
		wait(5);
		if (keyboard_modifiers & KEYMOD_ALT > 0 && key_pressed(KEY_F4))
			exit();
	}
}

message_box_flags

This is an enumeration of possible flags to be passed to the message_box(), alert(), question(), and similar functions.

Functions

alert

Display a message box with an OK button to the user.

int alert(string title, string text, bool can_cancel = false, uint flags = 0);

Arguments:

Returns:

int: the number of the button that was pressed, either OK or cancel.

Example:

void main() {
	alert("Hello", "I am a standard alert");
	alert("Hi", "And I'm a cancelable one", true);
}

clipboard_get_text

Returns the text currently on the user's clipboard.

string clipboard_get_text();

Returns:

The text on the user's clipboard, as UTF_8.

Example:

void main() {
	string text = clipboard_get_text();
	if (text == "")
		alert("Info", "Your clipboard is empty");
	else
		if (text.length() > 1024)
			alert("Info", "Your clipboard contains a long string. It is " + text.length() + " characters");
		else
			alert("Info", "Your clipboard contains " + text);
}

clipboard_set_raw_text

Sets the text on the user's clipboard, using the system encoding.

bool clipboard_set_raw_text(string text);

Arguments:

Returns:

Bool: true on success, false on failure.

Remarks:

To copy UTF-8 text, see clipboard_set_text().

Example:

void main() {
	string text = input_box("Text", "Enter the text to copy.");
	clipboard_set_raw_text(text);
	if (text == "")
		alert("Info", "Your clipboard has been cleared.");
	else
		alert("Info", "Text copied");
}

clipboard_set_text

Sets the text on the user's clipboard.

bool clipboard_set_text(string text);

Arguments:

Returns:

Bool: true on success, false on failure.

Remarks:

To copy text in the system encoding, see clipboard_set_raw_text().

Example:

void main() {
	string text = input_box("Text", "Enter the text to copy.");
	clipboard_set_text(text);
	if (text == "")
		alert("Info", "Your clipboard has been cleared.");
	else
		alert("Info", "Text copied");
}

destroy_window

Destroys the currently shown window, if it exists.

bool destroy_window();

Returns:

bool: true if the window was successfully destroyed, false otherwise.

Example:

void main() {
	alert("Info", "Pressing SPACE will destroy the window");
	show_window("Example");
	while (true) {
		wait(5); // Don't hog all the CPU time.
		if (key_pressed(KEY_SPACE)) {
			destroy_window();
			wait(2000); // Simulate doing things while the window isn't active.
			exit();
		}
	}
}

exit

Completely shut down your application, returning a particular exit code to your operating system in the process.

void exit(int exit_code = 0);

Arguments:

Example:

void main() {
	show_window("Example");
	screen_reader_output("Press escape to exit.", true);
	while (true) {
		wait(5);
		if (key_pressed(KEY_ESCAPE)) {
			screen_reader_output("Goodbye.", true);
			wait(500);
			exit();
		}
	}
}

get_characters

Determine any printable characters typed into the games window since this function's lass call.

string get_characters();

Returns:

string: Any characters typed since this function was last called, or an empty string if none are available.

Remarks:

This is the function one would use if they wished to integrate a virtual text field of any sort into their games or applications.

Unlike functions such as key_down or keys_pressed, this function focuses specifically on textual content which has been input to the application. A character returned from this function, for example, could be anything from the space bar to an emoticon inserted using the windows emoji picker.

A typical use case would involve calling this function once per iteration of your game loop and storing any new characters that are typed into a buffer that composes a chat message or a username or anything else requiring virtual text input.

Example:

void main() {
	string buffer;
	show_window("get_characters example");
	while (!key_pressed(KEY_ESCAPE)) {
		wait(5);
		string char = get_characters();
		if (!char.empty()) {
			buffer += char;
			screen_reader_speak(char, true); // You need to process this further for screen readers, such as replacing . with period and other punctuation.
		}
		if (key_pressed(KEY_RETURN)) {
			screen_reader_speak("You typed " + (!buffer.empty()? buffer : "nothing"), true);
			buffer = "";
		}
	}
}

get_window_os_handle

Returns the native handle used by the operating system to manage NVGT's window.

uint64 get_window_os_handle();

Returns:

uint64: An HWND / NSWindow* / similar handle that the operating system uses to manage the window.

Remarks:

This function is only useful for someone trying to do something advanced, usually involving passing the identifier for the game window to a system API function or something similar. If you don't understand what this function does, you should probably avoid it for the present.

Example:

void main() {
	// Lets set the window title using the windows API, typically you'd use show_window a second time for this.
	show_window("hello");
	uint64 handle = get_window_os_handle();
	library lib;
	lib.load("user32");
	lib.call("int SetWindowTextA(uint64, ptr)", handle, "example window");
	wait(500); // Let the user observe the change before exiting.
}

idle_ticks

Obtain the time passed in milliseconds since a user has pressed a key or used the mouse.

uint64 idle_ticks();

returns

uint64: the number of milliseconds since a user has last interacted with the machine.

remarks

This function can serve as a useful utility to verify whether a user has been away from the keyboard.

It is currently integrated for windows and MacOS. On linux, it will always return 0 until further notice.

Example:

void main() {
	int64 t;
	show_window("Idle test");
	wait(50);
	screen_reader_speak("Press space to check the idle time and escape to exit.", true);
	while (!key_pressed(KEY_ESCAPE)) {
		wait(5);
		if (key_pressed(KEY_SPACE))
			screen_reader_speak("You have been idle for %0 milliseconds".format(t), true);
		t = idle_ticks();
	}
}

info_box

Displays a dialog to the user consisting of a read-only text field and a close button.

bool info_box(string title, string label, string text, uint64 flags = 0);

Arguments:

Returns:

bool: true if the user pressed the close button, false otherwise.

Example:

void main() {
	info_box("Test", "Information", "this is a\r\nlong string\r\nthat can be split\r\nacross lines");
}

input_box

Displays a dialog to the user consisting of an input field, an OK button and a cancel button.

string input_box(string title, string text, string default_text = "", uint64 flags = 0);

Arguments:

Returns:

string: the text that the user typed.

Example:

void main() {
	string name = input_box("Name", "What is your name?", "John Doe");
	if (name.is_empty()) {
		alert("Error", "You didn't type a name, unidentified person!");
		exit();
	}
	alert("Hi", name + "!");
}

install_keyhook

Attempts to install NVGT's JAWS keyhook.

bool install_keyhook(bool allow_reinstall = true);

Arguments:

Returns:

bool: true if the keyhook was successfully installed, false otherwise.

Remarks:

This keyhook allows NVGT games to properly capture keyboard input while the JAWS for Windows screen reader is running.

Example:

void main() {
	bool success = install_keyhook();
	if (success) {
		alert("Info", "The keyhook was successfully installed!");
		uninstall_keyhook();
	}
	else
		alert("Info", "The keyhook was not successfully installed.");
}

is_window_active

Determines if your game's window is active (i.e. has the keyboard focus).

bool is_window_active();

Returns:

bool: true if your game window has the keyboard focus, false if not.

Example:

void main() {
	show_window("Test");
	wait(1000); // Give the user time to alt+tab away if they so choose.
	bool active = is_window_active();
	if (active)
		alert("Info", "Your game window is active.");
	else
		alert("Info", "Your game window is not active.");
}

joystick_count

Retrieves the number of joysticks currently connected to the system.

int joystick_count(bool only_active = true);

Arguments:

Returns:

int: the number of joysticks currently connected to the system.

Example:

void main() {
	int joysticks = joystick_count();
	alert("Your system currently has", joysticks + " " + (joysticks == 1 ? "joystick" : "joysticks") + " connected");
}

key_down

Determine if a particular key is held down.

bool key_down(uint key);

Arguments:

Returns:

bool: true if the key is down at all, false otherwise.

Remarks:

For a complete list of keys that can be passed to this function, see input constants.

Example:

void main() {
	show_window("Example");
	while (true) {
		wait(5);
		if (key_down(KEY_SPACE))
			screen_reader_output("space", true);
		if (key_pressed(KEY_ESCAPE))
			exit();
	}
}

key_pressed

Determine if a particular key is pressed.

bool key_pressed(uint key);

Arguments:

Returns:

bool: true if the key was just pressed, false otherwise.

Remarks:

For a complete list of keys that can be passed to this function, see input constants.

Example:

void main() {
	show_window("Example");
	while (true) {
		wait(5);
		if (key_pressed(KEY_SPACE))
			screen_reader_output("You just pressed space!", true);
		if (key_pressed(KEY_ESCAPE))
			exit();
	}
}

key_released

Determine if a particular key was just released.

bool key_released(uint key);

Arguments:

Returns:

bool: true if the key was just released, false otherwise.

Remarks:

For a complete list of keys that can be passed to this function, see input constants.

Example:

void main() {
	show_window("Example");
	while (true) {
		wait(5);
		if (key_released(KEY_SPACE))
			screen_reader_output("you just released the space key", true);
		if (key_pressed(KEY_ESCAPE))
			exit();
	}
}

key_repeating

Determine if a particular key is repeating (i.e. it's being held, but wasn't just pressed).

bool key_repeating(uint key);

Arguments:

Returns:

bool: true if the key is repeating, false otherwise.

Remarks:

For a complete list of keys that can be passed to this function, see input constants.

Example:

void main() {
	show_window("Example");
	while (true) {
		wait(5);
		if (key_repeating(KEY_SPACE))
			screen_reader_output("space", true);
		if (key_pressed(KEY_ESCAPE))
			exit();
	}
}

key_up

Determine if a particular key is up.

bool key_up(uint key);

Arguments:

Returns:

bool: true if the key is up, false otherwise.

Remarks:

For a complete list of keys that can be passed to this function, see input constants.

Example:

void main() {
	int last_spoken = ticks(); // Speak periodically to avoid overwhelming the user (or their screen reader).
	show_window("Example");
	while (true) {
		wait(5);
		if (key_up(KEY_SPACE) && (ticks() - last_spoken) >= 500) {
			last_spoken = ticks();
			screen_reader_output("space is up", true);
		}
		if (key_pressed(KEY_ESCAPE))
			exit();
	}
}

Returns a handle to an array of keys that are held down.

uint[]@ keys_down();

Returns:

uint[]@: a handle to an array containing keys that are held down.

Remarks:

For a complete list of keys that can be returned by this function, see input constants.

Returns a handle to an array of keys that were just pressed.

uint[]@ keys_pressed();

Returns:

uint[]@: a handle to an array containing keycodes that were just pressed.

Remarks:

For a complete list of keys that can be returned by this function, see input constants.

Returns a handle to an array of keys that were just released.

uint[]@ keys_released();

Returns:

uint[]@: a handle to an array containing keycodes that were just released.

Remarks:

For a complete list of keys that can be returned by this function, see input constants.

message_box

Displays a customizable message box.

int message_box(string title, string text, string[]@ buttons, uint flags = 0);

Arguments:

Returns:

int: the number of the button that was pressed, according to its position in the buttons array.

Remarks:

Notes on button syntax:

Example:

void main() {
	message_box("Hello there", "I am a message box with two buttons", {"`OK", "~Cancel"});
}

question

Display a yes/no dialog box to the user.

int question(string title, string text, bool can_cancel = false, uint flags = 0);

Arguments:

Returns:

int: the number of the button that was pressed (1 for yes, 2 for no).

Example:

void main() {
	int res = question("Hello there", "Do you like pizza?");
	alert("Info", "You clicked " + (res == 1 ? "yes" : "no"));
}

show_window

Shows a window with the specified title.

bool show_window(string title);

Arguments:

Returns:

bool: true if window creation was successful, false otherwise.

Remarks:

This window doesn't do any event processing by default. As such, you have to create a loop in order to keep it alive.

Example:

void main() {
	alert("Info", "Press escape to close the window.");
	show_window("Example");
	while (true) {
		wait(5); // Don't hog all the CPU.
		if (key_pressed(KEY_ESCAPE))
			exit();
	}
}

total_keys_down

Returns the total number of keys that are currently held down.

int total_keys_down();

Returns:

int: the number of keys currently held down.

Example:

void main() {
	int check_time = 1000, orig_ticks = ticks();
	show_window("Example");
	while (true) {
		wait(5);
		if ((ticks() - orig_ticks) >= check_time) {
			orig_ticks = ticks();
			int key_count  = total_keys_down();
			screen_reader_output(key_count + " " + (key_count == 1 ? "key is" : "keys are") + " currently held down.", true);
		}
		if (key_pressed(KEY_ESCAPE))
			exit();
	}
}

uninstall_keyhook

Uninstall's NVGT's JAWS keyhook.

void uninstall_keyhook();

Remarks:

This keyhook allows NVGT games to properly capture keyboard input while the JAWS for Windows screen reader is running.

Example:

void main() {
	install_keyhook();
	alert("Info", "Keyhook installed. Uninstalling...");
	uninstall_keyhook();
	alert("Done", "Keyhook uninstalled.");
}

urlopen

Opens the specified URL in the appropriate application, for example an https:// link in your web browser, or a tt://link in TeamTalk.

bool urlopen(string url);

Arguments:

Returns:

bool: true if the URl was successfully opened, false otherwise.

Remarks:

What application this function opens depends on what the user has set on their system; there's no way for you to control it.

Example:

void main() {
	urlopen("https://nvgt.gg");
}

wait

Waits for a specified number of milliseconds.

void wait(int milliseconds);

Arguments:

Remarks:

This function blocks the thread it's ran from, meaning no other work can happen on that thread until the wait period is over.

It is strongly advised to always put wait(5); in your main loops. This prevents your game from hogging the CPU, and also prevents weird bugs with the game window.

Example:

void main() {
	alert("Info", "Once you press OK, I will wait for 2000 milliseconds (2 seconds).");
	wait(2000);
	alert("Info", "2000 milliseconds passed!");
}