So many widgets, so little time
TwitterFacebookGoogle

Loading Items from the Captivate Library – Part 1

Edit: See part 2 here.

I have finally made a tutorial on loading stuff from the Captivate Library! This is by far the most exciting new feature in Captivate 6 as far as widgets are concerned. Unfortunately in all the time since CP6 was released, I haven’t put up a tutorial on how to do it. So finally the silence is broken! And it is broken in video! Which is a good thing, because technically a blog post is not an audible format, thereby silence would not have been broken that way.

mzmnt~

N-E-WAY, here’s the tutorial.

Hopefully I’ll have part 2 up soon where I explain how you can register which library objects you want to access at runtime.

Till then, happy loading from the library!

Using the WidgetDebugger Class

For a long time I’ve been meaning to write about the WidgetDebugger class. It was introduced in WidgetFactory 5.5 and is extremely useful for using third party debugging tools to test your widgets.

Currently the WidgetDebugger class is only compatible with Arthropod and MonsterDebugger. You must also have them installed and their connecting classes set up before they can be used. You can find information about how to do that on the debugger’s websites.

Step 1

In your widget’s document class (the class that extends StaticWidget, InteractiveWidget, QuestionWidget or Widget) import the WidgetDebugger class and either the WidgetMonsterDebugger or the WidgetArthropodDebugger class.

1
2
3
import widgetfactory.logging.WidgetDebugger;
import widgetfactory.logging.debuggers.WidgetArthropodDebugger;
import widgetfactory.logging.debuggers.WidgetMonsterDebugger;

Step 2

In the document class’ constructor function, write the following if you want to use Arthropod:

1
WidgetDebugger.debugger = new WidgetArthropodDebugger();

On the other hand, if you’d rather use Monster Debugger then write the following.

1
WidgetDebugger.debugger = new WidgetMonsterDebugger(this);

As you may have guessed, this tells the WidgetDebugger tool which debugger you want to use. The handy thing about MonsterDebugger is that it allows you to search through the structure of your swf while it’s running. To do that it needs a reference to the part of your swf that you want to inspect. That’s why when we type ‘new WidgetMonsterDebugger()’ we give it an object to start inspecting. This is a mandatory field.

Step 3

Now go to the part of your code that you want to debug, make sure the WidgetDebugger class is imported into that class (you don’t need to import WidgetMonsterDebugger or WidgetArthropodDebugger again) and then use the various tracing methods to send traces to the debugger app.

1
2
3
4
5
6
7
WidgetDebugger.trace("This method is used for simple vanilla tracing");
WidgetDebugger.log("This method is used to trace your widget's processes");
WidgetDebugger.info("This method is used to trace information. It's sort of like a highlighted log trace");
WidgetDebugger.warn("This method is used to trace warnings. Use it to mark when you might run into problems");
WidgetDebugger.error("This method is used to trace errors. Use it inside try catch statements");
WidgetDebugger.fatal("This method is used to trace REALLY bad errors that break your whole program");
WidgetDebugger.debug("This method is used for temporary traces to assist with debugging");

In truth, the only real difference between these methods is that they appear in different colours inside the debugger app, but a little structure never hurt anyone.

Extras

The WidgetDebugger class also comes with a couple of goodies to assist with debugging.

Clear Traces

1
WidgetDebugger.clearTraces();

If the debugger app allows it, calling this method will wipe all previous traces from the trace list. I often call this right after I set the debugger type in the Widget’s constructor method. This means every time I test the widget, the previous test session’s traces are cleared away.

Filter Traces

WidgetDebugger also has settings that allow you to stop certain types of traces from being sent to the debugger. Here’s how you use them.

1
2
3
4
WidgetDebugger.logging = false; // Stops log() messages from being traced.
WidgetDebugger.information= false; // Stops info() messages from being traced.
WidgetDebugger.warnings= false; // Stops warn() messages from being traced.
WidgetDebugger.widgetFactoryLogging= false; // Stops WidgetFactory's automatic log messages from being traced.

Of course, if you set these properties back to true, these messages will start getting through to the debugger again.

