**************************************************************************
*                      BluPlusPlus  -  JAlbum Skin                       *
*                                                                        *
*                                                                        *
*                By: Armond Avanes (Armond555[at]yahoo.com)              *
*                   http://bluplusplus.armondavanes.com                  *
**************************************************************************

Usage Tips
===========
Complete documentation for the current version of BPP is available at the
following address and highly recommended:
http://bluplusplus.armondavanes.com/docs.html

Usages, applications, definitions, FAQs along with numerous examples are
included. The site can also be easily reached through the "About" tab on
the BPP user interface in JAlbum.

Credits here go to my friend, Robert Camner, for his outstanding job on
the documentation site.



* Multilingual Support:
------------------------
If you want to generate your album in a langauge other than your system's 
default one (actually for forcing a language), you can use "user.language" 
parameter when launching JAlbum.

Example for Italian language:
java -Duser.language=it -jar jalbum.jar 

Example for German language:
java -Duser.language=de -jar jalbum.jar 




* User Variables (Global/Album-Level):
---------------------------------------
  - For controlling whether or not to show the background voice annotations 
    console/controls, you can use "showAudioConsole" variable. Setting it to 
    "false" will not show any console but only the voice annotation will be played 
    (which is the default).

  - For controlling whether or not to include 'save protection' for album images
    to prevent them from being saved via right-click or context-menu, you can use
    "includeSaveProtection" variable. Setting it to "false" will remove the 
    protection (which is the default).

  - For controlling the navigation bar vertical location, you can use
    "navigationBarVerticalLocation" variable.
    The following values are valid:
    	+ Top: Having the navigation bar at the top of the pages. (default)
    	+ Bottom: Having the navigation bar at the bottom of the pages.
    	+ Both: Having the navigation bar both at the top and bottom of the pages.

  - For controlling the screen actions' and elements' context help style, you can
    use "contextHelpStyle" variable.
    The following styles are valid for this variable:
    	+ None: For not to have any context help in any style.
    	+ ToolTip: For having the context help as tooltip. (default)
    	+ StatusBar: For having the context help in status bar.
    	+ Both: For including both the tooltips and the status bar.

  - For controlling whether to include the navigation tips within the pages, you can
    use "includeNavigationHelpTips" variable.

  - For controlling whether or not to prefetch/preload the sibling sides of the
    current one, you can use "prefetchSiblingSlides" variable. Setting it to "false" 
    will remove the prefetch facility.
    
  - For controlling whether or not to include the blending effects on slide and index
    pages, you can use "includeBlendingEffectOnSlides" and "includeBlendingEffectOnIndexes"
    variables. Setting them to "false" will remove the blending effects.

  - For controlling whether or not to include any online printing service support for
    album images, you can use "printing" variable. The default value is "none" and the
    currently available services are "shutterfly" and "mypix".

  - For controlling whether or not to include the Slide Show facility on 
    slide pages, you can use "includeSlideShow" variable. Setting it to "false"
    will remove Slide Show feature.

  - For controlling whether to have cyclic Slide Show on slide pages, you can set
    the user variable "cyclicSlideShow".
    At the positive case ("true" value), it means that by reaching to the last slide,
    it will automatically restart/cycle from the first. Kind of forever loop till the
    viewer explicitly stops it.
    Otherwise ("false" value), Slide Show will stop when it gets to the last slide.
    This option is "true" by default.

  - For controlling the slide show "delay", you can change the user variable
    "slideShowDelay" to whatever you want (the unit is second).

  - For controlling the slide show "delay" on commented slides separately, you can
    change the user variable "slideShowCommentDelay" to whatever you want
    (the unit is second). The "slideShowDelay" value will be used if nothing is
    specified for this variable.

  - For excluding the First & Last page actions on slide & index pages in order to
    have a simpler layout, put the value of variable "includeFirstLastPageActions"
    to "false".

  - For having the one click moving-forward facility in the case you do not have any
    "Link to originals via scaled images" option set. Having this facility on,
    moving forward is as easy as clicking on the slide itself :-) Much more handy
    than clicking exactly on "next" arrow.

  - For controlling whether or not to include the Next & Previous N thumbnails 
    within each slide page, you can use 'includeSlidePageThumbnails' (setting to
    "false" will totally remove it).
    
  - For controlling the count of the Next & Previous N thumbnails displayed in each 
    slide page, you can use 'slidePageThumbnailCount'.
    
  - For controlling the ratio of the slide page thumbnails against the index page 
    ones, you can use 'slidePageThumbnailRatio' variable.
    
  - For controlling the size of the movie slides, you can use 'movieSlideDimension'
    variable. Leaving it empty means the maximum size of image slides you've already
    defined.
    
  - For excluding the Jump To Page quick accessor from top of the pages, put 
    the value of variable "includeJumpToPageAction" to "false".
    
  - For turning the keyboard navigation OFF (which is on by default), put the value 
    of variable "includeKeyboardSupport" to "false".
    
  - For adding your own copyright notes to the bottom of all the index and 
    slide pages, you can set "copyright" variable to whatever text you want. 
    It will do the job!

  - "chooseRandomIconForFolder" is used for controlling whether or not to
    automatically choose a random image from the image containing folders as 
    folder icon IF there isn't any specific icon defined by 'folderIcon' in 
    "meta.properties". Setting the value to "false" will cause the standard folder 
    icon to get chosen IF no specific icon is defined.

  - For appending any prefix to the slides comment (say an HTML start tag like <b>),
    set a value for "slideCommentPrefix" variable. The same story goes for the
    postfix and it can be done by "slideCommentPostfix". Having these two variables
    together can be useful when you want to enclose the whole comment inside an 
    HTML tag or so.

  - For specifying the slides comment horizontal alignment, use 'slideCommentHorizontalAlign'
    variable. And you have the "Left", "Center" and "Right" options.

  - For controlling the slides comment vertical position, use 'slideCommentVerticalPosition'
    variable. And you have the "TOP_ABOVE_NAVIGATION", "TOP_UNDER_NAVIGATION"
    and "BOTTOM" options. The default is "TOP_UNDER_NAVIGATION" if not defined.

  - For controlling whether or not to include a link to outside of your album (usually one
    level upper) at the top bar, use 'externalHomePath' variable.
    Not defining anything for this variable (the default) will remove the external home link.
    This is useful when you have several separately generated albums all in one folder, and 
    want to be able to traverse among them.

  - For controlling the content/detail of the slide pages displayed information, you
    can use "slideCaptionContent" variable.
    This variable can contain different parts and each part is separated 
    by '|', ',', ';' or '~' from the next. Using double separators (like '||' and '~~' )
    will lead into a new line. The following part names are valid:
       + Title: Title of the slide/thumbnail
       + FileName: Real file name of the slide content
       + FileType: File type/extension
       + Date: Date of the file (or EXIF date for the images if exists)
       + Dimension: Dimension of the original file (actually for images)
       + SlideDimension: Dimension of the slide (actually for images)
       + FileSize: File size of the original file
    The default value for this variable is:
    FileName|Dimension|FileSize||Date

  - For controlling the content/detail of the thumbnail (non-folder) tooltips, you
    can use "thumbnailTooltipContent" variable. "thumbnailCaptionContent" can be used
    to control the content/detail of the displayed information for the thumbnails on
    index pages.
    Both of the variables can contain different parts and each part is separated 
    by '|', ',', ';' or '~' from the next. And the following part names are valid:
       + Title: Title of the slide/thumbnail
       + FileName: Real file name of the slide content
       + FileType: File type/extension
       + InternalComment or ExifComment or EmbeddedComment: The EXIF comment embedded 
         in the image
       + ExternalComment: The comments specified in the external text files for the 
         slide
       + Date: Date of the file (or EXIF date for the images if exists)
       + Dimension: Dimension of the original file (actually for images)
       + SlideDimension: Dimension of the slide (actually for images)
       + FileSize: File size of the original file
    The default value for "thumbnailTooltipContent" is:
    Title|EmbeddedComment|ExternalComment|Dimension|FileSize
    And for "thumbnailCaptionContent", the default is:
    Title

  - For controlling the content/detail of the folder thumbnail tooltips, you can 
    use "folderTooltipContent" variable. "folderCaptionContent" can be used
    to control the content/detail of the displayed information for the folders on
    index pages.
    Both of the variables can contain different parts and each part is separated 
    by '|', ',', ';' or '~' from the next. And the following part names are valid:
       + Title: Title of the folder
       + FileName: Real file name of the folder
       + Date: Date of the folder
       + Header: Header of the index page (folder)
       + Footer: Footer of the index page (folder)
       + SlideCount: Slide cound of the folder
    Not specifying anything for "folderTooltipContent" will lead you to the default 
    which is:
    Title|Header|SlideCount
    And the default for "folderCaptionContent" variable is:
    Title

  - Variable 'borderType' for controlling the slide thumbails', slide images' & folder
    thumbnails' border type. 
    This can be easily overridden by 'thumbnailBorderType' for slide thumbnails as well
    as 'folderThumbnailBorderType' for folder thumbnails.
    Not defining anything for these variables will lead into the default type (shadow).
    They can have one of the following values:
		+ none: No border at all
		+ solid: A solid color-based border. See 'borderColor' variable for controlling
                 the color in this case.
		+ frame: Nice NeoExhibit-like frame
		+ shadow: Shadow effect suitable for bright themes (the default)
        + shadow_dark: Shadow effect suitable for dark themes
        + shadow_artsy: Shadow effect suitable for "Artsy" theme
        + shadow_autumn: Shadow effect suitable for "Autumn" theme
        + shadow_canvas: Shadow effect suitable for "Canvas" theme
        + shadow_christmas: Shadow effect suitable for "Christmas" theme
        + shadow_expedition: Shadow effect suitable for "Expedition" theme
        + shadow_gray: Shadow effect suitable for "Gray" theme
        + shadow_hakki: Shadow effect suitable for "Hakki" theme
		+ bracket_black: Black bracket like border only with corners
		+ bracket_horizontal_black: Black horizontal bracket border
		+ bracket_vertical_black: Black vertical bracket border
		+ bracket_white: White bracket like border only with corners
		+ bracket_horizontal_white: White horizontal bracket border
		+ bracket_vertical_white: White vertical bracket border

  - Variable 'borderColor' controls the slide thumbails', slide images' & folder
    thumbnails' border color.
    This can be easily overridden by 'thumbnailBorderColor' for thumbnails as well as
    'folderThumbnailBorderColor' for folder thumbnails.
    Both the variables effective when the border type is "solid" and border size is 
    greater than zero.

  - For controlling the slide thumbails', slide images' & folder thumbnails' border size, 
    you can use 'borderSize' user variable (a number in pixel unit).
    This can be easily overridden by 'thumbnailBorderSize' for slide thumbnails as well
    as 'folderThumbnailBorderSize' for folder thumbnails.
    The default value for 'borderSize' is 15 if not defined. As for 'thumbnailBorderSize'
    default value, 'borderSize' is divided by 1.5 (so 10 by default!). The same story
    goes for 'folderThumbnailBorderSize'.
    As for "shadow" border type, 15 will fit the best as border size. And for "frame"
    border type, something between 35 and 51 (its actual size) will look the best.

  - Variable 'iconSet' controls the icon set. Not defining anything will set it to the
    default ("universal").
    It can have one of the following values:
	+ bright-matte: A set of icons which looks nice on bright backgrounds such as
	                "Bluish" and "Bluish2" themes.
	+ dark-matte: The same set as the above icons but good for dark backgrounds
		          such as the "Black" theme.
	+ universal: The default set of icons and as its name suggests it's modified 
	             and optimized to fit the best on any kind of backgrounds.
	+ black: A black set of icons. Great for bright themes.
	+ white: A white set of icons. Great for dark themes.


  IMPORTANT NOTE: All of the user variables described above can be overriden for each of 
                  the album folders and their subfolders (via "variables.properties" meta 
                  file which can be placed within any folder) - aka per folder 
                  customizations.
                  For example having "style=Bluish.css" in variables.properties will 
                  override the default style chosen by teh suer in JAlbum's "Main" tab.




