Articulate Presenter Player SDK

This is the preview version of the documentation, which excludes certain details required for implementation. The full documentation and the associated sample files are available to Articulate Platinum Membership Plan members at no charge. Click here to request access to the full SDK.

Introduction to the Player SDK

The Articulate Presenter Player SDK gives Flash developers the ability to create custom Flash movies that extend and interact with the Articulate Presenter Player. With the SDK, developers are able to:

• Add functionality by developing custom player tabs.
• Add player features by creating custom player toolbar items.
• Customize certain player assets.
• Communicate with the player via runtime API methods.

This documentation, along with the included sample files, will provide you with tools to get you started.

Creating Custom Tabs

Articulate Presenter ships with four tabs - Outline, Thumbnails, Notes and Search. In addition, you can create your own custom tabs to provide additional features and functionality for the Player. You create custom tabs by modifying the supplied .FLA file in Flash MX and also editing an XML file.

Locate the sample tab in the folder named "Test_Tab." This folder contains the source FLA file TestTab.fla, the compiled SWF file TestTab.swf, and the art_plugins.xml file that references the TestTab.swf file. To add this test tab to any presentation simply copy the SWF and XML file to the "player" folder of any published presentation.

Create your own custom tab by first modifying the FLA file in Flash MX. Publish your SWF for Flash Player 6. Tabs are then added to the Player by modifying the file art_plugins.xml. Within the "modules" section, define an item for each custom tab in your presentation. A typical item will look the following:

	<item>
		<id>5050</id>
		<type>navmod</type>
		<file>NewTab.swf</file>
		<labeltext>New	Tab</labeltext>
		<scrollenabled>true</scrollenabled>
	</item>
	

Below is a quick description of the tags:

• id -- An internally used ID. It must be a number and unique among all item IDs.
• type -- Determines whether the custom item is a toolbar or a tab item. Use "navmod" for tab items; use "toolmod" for toolbar items.
• file -- Defines the SWF the Player will display when the item is activated.
• labeltext -- The text that is displayed on the tab or toolbar button.
• scrollenabled -- If the item is a tab, this value enables or disables the scrollbar.

All tags are required except for scrollenabled. You may add more tags to provide the item with more information. Once built, your custom tabs and toolbar items can be added to any presentation by simply copying your SWF and XML files to the published output's "player" folder. You can also automatically include your custom tabs and toolbar items in every publish by copying them to the "player" folder within the program. This way, they will be included in the published output with each future publish. Assuming you installed Presenter to the default location, the folder will live here:

C:\Program Files\Articulate\Presenter\players\core\player

Creating Custom Toolbar Items

Articulate Presenter Player includes several toolbar items accessed from the upper-right of the Player. The standard toolbar items include Attachments, Bookmark, Send Link, and Exit. Like tabs, you can create your own custom toolbar items to provide additional features and functionality to the Player.

Adding a custom toolbar item is similar to adding a custom tab. Locate the sample toolbar item in the folder named "Test_Tool." This folder contains the source FLA file TestTool.fla, the compiled SWF file TestTool.swf, and the art_plugins.xml file that references the TestTool.swf file. To add this toolbar item to any presentation simply copy the SWF and XML file to the "player" folder of any published presentation.

Create your own custom toolbar item by first modifying the FLA file in Flash MX. When creating your Custom toolbar item, you must implement a function named artModuleAPI. This function is a command handler that should handle events from the Player. It should handle the following commands:

• activate_onclick
• activate
• deactivate

A typical implementation of this command handler follows:

function artModuleAPI( command )
{
	switch(command)
	{
		case "activate_onclick":
		case "activate":
			gotoAndPlay("activate");
			break;
		case "deactivate":
			gotoAndPlay("deactivate");
			break;
	}
}

Additionally, it is the responsibility of the toolbar item to define a Boolean variable named "artModuleIsActive" at the item's base level and set the value of this variable based on whether or not the toolbar item is active or not. When finished authoring your custom toolbar item, publish your SWF for Flash Player 6.

As with tabs, create a new item tag within art_plugins.xml for each custom toolbar item you wish to add to your presentation. A typical toolbar item will look similar to the following:

	<item>
		<id>5050</id>
		<type>navtool</type>
		<file>NewToolbarItem.swf</file>
		<labeltext>New	Tool</labeltext>
	</item>

Modifying Assets

An asset is a Player component that resides outside of the core player files. Assets are usually required for the Player to function normally. Asset file names contain the prefix "ast_." Not all assets can be modified; you will find all modifiable assets in the included "Assets" folder. Below is a list of the supplied FLA files followed by a brief description.

• ast_loader.fla -- A preloader for inserted Flash Movies that buffers the movie and allows the player controls to control the inserted movie.
• ast_navicons.fla -- Defines the icons that are displayed in the Outline view of the navigation used to expand and collapse the list.
• ast_remote.fla -- Defines a floating control to replace the normal controls that are in view mode three. To enable the floating controls add the following XML to your published playerproperties.xml file:

  	<floatcontrols>
  		<left>10000</left>
  		<top>10000</top>
  		<inneralpha>100</inneralpha>
  		<outeralpha>100</outeralpha>
  	</floatcontrols>
  