I find it useful to turn off logging, information and WidgetFactory logging when I’m doing debugging. That way I will only see my debug() and error() traces and they don’t get lost in the sea of process logging messages.

Hopefully this will make debugging your widgets easier. Do you have another ActionScript debugger you like using? Leave a comment below about it and I may add compatibility for it in the next version of WidgetFactory.

WidgetFactory 5.5

It’s been a long time coming, and now it’s here…

5 POINT 5 YEEEEEHAAAA!

That’s not to say that WidgetFactory 5.1 wasn’t compatible with Captivate 5.5, but… Yeah.

WidgetFactory 5.5 has many new features, but there are three major ones. I will briefly describe them here, and then in the coming weeks write a post that goes into greater detail for each of them.

Just before I delve in here, I’d like to say that anyone out there who has an Interactive Widget should update to 5.5 as soon as possible. Why? All I can say is… Stay tuned :)

Debugging

Debugging has always been difficult with widgets, because the only true way to test them is to pull them in to Captivate and see how they fare. When a swf leaves the confines of its design environment a lot of its debugging features leave as well.

WidgetFactory 5.5 now has an interface to trace to external debuggers. This interface is focused on delivering the best debug experience for widgets.

If you need information on how to use these features before I write the next article, see the documentation under the WidgetDebugger class.

Communication

Widgets have come a long way since they were released, they are moving past childhood and into the awkward stages of adolescence. Probably no other milestone will be more awkward, or powerful, than communication with other widgets. But do not worry, because WidgetFactory 5.5 is here to ease the awkwardness.

Just a note up front, the communication architecture in 5.5 is not the only way that widgets can communicate with each other. In fact there are many ways that communication can be done. The hope is this architecture will help to establish a standard which will allow different types of widgets (even those created by separate developers) to communicate with each other.

Here’s the concept: There is a ‘room’ and widgets can become ‘members’ of the room. By joining the room, widgets can contact each other and make decisions that take into account all other members of the room. Alternatively, the room itself could become a middle man for its members, it receives requests from widgets and decides which should be acted upon.

WidgetFactory 5.5 provides two types of rooms:

  • Global Rooms: Are available for all widgets to register with, no matter where they are in the movie. (See the BaseRoom class in the documentation)
  • Slide Rooms: Are only open to widgets on a certain slide. (See the BaseSlideRoom class in the documentation)

When your widget creates a room it has to decide what type of object the room will be. A room could be created with the BaseRoom or BaseSlideRoom classes listed above, or a class of your own creation that extends either BaseRoom or BaseSlideRoom.

Anyway, more information on this to come. Until then, the third major feature is…

Runtime Detection

Runtime detection is how a widget detects the Captivate Movie is playing through the time period the widget is supposed to appear. Now this doesn’t sound like such a big deal, but believe me, it is.

The problem is not so much finding a way to detect runtime, but finding a way that doesn’t chew up CPU. It’s a balancing act of accuracy and resources, and with WidgetFactory 5.5 we’ve found that balance. I’ll tell you more about the method in another post. :)

When a widget ‘detects runtime’ it will call the enterRuntime() template method. We’ve all used that one right? (<– I knew this was a mistake the instant I typed it. But I kept it in and wrote this aside instead. Go figure). One thing that always bothered me about the ‘enterRuntime()’ template method was that it had no ’exitRuntime()’ method to balance it out. Well guess what… now there is!

enterRuntime() is called when the Captivate Movie enters the period of time that the widget is set to appear, and exitRuntime() is called when the movie exits that period. This will make things like loading and unloading the widget much easier. In my projects now I find myself using exitRuntime() just as much as enterRuntime().

Now there is one side effect of this new system that may cause a hiccup for certain widgets. Previously, runtime detection was tied into the widget’s visibility. However, with the new system enterRuntime() and exitRuntime() are called regardless of whether the widget is visible or not. Again, I’ll go more into this in a later post.

Everything Else

Besides those features there are a number of small additions:

