Clickable Button Panel Primitive

October 27, 2008


Custom primitives are unexplored territory in Papervision. And they pack a big punch. To illustrate the point, consider the following custom clickable button panel primitive. From the image below you see 8 planes in two rows. Typically you rez planes on the stage one at a time and keep track of them individually as they rotate.

But with a custom primitive it’s all one primitive, which reduces the number of primitives you have to keep track of to one.

Click the image below to see a demo.

Clickable Custom Button Panel

Clickable Custom Button Panel

In the demo above, when you click on a plane a URL is brought up in the browser. Each plane calls a different URL.

Even cooler – you have total control over the number of rows, columns and spacing. The custom primitive is called


You place it in the primitives folder and rez it to the state the same way you would any other primitive and adjust its properties in the same way as well.

The primitive function look like this

MultMatPlane( materials:MaterialsList, myGap:Number=0,horizNum:int=1, vertiNum:int=1, width:Number=0, height:Number=0, segmentsW:Number=0, segmentsH:Number=0, initObject:Object=null )

The adjustable parameters are

  • materials
  • gap
  • column number
  • row number
  • image width
  • image height
  • width segments
  • height segments

Of course the important part in changing row and column parameter is to have the materials labeled correctly in the materials list. If the materials aren’t in the materials list – you won’t see them. That makes sense, but I’ve already made the mistake 100 times. And you should probably know about it. More on how this works below.

Note of Caution

One more thing – late last night this primitive didn’t like my Firefox pop up blocker (well at least not at 2 o’clock in the morning) – so keep an eye on that!

Any primitive as new as this one has to go through a few cycles of work to make sure it is fully functional for web use; this one has not been through those cycles yet!!! But it is being used successfully on a website – which is encouraging. The purpose of this tutorial is to demystify how such primitives are built – not beat all the bugs out. That comes with time and use.

Web Stuff



(Download from the list)


How it was made

Building this primitive was really easy. Here are the steps and stuff to look out for:

  1. Make a copy of the plane primitive and rename its class and constructor function to MultMatPlane (or whatever you want to call it)
  2. In the public class MultMatPlane, add the new properties that you need such as row number, column number, materials, … whatever you want.
  3. Then make sure those variables are carried over in your constructor function.
  4. Open up the cube primitive and see how the different sides were made. You will need to follow the same pattern, but generalize it for multisides and different geometries.
  5. After porting the cube code that you need, create and call the buildMultiPlane function – this is the heart of your class. It iterates through your column and row sizes placing them on the screen, shown below:

private function buildMultiPlane(myGap:Number, horizNum:Number, vertiNum:Number, width:Number, height:Number ):void

for(var n:int=0; n <vertiNum; n++){

for(var m:int=0; m <horizNum; m++){

var myMaterial:String = “myMat”+””+n+””+m;


buildPlane( myMaterial, myGap, m, n, horizNum, vertiNum, width, height) ;

5. Keep the code very similar to the cube code port, only replace all u variables with x variables and v variables with y variables.

6. And here is the big trick. Replace the plane vertices.push( new Vertex3D( x, y, 0 ) ) with the cube primitive technique for dealing with vertices as shown below. Make sure you put x in for u and y in for v.

var vertex:Vertex3D = new Vertex3D();

vertex[ “x” ] = x;
vertex[ “y” ] = y;
vertex[ “z” ] = 0;

vertices.push( vertex );
planeVerts.push( vertex );

And that is pretty much it! A little bit of work here, but now you are set up to do so much more. Like make single primitive carousels, images balls, and terrains. An all-in-one primitive. How cool is that?

Material List

So how do your get different images on the different planes in your custom primitive?

Use a materials list!

Here is an example of such a list from your main code:

var materialsList:MaterialsList = new MaterialsList();
materialsList.addMaterial(myBitmapFileMaterial00, “myMat00”);
materialsList.addMaterial(myBitmapFileMaterial01, “myMat01”);
materialsList.addMaterial(myBitmapFileMaterial02, “myMat02”);
materialsList.addMaterial(myBitmapFileMaterial03, “myMat03”);
materialsList.addMaterial(myBitmapFileMaterial10, “myMat10”);
materialsList.addMaterial(myBitmapFileMaterial11, “myMat11”);
materialsList.addMaterial(myBitmapFileMaterial12, “myMat12”);
materialsList.addMaterial(myBitmapFileMaterial13, “myMat13”);

The big thing was coming up with a naming conventions. For the cube it is top, right, left, top,…

But in this case I just numbered them by row and column, where myMatt00 is the lower left most button.


Making the plane interactive is not difficult. Give each of your materials a name and use a switch case to call that name when a plane is clicked on:

Name it like this! = “myMat00”;

Call it like this!

case “myMat00”:
navigateToURL(new URLRequest(“;), “_blank”);
}// end case …

That’s pretty much it! To check out the rest of the code by downloading it from the link above. And the MultMatPlane code is given below.

MultMatPlane Code

Get the MultMatPlane code under the more tab below. Note: The code is not fully documented. I’ll take care of that before the book comes out.

Read the rest of this entry »