KC8 mediaPlayer API
===================


Functions:
==========

setClassicSkin( initObject )
----------------------------
Initobject should contain _x, _y, with, height and the c and s arrays like the
other KoolMoves flash 8 components. 
c [control base, control color 1, control color 2, control color 3, component background, display background] : colors
s [raise, angle, component shadow alpha] : styling options
Other variables the initobject can contain are lpos, lsize and lfsize.
lpos   : position of the list display
         0 top
         1 right
         2 bottom
         3 left
lsize  : width of the list display when lpos is 1 or 3, height of the list
         display when lpos is 0 or 2.
lfsize : font size used in the list display.


setUnderlayImage ( xOffset, yOffset, image [, width, height [, scale9Grid ]] )
setOverlayImage  ( xOffset, yOffset, image [, width, height [, scale9Grid ]] )
-----------------------------------------------------------------------------
xOffset, yOffset : offset in pixels
image            : bitmap image link name or reference to a bitmap image
width, height    : in pixels. Can be used to scale the image.
scale9Grid       : a rectangle (flash.geom.Rectangle) that defines how the
                   scaling of the image should be done.


setPrevButton     ( xOffset, yOffset, upImage, downImage, overImage )
setPlayButton     ( xOffset, yOffset, upImage, downImage, overImage )
setPauseButton    ( xOffset, yOffset, upImage, downImage, overImage )
setStopButton     ( xOffset, yOffset, upImage, downImage, overImage )
setNextButton     ( xOffset, yOffset, upImage, downImage, overImage )
setPlButton       ( xOffset, yOffset, upImage, downImage, overImage )
setDragButton     ( xOffset, yOffset, upImage, downImage, overImage )
setUserButton ( nr, xOffset, yOffset, upImage, downImage, overImage [, hold [, down ]] )
----------------------------------------------------------------------------------------
xOffset, yOffset              : see the underlay and overlay functions.
upImage, downImage, overImage : bitmap image link name or reference to a bitmap image.
                                All three images should be equal in size. They are used
                                for the up, down and over state of the button.
setPlButton                   : function to set the button that toggles the display of
                                the playlist.
nr                            : can be 0 - 9 . Nr of the user defined button.
hold                          : when set to true, the button acts as a switch.
down                          : when hold is set to true, this can be used to set the 
                                initial state of the button.


setTimelineSlider ( xOffset, yOffset, bImage, rxFill, ryFill, dFill, fImage, rxDrag, ryDrag, dDrag, dUpImage, dDownImage, dOverImage )
setVolumeSlider   ( xOffset, yOffset, bImage, rxFill, ryFill, dFill, fImage, rxDrag, ryDrag, dDrag, dUpImage, dDownImage, dOverImage )
setUserSlider ( nr, xOffset, yOffset, bImage, rxFill, ryFill, dFill, fImage, rxDrag, ryDrag, dDrag, dUpImage, dDownImage, dOverImage )
--------------------------------------------------------------------------------------------------------------------------------------
xOffset, yOffset                 : see the underlay and overlay functions.
bImage                           : base image of the slider
rxFill, ryFill                   : x and y offset of the fill image relative to the positon of the slider
dFill                            : direction of how the fill image is revealed depending on the slider value.
                                   >  0 left to right
                                   <= 0 bottom to top
fImage                           : fill image
rxDrag, ryDrag                   : x and y offset of the drag button relative to the positon of the slider.
dDrag                            : direction and amount the drag button can be moved.
                                   >  0 left to right, absolute value indicates amount of pixels.
                                   <= 0 bottom to top, absolute value indicates amount of pixels.
dUpImage, dDownImage, dOverImage : images used for the drag button (center of images will be used for (0,0) ).
                                   For more information see the functions above to set the buttons.
nr                               : can be 0 - 9 . Nr of the user defined slider.


setUserSliderValue ( nr, value )
--------------------------------
Set the value of a user defined slider.
nr    : can be 0 - 9 . Nr of the user defined slider.
value : 0 - 100


setDisplay ( xOffset, yOffset, width, height, bgColor [, ellipse ] )
--------------------------------------------------------------------
xOffset, yOffset : see the underlay and overlay functions.
width, height    : width and height of the display
bgColor          : background color of the display
ellipse          : when set to true the display will be shaped elliptical.


setScaleMode ( scaleMode, smoothing )
-------------------------------------
Both settings affect the way a movie or still is displayed.
ScaleMode can be 0 (scale to fit), 1 (scale and crop) or 2 (crop).
Smoothing can be true or false. The default setting is true.
To decrease CPU load, you can set smoothing to false.


setFD ( xOffset, yOffset, bWidth, bHeight, bSpace, bColor [, rAnchor ] )
------------------------------------------------------------------------
This function is used to set up the bar graph that's used to display the
frequency data of an .fd file.

xOffset, yOffset : see the underlay and overlay functions.
bWidth, bHeight  : width and height of a single bar
bSpace           : space between two bars
bColor           : color of the bars
rAnchor          : when set to true the bottom right is represented by
                   xOffset and yOffset, otherwise the bottom left.


setInfoScroll ( mode, font, size, color, bold, speed [, xOffset, yOffset, width, height ] )
-------------------------------------------------------------------------------------------
mode             : >  0 use both playlist labels and id3 data
                   <= 0 use only playlist labels
font             : font name
size             : font size
color            : font color
bold             : bold font (true / false)
speed            : how many pixels the text moves each 1/10 of a second.

