-[ LiteStep Theme Installer v1.1.2 ]-------------------------------------------


A utility to simplify and enhance LiteStep theme installation and switching.
(For LiteStep themes that are OTS compliant, of course. ;)




-[ NOTES ]---------------------------------------------------------------------


LSTI is a comprehensive theme installation and switching utility that allows
for (amongst other things) the automated installation of LiteStep themes that
have an '.lsz' extension. ('.lsz' theme archives are simply renamed '.zip'
archives.)

LSTI installs themes according to the OTS specification as described here:

http://o-t-s.sourceforge.net/theme_installation.html#manual_installation

LSTI can install themes right from your web browser, provided you allow it to
do so. The configuration will vary from browser to browser, but generally
speaking, you have to let your browser know that it's ok to open '.lsz' files
with the default handler (i.e. LSTI). Please note that doing things like this
may be considered to be a security risk.

LSTI logs the activities of its last session to LSThemeInstaller.log




-[ OPERATION ]-----------------------------------------------------------------


OPTIONAL SETTINGS

When you run LSTI you will see a 'Settings' button - this will allow you to set
all of LSTI's options to your liking, which include:

 - editing themevars.rc before recycling
 - prompting to revert to the default theme after loading a new one
 - saving converted wallpaper in $ThemesDir$
   (as opposed to storing converted wallpaper separately with each theme)
 - applying wallpaper included with themes
 - installing font included with themes
 - installing Winamp2 skin included with themes
 - installing Winamp3 skin included with themes
 - installing WindowBlinds skin included with themes

After setting the options, click 'OK'. At this point you can install a theme,
or you can just click 'Cancel' to exit, either way the settings are saved.


INSTALLING THEMES

If you chose to auto-install themes when you installed LiteStep, you can simply
double click on theme archives that end in '.lsz' to install them.

You can also run LSTI and tell it what theme you want to install. 

When installing themes, LSTI will install any included wallpaper, font, winamp2
skin, winamp3 skin, or windowblinds skin, depending on what options you've
chosen. By default, everything is enabled. (If you are a theme author, consult
the 'Font, Wallpaper, & Skin Support' section for more information on the
installation of these items.)

You can if you wish, provide LSTI with a command line parameter telling it what
theme to install, e.g.:

LSThemeInstaller "e:\downloads\theme-X.zip"

(Note: If you are reinstalling a theme already present on your system AND have
some of the theme's .rc files or graphics open in an editor, OR you're actually
running the theme, the reinstallation of the theme may fail since the theme's
files are in use. Nothing bad will happen, you'll just need to make sure the
theme's files aren't in use, and then reinstall.)


SWITCHING THEMES

LSTI allows for popup-based theme switching. Simply include the LSTI-generated
'$ThemesDir$themeslist.rc' file in your popup menu. This will add a list of
all installed themes to the popup menu, clicking on any theme's entry switches
to it. Your popup menu is already setup for this, simply go to:

    litestep-> change themes

Should you find that the theme list in your popup menu needs updating, simply
select the 'refresh list' option in the 'change themes' menu, which is
equivalent to executing 'LSThemeInstaller /refresh' at the command line.


RECOVERING FROM A BAD THEME

There is no excuse for a theme that does not work properly upon installation
due to errors in the theme itself.

If you are unfortunate enough to encounter such a theme, you can revert to the
default theme by going to your LiteStep directory and double-clicking the 
'Switch to default theme' shortcut.


SUPPORT FOR OLDER OTS1 COMPLIANT THEMES

In order to ease the transition to OTS2 compliant LiteStep themes, backwards
compatibility is now being provided. PLEASE DO NOT USE THIS AS AN EXCUSE TO
CONTINUE THE DEVELOPMENT OF OTS1 COMPLIANT THEMES.

In order to use OTS1 compliant themes, you should have selected the appropriate
option in the LiteStep Installer (lsinstaller.loose-screws.com). It's selected
by default anyway. :P

So if you chose to install support for OTS1 compliant themes, all you need to
do is rename your OTS1 compliant's theme archive to end in '.lsz', double-click
it, and the rest will be taken care of by LSTI.

Or, if you're not auto-installing themes, simply fire up LSTI, point it at the
OTS1 compliant theme you wish to install, and hit 'Install'.

