Skip to content

Introductory Tutorial Starting with Punk.UI: setup and component overview

Rolpege edited this page · 6 revisions

Introduction

Welcome to the Punk.UI official introductory tutorial, a tutorial which will guide you through the setup of Punk.UI and teach you how to use it in a basic way. After you finish this tutorial, you'll be ready to use Punk.UI.

You may want to read What is Punk.UI? before reading this tutorial. Ok, let's start!

Setup

Setup works the same way as you add FlashPunk to your project.

Grab a compressed file with the source here: https://github.com/RichardMarks/punk.ui/tarball/master. You have two options to link the library on your project:

1.- Place the contents of the src folder inside the src folder of your project.

OR:

2.- Place the folder somewhere and make sure you remember where it is. Then, configure your AS3 project to link to that directory.

Ultra-important extra step required

You’ll need to add the Additional function on World.as, or your project will fail to compile.

Setup finished

We have finish Punk.UI setup. It should be working now. If not, there's something weird happening. You can try asking the forums.

We're going to code Punk.UI stuff now, so it's very important that you read the Class hierarchy page so you know what we're talking about, what components can you use and what are they, more or less.

Punk.UI stuff

Every Punk.UI component is an entity. Therefore, we need a World to store them. So, first create a World:

package
{
    import net.flashpunk.World;

    public class Tutorial extends World
    {
        public function Tutorial()
        {
            super();
        }
    }
}

Now, we'll add some components there. Adding a component is very easy. You just instantiate it an add it. If you want, you can store them on a variable as well, if you want to tweak them, but for simple stuff you won't need that.

Let's add a few components there!

package
{
    import net.flashpunk.World;

    import punk.ui.PunkButton;
    import punk.ui.PunkLabel;
    import punk.ui.PunkPasswordField;
    import punk.ui.PunkTextArea;
    import punk.ui.PunkTextField;
    import punk.ui.PunkToggleButton;

    public class Tutorial extends World
    {
        public function Tutorial()
        {
            super();

            add(new PunkButton(10, 10, 100, 25, "Press me"));
            add(new PunkToggleButton(10, 40, 100, 25, false, "Toggle me"));
            add(new PunkLabel("Read me", 125, 10));
            add(new PunkTextField("Write something", 125, 40, 200));
            add(new PunkPasswordField(125, 70, 200));
            add(new PunkTextArea("You could write a book here!", 330, 10, 300, 228));
        }
    }
}

As you can see, creating components is really simple. You will see a Button, a Checkbox, a Label, a TextField, a PasswordField and a TextArea. Buttons won't do nothing, and TextField, PasswordField and TextArea will allow you to write there.

Let's add some actions to our button. We could add a function to the next constructor parameter, which would be the onReleased callback (added there for conveniency), but if we really want to add a lot of cool callbacks, we can use the setCallbacks function (or add them manually…):

package
{
    import net.flashpunk.World;

    import punk.ui.PunkButton;
    import punk.ui.PunkLabel;
    import punk.ui.PunkPasswordField;
    import punk.ui.PunkTextArea;
    import punk.ui.PunkTextField;
    import punk.ui.PunkToggleButton;

    public class Tutorial extends World
    {
        public var button:PunkButton;

        public function Tutorial()
        {
            super();

            button = new PunkButton(170, 300, 300, 140, "Press me");
            button.setCallbacks(onReleased, onPressed, onEnter, onExit);
            add(button);
            add(new PunkToggleButton(10, 40, 100, 25, false, "Toggle me"));
            add(new PunkLabel("Read me", 125, 10));
            add(new PunkTextField("Write something", 125, 40, 200));
            add(new PunkPasswordField(125, 70, 200));
            add(new PunkTextArea("You could write a book here!", 330, 10, 300, 228));
        }

        public function onReleased():void
        {
            button.label.text = "You released me!";
        }

        public function onPressed():void
        {
            button.label.text = "You pressed me!";
        }

        public function onEnter():void
        {
            button.label.text = "You touched me!";
        }

        public function onExit():void
        {
            button.label.text = "You stopped touching me!";
        }
    }
}

