A UI Canvas API for the gEngine.
This document covers the proposed API used for our final project, as well as documentation of the exposed functionality our game engine will provide to users with detailed implementation instructions.
The UI Canvas API provides centralized support for the game designer to access UI controls such as buttons, sliders, toggles, ect. Currently in gEngine, ‘UI’ objects need to be created using renderables and would need new individual behaviors for each different type of object. Our UI Canvas API allows for a modular and easy way to combine all UI into one simple package.
Table of Contents
1.0 - 20210315 API Demo
TODO script install
Or, to install the API manuall:
index.html for your project:<!-- API Scripts -->
<script src="src/canvasUI/utilities.js"></script>
<script src="src/canvasUI/canvas/UIcanvas.js"></script>
<script src="src/canvasUI/canvas/UIcanvasUpdate.js"></script>
<script src="src/canvasUI/canvas/UIcanvasCreate.js"></script>
<script src="src/canvasUI/canvas/UIcanvasEditMode.js"></script>
<script src="src/canvasUI/events/UIEvent.js"></script>
<script src="src/canvasUI/events/UIEventHandler.js"></script>
<script src="src/canvasUI/elements/UIelement.js"></script>
<script src="src/canvasUI/elements/UIButton.js"></script>
<script src="src/canvasUI/elements/UISlider.js"></script>
<script src="src/canvasUI/elements/UIDropdown.js"></script>
<script src="src/canvasUI/elements/UIToggle.js"></script>
A UI canvas is an overlay of the main document with objects that display information and allow the user to interact with objects in the scene with out explicitly referencing the object themselves. It requires no arguements.
A sample implement looks like the following:
MyGame::Initialize()
this.UI = new UIcanvas();
MyGame::Draw()
this.UI.Draw();
MyGame::Update()
this.UI.update();
Currently, the UI Canvas API supports four (4) elements:
To add an element to the UI canvas, call the CreateElement() function. The CreateElement() function can take unlimited arguments, but will throw an error if an invalid combination of arguments is given.
See below for details on valid arguments for each UI element type. When calling CreateElement(), the first argument is always the type as defined by the UI Canvas.
A UI element button is a standard button that can be clicked in order to trigger an event.
Argument list: type, size, position, color, text.
A sample implement looks like the following:
this.UI.CreateElement(this.UI.UIELEM_TYPES.Button, [50,20],
[20,60], [1,1,1,1], "Button");
A UI element slider can be moved between a minimum and maximum value. When a change to the slider value occurs, a callback is sent to any registered listeners of Slider.onValueChanged.
Argument list: type, size, position, range, default value, step increment.
A sample implement looks like the following:
this.UI.CreateElement(this.UI.UIELEM_TYPES.Slider ,[50,5],
[60, 5], [-100, 100], 0, 1);
A UI element toggle is a checkbox that allows the user to switch an option on or off.
Argument list: type, size, position, text
A sample implement looks like the following:
this.UI.CreateElement(this.UI.UIELEM_TYPES.Toggle, [20,20],
[-50, 10], "Toggle");
A UI element dropdown presents a list of options when clicked, of which one can be chosen. When a dropdown event occurs a callback is sent to any registered listeners of onValueChanged.
Argument list: type, size, position, color, text.
A sample implement looks like the following:
this.UI.CreateElement(this.UI.UIELEM_TYPES.Dropdown, [50,20],
[100,75], [1,1,1,1], "Sprite", opts);
UI Events are a special kind of multicast delegate that can only be invoked from within the class where they are declared (the publisher class). If other classes subscribe to the event, their event handler methods will be called when the publisher class raises the event.
UI Events can:
Pass values when invoked.
this.onValueChange.Invoke(this.eSliderValue.toFixed(this.decimalPlaces));
This invoke will pass the slider value to all of the handlers subscribed to the event.
Utilize a static value passed when the listener was created.
this.onClick.Invoke();
This invoke will use the value set when the listener was created.
The value used by the handler is determined in the event when invoked. As the event executes the listener, it checks the value associated with the same index. If the value is null, the value is taken from the default arguments.
UIEvent.prototype.Invoke = function(){
for (var i = 0; i < this.listeners.length; i++) {
var val = (this.values[i] === null)? arguments[0] : this.values[i];
this.listeners[i](val);
}
};
Argument list: function, handler, value
A sample implement looks like the following:
this.UI.UIElements[0].AddListener(this.UI.UIElements[1].SetValue, this.UI.UIElements[1], 50);
This line of code will add an event listener to the object stored in UIElements[0]. The function associated with the event handler is this.UI.UIElements[1].SetValue and the object it is called from on being invoked is this.UI.UIElements[1]. Additionally, when subscribing a handler to an event, a value can be associated with that listener. If a value is not passed, it will use the default arguments passed by the function when it is invoked.
A collection of global helper functions used throughout the API.