Defining core functions

You must define five functions in the component class file: the constructor, init(), createChildren(), draw(), and size(). When a component extends UIComponent, functions in the class file are called in the following order:

• Constructor
• init()

  Once init() is called, the width and height properties are set.

• createChildren()

  A frame passes in the Timeline. During this time, the component user can call methods and properties to set up the component.

• draw()
• The size() method is called whenever a component is resized at runtime.

Defining the constructor function

You can recognize a constructor because it has the same name as the component class. For example, the following code shows the ScrollBar component's constructor function:

function ScrollBar() {
}

In this case, when a new scroll bar is instantiated, the ScrollBar() constructor is called.

Generally, component constructors should be empty. Setting properties in constructors can sometimes lead to overwriting default values, depending on the order of initialization calls.

If your component extends UIComponent or UIObject, Flash automatically calls init(), createChildren(), and size() methods and you can leave your constructor function empty, as shown here:

class MyComponent extends UIComponent{
   ...
   // this is the constructor function
   function MyComponent(){
   }
}

All version 2 components should define an init() function that is called after the constructor has been called. You should place the initialization code in the component's init() function. For more information, see Defining the init() method.

If your component extends MovieClip, you may want to call an init() method, a createChildren() method, and a method that lays out your component from the constructor function, as shown here:

class MyComponent extends MovieClip{
   ...
   function MyComponent(){
      init()
   }

   function init():Void{
      init();
      createChildren();
      layout();
  }
   ...
}

For more information about constructors, see "Constructor functions" in Using ActionScript in Flash.

Defining the init() method

Flash calls the init() method when the class is created. This method is called once when a component is instantiated and never again.

You should use the init() method to do the following:

• Call super.init().

  This is required.

• Make the boundingBox_mc invisible.

  boundingBox_mc.width = 0;
  boundingBox_mc.height = 0;
  boundingBox_mc.visible = false;
  

• Create instance member variables.

The width, height, and clip parameters are properly set only after this method is called.

The init() method is called from UIObject's constructor, so the flow of control climbs up the chain of constructors until it reaches UIObject. UIObject's constructor calls the init() method that is defined on lowest subclass. Each implementation of init() should call super.init() so that its base class can finish initializing. If you implement an init() method and you don't call super.init(), the ()init method is not called on any of the base classes, so they might never be in a usable state.

Defining the createChildren() method

Components implement the createChildren() method to create subobjects (such as other components) in the component. Rather than calling the subobject's constructor in the createChildren() method, call createClassObject() or createObject() to instantiate a subobject of your component.

It's a good idea to call size() within the createChildren() method to make sure all children are set to the correct size initially. Also, call invalidate() within the createChildren() method to refresh the screen. (For more information, see About invalidation.)

The createClassObject() method has the following syntax:

createClassObject(className, instanceName, depth, initObject)

The following table describes the parameters:

To call createClassObject(), you must know what the children are, because you must specify the name and type of the object, plus any initialization parameters in the call to createClassObject().

The following example calls createClassObject() to create a new Button object for use inside a component:

up_mc.createClassObject(mx.controls.Button, "submit_btn", 1);

You set properties in the call to createClassObject() by adding them as part of the initObject parameter. The following example sets the value of the label property:

form.createClassObject(mx.controls.CheckBox, "cb", 0, {label:"Check this"});

The following example creates TextInput and SimpleButton components:

function createChildren():Void {
   if (text_mc == undefined)
      createClassObject(TextInput, "text_mc", 0, { preferredWidth: 80,    editable:false });
      text_mc.addEventListener("change", this);
      text_mc.addEventListener("focusOut", this);

   if (mode_mc == undefined)
      createClassObject(SimpleButton, "mode_mc", 1, { falseUpSkin: modeUpSkinName, falseOverSkin: modeOverSkinName, falseDownSkin: modeDownSkinName });
   mode_mc.addEventListener("click", this);
   size()
   invalidate()
}

Defining the draw() method

You can write code in the draw() method to create or modify visual elements of a component. In other words, in the draw() method, a component draws itself to match its state variables. Since the last draw() call, multiple properties or methods may have been called, and you should try to account for all of them in the body of draw().

However, you should not call the draw() method directly. Instead, call the invalidate() method so that calls to draw() can be queued and handled in a batch. This approach increases efficiency and centralizes code. (For more information, see About invalidation.)

Inside the draw() method, you can use calls to the Flash drawing API to draw borders, rules, and other graphical elements. You can also set property values and call methods. You can also call the clear() method, which removes the visible objects.

In the following example from the Dial component (see Building your first component), the draw() method sets the rotation of the needle to the value property:

   function draw():Void {
      super.draw();
      dial.needle._rotation = value;
   }

Defining the size() method

When a component is resized at runtime using the componentInstance.setSize() method, the size() function is invoked and passed width and height properties. You can use the size() method in the component's class file to lay out the contents of the component.

At a minimum, the size() method should call the superclass's size() method (super.size()).

In the following example from the Dial component (see Building your first component), the size() method uses the width and height parameters to resize the dial movie clip:

   function size():Void {
      super.size();
      dial._width  = width;
      dial._height = height;
      invalidate();
   }

Call the invalidate() method inside the size() method to tag the component for redraw instead of calling the draw() method directly. For more information, see About invalidation.

About invalidation

Macromedia recommends that a component not update itself immediately in most cases, but that it instead should save a copy of the new property value, set a flag indicating what is changed, and call the invalidate() method. (This method indicates that just the visuals for the object have changed, but size and position of subobjects have not changed. This method calls the draw() method.)

You must call an invalidation method at least once during the instantiation of your component. The most common place for you to do this is in the createChildren() or layoutChildren() methods.

Comments

Add Comment

Krxtopher said on Nov 3, 2004 at 12:25 PM :

After re-reading the entry, it appears that the code I sited should actually be changed to this:

<code>

class MyComponent extends MovieClip{
...
function MyComponent(){
init()
}

function init():Void{
super.init();
createChildren();
layout();
}
...
}

</code>

jepo said on Nov 24, 2004 at 2:10 PM :

I have confirmed and fixed the source file. Thanks!

hcampbell said on Dec 23, 2004 at 10:42 PM :

It seems that from within the size() function, the height and width variables refer to the size of a rectangle containing the component, not the actual size of the component. This is fine until the component is rotated. Try rotating any of the standard UI components and you'll see that they cannot draw themselves properly.

Anyone know of a good way to get around this? I'm creating a component that I need to be able to rotate. Thanks.

jepo said on Jun 9, 2005 at 2:31 PM :

Thank you for your comments. This site is for documentation feedback only. Some comments with general questions about how to use components, bug reports, or feature requests for the Flash product, have been removed. Please use the Flash webforums for questions about how to use components: http://webforums.macromedia.com/flash. Please use this form for feature requests or suspected bugs: www.macromedia.com/support/email/wishform/.

No screen name said on Aug 5, 2005 at 4:40 PM :

in the explanation for defining the init() method, shouldn't there be underscores in the boundinBox_mc property names?

boundingBox_mc.width = 0;
boundingBox_mc.height = 0;
boundingBox_mc.visible = false

should be:

boundingBox_mc._width = 0;
boundingBox_mc._height = 0;
boundingBox_mc._visible = false

HedgePedge said on Oct 27, 2005 at 1:28 PM :

this is incredible once you get the hang of it
(I wish i got the hang of it earlier)

RSS feed | Send me an e-mail when comments are added to this page | Comment Report

Current page: http://livedocs.adobe.com/flash/mx2004/main_7_2/00003104.html

Add Comment