Features

  • Slide Label features can now be used in all versions of Captivate. However, they still can’t be used when Captivate’s accessibility features are turned off.
  • New property itemName allows you to read the item name the Captivate Author gave the widget (Note: At runtime InteractiveWidgets get a suffix added to the end of their name, which leads me to…).
  • New constant INTERACTIVE_WIDGET_SUFFIX holds the suffix that Captivate slaps on the end of Interactive Widget item names (The suffix is: _iWidgetAS3)
  • Eliminated the need for translatePropertiesXML(). Properties are now translated the first time you access them at runtime.
  • New property isCaptivate4Embedded indicates if the widget is embedded into a Captivate 4 movie (rather than being externalized).
  • Added new WidgetEvent INTERACTIVE_WIDGET_SUBMITTED event which is dispatched when an InteractiveWidget sets success or failure.
  • Added new WidgetEvent RESET_CRITERIA event which is dispatched when an InteractiveWidget calls resetCriteria().
  • Added new property captivateMainTimeline, which is exactly the same as cpVariables, but with a more appropriate name.

Bug Fixes

  • Fixed bug where Widget Properties did not appear to be saved under certain circumstances in Captivate 5.
  • Fixed a bug regarding QuestionWidgets and failure levels.
  • Corrected spelling mistake on WidgetInfo property maxAttempts.
  • getSlideObjectByName() now takes into the account the possibility of the Interactive Widget suffix.

Known Bugs

  • If a question widget is on the first slide of the movie, the enableAnswers() Template Method will be called before enterRuntime().

That’s a lot of new stuff to play around with. Have fun!

Debugging Widgets Inside Your IDE

Last week we discussed a few ways that you can debug your widget from inside Captivate. This week I’ll show you how to trick your widget into believing it’s in Captivate while still testing in your IDE.

To Trick A Widget

In pretty much every post I’ve written so far, I’ve linked back to one of the first articles I ever wrote – the Template Methods post. I’ve linked back to it so often, that my blogging software now makes the link automatically when I type ‘Template Methods’ (It’s becoming sentient!), with good reason too.

Template Methods are the most essential feature in WidgetFactory. Without them, each Widget Mode would do the same thing and widgets would be pointless. With Template Methods employed, all your mode code is segregated nicely into individual methods to be called when needed.

Now don’t let the word ‘Template’ fool you into thinking there’s something special about these methods (or functions). They’re just the same as any other function in your program, and you can call them yourself just the same.

So what would happen if instead of Captivate calling the Template Method, we called it instead? Let’s say, in our constructor, like below.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
package
{
    import fl.controls.TextInput;
    import widgetfactory.StaticWidget;
   
    public class TestingWidget extends StaticWidget
    {

        private var textField:TextInput;

        public function TestingWidget()
        {
            ///////////// THE IMPORTANT BIT
            enterPropertiesDialog();
        }
       
        override protected function enterPropertiesDialog():void
        {
            // Building the Properties Dialog interface.
            // Of sorts
            textField= new TextInput();
            addChild(textField);
           
            textField.width = 250;
            textField.text = "Seriously... I'm a Properties Interface."
           
            // Centre text field.
            textField.x = stage.stageWidth / 2 - textField.width / 2;
            textField.y = stage.stageHeight / 2 - textField.height / 2;
        }
    }
}

Then when we publish the swf, we’d get…

TrickPropertiesInterface

This kicks the widget’s Properties Dialog code off even though it’s not inside Captivate at all. Which means you can test how your Properties Dialog interface is going to act, without having to leave your IDE. Which means you can use all your IDE’s debugging tools, including trace!

You can do this for any of the other widget modes as well, and it works remarkably well for the Widget Panel Preview (enterWidgetPanelPreview()), and even Stage mode (enterStage()). Where you start running into difficulties is with Runtime.

If your widget’s actions are relatively internal, then you could probably test it successfully in the IDE. However, if your widget interacts with the Captivate Movie at all, in say: grabbing slide objects, reading Captivate Variables, jumping to another slide, then the only way to reliably test it is to bring it into Captivate.

About now some of you may be raising your hands and asking: “What about Widget Properties?” Well that’s a good point. Both the Properties Dialog and Stage modes rely heavily on Widget Properties. Fortunately there is a way to get around that. Fake ‘em!

How to Forge Widget Properties

This is quite similar to The Widget King Widget Properties Method I wrote about in another post. I’ll try and sum up in a few sentences what it took me that whole post to explain.

