NVGT Includes Improvements

doc/src/references/include/Auditory User Interface (form.nvgt)/Classes/audio_form/Methods/create_subform.nvgt

@@ -0,0 +1,100 @@
+/**
+	Creates a new sub form and adds it to the audio form.
+	int audio_form::create_subform(string caption, audio_form@ f);
+	## Arguments:
+		* string caption: the label to associate with the sub form.
+		* audio_form@ f: an object pointing to an already created form.
+	## Returns:
+		int: the control index of the new sub form control, or -1 if there was an error. To get error information, look at `audio_form::get_last_error();`.
+*/
+
+// Example:
+#include "form.nvgt"
+
+// some imaginary global application variables.
+bool logostart = true, menuwrap = false, firespace = false, radar = true;
+
+// First, lets make a class which stores a category name and the form that the category is linked to.
+class settings_category {
+	string name;
+	audio_form@ f;
+	settings_category(string n, audio_form@ f) {
+		this.name = n;
+		@this.f = @f;
+	}
+}
+
+void settings_dialog() {
+	// Define some categories and settings on each category like this:
+	audio_form fc_general;
+	fc_general.create_window();
+	int f_logostart = fc_general.create_checkbox("Play &logo on startup", logostart);
+	int f_menuwrap = fc_general.create_checkbox("Wrap &menus", menuwrap);
+	audio_form fc_gameplay;
+	fc_gameplay.create_window();
+	int f_firespace = fc_gameplay.create_checkbox("Use space instead of control to &fire", firespace);
+	int f_radar = fc_gameplay.create_checkbox("Enable the &radar", firespace);
+	// Add as many categories as you want this way.
+	audio_form f; // The overarching main form.
+	f.create_window("Settings", false, true);
+	int f_category_list = f.create_tab_panel("&Category"); // The user will select categories from here. Note: you can also use create_list.
+	int f_category_display = f.create_subform("General settings", @fc_general); // Now by default, the main form embeds the general category form right there.
+	int f_ok = f.create_button("&Save settings", true);
+	int f_cancel = f.create_button("Cancel", false, true);
+	// Now lets create a structured list of categories that can be browsed based on the class above.
+	settings_category@[] categories = {
+		settings_category("General", @fc_general),
+		settings_category("Gameplay", @fc_gameplay)
+	};
+	// And then add the list of categories to the form's list.
+	for (uint i = 0; i < categories.length(); i++) {
+		f.add_list_item(f_category_list, categories[i].name);
+	}
+	// Focus the form's list position on the general category, then set the form's initial focused control to the category list.
+	f.set_list_position(f_category_list, 0);
+	f.focus(0);
+	settings_category@ last_category = @categories[0]; // A handle to the currently selected category so we can detect changes to the selection.
+	// Finally this is the loop that does the rest of the magic.
+	while (!f.is_pressed(f_cancel)) {
+		wait(5);
+		f.monitor();
+		int pos = f.get_list_position(f_category_list);
+		settings_category@ selected_category = null;
+		if (pos > -1 and pos < categories.length())
+			@selected_category = @categories[pos];
+		if (@last_category != @selected_category) {
+			last_category.f.subform_control_index = -1; // Later improvements to audio form will make this line be handled internally.
+			last_category.f.focus_silently(0); // Make sure that if the category is reselected, it is focused on the first control.
+			@last_category = @selected_category;
+			f.set_subform(f_category_display, @selected_category.f);
+			f.set_caption(f_category_display, selected_category.name + " settings");
+		}
+		// The following is a special feature I came up with in stw which makes it so that if you are in the category list, keyboard shortcuts from the entire form will work regardless of category.
+		if (f.get_current_focus() == f_category_list and key_down(KEY_LALT) or key_down(KEY_RALT)) {
+			for (uint i = 0; i < categories.length(); i++) {
+				if (categories[i].f.check_shortcuts(true)) {
+					f.set_list_position(f_category_list, i);
+					@last_category = @categories[i];
+					f.set_subform(f_category_display, @last_category.f);
+					f.set_caption(f_category_display, last_category.name + " settings");
+					f.focus(f_category_display);
+					break;
+				}
+			}
+		}
+		// Now we can finally check for the save button.
+		if (f.is_pressed(f_ok)) {
+			logostart = fc_general.is_checked(f_logostart);
+			menuwrap = fc_general.is_checked(f_menuwrap);
+			firespace = fc_gameplay.is_checked(f_firespace);
+			radar = fc_gameplay.is_checked(f_radar);
+			return;
+		}
+	}
+}
+
+// Lets make this thing run so we can see it work.
+void main() {
+	show_window("test");
+	settings_dialog();
+}

