Jump to content

Okay, FINE: the SQL GUI system gets XML.


Recommended Posts

Well, hello again!

Believe it or not, I actually listened to you people for once, :-) and due to an unexpected bit of free time at just the right moment, decided to double down and chase this thing to its natural conclusion. (Or at least a big step closer.)

For those who don't know what I'm talking about, you might want to take a minute to go read my first post on the subject.

So, the last couple weeks resulted in the following improvements:

- XML: There is now support for saving/loading XML files.

- The GUI for making GUIs is now fully functional. (And I must admit, was a lot of fun to write, once I got it to the point where I was using it to create itself.)

- Everything has been pushed to a new uiForms branch on my Torque3D repo on github (github.com/ChrisCalef/Torque3D)

- I also released a zip file version with an executable, so people can just download and use it immediately.

So, without further ado, here's the new look:


Before I go further, however, I must make a small confession - the system is not entirely independent of SQL, which is one reason I included the compiled version, to support those who simply refuse to compile sqlite into their projects. ;-) The GUIs you see above only work in conjunction with the (included) database, called uiForms.db. However, what those two XML buttons do is A) save a form from its SQL form out into an XML file, and then B) convert that XML file into a .gui file for Torque.

What it does *not* do, yet, is allow you to make changes to the XML file and then import those changes back into the database, although that is a fairly small additional step and it may happen before long, especially if anybody whines about how much they want it.

So, if you don't want to use SQL, you can just keep my little Empty template build sitting around, and design your GUIs in it, and then kick them out into XML or just save them as .gui files, and use them in your final project.

The only advantage to using XML at all at that point, of course, is if you want to hand edit them, or make new XML files using the same protocol... but that might apply to some people here, so there you go.


First, to put it in your own project, you only need one script file (uiForms.cs), plus a couple of trivial changes to include and execute it, plus the handful of code files to support SQLite. You can grab everything you need by cherry-picking three commits from my branch on github, if you want to go this route.

But for now let's assume you're just using my executable. Fire up uiForms.exe, go to the Empty Room, hit F11 for the World Editor, and look for the uiForms menu up top. Click on the only option, and you should have the big form in front of you.

Now, to make a new gui, simply hit the "+" button next to the Forms list at the very top.

The only things you need to know here are that your form needs a Name, which must be unique for forms in your database, and it needs a Type, which must be a valid Torque standalone GUI window class. You can also set width and height here, or take the defaults and change them later.

Once you hit the Add Form button, it will create and select your new GUI in the big form. Note: the form itself is treated exactly the same as any other GUI element, except that you have to use the Form "-" button to delete it, and please do not attempt to parent or anchor it to any of its children, for obvious reasons.

Anyway, now that your new GUI has a name, you need to add some elements before it will show up, and you need to give it a position. The position (pos x, pos y) is defined for forms in terms of {0.0,1.0} to define a percentage of screen space, ie 0.5,0.5 puts the upper left corner in the exact center of the screen, regardless of resolution.

To add elements, simply hit the "+" button beside the Elements list, and fill in the name, type, and size parameters there. For Elements, the name must be unique within this form, but not for the entire database. The type has to be a valid Torque GUI control, or you will be sorry. I put in a check to make sure it's a valid class, but you're on your own to make sure it's a GUI class.

The Parent list is for containers, please do not get it confused with the Anchor lists! If you make a container control, then you use it as the parent for all controls that are meant to go inside it. Otherwise, the parent should be the main form for everything.

The Anchors are how you arrange controls next to one another. The left align / right align / etc. checkboxes tell it to line up the e.g. left sides together, instead of the default behavior of making the left side of this control line up with the right side of the control you are anchoring it to. IE, use "left align" checked, and top align unchecked, to make a vertical column of controls, but use top align checked and left align unchecked to make a horizontal row of controls.

WARNING: Do NOT make circular loops of anchors! The system will spin its wheels for a while and then give up, or potentially crash, but in no case will you get desirable results! And this is easier to do than you might expect, so please be careful.

Horiz Align and Vert Align are not supported yet, sorry. They were meant to give forms and containers the option of centering, left aligning, right aligning, etc. but I haven't gotten to this yet. If you want to center things, currently you just have to do the math and add an appropriate amount of horizontal or vertical padding to the appropriate elements.

Which brings me to the next subject I should explain a bit: each container has edge padding and regular padding, for both horizontal and vertical axes. As you might expect, the edge padding is what pushes all controls away from the edges, and the regular padding is what goes between controls.

