Auditory User Interface (form.nvgt)

Classes

audio_form

This class facilitates the easy creation of user interfaces that convey their usage entirely through audio.

Notes:

many of the methods in this class only work on certain types of controls, and will return false and set an error value if used on invalid types of controls. This will generally be indicated in the documentation for each function.
Exceptions are not used here. Instead, we indicate errors through audio_form::get_last_error().

Methods

activate_progress_timer

Activate progress updates on a progress bar control.

bool audio_form::activate_progress_timer(int control_index);

Arguments:

int control_index: the index of the progress bar.

Returns:

bool: true if the progress bar was successfully activated, false otherwise.

add_list_item

Add a string item to a list control.

bool audio_form::add_list_item(int control_index, string option, int position = -1, bool selected = false, bool focus_if_first = true);
bool audio_form::add_list_item(int control_index, string option, string id, int position = -1, bool selected = false, bool focus_if_first = true);

Arguments (1):

int control_index: the control index of the list to add to.
string option: the item to add to the list.
int position = -1: the position to insert the new item at (-1 = end of list).
bool selected = false: should this item be selected by default?
bool focus_if_first = true: if this item is the first in the list and no other item gets explicitly focused, this item will be focused.

Arguments (2):

int control_index: the control index of the list to add to.
string option: the item to add to the list.
string id: the ID of the item in the list.
int position = -1: the position to insert the new item at (-1 = end of list).
bool selected = false: should this item be selected by default?
bool focus_if_first = true: if this item is the first in the list and no other item gets explicitly focused, this item will be focused.

Returns:

bool: true if the item was successfully added, false otherwise.

Remarks:

This function only works on list controls.

clear_list

Clear a list control of all its items.

bool audio_form::clear_list(int control_index);

Arguments:

int control_index: the index of the list to clear.

Returns:

bool: true if the list was successfully cleared, false otherwise.

create_button

Creates a new button and adds it to the audio form.

int audio_form::create_button(string caption, bool primary = false, bool cancel = false, bool overwrite = true);

Arguments:

string caption: the label to associate with the button.
bool primary = false: should this button be activated by pressing enter anywhere in the form?
bool cancel = false: should this button be activated by pressing escape anywhere in the form?
bool overwrite = true: overwrite any existing primary/cancel settings.

Returns:

int: the control index of the new button, or -1 if there was an error. To get error information, look at audio_form::get_last_error();.

create_checkbox

Creates a new checkbox and adds it to the audio form.

int audio_form::create_checkbox(string caption, bool initial_value = false, bool read_only = false);

Arguments:

