This is the documentation for the gm82con extension.
The extension allows you to manage your own debug console window for whatever purposes.
Written by nkrapivindev for the GameMaker 8.2 project. Adapted by renex.
This is the table of contents for the documentation.
This paragraph describes the constants provided by the con extension.
Specific values of the constants are not provided on purpose to encourage the developers to actually use the constants instead of hardcoding the numbers.
These constants are values that can be used as a bit mask for the con_handle_events and con_is_event_signaled functions.
con_event_none: just zero, can be used to initialize a variablecon_event_ctrl_c: corresponds to 1 <<CTRL_C_EVENTin the Windows headerscon_event_ctrl_break: corresponds to 1 <<CTRL_BREAK_EVENTin the Windows headerscon_event_ctrl_close: corresponds to 1 <<CTRL_CLOSE_EVENTin the Windows headerscon_event_ctrl_logoff: corresponds to 1 <<CTRL_LOGOFF_EVENTin the Windows headerscon_event_ctrl_shutdown: corresponds to 1 <<CTRL_SHUTDOWN_EVENTin the Windows headers
Please see this page for more information about the events.
See the mentioned functions for more information about these constants
These constants are values that correspond to the console mode values from the Windows headers.
Special values:
con_mode_dontupdate, special constant used to not update a mode and has no equivalent in the Windows headers
Input modes:
con_mode_in_enable_processed_input, corresponds toENABLE_PROCESSED_INPUTin the Windows headerscon_mode_in_enable_line_input, corresponds toENABLE_LINE_INPUTin the Windows headerscon_mode_in_enable_echo_input, corresponds toENABLE_ECHO_INPUTin the Windows headerscon_mode_in_enable_window_input, corresponds toENABLE_WINDOW_INPUTin the Windows headerscon_mode_in_enable_mouse_input, corresponds toENABLE_MOUSE_INPUTin the Windows headerscon_mode_in_enable_insert_mode, corresponds toENABLE_INSERT_MODEin the Windows headerscon_mode_in_enable_quick_edit_mode, corresponds toENABLE_QUICK_EDIT_MODEin the Windows headerscon_mode_in_enable_extended_flags, corresponds toENABLE_EXTENDED_FLAGSin the Windows headerscon_mode_in_enable_auto_position, corresponds toENABLE_AUTO_POSITIONin the Windows headerscon_mode_in_enable_virtual_terminal_input, corresponds toENABLE_VIRTUAL_TERMINAL_INPUTin the Windows headers
Output modes:
con_mode_out_enable_processed_output, corresponds toENABLE_PROCESSED_OUTPUTin the Windows headerscon_mode_out_enable_wrap_at_eol_output, corresponds toENABLE_WRAP_AT_EOL_OUTPUTin the Windows headerscon_mode_out_enable_virtual_terminal_processing, corresponds toENABLE_VIRTUAL_TERMINAL_PROCESSINGin the Windows headerscon_mode_out_disable_newline_auto_return, corresponds toDISABLE_NEWLINE_AUTO_RETURNin the Windows headerscon_mode_out_enable_lvb_grid_worldwide, corresponds toENABLE_LVB_GRID_WORLDWIDEin the Windows headers
Please see this page on MSDN for more information.
cc_...constants: Color values. Put them in the middle of your string.cs_...constants: Style options. Put them in the middle of your string.vk_cr: Just a carriage return character as a string.vk_lf: Just a newline character as a string.vk_crlf: A carriage return + newline (CRLF, RN) sequence string that is used to mark the end of a line and the start of a new one.
This paragraph describes the functions provided by the con extension.
Help: console_open()->bool
Arguments: None
Returns: bool, Whether the console window creation was successful.
Purpose:
This function calls AllocConsole, sets up console I/O handles and applies the console mode.
Help: console_close()->bool
Arguments: None
Returns: bool, Whether the console window has been destroyed successfully.
Purpose:
This function closes all console I/O handles, stops the input thread, then calls FreeConsole to kill the console window.
Help: console_write(line:string)->bool
Arguments:
| Name | Type | Purpose |
|---|---|---|
| line | string | The string to write into the console output |
Returns: bool, Whether the write operation was successful or not.
Purpose:
This function writes a string into the console output.
To print a full line, the string must be terminated with a carriage return + newline (CRLF, RN) sequence.
You can append con_rn to the end of the string to terminate a line properly.
The function has a limit of maximum 4096 UTF-16 characters, to print more characters you need to call the function multiple times (with smaller chunks).
Help: console_input_begin()->bool
Arguments: None
Returns: bool, Whether the input thread is running.
Purpose:
This function starts the input read thread and starts reading input from the console input into a global buffer.
Help: console_input_get()->string
Arguments: None
Returns: string, The current contents of the global input buffer.
Purpose:
This function returns whatever is in the global input buffer that is filled in by the input thread.
The global buffer has a maximum size of 8192 characters and shall be cleared periodically if you're expecting large amounts of input.
Help: console_input_clear()->bool
Arguments: None
Returns: bool, Whether the buffer was cleared successfully or not.
Purpose:
This function clears the input buffer.
When expecting large amounts of input from the console it is sometimes necessary to copy the contents of the input buffer into a GML string when the buffer is getting large, then clear the input buffer and expect more data.
Usually, when working with line-based input (an input is a single line) this is not necessary.
Help: console_input_end()->bool
Arguments: None
Returns: bool, Whether the input thread has been stopped successfully or not.
Purpose:
This function cancels the reading operations and stops the input thread, clearing the input buffer in the process.
Make sure you preserve the contents of the input buffer somewhere before stopping the input thread.
Help: console_set_options(output:con_mode,input:con_mode)->bool
Arguments:
| Name | Type | Purpose |
|---|---|---|
| output | con_mode | A con_mode constant |
| input | con_mode | A con_mode constant |
Returns: bool, Whether the console mode(s) were set successfully or not.
Purpose:
Sometimes it is needed to change the mode of the console window to a different one.
This function can be called before or after the creation of the console window.
A constant con_mode_dontupdate can be used for the output or the input argument if you do not wish to update the respective mode.
(for example if you only want to update the output mode, pass con_mode_dontupdate as the input argument)
The default modes enable VT100 sequences for the output (but not input!), so you can use them to interact with the console window.
Help: console_handle_events(signalmask:con_event)->con_event
Arguments:
| Name | Type | Purpose |
|---|---|---|
| signalmask | con_event | A bit mask of con_event constants |
Returns: con_event, The previous event handler bit mask.
Purpose:
This function allows you to specify for which console events you wish to override the default system handling.
By default the extension handles con_event_ctrl_c and con_event_ctrl_close for you.
(meaning the default previous bit mask is con_event_ctrl_c|con_event_ctrl_close)
This function can be called before or after console window creation.
Help: console_is_event_signaled(signalmask:con_event)->con_event
Arguments:
| Name | Type | Purpose |
|---|---|---|
| signalmask | con_event | A bit mask of con_event constants |
Returns: con_event, a bit mask of events that have been signaled.
Purpose:
This function queries which events have been signaled by the system, returns and then clears the corresponding bits (to prevent querying the same value over and over again).
Meaning, you must preserve the result of this function somewhere if you wish to persist the signaled mask between events.
Example:
///Example
var _signalmask, _is_ctrl_c, _is_ctrl_close;
_signalmask = console_is_event_signaled(con_event_ctrl_c|con_event_ctrl_close);
_is_ctrl_c = (_signalmask & con_event_ctrl_c) != 0;
_is_ctrl_close = (_signalmask & con_event_ctrl_close) != 0;
// now use the _is_ctrl_c and _is_ctrl_close variables for your handlingThis paragraph provides a usage example in GML:
///Create
r = vk_cr;
n = vk_lf;
rn = vk_crlf;
console_open();
console_write("Hello, World!" + rn);
// start accepting input:
console_string = "";
// default events mask
events_mask = con_event_ctrl_c|con_event_ctrl_close;
console_input_begin();
console_write("Type something: "); // do not terminate
///Step
var __con_input, __con_len, __con_i, __con_c, __con_r, __con_ctrl;
__con_input = console_input_get();
__con_len = string_length(__con_input);
__con_i = 1;
__con_r = false;
repeat (__con_len + 1) {
__con_c = string_char_at(__con_input, __con_i);
if (__con_c == r || __con_c == n) {
__con_r = true; // end of line
break;
} else {
console_string += __con_c;
}
__con_i += 1;
}
__con_ctrl = console_is_event_signaled(events_mask) != 0;
if (__con_ctrl) {
window_set_caption("Ctrl handler called!");
}
// clear the input buffer when we have copied stuff from it.
console_input_clear();
if (__con_r) {
if (console_string == "silly") {
window_set_caption("owo i am such a silly gm user");
console_write("can't you upgrade to Studio 2.3+ or something?" + rn);
} else if (console_string == "brazil") {
window_set_caption("https://www.youtube.com/watch?v=fOvJeinoX3s");
console_write("YUOR'E GOING TO BRAZIL MWAHAHA" + rn);
} else if (console_string == "test_utf8") {
console_write("русский утф-8 текст..." + rn);
} else {
console_write("Command not recognized: " + console_string + rn);
}
console_write("Type something: ");
console_string = "";
}