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!