You will find an example of ast_remote.fla in use in the included sample presentation; toggle to the "slide-only" display mode to view it. Contained within each FLA file on the layer named "Implementation Notes," you will find any special instructions needed to modify or create your own asset.

The Articulate API Object

The Articulate API object is a global variable and is accessible to a Flash movie loaded within the playershell.swf simply by referencing API. However, if the loaded SWF was published for a different version of Flash then version 6, the global object may not be accessible. For this reason we strongly encourage you to reference the API Object at _level0.

You can find a sample movie that implements the API in the folder "Flash_Object." This folder contains the source FLA and the generated SWF.

Methods

Below is a list of the methods exposed by the API:

Play()

Causes the player to continue playing. If the player is already playing then it does nothing.

Pause()

Pauses the player if it is currently playing. If the player is already paused then it has no effect.

LockPlay(bLocked)

Locks the play /pause button so that the user can't start or stop the presentation until it is unlocked.

PlayNext()

Plays the next slide.

PlayPrevious()

Plays the previous slide.

PlaySlideNum(nSlideNum)

Plays the slide specified by nSlideNum. nSlideNum must be an integer greater than 0 and less than or equal to the number of slides in the presentation.

GotoFrame(nFrameNum)

Goes to the frame specified by nFrameNum in the current slide.

SetDisplayMode(strDisplayMode)

Changes the display mode to the mode specified by strDisplayMode. strDisplayMode can have the following values:

• "1" -- The standard view
• "2" -- The no sidebar view
• "3" -- The slide only view
• "next" -- toggles the display mode to the next enabled view
• "previous" -- toggles the display mode previous enabled view

GetDisplayMode()

Returns a number representing the current display mode. For more details see Set- DisplayMode.

GetCurrentSlide()

Returns the index of the currently displayed slide

IsPlaying()

Returns true if the slide is playing and false if it has been paused.

GetCurrentSlideTime()

Returns the current position in seconds within the slide.

GetCurrentPresentationTime()

Returns the current position in seconds within the presentation.

GetSlideCount()

Returns the number of slide contained within the presentation.

GetVolume()

Returns the Volume setting.

SetVolume(nVolume)

Sets the volume to the value specified by nVolume. nVolume should be a number between 0 and 100.

GetSlideInfo(nSlideNum)

Returns a slide info object. Supported properties:

• oSlideInfo.strFileName -- The slide file SWF name
• oSlideInfo.strBgSwf -- The slide background SWF name
• oSlideInfo.nPlayListId -- The slide's playlist id
• oSlideInfo.strTitle -- The slide title
• oSlideInfo.strSlideText -- The slide text
• oSlideInfo.strNotes -- The slide notes
• oSlideInfo.nSlideTime -- The slide duration
• oSlideInfo.bWaitForUser -- Determines if the slide waits when it reaches the end or plays the next slide
• oSlideInfo.nFrameRate -- The slide framerate
• oSlideInfo.nLevel -- The nesting level of the slide

GetModuleData(nModuleId)

Returns a reference to the array representation of the xml for the specified module ID. The structure of this array may vary depending on the data included in the modules xml.

GetPlayerData()

Returns a reference to the array representation of the xml data contained within playerproperties.xml.

GetPresentationData()

Returns a reference to an array representation of the xml data contained within presentation.xml.

EnableKeyboardShortcuts(bEnable)

Enables or disables keyboard shortcuts based on the value of bEnable.

IsColorized()

Returns true if a color scheme has been enabled for the player.

GetColorInfo()

Returns a color info object. Properties supported:

	ColorInfo.Core.strText
	ColorInfo.Core.strSlideBg
	ColorInfo.Core.strAccentLines
	ColorInfo.Core.strSideBarBg
	ColorInfo.Core.strPlayerBg
	
	ColorInfo.Sidebar.strTouch
	ColorInfo.Sidebar.strIcon
	ColorInfo.Sidebar.strSeperator
	ColorInfo.Sidebar.strSlideSelected
	ColorInfo.Sidebar.strSlideRollover
	
	ColorInfo.Button.strText
	ColorInfo.Button.strFace
	ColorInfo.Button.strRollover
	
	ColorInfo.Tab.strText
	ColorInfo.Tab.strBorder
	ColorInfo.Tab.strRollover
	ColorInfo.Tab.strTopGrad
	ColorInfo.Tab.strBottomGrad
	
	ColorInfo.Scrollbar.strFace
	ColorInfo.Scrollbar.strTrack
	ColorInfo.Scrollbar.strArrows
	
	ColorInfo.TopBar.strGradTop
	ColorInfo.TopBar.strGradBottom
	
	ColorInfo.BottomBar.strGradTop
	ColorInfo.BottomBar.strGradBottom
	
	ColorInfo.Tooltip.strText
	ColorInfo.Tooltip.strBackground
	ColorInfo.Tooltip.strBorder
	
	ColorInfo.Playback.strGradTop
	ColorInfo.Playback.strGradBottom 

Adding Your Custom API SWF to Your Presentation

When inserting a Flash movie that contains the API into a slide, follow the steps:

1. In PowerPoint menubar, select Articulate --> Flash Movie.
2. Browse to and select the Flash movie that contains the API.
3. Select "Display in slide."
4. Select from the Synchronization drop-down menu the "Movie plays independently of slide" option.
5. Set other options to your liking.
6. Click OK.