The first time the user enters the Properties Dialog, there are no proir properties to populate the interface. In this case you have to set up some default properties. We have essentially the same problem here and can use the same method to solve it.

Let’s take the widget example above and make some changes. Let’s save and text written in the textField to a Widget Property.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
package
{
    import fl.controls.TextInput;
    import widgetfactory.StaticWidget;
   
    public class TestingWidget extends StaticWidget
    {
        private var textField:TextInput;
       
        public function TestingWidget()
        {
            ///////////// THE IMPORTANT BIT
            enterPropertiesDialog();
        }
       
        override protected function enterPropertiesDialog():void
        {
            if (properties.text == undefined) {
                properties.text = "Default Text";
            }
           
            // Building the Properties Dialog interface.
            // Of sorts
            textField = new TextInput();
            addChild(textField);
           
            textField.width = 250;
            textField.text = properties.text;
           
            // Centre text field.
            textField.x = stage.stageWidth / 2 - textField.width / 2;
            textField.y = stage.stageHeight / 2 - textField.height / 2;
        }
       
        override protected function saveProperties():void
        {
            properties.text = textField.text;
        }
    }
}

To do that we’ve had to make a number of changes, but most important for us is this if statement:

1
2
3
if (properties.text == undefined) {
    properties.text = "Default Text";
}

This if statement checks if the Widget Properties had been set before. If they haven’t, then we give the property a default value which is then applied to the textfield latter. However, this if statement will evaluate to true when testing in your IDE also. So you’ll see the default text come up.

All fine and dandy, but what if you wanted to test a certain combination of properties without messing with your defaults? In that case set those properties up in your constructor before you call enterPropertiesDialog(). In that case the if statement will evaluate to false and wont set up the defaults.

1
2
3
4
5
public function TestingWidget()
{
    properties.text = "Not default text. HA-HA!";
    enterPropertiesDialog();
}

If you have a large set of properties though, it might be better to extract this operation into a function of its own. Then when you come to releasing your widget, you only have to comment out one line.

Bare in mind this method will work just as well with any of the other Widget Modes.

Faking Template Methods for Question Widgets

Question Widgets have some additional Template Methods. Most notably the submit() method, which is called when the audience submits the question, and the clearAnswers() method, which is called when the audience clicks the clear button.

SubmitAndClear

But what if you’re testing your question in the IDE and you want to see if your submit process, or question clearing, is working correctly?

In that case, you can add a temporary button to the stage, listen for when it’s clicked, and when it is call the submit() or clearAnswers() template method. In code, it looks like this:

1
2
3
4
5
6
7
8
9
10
11
var button:Button = new Button();
addChild(button);
           
button.label = "Submit";
           
button.addEventListener(MouseEvent.CLICK, onButtonClick);
       
private function onButtonClick(e:MouseEvent):void
{
    submit();
}

You could also jerry rig something like this to trigger the saveProperties() Template Method, and then trace out the properties object to see if your properties are being extracted correctly.

The other advantage of this method, besides being able to use the beloved trace, is that it saves a lot of time. Rather then having to pull your widget into Captivate every time you make a change, just publish the movie and there you go!

So in short: Call a Template Method and everyone’s happy!

Debugging – A Widget Debacle

No matter what you’re programming, be it a widget, a desktop app, or anything else, you’re going to need to debug it. Yes, it seems no matter how small the program them bugs will find their way into some crevice. Widgets can be particularly susceptible as there are a number of ‘gotchas’ that result from unique Captivate situations.

So you definitely need your debugging tools at the ready when building widgets.

The problem is, the nature of Captivate makes debugging a bit of a debacle.

Let Me Explain

The most debugging basic tool is trace(); which sends a message to the debugging program. So if you wrote…

1
trace("Hello World");

…you’d get:

OutputPanel

As long as you’re testing with an IDE (like Flash Builder, Flash Pro, Flash Develop, FDT) then you’ll have a panel, like the one above, which will receive your traces.

So what’s so great about tracing? Well it’s very useful to see if your if statements was successful…

1
2
3
if (this == that) {
    trace("This does equal That");
}

…or to find the current value of a variable…