doc/src/references/include/Auditory User Interface (form.nvgt)/Classes/audio_form/Methods/set_subform.nvgt

@@ -0,0 +1,100 @@
+/**
+	Sets a sub form to use on the current form.
+	bool audio_form::set_subform(int control_index, audio_form@ f);
+	## Arguments:
+		* int control_index: the control index of the sub form created with `audio_form::create_subform` method.
+		* audio_form@ f: an object pointing to an already created form.
+	## Returns:
+		bool: true if the operation was successful, false otherwise. To get error information, look at `audio_form::get_last_error();`.
+*/
+
+// Example:
+#include "form.nvgt"
+
+// some imaginary global application variables.
+bool logostart = true, menuwrap = false, firespace = false, radar = true;
+
+// First, lets make a class which stores a category name and the form that the category is linked to.
+class settings_category {
+	string name;
+	audio_form@ f;
+	settings_category(string n, audio_form@ f) {
+		this.name = n;
+		@this.f = @f;
+	}
+}
+
+void settings_dialog() {
+	// Define some categories and settings on each category like this:
+	audio_form fc_general;
+	fc_general.create_window();
+	int f_logostart = fc_general.create_checkbox("Play &logo on startup", logostart);
+	int f_menuwrap = fc_general.create_checkbox("Wrap &menus", menuwrap);
+	audio_form fc_gameplay;
+	fc_gameplay.create_window();
+	int f_firespace = fc_gameplay.create_checkbox("Use space instead of control to &fire", firespace);
+	int f_radar = fc_gameplay.create_checkbox("Enable the &radar", firespace);
+	// Add as many categories as you want this way.
+	audio_form f; // The overarching main form.
+	f.create_window("Settings", false, true);
+	int f_category_list = f.create_tab_panel("&Category"); // The user will select categories from here. Note: you can also use create_list.
+	int f_category_display = f.create_subform("General settings", @fc_general); // Now by default, the main form embeds the general category form right there.
+	int f_ok = f.create_button("&Save settings", true);
+	int f_cancel = f.create_button("Cancel", false, true);
+	// Now lets create a structured list of categories that can be browsed based on the class above.
+	settings_category@[] categories = {
+		settings_category("General", @fc_general),
+		settings_category("Gameplay", @fc_gameplay)
+	};
+	// And then add the list of categories to the form's list.
+	for (uint i = 0; i < categories.length(); i++) {
+		f.add_list_item(f_category_list, categories[i].name);
+	}
+	// Focus the form's list position on the general category, then set the form's initial focused control to the category list.
+	f.set_list_position(f_category_list, 0);
+	f.focus(0);
+	settings_category@ last_category = @categories[0]; // A handle to the currently selected category so we can detect changes to the selection.
+	// Finally this is the loop that does the rest of the magic.
+	while (!f.is_pressed(f_cancel)) {
+		wait(5);
+		f.monitor();
+		int pos = f.get_list_position(f_category_list);
+		settings_category@ selected_category = null;
+		if (pos > -1 and pos < categories.length())
+			@selected_category = @categories[pos];
+		if (@last_category != @selected_category) {
+			last_category.f.subform_control_index = -1; // Later improvements to audio form will make this line be handled internally.
+			last_category.f.focus_silently(0); // Make sure that if the category is reselected, it is focused on the first control.
+			@last_category = @selected_category;
+			f.set_subform(f_category_display, @selected_category.f);
+			f.set_caption(f_category_display, selected_category.name + " settings");
+		}
+		// The following is a special feature I came up with in stw which makes it so that if you are in the category list, keyboard shortcuts from the entire form will work regardless of category.
+		if (f.get_current_focus() == f_category_list and key_down(KEY_LALT) or key_down(KEY_RALT)) {
+			for (uint i = 0; i < categories.length(); i++) {
+				if (categories[i].f.check_shortcuts(true)) {
+					f.set_list_position(f_category_list, i);
+					@last_category = @categories[i];
+					f.set_subform(f_category_display, @last_category.f);
+					f.set_caption(f_category_display, last_category.name + " settings");
+					f.focus(f_category_display);
+					break;
+				}
+			}
+		}
+		// Now we can finally check for the save button.
+		if (f.is_pressed(f_ok)) {
+			logostart = fc_general.is_checked(f_logostart);
+			menuwrap = fc_general.is_checked(f_menuwrap);
+			firespace = fc_gameplay.is_checked(f_firespace);
+			radar = fc_gameplay.is_checked(f_radar);
+			return;
+		}
+	}
+}
+
+// Lets make this thing run so we can see it work.
+void main() {
+	show_window("test");
+	settings_dialog();
+}