That's all there is to it. Just use LSTI to install OTS1 compliant themes. :)




-[ FONT,WALLPAPER, & SKIN SUPPORT ]--------------------------------------------


If you are a theme author and have fonts, wallpaper, or skins you wish to have
installed along with your theme, you will need to create a file called
'theme.ini' and put it in the root directory of your theme.

The contents of 'theme.ini' should be as follows:

[Install]
Font="misc\font.ttf"
FontName="font name (TrueType)"
Wallpaper="wallpaper\theme-X.png"
WallpaperStyle="stretched"
Winamp2="misc\skins\theme-X_amp.wsz"
Winamp3="misc\skins\theme-X_amp3.wal"
WindowBlinds="misc\skins\theme-X_wb.wba"

Things to note:

  * All paths in 'theme.ini' are relative to the root directory of the theme

  * Entries should be quoted

  * The 'FontName' can be determined by double-clicking the '.ttf' file, and
    reading the information at the top of the window. If you see 'TrueType'
    written anywhere in the window, you should add a '(TrueType)' suffix.

  * Although you could put the wallpaper anywhere, the OTS specifies that it be
    stored in a 'wallpaper' folder (or subfolders thereof).

  * Valid values for 'WallpaperStyle' are 'tiled', 'centered', or 'stretched'

  * Zip files are supported, e.g. Winamp2="misc\skins\theme-X_amp.zip" is fine.
    (It's not very sensible though.)

  * Extraneous entries should be deleted

  * Please note that it is *your* responsibility to ensure that your skins,
    particularly windowblinds skins, have the correct internal structure. As
    far as I've been able to discern, windowblinds now frowns upon skin
    archives with path information. I had to re-structure some of my old skins
    before they would install properly. Have a look at the windowblinds skin
    included with synchronicity if you're confused. ;)


ADVANCED USAGE (using LiteStep Theme Installer to apply wallpaper)

Some of you themers have no doubt already noticed this, but you can use LSTI
to quickly apply wallpaper for your theme. This can be useful if your theme
includes different styles or schemes with different wallpapers, for instance.

This avoids the overhead of loading an additional LiteStep module for wallpaper
management.

All you need to do is:

1. set the appropriate entries in $ThemeDir$theme.ini
2. tell LSTI to switch to your theme, e.g.
   !execute ["$LiteStepDir$utilities\LSThemeInstaller.exe" /switch theme-X]

Both of the above can be performed easily with LiteStep modules such as
mzscript and textedit. For a complete working example, consult the script.rc
files of simplicity or synchronicity.




-[ CONTACT ]-------------------------------------------------------------------


If you have any problems, take a look at the log, maybe you'll spot the error.

Please use the LiteStep Installer Forum at loose-screws.com for feedback and
support:

http://forums.loose-screws.com/viewforum.php?f=52


Omar




-[ HISTORY ]-------------------------------------------------------------------


* 1.1.2
    - added option to save wallpaper in $ThemesDir$, enabled by default
      (requested By Brian Wolven, Derek Buranen, and 143lsstep)
    - revised procedure for displaying files (themevars, log)


* 1.1.1
    - 'revert to default theme' prompt now waits for NetLoadModule to finish
       downloading first, as sugested by locketine


* 1.1
    - added support for older OTS1 compliant themes (please *don't* use this as
      a crutch, use and develop OTS2 compliant LiteStep themes!)
    - added optional prompt to revert to default theme
    - added ability to adjust LSThemeInstaller's settings :)
    - the path to the LSThemeInstaller executable in themeslist.rc is written
      relative to the LiteStep directory  now, as requested by ilmcuts.
    - disabled the cute little progress window :( (it was causing instability
      and I've already spent two days trying to fix it with no luck.)


* 1.0.3
    - changed error messages to state that theme is not OTS2 compliant if
      theme.rc is not found, as suggested by DeViLbOi


* 1.0.2
    - improved the workaround added in 1.0.1, it stays for now. ;)
    - recommend to theme authors that unnecessary theme.ini entries be deleted


* 1.0.1
    - workaround for theme failing to install when files are to be moved: don't
      know what the source of the problem is though. :(

* 1.0
    - initial release
