New documentations (#98)

* Started documentation on the number_speaker include

* Completed methods of number_speaker

* Finished number_speaker documentation

* audio_form docs

* Fix indentation and headings in a few places.

---------

Co-authored-by: TheQuinbox <[email protected]>

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

@@ -0,0 +1,14 @@
+# create_link
+Creates a new link and adds it to the audio form.
+
+`int audio_form::create_link(string caption, string url);`
+
+## Arguments:
+* string caption: the label of the link.
+* string url: The link to open.
+
+## Returns:
+int: the control index of the new link, or -1 if there was an error. To get error information, see `audio_form::get_last_error();`.
+
+## Remarks:
+The link control is similar to buttons, but this opens the given link when pressed. This also speaks the error message if the link cannot be opened or the link isn't an actual URL. If you want the maximum possible customization, use `audio_form::create_button` method instead.

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

@@ -0,0 +1,11 @@
+# set_custom_type
+Sets a custom type for a control.
+
+`bool audio_form::set_custom_type(int control_index, string custom_type);`
+
+## Arguments:
+* int control_index: the index of the control.
+* string custom_type: a custom text type to set on the control.
+
+## Returns:
+bool: true if the custom text type was successfully set, false otherwise.

doc/src/references/include/Number Speaking (number_speaker.nvgt)/classes/number_speaker/!number_speaker.nvgt

@@ -0,0 +1,15 @@
+/**
+ The `number_speaker` object is used to facilitate natural and smooth number speech. It is best to use this class if you're developing a game with voice acting.
+ number_speaker();
+ ## Remarks:
+ The `number_speaker` class searches for sound files that match the spoken components of a number as closely as possible, separating words with an underscore. For instance, if the number is 72, it'll first check for a file named seventy_two.wav. If this file is not available, it'll search for seventy.wav and two.wav and combine them.
+ This system allows you to record as many number sounds as desired to achieve flawless spoken output. Alternatively, you can record only essential numbers, such as zero.wav to nineteen.wav, twenty.wav to ninety.wav, and optionally hundred.wav, thousand.wav, and million.wav. You can also record a file named minus.wav to distinguish between positive and negative numbers, as well as and.ogg to have the word "and" spoken if the include_and parameter is enabled.
+*/
+
+// Example:
+#include "number_speaker.nvgt"
+void main() {
+ // Speak a number using speak_wait.
+ number_speaker test;
+ test.speak_wait(350);
+}

doc/src/references/include/Number Speaking (number_speaker.nvgt)/classes/number_speaker/methods/!speak.nvgt

@@ -0,0 +1,21 @@
+/**
+ This method will speak a number.
+ int number_speaker::speak(double the_number);
+ ## Arguments:
+ * double the_number: the number to speak.
+ ## Returns:
+ int: 0 on success, -1 on failure.
+ ## Remarks:
+ The speak method searches for sound files based on the values stored in the prepend and append properties, determining the most appropriate sound files to use by performing multiple searches based on the given number.
+ When this function is called, it returns immediately, allowing the script to continue running while the number is being spoken. To ensure that numbers are spoken smoothly and fluently, it is necessary to call the speak_next method continuously.
+*/
+
+// Example:
+#include "number_speaker.nvgt"
+void main() {
+ number_speaker number;
+ number.speak(350);
+ while(number.speak_next()==1) {
+ wait(5);
+ }
+}

doc/src/references/include/Number Speaking (number_speaker.nvgt)/classes/number_speaker/methods/!speak_next.nvgt

@@ -0,0 +1,20 @@
+/**
+ This method is used to check the status of a number that is currently being spoken or has already been spoken, and, if necessary, initiates the playback of the next number.
+ int number_speaker::speak_next();
+ ## Returns:
+ int: 0 if there are no more files to be played, 1 if there are more files to be played or if the last file is still playing, and -1 if an error occurs.
+ ## Remarks:
+ The speak_next method works in conjunction with the speak method and should be used continuously while the number is being spoken.
+ This method functions not only as a status indicator but also as a trigger, checking and playing numbers as needed. To ensure that the numbers are spoken smoothly and fluently, it is essential to perform this check at regular intervals, approximately every 5 milliseconds.
+*/
+
+// Example:
+#include "number_speaker.nvgt"
+void main() {
+ // Speak a number using speak and speak_next.
+ number_speaker test;
+ test.speak(350);
+ while(test.speak_next()==1) {
+ wait(5);
+ }
+}

doc/src/references/include/Number Speaking (number_speaker.nvgt)/classes/number_speaker/methods/!speak_wait.nvgt

@@ -0,0 +1,19 @@
+/**
+ This method will speak a number and wait until the number is fully read before returning.
+ int number_speaker::speak_wait(double the_number);
+ ## Arguments:
+ * double the_number: the number to speak.
+ ## Returns:
+ int: 0 on success, -1 on failure.
+ ## Remarks:
+ The speak_wait method searches for sound files based on the values stored in the prepend and append properties, determining the most appropriate sound files to use by performing multiple searches based on the given number.
+ The speak_wait function pauses execution until the number has been fully spoken before returning. This means that the script execution is halted for the duration of the reading. To avoid this, you can use the speak and speak_next methods instead.
+*/
+
+// Example:
+#include "number_speaker.nvgt"
+void main() {
+ // Speak a number using speak_wait.
+ number_speaker test;
+ test.speak_wait(350);
+}

doc/src/references/include/Number Speaking (number_speaker.nvgt)/classes/number_speaker/methods/!stop.nvgt

@@ -0,0 +1,17 @@
+/**
+ This method stops any number that is currently being spoken.
+ void number_speaker::stop();
+*/
+
+// Example:
+#include "number_speaker.nvgt"
+void main() {
+ // Speak a number using speak and speak_next, stopping it prematurely if the user presses space.
+ number_speaker test;
+ test.speak(350);
+ while(test.speak_next()==1) {
+ if(key_pressed(KEY_SPACE))
+ test.stop();
+ wait(5);
+ }
+}

doc/src/references/include/Number Speaking (number_speaker.nvgt)/classes/number_speaker/methods/set_sound_object.nvgt

@@ -0,0 +1,19 @@
+/**
+ This method allows you to specify an existing sound object to be used for any auditory feedback in the number speaker.
+ bool number_speaker::set_sound_object(sound@ handle);
+ ## Arguments:
+ * sound@ handle: a reference to an existing sound object that will be utilized for all future sound output.
+ ## Returns:
+ bool: true on success, false on failure.
+ ## Remarks:
+ The object specified in this function will handle all future auditory feedback provided by the number speaker. If this method is not called, an internal sound object will be used by default for sound output.
+*/
+
+// Example:
+#include "number_speaker.nvgt"
+void main() {
+ sound test;
+ number_speaker number;
+ number.set_sound_object(test);
+ number.speak_wait(350);
+}

doc/src/references/include/Number Speaking (number_speaker.nvgt)/classes/number_speaker/properties/!append.md

@@ -0,0 +1,4 @@
+# append
+This string will be appended to any loaded number file. The default extension is .wav, so you only need to change this if your number files use a different extension.
+
+`string number_speaker::append;`

doc/src/references/include/Number Speaking (number_speaker.nvgt)/classes/number_speaker/properties/!prepend.md

@@ -0,0 +1,4 @@
+# prepend
+This string will be prepended to any loaded number file. It is useful if your number files are stored in a separate directory or if the filenames include a specific prefix.
+
+`string number_speaker::prepend;`

doc/src/references/include/Number Speaking (number_speaker.nvgt)/classes/number_speaker/properties/include_and.md

@@ -0,0 +1,4 @@
+# include_and
+This boolean determines whether the word "and" should be included in the appropriate places in the output. If set to true, you must create a file named and.wav, unless the extension (e.g., the append property) is something other than .wav. The default value is false.
+
+`bool number_speaker::include_and;`

doc/src/references/include/Number Speaking (number_speaker.nvgt)/classes/number_speaker/properties/pack_file.md

@@ -0,0 +1,4 @@
+# pack_file
+The pack file to use in the object.
+
+`pack@ number_speaker::pack_file = null;`