Soundstep

BaseUI tutorial

| 5 min read

Click here to access to the demo and source.

This is a tutorial to explain you what you can do with BaseUI. It will not build a website for you (not yet :)) but should reduce your efforts by handling basic and common rules in a flash site, such as position, margin and resize of a DisplayObject.

I didn't test all the DisplayObject subclasses, so you might find funny results if a subclass is not working as expected. BaseUI is a young class I'm using for my own project and obviously needs debugging, more testing and improvement.

Let's get started.

Creating a BaseUI instance

BaseUI extends EventDispatcher and is basically managing a list of DisplayObject and a list of DisplayObject to render (I mean render by changing the position and the size).

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. As you can see in the demo, the central window is a Sprite with its own BaseUI instance.

Example in the main class (which is extending Sprite or MovieClip):

 import com.soundstep.ui.\* var baseUI:BaseUI = new BaseUI(this);

Adding Elements as ElementUI

Now that we have our instance, we can start to add a DisplayObject in the list. BaseUI has 3 public methods: addElement, removeElement and getElement.

You can get an array of the elements added with the elements property of the BaseUI instance:

var allElements:Array = baseUI.elements;

The addElement will return an instance of the ElementUI class. This instance has the properties needed to handle the behavior of the DisplayObject.

var element:ElementUI = baseUI.addElement(mySprite);

This action add the DisplayObject to the BaseUI list and when you will add the sprite to the display list by using addChild(mySprite), the DisplayObject will be automatically added to the list-to-render in the BaseUI class, and then apply the rules set in the ElementUI instance.

You can get the ElementUI created like this:

var element:ElementUI = baseUI.getElement(mySprite);

You can remove an element from the list like this:

baseUI.removeElement(mySprite);

Note: If you remove the DisplayObject from the display list using removeChild(mySprite), the BaseUI removes the element from the list-to-render but the element is still listed in the BaseUI instance until you use the removeElement method. It means you can remove a child from the display list and add it again, the BaseUI will still apply the rules you have set to this element.

Type of an ElementUI

An ElementUI instance can be two types: element that is the default one and background. Some rules are common and some others are only working with a certain type. The class will throw an error if you try to do something wrong.

You can set the type when you add the element to the BaseUI instance or later.

Add a DisplayObject type element:

var element:ElementUI = baseUI.addElement(mySprite);

or

var element:ElementUI = baseUI.addElement(mySprite, ElementUI.TYPE\_ELEMENT);

Add a DisplayObject type background:

var element:ElementUI = baseUI.addElement(mySprite, ElementUI.TYPE\_BACKGROUND);

Change the type of an element:

 element.type = ElementUI.TYPE\_ELEMENT; element.type = ElementUI.TYPE\_BACKGROUND;

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 margin top, 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.

In the demo, the property onStage of the ElementUI in the Window are set to false because I want them to react with the window Sprite (DisplayObject reference), not the stage.

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. The central window in the demo is working like that, 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.

Note: at the moment the type background is not working with a property onstage set to false, probably a further development.

Alignment

The alignment is a common property for both types, you can align an ElementUI to top, bottom, left, right and center. You have to set your alignment to an axis. The following example aligns an ElementUI to the right and the bottom of the DisplayObject reference:

 element.alignX = ElementUI.ALIGN\_RIGHT; element.alignY = ElementUI.ALIGN\_BOTTOM;

Here is the list of the alignment

 element.alignX = ElementUI.ALIGN\_LEFT; element.alignX = ElementUI.ALIGN\_CENTER; element.alignX = ElementUI.ALIGN\_RIGHT; element.alignY = ElementUI.ALIGN\_TOP; element.alignY = ElementUI.ALIGN\_CENTER; element.alignY = ElementUI.ALIGN\_BOTTOM;

From the version 1.1.0 you can set the horizontal and vertical alignment when the element is centered.

 element.horizontalAlign = 100; element.verticalAlign = -80;

Margin

The margin is also a common property for both types. Here is an example how to set a 10 pixels margin around a DisplayObject:

element.margin = 10;

You can set the margin only on a side, here is a list of the properties:

 element.marginLeft = 10; element.marginRight = 10; element.marginTop = 10; element.marginBottom = 10;

The margin property can also accept an Object:

element.margin = {left:10, right:20, top:10, bottom:20};

Type background

This type can be used for a background or a slideshow for example. It has a specific property mode that is resizing a DisplayObject to fit the DisplayObject reference. When a picture or a video is resized, I strongly recommend using the smoothing property like this:

 var bg:Bitmap = new Bitmap(new MyBitmap(0,0), PixelSnapping.AUTO, true); var element:ElementUI = baseUI.addElement(bg, ElementUI.TYPE\_BACKGROUND); element.mode = ElementUI.RATIO\_OUT; addChild(bg);

The three mode of the type background are ratio in, ratio out and ratio fit. Test the demo and see the behaviour of the different mode. You can use the alignment and margin with the mode.

The mode ratio fit is fitting the DisplayObject reference with the DisplayObject without keeping the ratio.

The mode ratio in is fitting the DisplayObject reference with the DisplayObject, keeping the ratio and you will always see the whole DisplayObject.

The mode ratio out is fitting the DisplayObject reference with the DisplayObject, keeping the ratio and you will always miss a part of the DisplayObject depending of the alignment.

Here is the syntax to set the mode:

 element.mode = ElementUI.RATIO\_FIT; element.mode = ElementUI.RATIO\_IN; element.mode = ElementUI.RATIO\_OUT;

Type Element

The type element has a property resizeOption. You can choose to resize the DisplayObject to fit the area in the width or the height. You can still use the margin and the alignment. It is useful for example to draw a line. Here is the syntax:

 element.resizeOption = ElementUI.OPTION\_ELEMENT\_WIDTH; element.resizeOption = ElementUI.OPTION\_ELEMENT\_HEIGHT;

Example:

 var lineAboveFooter:Sprite = new Sprite(); lineAboveFooter.graphics.beginFill(0xFF0000); lineAboveFooter.graphics.drawRect(0, 0, 10, 1); var element:ElementUI = baseUI.addElement(lineAboveFooter); element.alignY = ElementUI.ALIGN\_BOTTOM; element.margin = {left:20, right:20, bottom:30}; element.resizeOption = ElementUI.OPTION\_ELEMENT\_WIDTH; addChild(lineAboveFooter);

This example will resize your Sprite to fit the DisplayObject reference, align it at 30 pixels from the bottom with a margin left and right of 20 pixels.

Note: For this example, use the drawRect with height 1 pixel as the drawLine method wasn't behaving as expected.

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. They are private property but it might change to public in further development.

This size is used to calculate the ratio of the mode for example.

An ElementUI instance has a property useInitialSize set by default to false, you can change it to true when you want the behaviour 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.

If you have an unexpected behaviour, if you find bugs or if you have ideas to improve BaseUI, just contact me.

I hope it helps.