From 8097af53d6e3fe4c77fd1ebfe92a6f5d41c36049 Mon Sep 17 00:00:00 2001 From: AffectedArc07 <25063394+AffectedArc07@users.noreply.github.com> Date: Sat, 21 Nov 2020 12:22:16 +0000 Subject: [PATCH] Documentation --- tgui/docs/tutorial-and-examples.md | 44 +++++++++++++++--------------- 1 file changed, 22 insertions(+), 22 deletions(-) diff --git a/tgui/docs/tutorial-and-examples.md b/tgui/docs/tutorial-and-examples.md index 590ea0f0ee7..3497ea97464 100644 --- a/tgui/docs/tutorial-and-examples.md +++ b/tgui/docs/tutorial-and-examples.md @@ -5,21 +5,21 @@ Basic tgui backend code consists of the following vars and procs: ``` -tgui_interact(mob/user, ui_key, datum/tgui/ui, force_open, - datum/tgui/master_ui, datum/tgui_state/state) -tgui_data(mob/user) -tgui_act(action, params) +ui_interact(mob/user, ui_key, datum/tgui/ui, force_open, + datum/tgui/master_ui, datum/ui_state/state) +ui_data(mob/user) +ui_act(action, params) ``` - `src_object` - The atom, which UI corresponds to in the game world. -- `tgui_interact` - The proc where you will handle a request to open an +- `ui_interact` - The proc where you will handle a request to open an interface. Typically, you would update an existing UI (if it exists), or set up a new instance of UI by calling the `SStgui` subsystem. -- `tgui_data` - In this proc you munges whatever complex data your `src_object` +- `ui_data` - In this proc you munges whatever complex data your `src_object` has into an associative list, which will then be sent to UI as a JSON string. -- `tgui_act` - This proc receives user actions and reacts to them by changing +- `ui_act` - This proc receives user actions and reacts to them by changing the state of the game. -- `tgui_state` (set in `tgui_interact`) - This var dictates under what conditions +- `ui_state` (set in `ui_interact`) - This var dictates under what conditions a UI may be interacted with. This may be the standard checks that check if you are in range and conscious, or more. @@ -37,7 +37,7 @@ powerful interactions for embedded objects or remote access. Let's start with a very basic hello world. ```dm -/obj/machinery/my_machine/tgui_interact(mob/user, ui_key = "main", datum/tgui/ui = null, force_open = FALSE, datum/tgui/master_ui = null, datum/tgui_state/state = GLOB.tgui_default_state) +/obj/machinery/my_machine/ui_interact(mob/user, ui_key = "main", datum/tgui/ui = null, force_open = 0, datum/tgui/master_ui = null, datum/ui_state/state = default_state) ui = SStgui.try_update_ui(user, src, ui_key, ui, force_open) if(!ui) ui = new(user, src, ui_key, "my_machine", name, 300, 300, master_ui, state) @@ -45,23 +45,23 @@ Let's start with a very basic hello world. ``` This is the proc that defines our interface. There's a bit going on here, so -let's break it down. First, we override the tgui_interact proc on our object. This +let's break it down. First, we override the ui_interact proc on our object. This will be called by `interact` for you, which is in turn called by `attack_hand` -(or `attack_self` for items). `tgui_interact` is also called to update a UI (hence +(or `attack_self` for items). `ui_interact` is also called to update a UI (hence the `try_update_ui`), so we accept an existing UI to update. The `state` is a default argument so that a caller can overload it with named arguments -(`tgui_interact(state = overloaded_state)`) if needed. +(`ui_interact(state = overloaded_state)`) if needed. Inside the `if(!ui)` block (which means we are creating a new UI), we choose our template, title, and size; we can also set various options like `style` (for themes), or autoupdate. These options will be elaborated on later (as will `ui_state`s). -After `tgui_interact`, we need to define `tgui_data`. This just returns a list of +After `ui_interact`, we need to define `ui_data`. This just returns a list of data for our object to use. Let's imagine our object has a few vars: ```dm -/obj/machinery/my_machine/tgui_data(mob/user) +/obj/machinery/my_machine/ui_data(mob/user) var/list/data = list() data["health"] = health data["color"] = color @@ -69,15 +69,15 @@ data for our object to use. Let's imagine our object has a few vars: return data ``` -The `tgui_data` proc is what people often find the hardest about tgui, but its +The `ui_data` proc is what people often find the hardest about tgui, but its really quite simple! You just need to represent your object as numbers, strings, and lists, instead of atoms and datums. -Finally, the `tgui_act` proc is called by the interface whenever the user used an +Finally, the `ui_act` proc is called by the interface whenever the user used an input. The input's `action` and `params` are passed to the proc. ```dm -/obj/machinery/my_machine/tgui_act(action, params) +/obj/machinery/my_machine/ui_act(action, params) if(..()) return if(action == "change_color") @@ -158,7 +158,7 @@ Here are the key variables you get from a `useBackend(context)` function: interface and who uses it, BYOND refs to various objects, and so forth. You are rarely going to use it, but sometimes it can be used to your advantage when doing complex UIs. -- `data` is the data returned from `tgui_data` and `tgui_static_data` procs in +- `data` is the data returned from `ui_data` and `ui_static_data` procs in your DM code. Pretty straight forward. - Note, that javascript doesn't have associative arrays, so when you return an associative list from DM, it will be available in `data` as a @@ -240,7 +240,7 @@ and builds a new array based on what was returned by that function. ``` If you need more examples of what you can do with React, see the -[interface conversion guide](docs/converting-old-nano-interfaces.md). +[interface conversion guide](docs/converting-old-tgui-interfaces.md). #### Splitting UIs into smaller, modular components @@ -294,18 +294,18 @@ here's what you need (note that you'll probably be forced to clean your shit up upon code review): ```dm -/obj/copypasta/tgui_interact(mob/user, ui_key = "main", datum/tgui/ui = null, force_open = FALSE, datum/tgui/master_ui = null, datum/tgui_state/state = GLOB.tgui_default_state) // Remember to use the appropriate state. +/obj/copypasta/ui_interact(mob/user, ui_key = "main", datum/tgui/ui = null, force_open = 0, datum/tgui/master_ui = null, datum/ui_state/state = default_state) // Remember to use the appropriate state. ui = SStgui.try_update_ui(user, src, ui_key, ui, force_open) if(!ui) ui = new(user, src, ui_key, "copypasta", name, 300, 300, master_ui, state) ui.open() -/obj/copypasta/tgui_data(mob/user) +/obj/copypasta/ui_data(mob/user) var/list/data = list() data["var"] = var return data -/obj/copypasta/tgui_act(action, params) +/obj/copypasta/ui_act(action, params) if(..()) return switch(action)