BaseUI v2 tutorial
Posted by: Romuald in BaseUI, tags: as3, BaseUI, class, flash, liquid layout, liquid UI, tutorialBaseUI will help you to manage your assets (a logo, footer, a menu, etc) in the browser, in a liquid layout or a fixed area.
BaseUI is managing a list of DisplayObject like Sprite, MovieClip, TextField, Bitmap, etc. You will be able to use properties like top, bottom, left, right, horizontalCenter, verticalCenter, width and height even with percentage, some ratio mode for backgrounds and other specific properties.
Here is the BaseUI main page to see the demo, the documentation and download the source.
BaseUI instance
BaseUI is not a Singleton, you can create as many instance as you wish.
Usually, I'm creating a main BaseUI instance in the main class, the entry point, to manage most of my elements. Example in the main class (which is extending Sprite or MovieClip):
-
var baseUI:BaseUI = new BaseUI(this);
BaseUI will refresh the position and size of your DisplayObject when the Event.RESIZE will trigger.
You can now add some DisplayObject to your list; it will return an instance of the ElementUI class:
-
var element1:ElementUI = BaseUI.add(mySprite);
-
var element2:ElementUI = BaseUI.add(myBitmap);
-
var element3:ElementUI = BaseUI.add(myTextField);
The public methods of the BaseUI class are:
-
baseUI.add(mySprite);
-
baseUI.refresh();
-
baseUI.getElement(mySprite);
-
baseUI.remove(mySprite);
-
baseUI.removeAll();
The public properties:
-
var elements:Array = baseUI.elements;
-
var holder:DisplayObjectContainer = baseUI.holder
BaseUI manages 2 lists: a list of DisplayObject and a list of DisplayObject added to the display list. Only the second one will be "refreshed".
BaseUI will trigger 2 events, when you add a DisplayObject to the BaseUI instance and when you remove it:
-
baseUI.addEventListener(BaseEventUI.ADDED, addedHandler);
-
baseUI.addEventListener(BaseEventUI.REMOVED, removedHandler);
Reference to the ElementUI
Before we start to change the size and position of an element, you have to understand on which DisplayObject you align or resize to.
An ElementUI instance has a property onStage, the default is true. It means if you add a 10 pixels top property, it will be 10 pixels from the top of the stage.
When I build a site, I'm using an element (like a logo, a menu, a page, a footer or whatever) like I would do in Photoshop, on a layer that is taking the whole area. That's why the onStage is set to true by default, you can change it like this:
-
element.onStage = false;
By doing this, you tell the Element to react, not with the stage anymore but with the parent DisplayObject. We will call it the DisplayObject reference, so the stage or the parent.
You have to be careful using an onStage property set to false, because it means the DisplayObject reference need to have a size to behave as expected.
For example, in a site, your main area is an invisible rectangle 800x600 (a container) that is always centered in the DisplayObject reference (the stage in my example). You can set the ElementUI onStage property of the DisplayObject in the container to false to make the elements behave as expected.
It means the invisible container will have to have a width and height. Here is a hack to do that:
-
var container:Sprite = new Sprite();
-
container.graphics.beginFil(0xFF0000, 0);
-
container.graphics.drawRect(0, 0, 800, 600);
-
addChild(container);
I draw an invisible rectangle (the alpha is set to 0) in my container to be sure the DisplayObject reference (the container) of my ElementUI has a size, and then make the ElementUI inside behave as expected.
ElementUI properties
When you get the instance of the ElementUI class, you can use its properties, here are some examples:
To align a Sprite 10px from the bottom and right border:
-
element.bottom = 10;
-
element.right = 10;
To center a Sprite:
-
element.horizontalCenter = 0;
-
element.verticalCenter = 0;
To have a Sprite fitting the browser:
-
element.left = 0;
-
element.right = 0;
-
element.top = 0;
-
element.bottom = 0;
You can also set (or get) all the properties in one time, like this:
-
element.properties = {top:10, bottom:10, horizontalCenter:-100};
BaseUI is flexible and will accept Number as well as String for the following properties:
x, y, left, right, top, bottom, width, height, horizontalCenter, verticalCenter
-
element.bottom = 10;
is the same as
-
element.bottom = "10";
For the width and the height, you can also use percentage values:
-
element.width = "80%";
-
element.height = "80%";
In the ElementUI class, they are cases when a property shouldn’t be used, for example if you set a left and right value, the width property is not used anymore. When you do so, the class will memorize the width value in case it will be "turned on" by another property. For example, if you set horizontalCenter to 0, left and right will be memorized and turn on to NaN, the width value will be restored.
Everything is done automatically by the ElementUI class, you don’t have anything to do, see the demo for a better understanding.
You can refer to the documentation for a full list of the properties.
Refresh method
In some case you will have to manually refresh the element, for example if you change the width and the Event.RESIZE won’t be triggered.
You can refresh the element like that:
-
element.refresh();
This will work only if the alpha of the DisplayObject is superior to 0 and the visible property is set to true. Otherwise, you will have to force the refresh:
-
element.forceRefresh();
The ElementUI class dispatches an updated event when the Element has been refreshed, you can listen to it like that:
-
Element.addEventListener(BaseEventUI.UPDATED, updatedHandler);
To refresh all the elements of the BaseUI class, use:
-
BaseUI.refresh();
Ratio property
As in the precedent version, you can set the ratio property, I guess mainly for a background:
-
element.ratio = ElementUI.RATIO_IN;
-
element.ratio = ElementUI.RATIO_OUT;
See the demo for the different behaviors.
To turn it off, just pass an empty String or whatever you want:
-
element.ratio = "none";
Some properties are bypassed when a ratio has been set as it doesn’t make sense, like width and height. Some others like top, bottom, left and right are still working.
In ratio set to RATIO_OUT, you can use the properties alignX and alignY:
-
element.alignX = ElementUI.ALIGN_CENTER;
-
element.alignY = ElementUI.ALIGN_BOTTOM;
Known issue: if you set the ratio to RATIO_IN or RATIO_OUT with the property onstage set to false, it won’t work properly. Probably a further development will allow it.
Initial Size
When a DisplayObject is added in the BaseUI instance, an ElementUI is created and at this moment, the Element instance is recording the size of the DisplayObject. This is the initialWidth and initialHeight of the DisplayObject
This size is used to calculate the ratio of the DisplayObject for example.
An ElementUI instance has a property useInitialSize set by default to false, you can change it to true when you want the behavior of the ElementUI working with the initial size. It is useful for example when you have a mask in a Sprite that is disturbing the width and height of this Sprite.
Bypass Size
In some case, your DisplayObject will be animated making its size impossible to use. To prevent unexpected behaviors you can set the bypassSize property to false. Only the properties for position will be used.
Keep on screen
By default the property keepOnScreen is set to true (added in 2.0.4). This prevent the top-left corner of the DisplayObject to go off the screen.
Entries (RSS)