LiteStep 0.24.8 Manual (release notes)

LiteStep について

LiteStep は Windows のエクスプローラ・シェルに置き換えて使う、互換シェルの一つです。

エクスプローラ・シェルは普段から使っているデスクトップ環境、つまりスタートメニューやタスクバーを提供しています。LiteStep の開発者たち（そして数多くの LiteStep ユーザ）は、このエクスプローラ・シェルについて、動きが少なく、扱いが面倒で、使っていて気分が悪くなることを他にも見つけていました。LiteStep は、そうした理由でいまここにあるのです。

LiteStep がその [エクスプローラ・デスクトップの] 環境を置き換えるにあたっては、あなたなら便利だと思うかもしれない（そして人目を引く）やり方を好きに使えます。LiteStep は、あなたがデスクトップというインターフェイスを、他になく、快適で、ダイナミックなものに作り上げるやり方を提供するのです。LiteStep ユーザが作り上げるデスクトップ環境というのは、何もないスクリーンにホットキーやホットスポットをベースに十分な機能を割り当てることからはじまって、目を楽しませるモーフィング・メニューやスライドするツールバー、そしてそこにはシステムの稼働状況から最新のニューズや天気の概況までがわかるグラフィカルで有益な表示までをも含んでいる。

（参考：http://en.wikipedia.org/wiki/Operating_system_shell）[日本語版はない]

それから以下にご紹介する、わたしたちのコミュニティを形作っている多くのサイトもご参考に。

http://www.lsdev.org/

LiteStep 開発チームのポータルサイト。公式な LiteStep のバージョンを全て公開しており、LiteStep 用のモジュール開発のリソースや、コミュニティ内でやりとりされている情報の連絡先も紹介している。

http://www.litestep.net/

LiteStep のコミュニティ内で最大のテーマ・ギャラリーと利用者数をもつサイト。スクリーンショットやテーマの公開リポジトリをもち、モジュールのダウンロードもできる。LiteStep についてあらゆるテーマを扱っている、ユーザフォーラムもある。

http://www.ls-universe.info/ [2010-02-06: http://www.ls-universe.ls-themes.org/news.php]

x* シリーズのモジュールを公開している。他のモジュールもダウンロードできるし、コミュニティ内のニューズを配信したり、テーマ・ギャラリーもある。

http://www.ls-themes.org/

————————-
- Module downloads.
- Screenshot and theme repository.
- LiteStep IRC Logs

http://www.shellfront.org/modules-list.php
——————————————
- Module downloads.

http://www.litestep-france.net/
——————————-
- French community website.

– SYSTEM REQUIREMENTS ———————————————————

LiteStep requires only that you are running a 32bit version of Windows:

Windows 95, Windows 98(se), Windows ME, Windows 2000, Windows XP, Windows 2003

NOTE: Windows Vista/2008 32bit versions are *NOT* supported in 0.24.8! Please
check our website for experimental builds containing support for running
under both 32bit and 64bit Windows XP/Vista/2008/Win7 versions.

LiteStep is designed to consume less resources than the Explorer shell which it
replaces; so there are no system requirements above and beyond that which is
needed for a normal Windows-based system.

However, depending on what modules (add-ons) are loaded, any given desktop
environment will have its own system requirements. This may range from being
only compatible with Win2K/XP or requiring a 3d accelerated graphics card. Be
sure to read the accompanying documentation for any theme or module that you
choose to install.

– INSTALL ———————————————————————

NOTE:
—–
You are about to install a replacement shell for Windows. A shell is not a
normal application; it runs as a special system process. Replacing the shell
is not a supported procedure by Microsoftｮ, and as such, it is possible that if
you do something wrong, you may end up with a non functional desktop and/ or
your system may display an erroneous error message asking you to re-install
Windows. Do NOT panic, a very simple solution will put you back to where you
need to be, so that you can fix whatever mistake you made, and try again.
Please read the documentation on this topic that came with your LiteStep
distribution, or review the “Manual Install” steps below.

Now that you are ready to get going, there are a couple of methods to start
using LiteStep.

You MUST have administrative access to install LiteStep.

A) LiteStep Distributions (Recommended and automated)
—————————————————–

The recommended way to start with LiteStep is to install one of the community
driven LiteStep distributions. Typically these distributions come with a
friendly step by step installation wizard that will set your system up using a
default desktop environment and theme. Currently we recommend using LOSI -
“LiteStep Open Source Installer” implementing the Open Theme Standard 2 (OTS2)
by Tobbe.

LOSI may be downloaded from at http://www.tlundberg.com/LOSI/

Regardless of which distribution you use, you will find plenty of help on the
LiteStep Mailing List (LSML) and user forums on one of the community websites.
Please join us in our IRC channel #litestep on Freenode (irc.freenode.net) if
you have any immediate support need. However, be patient when asking a
question as IRC is renown for being full of idlers.

