-
Notifications
You must be signed in to change notification settings - Fork 138
Gui Editor Guide
The GUI Editor lets you build a screen by dragging controls onto a canvas instead of typing them out. You place a button where you want it, drag its corner until it's the right size, type its caption into a box, and save. The editor writes the file.
That file is an ordinary GUI file. There's nothing special or locked about it — you can open it in a text editor afterwards, or build half a screen here and finish it in script. It works the other way round too: a screen somebody wrote by hand opens in the editor just fine.
This guide covers version 4.0 Early Access 4. The editor arrived in Early Access 3, but several things described here - undo and redo, cut/copy/paste, Duplicate, the control palette and the Explorer's eye and padlock columns - are Early Access 4 additions.
If you'd rather write your screens by hand, or you want to know exactly what each control and each field does, that's the GUI Guide. This page is about the editor.
Press Ctrl + Tilde (~) anywhere in the engine. A set of tabs appears across the top of the screen — Asset Manager, Project Manager, GUI Editor and so on. Click GUI Editor.
You can also get there from the Toybox using the console button.
There's a lot on screen at first. Here's what everything is.
The canvas is the big area in the middle. This is your screen, shown at actual size. What you see is what your players will see.
The Tools window, top left, holds two buttons and — importantly — the name of the file you're editing. If that name has a * after it, you have unsaved changes. A brand new screen is called untitled.gui until you save it.
The control palette is where you pick controls from. Each one is a little picture of the control itself, sorted into four groups you can fold away when you're not using them.
A couple of controls aren't in the palette, and that's on purpose — a tab page and a menu item mean nothing on their own, so they're made by the tab book and the menu bar that own them instead. More on that below.
The Explorer shows every control in your screen as a tree, so you can see what's inside what. It shares the right-hand column with the palette.
The properties pane shows the settings for whatever control you have selected.
Two ways, and they do exactly the same thing:
- Drag a control from the palette onto the canvas. It lands where you drop it.
- Click a control in the palette. It gets placed for you somewhere sensible and visible.
Clicking is quicker when you're going to move the thing anyway. Dragging is better when you already know where it goes.
The palette has two looks, switched with the pair of buttons at the top. Grid shows big pictures three to a row — nice for browsing when you're not sure what you want. Rows shows a smaller picture with the control's name beside it — better when you know what you're after and want to find it fast.
Controls go inside whatever you drop them on. Drop a button on a window and it belongs to that window; move the window and the button goes with it. If you drop it on empty canvas, it belongs to the screen itself.
Click a control to select it. You'll get a box around it with eight handles — drag the handles to resize, drag the middle to move.
- Arrow keys nudge the selection one step at a time. Much easier than the mouse for lining things up.
- Ctrl + arrow keys grow and shrink the control instead of moving it.
- Shift-click or drag a box around several controls to select more than one. They then move together.
Under Layout there are commands to line things up for you — align the selection to the top, bottom, left or right, center it, or space several controls out evenly. These are much faster than nudging things by eye, and the result is actually straight.
Snap to Grid (Ctrl+G) makes everything you drag land on a grid. Set Grid Size (Ctrl+Shift+G) changes how big the grid squares are, anywhere from 5 to 50 pixels. Turning snapping off no longer forgets your grid size.
The Explorer is the tree of everything in your screen. It's the reliable way to find a control that's hidden behind another one, or to see at a glance what's inside what.
Each row shows a small picture of what kind of control it is, and its name.
Down the left there are two narrow columns:
- The eye hides a control while you work. A hidden control isn't drawn and clicks pass straight through it, so this is how you get at something buried underneath. This is a working convenience only — it is never saved into your file, and your game will never hide anything because of it.
- The padlock locks a control so you can't move or resize it by accident. You can still click it to look at its properties. Also never saved.
You can drag a row onto another row to move a control into a different parent. If a control ends up somewhere it can't be seen after a move like that, the editor pulls it back into view for you.
Select a control and its settings appear here.
The pane only shows you the fields that this kind of control actually uses. That's the main thing to know about it. A chain control never draws text, so it isn't offered nine text settings it will ignore. A tab page's position gets overwritten by its book every time the layout runs, so you aren't invited to set it and watch it snap back. If a field isn't there, it's because changing it wouldn't have done anything.
Most settings get a proper editor rather than a text box:
- Sizing is an anchor picker — you click the edges you want the control to hold on to. (What these mean is explained in the GUI Guide.)
- Colors are swatches you click, with the theme's own colors offered first.
- Images are chosen by looking at them, not by typing a path.
- A list box or drop down gets an Items panel where you type the rows in directly. These get saved with your screen, so a difficulty picker or a language menu can just be part of the file.
- A menu bar builds its own menus. A dropped menu bar arrives with one menu in it, and there's a "+" to add more. Click a menu and a box drops under it where you can add the commands.
- A tab book does the same for pages — it arrives with one page and shows a "+" tab to add another.
At the top there's a Category dropdown. This is what decides which look a control wears — whether a plain GuiControl is a backdrop, a label, or a modal scrim, for example. Changing it swaps the control's appearance for another one from the theme.
File
| Command | Shortcut |
|---|---|
| New Gui | Ctrl+N |
| Open Gui… | Ctrl+O |
| Save Gui… | Ctrl+S |
| Save Gui As… | Ctrl+Shift+S |
| Revert |
Revert re-reads the file from disk and throws away everything you've done since your last save. It asks first.
Edit
| Command | Shortcut |
|---|---|
| Undo | Ctrl+Z |
| Redo | Ctrl+Shift+Z |
| Cut | Ctrl+X |
| Copy | Ctrl+C |
| Paste | Ctrl+V |
| Duplicate | Ctrl+D |
| Delete | Delete |
Layout
| Command | Shortcut |
|---|---|
| Nudge up / down / left / right | Arrow keys |
| Shrink and expand height | Ctrl+Up / Ctrl+Down |
| Shrink and expand width | Ctrl+Left / Ctrl+Right |
| Align top / bottom / left / right | Ctrl+T / Ctrl+B / Ctrl+L / Ctrl+R |
| Center horizontally | |
| Space vertically / horizontally | |
| Bring to Front | Ctrl+Shift+Up |
| Push to Back | Ctrl+Shift+Down |
| Set Grid Size… | Ctrl+Shift+G |
| Snap to Grid | Ctrl+G |
Select
| Command | Shortcut |
|---|---|
| Select All | Ctrl+A |
| Deselect | Ctrl+Shift+A |
Theme — this one changes how the editor itself looks, not your screen. There are four to choose from: Construction Vest (Ctrl+1), Lab Coat (Ctrl+2), Forest Robe (Ctrl+3) and Torque Suit (Ctrl+4). Pick whichever you find easiest on the eyes. To change how your screen looks, use the Set Theme button described below.
Undo and redo work on everything you do to the layout — placing, moving, resizing, deleting, reparenting, editing fields. If you delete something by mistake, Ctrl+Z brings it back.
Copy and paste work within a screen and between screens, so you can build a row of buttons once and paste it into another dialog. Pasted controls get their own names rather than clashing with the originals.
Duplicate (Ctrl+D) is the one you'll use most. It drops a copy of the selection right next to the original, one grid step away, in the same parent. Unlike copy-then-paste, it leaves your clipboard alone — so you can keep something on the clipboard and still duplicate other things while you work.
Names count up sensibly, so duplicating okButton2 gives you okButton3.
Save Gui As… asks for a file name and a format. There are two:
- GUI File (*.gui) — the classic format. It's a script file, and if you open it you'll see something that looks like code.
- TAML (*.gui.taml) — the newer format, which looks like XML.
Pick TAML if you're not sure. The .gui format can't store a couple of things: the rows you typed into a list box or drop down, and the arrangement of a frame set. The editor checks your screen before you save and warns you if you're about to lose something — and it only warns when your screen actually contains one of those, so a warning means it really applies to you.
The editor will not throw away unsaved work without asking. Starting a new screen, opening another one, closing the project and quitting all check first, and offer to save.
The one exception is the window's own X button. That closes the program immediately, and the editor never gets a chance to stop it — so use File → Exit if you have unsaved changes.
A theme is a matched set of looks for all your controls — the fill colors, the borders, the fonts, the cursors. The point is that you don't have to invent an appearance for every button you make. You drop a button in, and it already looks like it belongs with everything else.
This is the main reason to use the editor even if you like writing script. Getting a screen to look consistent by hand means writing out a lot of profiles and keeping them in step.
Set Theme is the brush button in the Tools window, top left. It re-skins your whole screen — every control gets the matching look from the theme you choose, based on what kind of control it is and which Category you gave it.
Themes live in a themes folder inside your project, so each project carries its own. A game can ship more than one and switch between them while it runs.
The other button in the Tools window — the one with the document and pencil — opens the Gui Profile Editor. This is where themes are made and edited. It fills the screen, and it has its own Save and Cancel, so nothing you do in here touches your project until you save.
Down the left is a tree with three folders.
A profile is the look of one kind of control: its fill colors, its font, its borders. The theme has one for each category — a Button profile, a Window profile, a Label profile, and so on.
Select one and its settings appear on the right, next to a live preview showing a real control wearing it. Change a color and the preview changes immediately, which beats saving and restarting to find out that your text is unreadable.
Each category can hold more than one profile. That's how you get two kinds of button in one theme — an ordinary one and a scary red Delete one. When a category holds more than one, the properties pane back in the main editor offers you the choice on that control.
Borders are kept separately because so many profiles share them. Edit one border and everything using it updates.
Each border has a margin, a border and a padding, on all four sides, and they can differ depending on whether the control is normal, hovered, selected or disabled. There's a grid for setting all of it at once when you want fine control.
One tip worth knowing: try to keep the inside of a control the same size across all four states. If you shrink the margin by one pixel when a control is hovered, add that pixel back to the border or the padding. Otherwise the text jumps around as the mouse moves over it.
The mouse pointers. There are seven kinds — the normal arrow, the text I-beam, the move cross, the two resize bars and the two diagonal resize arrows — and a theme carries its own set, so a menu screen and a combat screen can have completely different pointers.
Selecting one gives you a magnified view of the art with a dot showing the hot spot — the exact pixel that counts as "where you clicked". You drag the dot to move it. This has to be done by eye rather than by typing numbers, because whether the tip of an arrow is on the right pixel is a question about what the drawing looks like.
There's a preview area with something to click, so you can try the cursor out before committing. That's the only real test of whether a hot spot is right.
The stock cursor art is gray on purpose. A theme tints it, so a new theme's pointers pick up its colors without anyone drawing anything.
Fonts are chosen from the ones installed on your computer, so you can see the list rather than having to remember exact names. The font gets copied into your project when you use it, so your game still works on a machine that doesn't have it installed.
Colors are picked from a popup with the theme's own colors offered as swatches. You can also type exact numbers if you're matching something.
- Use the Explorer when things get crowded. Clicking on the canvas selects the topmost thing under the mouse, which isn't always the thing you meant. Clicking in the tree is unambiguous.
- The eye column is your friend. If something is buried, hide the thing on top of it rather than moving things around and trying to remember where they were.
-
Give your controls names. The properties pane has a name field at the top.
okButtonis a lot easier to find in the tree later thanGuiButtonCtrl, and it's how your script will reach the control. - Save as TAML unless you have a reason not to. See above.
- Undo goes a long way back. Don't be shy about trying something.
- The editor is not a cage. If you want to hand-edit the file it produces, go ahead — and read the GUI Guide for what every field means.