I get asked this question a lot, so I thought I’d make a video on it.
How to Access Captivate Variables in CP6 if you’re using the Adobe Widget Template.
If you’re using an animation or for some reason do not have access to cpSetValue, then don’t worry, everything’s not lost. The getMovieProps() function is available two parents up from the animation’s main timeline. So just use this code:
1 |
Here’s a quick tip.
As many of you know, the Drag and Drop widgets come in two flavors, a Question Widget and an Interactive Widget. These two widgets mostly use the same code, but of course there are differences in between Question Widgets and Interactive Widgets, so at certain points different code is executed for the Question Widget than is for the Interactive Widget.
If you’ve got a similar situation and need to detect what type of widget is executing the code you’re writing, here’s how you go about it.
New to WidgetFactory 6 is the WidgetType class. It is found under the ‘widgetfactory’ package, so to import it you’d write the following:
1 | import widgetfactory.WidgetType; |
The WidgetType class has a single static property…
…and three static constants.
So if you want to check the widget type, just compare the relevant constant to the ‘type’ property like so:
1 2 3 4 5 6 7 | if (WidgetType.type == WidgetType.QUESTION) { // This is a question widget. } else if (WidgetType.type == WidgetType.INTERACTIVE) { // This is an interactive widget. } else { // This is a static widget. } |
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.
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!
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.
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!
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.
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.
Also, the items inside the Arrays and Objects must not fall outside the above list.
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 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 | private var textFieldDefaultText:String = "Default Text"; override protected function enterPropertiesDialog():void { checkProperties(); textField.text = textFieldDefaultText; } private function checkProperties():void { } |
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.
I don’t know about you, but when I’m building a widget I often get so caught up in the cool functionality and how it’s going to revolutionise the eLearning world (<—this never happens) that I forget about something really simple.
That’s right folks, there are some people out there who need to see something more than once to remember it (like me). So widgets can’t be a one show deal. They need to be able to work predictably no matter how many times the movie is rewound and watched again. So how can we make sure of this? Well I have good news and bad news.
The good news is that due to a handy feature in WidgetFactory, sometimes we don’t have to worry about this.
The bad news is that even though we have this handy feature in WidgetFactory, sometimes we do.
If your widget doesn’t have any animation, and doesn’t have any interactivity, then it’s likely all it needs to do is set up and look pretty. Here’s a simple (if useless) example of one of these types of widgets. All it does is draw a red circle at a random location on stage when the widget is displayed in the Captivate Movie (enterRuntime template method).
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 | package { import widgetfactory.StaticWidget; public class RandomCircle extends StaticWidget { public function RandomCircle() { } override protected function enterRuntime():void { // Setting the color (or: colour) graphics.beginFill(0xFF0000); // Make a circle graphics.drawCircle(Math.random() * stage.stageWidth, // Random x position Math.random() * stage.stageHeight, // Random y position 10); // Radius of 10 pixels graphics.endFill(); // Stop using a red fill for any of our next drawings. } } } |
Play the movie and a red circle will appear at a random point on stage. But what happens when you rewind the movie? Take a look.
Yep. Rewind and there are two red circles. Rewind again and there are three red circles. What’s happening? Well each time the widget appears in the movie, the enterRuntime template method is called, and the widget’s circle drawing code is executed, again. Therefore, every time you rewind you get a new circle.
However, if the enterRuntime template method didn’t get called for a second time when you rewound, we’d have no problem would we? Is there any way to stop it doing so? Well yes. WidgetFactory has a tiny little property that’s easilyoverlooked, but is oh-so-useful for these situations. It’s called: dispatchRuntimeAfterRewind.
dispatchRuntimeAfterRewind holds a true or false value (known as a Boolean). If it’s true, then the enterRuntime, and the WidgetEvent.ENTER_RUNTIME event, will be called again when the user rewinds the movie. If it’s false, then they won’t.
Say we set dispatchRuntimeAfterRewind to false in the constructor function.
1 2 3 | public function RandomCircle() { dispatchRuntimeAfterRewind = false; } |
Take a look at what that one line of code does to our widget.
Rewind the movie, and there is no new circle! Problem solved!
The problem is: widgets that work like this are few and far between. Nine times out of ten, you’re going to want your widget to do something again when the movie is rewound. For example, if you built a widget that paused the Captivate Movie when it appeared on stage, then you’re more than likely going to want it to pause the movie again when the movie is rewound. What if you had a widget that played an animation? You’re going to want to show that animation again when the movie is rewound. But like we saw with the RandomCircle widget above, if your runtime code adds things to the stage, it has a habit of adding duplicates to the stage when it is called again (oh look, there are two ‘OK’ buttons now). How can we get around this?
Well, first let’s start with the example we had above. We have a widget that draws a single circle on stage at a random position. However, when we rewind the movie and see the widget again, the circle is in the same position it was when we first saw it. That’s not very random. What if we wanted the circle to be drawn at another random location when we see the widget again? Well for starters we’re going to need to know when the widget is being shown again, that means we need enterRuntime to be called again, which means dispatchRuntimeAfterRewind needs to be true.
1 2 3 | public function RandomCircle() { dispatchRuntimeAfterRewind = true; } |
Although, we could completely remove this line, as dispatchRuntimeAfterRewind defaults to true anyway.
Next we need to know whether enterRuntime is being called for the first time or not. That can be done quite easily. We’ll add a Boolean variable called _isFirstRuntime and set it to true by default. In the last line of our enterRuntime method, we’ll set _isFirstRuntime to false. So for the first time the function runs, isFirstRuntime will be true, every time after that it will be false. Now, at the start of enterRuntime, we can check if _isFirstRuntimeis false (meaning there must already be a circle on stage) and if so, clear the stage of all drawings before we draw a new random circle.
All together, the widget looks like this:
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 | package { import widgetfactory.StaticWidget; public class RandomCircles1 extends StaticWidget { private var _isFirstRuntime:Boolean = true; public function RandomCircles1() { dispatchRuntimeAfterRewind = true; } override protected function enterRuntime():void { if (_isFirstRuntime == false) { // If we've already drawn a circle... graphics.clear(); // ...then erase all drawings. } // Setting the color (or: colour) graphics.beginFill(0xFF0000); // Make a circle graphics.drawCircle(Math.random() * stage.stageWidth, // Random x position Math.random() * stage.stageHeight, // Random y position 10); // Radius of 10 pixels graphics.endFill(); // Stop using a red fill for any of our next drawings. _isFirstRuntime = false; } } } |
And the output looks like this:
And there you go! Rewind the movie and we still only have one circle, and it’s in a completely new position!
Now there are probably some of you who’d like to point out that this whole thing could have been avoided by calling graphics.clear() right off the bat. But if we did, would we have learned anything?
Like I said, nine times out of ten you need to do something like this to your widget, so I’m wondering if I should include _isFirstRuntime as a property in the next version of WidgetFactory. What do you guys think?
Loading ...Update: As of WidgetFactory 5.1 the isFirstRuntime property has been included.
By the way, keep those votes on what you’d like me to write next coming! The poll is a lot tighter than I thought it was going to be.