Introduction

One nifty thing about CpGears is that it provides you with events when things are changing. It is especially useful in two circumstances: when the widget changes its visibility and when a Captivate Variable changes value.

This article will concentrate on the CpGears eventing mechanism and assumes that you already know how to create a static widget in CpGears. If you don't, please read the CreateStaticWidget article in the wiki section.

Project

A FlashDevelop project containing all the files for this article is available in the Download Section. It also contains a Captivate test project showcasing the widget in action.

Monitoring Widget Visibility

In some cases, a developer needs to know when his widget appears on the stage and when it is removed. CpGears provides an event for this. The simplest way to tap onto it is to add an event listener from within the initialize method of the Runtime View:

	import cpgears.movie.widget.events.WidgetEvent;
	import cpgears.movie.widget.events.WidgetVisibilityEvent;

	override public function initialize():void {
		movie.widget.addEventListener(WidgetEvent.VISIBILITY_CHANGED, onWidgetVisibilityChanged);
	}
		
	private function onWidgetVisibilityChanged(event:WidgetVisibilityEvent):void {
		<ADD YOUR CODE HERE>
	}

A CpGears Runtime View (derived from RuntimeWidgetView) offers an interface to access some Captivate Movie properties. From the movie property, you can access the widget property which in turn gives you access to other widget properties including a Visibility event. This event contains a visible property that will tell you if the widget is visible or not. The event will be triggered every time the widget changes its visibility.

Monitoring Captivate Variables

A widget will usually access Captivate variables. It will try to read them and also set them to control the presentation flow. In some circumstances, a developer will want to know when the variable will have changed its value. CpGears offers a VariableMonitor mechanism to detect these changes. Again, from the initialize() method of the Runtime View:

	import cpgears.movie.MovieEvent;
	import cpgears.movie.variables.monitor.MonitoredVariableEvent;

	private static const SHOWPLAYBAR:String = "cpCmndShowPlaybar";

	override public function initialize():void {
		movie.addEventListener(MovieEvent.VARIABLE_CHANGED, onVariableChanged);
		movie.monitorVariable(SHOWPLAYBAR);
	}
		
	private function onVariableChanged(event:MonitoredVariableEvent):void {
		<ADD YOUR CODE HERE>
	}

The first thing that we need to do is to register an event listener for when a variable will change value. Next, we instruct CpGears to monitor a specific variable. By default, CpGears doesn't monitor any variables. It will start the monitoring process only when a variable is added to the monitoring function. This helps saving CPU resources.

If you want to monitor many variables, you just need to make more calls to the monitorVariable() function with the name of the variable you want to monitor. At this point, you may ask yourself how will you know which variable will have changed value. This is quite simple. The MonitoredVariableEvent contains three properties:

• name
• value
• previousValue

So, if you want to target a specific variable, you just check the name property.

	private function onVariableChanged(event:MonitoredVariableEvent):void {
		if (event.monitoredVariable.name == SHOWPLAYBAR) {
			<ADD YOUR CODE HERE>
		}
	}

Demo Playbar Widget

The project associated to this article contains the code for a widget that capitalizes on the widget visibility event and the monitoring capabilities of CpGears. The widget basically hides the playbar when it is displayed and restores it when it disappears. The widget also contains a button that will be visible only when the playbar is invisible.

The project contains a Captivate project (DemoPlaybarProject) that showcases the Demo Playbar Widget. The presentation contains the widget as well as two buttons: one for displaying the playbar and another one to hide it. Therefore, by clicking on the two buttons, the playbar will be shown/hidden and the widget will adapt its functionality since it's monitors the Captivate Playbar variable. I suggest that you open up the Captivate file and experiment with the widget capabilities. Try to:

• Change the widget duration and start time
• Play with the widget's button as well as the two other buttons
• Explore the widget's code to see how it really works

The widget Runtime View code is shown below:

package demo.views {
	import cpgears.log.ILogger;
	import cpgears.log.LogManager;
	import cpgears.movie.MovieEvent;
	import cpgears.movie.variables.monitor.MonitoredVariableEvent;
	import cpgears.movie.widget.events.WidgetEvent;
	import cpgears.movie.widget.events.WidgetVisibilityEvent;
	import cpgears.views.RuntimeWidgetView;
	import fl.controls.Button;
	import flash.events.Event;
	import flash.events.MouseEvent;
	
	/**
	 * ...
	 * @author Whyves
	 */
	public class RuntimeView extends RuntimeWidgetView {
		
		public var showPlaybar_btn:Button;
		
		private var mLogger:ILogger = null;
		private static const SHOWPLAYBAR:String = "cpCmndShowPlaybar";
		
		public function RuntimeView() {
			super();
			mLogger = LogManager.getLogger(this);
			
			// Register an event listener on the button in the Runtime view.
			showPlaybar_btn.addEventListener(MouseEvent.CLICK, onShowPlaybar);
		}

		/**
		 * Initializes the runtime view
		 */
		override public function initialize():void {
			// Listen to widget visibility changes
			movie.widget.addEventListener(WidgetEvent.VISIBILITY_CHANGED, onWidgetVisibilityChanged);
			
			// Monitor for playbar variable changes
			movie.addEventListener(MovieEvent.VARIABLE_CHANGED, onVariableChanged);
			movie.monitorVariable(SHOWPLAYBAR);
		}
		
		/**
		 * Callback function when a monitored variable has changed value
		 * 
		 * @param	event The MonitorVariable event
		 */
		private function onVariableChanged(event:MonitoredVariableEvent):void {
			if (event.monitoredVariable.name == SHOWPLAYBAR) {
				showPlaybar_btn.visible = !event.monitoredVariable.value;
			}
		}
		
		/**
		 * Callbacl function when the widget visibility changed
		 * 
		 * @param	event The widget visibility event
		 */
		private function onWidgetVisibilityChanged(event:WidgetVisibilityEvent):void {
			// Hide playbar when the widget is displayed and show the playbar when it's not
			setPlaybarVisibility(!event.visible);
		}
		
		/**
		 * Callback function when the button in the Runtime view was clicked.
		 * 
		 * @param	event The button event.
		 */
		private function onShowPlaybar(event:Event):void {
			// Show the playbar when the button is clicked
			setPlaybarVisibility(true);
		}
		
		/**
		 * 
		 * @param	visible Set to <code>true</code> to make the playbar visible, <code>false</code> otherwise.
		 */
		private function setPlaybarVisibility(visible:Boolean = true):void {
			movie.setCpVariable(SHOWPLAYBAR, visible);
		}
	}
}