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…

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.

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!

Widget Properties – How they’re used

Last week we looked at how Widget Properties work. This week we’ll see how to use them, and I’ll show you what Widget Properties process I use in my widgets.

How to Write Widget Properties

As we learnt last week, Widget Properties can only be created in the Properties Dialog mode, and the saveProperties() Template Method is usually the best place to do this as it is called just before Captivate requests the Widget Properties from the widget.

To create a new Widget Property, you must access the Widget Properties object (through the ‘properties’ property) and create a new property on it. I know, I know, there was an awful lot of ‘properties’ in the last sentence. It sounds complicated, and to a certain extent the concept can be, but the code is dead simple.

I’ll refer to Widget Properties as WP from now on, hopefully that will cut down the propertying

The property on the WP object will hold the data you save to it. Though initially that property will not exist on the WP object, once you create it, it will still be there when you check the WPs again.

Enough talk. Time for examples! Say the user had writen something in a text field in your interface, and you wanted to save this data to a WP called asdfasdf. Here is how you’d create that property.

1	properties.asdfasdf = textField.text;

I can assure you that asdfasdf is not an existing property on the WP object. In fact, I’d be pretty surprised if it’s an existing property on any object. However, just by assigning it a value, you create it.

Some of you may be raising your hands and asking about the good old 1119 error. You know the one you get when you misspell a property and the Flash compiler crashes the party saying:

Access of possibly undefined property asdfasdf through a reference with static type ClassName.

Well it’s true, this code usually would lead to that error. However, the WP object is special. It’s not one of those ‘static types’ it’s a ‘dynamic type’. Dynamic objects allow you to create properties on them that don’t naturally exist. Some dynamic objects you would have used before would be Arrays, Objects, and MovieClips.

There is no limit to how many properties you can create on a dynamic object. So you can create as many WPs as you like.

1
2
3
4
5
6
7
8

override protected function saveProperties():void
{
    properties.textFieldText = textField.text;
    properties.aNumberProperty = 72;
    properties.aStringProperty = "Greetings World";
    properties.aBooleanProperty = true;
    properties.anArrayProperty = [1,2,3];
}

WPs can only hold certain data types. Make sure you only save those data types to the object. If you tried saving a reference to the textField as a Widget Property instead of the textField’s text, that’s not going to work. Your whole WPs will probably fail as a result.

1
2
3
4

override protected function saveProperties():void
{
properties.myDynamicTextHoldingProperty = textField; // This won't end well
}

These are the types of data that you can save as Widget Properties.

Objects,
Strings,
Numbers,
Booleans (true and false),
Arrays, and
Null.

Also, the items inside the Arrays and Objects must not fall outside the above list.

How do I Access Widget Properties?

Once a Widget Property has been created, it can be accessed in any of the other modes that receive Widget Properties (see last week’s post)

So say we were in the enterPropertiesDialog() Template Method and wanted to set our textField back to what it was in the previous Properties Dialog session, then you’d set textField’s text equal to the WP you stored its data in, like so:

1
2
3
4

override protected function enterPropertiesDialog():void
{
textField.text = properties.textFieldText;
}

The Widget King Widget Properties Method

The problem with WPs is that they don’t come with defaults. When the Captivate Author opens up the Widget Properties interface for the first time, the WP object will be blank. In this case you need defaults set up. I like to have a variable for each of my WPs that holds its default value, then set my interface element equal to that variable. So for example, if we were using the textField example above, then the code would look like this.

1
2
3
4
5
6

private var textFieldDefaultText:String = "Default Text";

override protected function enterPropertiesDialog():void
{
textField.text = textFieldDefaultText;
}

When the Widget’s Properties Dialog opens up, the textField will be given the default text. However, before I set up the textField, I’ll insert a call to a function called checkProperties(), then go down and define that function.

1
2
3
4
5
6
7
8
9
10
11
12

There I will put in an if statement that checks if the setBefore WP equals true. If so, then I’ll set the textFieldDefaultText variable equal to the textField’s Widget Property.

1
2
3
4
5
6
7
8

private function checkProperties():void
{
    if (properties.setBefore == true) {

        textFieldDefaultText = properties.textFieldText;

    }
}

Then in my saveProperties() Template Method, I’ll extract the data from my interface and save it to WPs. Then at the end I’ll set the setBefore WP to true. So all up the code would look like this:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

private var textFieldDefaultText:String = "Default Text";

override protected function enterPropertiesDialog():void
{
    checkProperties();
    textField.text = textFieldDefaultText;
}

private function checkProperties():void
{
    if (properties.setBefore == true) {

        textFieldDefaultText = properties.textFieldText;

    }
}

override protected function saveProperties():void
{
    properties.textFieldText = textField.text;
    properties.setBefore = true;
}

Let’s run through the process and see how it works. The first time around, there is no setBefore property, so the if statement comes back false and the textFieldDefaultText property stays at its default value. When the properties are saved, the setBefore property is created with a true value. That means for every time afterwards the if statement returns true and the default variable’s value is swapped out with the saved property’s value. Then when that variable is applied to the interface, it’s the saved value, not the default value, which is assigned.

To add another property, create another default variable, set its associated interface element equal to that variable in enterPropertiesDialog(), associate the variable with its WP in the checkProperties() method, and save the interface element’s value to the WP in the saveProperties() Template Method.

This gives you a water tight properties system. I keep the code in the checkProperties() method separate so I can use it in other Widget Modes.

There are many different ways to handle Widget Properties. If you have your own particular method, by all means feel free to share it with us.

Widget Properties – How they work

Widget Properties! They are a wonderful thing. You could argue they are what separates Widgets from regular Animations. However, their very nature is mysterious. Where do they come from? Where do they go? When do they have lunch?

