README - LiNsta_Photo
===================

About:
======

LiNsta_Photo, an adesklet (http://adesklets.sourceforge.net), is a photo/slide-show 
desklet for your desktop released under GNU/GPL for code (See `COPYING' 
file for license).
Some skins come from Gavatx (http://gavatx.deviantart.com/) and/or halfwayglad
(http://halfwayglad.deviantart.com/). I obtained their authorization to use
and share them. So these skins are licensed under a Creative Commons
Attribution-Noncommercial-No Derivative Works 2.5 License.

This desklet has 2 functionalities :
 - as photo desklet : shows an image;
 - as slideshow desklet : shows images existing in a dir and slide them.

Author:
========

ETIENNE ALAURENT <etienne.alaurent@free.fr> FOR THIS ORIGINAL CODE.

Requirements:
=============

Initially developed and tested using 
 - adesklets 0.5
 - linux 2.6.15-28 (Ubuntu 6.06 aka Dapper Drake)
 - gcc 4 
 - python 2.4

Running:
========

Simply run the 'LiNstaPhoto.py' script from within its containing directory.
If you don't see anything then run 'LiNstaPhoto.py --nautilus' if you are on GNOME,
or 'LiNstaPhoto.py --kde' or something like that (not tested) - see documentation.

Use custom right-click menu to change skins or other things.

Further Notes for v0.2.0 from Etienne Alaurent:
==============

One bug : when changing skin from custom right-click menu, bad init, so this
desklet must be restarted (right-click, and restart).

Version History:
================

v0.2
- 2 modes : Slide-show and photo
- Controls visible when mouse over the desklet
- Configurable skin for the desklet (to be enhanced)
- Configurable skin for the controls
- Skin configuration files
- Control skin configuration files
- General configuration files

v0.1
 - First released version.
 - Only slide-show.
 - Still a bit buggy

Files and Config files:
===================

Files and dir structure:
------------------------------------
LiNsta_Photo : LiNstaPhoto.py (the adesklet), config.txt (general config file), legal and doc files
 I--- skins : skins directory
 I   I--- backgrounds : one image by desklet theme
 I   I--- ctrl : control skins directory
 I   I   I--- skin1 : one dir for one skin
 I   I   I--- skin2 : one dir for one skin
 I   I     ...
 I   I--- themes : theme config files

In a ctrl subdir (ex: LiNsta):
 - a config file (config.ctrl)
 - gfx files for control : background, buttons for next or previous image, for playing slide-show
   forward or backward, for switching between photo and slide-show mode, for viewing image
   with any image viewer, for putting image in background wallpaper

Config files:
-------------------

All config files are python dictionaries.

General config file : config.txt in base dir.
 - delay: transition delay between 2 pictures in second. Changed when selecting right option
   in the custom right-click menu. Don't change this by yourself. See delay_list.
 - delay_list: acceptable values for delay (1, 2, 3, 5, 10, 15, 20, 30, 60). You can put your own
   list.
 - ShowFileName: show or hide image file name. Possible values : True or False. Changed when
   selecting right option in the custom right-click menu.
 - as_wp_cmd: command to use current image as wallpaper.
 - view_cmd: command to view image with viewer.
 - current_img: current image saved for next desklet run.
 - file_mask: image mask for file extraction
 - file_path: image dir
 - img_sort: 'Alphanumeric' or 'Random'. Changed when selecting right option in the custom
   right-click menu.
 - mode: 'Photo' or 'Slideshow'. Changed when selecting right option in the custom right-click
   menu.
 - skin: the skin to use. Must be the name (without extention) of a skin config file found in
   themes subdir. Changed when selecting the right option in the custom right-click menu.
 - transition and transition_delay: not used in this version

Skin config file with .skin extention in themes subdir :
 - background: desklet background image. This image is in backgrounds subdir.
 - ctrl_skin: control skin for this theme. ctrl_skin is a subdir of ctrl subdir.
 - photo_width, photo_height: image/photo size in the desklet.
 - photo_left, photo_top: left top image/photo position in the desklet.
 - txt_color, txt_shadow_color, txt_font: guess ;-)
 - txt_alarm_color: not used for now.

Control skin config file : config.ctrl in control skin subdir. All related files are in this same
control skin subdir.
 - ctrl_background: control background file.
 - ctrl_icons: python dictionary.
   + action: python dictionary. Action icon.
       gobackward, goforward, wallpaper: img files for gobackward, goforward, wallpaper action icon.
   + next: python dictionary. Next icon.
       default, inactive: img files for default or inactive next icon.
   + playview: python dictionary. Play or view icon.
       backward, forward, pause, view:  img files for backward, forward, pause, view play or view icon.
   + prev: python dictionary. Previous icon.
       default, inactive: img files for default or inactive prev icon.
   +sliderviewer: python dictionary. Slider or viewer icon.
       slider, viewer: img files for slider, viewer slider or viewer icon.
 - ctrl_icons_xy: python dictionary. x, y positions for control icons.

The Future:
===================

 - correct the bug when changing the desklet skin.
 - make transition between 2 images in the slide-show (like in OOo Impress).
 - GTK+ window to configure the desklet. Difficult : adesklet api compatible with
   GTK+/GNOME python api ?
 - build a real sidebar with plugins. Every plugin is a widget. Total code rewrite needed.

===================
