Skip to content

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:

Methods

activate_progress_timer

Activate progress updates on a progress bar control.

bool audio_form::activate_progress_timer(int control_index);

Arguments:
Returns:

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

add_list_item

Add a string item to a list control.

  1. bool audio_form::add_list_item(int control_index, string option, int position = -1, bool selected = false, bool focus_if_first = true);
  2. 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):
Arguments (2):
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:
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:
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:
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:
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:
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:
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:
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:
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:
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.

  1. void audio_form::create_window();

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

Arguments (2):
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:
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:
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:
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:
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:
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:
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:
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:
Returns:

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

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:
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:
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_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:
Returns:

int: the number of items in the list.

get_list_position

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

int audio_form::get_list_position(int control_index);

Arguments:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
Returns:

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

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:
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:
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:
Returns:

bool: true if the echo 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:
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:
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:
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:
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.

control_event_type

Lists all possible event types that can be raised.

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.

text_edit_mode_constants

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

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.

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;