# Usage (Help)

The following section lays out the structure of LiteStep, and the available configuration options.  When used within this document to describe a parameter value, <> means a required parameter, and {} means an optional parameter.
An always available built-in „Recovery Menu“ can be accessed by pressing the key combination: CTRL+ALT+F1 that is, press and hold the CTRL key and the ALT key then depress the F1 key and release all three. A popup menu will appear at your mouse cursor location.  This menu can be used recover from a broken configuration.

A) LiteStep Structure
———————

LiteStep is designed around a modular plugin system.  The LiteStep „core“ by itself is rather useless to you until you configure and load a plugin.  These plugins are called „Modules“ and are available from several LiteStep community websites (See the ABOUT section).

The LiteStep core consists of:
– litestep.exe     Main executable.  Loads modules, handles window messages
communication.  Runs startup apps, includes DDE and tray
services.

– lsapi.dll        LiteStep API for modules to use.  Loads and parses step.rc;
handles $evars$ and all other configuration.  Manages !bang
commands, includes core !bangs.

– hook.dll         The system shell hook used by some legacy LiteStep modules
for receiving global system messages.

LiteStep also depends on „libpng13.dll“ and „zlib1.dll“ for Portable Network Graphics (PNG) image support.  Those two files must exist in the same directory as „litestep.exe“ or in the system path.

LiteStep uses a text configuration file named „step.rc“ which must exist in the same directory as „litestep.exe“.

LiteStep loads Modules which use the LiteStep API „lsapi.dll“ to read their configuration values, create advanced graphical displays and interact with the LiteStep core to provide you with a highly functional and eye-caching desktop.

B) Command Line Parameters
————————–

„litestep.exe“ has several command line switches to perform various actions.

-nostartup
———-
Disables running Windows startup items when loading LiteStep.

This is useful on Windows 95, Windows 98(se) and Windows ME if you need to restart LiteStep.

On Windows 2000 and Windows XP this switch is not needed as startup items are ran only once per session.

Usage:
litestep.exe -nostartup

-startup
——–
Force running Windows startup items when loading LiteStep.

On Windows 2000 and Windows XP, startup items are run only once per session. Using this switch overrides that behavior and forces startup item execution.
This is not useful on Windows 95/98(se)/ME as startup items are always ran.

Usage:
litestep.exe -startup

!<bang command>
—————
Passes the specified !bang command and parameters to a currently running instance of LiteStep.  The previous instance of LiteStep receiving the !bang command executes the specified !bang command. This is useful for external control of LiteStep, perhaps from a script.

Usage:
litestep.exe !recycle

<file>
——
Specifies the absolute path of the „step.rc“ configuration file LiteStep should read its directives from.  This overrides the default of using the step.rc file located in the same folder as litestep.exe.

Usage:
litestep.exe C:\LiteStep\step.rc

C) Step.rc Syntax
—————–

The step.rc is formatted in a <command> {value} directive syntax.

– There may be one directive per textual line.

– <command> must not begin with a digit, be quoted, bracketed or in any other
way use the reserved characters of the step.rc parsers except in the special
case of * character.  The following characters are reserved:

! $& * ( ) – + = [ ] ; “ ‚ < > , / Furthermore it is recommended that you do not use @, #, or | (vertical bar), because these characters may become reserved in the future. – {value} is dependent per <command> directive and is explained in each directive’s documentation. If the directive is required by a Module, please read the corresponding documentation provided with the Module. See the section „Step.rc Directive Parser“ for more information on possible data types. LiteStep employs three levels of parsing to step.rc at load-time and expands variable references at runtime. 1. Step.rc File Parser – The step.rc File Parser uses these reserved characters: ;[]“‚ ; Used at the beginning of a textual line to delineate a comment. Comments are lines that are ignored by the Directive Parser. A comment may also exist at the end of a <command> directive. Everything after (and including) the semicolon is ignored. See „Step.rc Directive Parser“ for other reserved character descriptions. – The File Parser behaves similarly to a pre-processor. The File Parser is the first to touch the step.rc. – The step.rc File Parser evaluates the following Directives: Include If ElseIf Else Endif 2. Step.rc Directive Parser – The step.rc Directive Parser uses these reserved characters: *$[]“‚

*  Used at the beginning of a <command> directive to delineate the ability
to specify multiple <command>s of the same name (one per line).

 Used as a set around a {value} parameter to delineate that a variable
expansion should occur for that parameter.

[] Used as a set around a {value} parameter to delineate that the contents
are a single token value.

