Page 1 of 1

ZScript Windows v0.4.0 - Walking Included!

PostPosted: Wed Aug 19, 2020 10:20 pm
by Nero


    ZScript Windows version 0.4.0
    The Generic GUI API Reborn in ZScript!

  • If you're not familiar with Z-Windows, that's ok, Z-Windows died due to memory leaks and lack of multiplayer support.
  • For those who are familiar with Z-Windows, it's back! In a way reborn from the ashes of Z-Windows but mostly rewritten from the ground up.
  • ZScript Windows is better than is predecessor in just about every way!

What Exactly is ZScript Windows?
  • ZScript Windows is a generic GUI API aimed at enabling unique implementations that are flexible and dynamic, specific to the needs of the user, fast, powerful, and simple to use. The entire ZScript Windows API is written in (G)ZDoom's native ZScript, allowing users to design GUI systems rendered at the game's framerate and multiplayer compatible.
  • -
  • Unlike the old GDCC dinosaur, Z-Windows, ZScript Windows is actually fairly straightforward to use for developers who are familiar with C++, if not familiar with ZScript. ZScript Windows is written as a sort of cross between the Win32 API and the .NET API for Windows Forms; hopefully much less confusing than Win32 though. Getting ZScript Windows up and working is even easier than Z-Windows, requiring no extra compilers or batch files. ZScript Windows functions just like any other (G)ZDoom mod.
  • -
  • Note that I'm not taking a jab at GDCC - I think that compiler is an underappreciated gem of programming genius and Z-Windows would not have been at all possible without it. ZScript Windows does some things similar to its ancestor, so it too owes its existence to GDCC.