string caption: the text to be read when tabbing over this checkbox. *( bool initial_value = false: the initial value of the checkbox (true = checked, false = unchecked).
bool read_only = false: can the user check/uncheck this checkbox?

Returns:

int: the control index of the new checkbox, or -1 if there was an error. To get error information, see audio_form::get_last_error();.

create_input_box

Creates an input box control on the audio form.

int audio_form::create_input_box(string caption, string default_text = "", string password_mask = "", int maximum_length = 0, bool read_only = false, bool multiline = false, bool multiline_enter = true);

Arguments:

string caption: the label of the input box (e.g. what will be read when you tab over it?).
string default_text = "": the text to populate the input box with by default (if any). *( string password_mask = "": a string to mask typed characters with, (e.g. "star"). Mainly useful if you want your field to be password protected. Leave blank for no password protection.
int maximum_length = 0: the maximum number of characters that can be typed in this field, 0 for unlimited.
bool read_only = false: should this text field be read-only?
bool multiline = false: should this text field have multiple lines?
bool multiline_enter = true: should pressing enter in this field insert a new line (if it's multiline)?

Returns:

int: the control index of the new input box, or -1 if there was an error. To get error information, look at audio_form::get_last_error();.

create_keyboard_area

Creates a new keyboard area and adds it to the audio form.

int audio_form::create_keyboard_area(string caption);

Arguments:

string caption: the text to be read when tabbing onto the keyboard area.

Returns:

int: the control index of the new keyboard area, or -1 if there was an error. To get error information, see audio_form::get_last_error();.

create_list

Creates a new list control and adds it to the audio form.

int audio_form::create_list(string caption, int maximum_items = 0, bool multiselect = false, bool repeat_boundary_items = false);

Arguments:

string caption: the label to attach to this list.
int maximum_items = 0: the maximum number of allowed items, 0 for unlimited.
bool multiselect = false: can the user select multiple items in this list?
bool repeat_boundary_items = false: do items repeat if you press the arrow keys at the edge of the list?

Returns:

int: the control index of the new list, or -1 if there was an error. To get error information, look at audio_form::get_last_error();.

create_progress_bar

Creates a new progress bar control and adds it to the audio form.

int audio_form::create_progress_bar(string caption, int speak_interval = 5, bool speak_global = true);

Arguments:

string caption: the label to associate with the progress bar.
int speak_interval = 5: how often to speak percentage changes.
bool speak_global = true: should progress updates be spoken even when this control doesn't have keyboard focus?

Returns:

int: the control index of the new progress bar, or -1 if there was an error. To get error information, look at audio_form::get_last_error();.

create_slider

Creates a new slider control and adds it to the audio form.

int audio_form::create_slider(string caption, int default_value = 50, int minimum_value = 0, int maximum_value = 100, string text = "");

Arguments:

string caption: the text to be spoken when this slider is tabbed over.
int default_value = 50: the default value to set the slider to.
int minimum_value = 0: the minimum value of the slider.
int maximum_value = 100: the maximum value of the slider.
string text = "": extra text to be associated with the slider.

Returns:

int: the control index of the new slider, or -1 if there was an error. To get error information, see audio_form::get_last_error();.

create_status_bar

Creates a new status bar and adds it to the audio form.

int audio_form::create_status_bar(string caption, string text);

Arguments:

string caption: the label of the status bar.
string text: the text to display on the status bar.

Returns:

int: the control index of the new status bar, or -1 if there was an error. To get error information, see audio_form::get_last_error();.

create_window

Creates a window to show audio form controls.

void audio_form::create_window();
void audio_form::create_window(string window_title, bool change_screen_title = true, bool say_dialog = true, bool silent = false);

Arguments (2):

string window_title: the title of the window.
bool change_screen_title = true: whether or not the main window's title should be set as well.
bool say_dialog = true: whether or not the window should be reported as a dialog (in the context of the audio form).
bool silent = false: should this window be shown silently?

Example:

#include "form.nvgt"
#include "speech.nvgt"
void main() {
	audio_form f;
	f.create_window("Test");
	wait(50); // Give screen readers time to speak the window title.
	int f_exit = f.create_button("exit");
	f.focus(f_exit);
	while (true) {
		wait(5);
		f.monitor();
		if (f.is_pressed(f_exit))
			exit();
	}
}

delete_control

Removes a control with a particular index from the audio form.

bool audio_form::delete_control(int control_index);

Arguments:

int control_index: the index of the control to delete.

Returns:

bool: true if the control was successfully deleted, false otherwise.

delete_list_item

Remove an item from a list control.

bool audio_form::delete_list_item(int control_index, int list_index, bool reset_cursor = true, bool speak_deletion_status = true);

Arguments:

int control_index: the index of the list to remove the item from.
int list_index: the index of the item to remove.
bool reset_cursor = true: should the user's cursor position be reset to the top of the list upon success?
bool speak_deletion_status = true: should the user be informed of the deletion via speech feedback?

Returns:

bool: true if the item was successfully deleted, false otherwise.

delete_list_selections

Unselect any currently selected items in a list control.

bool audio_form::delete_list_selections(int control_index, bool reset_cursor = true, bool speak_deletion_status = true);

Arguments:

int control_index: the index of the list to unselect items in.
bool reset_cursor = true: should the user's cursor position be reset to the top of the list upon success?
bool speak_deletion_status = true: should the user be informed of the unselection via speech feedback?

Returns:

bool: true if the selection was successfully cleared, false otherwise.

edit_list_item

Edits the value of a list item.

bool audio_form::edit_list_item(int control_index, string new_option, int position);

Arguments:

int control_index: the index of the list containing the item.
string new_option: the new text of the item.
int position: the item's index in the list.

Returns:

bool: true if the item's value was successfully updated, false otherwise.

edit_list_item_id

Modifies the ID of a list item.

bool audio_form::edit_list_item_id(int control_index, string new_id, int position);

Arguments:

int control_index: the index of the list containing the item.
string new_id: the new ID of the list item.
int position: the item's index in the list.

Returns:

bool: true if the item's ID was successfully updated, false otherwise.

focus

Set a particular control to have the keyboard focus, and notify the user.

bool audio_form::focus(int control_index);

Arguments:

int control_index: the index of the control to focus.

Returns:

bool: true if the control was successfully focused, false otherwise.

focus_interrupt

Set a particular control to have the keyboard focus, and notify the user (cutting off any previous speech).

bool audio_form::focus_interrupt(int control_index);

Arguments:

int control_index: the index of the control to focus.

Returns:

bool: true if the control was successfully focused, false otherwise.

focus_silently

Set a particular control to have the keyboard focus, without notifying the user.

bool audio_form::focus_silently(int control_index);

Arguments:

int control_index: the index of the control to focus.

Returns:

bool: true if the control was successfully focused, false otherwise.

get_cancel_button

Get the control index of the cancel button (e.g. the button activated when pressing escape anywhere on an audio form).

int audio_form::get_cancel_button();

Returns:

int: the control index of the cancel button.

get_caption

Get the caption of a control.

string audio_form::get_caption(int control_index);

Arguments:

int control_index: the index of the control to query.

Returns:

string: the caption of the control.

get_checked_list_items

Get a list of all currently checked items in a list control.

int[]@ audio_form::get_checked_list_items(int control_index);

Arguments:

int control_index: the index of the list to query.

Returns:

int[]@: handle to an array containing the index of every checked item in the list.

Remarks:

This function only works on multiselect lists. If you want something that also works on single-select lists, see get_list_selections().

get_control_count

Returns the number of controls currently present on the form.

int audio_form::get_control_count();

Returns:

int: the number of controls currently on the form.

get_control_type

Returns the type of a control.

int audio_form::get_control_type(int control_index);

Arguments:

int control_index: the index of the control to get the type of.

Returns:

int: the type of the control (see control_types for more information).

get_current_focus

Get the control index of the control with the keyboard focus.

int audio_form::get_current_focus();

Returns:

int: the control index that currently has the keyboard focus.

get_default_button

Get the control index of the default button (e.g. the button activated when pressing enter anywhere on an audio form).

int audio_form::get_default_button();

Returns:

int: the control index of the default button.

get_last_error

Get the last error that was raised from this form.

int audio_form::get_last_error();

Returns:

int: the last error code raised by this audio_form ( see audioform_errorcodes for more information).

Remarks:

As noted in the introduction to this class, exceptions are not used here. Instead, we indicate errors through this function.

get_list_count

Get the number of items contained in a list control.

int audio_form::get_list_count(int control_index);

Arguments:

int control_index: index of the list control to query.

Returns:

int: the number of items in the list.

get_list_index_by_id

Get the index of a list item by its ID.

int audio_form::get_list_index_by_id(int control_index, string id);

Arguments:

int control_index: the index of the list.
string id: the ID of the item to query.

Returns:

int: the index of the item, -1 on error.

get_list_item

Get the text of a particular list item.

string audio_form::get_list_item(int control_index, int list_index);

Arguments:

int control_index: the index of the list.
int list_index: the index of the item to get.

Returns:

string: the text of the item.

get_list_item_id

Get the ID of a particular list item.

string audio_form::get_list_item_id(int control_index, int list_index);

Arguments:

int control_index: the index of the list.
int list_index: the index of the item to get.

Returns:

string: the ID of the item.

get_list_position

Get the user's currently focused item in a list control.

int audio_form::get_list_position(int control_index);

Arguments:

int control_index: the index of the list.

Returns:

int: the user's current cursor position in the list.

get_list_selections

Get a list of all items currently selected in a list control.

int[]@ audio_form::get_list_selections(int control_index);

Arguments:

int control_index: the index of the list to query.

Returns:

int[]@: handle to an array containing the index of every selected item in the list (see remarks).

Remarks:

In the context of this function, a selected item is any item that is checked (if the list supports multiselection), as well as the currently selected item. If you want to only get the state of checked list items, see the get_checked_list_items() function.

get_progress

Get the value of a progress bar.

int audio_form::get_progress(int control_index);

Arguments:

int control_index: the index of the progress bar to query.

Returns:

int: the current value of the progress bar.

Remarks:

This method only works on progress bar controls.

is_checked

Get the state of a checkbox.

bool audio_form::is_checked(int control_index);

Arguments:

int control_index: the index of the control to query.

Returns:

bool: true if the checkbox is checked, false otherwise.

Remarks:

This function only works on checkbox controls.

is_enabled

Determine if a particular control is enabled or not.

bool audio_form::is_enabled(int control_index);

Arguments:

int control_index: the index of the control to query.

Returns:

bool: true if the control is enabled, false if it's disabled.

is_list_item_checked

Determine if the list item at a particular index is checked or not.

bool audio_form::is_list_item_checked(int control_index, int item_index);

Arguments:

int control_index: the index of the list containing the item to be checked.
int item_index: the index of the item to check.

Returns:

bool: true if the item exists and is checked, false otherwise.

is_multiline

Determine if a particular control is multiline or not.

bool audio_form::is_multiline(int control_index);

Arguments:

int control_index: the index of the control to query.

Returns:

bool: true if the control is multiline, false otherwise.

Remarks:

This function only works on input boxes.

is_pressed

Determine if a particular button was just pressed.

bool audio_form::is_pressed(int control_index);

Arguments:

int control_index: the index of the control to query.

Returns:

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

Remarks:

This function only works on button controls.

is_read_only

Determine if a particular control is read-only or not.

bool audio_form::is_read_only(int control_index);

Arguments:

int control_index: the index of the control to query.

Returns:

bool: true if the control is read-only, false if it's not.

Remarks:

This function only works on input boxes and checkboxes.

is_visible

Determine if a particular control is visible or not.

bool audio_form::is_visible(int control_index);

Arguments:

int control_index: the index of the control to query.

Returns:

bool: true if the control is visible, false if it's invisible.

monitor

Processes all keyboard input, and dispatches all events to the form. Should be called in your main loop.

int audio_form::monitor();

Returns:

int: this value can be ignored for users of this class; it's used internally for subforms.

pause_progress_timer

Pause updating of a progress bar control.

bool audio_form::pause_progress_timer(int control_index);

Arguments:

int control_index: the index of the progress bar.

Returns:

bool: true if the progress bar was paused, false otherwise.

set_button_attributes

Set the primary and cancel flags of a button.

`bool audio_form::set_button_attributes(int control_index, bool primary, bool cancel, bool overwrite = true);

Arguments:

int control_index: the index of the button to update.
bool primary: should this button be made primary (e.g. pressing enter from anywhere on the form activates it)?
bool cancel: should this button be made the cancel button (e.g. should pressing escape from anywhere on the form always activate it?).
bool overwrite = true: should the previous primary and cancel buttons (if any) be overwritten?

Returns:

bool: true if the attributes were successfully set, false otherwise.

set_caption

Sets the caption of a control.

bool audio_form::set_caption(int control_index, string caption);

Arguments:

int control_index: the index of the control.
string caption: the caption to set on the control (see remarks for more infromation).

Returns:

bool: true if the caption was successfully set, false otherwise.

Remarks:

The caption is read every time a user focuses this particular control.

It is possible to associate hotkeys with controls by putting an "&" symbol in the caption. For example, setting the caption of a button to "E&xit" would assign the hotkey alt+x to focus it.

set_checkbox_mark

Set the state of a checkbox (either checked or unchecked).

bool audio_form::set_checkbox_mark(int control_index, bool checked);

Arguments:

int control_index: the control index of the checkbox.
bool checked: whether the checkbox should be set to checked or not.

Returns:

bool: true if the operation was successful, false otherwise. To get error information, look at audio_form::get_last_error();.

set_default_controls

Sets default and cancel buttons for this form.

bool set_default_controls(int primary, int cancel);

Arguments:

int primary: the control index of the button to make primary.
int cancel: the control index of the cancel button.

Returns:

bool: true if the controls were successfully set, false otherwise.

set_default_keyboard_echo

Sets the default keyboard echo of controls on your form.

bool audio_form::set_default_keyboard_echo(int keyboard_echo, bool update_controls = true);

Arguments:

int keyboard_echo: the keyboard echo mode to use (see text_entry_speech_flags for more information).
bool update_controls = true: whether or not this echo should be applied to any controls that already exist on your form.

Returns:

bool: true if the echo was successfully set, false otherwise.

set_disallowed_chars

Sets the whitelist/blacklist characters of a control.

bool audio_form::set_disallowed_chars(int control_index, string chars, bool use_only_disallowed_chars = false, string char_disallowed_description = "");

Arguments:

int control_index: the index of the control.
string chars: the characters to set.
bool use_only_disallowed_chars = false: sets whether the control should only use the characters in this list. true means use only characters that are in the list, and false means allow only characters that are not in the list.
string char_disallowed_description = "": the text to speak when an invalid character is inputted.

Returns:

bool: true if the characters were successfully set, false otherwise.

Remarks:

Setting the use_only_disallowed_chars parameter to true will restrict all characters that are not in the list. This is useful to prevent other characters in number inputs.

Setting the chars parameter to blank will clear the characters and will switch back to default.

set_enable_go_to_index

Toggles whether the control can use go to line functionality.

bool audio_form::set_enable_go_to_index(int control_index, bool enabled);

Arguments:

int control_index: the index of the control.
bool enabled: enables the go to line functionality.

Returns:

bool: true if the state was successfully set, false otherwise.

set_keyboard_echo

Set the keyboard echo for a particular control.

bool audio_form::set_keyboard_echo(int control_index, int keyboard_echo);

Arguments:

int control_index: the index of the control to modify.
int keyboard_echo: the keyboard echo mode to use (see text_entry_speech_flags for more information).

Returns:

bool: true if the keyboard echo was successfully set, false otherwise.

set_list_multinavigation

Configures how the multi-letter navigation works in a list control.

bool audio_form::set_list_multinavigation(int control_index, bool letters, bool numbers, bool nav_translate = true);

Arguments:

int control_index: the index of the list control.
bool letters: can the user navigate with letters?
bool numbers: can the user navigate with the numbers.
bool nav_translate = true: should the letters work with the translated alphabet in use?

Returns:

bool: true if the settings were successfully set, false otherwise.

set_list_position

Set the user's cursor in a list control.

bool audio_form::set_list_position(int control_index, int position = -1, bool speak_new_item = false);

Arguments:

int control_index: the index of the list.
int position = -1: the new cursor position (-1 for no selection).
bool speak_new_item = false: should the user be notified of the selection change via speech?

Returns:

bool: true if the cursor position was successfully set, false otherwise.

set_state

Set the enabled/visible state of a control.

bool audio_form::set_state(int control_index, bool enabled, bool visible);

Arguments:

int control_index: the index of the control.
bool enabled: is the control enabled (e.g. if it's a button, being disabled would make the button unpressable).
bool visible: can the user access the control with the navigation commands?

Returns:

bool: true if the state was successfully set, false otherwise.

Properties

active

Determine if the form is currently active.

bool audio_form::active;

Enums

audioform_errorcodes

This enum contains any error values that can be returned by the audio_form::get_last_error(); function.

form_error_none: No error.
form_error_invalid_index: you provided a control index that doesn't exist.
form_error_invalid_control: you are attempting to do something on an invalid control.
form_error_invalid_value: You provided an invalid value.
form_error_invalid_operation: you tried to perform an invalid operation.
form_error_no_window: you haven't created an audio_form window yet.
form_error_window_full: the window is at its maximum number of controls
form_error_text_too_long: the text provided is too long.
form_error_list_empty: indicates that a list control is empty.
form_error_list_full: indicates that a list control is full.
form_error_invalid_list_index: the list has no item at that index.
form_error_control_invisible: the specified control is invisible.
form_error_no_controls_visible: no controls are currently visible.

control_event_type

Lists all possible event types that can be raised.

event_none: no event.
event_focus: a control gained keyboard focus.
event_list_cursor: the cursor changed in a list control.
event_text_cursor: the cursor changed in an input box.
event_button: a button was pressed.
event_checkbox: a checkbox's state has changed.
event_slider: a slider's value has been changed.

control_types

This is a complete list of all control types available in the audio form, as well as a brief description of what they do.

ct_button: a normal, pressable button.
ct_input: any form of text box.
ct_checkbox: a checkable/uncheckable control.
ct_progress: a progress bar that can both beep and speak.
ct_status_bar: a small informational area for your users to get information quickly.
ct_list: a list of items.
ct_slider: a slider, adjustable to a given percent with the arrow keys.
ct_form: a child form.
ct_keyboard_area: an area that captures all keys from the user (minus a few critical ones like tab and shift+tab) and lets you handle them, useful for embedding your game controls within your UI.

text_edit_mode_constants

This is a list of constants that specify text editing modes, used mainly with audio_form::edit_text();.

edit_mode_replace: replace text.
edit_mode_trim_to_length: trim the final text to a given length.
edit_mode_append_to_end: append text to the end.

See the audio_form::edit_text(); documentation for more information.

text_entry_speech_flags

This enum provides constants to be used with the character echo functionality in input boxes.

textflag_none: no echo.
textflag_characters: echo characters only.
textflag_words: echo words only.
textflag_characters_words: echo both characters and words.

Global Properties

audioform_input_disable_ralt

Set whether or not the right alt key should be disabled in input boxes, mostly useful for users with non-english keyboards.

bool audioform_input_disable_ralt;

audioform_word_separators

A list of characters that should be considered word boundaries for navigation in an input box.

string audioform_word_separators;