This document will explain exactly how a theme must be configured and packaged in order to adhere to the Open Theme Standard.
The OTS directory structure is as follows:
X:
|__litestep...................main LiteStep directory
|
|__personal...............contains all user settings
|
|__shortcuts..............contains shortcuts [.lnk files]
|
|__themes.................LiteStep themes directory
|
|__theme-X............theme directory
|
|__config.........theme config. files
|
|__images.........theme graphics
|
|__misc...........skins, any other extras
|
|__modules........all [non-core] modules used
| |
| |_docs........documentation for modules
|
|__sounds.........sound files
|
|__wallpaper......desktop backgrounds
The directories mentioned above are simply the essential ones - it does not mean that these should be the only entries in the LiteStep folder hierarchy. If a theme has no sounds or wallpapers, it obviously does not need to have the corresponding folders. Nor does the directory structure need to be this flat: For example, theme graphics need not go directly into the ...theme-X\images folder - they may be placed in subfolders therein.
As a theme author, you need only be concerned with the contents of the ...themes\theme-X folder.
theme-X [ThemeDir] |
The 'root' directory for a theme. All theme related files are stored in subfolders of this directory. It should contain the following files:
- step.rc
- modules.ini [if required by a theme]
- readme.[txt/htm]
- theme-X.thm
- preview.bmp |
config [ConfigDir] |
This folder contains two core files and all general theme config. files, e.g. script.rc, syscolour.ini, rainmeter.ini, .box, etc. Files may be placed in subfolders if desired, for example, .box files could be placed in ...\Config\box.
Themevars.rc is used to define any evars required by a theme, and popuptheme.rc defines the standard SHIFT-left-click theme popup menu:
- themevars.rc [if required by a theme]
- popuptheme.rc [SHIFT-left-click popup menu] |
images |
Theme images are contained in this folder or its subdirectories. |
misc [MiscDir] |
This the place to include fonts, skins for applications such as sysmeter, Winamp, WindowBlinds, etc. Any miscellaneous items may be included here, hence the name. ; ) |
modules [ModulesDir] |
All third party modules used by a theme must be stored here. If a core file from a particular build is required, it may be placed here. |
docs |
The documentation for all third party modules should be stored here. |
sounds [SoundsDir] |
If a theme requires any sound files they may be placed here. |
wallpaper [WallpaperDir] |
Desktop backgrounds are contained here, or in subdirectories of this folder. |
[1] $ThemeDir$step.rc
The ThemeDir must contain a step.rc file, and the first un-commented lines must be:
ThemeName "theme-X"
ThemeAuthor "Themer X"
PersonalDir "$LiteStepDir$personal\"
ThemeDir "$LiteStepDir$themes\theme-X\"
ConfigDir "$ThemeDir$config\" ;if required
include "$PersonalDir$personal.rc"
include "$ConfigDir$themevars.rc" ;if required
include "$ConfigDir$popuptheme.rc" ;if required
[2] using evars
The following environment variables are to be defined in $ThemeDir$step.rc as the need arises:
ModulesDir "$ThemeDir$modules\"
SoundsDir "$ThemeDir$sounds\"
WallpaperDir "$ThemeDir$wallpaper\"
MiscDir "$ThemeDir$misc\"
ShortcutsDir "$LiteStepDir$shortcuts\"
The LiteStepDir evar is set automatically by LiteStep and there is no need to define it - the same is true for WinDir.
Always use evars, not 'hard coded' paths like 'C:\litestep\popup2.dll'. So for example, your 'LoadModule' statements should look like:
LoadModule "$LitestepDir$desktop2.dll"
LoadModule "$LitestepDir$hotkey.dll"
LoadModule "$LitestepDir$popup2.dll"
LoadModule "$LitestepDir$shortcut2.dll"
LoadModule "$ModulesDir$ckhotspots.dll"
LoadModule "$ModulesDir$ckvwm.dll"
etc.
If you absolutely must have a 'hard coded' path in your theme, define an evar for it in themevars.rc as described in step 5.
For your convenience, a template step.rc file has been created which may be downloaded and used as a starting point for your theme's step.rc file.
[Note that LSImageFolder has not been specifically mentioned. It has been deliberately omitted because themers know they have to set this variable, and they are free to set it to whatever they choose. It is implicitly understood that it will be defined in the following manner:
LSImageFolder "$ThemeDir$images\", or
LSImageFolder "$ThemeDir$images\blue\", etc.
at any point after ThemeDir has been defined.]
[3] $ConfigDir$popuptheme.rc
The contents of the user's right-click popup menu cannot be modified. There is only one exception to this: you can set the title of the right-click popup menu, so don't forget to do so! With popup2.dll this is done via the 'HotlistName' setting. It is the user's right to have a popup menu that contains only what they choose to put into it. A standard SHIFT-left-click menu [!PopupTheme] has been established for themes, so you will be able to provide an entire custom popup menu for your theme. This popup menu could merely be for display, to show the user where you think separators should be placed, etc. or it may be functional, providing access to theme functions, or a combination of both. [If your !PopupTheme menu is for 'display' only, it would be a good idea to make note of this somewhere in your documentation.]
You are encouraged to include popuptheme.rc, but not required to do so if your theme has no need of one.
The only requirements for !PopupTheme are:
;it must begin with this line:
*Popup "theme-X" !New !PopupTheme
.
.
.
;...and end with this one:
*Popup ~New
[4] universal module settings
There are some module settings that should be applied across all themes. Right-clicking on the desktop to access the popup menu is standard. Similarly, SHIFT-left-clicking on the desktop to access a theme's popup menu is also now standard. These two settings cannot be changed. (Of course advanced users can change these settings on their system if they wish. ; ) These two universal, fixed module settings have been put in $PersonalDir$personal.rc
In addition to the above fixed universal settings, there are user defined universal settings in $PersonalDir$personal.rc controlling things like what applications should be 'fixed' by a virtual window manager, what windows should be 'sticky', etc.
So the $PersonalDir$personal.rc file contains:
;----------------------------------------------------
;DO NOT EDIT
include "$PersonalDir$evars.rc"
include "$PersonalDir$hotkey.rc"
include "$PersonalDir$popup.rc"
;----------------------------------------------------
;DO NOT CHANGE UNLESS YOU KNOW WHAT YOU ARE DOING. :)
*Desktop RButton !Popup
*Desktop LButton+SHIFT !PopupTheme
*jDeskMButton2 [.none;!none;!Popup;!none]
*jDeskMButton1 [SHIFT;!none;!PopupTheme;!none]
;----------------------------------------------------
;you are free to add to, remove, or change these settings
jDeskDoubleClickTime "1"
*VWMFix Photoshop
*VWMSticky colorPadWin
Now what all this means for you as a themer is that you cannot use the following four module settings in a theme:
*Desktop RButton !anything
*Desktop LButton+SHIFT !anything
*jDeskMButton2 [.none;!none;!anything;!none]
*jDeskMButton1 [SHIFT;!none;!anything;!none]
I would like to point out that no sane themer would change the right-click action in any case. : ) Really the only sacrifice on the part of themers is the SHIFT-left-click setting. The OTS team feels the benefit [a standard theme popup menu, just as the right-click menu is accepted as standard] completely outweighs any perceived disadvantage.
[5] $ConfigDir$themevars.rc
Theme specific environment variables should be used [if required]. For example, if there is a shortcut bar in your theme, use environment variables to define the shortcut bar functions:
*Shortcut "" 215c -19 sc_1.bmp .none .none #1 "$SCBAR1$"
*Shortcut "" 234c -19 sc_2.bmp .none .none #1 "$SCBAR2$"
*Shortcut "" 250c -19 sc_3.bmp .none .none #1 "$SCBAR3$"
*Shortcut "" 266c -19 sc_4.bmp .none .none #1 "$SCBAR4$"
etc.
Define the environment variables in themevars.rc where they may be easily set by users:
SCBAR1 "C:\Program Files\MegaShaft\subliminalmessages.exe"
SCBAR2 "C:\Program Files\MegaShaft\sendmeyourmoney.exe"
SCBAR3 "$FileManager$"
SCBAR4 "$TxtEditor$"
etc.
[6] $ThemeDir$modules.ini
If a theme uses modules that store their settings in modules.ini, then it should be included in the ThemeDir. It is the user's responsibility to copy modules.ini to the LiteStepDir.
[7] $ThemeDir$readme.[txt/htm]
Documentation should always be included with a theme. Any specific installation caveats should be noted. The following installation instructions must be included with your theme:
ATTENTION: If this is the first time you are using a theme that follows the Open Theme Standard, go to http://ls-ots.cjb.net, read the requirements in the installation section, and follow the instructions on setting up your personal config. files.
1. install the theme
Unzip the theme archive to your LiteStep\themes directory with path information.
2. modules.ini
Open your file manager and navigate to the ...themes\theme-X directory.
If a modules.ini file has been provided, copy it to your LiteStep directory.
3. themevars.rc
Browse to the ...theme-X\config directory in your file manager.
If themevars.rc exists, edit it and ensure all paths have been set correctly.
4. edit step.rc
Browse to the LiteStep directory in your file manager.
If you are using LSTS, run LSTS and select the theme. Otherwise, edit step.rc so that it contains the following line and nothing else:
include "$LiteStepDir$themes\theme-X\step.rc"
Recycle LiteStep.
Download the installation instructions. [Remember to change all 'theme-X' references to your theme's directory name.]
You are encouraged to edit the instructions to suit your theme's needs. You could remove steps 2 or 3 if they are unnecessary, or insert a step, if you wanted to provide instructions on installing skins for example. The above instructions are very generic and should be sufficient for any theme that follows the Open Theme Standard though. An example of customized installation instructions is available.
[8] LSTS support [theme-X.thm and preview.bmp]
The theme-X.thm and preview.bmp files must be provided so that those who wish to use LSTS may easily do so. The preview image is simply a 200x150 bitmap [or jpeg] placed in the root directory of a theme. To make a theme-X.thm for your theme:
- run LSTS
- right click on the desired theme from the list of 'Installed Themes' and
select the 'Edit Settings' entry
- On the 'Theme Info' tab, fill in the 'Theme Name', 'Step', 'Preview' and
'Documentation' fields.
You may set any of the other fields if desired.
On the 'Author' tab, fill in all fields that you can.
- click 'OK': a theme-X.thm file is now present in the root directory of your theme
If you don't have LSTS, you can download theme-X.thm, edit it, and rename it for inclusion in the root directory of your theme.
[9] Archiving the theme
Check the structure of your theme and ensure it follows the structure described in the previous section. [E.g. did you remember to create a docs subfolder in the modules dir to store all module documentation?] Also be certain that the requirements in this section have been met. Make sure you have everything you want to include in the theme: skins, wallpaper, fonts, etc.
When zipping the theme directory, only the directory name of your theme must be included as part of the path information. [So the path information in the archive should be 'theme-X', not 'themes\theme-X'.] In this way, your theme can easily be extracted to ...\themes by end users.
|