Working Features
  1. Toggle-able cursor interaction via a keybind.
    • Pretty much every possible mouse event is supported (13 in total).
  2. Windows with multiple border options and background options.
  3. Text with static and dynamic text wrapping, with native ZScript support for fonts and colors.
  4. Alpha for all objects (this is only limited by the drawer - if it has an alpha argument it's supported).
  5. Priority-based layering.
  6. Moving and resizing windows. I need this for further interactive testing.
  7. Buttons, including checkbox and radio types.
  8. Actual multiplayer compatibility - about 90% sure I got it fixed this time.
  9. Event system extensions - every ZObject can send and receive its own net events.

In Progress Features
  1. Textboxes - supporting single and multi-line input (mostly working the kinks out of the cursor)
  2. Command system maintenance - found some bugs, one very crashy bug, just don't put colons (:) in textboxes right now :P
  3. Lines, boxes, and group boxes (boxes with names at the top), even rounded corners.*
    • See Limitations

Planned Features - not in any particular order or determined time frame
  1. Linking for radio/check buttons for easier toggling.
  2. Expanded linking for shapes. Right now a shape can be linked to a text object to clip the text at the shape width.
  3. Support for the 2D shape class - I just need to spend some time messing with it.
  4. Offsets, margins, padding, etc. There's just nothing like that right now.
  5. Scrollbars! I have the algorithms just need to implement.

Limitations
I recently discovered that SetClipRect does not have any impact on the DrawLine methods. While I've fixed the problem for buttons, I have not fixed the issue for ZShapes. Just take a look at the code for the shape drawer, it's a bit of a mess. So for the time being, ZShapes that are located incorrectly will cause unusual clipping glitches. Hopefully a feature request will fix this and make my job way easier.

Downloads and Documentation
Version 0.4.0 Almost Walking Talking Textboxes is on Github!:
  • ZScript Windows v0.4.0 is available via the repository for anyone interested, including the code for textboxes as the control currently stands. As I mentioned I am still working the kinks out of the cursor, I need to re-write how it is handled, and a few features, such as password characters, are as of yet non-functional - just not implemented yet in some cases. The command system is patched, but I feel that a second overhaul is due as I see some yucky-ness about the whole thing I just don't like and I know users will not like.
  • Furthermore, ZScript Windows has been reverted to the original concept of creating hybrid GUI objects out of Actors. This has been successfully tested in multiplayer and the claims are true indeed, you can conceivably create actors with ZScript Windows that can be activated conversationally, i.e. walking, talking, textboxes :D
  • ZScript Windows is an API and no API is useful without demonstrations and documentation. That's where Github comes in. Everything you need can be found there.
  • -
  • ZScript Windows Repository and Documentation
    • Table of Contents
    • Disclaimer! This Wiki is very WIP and very incomplete, I am updating and documenting as I can.
    • Introduction - Not a necessary read, kind of long winded, just an overview of the project history.
    • Conventions - A brief explanation of the central ZScript Windows code structure, kind of the "how and why and what" it does, broadly explained.
    • Class Details - There's a buncha, naw not that many, classes, but one for each control, the window, the event handler, etc. The details are here.
    • Packets - Communicating between contexts involves the Command System and packets, small classes that pass information between contexts for a specific purpose.
    • -
      • Second Disclaimer! There are outdated tutorials on the Github documentation, please disregard them for the time being. For now, the following files can be referenced for functioning examples of window and controls creation.
      • BFG Terminal Window - This is the window the player creates from a line activation in the demo map.
      • Imp Windows - This file contains the definitions for the windows created by talking to the Imp in the demo map.
      • Talk Imp - This is a ham-fisted replacement of the DoomImp to create an activate-able Imp for window creation.
      • BFG Button - A bit more effort goes into buttons, the user has to write a bit of ZScript themselves. This example is the button in the BFG Window that gives the player access to the BFG; that poor Imp.
      • -
        The following are the internal buttons, of course optional buttons, but also valid examples of buttons:
      • Close Button - Same thing as the BFG Button, the functionality to close a window has to be programmed into a button, thus this bit of code.
      • Move Button - And this bit of code lets you move a window around on the screen.
      • Scale Button - I think you get the idea; actually this one kind of got renamed to a confusing name, the button is the "resize button" for making the window bigger or smaller - the blasted drag handle.
  • Packages will be released when things are more finalized.

Requirements
  • I won't lie, I'm fond of my own creation Tooltips, so guess what, ZScript Windows requires Tooltips.
  • ZScript Windows is dependent on Tooltips, so you have to go download that package too.
  • -
  • And you're engine flavor of choice needs needs to support ZScript version : 4.2.1 (or higher)
  • ZScript Windows requires a recent development build of your chosen ZScript-supporting engine, that is in line with the ZScript version in GZDoom version 4.5pre-383
  • Dev build requirement has been redacted, I'm not using the specific feature requiring it like I thought I would so I will wait until next main release. ZScript version requirement remains.

That Pesky Load Order
  • Welp time to get a mod loader such as ZDL - I personally use Lcferrum's for Windows but didn't have success in Debian.
  • As far as I'm aware, this is the safest load order:
    1. Tooltips
    2. ZScript Windows Package
    3. ... other mods, especially anything relying on ZScript Windows

Usage
  • That depends. If you were directed here as part of the requirements for getting a mod to work, you should have downloaded Tooltips and probably ZScript Windows - Regular, but pay attention to what the mod author listed as the required package and any specific load order instructions you are given there as well. When in doubt, if it's not working, please ask!
  • If you're a mod author, ZScript Windows is a bit more involved than Tooltips, so documentation is here.
  • Also, if you're a mod author and you decide to use ZScript Windows, please credit me. Thanks!

Bugs, Updates, Contributions/Code Submissions
  • ZScript Windows Nuked the Console (literally can - I got my HCF method!)
  • Think there's a bug? What's it doing? Got a screenshot? A video? A file? Code? Somethign?! Well then please let me know either here or open an issue on Github.
  • -
  • Hopefully My Updates are Less Painful than Windows 10
  • So ZScript Windows is still a work in progress and stuff is going to change and those changes might break people's code. Sorry, but luckily there's the change tracker on Github and I'll try to be as clear as possible about possible code-breaking changes when releasing updates.
  • -
  • Contributions and Code Submissions
    • The underlying data structure of ZScript Windows isn't really all that complicated, it's largely just a bunch of classes that describe GUI objects, and an operational system to make the objects have relevance to the game world. So if there's a feature or control that you'd like to submit, please do so on the repository! I just ask for clean code and that you use camelCase. And I reserve the right to tweak and fix it (for example, yah spaghetti a bunch of stuff I could do way simpler with inlines, or it works except for one instance, something like that).
    • Also if you have code that will fix bugs, by all means submit that!

Spoiler: "Changelog"