Use JCThumbViewerScroller by Code
Here are the steps you need to follow in order to use the JCThumbViewerScroller component with ActionScript 3.0 code:
1. Create a new Flash ActionScript 3.0 file and set its frame rate to 30 fps. Open up the Components panel (Ctrl + F7 for Windows or Command + F7 for Mac), select the JCThumbviewerScroller component and drag it over the Library panel. Next, bring up the Actions panel (F9 for Windows or Option + F9 for Mac) and paste the following lines of code inside it.
2. Import the necessary classes for the JCThumbViewerScroller component and the JCThumbViewerScroller events class (JCThumbViewerScrollerEvent):
import com.jumpeye.Events.JCThumbViewerScrollerEvent;
import JCThumbViewerScroller;
3. Create and set up the JCThumbViewerScroller instance:
var myScroller:JCThumbViewerScroller = new JCThumbViewerScroller();
myScroller.x = 20;
myScroller.y = 20;
myScroller.setSize(510, 200);
myScroller.showLabels = true;
myScroller.scaleMode = "scaleCrop";
addChild(myScroller);
4. Listen for events triggered by the component:
myScroller.addEventListener(JCThumbViewerScrollerEvent.CONTENT_LOAD_PROGRESS, loadingProgress);
function loadingProgress(evt:JCThumbViewerScrollerEvent):void {
trace("Loaded "+evt.count+" items of "+myScroller.length);
}
myScroller.addEventListener(JCThumbViewerScrollerEvent.IO_ERROR, itemLoadingError);
function itemLoadingError(evt:JCThumbViewerScrollerEvent):void {
trace("Error loading item with index "+evt.item.index);
}
myScroller.addEventListener(JCThumbViewerScrollerEvent.CHANGE, itemSelected);
function itemSelected(evt:JCThumbViewerScrollerEvent):void {
trace("The item with index "+myScroller.selectedItem.index+" is now selected");
}
5. Set the source property of the component. Once you set the source property, the JCThumbViewerScroller component will start loading the content:
myScroller.source = "source.xml";
6. Compile the application by hitting Ctrl + Enter for Windows or Cmd + Enter for Mac.
Properties
Property |
Type JCThumbViewer Panel |
Description |
_targetInstanceName |
String yes |
The instance name of the target display object that will load the large images, video or other content associated to the items. That display object will act as a loader.
|
alignMode |
String yes |
The type of horizontal and vertical alignment used for the content. Possible values are topLeft, topMiddle, topRight, centerLeft, centerMiddle, centerRight, bottomLeft, bottomMiddle, bottomRight.
The default value is topLeft.
Example
Center the content (thumbnail images) inside the items:
myScroller.alignMode = "centerMiddle";
|
autoPlay |
Boolean yes |
Specifies whether the component will automatically play a slide show by consecutively selecting the items.
If _targetInstanceName is set, the thumbnail scroller will automatically set the target display object's source property to load the content associated to the selected item.
The default value is false.
Example
Set the scroller to automatically start the slide show:
myScroller.autoPlay = true;
|
autoPlayDelay |
Number yes |
The time interval measured in seconds when the slide show will change the selected item.
The default value is 5 seconds.
Example
Make the slide show play faster:
myScroller.autoPlayDelay = 2;
|
config |
XML/String no |
Sets the configuration xml for the component. In this case the component will be set up using the values in the xml data and will disregard any previous settings made from the panel or by using code.
You can also set up the component using external configuration XML files. In this case you need to specify the URL to that configuration XML file.
Example
myScroller.config = "myConfig.xml";
or
myScroller.config = <config>
<params>
<autoPlay>
<type>Boolean</type>
<value>true</value>
</autoPlay>
...
</params>
<patterns>
...
</patterns>
</config>;
|
direction |
String yes |
The way the items will be displayed in the scroller. Possible values are horizontal and vertical.
The default value is horizontal.
Example
Set the items to be displayed vertically:
myScroller.direction = "vertical";
|
easeType |
String yes |
The type of easing applied for the scrolling movement of the thumbnails. Possible values are easeIn, easeOut, easeInOut and easeNone.
The default value is easeOut.
Example
Change the easing to easeInOut:
myScroller.easeType = "easeInOut";
|
firstVisibleItem |
int yes |
The 0-based index of the first item visible in the thumbnail scroller.
The default value is 0.
Example
Make the thumbnail scroller start with the third thumbnail being the first one displayed in the list:
myScroller.firstVisibleItem = 2;
|
itemHeight |
Number yes |
The height of the thumbnails measured in pixels.
Note: For best results make sure the itemHeight matches the actual thumbnail image height in pixels and use the "exactFit" scale mode.
The default value is 100.
|
items |
Array no |
[read-only] The list of objects representing the references to the thumbnails. Each object is of type ScrollerItemModel. For details about the ScrollerItemModel class please refer to the section called Class ScrollerItemModel.
|
itemSpace |
Number yes |
The size of the space between the thumbnails.
The default value is 5.
|
itemWidth |
Number yes |
The width of the items measured in pixels.
Note: For best results make sure the itemWidth matches the actual thumbnail image width in pixels and use the "exactFit" scale mode.
The default value is 100.
|
length |
int no |
[read-only] The number of items in the list.
|
margins |
Number yes |
The left and right side spacing of the component if the direction is set to horizontal or the top and bottom spacing if the direction is set to vertical.
The default value is 5.
|
navigationType |
String yes |
The type of navigation used to scroll the list of items. Possible values are:
- mouseRelative - the list will slide towards the first or last item, depending on the mouse position; the navigation stops once the list has reached the correct position, depending on the mouse pointer's coordinates over the component;
- mouseAbsolute - the list will slide towards the first or last item without stopping, until it reaches the beginning or the end of the list; the direction of the sliding is given by the mouse position over the component and the speed of the slide is given by the distance from the center of the component to the mouse position;
- scrollBar - the navigation is done using a scrollbar;
- none - the component will not allow navigation from user input.
The default value is mouseRelative.
Example
Navigate through the list of thumbnails using the scrollbar:
myScroller.navigationType = "scrollBar";
Note: When using the scroll bar as navigation type, a scroll bar will appear below the component (or attached to the right side). In this case the component's height (or width) property will have the same values as the component without the scroll bar, but visually, the component will have the scroll bar attached to the bottom or the right side, making it larger than the value returned by the height or width properties.
|
scaleMode |
String yes |
The type of scaling applied on the content of the items (thumbnails). Possible values:
- scaleCrop - scales the content so it fills in the entire size of the thumbnail and then crops the parts of the content that do not fit;
- exactFit - resizes the content so that it takes the same size as the thumbnail - may distort the content if the thumbnail does not have the same size as the content;
- maintainAspectRatio - scales the content so that it fits entirely inside the thumbnail - does not necessarily fill in the entire thumbnail;
- crop - keeps the content at its original size and only displays a part of it, according to the thumbnail's size.
Note: Some filters will not work correctly with the scaleCrop and scale settings unless their refresh property is set to false (unchecked).
Note: For best results make sure the itemWidth and itemHeight match the actual thumbnail image width and height in pixels and use the "exactFit" scale mode.
The default value is exactFit.
Example
Set the component to display the thumbnails inside the items maintaining the scale:
myScroller.scaleMode = "maintainAspectRatio";
|
selectedIndex |
int yes |
Set or get the index of the selected item in the list. The index is 0-based, meaning that the index of the first item is 0, the index of the second item is 1 and the index of the last item is length - 1.
The default value is 0.
Example
Select the last thumbnail from the list:
myScroller.selectedIndex = myScroller.length - 1;
|
selectedItem |
ScrollerItemModel no |
[read-only] A reference to the currently selected item. The reference is of type ScrollerItemModel and contains details about the thumbnail. For details about the ScrollerItemModel class please refer to the section called Class ScrollerItemModel.
|
showLabels |
Boolean yes |
Specifies whether the labels associated to the items will be displayed or not. For horizontal thumbnail lists, the labels will be displayed below the thumbnails. For vertical thumbnail lists, the labels will be displayed next to the thumbnails, on their right side.
The default value is false.
|
source |
XML/String yes |
The xml data containing the list of images and their information. You can also set this property from the JCThumbViewer Panel, by pasting the xml data into the source text field.
You can also set up the component using external XML files by specifying the URL of the source XML file.
Example
myScroller.source = "mySource.xml";
or
myScroller.source = <source>
<item>
<src>image1.jpg</src>
...
</item>
<item>
...
</item>
</source>;
|
transitionDuration |
Number yes |
The amount of time (measured in seconds) that the transition effect will use to complete.
The default duration is 0.5.
|
tweenType |
String yes |
The type if tween used when sliding the list if thumbnails. Possible values are Back, Bounce, Circular, Cubic, Elastic, Exponential, Linear, Quadratic, Quartic, Quintic, Sine and Strong.
The default value is Strong.
|
useSlideShowNavigation |
Boolean yes |
Specifies whether to display the slide show controls or not. The slide show controls are play and pause buttons used to start or pause the slide show from within the component.
The default value is false.
|
Methods
Method |
Description |
addItem |
Adds a new item to the end of the list.
Parameters
- item:Object - the item that will be added to the list. The object passed as parameter should contain at least the URL of the external image of SWF file or the class name (linkage id) of the clip from the library as value of the property source.
Example
Add a new item to the list:
var obj:Object = new Object();
obj.source = "myImage.jpg";
obj.label = "Ia sa vedem";
myScroller.addItem(obj);
|
addItemAt |
Adds a new item to the list, in the position specified by the index parameter.
Parameters
- item:Object - the item that will be added to the list. The object passed as parameter should contain at least the URL of the external image of SWF file or the class name (linkage id) of the clip from the library as value of the property source.
- index:int - the index in the list where the item will be added. If index is less than 0, the new item will be added at the beginning. If index is greater than the total number of items, the new item will be added to the end of the list.
Example
Add a new item to the end of the list:
var obj:Object = new Object();
obj.source = "myImage.jpg";
obj.label = "Ia sa vedem";
myScroller.addItemAt(obj, myScroller.length);
|
clearSelection |
Deselects the currently selected item.
|
getItemAt |
Returns the item found at the index specified as parameter.
Parameters
- index:int - the position of the item in the list
Returns
- ScrollerItemModel - a reference to the item object found at the specified index or undefined if the item doesn't exist. For more information about the properties of the ScrollerItemModel class please see the section called Class ScrollerItemModel.
Example
Get the label of the last item in the list.
trace(myScroller.getItemAt(myScroller.length - 1).label);
|
getXmlSource |
Returns the XML object corresponding to the source of the items list.
Returns
- XML - the source XML object containing the list of items and their properties.
|
next |
Selects the next item from the list. If the item is not visible, the list will be scrolled.
|
previous |
Selects the previous item from the list. If the item is not visible, the list will be scrolled.
|
removeAll |
Removes all the thumbnails from the list.
|
removeItem |
Removes the specified item from the list.
Parameters
- item:ScrollItemModel - the item that will be removed from the list. You can get a reference to a ScrollItemModel object by calling the getItemAt() method.
Example
Remove the last item in the list.
var lastItemIndex:int = myScroller.length - 1;
myScroller.removeItem(myScroller.getItemAt(lastItemIndex));
|
removeItemAt |
Removes the item having the index specified as parameter.
Parameters
- index:int - the position in the list where the item will be removed from.
Example
Remove the last item in the list.
var lastItemIndex:int = myScroller.length - 1;
myScroller.removeItem(lastItemIndex);
|
setSize |
Sets the size for the thumbnail scroller component instance.
Parameters
- width:Number - the new width of the scroller component
- height:Number - the new height of the scroller component
|
Events
Event |
Description |
ASYNC_ERROR |
Dispatched after a AsyncErrorEvent.ASYNC_ERROR event has occurred while an item is loading.
Parameters
- text:String - the text displayed by the error message.
- item:Object - a reference to the item that generated the event.
|
CHANGE |
Dispatched when a new item is selected in the component, either by user interaction (clicking on an item) or by auto slide show (when autoPlay is set to true).
Example
Find out when another item has been selected (either by mouse click or by auto playing the slide show):
import com.jumpeye.Events.JCThumbViewerScrollerEvent;
myScroller.addEventListener( JCThumbViewerScrollerEvent.CHANGE, itemSelected);
function itemSelected(evt: JCThumbViewerScrollerEvent):void {
trace("The item with index "+ myScroller.selectedItem.index +" is now selected");
}
|
CONFIG_ASYNC_ERROR |
Dispatched after a AsyncErrorEvent.ASYNC_ERROR event has occurred while loading the configuration XML data.
Properties
- text:String - the text displayed by the error message.
|
CONFIG_IO_ERROR |
Dispatched after a IOErrorEvent.IO_ERROR event has occurred while the configuration XML data is loading.
Properties
- text:String - the text displayed by the error message.
|
CONFIG_LOAD_COMPLETE |
Dispatched after the configuration XML data has been completely loaded.
|
CONFIG_LOAD_START |
Dispatched when the thumbnail scroller starts loading the configuration XML data.
|
CONFIG_SECURITY_ERROR |
Dispatched when the configuration XML data cannot load because of a SecurityErrorEvent.SECURITY_ERROR event.
Properties
- text:String - the text displayed by the error message.
|
CONTENT_LOAD_COMPLETE |
Dispatched after the thumbnail scroller has loaded all of the items. If at least one of the items could not load, the event will not trigger, even if the next items were loaded successfully.
Example
Get the overall progress of the loading process:
import com.jumpeye.Events.JCThumbViewerScrollerEvent;
myScroller.addEventListener( JCThumbViewerScrollerEvent.CONTENT_LOAD_START, loadingStarted);
myScroller.addEventListener( JCThumbViewerScrollerEvent. CONTENT_LOAD_PROGRESS, loadingProgress);
myScroller.addEventListener( JCThumbViewerScrollerEvent. CONTENT_LOAD_COMPLETE, loadingComplete);
function loadingStarted(evt: JCThumbViewerScrollerEvent):void {
trace("Started loading the content");
}
function loadingProgress(evt: JCThumbViewerScrollerEvent):void {
trace("Loaded "+ evt.count +" items of "+ myScroller.length);
}
function loadingComplete(evt: JCThumbViewerScrollerEvent):void {
trace("All the items are now created and the content is loaded.");
}
|
CONTENT_LOAD_PROGRESS |
Dispatched during the loading process of all the items.
Parameters
- count:int - the number of items loaded so far.
Example
Get the overall progress of the loading process:
import com.jumpeye.Events.JCThumbViewerScrollerEvent;
myScroller.addEventListener( JCThumbViewerScrollerEvent.CONTENT_LOAD_START, loadingStarted);
myScroller.addEventListener( JCThumbViewerScrollerEvent. CONTENT_LOAD_PROGRESS, loadingProgress);
myScroller.addEventListener( JCThumbViewerScrollerEvent. CONTENT_LOAD_COMPLETE, loadingComplete);
function loadingStarted(evt: JCThumbViewerScrollerEvent):void {
trace("Started loading the content");
}
function loadingProgress(evt: JCThumbViewerScrollerEvent):void {
trace("Loaded "+ evt.count +" items of "+ myScroller.length);
}
function loadingComplete(evt: JCThumbViewerScrollerEvent):void {
trace("All the items are now created and the content is loaded.");
}
|
CONTENT_LOAD_START |
Dispatched when the thumbnail scroller starts loading the items (all of them).
Example
Get the overall progress of the loading process:
import com.jumpeye.Events.JCThumbViewerScrollerEvent;
myScroller.addEventListener( JCThumbViewerScrollerEvent.CONTENT_LOAD_START, loadingStarted);
myScroller.addEventListener( JCThumbViewerScrollerEvent. CONTENT_LOAD_PROGRESS, loadingProgress);
myScroller.addEventListener( JCThumbViewerScrollerEvent. CONTENT_LOAD_COMPLETE, loadingComplete);
function loadingStarted(evt: JCThumbViewerScrollerEvent):void {
trace("Started loading the content");
}
function loadingProgress(evt: JCThumbViewerScrollerEvent):void {
trace("Loaded "+evt.count+" items of "+ myScroller.length);
}
function loadingComplete(evt: JCThumbViewerScrollerEvent):void {
trace("All the items are now created and the content is loaded.");
}
|
INIT |
Dispatched after the thumbnail scroller has finished initializing.
|
IO_ERROR |
Dispatched after a IOErrorEvent.IO_ERROR event has occurred during loading process of an item. If one of the items could not load, the thumbnail scroller will continue to load the rest of the items.
Parameters
- text:String - the text displayed by the error message.
- item:Object - a reference to the item that generated the event.
Example
Find out if one of the items could not load:
import com.jumpeye.Events.JCThumbViewerScrollerEvent;
myScroller.addEventListener( JCThumbViewerScrollerEvent.IO_ERROR, itemLoadingError);
function itemLoadingError(evt: JCThumbViewerScrollerEvent):void {
trace("Error loading item with index "+ evt.item.index);
}
|
ITEM_LOAD_COMPLETE |
Dispatched after the thumbnail scroller has completely loaded the item.
Parameters
- item:Object - a reference to the item that generated the event.
Example
Let the users know how the loading process goes (how the content is loaded):
import com.jumpeye.Events.JCThumbViewerScrollerEvent;
myScroller.addEventListener( JCThumbViewerScrollerEvent.ITEM_LOAD_START, itemLoadingStarted);
myScroller.addEventListener( JCThumbViewerScrollerEvent.ITEM_LOAD_PROGRESS, itemLoadingProgress);
myScroller.addEventListener( JCThumbViewerScrollerEvent.ITEM_LOAD_COMPLETE, itemLoadingComplete);
function itemLoadingStarted(evt: JCThumbViewerScrollerEvent):void {
trace("Started loading item with index "+ evt.item.index);
}
function itemLoadingProgress(evt: JCThumbViewerScrollerEvent):void {
trace("Loaded "+evt.bytesLoaded+" / "+ evt.bytesTotal +" so far");
}
function itemLoadingComplete(evt: JCThumbViewerScrollerEvent):void {
trace("Item with index "+ evt.item.index +" has loaded");
}
|
ITEM_LOAD_PROGRESS |
Dispatched by the thumbnail scroller during the loading process of an item.
Parameters
- bytesLoaded:Number - the number of bytes loaded so far.
- bytesTotal:Number - the total amount of bytes of the content loading into the item.
- item:Object - a reference to the item that generated the event.
Example
Let the users know how the loading process goes (how the content is loaded):
import com.jumpeye.Events.JCThumbViewerScrollerEvent;
myScroller.addEventListener( JCThumbViewerScrollerEvent.ITEM_LOAD_START, itemLoadingStarted);
myScroller.addEventListener( JCThumbViewerScrollerEvent.ITEM_LOAD_PROGRESS, itemLoadingProgress);
myScroller.addEventListener( JCThumbViewerScrollerEvent.ITEM_LOAD_COMPLETE, itemLoadingComplete);
function itemLoadingStarted(evt: JCThumbViewerScrollerEvent):void {
trace("Started loading item with index "+evt.item.index);
}
function itemLoadingProgress(evt: JCThumbViewerScrollerEvent):void {
trace("Loaded "+evt.bytesLoaded+" / "+ evt.bytesTotal +" so far");
}
function itemLoadingComplete(evt: JCThumbViewerScrollerEvent):void {
trace("Item with index "+ evt.item.index +" has loaded");
}
|
ITEM_LOAD_START |
Dispatched when the thumbnail scroller starts loading an item.
Properties
- item:Object - a reference to the item that generated the event.
Example
Let the users know how the loading process goes (how the content is loaded):
import com.jumpeye.Events.JCThumbViewerScrollerEvent;
myScroller.addEventListener( JCThumbViewerScrollerEvent.ITEM_LOAD_START, itemLoadingStarted);
myScroller.addEventListener( JCThumbViewerScrollerEvent.ITEM_LOAD_PROGRESS, itemLoadingProgress);
myScroller.addEventListener( JCThumbViewerScrollerEvent.ITEM_LOAD_COMPLETE, itemLoadingComplete);
function itemLoadingStarted(evt: JCThumbViewerScrollerEvent):void {
trace("Started loading item with index "+ evt.item.index);
}
function itemLoadingProgress(evt: JCThumbViewerScrollerEvent):void {
trace("Loaded "+ evt.bytesLoaded +" / "+ evt.bytesTotal +" so far");
}
function itemLoadingComplete(evt: JCThumbViewerScrollerEvent):void {
trace("Item with index "+ evt.item.index +" has loaded");
}
|
ON_CLICK_ITEM |
Dispatched after the user clicks on one of the items.
Parameters
- item:Object - a reference to the item that received the click event.
Example
Know when an item has been selected (clicked) by the user:
import com.jumpeye.Events.JCThumbViewerScrollerEvent;
myScroller.addEventListener( JCThumbViewerScrollerEvent.ON_CLICK_ITEM, itemClicked);
function itemClicked(evt:JCThumbViewerScrollerEvent): void {
trace("The item with index "+ evt.item.index +" has been selected by the user");
}
|
SECURITY_ERROR |
Dispatched after a SecurityErrorEvent.SECURITY_ERROR event has occurred while an item is loading.
Parameters
- text:String - the text displayed by the error message.
- item:Object - a reference to the item that generated the event.
|
SOURCE_ASYNC_ERROR |
Dispatched after a AsyncErrorEvent.ASYNC_ERROR has occurred while loading the source XML data.
Properties
- text:String - the text displayed by the error message.
|
SOURCE_IO_ERROR |
Dispatched after a IOErrorEvent.IO_ERROR event has occurred while the source XML data is loading.
Properties
- text:String - the text displayed by the error message.
|
SOURCE_LOAD_COMPLETE |
Dispatched after the XML data containing the list of items has been completely loaded.
|
SOURCE_LOAD_START |
Dispatched when the thumbnail scroller starts loading the XML data containing the list of items.
|
SOURCE_SECURITY_ERROR |
Dispatched when the source XML data cannot load because of a SecurityErrorEvent.SECURITY_ERROR event.
Properties
- text:String - the text displayed by the error message.
|
Class ScrollerItemModel
Property |
Type |
Description |
callFunction |
Boolean |
Specifies whether there will be a function called when the item is selected.
|
callFunctionParameters |
Array |
A list of parameters passed to the function called when the item is selected.
|
content |
* |
The content associated to the item.
|
frame |
Number |
The frame number where the playhead will navigate when the function is selected.
|
functionName |
String |
The name of the function that will be called when the item is selected.
|
gotoFrameAction |
Boolean |
Specifies whether the Flash application will navigate to a specified frame when the item is selected.
|
index |
Number |
The index of the item in the thumbnail scroller's list.
|
label |
String |
The label corresponding to the item.
|
navigateToUrlAction |
Boolean |
Specifies whether a URL will be opened when the item is selected.
|
selected |
Boolean |
Specified whether the thumbnail scroller item is selected or not.
|
source |
String |
The source of the content loaded into the item. It can be the URL of an external image or SWF file or the class name (linkage id) of a clip from the library.
|
target |
String |
The target window where the URL will be opened if navigateToURL is called when the item is selected.
|
url |
String |
The URL that will be opened if navigateToURL is called when the item is selected.
|
The configuration XML structure
The configuration XML contains two nodes that represent the list of values for the component properties and the list of FlashEff2 filters and button effect patterns applied on the items.
<config>
<params>
...
</params>
<patterns>
...
</patterns>
</config>
The property values are specified as XML nodes having the same name as the component properties you want to set (<autoPlay>, <navigationType>, <scaleMode>, <toggle> and so on). Each property node has two more nodes: one node (<type>) specifies the type of the property (Boolean, String, Number, int or uint) and the other node (<value>) specifies the value for the component property. You cannot set Array or XML type of properties or read-only properties and you should only specify those component properties you want to set from the configuration XML.
<autoPlay>
<type>Boolean</type>
<value>true</value>
</autoPlay>
|
or |
<navigationType>
<type>String</type>
<value>scrollBar</value>
</navigationType>
|
The patterns node contains the list of filters applied over each item (like the reflection filter) and also button effect patterns that allow different up, over, down and selected states for the items.
The best way to get the XML structure of a list of patterns is to apply the filters and button effects using the JCThumbViewer Panel. Then, using the Copy button, copy the generated XML into the clipboard and paste it into a text editor. From that XML, simply select the <patterns> node with all of its contents and use it in your own configuration XML.
The source XML structure
The source XML contains a list of item nodes, each item node having extra child nodes representing the URL for their contents, text for the labels, any other extra parameters the user might need and also a set or parameters for the display object (for example a LoaderProV3AS3, JCLoader or JCPlayer component) specified at the _targetInstanceName property (this display object could load a larger version of the content - image, audio/video or another Flash animation).
<source>
<item>
<source>image1.jpg</source>
<label>Image 1</label>
<someOtherProperty>someValue</someOtherProperty>
<data>
<source>large_image1.jpg</source>
</data>
<actions>
<gotoFrame>
<frame>23</frame>
</gotoFrame>
<callFunction>
<function>myCallFunction(param1, param2, param3)</function>
</callFunction>
</actions>
</item>
<ite>
<source>image2.jpg</source>
<label>Image 2</label>
<action>
<navigateToURL>
<url>http://www.jumpeyecomponents.com</url>
<target>_blank</target>
</navigateToURL>
</action>
</item>
...
<item>
<source>image10.jpg</source>
<label>Image 10</label>
<data>
<source>flashAnimation.swf</source>
</data>
</item>
</source>
The <item> node
The <item> node contains all the information regarding each item displayed by the component.
<source>
This node contains the URL of the image or .swf file that will be loaded into the items as thumbnails. If it is not specified, the item will be displayed without any content inside it.
<label>
This node contains the text displayed for the items - below the items if direction is set to "horizontal" or in the right side of the items if direction is set to "vertical". If it is not specified, the item will not display a label if the showLabels property of the JCThumbViewerScroller component is set to true.
<actions>
This node contains one or more nodes representing the actions that should be executed when the corresponding item from the list is selected. Possible actions are open a specified URL, move the playhead to a specific frame number and execute a specified function.
Open a URL
For this, you need to add the <navigateToURL> node to the <actions> node where you will specify, using the <url> node, the URL that will be opened and, using the <target> node, the window into which it will be opened (possible values for <target> are _blank, _self, _parent, _top or the name of an HTML frame):
<navigateToURL>
<url>http://www.jumpeyecomponents.com</url>
<target>_blank</target>
</navigateToURL>
Navigate to a specific frame in the timeline
This action actually calls the gotoAndPlay() method and moves the playhead to the specified frame number on the timeline. You can only specify frame numbers and not frame labels:
<gotoFrame>
<frame>5</frame>
</gotoFrame>
Execute a specified function
In this case a user function will be executed by the component. The function must already be declared by the time the corresponding item is selected. You can also specify parameters for the declared function and you can use parameters of different type (String, Boolean, Number):
<callFunction>
<function>myCallFunction(param1, param2)</function>
</callFunction>
<data>
This node contains other properties that will be set to the display object specified with _targetInstanceName. For example, in case you would use the JCLoader component to load larger images, you could specify the URL of the large image for the source property of the JCLoader instance. Also, you could specify a new size for that loader and maybe a new scale mode:
<data>
<sourc>myLargeImage.jpg</source>
<width>400</width>
<height>300</height>
<scaleMode>scaleCrop</scaleMode>
</data>
Besides these nodes, you can also specify other nodes representing extra properties for the items in the list, like extra descriptions for images (in which case you could use label as titles), prices displayed over the large images if the list would represent items from an online store or simply some other information you could use to execute different actions in your Flash application.
<item>
<source>myThumbnailImage1.jpg</source>
<label>My photo</label>
<description>This is some description of the image</description>
<type>image</type>
<largeImage>myLargeImage.jpg</largeImage>
</item>
<item>
<source>myThumbnailImage2.jpg</source>
<label>My video</label>
<description>This is some description of the video</description>
<type>video</type>
<videoSource>myVideo.flv</videoSource>
</item>
These extra nodes will be then added as properties to the items and you can then retrieve their values: myScroller.selectedItem.description or myScroller.selectedItem.type.
This way, by verifying the value of the node <type> (actually by checking the type property added to the item), you could load the larger image or video into a different loader component: load the image into a simple loader and the video into a video player component, showing or hiding the appropriate component, according to the value of the type property.
Use JCThumbViewerDock by Code
Here are the steps you need to follow in order to use the JCThumbViewerDock component with ActionScript 3.0 code:
1. Create a new Flash ActionScript 3.0 file and set its frame rate to 30 fps. Open up the Components panel (Ctrl + F7 for Windows or Command + F7 for Mac), select the JCThumbViewerDock component and drag it over the Library panel. Next, bring up the Actions panel (F9 for Windows or Option + F9 for Mac) and paste the following lines of code inside it.
2. Import the necessary classes for the JCThumbViewerDock component and the JCThumbViewerDock events class (JCThumbViewerDockEvent):
import com.jumpeye.events.JCThumbViewerDockEvent;
import JCThumbViewerDock;
3. Create and set up the JCThumbViewerDock instance:
var myDock:JCThumbViewerDock = new JCThumbViewerDock();
myDock.x = 20;
myDock.y = 20;
myDock.setSize(510, 200);
myDock.showLabels = true;
myDock.scaleMode = "scaleCrop";
addChild(myDock);
4. Listen for events triggered by the component:
myDock.addEventListener(JCThumbViewerDockEvent.CONTENT_LOAD_PROGRESS, loadingProgress);
function loadingProgress(evt:JCThumbViewerDockEvent):void {
trace("Loaded "+evt.count+" items of "+myDock.length);
}
myDock.addEventListener(JCThumbViewerDockEvent.IO_ERROR, itemLoadingError);
function itemLoadingError(evt:JCThumbViewerDockEvent):void {
trace("Error loading item with index "+evt.item.index);
}
myDock.addEventListener(JCThumbViewerDockEvent.CHANGE, itemSelected);
function itemSelected(evt:JCThumbViewerDockEvent):void {
trace("The item with index "+myDock.selectedItem.index+" is now selected");
}
5. Set the source property of the component. Once you set the source property, the JCThumbViewerDock component will start loading the content:
myDock.source = "source.xml";
6. Compile the application by hitting Ctrl + Enter for Windows or Cmd + Enter for Mac.
Properties
Property |
Type JCThumbViewer Panel |
Description |
_targetInstanceName |
String yes |
The instance name of the target display object that will load the large images, video or other content associated to the items. That display object will act as a loader.
|
alignMode |
String yes |
The type of horizontal and vertical alignment used for the content. Possible values are topLeft, topMiddle, topRight, centerLeft, centerMiddle, centerRight, bottomLeft, bottomMiddle, bottomRight.
The default value is topLeft.
Example
Center the content (thumbnail images) inside the items:
myDock.alignMode = "centerMiddle";
|
applyEffectOn |
String yes |
Specifies on which items the transition effect should be applied. Possible values:
- onVisibleItems - applies the transition effects only on the visible items
- onAllItems - applies the transition effects on all the items of the list
Depending on the type of transition, this property has the effect of making the component use more or less memory and CPU time. For the transition effects of roll and fade we recommend using the onVisibleItems value. For the rest of the transition effects, you should use the onAllItems value. This way you can make sure that the component always uses as less memory as possible during the transitions.
The default value is onAllItems.
Example
Change the transition type and the items it is applied on:
myDock.transitionEffect = "fade";
myDock.applyEffectOn = "onVisibleItems";
|
autoPlay |
Boolean yes |
Specifies whether the component will automatically play a slide show by consecutively selecting the items. Once the last item from the page has been selected and the slide show delay has passed, the component will load the next thumbnails page.
If _targetInstanceName is set, the thumbnail dock will automatically set the target display object's source property to load the content associated to the selected item.
The default value is false.
Example
Set the dock to automatically start the slide show:
myDock.autoPlay = true;
|
autoPlayDelay |
Number yes |
The time interval measured in seconds when the slide show will change the selected item. The thumbnail page will also be changed, after the last displayed item is selected.
The default value is 5 seconds.
Example
Make the slide show play faster:
myDock.autoPlayDelay = 2;
|
config |
XML/String no |
Sets the configuration xml for the component. In this case the component will be set up using the values in the xml data and will disregard any previous settings made from the panel or by using code.
You can also set up the component using external configuration XML files. In this case you need to specify the URL to that configuration XML file.
Example
myDock.config = "myConfig.xml";
or
myDock.config = <config>
<params>
<autoPlay>
<type>Boolean</type>
<value>true</value>
</autoPlay>
...
</params>
<patterns>
...
</patterns>
</config>;
|
currentPage |
int yes |
The 0 based index (the first page is 0, the second page is 1 and so on) of the page currently displayed by the component. You can also change the page by setting a new value to this property.
The default value is 0.
Example
Change the page to the last one:
myDock.currentPage = myDock.totalPages - 1;
|
direction |
String yes |
The way the items will be displayed in the dock. Possible values are horizontal and vertical.
The default value is horizontal.
Example
Set the items to be displayed vertically:
myDock.direction = "vertical";
|
easeType |
String yes |
The type of easing used by the animations that change the thumbnails page of the component. Possible values are easeIn, easeOut, easeInOut and easeNone.
The default value is easeOut.
Example
Change the easing to easeInOut:
myDock.easeType = "easeInOut";
|
horizontalMargins |
Number yes |
The spacing between the left margin of the component (including the navigation button) and the left margin of the list of items (the left margin of the first item) and the spacing between the right margin of the component (including the navigation button) and the right margin of the list of items (the right margin of the last item if direction is set to "horizontal"). The right side spacing is displayed when the list of items scrolls to the end.
If showLabels is set to true and direction is set to "vertical" the right margin is between the right margin of the items including the labels (if there are any) and the right margin of the component. In this case the right margin is displayed only if the width of the component is large enough to include the width of the items (including the labels, if there are any) and the two horizontal margins.
Note: For a value of 0, the items are aligned at the left margin of the component and any visual effects added to the exterior of the items (like a glow filter) will not be displayed on the left margin, unless the horizontal margins are increased.
The default value is 5.
Example
Set the horizontal margins to 10 pixels:
myDock.horizontalMargins = 10;
|
itemHeight |
Number yes |
The height of the thumbnails measured in pixels.
Note: For best results make sure the itemHeight matches the actual thumbnail image height in pixels and use the "exactFit" scale mode.
The default value is 100.
|
items |
Array no |
[read-only] The list of objects representing the references to the thumbnails. Each object is of type DockItemModel. For details about the DockItemModel class please refer to the section called Class DockItemModel.
|
itemSpace |
Number yes |
The size of the space between the thumbnails.
The default value is 5.
|
itemWidth |
Number yes |
The width of the items measured in pixels.
Note: For best results make sure the itemWidth matches the actual thumbnail image width in pixels and use the "exactFit" scale mode.
The default value is 100.
|
length |
int no |
[read-only] The number of items in the list.
|
scaleMode |
String yes |
The type of scaling applied on the content of the items (thumbnails). Possible values:
- scaleCrop - scales the content so it fills in the entire size of the thumbnail and then crops the parts of the content that do not fit;
- exactFit - resizes the content so that it takes the same size as the thumbnail - may distort the content if the thumbnail does not have the same size as the content;
- maintainAspectRatio - scales the content so that it fits entirely inside the thumbnail - does not necessarily fill in the entire thumbnail;
- crop - keeps the content at its original size and only displays a part of it, according to the thumbnail's size.
Note: Some filters will not work correctly with the scaleCrop and scale settings unless their refresh property is set to false (unchecked).
Note: For best results make sure the itemWidth and itemHeight match the actual thumbnail image width and height in pixels and use the "exactFit" scale mode.
The default value is exactFit.
Example
Set the component to display the thumbnails inside the items maintaining the scale:
myDock.scaleMode = "maintainAspectRatio";
|
selectedIndex |
int yes |
Set or get the index of the selected item in the list. The index is 0-based, meaning that the index of the first item is 0, the index of the second item is 1 and the index of the last item is length - 1.
The default value is 0.
Example
Select the last thumbnail from the list:
myDock.selectedIndex = myDock.length - 1;
|
selectedItem |
DockItemModel no |
[read-only] A reference to the currently selected item. The reference is of type DockItemModel and contains details about the thumbnail. For details about the DockItemModel class please refer to the section called Class DockItemModel.
|
showLabels |
Boolean yes |
Specifies whether the labels associated to the items will be displayed or not. For horizontal thumbnail lists, the labels will be displayed below the thumbnails. For vertical thumbnail lists, the labels will be displayed next to the thumbnails, on their right side.
The default value is false.
|
source |
XML/String yes |
The xml data containing the list of images and their information. You can also set this property from the JCThumbViewer Panel, by pasting the xml data into the source text field.
You can also set up the component using external XML files by specifying the URL of the source XML file.
Example
myDock.source = "mySource.xml";
or
myDock.source = <source>
<item>
<src>image1.jpg</src>
...
</item>
<item>
...
</item>
</source>;
|
totalPages |
int no |
[read-only] The total number of thumbnail pages. The last page may contain less items than the other pages.
The number of pages depends on the total number of items (please see the length property) and the number of items displayed in one page. This number of items per page is calculated according to the space the items have to be displayed.
|
transitionDuration |
Number yes |
The amount of time (measured in seconds) that the transition effect will use to complete.
The default duration is 0.5.
|
transitionEffect |
String yes |
The transition effect used by the component to change the thumbnail pages. The transition effects are applied on each item separately. Possible values:
- slide - slides the next page of thumbnails into view from right to left if direction is set to horizontal or from bottom to top if direction is set to vertical
- roll - slides the next page of thumbnails into view from right to left if direction is set to vertical and from bottom to top if direction is set to horizontal
- fade - applies an alpha fade effect to show the new thumbnail page; the effect is applied on each item separately
- none - loads the new thumbnail page without using any transition effect
The transition effect depends on the onTransitionStartEvent parameter: if it is set to onItemTransitionEnd, each transition effect will start after the previous transition effect has finished; if it is set to onPageTransitionEnd, the new thumbs will transition in, after the previous page of thumbs has transitioned out.
The default value is roll.
|
transitionEffectItemDelay |
Number yes |
The delay (measured in seconds) between the transition effects for each item. This delay is applied from the moment one item starts to transition out until the next item in the page starts to transition out.
The default value is 0.1.
|
transitionStartEvent |
String yes |
Specifies the moment when the next page of items starts to transition into the view. Possible values:
- onItemTransitionEnd - the next items start transitioning in after each previous item has transitioned out;
- onPageTransitionEnd - the next items start transitioning in after all the previous item have transitioned out
The default value is onItemTransitionEnd.
Example
Show the next page of thumbnails only after the previous page has finished transitioning out:
myDock.transitionStartEvent = "onPageTransitionEnd";
|
tweenType |
String yes |
The type if tween used when sliding the list if thumbnails. Possible values are Back, Bounce, Circular, Cubic, Elastic, Exponential, Linear, Quadratic, Quartic, Quintic, Sine and Strong.
The default value is Strong.
|
useSlideShowNavigation |
Boolean yes |
Specifies whether to display the slide show controls or not. The slide show controls are play and pause buttons used to start or pause the slide show from within the component.
The default value is false.
|
verticalMargins |
Number yes |
The space left between the top margin of the component (including the navigation button) and the top margin of the items. The bottom spacing is displayed only if the height of the thumbnail dock is large enough to include the items with their largest height (including the labels, if there are any) and the two vertical margins.
Note: For a value of 0, the items are aligned right at the top of the component and any visual effects added to the exterior of the items (like a glow filter) will not be displayed on the top margin, unless the vertical margins are increased.
The default value is 5.
Example
Set the vertical margins to 10 pixels:
myDock.verticalMargins = 10;
|
Methods
Method |
Description |
addItem |
Adds a new item to the end of the list.
Parameters
- item:Object - the item that will be added to the list. The object passed as parameter should contain at least the URL of the external image of SWF file or the class name (linkage id) of the clip from the library as value of the property source.
Example
Add a new item to the list:
var obj:Object = new Object();
obj.source = "myImage.jpg";
obj.label = "Ia sa vedem";
myDock.addItem(obj);
|
addItemAt |
Adds a new item to the list, in the position specified by the index parameter.
Parameters
- item:Object - the item that will be added to the list. The object passed as parameter should contain at least the URL of the external image of SWF file or the class name (linkage id) of the clip from the library as value of the property source.
- index:int - the index in the list where the item will be added. If index is less than 0, the new item will be added at the beginning. If index is greater than the total number of items, the new item will be added to the end of the list.
Example
Add a new item to the end of the list:
var obj:Object = new Object();
obj.source = "myImage.jpg";
obj.label = "Ia sa vedem";
myDock.addItemAt(obj, myDock.length);
|
clearSelection |
Deselects the currently selected item.
|
getItemAt |
Returns the item found at the index specified as parameter.
Parameters
- index:int - the position of the item in the list
Returns
- DockItemModel - a reference to the item object found at the specified index or undefined if the item doesn't exist. For more information about the properties of the DockItemModel class please see the section called Class DockItemModel.
Example
Get the label of the last item in the list.
trace(myDock.getItemAt(myDock.length - 1).label);
|
getXmlSource |
Returns the XML object corresponding to the source of the items list.
Returns
- XML - the source XML object containing the list of items and their properties.
|
next |
Selects the next item from the list. If the item is not visible, the list will be scrolled. This method disregards the transition effect set on the component and only slides the items one by one.
|
nextPage |
Displays the next page of thumbnails using the transition effect set using the transitionEffect property.
|
previous |
Selects the previous item from the list. If the item is not visible, the list will be scrolled. This method disregards the transition effect set on the component and only slides the items one by one.
|
previousPage |
Displays the previous page of thumbnails using the transition effect set using the transitionEffect property.
|
removeAll |
Removes all the thumbnails from the list.
|
removeItem |
Removes the specified item from the list.
Parameters
- item:DockItemModel - the item that will be removed from the list. You can get a reference to a DockItemModel object by calling the getItemAt() method.
Example
Remove the last item in the list.
var lastItemIndex:int = myDock.length - 1;
myDock.removeItem(myDock.getItemAt(lastItemIndex));
|
removeItemAt |
Removes the item having the index specified as parameter.
Parameters
- index:int - the position in the list where the item will be removed from.
Example
Remove the last item in the list.
var lastItemIndex:int = myDock.length - 1;
myDock.removeItem(lastItemIndex);
|
setSize |
Sets the size for the thumbnail dock component instance.
Parameters
- width:Number - the new width of the component
- height:Number - the new height of the component
|
Events
Event |
Description |
ASYNC_ERROR |
Dispatched after a AsyncErrorEvent.ASYNC_ERROR event has occurred while an item is loading.
Parameters
- text:String - the text displayed by the error message.
- item:Object - a reference to the item that generated the event.
|
CHANGE |
Dispatched when a new item is selected in the component, either by user interaction (clicking on an item), by auto slide show (when autoPlay is set to true) or by calling the next()/previous() methods.
Example
Find out when another item has been selected (either by mouse click, by auto playing the slide show or by calling the next()/previous() methods):
import com.jumpeye.events.JCThumbViewerDockEvent;
myDock.addEventListener(JCThumbViewerDockEvent. CHANGE, itemSelected);
function itemSelected(evt:JCThumbViewerDockEvent): void {
trace("The item with index "+ myDock.selectedItem.index +" is now selected");
}
|
CONFIG_ASYNC_ERROR |
Dispatched after a AsyncErrorEvent.ASYNC_ERROR event has occurred while loading the configuration XML data.
Parameters
- text:String - the text displayed by the error message.
|
CONFIG_IO_ERROR |
Dispatched after a IOErrorEvent.IO_ERROR event has occurred while the configuration XML data is loading.
Parameters
- text:String - the text displayed by the error message.
|
CONFIG_LOAD_COMPLETE |
Dispatched after the configuration XML data has been completely loaded.
|
CONFIG_LOAD_START |
Dispatched when the thumbnail dock starts loading the configuration XML data.
|
CONFIG_SECURITY_ERROR |
Dispatched when the configuration XML data cannot load because of a SecurityErrorEvent.SECURITY_ERROR event.
Parameters
- text:String - the text displayed by the error message.
|
CONTENT_LOAD_COMPLETE |
Dispatched after the thumbnail dock has loaded all of the items. If at least one of the items could not load, the event will not trigger, even if the next items were loaded successfully.
Example
Get the overall progress of the loading process:
import com.jumpeye.events.JCThumbViewerDockEvent;
myDock.addEventListener(JCThumbViewerDockEvent. CONTENT_LOAD_START, loadingStarted);
myDock.addEventListener(JCThumbViewerDockEvent. CONTENT_LOAD_PROGRESS, loadingProgress);
myDock.addEventListener(JCThumbViewerDockEvent. CONTENT_LOAD_COMPLETE, loadingComplete);
function loadingStarted(evt:JCThumbViewerDockEvent): void {
trace("Started loading the content");
}
function loadingProgress(evt:JCThumbViewerDockEvent): void {
trace("Loaded "+ evt.count +" items of "+ myDock.length);
}
function loadingComplete(evt:JCThumbViewerDockEvent): void {
trace("All the items are now created and the content is loaded.");
}
|
CONTENT_LOAD_PROGRESS |
Dispatched during the loading process of all the items.
Parameters
- count:int - the number of items loaded so far.
Example
Get the overall progress of the loading process:
import com.jumpeye.events.JCThumbViewerDockEvent;
myDock.addEventListener(JCThumbViewerDockEvent. CONTENT_LOAD_START, loadingStarted);
myDock.addEventListener(JCThumbViewerDockEvent. CONTENT_LOAD_PROGRESS, loadingProgress);
myDock.addEventListener(JCThumbViewerDockEvent. CONTENT_LOAD_COMPLETE, loadingComplete);
function loadingStarted(evt:JCThumbViewerDockEvent): void {
trace("Started loading the content");
}
function loadingProgress(evt:JCThumbViewerDockEvent): void {
trace("Loaded "+ evt.count +" items of "+ myDock.length);
}
function loadingComplete(evt:JCThumbViewerDockEvent): void {
trace("All the items are now created and the content is loaded.");
}
|
CONTENT_LOAD_START |
Dispatched when the thumbnail dock starts loading the items (all of them).
Example
Get the overall progress of the loading process:
import com.jumpeye.events.JCThumbViewerDockEvent;
myDock.addEventListener(JCThumbViewerDockEvent. CONTENT_LOAD_START, loadingStarted);
myDock.addEventListener(JCThumbViewerDockEvent. CONTENT_LOAD_PROGRESS, loadingProgress);
myDock.addEventListener(JCThumbViewerDockEvent. CONTENT_LOAD_COMPLETE, loadingComplete);
function loadingStarted(evt:JCThumbViewerDockEvent): void {
trace("Started loading the content");
}
function loadingProgress(evt:JCThumbViewerDockEvent): void {
trace("Loaded "+ evt.count +" items of "+ myDock.length);
}
function loadingComplete(evt:JCThumbViewerDockEvent): void {
trace("All the items are now created and the content is loaded.");
}
|
INIT |
Dispatched after the thumbnail dock has finished initializing.
|
IO_ERROR |
Dispatched after a IOErrorEvent.IO_ERROR event has occurred during loading process of an item. If one of the items could not load, the thumbnail dock will continue to load the rest of the items.
Parameters
- text:String - the text displayed by the error message.
- item:Object - a reference to the item that generated the event.
Example
Find out if one of the items could not load:
import com.jumpeye.events.JCThumbViewerDockEvent;
myDock.addEventListener(JCThumbViewerDockEvent. IO_ERROR, itemLoadingError);
function itemLoadingError(evt:JCThumbViewerDockEvent): void {
trace("Error loading item with index "+ evt.item.index);
}
|
ITEM_LOAD_COMPLETE |
Dispatched after the thumbnail dock has completely loaded the item.
Parameters
- item:Object - a reference to the item that generated the event.
Example
Let the users know how the loading process goes (how the content is loaded):
import com.jumpeye.events.JCThumbViewerDockEvent;
myDock.addEventListener( JCThumbViewerDockEvent.ITEM_LOAD_START, itemLoadingStarted);
myDock.addEventListener( JCThumbViewerDockEvent.ITEM_LOAD_PROGRESS, itemLoadingProgress);
myDock.addEventListener( JCThumbViewerDockEvent.ITEM_LOAD_COMPLETE, itemLoadingComplete);
function itemLoadingStarted(evt: JCThumbViewerDockEvent): void {
trace("Started loading item with index "+ evt.item.index);
}
function itemLoadingProgress(evt: JCThumbViewerDockEvent): void {
trace("Loaded "+ evt.bytesLoaded +" / "+ evt.bytesTotal +" so far");
}
function itemLoadingComplete(evt: JCThumbViewerDockEvent): void {
trace("Item with index "+ evt.item.index +" has loaded");
}
|
ITEM_LOAD_PROGRESS |
Dispatched by the thumbnail dock during the loading process of an item.
Parameters
- bytesLoaded:Number - the number of bytes loaded so far.
- bytesTotal:Number - the total amount of bytes of the content loading into the item.
- item:Object - a reference to the item that generated the event.
Example
Let the users know how the loading process goes (how the content is loaded):
import com.jumpeye.events.JCThumbViewerDockEvent;
myDock.addEventListener( JCThumbViewerDockEvent.ITEM_LOAD_START, itemLoadingStarted);
myDock.addEventListener( JCThumbViewerDockEvent.ITEM_LOAD_PROGRESS, itemLoadingProgress);
myDock.addEventListener( JCThumbViewerDockEvent.ITEM_LOAD_COMPLETE, itemLoadingComplete);
function itemLoadingStarted(evt: JCThumbViewerDockEvent): void {
trace("Started loading item with index "+ evt.item.index);
}
function itemLoadingProgress(evt: JCThumbViewerDockEvent): void {
trace("Loaded "+ evt.bytesLoaded +" / "+ evt.bytesTotal +" so far");
}
function itemLoadingComplete(evt: JCThumbViewerDockEvent): void {
trace("Item with index "+ evt.item.index +" has loaded");
}
|
ITEM_LOAD_START |
Dispatched when the thumbnail dock starts loading an item.
Parameters
- item:Object - a reference to the item that generated the event.
Example
Let the users know how the loading process goes (how the content is loaded):
import com.jumpeye.events.JCThumbViewerDockEvent;
myDock.addEventListener( JCThumbViewerDockEvent.ITEM_LOAD_START, itemLoadingStarted);
myDock.addEventListener( JCThumbViewerDockEvent.ITEM_LOAD_PROGRESS, itemLoadingProgress);
myDock.addEventListener( JCThumbViewerDockEvent.ITEM_LOAD_COMPLETE, itemLoadingComplete);
function itemLoadingStarted(evt: JCThumbViewerDockEvent): void {
trace("Started loading item with index "+ evt.item.index);
}
function itemLoadingProgress(evt: JCThumbViewerDockEvent): void {
trace("Loaded "+ evt.bytesLoaded +" / "+ evt.bytesTotal +" so far");
}
function itemLoadingComplete(evt: JCThumbViewerDockEvent): void {
trace("Item with index "+ evt.item.index +" has loaded");
}
|
ON_CLICK_ITEM |
Dispatched after the user clicks on one of the items.
Parameters
- item:Object - a reference to the item that received the click event.
Example
Know when an item has been selected (clicked) by the user:
import com.jumpeye.events.JCThumbViewerDockEvent;
myDock.addEventListener(JCThumbViewerDockEvent. ON_CLICK_ITEM, itemClicked);
function itemClicked(evt:JCThumbViewerDockEvent): void {
trace("The item with index "+ evt.item.index +" has been selected by the user");
}
|
PAGE_CHANGE |
Dispatched when a new page of thumbnails has been displayed either by using the navigation buttons, by auto slide show (when autoPlay is set to true) or by calling the nextPage()/previousPage() methods.
Example
Find out when another the page has been changed (either by mouse click, by auto playing the slide show or by calling the nextPage()/previousPage() methods):
import com.jumpeye.events.JCThumbViewerDockEvent;
myDock.addEventListener(JCThumbViewerDockEvent. PAGE_CHANGE, pageChanged);
function pageChanged (evt: JCThumbViewerDockEvent): void {
trace("The current page is "+ myDock.currentPage);
}
|
SECURITY_ERROR |
Dispatched after a SecurityErrorEvent.SECURITY_ERROR event has occurred while an item is loading.
Parameters
- text:String - the text displayed by the error message.
- item:Object - a reference to the item that generated the event.
|
SOURCE_ASYNC_ERROR |
Dispatched after a AsyncErrorEvent.ASYNC_ERROR has occurred while loading the source XML data.
Parameters
- text:String - the text displayed by the error message.
|
SOURCE_IO_ERROR |
Dispatched after a IOErrorEvent.IO_ERROR event has occurred while the source XML data is loading.
Parameters
- text:String - the text displayed by the error message.
|
SOURCE_LOAD_COMPLETE |
Dispatched after the XML data containing the list of items has been completely loaded.
|
SOURCE_LOAD_START |
Dispatched when the thumbnail dock starts loading the XML data containing the list of items.
|
SOURCE_SECURITY_ERROR |
Dispatched when the source XML data cannot load because of a SecurityErrorEvent.SECURITY_ERROR event.
Parameters
- text:String - the text displayed by the error message.
|
Class DockItemModel
Property |
Type |
Description |
callFunction |
Boolean |
Specifies whether there will be a function called when the item is selected.
|
callFunctionParameters |
Array |
A list of parameters passed to the function called when the item is selected.
|
content |
* |
The content associated to the item.
|
frame |
Number |
The frame number where the playhead will navigate when the function is selected.
|
functionName |
String |
The name of the function that will be called when the item is selected.
|
gotoFrameAction |
Boolean |
Specifies whether the Flash application will navigate to a specified frame when the item is selected.
|
index |
Number |
The index of the item in the thumbnail scroller's list.
|
label |
String |
The label corresponding to the item.
|
navigateToUrlAction |
Boolean |
Specifies whether a URL will be opened when the item is selected.
|
selected |
Boolean |
Specified whether the thumbnail scroller item is selected or not.
|
source |
String |
The source of the content loaded into the item. It can be the URL of an external image or SWF file or the class name (linkage id) of a clip from the library.
|
target |
String |
The target window where the URL will be opened if navigateToURL is called when the item is selected.
|
url |
String |
The URL that will be opened if navigateToURL is called when the item is selected.
|
The Configuration XML Structure
The configuration XML contains two nodes that represent the list of values for the component properties and the list of FlashEff2 filters and button effect patterns applied on the items.
<config>
<params>
...
</params>
<patterns>
...
</patterns>
</config>
The property values are specified as XML nodes having the same name as the component properties you want to set (<autoPlay>, <navigationType>, <scaleMode>, <toggle> and so on). Each property node has two more nodes: one node (<type>) specifies the type of the property (Boolean, String, Number, int or uint) and the other node (<value>) specifies the value for the component property. You cannot set Array or XML type of properties or read-only properties and you should only specify those component properties you want to set from the configuration XML.
<autoPlay>
<type>Boolean</type>
<value>true</value>
</autoPlay>
|
or |
<navigationType>
<type>String</type>
<value>scrollBar</value>
</navigationType>
|
The patterns node contains the list of filters applied over each item (like the reflection filter) and also button effect patterns that allow different up, over, down and selected states for the items.
The best way to get the XML structure of a list of patterns is to apply the filters and button effects using the JCThumbViewer Panel. Then, using the Copy button, copy the generated XML into the clipboard and paste it into a text editor. From that XML, simply select the <patterns> node with all of its contents and use it in your own configuration XML.
The Source XML Structure
The source XML contains a list of item nodes, each item node having extra child nodes representing the URL for their contents, text for the labels, any other extra parameters the user might need and also a set or parameters for the display object (for example a LoaderProV3AS3, JCLoader or JCPlayer component) specified at the _targetInstanceName property (this display object could load a larger version of the content - image, audio/video or another Flash animation).
<source>
<item>
<source>image1.jpg</source>
<label>Image 1</label>
<someOtherProperty>someValue</someOtherProperty>
<data>
<source>large_image1.jpg</source>
</data>
<actions>
<gotoFrame>
<frame>23</frame>
</gotoFrame>
<callFunction>
<function>myCallFunction(param1, param2, param3)</function>
</callFunction>
</actions>
</item>
<item>
<source>image2.jpg</source>
<label>Image 2</label>
<action>
<navigateToURL>
<url>http://www.jumpeyecomponents.com</url>
<target>_blank</target>
</navigateToURL>
</action>
</item>
...
<item>
<source>image10.jpg</source>
<label>Image 10</label>
<data>
<source>flashAnimation.swf</source>
</data>
</item>
</source>
The <item> node
The <item> node contains all the information regarding each item displayed by the component.
<source>
This node contains the URL of the image or .swf file that will be loaded into the items as thumbnails. If it is not specified, the item will be displayed without any content inside it.
<label>
This node contains the text displayed for the items - below the items if direction is set to "horizontal" or in the right side of the items if direction is set to "vertical". If it is not specified, the item will not display a label if the showLabels property of the JCThumbViewerScroller component is set to true.
<actions>
This node contains one or more nodes representing the actions that should be executed when the corresponding item from the list is selected. Possible actions are open a specified URL, move the playhead to a specific frame number and execute a specified function.
Open a URL
For this, you need to add the <navigateToURL> node to the <actions> node where you will specify, using the <url> node, the URL that will be opened and, using the <target> node, the window into which it will be opened (possible values for <target> are _blank, _self, _parent, _top or the name of an HTML frame):
<navigateToURL>
<url>http://www.jumpeyecomponents.com</url>
<target>_blank</target>
</navigateToURL>
Navigate to a specific frame in the timeline
This action actually calls the gotoAndPlay() method and moves the playhead to the specified frame number on the timeline. You can only specify frame numbers and not frame labels:
<gotoFrame>
<frame>5</frame>
</gotoFrame>
Execute a specified function
In this case a user function will be executed by the component. The function must already be declared by the time the corresponding item is selected. You can also specify parameters for the declared function and you can use parameters of different type (String, Boolean, Number):
<callFunction>
<function>myCallFunction(param1, param2)</function>
</callFunction>
<data>
This node contains other properties that will be set to the display object specified with _targetInstanceName. For example, in case you would use the JCLoader component to load larger images, you could specify the URL of the large image for the source property of the JCLoader instance. Also, you could specify a new size for that loader and maybe a new scale mode:
<data>
<source>myLargeImage.jpg</source>
<width>400</width>
<height>300</height>
<scaleMode>scaleCrop</scaleMode>
</data>
Besides these nodes, you can also specify other nodes representing extra properties for the items in the list, like extra descriptions for images (in which case you could use label as titles), prices displayed over the large images if the list would represent items from an online store or simply some other information you could use to execute different actions in your Flash application.
<item>
<source>myThumbnailImage1.jpg</source>
<label>My photo</label>
<description>This is some description of the image</description>
<type>image</type>
<largeImage>myLargeImage.jpg</largeImage>
</item>
<item>
<source>myThumbnailImage2.jpg</source>
<label>My video</label>
<description>This is some description of the video</description>
<type>video</type>
<videoSource>myVideo.flv</videoSource>
</item>
These extra nodes will be then added as properties to the items and you can then retrieve their values: myDock.selectedItem.description or myDock.selectedItem.type.
This way, by verifying the value of the node <type> (actually by checking the type property added to the item), you could load the larger image or video into a different loader component: load the image into a simple loader and the video into a video player component, showing or hiding the appropriate component, according to the value of the type property.
|