doc/src/references/include/Legacy Sound Manager (sound_pool.nvgt)/.MDRoot

@@ -0,0 +1 @@
+This file indicates that this subdirectory should be considered as a root page in the markdown version of the documentation, see the docgen notes for more details.

doc/src/references/include/Legacy Sound Manager (sound_pool.nvgt)/Classes/sound_pool/!sound_pool.md

@@ -0,0 +1,7 @@
+# sound_pool
+This class provides a convenient way of managing sounds in an environment, with 1 to 3 dimensions. The sound_pool_item class holds all the information necessary for one single sound in the game world. Note that you should not make instances of the sound_pool_item class directly but always use the methods and properties provided in the sound_pool class.
+
+`sound_pool(int default_item_size = 100);`
+
+## Arguments:
+* int default_item_size = 100: the number of sound items to be initialized by default.

doc/src/references/include/Legacy Sound Manager (sound_pool.nvgt)/Classes/sound_pool/Methods/destroy_all.md

@@ -0,0 +1,4 @@
+# destroy_all
+destroy all sounds.
+
+`void sound_pool::destroy_all();`

doc/src/references/include/Legacy Sound Manager (sound_pool.nvgt)/Classes/sound_pool/Methods/destroy_sound.md

@@ -0,0 +1,10 @@
+# destroy_sound
+Destroy a sound.
+
+`bool sound_pool::destroy_sound(int slot);`
+
+## Arguments:
+* int slot: the slot of the sound you wish to destroy.
+
+## Returns:
+bool: true if the sound is removed successfully, false otherwise.

doc/src/references/include/Legacy Sound Manager (sound_pool.nvgt)/Classes/sound_pool/Methods/pause_all.md

@@ -0,0 +1,4 @@
+# pause_all
+Pauses all sounds.
+
+`void sound_pool::pause_all();`

doc/src/references/include/Legacy Sound Manager (sound_pool.nvgt)/Classes/sound_pool/Methods/pause_sound.md

@@ -0,0 +1,10 @@
+# pause_sound
+Pauses the sound.
+
+`bool sound_pool::pause_sound(int slot);`
+
+## Arguments:
+* int slot: the sound slot you wish to pause.
+
+## Returns:
+bool: true if the sound was paused, false otherwise.

doc/src/references/include/Legacy Sound Manager (sound_pool.nvgt)/Classes/sound_pool/Methods/play_1d.md

@@ -0,0 +1,18 @@
+# play_1d
+Play a sound in 1 dimension and return a slot.
+
+`int sound_pool::play_1d(string filename, pack@ packfile, float listener_x, float sound_x, bool looping, bool persistent = false);`
+
+## Arguments:
+* string filename: the file to play.
+* pack@ packfile: the pack to use. This can be omitted.
+* float listener_x: the listener coordinates in X form.
+* float sound_x: the coordinates of the sound in X form.
+* bool looping: should the sound play continuously?
+* bool persistent = false: should the sound be cleaned up once the sound is finished playing?
+
+## Returns:
+int: the index of the sound which can be modified later, or -1 if error. This method may return -2 if the sound is out of earshot.
+
+## Remarks:
+If the looping parameter is set to true and the sound object is inactive, the sound is still considered to be active as this just means that we are currently out of earshot. A non-looping sound that has finished playing is considered to be dead, and will be cleaned up if it is not set to be persistent.

