HaxeFlixel Tutorial – 9-slice Images and Buttons

To handle 9-slice images and buttons, we will have to look into the  flixel.addons.ui  package, where we find FlxUI9SliceSprite (API). Thankfully, there is the flixel-ui Github page which includes a very lengthy readme of how to use the UI addons:

https://github.com/HaxeFlixel/flixel-ui

Unfortunately, it still takes some effort for beginners like myself to figure out how to use it, because the information focuses on using XML to generate and format the UI components. As such, we’re going to proceed with the tutorial below using only code, to illustrate usage without XML.

Setup

Let’s create a new template HaxeFlixel project for this tutorial:

Now let’s find some placeholder images. We’ll be using this image, taken from Kenney’s UI pack (visit the website www.kenney.ul for more awesome stuff, btw!) — “blue_button07.png“:

blue_button07Right-click the image above, and save it into your HaxeFlixel project’s  /assets/images  folder. Now we can begin coding.

9-slice Images

In case you’re not sure how 9-slice works, here’s an image to demonstrate:

tut-9slice-ss1In a nutshell, 9-slice images preserve the resolution of the borders. It’s most commonly used in dialogue boxes and button images.

Before we can use the  flixel.addons.ui.FlxUI9SliceSprite  class, we will need to include the haxelib. Go to your Project.xml and enable the following code:

Now you can start using it. Here’s how we add a simple 9-slice image:

In case you’re wondering how the  _slice  works, here’s an illustration:

tut-9slice-ss2

This should be the result when you build with lime test neko :

Screen Shot 2015-03-21 at 10.45.35 AM

9-slice Buttons

If you look at the FlxUITypedButton API page, the descriptions are not helpful in telling you how to use the 9-slicing. However, if you look into the code (FlxUITypedButton.hx on Github), you will discover that there are in fact, annotated comments for the function.

Before we proceed, let’s add the following images into the  /assets/images  folder:

blue_button08blue_button08.png

green_button07green_button07.png

sheet_buttonsheet_button.png

Now let’s update the code like this:

The code above demonstrates 3 parts:

  1. Default 9-sliced button (with default skin)
  2. 9-sliced button using 3 separate images as the 3 states (up, hover, down)
  3. 9-sliced button using one image spritesheet

It may take a while to understand what the function parameters mean — in fact, I recommend you check the Github FlxUITypedButton.hx page, and look for the  loadGraphicSlice9  function’s comments and read the parameter descriptions.

However, if you want a rundown of what to take note of, here’s some points:

  • When loading separate 3 separate images for the button, make sure  _graphicArray  and  _sliceArray  are of equal length. For buttons, the length must be 3, and for toggle buttons, the length is 6. (We’ll talk about toggle buttons some other day!)
  • When loading one spritesheet for the button, make sure to specify the original image size. In the code above, it’s the last two values  49, 49  part in Line 51.
  • When loading one spritesheet for the button, you can either specify just one slice array data, or 3 slice array data. I.e. Line 51, the  _sliceArray  value can also be written as  [_slice]  or [_slice,_slice,_slice] .

Here is a screenshot of how the screen should look like in the end, after adding the three 9-slice button code above:

Screen Shot 2015-03-22 at 4.11.03 AM

And this is a GIF of the buttons in action, to further illustrate the button’s states (up, hover, down):

licecap-button-2

This concludes the tutorial for 9-slice images and buttons. I hope it wasn’t too confusing — It took me a while to figure it out, and it took me even longer to find a way to write the tutorial in an understandable way.

In the next post, we move on to another most commonly used component — Text in HaxeFlixel.

HaxeFlixel Tutorial – Button Events, Callbacks

In the Simple Button tutorial, we covered how to create a simple default button (which comes with text). If you check the API, you’ll notice that FlxButton is extended from FlxTypedButton, which does not include text. This means, we can actually use the functions in FlxTypedButton from FlxButton.

One thing that stumped me as a beginner was that the API did not explain how to use the callback events; the onUp, onDown, onOver and onOut variables are exposed, but there was no example on how to use them. I tried these, but it didn’t work:

It turns out, after some Googling, the answer here, in the upgrade guide page, that explains that you have to set the callbacks within those variables:

Note: the OnButtonUp will replace the OnClickButton callback that was set in the new FlxButton(...)  — they use the same onUp event handler.

Okay, we now know how to add callback to the button events. What if you want to trigger the callbacks with arguments? According to the upgrade guide page, you can do this (Let’s reduce the code to just one onDown event for simplicity sake):

It sounds straight-forward, but … let’s say we have 3 buttons, and we want to know which button the player clicked on. How do we code that? There are two ways I could think of.

The first method is just to add and bind simple values for each button’s callback; In the case below, we use the strings “button 1”, “button 2”, and “button 3”.

However, what if, for each button we click, we want to trigger something else within that button? We can pass the button itself as the value:

Pretty cool, huh?

Note: There’s something quirky about the button event behaviour — the onDown event triggers even when you hold your mouse button down and hover over/hover out of the button. This also happens for onUp event. If you want the onDown/onUp to trigger only if the mouse is over the button, you can set allowSwiping to false.

One last thing — what about sound? e.g. Play a sound when the mouse hovers over and out of a button? Check the upgrade guide again, I think the example usage is straight forward. However, just in case you need an example, here is one, based on the code we’ve written above so far (assuming you have the audio file in the /assets/sounds  folder):

I think that about sums up all there is to know about button handling. In the next post, I’ll attempt to cover 9-slice images, and if possible, 9-slice buttons.

HaxeFlixel Tutorial – Creating A Simple Button

Before playing a game, there usually is a menu of buttons, right? While this seems like a trivial topic, I personally had some difficulty figuring out how to create buttons (not just in HaxeFlixel) beyond the default skin.

Let’s go through the easiest way to create a button by referring to the HaxeFlixel cheat sheet (FlxButton section). Assuming you created a new HaxeFlixel template, let’s modify the MenuState.hx, like this:

And now it should look like this when you build it with lime test neko :

haxeflixel-button-ss1

Now, what if we wanted a custom skin for the button? You could watch a 12-minute video tutorial by varomix WEY below…

… Or you could continue reading below, at your own pace. Let’s assume you’ve watched the video above and still didn’t understand, so let’s start from the beginning then.

Buttons typically have 3 states, and such, we’d need 3 images — the default button, the hovered button, and the pressed button.

So let’s head over to OpenGameArt.org and find a button spritesheet to use, perhaps this one: UI Orbs by StumpyStrust. Download the zip file and extract its contents. Let’s just use one image from the pack — “bnw.png” — and put it in your /assets/images  folder. Take note of the size of the button — each button image is 128×128, and combined, becomes 384×128.

haxeflixel-button-ss2

Now if you modify the code like this:

You’ll get this result, which is undesirable:

haxeflixel-button-ss3

This is because it assumes the button is the full image itself (384×128). Now, if we write the code like this:

… The button now looks fine and works out of the box.

licecap-button

Coincidentally, the order of the button images correspond with the mouse state — normal, hover, pressed. Convenient, huh?

haxeflixel-button-ss4

One last thing — you can just remove the “Click here” text on the button like this:

Okay, so now we know how to make a simple button, and execute code when the player clicks on it. In the upcoming posts, we’ll go in-depth — event/callbacks.