Introduction into using EZGUI with PIXI.js
PUBLISHED
Introduction
The EZGUI library is a tool designed to create graphical user interfaces for games and applications created with PIXI.js. EZGUI is still a work in progress, so many things can change until the final release. However it's worth writing about it. EZGUI offers such components like:
- Window
- Layout
- Button
- Label
- Checkbox
- Radio
- Slider
- List
- Input
You can also choose one of predefined themes or create your own.
Prerequisites
Before trying to use EZGUI, we have to deal with one issue that is caused by the wrong interpretation of the status code in the XMLHttpRequest object. Where the status code should be 200 and its actual value now is 0. This value is interpreted as an error in the EZGUI library. Let's make a little fix.
// The fix.js file.
EZGUI.utils.loadJSON = function(url, cb, crossOrigin) {
if (crossOrigin === void 0) {
crossOrigin = true;
}
var xmlhttp = new XMLHttpRequest();
xmlhttp.onreadystatechange = function() {
if (xmlhttp.readyState == 4) {
var jsonContent = JSON.parse(xmlhttp.responseText);
cb(jsonContent);
}
};
xmlhttp.open('GET', url, crossOrigin);
xmlhttp.send();
};
EZGUI.utils.loadXML = function loadXML(url, cb, crossOrigin) {
if (crossOrigin === void 0) {
crossOrigin = true;
}
var xmlhttp = new XMLHttpRequest();
xmlhttp.onreadystatechange = function() {
if (xmlhttp.readyState == 4) {
var xmlDoc;
if (window['DOMParser']) {
var parser = new DOMParser();
xmlDoc = parser.parseFromString(xmlhttp.responseText, 'text/xml');
} else {
xmlDoc = new ActiveXObject('Microsoft.XMLDOM');
xmlDoc.async = false;
xmlDoc.loadXML(xmlhttp.responseText);
}
cb(xmlDoc);
}
};
xmlhttp.open('GET', url, crossOrigin);
xmlhttp.send();
};The code above will fix this issue. We have just removed the checking of the xmlhttp.status code.
We can download the newest version of the EZGUI library from this repository file. You also have to download all the assets to properly display themes. In fact, the best way of doing it is downloading the entire repository and removing unnecessary files (like the examples directory).
The next thing is to include EZGUI and our fix in the document's head section.
<html>
<head>
<!-- ... -->
<script src="js/pixi.js"></script>
<script src="js/EZGUI.js"></script>
<script src="js/fix.js"></script>
</head>
<body>
<!-- ... -->
</body>
</html>As you can see JavaScript files have been put in the js directory in the main project's directory. The same thing we do with the assets. We place them in the assets folder in the main project's directory. Thanks to it all the dependencies will be loaded correctly.
Usage
The first thing we have to do when working with the EZGUI library is loading a theme that we want to use in our UI. We do it using the EZGUI.Theme.load function. Here is the example of using it.
EZGUI.Theme.load(['assets/metalworks-theme/metalworks-theme.json'], function() {
/* Do something after loading theme */
});In the callback function, we can create the GUI elements and add them to the stage.
var screen = EZGUI.create(screenJson, 'metalworks'); // Stage is the PIXI.Container. stage.addChild(screen);
As you can see we use the EZGUI.create method to create new UI elements. It takes a component definition as the first parameter and the theme name as the second. Returned element is the PIXI.DisplayObject object which we can use and add to the stage.
One thing needs explanation here. What is the screenJson object? It's a component description in the JSON format. In fact creating a UI in EZGUI is mostly related with defining component's JSON definition. Let's see how a sample JSON description can look like.
var screenJson = {
id: 'mainmenu',
component: 'Window',
header: {
position: {
x: 0,
y: 0
},
height: 40,
text: 'Main Menu'
},
draggable: true,
position: {
x: 0,
y: 0
},
width: 400,
height: 500,
layout: [1, 3],
children: [{
id: 'newgame',
component: 'Button',
position: 'center',
text: 'New Game',
width: 200,
height: 100
}, {
id: 'settings',
component: 'Button',
position: 'center',
text: 'Settings',
width: 200,
height: 100
}, {
id: 'exit',
component: 'Button',
position: 'center',
text: 'Exit',
width: 200,
height: 100
}]
};There are a few attributes that we will focus on. The first one is id. Elements defined with the id attribute can be easily referenced.
EZGUI.components.mainmenu
The next thing is the component type. We can choose one of the previously mentioned components.
In the window component we can also define a header, its height and title.
Of course, each component has its position and size. That's what position, width and height attributes are for.
Now we can go to the layout definition. All layouts in EZGUI are based on a grid. We provide an array with two numerical values where the first one is the number of components in the horizontal axis and the second is the number of components in the vertical axis.
Events
We can attach events to the components. Of course, the most often used event will be the click event. To register an event listener just use the on method.
EZGUI.components.button.on('click', function() {
alert('Clicked!');
});You can use other events defined in PIXI.js like mousedown, mouseup, mousemove, mouseout,
Animations
EZGUI also offers possibility to animate UI elements. We can for example make a fancy slide between two windows of the menu screens. For that purpose we have two animation functions: animatePosTo and animateSizeTo. As you can guess the first one is used to animate element position and the second one to animate the size. It's worth mentioning that changing component's size doesn't recalculate the layout, it just scales elements using the standard PIXI.js scale() function. So its main purpose is in windows/components transformation, when navigating in the menu.
Both functions take the same set of arguments.
EZGUI.componens.window.animatePosTo(x, y, time, easing, callback); EZGUI.componens.window.animateSizeTo(width, height, time, easing, callback);
But the first two in the animatePosTo are a new element's position and in the animateSizeTo are a new element's size. The third argument is the time of the animation in milliseconds. The next one is an easing function from the EZGUI.Easing object. Most of the easing functions comes in three variants In, Out, InOut. The last argument is a callback function that will get called after the animation completion. Let's take a look at the example usage of the animation functions.
EZGUI.components.button.on('click', function() {
EZGUI.components.window.animatePosTo(-500, 0, 500, EZGUI.Easing.Cubic.In, function() {
EZGUI.components.window.visible = false;
EZGUI.components.secondWindow.visible = true;
});
});As you can see in the example above, after clicking the button we animate our window out of the screen and show the second one. Of course, we should also animate the second window.
Summary
We will follow the development of the EZGUI library and post information about any future major releases. It's definitely worth using in your project and you should give it a try.