I’m not a developer of Captivate (sigh) so I can’t tell you with any absoluteness what happens to Widget Properties when they get sucked into Captivate. I can, however, tell you their life cycle as far as widgets go.

First of all though, let’s look at some basic questions.

Why do we need Widget Properties?

There are many different places that the widget swf finds itself in inside of Captivate (called Widget Modes). There is Runtime Mode, when the widget is in the published Captivate Movie and needs to be a fully functioning tool. There is Stage Mode, when the Captivate Author is editing the slide that the widget is on, and the widget needs to display a preview of what it will look like at Runtime. Then if your widget any settings, it needs to create an interface to display in the Properties Dialog’s Mode as well. A rule that Captivate follows with regards to widgets and their modes is that they never touch. You will never have the widget swf load in the Properties Dialog, then jump to the Stage preview, and then find itself being published into Runtime, or any variant thereof. What happens is the swf will load in the Properties Dialog, then reload on the Stage, and reload again at Runtime. Think of it like if you were filling out a form on the web. If you refresh the page, the form will be loaded again, and will wiped clean of anything we wrote in it. Same with widgets. When the widget swf moves from one mode to another, it will be reloaded and have no memory of what happened to it in another mode.

This leads to a major issue. How do you save any information gathered in this widget mode that might be of use in another? For example: Say we had a widget that drew a square on stage, and in the widget properties you could customise the colour of that square. If the user specifies that he wants it to be red, how do we save that information so that the other modes will know to draw a red square?

Answer: Widget Properties

What are Widget Properties?

Widget Properties are an object that Captivate holds for our widget. The widget can write information to this object (such as what colour the square should be) and Captivate will save it. When the widget swf is reloaded into a new location, Captivate will give the widget the Properties object so that it can read any information that it has set previously.

How do Widget Properties Work?

Widget Properties go through quite a life cycle. This gives me an excellent opportunity to pull out a FLOW CHART!

Lets start at the beginning.

1. Where do Widget Properties come from?

Widget Properties start their life in the Properties Dialog. The place where you should stick the settings interface for the widget.

Ah yes, but why do I keep saying that you should stick your widget’s interface here?

When the Captivate Author clicks OK the Properties Dialog will close down. Before closing down however, Captivate will request the widget give him its Widget Properties object. Sort of like if you were on a sinking ship and then these pirates came along and told you to throw your valuables at them before going down.

In WidgetFactory terms, this handing over of Widget Properties happens just after the saveProperties() Template Method is called. So saveProperties() is an excellent place to extract the information in the widget’s interface, and place them into Widget Properties, before the whole widget gets closed down.

(Yes, I built the flow chart in Captivate. I knew that software must have been good for something )

This, ladies and gentlemen, is the birth place of all Widget Properties. This is the only place where Captivate receives properties from the widget. After that it’s all give give give. You can’t change the Properties when the widget is on Stage or at Runtime. So this is the ONLY place you can allow the user the change the settings of the widget.

2. Captivate sends the Widget Properties out.

Now that we’ve saved some Widget Properties in Captivate, Captivate will send them back to the widget at the start of a new Stage Mode, Runtime Mode, or the Properties Dialog Preview in Captivate 4 (See the enterPropertiesDialogPreview() Template Method under the StaticWidget class in the documentation).

The Widget’s Properties are also sent back to the widget when it enters the Properties Dialog. Why is this? Take an example of what would happen if they weren’t given to the Properties Dialog. Say we were building that widget I mentioned above that drew a square and allowed the Captivate Author to define what colour it would be. Let’s say that the square had a default colour of blue. However, the Captivate Author enters the Properties Dialog and changes the Widget Property that controls the colour of the square from blue to red. So they close down the Properties Dialog and the Stage preview updates to show a red square. But then if the Captivate Author opens up the Properties Dialog again to change more settings, the widget will show the default settings again. In other words, the Captivate Author will open up the dialog again, see the square’s colour has been set back to the default blue, judge our widget as being buggy, and it out.

So Widget Properties are given to the Properties Dialog again, so that the widget can update its interface to hold the same values as when the Captivate Author last left it.

Let’s make what’s sending and what’s recieving clear:

Stage mode RECIEVES Widget Properties at its start.
Properties Dialog Preview RECIEVES Widget Properties at its start.
Properties Dialog RECIEVES Widget Properties at its start.
Properties Dialog SENDS Widget Properties to Captivate at its end (assuming the Captivate Author clicked OK and not Cancel)

Where’s Runtime? Well technically that should be on the list so I’ll add it.

Runtime mode RECIEVES Widget Properties at its start.

However, it’s not quite as simple as that.

3. Covert Runtime Properties

When the widget is inside Captivate, Captivate sends and recieves the Widget Properties in an Object form. For some reason I do not fully understand (again, not a Captivate Developer) at Runtime the Widget Properties object is transcribed into XML, and that’s how the Widget receives them.

SPLOT!

It requires quite a bit of time to learn the structure of the XML and how to weed your way through it to get to the properties you want. A lot of trial and erroring there. Not fun.

You can see this XML for your own if you like. It’s available under the widgetPropertiesRawData property as a String. But you need not worry about searching through an XML jungle no more.

Thankfully, WidgetFactory runs through that XML and formats it back into the classic object we are used to dealing with inside of Captivate. This saves a LOT of time and headache I can tell you. It’s probably the main reason why WidgetFactory was built in the first place.

So let’s look at the completed flow chart why don’t we?

So there you go. Everything I know about how Widget Properties work. Not a whole lot about how to use them, but next week I will be sharing the Widget Properties workflow I use in my Widgets.

See you then!

The Widget King