directory structure

As most of you probably know, Windows 9x (95, 98, ME...) is a single-user OS. Even though some versions of Win9x appear to have distinct user profiles, no version of Win9x is truly a multi-user operating system. On the other hand, Windows NT (NT, 2k, XP) is a multi-user OS. This difference between Win9x and WinNT means that the directory structure of a LiteStep installation will vary somewhat between these two platforms.

When LiteStep is installed on a Win9x system and used as a shell, it affects all users on that system. All users will see the same LiteStep theme, have the same popup menus, hotkeys, etc. - all core files, themes, and personal settings will be stored in one place, typically the LiteStep directory.

On a WinNT system though, LiteStep can be set as shell on a per-user basis. The core LiteStep files are stored in the LiteStep directory, and are shared between all LiteStep users on the system. Themes and personal settings however, are stored separately for each user.

The image below shows what the directory structure of a typical LiteStep installation on Win9x would look like. On WinNT the only difference is that the 'personal' and 'themes' directories would be in an '...\Application Data\LiteStep' directory. (Each user has an 'Application Data' directory associated with their profile in an NT based OS. For example, on XP the full path to the 'personal' folder for 'user-X' would be along the lines of 'X:\Documents and Settings\user-X\Application Data\LiteStep\personal\'.)

(Note: The 'personal' and 'themes' directories may not necessarily be in an '...\Application Data\LiteStep' directory on WinNT - the exact location is chosen by a user during installation - but they will be assumed to be in this location in the ensuing discussion.)

Please note that not all directories have been shown, in fact, there will almost certainly be more. The only ones shown here are those that are relevant to the current discussion.

litestep directory

The directory layout presented is not set in stone. Most of the directory locations can be changed - some by the user, and some by the theme author (themer). To change the location of a user-defined directory, the desired directory should be created, the appropriate files should be placed inside, and the associated environment variable (evar) should then be updated to point to the desired location. It should be noted though, that the default directory locations mentioned are strongly recommended and should not be modified, except by advanced users.

The LiteStep directory is unique in that it's location is chosen by the user during installation, and the associated $LiteStepDir$ evar is automatically defined by LiteStep, not via an evar definition in an .rc file.

The following table describes each directory in turn, the evar associated with it, its default location, etc.

Directory Evar Location Description
LiteStep $LiteStepDir$ X:\LiteStep\

specified by user during installation
the main LiteStep folder - at the root level, it contains step.rc and a build of LiteStep
modules $ModulesDir$ X:\LiteStep\modules\

user-defined via the $ModulesDir$ evar in step.rc
central repository for all LiteStep modules
NLM - X:\LiteStep\NLM contains NetLoadModule.dll and NetLoadModule.ini
personal $PersonalDir$ X:\LiteStep\personal\ (Win9x)

...\Application Data\LiteStep\personal\ (WinNT)

user-defined via the $PersonalDir$ evar in step.rc
the files in this folder (personal.rc, evars.rc, hotkey.rc, popup.rc) are where all user preferences and settings for things like application evars, hotkeys, and the popup menu are stored - there are also personal settings (and related files) for lsxcommand and rainlendar (settings for additional modules may be added at the user's discretion)
themes $ThemesDir$ X:\LiteStep\themes\ (Win9x)

...\Application Data\LiteStep\themes\ (WinNT)

user-defined via the $ThemesDir$ evar in step.rc
all LiteStep themes are stored in subdirectories of this folder - at the root level, it contains themeselect.rc, the file that specifies which LiteStep theme is in use
theme-X $ThemeDir$ X:\LiteStep\themes\theme-X\ (Win9x)

...\Application Data\LiteStep\themes\theme-X\ (WinNT)

user-defined via the $ThemeDir$ evar in themeselect.rc
the root folder of the LiteStep theme currently in use
config $ConfigDir$ X:\LiteStep\themes\theme-X\config\ (Win9x)

...\Application Data\LiteStep\themes\theme-X\config\ (WinNT)

themer-defined via the $ConfigDir$ evar in theme.rc
stores LiteStep theme configuration files such as theme.rc and popuptheme.rc

In the next section the key files from each directory will be examined.

key files

$LiteStepDir$step.rc

This is the main LiteStep configuration file, and is automatically loaded by LiteStep on startup. In fact, this file is really the only means by which LiteStep can be configured. You might be wondering then, looking at the short step.rc file below, where all the LiteStep settings are.

In the past, all LiteStep settings were stored directly in step.rc resulting in files that were often a few pages long. Once the include statement was added to LiteStep, allowing the contents of one file to be included in an another, this was no longer necessary. LiteStep settings are now stored in separate files according to their purpose, and added to step.rc via include statements.

;------------------------------------------------------------------------------
;   define critical folder locations (and name of main theme config. file)
;------------------------------------------------------------------------------

ModulesDir              "$LiteStepDir$modules\"
IF Win9x
    PersonalDir         "$LiteStepDir$personal\"
    ThemesDir           "$LitestepDir$themes\"
ELSE
    PersonalDir         "$AppData$\LiteStep\personal\"
    ThemesDir           "$AppData$\LiteStep\themes\"
ENDIF



;------------------------------------------------------------------------------
;   NetLoadModule configuration
;------------------------------------------------------------------------------

LoadModule              "$LiteStepDir$NLM\NetLoadModule2.dll"

*NetLoadModuleSite      "http://www.modules.ls-universe.info/modules/"
*NetLoadModuleSite      "http://modules.shellfront.org/"
NetLoadModulePath       "$ModulesDir$"
NetLoadModuleDocPath    "$ModulesDir$docs\"
NetLoadModuleZipPath    "$ModulesDir$archive\"
NetLoadModuleAliasFile  "$LiteStepDir$NLM\NetLoadModule.ini"



;------------------------------------------------------------------------------
;   load personal settings, select a theme, and load theme settings
;------------------------------------------------------------------------------

include "$ThemesDir$themeselect.rc"
include "$PersonalDir$personal.rc"
include	"$ThemeDir$theme.rc"

The first section simply sets up some evars to define the locations of a few important folders, taking into account the differences in directory structure between a Win9x and WinNT LiteStep installation discussed earlier.

The next section establishes how LiteStep modules are loaded and where they are stored. But before delving into exactly what this section does, some background information is needed.

In the past, each theme would come packaged with the modules it required, which were stored in the theme's 'modules' subdirectory and loaded via LoadModule statements in theme.rc.

This worked quite well, but led to file duplication since the same module would often be stored in the 'modules' folder of several different themes.

With the development of NetLoadModule, it is now possible to automatically download modules as they are needed, and store them in a central location. This obviously eliminates duplication of modules, and is also quite simply the superior approach from a technical perspective. All LiteStep modules can now be stored in a single 'modules' directory (whose location is defined via the $ModulesDir$ evar), and are loaded via *NetLoadModule statements in theme.rc.

The only exception to this is NetLoadModule itself - it has to be manually stored in $LiteStepDir$NLM\ and loaded via a LoadModule statement in step.rc.

So the NetLoadModule section defines:

  • where modules can be downloaded from
  • where installed modules are stored
  • where downloaded module archives are stored
  • where module documentation is stored

Please consult theme creation and NetLoadModule's documentation for further details.

Having covered the folder location definitions and NetLoadModule configuration, all that remains is the third and final section of step.rc. This section is where LiteStep settings are pulled together from their sources. The first statement in this section loads all user-defined settings by including personal.rc. The next statement involving themeselect.rc determines which LiteStep theme is in use, and the last loads all settings for this theme, stored in theme.rc.


$PersonalDir$personal.rc

This file has two purposes:
1. To serve as a 'container' for all user settings by encapsulating them within itself via include statements.
2. To define very specific module settings that are to be applied universally across all themes.

;------------------------------------------------------------------------------
;personal config file
;------------------------------------------------------------------------------

;Take care when editing this file - do not change the contents of the first two
;sections, change settings only in subsequent sections.



;------------------------------------------------------------------------------
; I    DO NOT EDIT
;------------------------------------------------------------------------------

OTSCfgMajorVersion 2
OTSCfgMinorVersion 0

include "$PersonalDir$evars.rc"
include "$PersonalDir$hotkey.rc"
include "$PersonalDir$popup.rc"



;------------------------------------------------------------------------------
; II    DO NOT CHANGE UNLESS YOU KNOW WHAT YOU ARE DOING. :)
;------------------------------------------------------------------------------

*Desktop RButton !Popup                         ;right-click popup menu
*Desktop LButton+SHIFT !PopupTheme              ;SHIFT-left-click popup menu
*jDeskMButton2 [.none;!none;!Popup;!none]       ;right-click popup menu
*jDeskMButton1 [SHIFT;!none;!PopupTheme;!none]  ;SHIFT-left-click popup menu



;------------------------------------------------------------------------------
;   load hotkey module
;------------------------------------------------------------------------------

;--> load hotkey module
*NetLoadModule          jkey-0.37

;--> define some jKey settings
jKeyVKTable             "$PersonalDir$jkey\vk104.txt"
jKeyUseHotkeyDef



;------------------------------------------------------------------------------
;   personal settings: popup
;------------------------------------------------------------------------------

;--> define desired popup settings
PopupMenuDelay          100
PopupScrollSpeed        1



;------------------------------------------------------------------------------
;   personal settings: lsxcommand
;------------------------------------------------------------------------------

;--> search engine and history files
CommandSearchEngineList "$PersonalDir$lsxcommand\engines.list"
CommandHistoryFile      "$PersonalDir$lsxcommand\history.ini"

;--> number of history entries
CommandHistoryEntries   20



;------------------------------------------------------------------------------
;   personal settings: rainlendar
;------------------------------------------------------------------------------

;--> paths to rainlendar.ini, events.ini, and rainlendar language files
RainlendarPath          "$PersonalDir$rainlendar\"
RainlendarEventsPath    "$PersonalDir$rainlendar\"
RainlendarLanguagesPath "$PersonalDir$rainlendar\languages\"



;------------------------------------------------------------------------------
;   personal settings: miscellaneous
;------------------------------------------------------------------------------

jDeskDoubleClickTime "1"
*VWMFix Photoshop

The first section imports user-defined evar, hotkey, and popup menu settings into personal.rc. Now all these settings can be accessed simply by including personal.rc, as demonstrated in step.rc earlier. It also defines two evars defining the version of the OTS that the configuration files support.

The second section contains some desktop module settings. (There are two sets of settings here since there are two desktop modules available for LiteStep). These settings define what happens when the desktop receives a right-click, and what happens when it receives a SHIFT-left-click.

As configured above, a right-click on the desktop launches the user-defined popup menu, which is stored in popup.rc. A SHIFT-left-click launches the themer-defined popup menu, which is stored in popuptheme.rc. (If the themer has not defined a popup menu for their theme, a SHIFT-left-click will do nothing.)

The third section loads the user's preferred hotkey module. It is preferable to load this module here because the differences amongst the few hotkey modules available are not relevant to theme creation, but do impact on usability. Furthermore, not all themes need a hotkey module, so if loading a hotkey module were left up to themes, a user could potentially be left without the use of their hotkeys. And finally, users who have no need for hotkeys can easily choose not to load a hotkey module in personal.rc, rather than editing each theme.

The next few sections define some personal settings for popup, lsxcommand and rainlendar. The lsxcommand settings specify the location of its search engine and history files, items that need only be set once according to user preference, hence their inclusion here. Rainlendar's general configuration and event files fall into the same category. Please note that the default settings shown above provide a sensible starting point, and may be added to or revised by users as they see fit.

Note that the settings for lsxcommand and rainlendar are in personal.rc and the related files are placed in subdirectories of $PersonalDir$. While not a requirement per se, this is a good way to add personal settings for any other modules as needed - add the settings to personal.rc, and any related files to a subdirectory of $PersonalDir$.

The settings in the first few sections of personal.rc are not to be modified except by advanced users who can appreciate the ramifications of their actions. The last section is where all users may freely define miscellaneous settings they wish to take effect in all themes. The other sections contain personal settings for specific modules, which may be added to or revised by knowledgeable users.


$PersonalDir$evars.rc

This file contains evars that specify the paths to certain executables.

;------------------------------------------------------------------------------
;    Edit *only* the paths as needed, and leave the file's *FORMAT* unchanged
;------------------------------------------------------------------------------

FileManager     "explorer.exe"
TxtEditor       "c:\Program Files\UltraEdit\UEDIT32.EXE"
CmdPrompt       "cmd.exe"
AudioPlayer     "d:\Winamp\Winamp.exe"
MediaPlayer     "d:\Winamp\Winamp.exe"
GfxViewer       "d:\ACDSee32\ACDSee32.exe"
GfxEditor       "d:\Photoshop\Photoshp.exe"
Browser         "d:\Opera\opera.exe"
DUN             "rasphone.exe"
Email           "d:\Eudora\Eudora.exe"
IRC             "d:\mIRC\mirc.exe"
FTP             "d:\CuteFTP Pro\cftppro.exe"
IM              "d:\Miranda IM\miranda32.exe"



;------------------------------------------------------------------------------
;    Add and define any additional evars you require
;------------------------------------------------------------------------------

;MiscApp        "c:\program files\misc\app.exe"

The evars in the first section are part of the OTS specification, they refer to what are generally considered to be common applications e.g. text editor, web browser, etc. - the names are self explanatory. The executable path associated with each evar is defined by a user according to their system and in this manner a general set of universally available evars is obtained. For example, a theme can safely use the $Browser$ evar to access whatever browser a user prefers.

The last section is strictly for end-users to define any additional application evars they desire. Themers are not to instruct users to add evars here as a requirement for installing or using their themes - that is what (amongst other things) themevars.rc is for.


$PersonalDir$hotkey.rc

This file contains user-defined hotkeys.

;------------------------------------------------------------------------------
;   sample hotkey config file: edit according to preference
;------------------------------------------------------------------------------

*Hotkey CTRL+ALT    U       !Run
*Hotkey CTRL+ALT    E       "$LitestepDir$step.rc"
*Hotkey CTRL+ALT    R       !Recycle
*Hotkey CTRL+ALT    LEFT    !VWMLeft
*Hotkey CTRL+ALT    RIGHT   !VWMRight
*Hotkey ALT         LEFT    !VWMMoveApp Left
*Hotkey ALT         RIGHT   !VWMMoveApp Right
*Hotkey CTRL        F1      "http://lsdocs.shellfront.org"

There's really not much to be said here... hotkey.rc quite simply contains any hotkey definitions a user cares to specify.


$PersonalDir$popup.rc

This file specifies the contents of the right-click popup menu.

;------------------------------------------------------------------------------
;   sample popup config file: edit according to preference
;------------------------------------------------------------------------------

*Popup !New !Popup              ;DO NOT DELETE THIS LINE (popup menu begins)

*Popup  "file manager"          "$FileManager$"
*Popup  "text editor"           "$TxtEditor$"
*Popup  !Separator
IF Win9x
  *Popup  "programs"            !DynamicFolder:"$Programs$"
ELSE
  *Popup  "programs"            !DynamicFolder:"$Programs$|$CommonPrograms$"
  *Popup  "admin"               !DynamicFolder:"$AdminToolsDir$"
ENDIF
*Popup  "quicklaunch"             "!PopupFolder:$QuickLaunch$"

*Popup ~New                     ;DO NOT DELETE THIS LINE (popup menu ends)

There's nothing to elaborate on for popup.rc - the contents of the right-click popup menu are entirely specified by this user-defined file.


$ThemesDir$themeselect.rc

This file determines which LiteStep theme is in use and is therefore the key to switching between LiteStep themes.

;------------------------------------------------------------------------------
;   edit this evar to switch themes
;------------------------------------------------------------------------------

ThemeDir "$ThemesDir$theme-X\"

The $ThemeDir$ evar specifies the path to the root folder of the LiteStep theme to be used, and the last include statement in step.rc uses this evar to load this theme's theme.rc file. Thus in order to switch themes, one merely has to set the $ThemeDir$ evar to the root folder of the desired LiteStep theme, and recycle LiteStep.


$ThemeDir$theme.rc

This is the main theme configuration file. It's contents are obviously entirely defined by the themer. Please see the theme creation section for further details.


$ConfigDir$themevars.rc

This is where themers should store theme-specific hotkeys, evars and the like so that these settings are located in one place where the end user can easily modify them as needed. Please see the theme creation section for further details.


$ConfigDir$popuptheme.rc

This file may be used by themers to define a theme-specific popup menu that is accessed by SHIFT-left-clicking on the desktop. Please see the theme creation section for further details.

summary

A fair amount of information on the OTS has been presented, hopefully in sufficient detail. It may seem like a great deal to absorb, especially for readers new to the OTS. It is hoped that the following summary will help clarify the OTS specification and demonstrate how simple it truly is.

  • step.rc: main LiteStep configuration file
  • key directory locations: define $ModulesDir$, $PersonalDir$, $ThemesDir$ evars in step.rc
  • theme switching: edit $ThemeDir$ evar in themeselect.rc to switch themes
  • module loading: automatically download and store modules in a common repository via NetLoadModule, themes no longer come packaged with modules
  • personal.rc: hotkey module loading, main user-defined settings file (includes user-defined evars.rc, hotkey.rc, and popup.rc)
  • two popup menus: user-defined right-click popup menu (popup.rc), themer-defined SHIFT-left-click popup menu (popuptheme.rc)
  • theme.rc: main theme configuration file
  • themevars.rc: used for storing any theme settings which users may customize

changelog

  • 2.0 - August 21, 2003 (development release)
    • definition of $ModulesDir$ moved from $ThemeDir$step.rc to $LiteStepDir$step.rc
    • definition of $PersonalDir$ moved from $ThemeDir$step.rc to $LiteStepDir$step.rc
    • addition of new evar $ThemesDir$ to $LiteStepDir$step.rc
    • definition of $ThemeDir$ moved from $ThemeDir$step.rc to $ThemesDir$themeselect.rc
    • inclusion of $PersonalDir$personal.rc moved from $ThemeDir$step.rc to $LiteStepDir$step.rc
    • inclusion of $ThemesDir$themeselect.rc added to $LiteStepDir$step.rc
    • $ThemeDir$step.rc renamed to $ThemeDir$theme.rc
    • addition of $OTSCfgMajorVersion$ and $OTSCfgMinorVersion$ evars to $PersonalDir$personal.rc, and $OTSMajorVersion$ and $OTSMinorVersion$ evars to $ThemeDir$theme.rc
    • elimination of $ShortcutsDir$ evar (use $Desktop$, $QuickLaunch$ etc. or theme-specific shortcuts dir instead)
    • themes do not include modules and use LoadModule anymore, modules loaded via NetLoadModule instead
    • creation of $LiteStepDir$modules to store modules (and deletion of $ThemeDir$modules)
    • addition of support for multiple users on NT-based platforms
    • OTS team: not exactly a team anymore - one project maintainer, with development of the OTS taking place in public by participants in the OTS Forum @ loose-screws.com
  • 1.0 - December 7, 2001
    • changes since 0.8 forgotten :| (there were changes though ;)
    • OTS specification publicly released
    • OTS team: ceeslans, darkfyre, grinch, jalist, laurent, morph, omar, un2
  • 0.8 - November 1, 2001
    • first draft of OTS released to a small audience
    • OTS team:
      omar