If xOffset, yOffset, width and height are specified, they define the area used to display
the info scroll. If they aren't specified the display is used (only for audio files).


setTimer ( xOffset, yOffset, font, size, color, bold [, rAnchor [, tTime ]] )
-----------------------------------------------------------------------------
xOffset, yOffset : see the underlay and overlay functions.
font             : font name
size             : font size
color            : font color
bold             : bold font (true / false)
rAnchor          : when set to true the top right is represented by xOffset
                   and yOffset, otherwise the top left.
tTime            : when set to true the timer displays both the current time
                   and the total time, otherwise only the current time.


setListDisplay ( xOffset, yOffset, image, width, height, scale9Grid, rxList, ryList, lHeight, iUpImage, iDownImage, iOverImage, font, size, color, bold, align, rxSlider, rySlider, bImage, rxDrag, ryDrag, dDrag, dUpImage, dDownImage, dOverImage )
-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
This function is used to set up the display that shows the playlist.

xOffset, yOffset, image , width, height and scale9Grid are used to set up the background image.
For more information see the underlay and overlay functions.

rxList, ryList                   : the offset of the actual list relative to xOffset and yOffset.
lHeight                          : the height of the actual list in pixels.
iUpImage, iDownImage, iOverImage : the images that are used for the up, down and over state of
                                   one list item. All three should be equal in size.
font, size, color, bold, align   : define the text format for a list item. The text format is the
                                   same for all stages (up, down and over).

rxSlider, rySlider, bImage, rxDrag, ryDrag, dDrag, dUpImage, dDownImage and dOverImage are used
to set up the slider of the list. rxSlider and rySlider are relative to xOffset and yOffset. For
the rest of these slider parameters, see the slider functions above.


setListVisibility ( visibility )
--------------------------------
visibility can be true or false.
This function can be used to show or hide the list display after it has been created.


setRepeat ( rMode )
-------------------
rMode can be 0 (no repeat), 1 (repeat one) or 2 (repeat all)


shufflePlay ()
--------------
Shuffles the playlist and starts playing the first media file.


setBufferTime ( bTime )
-----------------------
Sets the buffertime for flv movies. bTime is a value in seconds.
The default value is 3 seconds.


setStillsDuration ( duration )
------------------------------
Sets the duration for all stills (jpg, png and gif are supported).
Duration is a value in milliseconds. The default value is 7000 (7 seconds).


setVolume ( volume )
--------------------
Volume van be 0 - 100.


setBalance ( balance )
----------------------
Balance can be 0 - 100.
0 = left, 100 = right. The default value is 50.


mute ( true / false )
---------------------
Can be used to mute the audio.


setPlaylist ( playlist, nr [, paused ] )
----------------------------------------
playlist : an array of labels and values. The labels represent the label shown in the
           list display, the values represent the file names of the media files.
           Supported media file filename extensions are
           flv (video)
           jpg, png, gif (still)
           mp3, fd (audio)
           fd files require the mp3 file that goes with it to be named the same except
           for the filename extension; that should be mp3 (all lowercase).
nr       : the playlist index number (zero based) of the media file to start with.
paused   : when set to true, the player starts in paused mode.

example  :

items = new Array();
items.push( { label: 'My first media file', value: 'MyMusicFile.mp3' } );
items.push( { label: 'My second media file', value: 'MyVideo.flv' } );
myMediaPlayer.setPlaylist ( items, 0 );


setExternalPlaylist ( playlistfile, nr [, paused ] )
----------------------------------------------------
playlistfile : external file containing the playlist. Each line contains one item
               in the format label | value

example      :

My first media file | MyMusicFile.mp3
My second media file | MyVideo.flv


Events:
=======

onUserButton ( nr [, down ] )
-----------------------------
Event triggered when a user defined button is pushed.
nr is the number of the button that was pushed.
When the button was set up with hold set to true, down represents the button state.


onUserSlider ( nr, value )
--------------------------
Event triggered when a user defined slider is moved.
nr is the number of the slider that was moved.
value is the new value of the slider.


onPlay (playlist index number, filename )
-----------------------------------------
Event triggered just before a new media
file starts playing.


onFD ( fArray[] )
-----------------
Event broadcasted when a .fd file is used.
fArray[] contains the values (each value can be 0 - 15) for the frequency bands.
fArray[] can have 9 or 12 items depending on the format used when the .fd file was created.
fArray[] will be undefined when the display has to be reset.


onID3, onMetaData, onCuePoint
-----------------------------
Similar to Sound and NetStream objects.


Remarks & known limitations :
=============================

- MP3FDCreator to create .fd files can be downloaded from www.koolexchange.com

- The minimum size of a classic skin when set using actionscript is 150 x 36 pixels.

- When you want to store user defined variables, it's recommended
  to the uservars object of the media player component to avoid
  the risk of using variable names that are already in use.
  
  example :
  myMediaPlayer.uservars.myVariable = myValue;


- Depth order of child objects :
Playlist underlay image (1)
Underlay image (2)
VideoHolder (3)
VideoHolder Mask (-9)
Frequency display (4)
InfoScroll (5)
Timer (6)
Playlist (8)
Overlay image (9)
Previous (10)
Play (11)
Pause (12)
Stop (13)
Next (14)
Toggle playlist (15)
Drag (16)
Timeline (18)
Volume (19)
User buttons (20-29)
User sliders (30-39)