B) LiteStep From Scratch (Manual install and configuration)
———————————————————–

STOP: If you are NOT highly familiar with editing the registry or reading
lots of documentation and editing text configuration files, then this
procedure is NOT for you! Please use a LiteStep Distribution. Thank you.

For the do-it-yourself type, please thoroughly read the following before
proceeding. It will save you a lot of headache. I promise.

Create a folder for LiteStep. Generally this is done at “C:\LiteStep”.

Extract the contents of “LS-0.24.8.zip” to this folder. Once the contents are
extracted, there should be a file located at “C:\LiteStep\litestep.exe”.

Create a text file named “step.rc” and place it in the same folder as
“litestep.exe”. Using the previous example location, this empty text file
should now be at “C:\LiteStep\step.rc”.

Next, consult the section “USAGE (HELP)” to configure LiteStep via the step.rc
text file (A sample step.rc is provided in that section). Do NOT set LiteStep
as your shell until you have configured it, otherwise you will be left with a
dysfunctional (yet recoverable) system.

To set LiteStep as your shell, follow these instructions:

1. Win9x/ME

- Using a text editor (e.g. Notepad) open the Windows System file named
“system.ini”. This file’s location is normally “C:\Windows\system.ini”

- Locate the line that begins with “shell=”. This line is located in the
“[boot]” section. Typically the full line looks like “shell=explorer.exe”
(without quotation marks). Comment out this line (which disables it) by
placing a semi-colon at the beginning of the line. The line should now
look like “;shell=explorer.exe” (without the quotation marks).

- Create a new “shell=” line in the same location as the one removed. This
new line should contain the location of “litestep.exe”. For example it
might look like “shell=C:\LiteStep\litestep.exe” (without the quotation
marks).

- Reboot your system.

- README! When you reboot, if you get the error:

“CANNOT FIND <shell file name> PLEASE REINSTALL WINDOWS”

Do NOT reinstall windows! Just simply follow the instructions below to
put your shell back to the default:

Boot into DOS (press F8 before Windows starts, or use a DOS boot disk).
Issue the command “edit C:\Windows\system.ini” adjusting for the location
of your system.ini file. Delete the new line you created in the previous
steps, and uncomment the line you previously disabled. Do this by
deleting the semicolon at the start of the line. You should now have one
line that starts with “shell=” in the “[boot]” section of the “system.ini”
file, “shell=explorer.exe”. Save the file and reboot your system.

2. Win2K/XP

- Note: If you are NOT an administrator, you will most likely NOT be able to
set LiteStep as your shell. The only exception to this is if your System
Administrator has enabled “per user” shells. This is highly unlikely.

While it is “possible” to run LiteStep at the same time as the default
Explorer shell, it is discouraged and completely unsupported. Good luck!

- Open “regedit” or a similar utility.

- To ENABLE “per user” shells:
* Locate the following key:

HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion
\IniFileMapping\system.ini\boot

* Change the string value named “Shell” to:

USR:Software\Microsoft\Windows NT\CurrentVersion\Winlogon

- To DISABLE “per user” shells:
* Locate the following key:

HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion
\IniFileMapping\system.ini\boot

* Change the string value named “Shell” to:

SYS:Microsoft\Windows NT\CurrentVersion\Winlogon

- To set the system’s DEFAULT shell (The shell all users use if “per user”
shells are disabled, or if a user does not have a custom shell specified):
* Locate the following key:

HKEY_LOCAL_MACHINE\Software\Microsoft\Windows NT\CurrentVersion\Winlogon

* Change the string value named “Shell” to the location of the file you
want to use as your default system shell.

For LiteStep use (adjust path as necessary):

C:\LiteStep\litestep.exe

For Explorer use (do not specify a path):

Explorer.exe

- To set the shell for the currently logged in user:
* Locate the following key:

HKEY_CURRENT_USER\Software\Microsoft\Windows NT\CurrentVersion\Winlogon

* Change (create) the string value named “Shell” to the location of the
file you want to use as your current user shell.

For LiteStep use (adjust path as necessary):

C:\LiteStep\litestep.exe

For Explorer use (do not specify a path):

Explorer.exe

- To use any shell besides Explorer, the following key MUST be changed.
If you do not configure this key, you will not be able to use the
Explorer File Manager.

* Locate the following key:

HKEY_CURRENT_USER\Software\Microsoft\Windows\CurrentVersion\Explorer

* Change (create) the DWORD value named “DesktopProcess” to a value of 1.

- If you changed the “per user” shell setting, you MUST reboot. Otherwise
simply log off. When you return to the desktop, LiteStep will be running
as your shell if you managed to configure everything correctly.

- If you end up with a blank or otherwise non-functional desktop. Press
CTRL+SHIFT+ESC key combination. The Windows Task Manager will open. Use
the File menu to Run a New Task. Launch your registry editor and use the
previous instructions to set your system shell back to the default
Explorer shell.

– 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.