doc/src/references/include/Legacy Sound Manager (sound_pool.nvgt)/Classes/sound_pool/Methods/play_2d.md

@@ -0,0 +1,22 @@
+# play_2d
+Play a sound in 2 dimensions and return a slot.
+
+1. `int sound_pool::play_2d(string filename, pack@ packfile, float listener_x, float listener_y, float sound_x, float sound_y, bool looping, bool persistent = false);`
+2. `int sound_pool::play_2d(string filename, pack@ packfile, float listener_x, float listener_y, float sound_x, float sound_y, double rotation, bool looping, bool persistent = false);`
+3. `int sound_pool::play_2d(string filename, float listener_x, float listener_y, float sound_x, float sound_y, bool looping, bool persistent = false);`
+4. `int sound_pool::play_2d(string filename, float listener_x, float listener_y, float sound_x, float sound_y, double rotation, bool looping, bool persistent = false);`
+
+## Arguments:
+* string filename: the file to play.
+* pack@ packfile: the pack to use (optional).
+* float listener_x, listener_y: the listener coordinates in X, Y form.
+* float sound_x, sound_y: the coordinates of the sound in X, Y form.
+* double rotation: the listener's rotation (optional).
+* bool looping: should the sound play continuously?
+* bool persistent = false: should the sound be cleaned up once the sound is finished playing?
+
+## Returns:
+int: the index of the sound which can be modified later, or -1 if error. This method may return -2 if the sound is out of earshot.
+
+## Remarks:
+If the looping parameter is set to true and the sound object is inactive, the sound is still considered to be active as this just means that we are currently out of earshot. A non-looping sound that has finished playing is considered to be dead, and will be cleaned up if it is not set to be persistent.

doc/src/references/include/Legacy Sound Manager (sound_pool.nvgt)/Classes/sound_pool/Methods/play_3d.md

@@ -0,0 +1,29 @@
+# play_3d
+Play a sound in 3 dimensions and return a slot.
+
+1. `int sound_pool::play_3d(string filename, pack@ packfile, float listener_x, float listener_y, float listener_z, float sound_x, float sound_y, float sound_z, double rotation, bool looping, bool persistent = false);`
+2. `int sound_pool::play_3d(string filename, pack@ packfile, vector listener, vector sound_coordinate, double rotation, bool looping, bool persistent = false);`
+
+## Arguments (1):
+* string filename: the file to play.
+* pack@ packfile: the pack to use. This can be omitted
+* float listener_x, listener_y, listener_z: the listener coordinates in X, Y, Z form.
+* float sound_x, sound_y, sound_z: the coordinates of the sound in X, Y, Z form.
+* double rotation: the listener's rotation.
+* bool looping: should the sound play continuously?
+* bool persistent = false: should the sound be cleaned up once the sound is finished playing?
+
+## Arguments (2):
+* string filename: the file to play.
+* pack@ packfile: the pack to use. This can be omitted
+* vector listener: the coordinates of listener in vector form.
+* vector sound_coordinate: the coordinates of the sound in vector form.
+* double rotation: the listener's rotation.
+* bool looping: should the sound play continuously?
+* bool persistent = false: should the sound be cleaned up once the sound is finished playing?
+
+## Returns:
+int: the index of the sound which can be modified later, or -1 if error. This method may return -2 if the sound is out of earshot.
+
+## Remarks:
+If the looping parameter is set to true and the sound object is inactive, the sound is still considered to be active as this just means that we are currently out of earshot. A non-looping sound that has finished playing is considered to be dead, and will be cleaned up if it is not set to be persistent.

doc/src/references/include/Legacy Sound Manager (sound_pool.nvgt)/Classes/sound_pool/Methods/play_extended.md