„“ Used as a set around a {value} parameter to delineate that any enclosed
whitespace is part of the value (whitespace is TABs and SPACEs).

“ Used as a set within the {value} parameter to delineate that the
enclosed contents are a sub value.

– The step.rc Directive Parser recognizes several {value} data types.

(The examples given have fictitious directive names)

Boolean
Must be either TRUE or FALSE.

Example: MyModuleHideIfEmpty TRUE

Color
Must be either in RGB Hexidecimal or Decimal Triplet formats.

Example     (Hex): MyModuleBackgroundColor 4682B4
Example (Decimal): MyModuleBackgroundColor 70 130 180

Integer
Must be a real Integer number

Example: MyModuleWidth 32

String
Can be any non-reserved character set enclosed in quotation marks.

Example: MyModuleDisplayText „This Module Rocks!“

Undefined/Line
An undefined value type can contain any data type, and is interpreted by
a particular Module’s implementation and documentation.  For example
a Module could require a single Directive Line contain both an Integer
and String data type within a single {value}.

Example: MyModuleFont Bold 16 „Courier New“

3. Step.rc Evaluation Parser

– The Evaluation Parser is used by the File Parser in evaluation of the
conditional directives: If and ElseIf.  It is also used by the Runtime
Variable Expansion handler.  The Evaluation Parser looks at the expression
in these parts: Variables (values), Operators and Functions.

– Data Types

Values in an expression are of one three fundamental types: boolean,
number, or string.  Booleans are logical true or false values.  Numbers
are IEEE 754 double-precision numbers, which includes the special values:
positive/negative infinity and Not a Number (NaN).  There is no distinct
integer data type, as integers are subsumed by the number type.  Strings
are sequences of characters.

As an expression is evaluated, values are automatically converted to
different types as necessary.  In the event that an explicit type
conversion is needed, use one of the conversion functions.  Whether
implicit or explicit, type conversions follow the same set of rules, which
are described in the section on Functions, below.

– Undefined Variables

For compatibility reasons, conditional expressions (If and ElseIf) can use
undefined variables without generating an error.  Any operator or function
applied to an undefined value produces an undefined result.  If the result
of a conditional expression is undefined, then it is treated as if it were
false.

This behavior, while supported in 0.24.8, will be removed in the future.
The correct way to detect undefined variables is to use the „defined“
keyword:

If defined(SomeVariable)
If not defined(AnotherVariable)

Defined behaves like a function that takes a variable name and returns
true if that variable is defined or false if it is not.  Defined is not,
however, a real function because its argument must be a variable name.

Using an undefined variable in an inline expression (one enclosed in $’s) generates an error, just as it always has. – Operators The operators that LiteStep supports are listed below from highest precedence to lowest precedence. With the exception of the three unary operators, all operators are binary and left associative. Parentheses: ( ) Unary: + – not Multiplicative: * / div mod Additive: + – Concatenation: & Relational: = < <= > >= <> != Logical AND: and Logical OR: or Identity (unary +) Returns the operand, converted to a number. Negation (unary -) Returns the negative of the operand, converted to a number. Logical Complement (not) Returns the logical complement of the operand, converted to a Boolean. Multiplication (*) Returns the product of the operands, converted to numbers. Division (/) Returns the ratio of the operands, converted to numbers. Integer Division (div) Returns the quotient from a truncating division of the operands, converted to numbers. Modulus (mod) Returns the remainder from a truncating division of the operands, converted to numbers. Addition (+) Returns the sum of the operands, converted to numbers. Subtraction (-) Returns the difference of the operands, converted to numbers. Concatenation (&) Returns the concatenation of the operands, converted to strings. Relational Operators (=, <, <=, >, >=, <>, !=) Returns true if the given relationship holds between the operands. If both operands are strings then they are compared as strings, otherwise they are compared as numbers. The inequality operators <> and != are interchangeable. String comparison is case-sensitive. Logical AND (and) Returns true if both of the operands, converted to Booleans, are true. Logical OR (or) Returns true if either of the operands, converted to Booleans, are true. – Functions LiteStep supports a small set of built-in functions that you can use in expressions. These functions are listed below in alphabetical order, with a short description. abs(number) Returns the absolute value of the argument, converted to a number. boolean(value) Returns its argument, converted to a Boolean. Zero, Not a Number (NaN), and the empty string map to false. All other values map to true. ceil(number) Returns the ceiling (least greater integer) of the argument, converted to a number. contains(string, string) Returns true if the second argument, converted to a string, is a substring of the first argument, converted to a string. endsWith(string, string) Returns true if the second argument, converted to a string, is a suffix of the first argument, converted to a string. floor(number) Returns the floor (greatest lesser integer) of the argument, converted to a number. if(condition, then, else) Converts its first argument to a Boolean. If its true, returns the second argument (then). If its false, returns the third argument (else). This function lets you do simple conditionals in an inline expression. integer(value) Returns the argument, converted to an integer. Conversion to integer is the same as conversion to number, except that infinites and NaNs become zero. length(string) Returns the length of the argument, converted to a string. lowerCase(string) Returns the argument, converted to a string, in lower case. max(number, number) Returns the larger of its arguments, converted to numbers. min(number, number) Returns the smaller of its arguments, converted to numbers. number(value) Returns its argument, converted to a number. For Booleans, true maps to 1 and false maps to 0. A string is parsed as a numeric literal; if parsing fails, the string is mapped to NaN. pow(number, number) Returns the first argument, converted to a number, raised to the power of the second argument, converted to a number. round(number) Returns the argument, converted to a number, rounded to the nearest integer. startsWith(string, string) Returns true if the second argument, converted to a string, is a prefix of the first argument, converted to a string. string(value) Returns the argument, converted to a string. For Booleans, true maps to „true“ and false maps to „false“. Numbers are formatted as strings in the standard way. sqrt(number) Returns the square root of the argument, converted to a number. upperCase(string) Returns the argument, converted to a string, in upper case. 4. Runtime Variable Expansion – Variable expansion supports textual replacements and expression evaluation when enclosed within a set of$ characters.
(e.g. $LiteStepDir$ or $ScreenWidth – 32$)

