[MOD/0.7] NetGUI - embeddable networking GUIs! [new/beta] (Page 1 of 2)

NetGUI embeddable network GUIs!

NOTE: This is 0.7 only yet, since it is not far away anymore and much people are porting their mods to 0.7 or creating new ones for it. But I am going to backport it to 0.6 when (nearly) out of beta if someone is using it

––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––
28.12.2015:

Beta3-rev1

I have to apologize, I did a big mess with the Beta3 release yesterday. It is completely broken, and I have no clue why. I already reviews the complete diff, but I weren't able to see the mistake. Weird things happen…
But as a compensation, I created a patch file for you to just easily apply if you're interested in implementing NetGUI version Beta3-rev1
» Download patch

27.12.2015:

Beta3 is out, the next one could be release1

- New GUI elements: Listboxes, ScrollbarV/H
- Example for Listboxes
- The main changes for this release was code refractoring, therefore not so much to see…
- I also merged the latest changes from vanilla teeworlds to be up-to-date
for complete changelog, see here

Testserver yet online: »151.80.85.125:8080«, kindly provided by Schwertspize
––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––

Hey fellow tees, Henritees here!

I want to present you a modification which is intended for developers, embedding it into their own mods.

NetGUI gives the ability of sending completely customized GUIs to the client, which are being displayed in the esc-menu.
It is written lightweight to be easy to implement. The server-side is only one extra class (so two files to drag and drop into your src folder) and a few lines of copy-paste code binding the class into your game. Conflicts with any other modification you may have made to the code are therefore very unlikely.
The server class provides a few functions which are kind of an API, so you don't have to understand how NetGUI works at all to make use of it.

Remember that this mod is highly in beta, and the current version is not more than a demonstration of what it might be one day. Nevertheless, it is yet powerful and worthy to use
Unfortunately, NetGUI needs both server and client modification to work (which is quite obvious...), but, depending on your purpose of use, you can make it optional by faking the nethash. Shouldn't cause problems at all. Clients which don't have the ability to receive and display GUIs will just not receive and display them then, but can still play on your server.

Features: (for details, see below of the screenshot!)
Currently not much (very beta!).
- UIRect, similar to the Client's RenderTools()->DrawUIRect(…), draws rectangles.
- Label, similar to the Client's TextRender()->Text(…), writes Text.
- ButtonMenu, similar to the Client's DoButton_Menu(…), draws (usable!) Buttons.
- EditBox, similar to the Client's DoEditBoxOption(…), creates EditBoxes for inputting text!
- CheckBox and CheckBoxNumber, makes checkboxes
- Scrollbar, similar to the Client's DoScrollbarV/H
- ScrollbarOption, similar to the Client's DoScrollbarOption
- InfoBox, thats a EditBox which is just not editable
- ListboxHeader and ListboxStart, together they make a Listbox containing a list of items
- - ListboxItemAdd and ListboxItemRemove to manage the items they contain (a item just holds a string of your wishes)

Download: (version Beta3, v0.1-b.3-151227 ~~ master: v0.1-b.2-151227)
<- automatically compiled and uploaded by Schwertspize, thanks for that!
- Source
- Linux 64 bit
- Windows 32 bit CLIENT ~ SERVER
- anything else: please compile from source. (GitHub: Henningstone/tw_netgui)
The server binary is only for demonstration of a little example, so you see it's working and you are too lazy to download and compile! If you want to USE this mod, you must download and edit it and/or embed the source.

News & Updates: (kinda littly devblog)
04.01.15 «» Windows builds are available from now on!
03.01.15 «» KeySelect element implemented; optional parameters for some functions
28.12.15 «» Nope, the next one is not release1. It is Beta3-rev1, released today
27.12.15 «» Beta3 is finally out! Next one could be release1...
25.12.15 «» Started implementing ListBoxes (you know, the ones which show a list of elements ^^), minor bugfixing
24.12.15 «» A lot of code refractoring (adding elements is a lot easier now since most code is written by the preprocessor now )
24.12.15 «» Added InfoBoxes (the same like EditBoxes but not editable )
22.12.15 «» Fixed vanilla compatibility issue (by Redix).
20.12.15 «» Beta2 is out, yay!
15.12.15 «» Added CheckBoxes and Number-CheckBoxes + cleanup to the networking code
14.12.15 «» Wrote some quite example code for reading multiple editboxes at once (e.g. for login fields)
13.12.15 «» Added EditBoxes and the possibility to request the entered text! I also advanced the Example

If you find bugs or have an idea, feel free to post it into this thread. Or into my GitHub issues tracker.

You are not supposed to read everything. That is only necessary if you want to make use of this mod or are extremely interested in how it workz
If you don't read on, thanks for having had a look anyway!

Greez and have fun,
Henritees
–––––––––––––––––––––––––––––––––––––––––––––––––––––––––
Screenshots: (below is a short how-to to get you started with implementing)

Quick-start guide for modders who want to use it in their server modification:

1. Implementing server-side:
1. First, go ahead an grab the source!
2.1 In case you haven't modified datasrc/network.py, just overwrite yours with mine.
2.2 In case you have, open my version of it and copy the bottom lines into yours. (They're labelled  "## netgui messages")
3. Drag-and-drop src/game/server/netgui.*
4. In my src/game/server/gamecontext.*, search for "netgui" using your text editor and copy-paste the lines you find into your source.
-> The server part is implemented, congratulations!

Building your own custom GUI:
Building GUIs is done in src/game/server/netgui.cpp
1. You are recommended to put every set of GUI elements into their own method of CNetGui, see my usage example in the code.

2. Usage of the API functions
Most API function have quite similar arguments. The ones which all of them have will be explained in the following:
¤ 2.1¬ int ClientID: obviously, the Client to send the GUI to (-1 for all connected Clients).
¤ 2.2¬ int NetGuiElemID: This is a unique ID for the element. Every type of element (labels, buttons, etc) has it's own list, so between them IDs can double. You'll need it to remove the element again, and Client's button presses will also send back the button's ID. Using an ID twice results in overwriting the previous element with the new element. Further, the ID tells the render order of elements with the same type (e.g. Rects): higher ID will be rendered before lower IDs.
¤ 2.3¬ vec4 Dimensions: Given in percent (0-100 of the Client's screen). The first to fields of the vec4 are the x values, the 3rd and 4th are the y values. Dimensions are always given like "X-Coord1 to X-Coord2, Y-Coord1 to Y-Coord2". Example: vec4(0,100,10,50) will draw a rect with x-Dimensions from 0% to 100% and y-Dimensions from 10% to 50%.
¡¡¡ please note: I will replace them in the following documentation by just three dots (…) !!!

List of currently available API functions:

CNetGui::void UIRect(int ClientID, int NetGuiElemID, vec4 Dimensions, vec4 Color, int Corner, float Rounding);

Additional notes:
- Color: color of the element in RGBA format.
- Corner: a value of s CUI::CORNER… enum. (e.g. CUI::CORNER_ALL would be 15)
- Rounding: the rounding of the corners (a good value is 5.0f)

void Label(int ClientID, int NetGuiElemID, const char *pText, vec4 Dimensions, vec4 Color, int FontSize, int FontAlign, int MaxTextWidth);

Additional notes:
Labels are being written into a virtual rect which you can define using Dimensions.
- FontAlign: how to align the text within it's rect. Pass 0 for left-aligned, 1 for centered, 2 for right-aligned.

void ButtonMenu(int ClientID, int NetGuiElemID, const char *pText, int Checked, vec4 Dimensions);

Additional notes:
(see "How to interact with buttons")

void RemoveElement(int ClientID, int Type, int NetGuiElemID);

Additional notes:
This removes an element from the client's screen.
- Type: You must pass one of the NETMSGTYPE_SV_NETGUI_… enum values here. This defines the type of element you want to remove, because every type has it's own list of identifiers.
- NetGuiElemID: The unique ID of the element you want to remove. You previously defined it when creating the element.

These ones are new in beta2!

void EditBox(…, const char *pTitle, int SplitValue, int MaxTextWidth, bool Password);

Additional notes:
- const char *pTitle: This text will automatically be set at the left of your editbox
- int SplitValue: The ratio between text and box in percent, e.g. 50 will do half-half
- int MaxTextWidth: How many characters the user will be able to input
- bool Password: Whether the entered characters will be hidden through stars ******

void CheckBox(…, const char *pText, int Checked);

Additional notes:
This checkbox can be checked or unchecked.
- int Checked: Whether the checkbox should be checked by default or not (enter 0 or 1)

void CheckBoxNumber(…, const char *pText, int MinValue, int MaxValue, int StepValue);

Additional notes:
This checkbox holds a number, whichs range you can define yourself:
- int MinValue, MaxValue, StepValue: the minimum/maximum value; how great the step should be

void Scrollbar(…, bool Vertical = false);

Additional notes:
- bool Vertical: When set to true, the scrollbar will be drawn vertical, otherwise it will be horizontal (default)

void ScrollbarOption(int ClientID, int NetGuiElemID, vec4 Dimensions, const char *pText, float VSplitVal, int Min, int Max, bool Infinite);

Additional notes:
- bool Infinite: when set, the value 0 (zero) will be shown as ∞ (infinite) instead

These ones are new in beta3!

void ListboxHeader(…, const char *pTitle, float Height, float Spacing);

Additional notes:
- If you want to use a Header for your Listbox, send this header before you send the listbox.
- It's Dimensions must resemble the final dimensions of the listbox (they will be used)

void ListboxStart(… const char *pBottomText, float RowHeight, int ItemsPerRow, int SelectedIndex, int HeaderID=-1, bool Background=true);

Additonal notes:
- const char *pBottomText: This text will be displayed at the bottom of the listbox. Pass '0' to disable.
- float RowHeight: How high each row of elements will be
- int ItemsPerRow: How many items should appear in one row (will determine the item width of cause...)
- int SelectedIndex: The element with this index will be selected by default for the client when receiving the GUI
- int HeaderID=-1: IMPROTANT!! If you want to use a header, enter it's NetGuiElemID here!

How to interact with buttons
whenever a client clicks a button on your NetGUI, the button will send a NetMsg containing it's NetGuiElemID back to the server (the one you defined before).
CNetGui::OnMessage handles this messages for now. From switching the ID, you can determine which actions need to be taken. See my example in code and you'll understand how to do it

How to interact with anything else that buttons

void RequestData(int ClientID, int Type, int NetGuiElemID);

Requests the data held by the defined GUI element
- int Type: the type (enter smth like NETMSGTYPE_SV_NETGUI_*
- int NetGuiElemID: The custom id you defined when creating the element
The client will send a appropriate message back to the server, which can be evaluated to take the steps you want.