1
2
3
4
5
6
7
var startingNumber:Number = 63;
var multiplier:Number = 7;

startingNumber = startingNumber * multiplier;

// What does startingNumber equal now?
trace(startingNumber); // 441

…or to see if/when your function has been called…

1
2
3
private function usefulFunction ():void {
    trace("UsefulFunction has been called");
}

…or if you want to know what type an object is…

1
2
var slideObject = getSlideObjectByName("SlideObjectName");
trace(slideObject);

With widgets however, most of the time you have to test them inside Captivate, which is OUTSIDE your IDE and far away from the handy trace panel.

So if you were in the properties dialog and wanted to trace a message…

1
2
3
override protected function enterPropertiesDialog():void {
    trace("Hello World!");
}

…you’d get…

 WidgetProperties

…nothing.

This makes debugging difficult. However, we are not doomed to spurn the ‘trace’ ability forever for there are a number of alternatives to the trace() method. I shall now list some of them in reverse order as to which I feel are the best.

Flash Debug Player

This is a developer version of the Flash Player that is supposed to write your traces to a text file somewhere on your computer. I vaguely remember someone saying that it can also display them on screen somewhere (though I’ve never been able to make it do so).

This is the method recommended in the Captivate help, but I’ve always had trouble installing the debug player, and I really want to see my traces live, not have to dig them out of some obscure directory.

So… Not for me…

DIY Output Panel

You could create a text field, add it to the stage, and direct your traces to it instead. The problem is it can be very time consuming to program a whole tracer interface.

I’m looking into building a tracing field much like this into WidgetFactory. But for current days I recommend you go with one of the next options.

Little Circles

In comparison to many other languages, drawing stuff in ActionScript is very easy. Drawing a circle can be a nice visual hint as to when something has happened. What’s more, you don’t even have to create an object for it, you can scribble it directly on to the widget itself. Like so:

1
2
3
graphics.beginFill(0xFF0000);
graphics.drawCircle(10, 10, 10);
graphics.endFill();

If you’re not familiar with drawing things in ActionScript, here’s a quick explanation of the above. graphics.beginFill() takes the hex colour (in the above case: red) of what we’re about to draw. The first two parameters of graphics.drawCircle() define the x and y location respectively of where the circle’s centre will be drawn, while the third parameter is the radius of the circle (So the above would draw a 20 pixel wide circle in the top left corner of the widget). Lastly, graphics.endFill() stops drawing with the colour from graphics.beginfill(). Cleaning the paintbrush of its colour so to speak.

Circle

This is a rather quick and dirty way of testing stuff. Where it really shines is when you’re trying to work out how many times something is happening. You can do this by changing graphics.drawCircle() to give the circle a random position.

1
graphics.drawCircle(Math.random() * 300, Math.random() * 300, 10);

Circles

This will make the circle appear randomly in the top 300 square pixels of the widget. So if the code was called six times, you’d see six circles. If you need to test a second section of code this way, then you can draw those circles with a different colour.

Use a 3rd Party Debugger

There are quite a number of AIR apps that can connect to your swf and help debug your code. My favourite is DeMonster Debugger. You can download it here, and I suggest you watch this tutorial here.

It has a few annoyances. For example: it is a little processor intensive, and it adds a good 10k to your widget’s file size; so before you release your widget makes sure you remove all references to it.

What makes DeMonster Debugger so great, is that it not only traces strings (letters and words):

1
MonsterDebugger.trace(this, "Hello World");

But objects as well.

So if you want to know how your properties look at runtime you can, by tracing them:

1
MonsterDebugger.trace(this, properties);

Trace

This also makes DeMonster Debugger useful for exploring the inner workings of Captivate. Do you want to know how slides work? Trace widgetSlide. Do you want to see a complete list of all Captivate Variables? Trace cpVariables.

If a little Captivate spelunking is your aim, then I recommend you check out Whyve’s CPXray widget. It works in conjunction with DeMonster Debugger, and quickly allows you to explore any slide of the movie with it.

So there are a few different ways for you to extract the arachnids from your widgets. I do, however, have one other hot debugging tip. It is in fact so hot that it will need it’s own separate post…