Scriptable Dialogs

# Introduction Scriptable dialogs is a feature that allows script developers create their own menu or popup dialogs, on [TT 4.7 Update 3 (r8616)](/Downloads/#rev-8616) and newer versions. ## Dialogs Scriptable dialogs allows developers to create a full-screen menu style, and popup style dialogs with customizable size, location and title bar. A dialog's max width can be 400, and max height can be 300, as well as control locations. This is called "dialog units". You should design your dialogs for 400x300 resolution. Dialog units are scaled to client's screen on render time. Exceeding the maximum dialog units may cause unwanted effects. ### Menu Dialog Menu dialog is a full screen menu dialog with usual background and scanline. As this dialog is full screen, location and size controlling of this type is impossible. ### Popup Dialog Popup dialog is a Message Box style, resizable and movable dialog with backdrop and optionally a title. It is possible to locate this dialog anywhere on screen, or you can also orientate this dialog with a combination of top, middle, bottom and left, center, right. ## Controls These dialogs are capable of handling 8 different control types: Labels, Images, Buttons, Text Boxes, Check Boxes, Combo Boxes (Dropdowns), Sliders and Progress Bars. ### Labels Labels displays texts, with custom color and style. It is possible to configure a label to display the text as title, or as normal text with customizable text color. By design, label texts are limited to 128 characters, and texts longer than 128 characters will be cropped. ### Images Images displays textures, with custom texture name. Image control is only capable of displaying valid game textures, such as DDS and TGA. Texture names are limited to 32 characters. Texture names longer than 32 characters will be cropped, thus causing possibly unintended appearance. ### Buttons Buttons are clickable elements that sends events to remote on click with 3 possible styles: Title, Image and Bordered. By design, button image texture names are limited to 32 characters, and button text is limited to 96 characters. Texture names longer than 32 characters long will be cropped, thus causing possibly unintended appearance. Button texts longer than 96 characters will be cropped. #### Title Buttons Title buttons are also known as flat buttons, is the title-label style buttons, such as the ones in the Main Menu. #### Image Buttons Image buttons displays textures instead of text, they display two different textures when mouse is down and up. #### Bordered Buttons Bordered buttons is the usual button style, with borders and a text in the middle. ### Text Boxes (Text Area) Text area is a text and password input field that a client can type in text. Although the text limit can go higher, textbox texts are limited to 128 characters, and texts longer than 128 characters will be cropped. ### Check Box Check box is a simple toggleable element which can be checked and unchecked. Checkbox texts are limited to 128 characters, and texts longer than 128 characters will be cropped. ### Combo Box (Dropdown) Combo box is a dropdown of multiple options that clients can select. Each combo box option has a 32 character limit, and options longer than 32 characters will be cropped. However, if total length of all option texts exceed 192 characters, clients may not receive the control properties properly. ### Slider (Track Bar) Slider is a control that allows clients to choose a number between specified upper and lower bounds. ### Progress Bar Progress bar allows clients to see the progress of an operation. # Usage *Note for regular users: This section is for developers, and details how to use scriptable dialogs.* Scriptable dialogs require an existing client's ID (whether or not they are in-game, so they can be created during connection requests) to work, and dialogs are automatically deleted when the owning client leaves the game, **after player leave event hooks**. Dialogs also reset automatically on every level unload. (Game Over event) ## Engine Functions Scriptable dialogs are created, controlled and deleted by calling engine functions. ### Create_Menu_Dialog(int target) This function creates a menu style dialog for the specified client, and returns the dialog instance. ### Create_Popup_Dialog(int target) This function creates a popup style dialog for the specified client, and returns the dialog instance. Note that this function does not configure the dialog size, location and orientation. You will have to do it later. ### Find_Dialog(int id) This function finds a dialog by it's ID. Returns `nullptr` if a dialog was not found. ### Show_Dialog(ScriptedDialogClass* dialog) This function signals the owning client to show this dialog. ### Hide_Dialog(ScriptedDialogClass* dialog) This function signals the owning client to close this dialog. ### Delete_Dialog(ScriptedDialogClass* dialog) This function deletes the dialog. ## Event Hooks Scriptable dialogs can also send button click events, value change events, dialog open and close events to the remote, so developers can create interactive dialogs. ### AddDialogHook(DialogHook h) This function registers a delegate which will be triggered when a dialog event occurs. This function also returns an ID which can be used later on to remove the hook. ### RemoveDialogHook(int pos) This function unregisters an event hook by its ID. ### SSGM Event Hook You can listen to dialog events from SSGM plugins, by registering `EVENT_DIALOG_HOOK`. Parameter list is same as `DialogHook`. Check out the example SSGM plugin for more information about this event hook. ## Dialog Functions Please refer to the header file `ScriptedControls.h` for available functions for controls. ## Utility Functions `engine_dialog.h` contains useful functions to speed up your development and keep the code shorter and cleaner. You can also read the source file `engine_dialog.cpp` to learn how to create, use and modify controls. ### Create_Label_Control(ScriptedDialogClass* dialog, int x, int y, int width, int height, const wchar_t* text, bool title, Vector3 label_color) This function creates a Label control in specified `dialog`, at `x` `y` coordinates, with specified `width` and `height`, and with optional label text, a boolean whether to enable title style or not, and label color. ### Create_Image_Control(ScriptedDialogClass* dialog, int x, int y, int width, int height, const char* texture_name) This function creates an Image control in specified `dialog`, at `x` `y` coordinates, with specified `width` and `height`, and with specified texture name. ### Create_Bordered_Button_Control(ScriptedDialogClass* dialog, int x, int y, int width, int height, const wchar_t* text) This function creates a Button control with bordered style in specified `dialog`, at `x` `y` coordinates, with specified `width` and `height`, and with button text. ### Create_Image_Button_Control(ScriptedDialogClass* dialog, int x, int y, int width, int height, const char* button_up_texture, const char* button_down_texture) This function creates a Button control with image style in specified `dialog`, at `x` `y` coordinates, with specified `width` and `height`, and with specified button up and down state texture names. ### Create_Title_Button_Control(ScriptedDialogClass* dialog, int x, int y, int width, int height, const wchar_t* text) This function creates a Button control with title (flat) style in specified `dialog`, at `x` `y` coordinates, with specified `width` and `height`, and with button text. ### Create_TextArea_Control(ScriptedDialogClass* dialog, int x, int y, int width, int height, const wchar_t* default_text, int limit) This function creates a Text Area control in specified `dialog`, at `x` `y` coordinates, with specified `width` and `height`, and with optional default text and limit. ### Create_CheckBox_Control(ScriptedDialogClass* dialog, int x, int y, int width, int height, const wchar_t* text, bool checked) This function creates a Check Box control in specified `dialog`, at `x` `y` coordinates, with specified `width` and `height`, with specified text and optionally a boolean whether to check the check box by default or not. ### Create_ComboBox_Control(ScriptedDialogClass* dialog, int x, int y, int width, int height, DynamicVectorClass<WideStringClass>* items, int selected_index) This function creates a Combo Box control in specified `dialog`, at `x` `y` coordinates, with specified `width` and `height`, and optionally with a list of strings and default selected index. ### Create_Slider_Control(ScriptedDialogClass* dialog, int x, int y, int width, int height, int value, int min, int max) This function creates a Slider control in specified `dialog`, at `x` `y` coordinates, with specified `width` and `height`, and optionally with minimum, maximum and value. ### Create_ProgressBar_Control(ScriptedDialogClass* dialog, int x, int y, int width, int height, int value, int min, int max) This function creates a Progress Bar control in specified `dialog`, at `x` `y` coordinates, with specified `width` and `height`, and optionally with minimum, maximum and value. ### Set_Control_Bounds(ScriptedControlClass* control, int x, int y, int width, int height) This function sets the specified `control`'s location and size. ### Create_Centered_Popup(int client, int width, int height, const wchar_t* title) This function creates a popup dialog for specified `client`, with specified `width` and `height`, and optionally with a popup title. ## Samples We provide 3 sample popup dialogs with scripts, which you can find their source in `engine_dialog.cpp`. ### Create_Yes_No_Dialog(GameObject* obj, const wchar_t* popup_title, const wchar_t* label_text, int& yes_button_id, int& no_button_id, Vector3 label_color) This function creates a centered popup dialog with a label and 2 buttons, with specified `popup_title`, `label_text` and optionally `label_color`, with 2 buttons which are "Yes" and "No", then writes the Yes button's ID to `yes_button_id`, No button's ID to `no_button_id` so events can be handled by developer. And finally, returns the created dialog. ### Create_Yes_No_Cancel_Dialog(GameObject* obj, const wchar_t* popup_title, const wchar_t* label_text, int& yes_button_id, int& no_button_id, int& cancel_button_id, Vector3 label_color) This function creates a centered popup dialog with a label and 3 buttons, with specified `popup_title`, `label_text` and optionally `label_color`, with 3 buttons which are "Yes", "No" and "Cancel"; then writes the Yes button's ID to `yes_button_id`, No button's ID to `no_button_id`, Cancel button's ID to `cancel_button_id` so events can be handled by developer. And finally, returns the created dialog. ### Create_User_Prompt(GameObject* obj, const wchar_t* popup_title, const wchar_t* label_text, int text_limit, int& textbox_id, int& ok_button_id, int& cancel_button_id, const wchar_t* initial_text, Vector3 label_color) This function creates a centered popup dialog with a label, text area and 2 buttons, with specified `popup_title`, `label_text` and optionally `label_color`, `initial_text` for text area, then writes the Okay button's ID to `okay_button_id`, Cancel button's ID to `cancel_button_id`, text area's ID to `textbox_id` so events can be handled by developer. And finally, returns the created dialog.