* Metadata Support (Folder-Level):
-----------------------------------
  - The entire folder metadata can easily be entered into a single file 
    ("meta.properties") inside that desired folder. You can specify the title, 
    voice annotation, background image, header, footer and icon of the folders 
    as well as the titles, voice annotations, background images, and descriptions 
    of their containing files.
    The meta.properties format should be as following:
    
	folderTitle=a title for current folder
	folderHeader=some header information for current folder
	folderFooter=some footer information for current folder
	folderIcon=relative/path/to/icon-file.ext
	folderVoice=relative/path/to/voice-file.ext
	
	indexBackgroundImage=relative/path/to/background-image.ext
	slideBackgroundImage=relative/path/to/background-image.ext

	title.filename1.ext=slide title 1
	description.filename1.ext=some slide descriptions 1
	voice.filename1.ext=relative/path/to/voice-file1.ext

	title.filename2.ext=slide title 2
	description.filename2.ext=some slide descriptions 2
	voice.filename2.ext=relative/path/to/voice-file2.ext

	title.filename3.ext=slide title 3
	description.filename3.ext=some slide descriptions 3
	voice.filename3.ext=relative/path/to/voice-file3.ext
	
    NOTE 1: 'slideBackgroundImage' is overriding the 'indexBackgroundImage' 
            value so 'indexBackgroundImage' will be used for slide pages too if 
            'slideBackgroundImage' is not defined.
    NOTE 2: 'indexBackgroundImage' & 'slideBackgroundImage' values are inherited 
            in sub-folders so defining any values for a specific folder will apply 
            them on its containing sub-folders too.

  - For overriding any of the global/album-level user variables for a specific
    folder (and its subfolders), you can just put "variables.properties" meta 
    file within that folder and override there whatever user variable you want (in 
    key=value pair format).

  - For making some comments at the header of any desired folder's page, just 
    put a file named "header.inc" in that folder. The file content will be 
    automatically picked up and inserted in that folder's home page as header 
    comment.
    NOTE: This is an alternative way to meta.properties.

  - For making some comments at the footer of any desired folder's page, just 
    put a file named "footer.inc" in that folder. The file content will be 
    automatically picked up and inserted in that folder's home page as footer 
    comment.
    NOTE: This is an alternative way to meta.properties.

  - For adding some comments to any desired image, just put add a file with 
    the same name of the image but with ".txt" extension right beside it in 
    the same folder.
    NOTE: This is an alternative way to meta.properties.

  - For adding voice annotations to any desired image, just name the voice file 
    (.wav, .mp3, .voc or .mid) as your image file and put it right beside the 
    image in the same folder. It will be automatically picked up and inserted 
    in that image's slide page so will be played as backgroud sound when you 
    view that slide.
    NOTE: This is an alternative way to meta.properties.

  - For adding voice annotations to any desired folder, just name the voice file 
    (.wav, .mp3, .voc or .mid) as your folder file with "_" prefix and put it 
    within the same folder. It will be automatically picked up and inserted 
    in the first index of the folder so will be played as backgroud sound when 
    you view that index page.
    NOTE: This is an alternative way to meta.properties.

  - For adding thumbnails for your movie clips, you can easily put whatever 
    image you like beside the clip (used as thumbnail) and name it the same
    movie name followed by a ".thumb" suffix. For example if you have "test.mpg", 
    the thumbnail will be "test.mpg.thumb" or as for "test.avi" it will be 
    "test.avi.thumb".




* Keyboard Navigation Support:
-------------------------------
    Keys:
      RIGHT Arrow  : Next page
      LEFT Arrow   : Previous page
      Page UP      : Index page
      HOME         : First page
      END          : Last page
      S, s         : Toggle start/stop slide show (not in index)
      ESC          : Stop slide show (not in index)
      I, i         : Toggle exif info (not in index)
      H, h         : Toggle help tips
    Tested on: IE6, Mozilla 1.4, Netscape 7.1, Opera 7.2

    Bugs:
     - HOME and END do not work in Opera
