Basic Menu

Best way to learn the features is to just do, I reckon.

Creating a button

All buttons must be a 9Patch, a plugin that lets you make a sprite with adaptive borders.

Create a 9Patch, give it a texture, set the margins, and change the origin to whatever feels best.

You can set the margins to 0 to just use the whole image as the button.

You can also set the edges and fill to be tiled instead of stretching, which may look better in some cases.

Add the new 9Patch to the ui family.

Now, we should change the button's instance variables.

• section - Since we're making a menu, let's set it to "menu". Any other buttons that should be accessible at the same time should have the same section.

• ID - The ID has to be unique for every component. To ensure this, I recommend using the naming system of putting the section as the prefix, and then what the button does. For this case, let's say this is a button you click to play the game. We'll give it an ID of "menuPlay".

• mGrowWidth, mGrowHeight - These aren't actually necessary in order for the framework to function, but I added them in by default because they're useful. Set them to how many pixels you want the button to grow during certain animations. I set both to 2.

Don't worry about the others right now.

Add some text to this button as a child of the button, and an icon if you want. I use a spritefont here, but it doesn't matter what text plugin you use.

Now, you can add more buttons to your menu. This is what I went for.

Pretty simple, but a great part about this framework is that it's easy to expand upon existing UI, since you don't need any sort of specific order.

The settings button is the same as the play button, but I set the ID to menuSettings. The quit button's ID is menuQuit.

Making it usable

Now that our buttons are set up, it's time to make them actually usable. If you play the layout right now, nothing will happen. Go to the event sheet for this layout.

Make sure you include the uiEV event sheet! It's a pretty common mistake.

Remember when we put our buttons' section to "menu"? We need to enable that section for them to start working.

Add an event like On start of layout, and call the function uiEnableSection(section). For the section parameter, enter the string "menu".

Also make sure that the layout you put the buttons on is actually set to use this event sheet! (Also a common mistake...)

Now, go ahead and play the layout.

If all went well, you should be able to use your mouse, keyboard, or gamepad to navigate the buttons you just made, and even select them with left click or enter.

Congratulations! 🎉🎉🎉

Using surface functions

Getting our new buttons to actually do something is pretty simple. Let's give the play button an actual use.

All you need to do is make a new function in your event sheet with a very specific name: select [insert button ID]

In this case, the function is called select select menuPlay, since we gave the play button that ID.

Now, let's add an action just so we know that this worked. Something like the Browser alert action would work. (You need to add the Browser plugin to your project to do this)

Go ahead and play the layout, and select the play button. The alert, or whatever actions you put there, should activate. If not, check that you named the function correctly, and that it matches with the ID of the button.

Quit confirmation

It's good practice to make it so the quit button in a game never immediately boots you out on click, so let's make it so when you click quit, two more buttons appear: confirm or cancel.

Create the two new buttons. You can create a new object for this, or just duplicate the buttons you already made. I took the lazy route.

Now, we don't want these buttons to be in the same section as menu, since they shouldn't be clickable at the same time as the first three. So, let's give them a new section.

Since these will be enabled when the player tries to quit, let's name the section the same as the ID for the quit button, menuQuit. (This isn't required, this is just a naming convention that I think makes most sense)

Let's name the ID something that makes sense too. The confirm button's ID will be menuQuitConfirm, and the cancel button will be menuQuitCancel.

If you play the layout now, the buttons should be darker, and you can't choose them.

Go to your event sheet and create a new surface function called select menuQuit.

In it, add an action that calls the function uiDisableSection("menu"). This makes it so we can't click the first three buttons anymore.

Add another function call, uiEnableSection("menuQuit"). This will enable our new section.

Play the layout, and click on the quit button. It'll switch over to the new confirmation buttons.

Make surface functions for the confirm and cancel button too. It'll look something like this when you're done...

The reason I called uiDisableAllSections before closing the game is because in the future, I may want the game to fade to black first. We don't want the player to click any buttons anymore while the screen is fading. It's a good function to call when you do any kind of transitions.

Now play the layout and try both buttons out!

One last thing. Normally, you wouldn't even be able to see the quit confirmation until you actually click quit. A quick organized fix is to create a new layer for these buttons specifically, and make that layer visible/invisible when switching sections.

You can also tween the opacity, make the buttons slide in, make the camera slide towards the buttons, whatever you want.

Conclusion

We've got ourselves a pretty simple menu! It's of course lacking a settings menu, but it would be pretty complicated and unnecessary to explain how to make one here. You'd just need to create a new layer, and use a surface function to enable that layer and a new section once settings is clicked on.

However, settings menus usually have more than just buttons. There can be sliders, checkboxes, carousels, and even a scroll view to fit more options. We'll go over how to create these in another page.