@@ -0,0 +1,29 @@
+# play_extended
+Play a sound and return a slot. This method has many parameters that can be customized.
+
+`int sound_pool::play_extended(int dimension, string filename, pack@ packfile, float listener_x, float listener_y, float listener_z, float sound_x, float sound_y, float sound_z, double rotation, int left_range, int right_range, int backward_range, int forward_range, int lower_range, int upper_range, bool looping, double offset, float start_pan, float start_volume, float start_pitch, bool persistent = false, mixer@ mix = null, string[]@ fx = null, bool start_playing = true, double theta = 0);`
+
+## Arguments:
+* int dimension: the number of dimension to play on, 1, 2, 3.
+* string filename: the file to play.
+* pack@ packfile: the pack to use.
+* float listener_x, listener_y, listener_z: the listener coordinates in X, Y, Z form.
+* float sound_x, sound_y, sound_z: the coordinates of the sound in X, Y, Z form.
+* double rotation: the listener's rotation.
+* int left_range, right_range, backward_range, forward_range, lower_range, upper_range: the range of the sound.
+* bool looping: should the sound play continuously?
+* double offset: the number of milliseconds for the sound to start playing at.
+* float start_pan: the pan of the sound. -100 is left, 0 is middle, and 100 is right.
+* float start_volume: the volume of the sound. 0 is maximum and -100 is silent.
+* float start_pitch: the pitch of the sound.
+* bool persistent = false: should the sound be cleaned up once the sound is finished playing?
+* mixer@ mix = null: the mixer to attach to this sound.
+* string[]@ fx = null: array of effects to be set.
+* bool start_playing = true: should the sound play the moment this function is executed?
+* double theta = 0: the theta calculated by `calculate_theta` function in rotation.nvgt include.
+
+## Returns:
+int: the index of the sound which can be modified later, or -1 if error. This method may return -2 if the sound is out of earshot.
+
+## Remarks:
+If the looping parameter is set to true and the sound object is inactive, the sound is still considered to be active as this just means that we are currently out of earshot. A non-looping sound that has finished playing is considered to be dead, and will be cleaned up if it is not set to be persistent.

doc/src/references/include/Legacy Sound Manager (sound_pool.nvgt)/Classes/sound_pool/Methods/play_stationary.md

@@ -0,0 +1,22 @@
+# play_stationary
+Play a sound without using dimension and return a slot.
+
+1. `int sound_pool::play_stationary(string filename, bool looping, bool persistent = false);`
+2. `int sound_pool::play_stationary(string filename, pack@ packfile, bool looping, bool persistent = false);`
+
+## Arguments (1):
+* string filename: the file to play.
+* bool looping: should the sound play continuously?
+* bool persistent = false: should the sound be cleaned up once the sound is finished playing?
+
+## Arguments (2):
+* string filename: the file to play.
+* pack@ packfile: the pack to use.
+* bool looping: should the sound play continuously?
+* bool persistent = false: should the sound be cleaned up once the sound is finished playing?
+
+## Returns:
+int: the index of the sound which can be modified later, or -1 if error. This method may return -2 if the sound is out of earshot.
+
+## Remarks:
+If the looping parameter is set to true and the sound object is inactive, the sound is still considered to be active as this just means that we are currently out of earshot. A non-looping sound that has finished playing is considered to be dead, and will be cleaned up if it is not set to be persistent.

doc/src/references/include/Legacy Sound Manager (sound_pool.nvgt)/Classes/sound_pool/Methods/resume_all.md

@@ -0,0 +1,4 @@
+# resume_all
+Resumes all sounds.
+
+`void sound_pool::resume_all();`

doc/src/references/include/Legacy Sound Manager (sound_pool.nvgt)/Classes/sound_pool/Methods/resume_sound.md

@@ -0,0 +1,10 @@
+# resume_sound
+Resumes the sound.
+
+`bool sound_pool::resume_sound(int slot);`
+
+## Arguments:
+* int slot: the sound slot you wish to resume.
+
+## Returns:
+bool: true if the sound was resumed, false otherwise.