Sunday, 19 August 2018

Godot - A Complete Guide To Control Nodes - Popups

So, here we are- part 2, which some of you seriously nagged me for you pests.

Anyway, as the title would suggest, let's get into Popup nodes. These are a lot more straight-forward than the messy stuff that I covered in my last video, so let's get going with the base "Popup" node.

You might notice that when you create it, it doesn't actually have any fancy graphics of its own. That's because it really only exists to hold some logic that is utilized by the rest of these popup nodes, but if you want you can add your own logic as children in Sprites, Labels, or whatever you want to put there.

So I'll add a Label as a child of the Popup node just so I can demonstrate some of the behaviour that the Popup node implements. I'll add a built-in script here, too.

I'll also add a simple ToolButton next to our Popup node so that when we press this button, some code will be executed, and we can change this code a few times to demonstrate a few different behaviours.

So by default this Popup node is hidden, unless we call a function specifically to reveal it, which is usually the "popup()" function. If we press the ToolButton with "popup()" in the callback, then as you might expect, it'll reveal the node, with the Label.

There are a few other functions to call here, "popup_centered", "popup_centered_minsize", and "popup_centered_ratio". It'll probably be easier to demonstrate these with some of the other Popup nodes we'll be looking, so I'll wait until then.

The next interesting thing about this node is that it has a VERY useful "about_to_show()" signal that you can connect. This does exactly what it sounds like, and will run the code that you place into the callback right before it shows the popup. This is useful for generating or changing data at the last moment in a nice and clean way, that ensures that you won't open it with old data showing for a moment.

There's also a "popup_hide()" function that is fairly self-explanatory- whenever you hide this popup, it'll emit this signal.

So that's about all for the base Popup node, let's move onto the more interesting ones- starting with WindowDialog. As you can see if you forcibly reveal the WindowDialog node, it has a nice little body, title bar and an "X" to hide it. This is useful if you want to use Godot's default UI, but you can use StyleBoxes to change it up a bit.

So similarly to our base Popup node, this node is hidden by default. Even if you reveal it in the editor and load up the scene, the Popup will still be hidden by default. So we have to call "popup()" on it to make it visible, which we've already got set up using this ToolButton.

So let's look at some of the other functions that I said we'd explore with a more interesting Popup node. First, let's do "popup_centered()". This one will center the node in the middle of the screen, and it's pretty useful. This means that even if we move the Popup node way off-center, it'll still appear in the center when we run this function.

Next, we have "popup_centered_minsize()", and this does the same as above but it takes in a Vector2 quantity for the minimum size of the Popup. I'm not entirely sure why this is useful but in case you wanted to implement that functionality easily, here it is.

Lastly, there's "popup_centered_ratio()", which scales the Popup as a ratio of the size of the screen. This means that it'll appear at the center of the screen, and whatever float you pass via this function will be the proportion of the screen that it'll take up on each axis, relative to the center point. So this means if you input 0.5, every edge will be half-way between the center point and the corresponding edge of the screen. This is very useful too.

So, let's move onto another Popup, and you might in fact notice that there is a child node from the WindowDialog node called AcceptDialog. That's right, we've got another layer to go down! This one is super simple, it basically gives you a pre-defined layout for an "OK" button, a little Alert message and it even gives you a bunch of really helpful signals and methods.

Let's start with the signals, since those are straightforward- "confirmed()" will emit whenever the "OK" button is pressed, and "custom_action()" will emit with the name of the action as an argument whenever we perform a custom action. I'll explain what this means now.

So there's a pretty rad method in the AcceptDialog class called "add_button", which allows you to literally add a button to the AcceptDialog using one line of code- it takes in the text to display on the button, where the button is placed(right or left), and the designated name of the action that you want to bind to this button. So you could bind an action named "explode", and you'd use that "custom_action()" signal that we mentioned earlier to run some code to actually explode something.

But in case that's too annoying for you and you want things to be even easier, there's an even more helpful function called "add_cancel", which just takes in the text to display as an argument and will add a button that hides the AcceptDialog without running the "confirmed()" signal.

So that's pretty nice and I think all you need to know about the AcceptDialog, so let's move onto the next Node.

What's this? AcceptDialog has a child of its own?! That's right, it goes one layer deeper and now we're dealing with ConfirmationDialog. This one is super simple though, as far as I'm aware it doesn't implement any new functionality- it's basically just an AcceptDialog with a "Cancel" button already there.

So let's move on- but wait. Something's not right. You're telling me that there is ANOTHER LAYER to this one?! Yup, I sure am telling you that. We've still got FileDialog to deal with and this one is a little bit more complex. This actually allows you to navigate your hard disk directory stuff and select a file, which is super neat to have already implemented by the engine.

There are a few properties to look at here, the first of which is "Mode". By default, "Mode" is set to  "Save" which means that it'll behave as if it's trying to save a new file. This means that if you select an existing file and click "Save", it'll give you an "are you sure you want to do this?" dialog box.

There are also a bunch of "Open" modes- you can open a folder, you can open a file, many files, or "open any" which I'm pretty sure allows you to select either a folder OR a file.

Next, there's the "Access" property which does do pretty much what it sounds like, it designates what sort of file this FileDialog should be allowed to access. As far as I'm aware, allowing it to access Resources will break it when you try to export, so you can't do that. User data and file system should be fine, so I'd recommend that you use those.

You can add some filters for things like filetypes, if you only want the user to be allowed to select .pngs or something then you can do that super easily.

Similarly, you can opt to show hidden files(though that might be a bit buggy on Windows, weird permission stuff) and you can set the current directory, etc, etc.

None of that is super complicated or unintuitive to use, I'm sure you'll get the hang of it. Likewise, FileDialog implements a few signals- "dir_selected", which passes the path to the directory, "file_selected" and "files_selected" which both pass a String or array of Strings when they're emitted.

Phew, so that's done.

Now we can move onto the next one, PopupDialog. This one is super simple, it's literally just the base Popup node with a panel underneath that corresponds to the size of the Popup. That's genuinely all it is. Easy.

The next one is PopupMenu, which is a little bit more involved. It's basically a context menu, so if you right-click on something and you want the options like copy, paste, select all, etc- that kind of thing, you'd be using the PopupMenu to implement that functionality. The properties are extremely straight-forward, and honestly the signals aren't very complex either- "id_pressed" and "index_pressed" which basically both just exist to point to whichever option was selected here.

There are a bunch of functions here, and a lot of them look pretty confusing at a first glance if you're reading the documentation, but honestly most of these are not complicated or hard to understand. A lot of them are referring to specifics about each entry type, like checkboxes, radio checkboxes(which are the ones where you can only select one option at a time), there's just an item you select and it disappears again, etc. It'd take me way too long for me to step through each function and tell you what it does and you'd probably get bored half way through so I'll leave you to learn what they do on your own. If you have any questions then feel free to ask but I'm confident that you can work it out easily enough.

And lastly, PopupPanel is basically the same as PopupDialog as far as I can tell, so don't stress about that one.

And that is it, I've covered in reasonable detail all of the Popup nodes. You guys asked for it, and I delivered because I'm just that kind. So yeah thanks for watching and stay tuned for more tutorial videos, I guess Part 3 would be on the topic of Buttons- quite a nice topic, I like Buttons, I use them a lot.

Goodbye!

No comments :

Post a comment