See „Step.rc Evaluation Parser“ section above.

5. Images, Icons and Magic Pink

– Modules may require the loading of an image file.

LiteStep can currently load BMP and PNG image files as well as icons from
ICO files and resource libraries.

(The examples below use the fictitious directive „ModuleBackgroundImage“)

To load a normal BMP or PNG image file, simply specify the path to the
file in the Module’s configuration directive that requires an image file.

ModuleBackgroundImage „C:\folder\image.bmp“

To load an icon from an ICO file or resource library for use as an image,
use the syntax:

ModuleBackgroundImage „.extract=<icon resource>“

Where <icon resource> specifies the icon to load. See below for further
details on the syntaxt for loading icons. Please note that the „.extract=“
prefix is required when loading an icon file when the Module is expecting
a normal image file.

To load and merge multiple images into a single image, separate the file
paths with the pipe character | using the syntax:

ModuleBackgroundImage „C:\folder\image1.png|C:\folder\image2.png{|…}“

where the last image specified will be on bottom, and the first image
specified will be on top. It is possible to include an icon resource in
this merging syntax as well, just use the „.extract=“ prefix.

Relative paths refer to files in the LiteStep image directory. Refer to
LSImageFolder Step.rc directive for details.

– If an image contains the „magic pink“ RGB color 255 0 255 (FF00FF) then
the portion of the image that is „magic pink“ will be rendered transparent
to the content below it.  Some modules require a separate configuration
setting to enable or disable transparency support.  Refer to the Module’s
documentation.

– Modules may require the specific loading of icon files.  LiteStep supports
loading icons from any icon resource file or archive as well as loading an
icon associated with a desktop.ini file.

It is possible to load an icon using the following syntax:

Directly load an icon file:

„C:\path\to\file.ico“

Extract an icon from a resource library (.icl, .dll, .exe, et cetera)
using the specified resource index (in this example, index 9):

„C:\path\to\icon\library.icl,9“

Extract the associated icon from a folder’s „desktop.ini“ file:

„C:\path\to\some\folder\“

Relative paths refer to files in the LiteStep image directory. Refer to
LSImageFolder Step.rc directive for details.

D) Step.rc Directives
———————

Include <file>
————–
Specifies an additional step.rc format file to include.

Usage:
Include C:\LiteStep\config\theme.rc

If, ElseIf, Else, and EndIf
—————————
Conditionally parse a section of the step.rc.

The If directive marks the start of a conditional section.  The If directive
evaluates an expression to produce a true (nonzero) or false (zero) result.
If the result is true then the lines following up to the next ElseIf, Else,
or EndIf are parsed, otherwise they are ignored.

The ElseIf directive behaves like an If, but the expression is evaluated only
if all of the previous If and ElseIf expressions have evaluated to false.

The Else directive parses the lines that follow it only if all the previous
If and Elseif expressions have evaluated to false.  There may be at most one
Else and it must follow any ElseIf statements.