(you'll notice we moved our button to the centre and made it bigger as well).

We've finished fiddling with some components now. But we have not met all the components we have available yet. Let's meet the complex ones.

Radio buttons

Radio buttons are a little more complex than the rest, because they need an special thing to operate. As you can only have one radio button selected at a time, they need to know which group they are in to disable the others when they are selected.

Punk.UI provides us the elements needed for grouping radio buttons: we add them as usual, but before that, we create a RadioButtonGroup. Let's see how we'll make this:

package
{
    import net.flashpunk.World;

    import punk.ui.PunkButton;
    import punk.ui.PunkLabel;
    import punk.ui.PunkPasswordField;
    import punk.ui.PunkRadioButton;
    import punk.ui.PunkRadioButtonGroup;
    import punk.ui.PunkTextArea;
    import punk.ui.PunkTextField;
    import punk.ui.PunkToggleButton;

    public class Tutorial extends World
    {
        public var button:PunkButton;

        public function Tutorial()
        {
            super();

            button = new PunkButton(170, 300, 300, 140, "Press me");
            button.setCallbacks(onReleased, onPressed, onEnter, onExit);
            add(button);
            add(new PunkToggleButton(10, 40, 100, 25, false, "Toggle me"));
            add(new PunkLabel("Read me", 125, 10));
            add(new PunkTextField("Write something", 125, 40, 200));
            add(new PunkPasswordField(125, 70, 200));
            add(new PunkTextArea("You could write a book here!", 330, 10, 300, 228));

            var group:PunkRadioButtonGroup = new PunkRadioButtonGroup;
            add(new PunkRadioButton(group, "", 10, 70, 100, 25, true, "Select me!"));
            add(new PunkRadioButton(group, "", 10, 100, 100, 25, false, "Select me!"));
            add(new PunkRadioButton(group, "", 10, 130, 100, 25, false, "Select me!"));
        }

        public function onReleased():void
        {
            button.label.text = "You released me!";
        }

        public function onPressed():void
        {
            button.label.text = "You pressed me!";
        }

        public function onEnter():void
        {
            button.label.text = "You touched me!";
        }

        public function onExit():void
        {
            button.label.text = "You stopped touching me!";
        }
    }
}

As you'll notice, we've added 3 radio buttons. And when we select a radio button, the other ones of the same group are deselected. Neat!

On RadioButtons, we can add callbacks to the radio button as normal, adding a new onChange function for the radio button when it's selected/unselected, by user interaction or not, and we can also add a callback on the group, which will gives us the id of the button which was selected. Great!

Panels and Windows

So you want to add components inside other components, huh? Great then, Punk.UI can do that, using PunkPanel and PunkWindow classes!

It is very important to remember that, at the moment, Panels can't be nested. That is, you cannot add Panels or Windows to other Panels or Windows. That's planned for the future.

Components inside Panel and Windows have their positions updated automatically. So, if you create a PunkButton at x = 10, and a Panel at x = 10 as well, and add that button to the panel, button will be at the absolute x of 20. Normal x/y properties will give you absolute coordinates on World. Setting them will also move them in an absolute way (if we set PunkButton to 15, it would be at the absolute coordinate of 15 instead of at 25), although moving panels will update components position normally. To get or to set relative coordinates, we can use relativeX and relativeY properties.

Components outside the PunkPanel hitbox will be hidden or partly hidden.

PunkWindow differ from PunkPanels on that they are skinable, that they have a label (as a window caption), and that the user can drag them (although we can set draggable to false). PunkWindow extends PunkPanel.

Hotkeys

Let's say we have a mute music checkbox for our cool game, and we want to let users to mute the game pressing the M key as well. Or we have a form and we want to submit it using the Enter key. We can do that easily using the hotkey property of buttons and classes which extend button. You just give an integer to it (you could use the FlashPunk Key class for easy reference, very useful).

At the future, we will have multiple hotkeys with AND and OR possibilities (we could have Control+Something hotkeys, for example).

Skins

Every PunkUIComponent is skinnable (except PunkPanel), which means you can provide them some images (an image for each state of PunkButton –normal, moused, down, inactive–, for example) and some label properties (if they have one).

Each skin is a class which extends PunkSkin. You can change the global skin (already created PunkUIComponents will NOT update their skin if the global skin is changed, changes will be only applied to new PunkUIComponents) by using the PunkUI.skin property.

The default skin is called YellowAfterlife. There's another skin included, which is called RolpegeBlue. You can try changing to that skin using:

PunkUI.skin = new RolpegeBlue;

After typing that, create a new component. You'll see it has a different skin!

You can also provide an individual skin for each component on creation, using their skin parameter on the constructor.

Creating a new skin is a little more advanced topic that won't be covered on this tutorial. You can read the Creating a Skin tutorial if you're interested on that.

Furthermore, if you really want to costumise the component, you'll have to set their graphics properties to whatever you want by extending them. That shouldn't be needed generally.

Where to go from here?

You can read more advanced tutorials on the wiki: Home.

TODO

  • Correct English. Are more/less explanation needed? Correct.
  • If needed, are more examples.
Something went wrong with that request. Please try again.