Beyond the container padding, fine adjustments can be done with horiz padding and vert padding on single controls. These get added to the control itself when it is being positioned, but they do *not* get added to the next control in line, just so you know. (That is, if I want my "name" label to be a few pixels over, I can add a few points to its horiz padding, but that won't also add extra pixels to the text edit field coming after it - this would generally be undesirable.)

Outside of that, I think everything there should be self explanatory. My apologies for all the potential GUI fields I've left out here, I'm sure I'll run into more things and be forced to add them as I go. Already it's made my life MUCH better, however. :D

Oh, also, someone mentioned hooking this up to the GUI editor... I'm not sure how that would work, except that there is certainly nothing stopping you from taking the gui output from this system and working on it in the GUI editor. It won't go the other way, however.

Oh yeah, almost forgot the most important part - WHERE are the gui & xml files? Fortunately, they're very easy to find, they just get dropped right into the main game directory. Feel free to modify the script to put them wherever you want, it happens at the very end of the makeSqlGuiForm / makeXmlGuiForm functions.

Which brings me to one more important part: you can just use the makeXmlGuiForm function on its own, in your own project, without sqlite, to convert your XML files to GUI files, and skip my whole little interactive form here, if you just REALLY love typing instead of pushing buttons.

And with that, I think I've spilled everything you need to know about this. Have fun!!!

Link to comment
Share on other sites

Just a head's up: I don't have any statistics enabled on my download links, so I have no idea if anyone has actually downloaded this or is at all interested. If you are, don't be a lurker, speak up!

Otherwise I might not get around to keeping the branch up to date...

Link to comment
Share on other sites

I really appreciate the amount of work this must have taken.

That being said, I have extremely limited knowledge of Torque's existing GUI system so I don't really understand what parts you replaced.

Would you mind explaining some of the bad things about Torque's GUI, why this one is better, why you use sql, how xml is utilized, etc? I did glance at the other thread and I didn't see you specifically address these questions (unless I'm blind, in which case I apologize).

I have to admit that my knowledge of GUI technology in general is pretty underdeveloped so I'm sorry if my questions are dumb.

Link to comment
Share on other sites


Sure, no problem! And your questions are not at all stupid, thanks for asking them!


Would you mind explaining some of the bad things about Torque's GUI, why this one is better, why you use sql, how xml is utilized, etc?


The primary feature I added here that Torque was lacking is the ability to anchor controls to other controls, instead of positioning each control independently. I think this is a fairly common feature of more evolved GUI systems, but Torque doesn't really have a way to do it. What I mean is, in the big form in my screenshot, each of the dropdown menus is linked to the label to its left. If I move the label, it moves the dropdown. Furthermore, I can link an entire column of labels to one label, for example the one on top, and then if I decide the whole list is a little too close to the edge, I can just move the top label, and then not only it but its associated dropdown menu, *and* the entire column of labels below it, *and* all of their associated dropdowns, will be moved with this one change.

As mentioned in the other thread, you can achieve some of this functionality by using GuiContainers, but not at the control-by-control level of granularity I was looking for.

I realized how much I wanted this after spending countless hours on a wall-of-buttons GUI system for a certain long term project, and being frustrated many, many times by the fact that I forgot to put something in that really belonged near the top, and that meant I was going to have to move potentially dozens of other controls just to fit it in. I've never been comfortable using the GUI editor in Torque because of the way it scrambles my files, and the way dragging controls around with the mouse always results in almost but not quite perfect positioning, so what this has meant for me is hours of digging through the script files, changing x and y positions for each control manually.

Needless to say, my new system here beats *that* process hands down. :lol:

Re: SQL and XML - XML got added just to be friendlier to the folks who aren't comfortable with using SQL in their projects yet, but the reason I'm using SQL is twofold:

1) I discovered years ago that any game or application I start writing is going to have a lot of data in it, and in Torque natively this data tends to get distributed across many script files. When I needed more data that didn't properly go into Torque Datablocks or the mission file or any other predefined location, I found myself making up little comma separated text file formats and such, until I finally gave up and rewrote everything to use sqlite. From that day, everything has been awesome and I've never looked back! :D Mainly because now I know I only have to drag ONE file around with me, the database file, and every single piece of information that is not code or art is going to be in that file, accessible via a standardized and efficient querying process.

2) The other big reason, although I hate to admit it here, is because I also discovered long ago that it would be a very wise thing, at every available opportunity, to reduce my dependence on any one engine. Right now I'm looking at one of my projects (openSimEarth) as having its first client in Torque, but hoping to expand it into other engines as time allows. This GUI system, and everything else I've done to move data out of the scripts and into my DB, is a major step toward engine independence and interoperability.

For people who don't want to use SQL, though, as I said above, you can save a GUI out into XML, and then hand edit that XML file to add controls or change anchors, etc., and then using my tool here you can convert that XML into a Torque GUI with everything in its proper position.

It would of course be extra sweet if I would have written all of this into the Torque GUI editor, so that anchors would be tracked there instead of only in my standalone script, but see point (2) to understand why I probably won't be doing that right now.

Hope that answers your questions!

Link to comment
Share on other sites

I'd like to point out that the arrow keys can be used to move all selected objects in the GUI editor in (I think) 10 pixel increments, and if you hold shift (or maybe ctrl) it moves them by 1 point. So, you could drag the selected control or group of controls to approximately the place you wanted them, then "nudge" them into place using the keyboard. With the finer control allowed by the "nudge" controls you don't need to hand-edit GUI files.

You're right, it's more intuitive to be able to treat the GUI almost like a text document. However, I've never found the GUI editor to be "hard to use." I've always found the horizontal and vertical resizing enumerations far more difficult to understand....

Link to comment
Share on other sites

Also, if you've already downloaded it, you might want to grab it again or fetch/merge if you're using the repo, I just put up an update.

Two changes:

1) removed the restriction that parent containers must be defined in the database before any of their children.

2) fixed a bug with clearResultSet, which should help prevent crashes.

Also, I found a little hiccup in my logic, in that you can't use vertical/horizontal padding as a way to move a container around on the form, since it is being used for its original intended purpose of providing padding between the controls inside it. This can be worked around by using two containers, the inside one defining padding between controls and the outside one providing fine tuned positioning, if you really need both functions.

Link to comment
Share on other sites

Join the conversation

You can post now and register later. If you have an account, sign in now to post with your account.

Reply to this topic...

×   Pasted as rich text.   Paste as plain text instead

  Only 75 emoji are allowed.

×   Your link has been automatically embedded.   Display as a link instead

×   Your previous content has been restored.   Clear editor

×   You cannot paste images directly. Upload or insert images from URL.

  • Create New...