The EndIf directive marks the end of a conditional section.  Each If
directive must have a corresponding EndIf.  If-EndIf blocks may be nested to
any depth.

See „Step.rc Evaluation Parser“ section above for conditional operators and
expression syntax.  When referencing LiteStep variables (e-vars) do not
enclose the variable references in dollar signs ($) when they occur in conditional expressions (dollar signs are only used in Runtime Variable Expansion – see above named section). Usage: If <expression> <lines> ElseIf <expression> <lines> Else <lines> EndIf LoadModule <file> —————– Specifies a Module (plugin) to load. Usage: LoadModule C:\LiteStep\modules\popup.dll LSNoStartup <boolean> ——————— Disables running of system Startup items. Note: LiteStep must be restarted for this setting to take affect. Usage: LSNoStartup TRUE LSAutoHideModules <boolean> ————————— Automatically hides all LiteStep modules from the display when an application enters Full Screen mode. (e.g. A full screen game) Usage: LSAutoHideModules TRUE LSNoShellWarning <boolean> ————————– Disables the warning issued when loading LiteStep if another shell is already running. Do not use this setting unless you know what you are doing! Note: LiteStep must be restarted for this setting to take affect. Usage: LSNoShellWarning TRUE LSSetAsShell <boolean> ———————- Registers LiteStep as the system shell on load. This will enable an automatic re-spawn of LiteStep if LiteStep exits inadvertently. However, this feature is experimental and not recommended at this time. If you experience problem using Explorer as your file manager, try disabling this setting. Note: LiteStep must be restarted for this setting to take affect. Usage: LSSetAsShell TRUE LSUseSystemDDE <boolean> ———————— Enables Dynamic Data Exchange under LiteStep. This is required to enable many features of the Explorer file manager and other system services. However its functionality is not fully developed at this time and irregularities may exist. If you experience resource usage troubles, try disabling this setting. Note: LiteStep must be restarted for this setting to take affect. Usage: LSUseSystemDDE TRUE LSDisableTrayService <boolean> —————————— Disables the Icon Notification (Systray) service. This is useful if you have to run LiteStep on top of another shell, or if you have another application implementing the service. Note: LiteStep must be restarted for this setting to take affect. Usage: LSDisableTrayService TRUE LSImageFolder <path> ——————– Sets the default folder that LiteStep looks in when loading images. This will default to <install path>\images\ (e.g. C:\LiteStep\images\). Usage: LSImageFolder „C:\LiteStep\themes\mytheme\images\“ ThemeAuthor <string> ——————– Sets the name of the Author of the current Theme and is displayed in the !About box dialog. Usage: ThemeAuthor „Mr. ThemeWizard“ ThemeName <string> —————— Sets the name of the current Theme and is displayed in the !About box dialog. Usage: ThemeName „Elite-h/\x“ LSLogLevel ———- (Deprecated) LSLogFile ——— (Deprecated) E) Step.rc Variables ——————– Variables that are evaluated at runtime when enclosed in$ characters.

1. Folder Path Expansions

CommonDesktopDir
CommonFavorites
CommonPrograms
CommonStartup
Desktop
DesktopDir
DocumentsDir
Favorites
Fonts
History
Internet
InternetCache
LiteStepDir
Nethood
Printhood
Programs
QuickLaunch
Recent
Sendto
Startup
Templates
WinDir

2. Conditional Expansions

Win2000
Win2003
Win95
Win98
Win9X
WinME
WinNT
WinNT4
WinXP

3. Resource Expansions

CompileDate
ResolutionX
ResolutionY

4. GUID Folder Mapping Expansions

BitBucket
Controls
Dialup
Documents
Drives
Network
NetworkAndDialup
Printers
Scheduled

F) !Bang Commands
—————–

——
Displays the About LiteStep dialog.

Usage:

——
Displays a message box.

Usage:

—————
Cascades all non-minimized application windows.

Usage:

!Confirm
——–
Displays a message box that allows the user to choose Yes or No.  Executes a
different command based on the users choice.

Usage:
!Confirm <message> {title} <yes-command> <no-command>

!Execute
——–
Executes a sequence of programs or bang commands.

Usage:
!Execute [<command-1>]{[<command-2>]…[<command-n>]}

!HideModules
————
Hides all modules.

Usage:
!HideModules

!Logoff
——-
Logs off the current user.  Does not display a prompt first.

Usage:
!Logoff

!MinimizeWindows
—————-
Minimizes all application windows.

Usage:
!MinimizeWindows

!None
—–
Does nothing.  Useful as a placeholder where a command is required.

Usage:
!None

