Advertisement

Quick Tip: Understanding getDefinitionByName()

by

In this Quick Tip, you'll learn how to construct a reference to a class from a String, and then create an instance of that class, using a built-in AS3 function called getDefinitionByName(). You'll also learn the best methods for using this in different situations.


Why Is getDefinitionByName() Useful?

getDefinitionByName() is very useful if you need to make new instances of classes by using a String. For example, if you had seven different tiles - each represented by a class called Tile1, Tile2, etc - and you needed to create an instance of each, you would have to write the following code:

private function createTiles():void
{
	var tile1:Tile1 = new Tile1();
	var tile2:Tile2 = new Tile2();
	var tile3:Tile3 = new Tile3();
	var tile4:Tile4 = new Tile4();
	var tile5:Tile5 = new Tile5();
	var tile6:Tile6 = new Tile6();
	var tile7:Tile7 = new Tile7();
	stage.addChild( tile1 );
	stage.addChild( tile2 );
	stage.addChild( tile3 );
	// You get the idea, it is very lengthy!
}

getDefinitionByName() allows you to solve this problem!


How to Use It

Now, the above code was a little messy and we had to type many lines just to make a few different tiles. This is how we could achieve the same goal using getDefinitionByName():

private function createTiles():void
{
	for( var i:int = 1; i < 8; i++ )
	{

		var tileRef:Class = getDefinitionByName( "Tile" + i ) as Class;
		var tile:Sprite = new tileRef();
		stage.addChild( tile );

	}
}

In line 6, getDefinitionByName() returns a reference of the class called "Tile + the current value of i in the for-loop". So, when i is equal to 1, getDefinitionByName("Tile" + i); returns a reference to the class Tile1. We then create the tile and add it to the stage.

(We can't write var tile:tileRef because tileRef does not refer to anything at compile time; if you try, you'll get a compiler error.)

However, when you run this code, it will not work! You'll get a variable is undefined error message, in most cases, because "Tile1" might not be enough information for Flash to find the class. Let's look at some workarounds.


Make It Work

There are a few commonly-used methods to solve the problem of the variable is undefined error you'll get when you run the above code, and I am going to teach you what they are. I would also like to give credit to Gert-Jan van der Well of Floorplanner Tech Blog for this blog post.

Here are some of the methods you can use:

  • Use a Dummy Variable
  • Use short notation of Class name
  • Include the full path in the String
  • Include the class's SWC in your project

Using a Dummy Variable

In this method, you just create some dummy variables with references to the classes you want to refer to with getDefinitionByName() later:

private var dummyTile1:Tile1;
private var dummyTile2:Tile2;
//etc

private function createTiles():void
{
	//Create the tiles
}

This works, but it is very ugly. If you have the Tile classes in another package, you would also have to import them!

Short Notation

This is much like the Dummy Variable method, but you don't bother setting up a dummy variable for each class; you just drop a few explicit references to the classes themselves:

Tile1;Tile2;Tile3;Tile4;Tile5;Tile6;Tile7;
//etc

private function createTiles():void
{
	//Create the tiles
}

Now, this may look neater, but the fact that you will have to update this list everytime you make a new Tile remains.

Including the Full Path Name

Another method, which is the tidiest (if you have classes in another package) is to include the full path name in your String:

//Let's say my Tiles are all in the package 'project.Tiles'

private function createTiles():void
{
	for( var i:int = 1; i < 8; i++ )
	{

		var tileRef:Class = getDefinitionByName( "project.Tiles.Tile" + i ) as Class;
		var tile:tileRef = new tileRef();
		stage.addChild( tile );

	}
}

Much tidier! However, this only works if the classes are in a separate package from this class.

Using a SWC

If the Tiles are held in an SWC, you can make this much easier, without needing to use any imports or dummy variables. I would like to give credit to v0id from Dreaming in Flash for this blog post that explained to me how to use this method:

  • In the project properties choose "ActionScript Compiler"
  • To the "Additional compiler arguments" field, add the following: include-libraries PATH_TO_SWC

The PATH_TO_SWC must be the absolute path and not the relative path!

Great, all these methods have now been explained. Unfortunately, there are no fantastic magical methods to use if you have all the tiles in the same package as all the other AS Files. I would recommend you make a new package called Tiles or something if you want to use the good methods!


Conclusion

Well, today you should have learnt how to use getDefinitionByName() and the best methods of using it. I hope this will help you in any future projects and if you have any questions, leave them in the comments section below!

Advertisement