[ZScript] ZForms 1.0

[Gutawer]

ZForms - An easy to use GUI library for ZScript by Gutawer and phantombeta

So honestly this is super way overdue but I'm finally getting around to releasing this after some recent changes reminding me that this exists.

ZForms is a project built out of the difficulty people have expressed with working with the bare-bones nature of the ZScript menu system. It allows easy creation of common UI elements such as buttons, labels, images and frames (which allow for nested menu design).

Version 1.0 Download
Code Repository (Unstable)

Usage of ZForms is pretty simple, in general. The repository has more specific instructions for use (in README.md) but the basic idea is that you use a Python "build script" to generate the code (this is necessary to avoid different projects from clashing with each other if they both use ZForms). Then you just inherit from a class and this gives you access to functions that can create and deal with rendering/handling input for standard UI elements so nothing needs to be done manually.

More detailed usage here (README.md)

Some examples (thanks entirely to phantombeta) are here
API documentation (also thanks to phantombeta) can be found here

Example images:

Se7evidas

---

[imgur]https://i.imgur.com/rwyybfw[/imgur]
[imgur]https://i.imgur.com/LTbVktb[/imgur]
[imgur]https://i.imgur.com/TZZFegV[/imgur]
[imgur]https://i.imgur.com/oXFOPAU[/imgur]

PDA Starter Kit

---

[imgur]https://i.imgur.com/KOoSa69[/imgur]
[imgur]https://i.imgur.com/RnffYPs[/imgur]
[imgur]https://i.imgur.com/guscTt7[/imgur]

Darkadia

---

[imgur]https://i.imgur.com/DMg7Xo3[/imgur]
[imgur]https://i.imgur.com/Cb3Vmgp[/imgur]

Credits:

Gutawer and phantombeta - Code and API design
Example images used - phantombeta and Nash

[Nash]

ZForms is good. If you aren't using it to make UIs in your mods, you don't value your free time. :D

[Jimmy]

Hell yeah!

[Redneckerz]

Incredible piece of work that brings yet another mod-friendly layer of versatility to the GZDoom family.

[Major Cooke]

Out of curiosity, how is the ZFML branch coming along? Looks like you've made quite a lot of progress on many things recently, was curious if that will be continued?

[Gutawer]

Probably not directly. If/when I go back to a textual definition format I'll be rethinking the text design and probably base it on something easier to parse like XML. Reason being, most people won't actually be writing this directly - the main point of making a textual format in the first place is to have it be output from a menu generator so having the text format be easy to read has only caused me issues.

At any rate it's not a priority for me. I'd like to get the 2.0 functionality in and documented before even thinking about continuing that project.

[Deon]

Thank you for the amazing framework.

Please implement a quick fix that currently ruins attempts to use "$text" (language strings).

Code: Select all

	void setText(string text)
	{
		self.text = text;
		self.wrap = true;
		self.autoSize = true;
	}

can be improved into

Code: Select all

	void setText(string text)
	{
		text = Stringtable.Localize(text);
		self.text = text;
		self.wrap = true;
		self.autoSize = true;
	}

or if you want it to be optional (suggestion of 3saster)

Code: Select all

void setText(string text, bool localize=true) {
    self.text = localize ? stringtable.localize(text) : text;
   self.wrap = true;
   self.autoSize = true;
}

Without "text = Stringtable.Localize(text);" the text (in case it's a language $string) would get translated AFTER being stored as text, which would destroy linebreaks, wrapping etc.
This simple fix saved my mod . I hope it's useful.

[Gutawer]

This essentially isn't a bug. There's a couple good internal reasons why not localizing strings inside ZForms itself is a good idea (not least the fact that in ZForms 2.0 internal elements regularly call setText on other labels, which would potentially lead to recursive expansion). You should simply call StringTable.Localize from the outside.

Without "text = Stringtable.Localize(text);" the text (in case it's a language $string) would get translated AFTER being stored as text, which would destroy linebreaks, wrapping etc.

This is a bug for sure but this can't currently be fixed without a feature in GZDoom itself to optionally not localize strings in DrawText. I completely overlooked this and it completely fucks with text input boxes where strings must never be localized, so I guess I should either feature request this or add it myself.

EDIT: Side note - the lack of this GZDoom feature actually screws over its own text boxes. If you set a CVAR in the menu to something like $MUSIC_E1M1 then what you'll notice is that the $ never gets drawn, and when you press Enter and it removes the cursor character _ it'll visually display the text as e1m1 but actually sets it to $MUSIC_E1M1.

[Deon]

I am a bit slow.
Can you explain why using this inside of SetText function for 1.0 could be a problem?

Code: Select all

self.text = localize ? stringtable.localize(text) : text;

I am asking because I've done it and it works perfectly, am I missing some possible issue?

I really appreciate the support and the tools, thank you for giving so much!

[TheRailgunner]

So, I know this must sound like a stupid question, but...how do I actually USE any of this? From what I can tell, doing literally ANYTHING with this requires a working knowledge of ZScript - am I missing something, or does this require essentially learning a complete programming language to do something as simple as make an inventory screen?

I ask mainly because ZForms is described as "incredibly easy to use", but seems impenetrable to me (much like ZScript itself).

[Caligari87]

Yes, you need to know ZScript to use ZForms. It's advertised as "incredibly easy to use" in comparison to doing this stuff in ZScript manually (which is fairly complex even for experienced coders).

TBH I get the impression making an inventory screen has never been "simple" in (G)ZDoom anyway, even using older tech like ACS. This just makes it less painful in a ZScript context.

[Jarewill]

Having made inventory menus in ZScript both manually and using ZForms, I can confirm that ZForms make it SO MUCH EASIER.

It still requires knowledge of ZScript to properly use though, but ZForms is well documented and has good examples.
Here's also a link to my project that has an inventory menu made in ZForms. I don't know if it will help, but it's always another example.

[ramon.dexter]

Hi, the latest gzdoom 4.10.0 returns an error in frame.zsc, line 32, return type mismatch.

[Major Cooke]

I'm unable to check at the moment but if this is because of dynamic array return type changes with the functions, I'm actually reporting this as a bug since it breaks mods.

[Xeotroid]

Use the version of ZForms found in the repository, that one works fine on both stable and dev builds of GZDoom.

(edited for clarity)