!Quit
—–
Shuts down LiteStep, but does not shut down Windows.  Be careful as there
will not be a shell running after this command is executed.

Usage:
!Quit

!Recycle
——–
Reloads configuration files and modules.  You can pause a recycle operation
by holding down the shift key.  This allows you to replace a module without
quiting LiteStep.

Usage:
!Recycle

!Refresh
——–
Reloads configuration files and notifies modules to update, however not all
modules support this.

Usage:
!Refresh

——-
Reloads configuration files.  Does not reload modules or notify them.

Usage:

————-
Reloads a specific module.  Does not reload configuration files.  If the

Usage:

!RestoreWindows
—————
Restores all minimized application windows.

Usage:
!RestoreWindows

!Run
—-
Displays the Windows Run dialog box.

Usage:
!Run

!ShowModules
————
Shows all modules after having been hidden using !HideModules.

Usage:
!ShowModules

!Shutdown
———
Displays the Windows Shutdown dialog box.

Usage:
!Shutdown

!SwitchUser
———–
On Windows XP with Fast User Switching enabled, this command will switch to
another user without logging off the current user.  On other systems this
command will lock the workstation.

Usage:
!SwitchUser

!TileWindowsH
————-
Tiles all non-minimized application windows horizontally.

Usage:
!TileWindowsH

!TileWindowsV
————-
Tiles all non-minimized application windows vertically.

Usage:
!TileWindowsV

!ToggleModules
————–
Toggles the visibility of all modules.  See !HideModules and !ShowModules.

Usage:
!ToggleModules

————-
Unloads a specific module.

Usage:

G) Sample Step.rc
—————–

STOP: Copying and pasting the following to your step.rc will *NOT* give you a
working LiteStep installation.  You will first need to download the
relevant modules and extract them to your LiteStep folder.

NOTE: The step.rc contents is what exists between {BeginStepRC} and {EndStepRC}
not including those two delimiters.  Create the step.rc file in the same
folder as litestep.exe.

{BeginStepRC}
; This is an EXAMPLE step.rc file.  This example will NOT work without
; downloading the necessary modules (plugins) and placing them in the
; same folder as litestep.exe.

; First, we need to load the modules (plugins) that we want to use.
; You may download these modules from:
http://www.shellfront.org/modules-list.php
; Extract these modules into your LiteStep folder.
LoadModule $LiteStepDir$hotkey.dll    ; hotkey-2.0.zip
LoadModule $LiteStepDir$popup2.dll    ; popup2-2.1.5.zip

; Configure a Hotkey combination to launch Notepad and open this
; step.rc configuration file.
*Hotkey WIN+CTRL   S   notepad.exe „$LiteStepDir$step.rc“

; Configure a Hotkey to recycle (restart) LiteStep.  This will reload
; this step.rc configuration file with any changes, and reload all modules.
*Hotkey WIN+CTRL   R   !recycle

; Configure a Hotkey to open an explorer window and quit LiteStep.
*Hotkey WIN+CTRL   Q   !execute [explorer.exe /e,/root,,$Drives$][!quit]

; Configure a Hotkey to display LiteStep’s „About“ dialog.
*Hotkey WIN+CTRL   A   !about

; Configure a few default hotkeys that emulate Explorer’s functionality
*Hotkey WIN        C   explorer.exe /root,,$Controls$
*Hotkey WIN        E   explorer.exe /e,/root,,$Drives$
*Hotkey WIN        L   !logoff
*Hotkey WIN        M   !MinimizeWindows
*Hotkey WIN+SHIFT  M   !RestoreWindows
*Hotkey WIN        R   !run

; NOTE: pressing CTRL+ESC or the Windows Key will display the Popup Menu.
; The Hotkey module automatically configures those hotkeys by default.

; Next, we will configure a basic Popup Menu.
HotlistName „LiteStep 0.24.8“
PopupIcons
PopupMinWidth 125
PopupMaxWidth 300
PopupNoBevel

*Popup „My Computer“ !PopupMyComputer
*Popup !Separator
IF Win9x
*Popup „Start Menu“ !PopupDynamicfolder:“$Startmenu$“
ENDIF
IF WinNT
*Popup „Start Menu“ !PopupDynamicfolder:“$Startmenu$|$CommonStartMenu$“
ENDIF
*Popup !Separator
*Popup „Control Panel“ !PopupControlPanel
*Popup „Recent Documents“ !PopupRecentDocuments
*Popup !Separator
*Popup .icon=“$LiteStepDir$litestep.exe,0″ „Running Tasks“ !PopupTasks
{EndStepRC}