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
    litestep.exe !ReloadModule „C:\LiteStep\modules\popup.dll“

  <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

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

  2. Conditional Expansions

   Win2000
   Win2003
   Win95
   Win98
   Win9X
   WinME
   WinNT
   WinNT4
   WinXP

  3. Resource Expansions

   CompileDate
   ResolutionX
   ResolutionY
   UserName

  4. GUID Folder Mapping Expansions

   AdminTools
   BitBucket
   Controls
   Dialup
   Documents
   Drives
   Network
   NetworkAndDialup
   Printers
   Scheduled

 F) !Bang Commands
 —————–

  !About
  ——
   Displays the About LiteStep dialog.

   Usage:
    !About

  !Alert
  ——
   Displays a message box.

   Usage:
    !Alert <message> {title}

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

   Usage:
    !CascadeWindows

  !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

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

   Usage:
    !Reload

  !ReloadModule
  ————-
   Reloads a specific module.  Does not reload configuration files.  If the
   specified module is not already loaded, it is loaded.

   Usage:
    !ReloadModule <path>

  !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

  !UnloadModule
  ————-
   Unloads a specific module.

   Usage:
    !UnloadModule <path>

 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
PopupAdaptiveWidth
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}