Contents

Introduction

Installing the program

Getting started

Main components

System window

Icon windows

Explorer

Wastepaper bin

Taskbar

Start menu

Shortcuts

General

File management

Working with descriptions

Keyboard commands

Selecting objects

Dialog boxes

Bin properties

Desktop properties

File/folder properties

File system properties

Find files

Run program

Start menu properties

System properties

Shortcut/alias properties

Taskbar properties

Advanced

Defining keyboard shortcuts

Multiple bin locations

Using custom icons

Environment strings

The System tray

Custom drive names

Miscellaneous settings


Introduction

Calmira is a complete 16-bit shell that lets you manage files, launch applications and control tasks.  It brings Windows 3.1 up to date with some of the advanced user interface enhancements from the Windows world, and for most people, provides welcome relief from the awkwardness of File Manager.

The installation is simple -- just copy a few files into a directory, and you are ready to go.  If you have used Windows 95 before, you should feel quite at home, but in any case, it won't take long to get used to the new look and feel.

There many settings and options which you can customise, and if that's not enough, then you can even re-write it (or get someone to do it for you!). Calmira is free and the Delphi source code is included in this package.  You are free to modify and redistribute it under the terms of the GNU General Public License, version 2 or later.

Windows, Windows95 and MS-DOS are registered trademarks of Microsoft Corporation.  4DOS is a registered trademark of JP Software Inc.  All other products are trademarks or registered trademarks of their respective owners.


Installing the program

Supplied files

You should have received at least the following:

calmira.exe	Main program
taskbar.exe	Taskbar module
explorer.exe	Launches the tree view window
wndhooks.dll	Low-level functions used by taskbar
calmira.ini	Stores main program settings
start.ini	Stores start menu structure and data
calmira.hlp	This help file
readme.txt	The latest update information
license.txt	The GNU General Public License
devnotes.txt	Development notes for programmers
file_id.diz	For vendors and sysops.
ctl3dv2.zip	Contains 3D controls library
source.zip	Contains the full Delphi source code

Where to put the files

Copy all the files into a single directory of your hard disk, for example, c:\calmira.  Avoid putting these in your Windows directory.

The INI files are constantly modified, so the directory must have write permission/access.  (If you received the files on a CD-ROM, they might have the read-only bit set, so use File Manager to remove them from the copies).

3D controls library

Calmira requires ctl3dv2.dll, which is supplied in a ZIP file.  If you don't already have this file in your \windows\system directory, unzip it to there.  Do not leave ctl3dv2.dll in the same directory as Calmira.

Setting up the shell

If you don't need Program Manager any more, you can use Calmira as the Windows shell.  You need to modify the system.ini file in your Windows directory, so make a backup copy first.  In the [boot] section there is a line which reads something like:

shell=c:\windows\progman.exe

Comment this out by adding a semi-colon in front of it, and add a line pointing to Calmira, for example

;shell=c:\windows\progman.exe

shell=c:\calmira\calmira.exe

Exit to DOS and restart Windows for the new shell to take effect.  If you encounter problems when loading Windows, reset the shell to Program Manager.


Getting started

Here are the major components of Calmira -- click on a graphic to jump to the desired topic.  Remember that you can get context sensitive help at any time by pressing F1, and right clicking on many objects will pop up a context sensitive menu.  Explore, and have fun...

System window

Icon windows

Explorer

Wastepaper bin

Taskbar

Start menu

Shortcuts


System window

This contains the disk drives which have been detected, plus some useful programs.  When you close the system window, Calmira will close down.

Settings dialogs

The system window is the centre of Calmira, and if you right click between the icons, a popup menu appears, which lets you access dialogs to configure the program.  These dialog boxes are often accessible from elsewhere but you can always open them from here.


Icon windows

These provide the facilities for managing your files.  Each window displays the contents of one folder, and each folder may only be shown by one window.  If you try and open a folder which is already displayed, the existing window is restored and brought to the front, as required.

If you right click over an icon, the object menu appears.  Commands in the top half affect all selected objects, those in the bottom half work on the focused object.  If you right click in the space between icons or the grey window border, the window menu appears.  These commands affect the icon window or the folder it represents.

To open the parent folder, press Backspace.  To close or arrange groups of windows, see the keyboard commands summary .

Managing files and folders

First select the objects which you want to work with.  To delete, rename or describe them, pick the appropriate command from the object menu.  To copy, drag the icons to the destination (either a window or another icon).  If you right-click during the drag, the operation is toggled between a copy and a move.

See also:

File Management

Explorer

Shortcuts and aliases

Wastepaper bin


Selecting objects

When you click on an icon, it becomes focused (with a dotted box around it).  It is also selected if it has a grey background.  Some file operations work on all selected items, others just on the focused one.

To select a single item

Click on the icon with the left mouse button.

To select a range

1   Select the first item in the range.

2   Hold down SHIFT.

3   Select the last item in the range.

To toggle the selection of a single item

Hold down CTRL when you left-click on it.

To select a block

Press the left mouse button when the cursor is to the top left of an icon.  Then stretch the lasso around the icons you wish to select.

To de-select items

Click on an unselected file/folder or click on an empty space.

To select or de-select everything in the window

Left click on the right hand label.  If there are items currently highlighted, all items are de-selected.  Otherwise everything is selected.

To select files using wildcards

Right click on the right hand label to open the Select Files box.


Explorer

This displays all drives and folders in a branching structure similar to File Manager.  Use it to give a broad view of your file system while you navigate through the folders.

Win95 Explorer style view

To combine the tree with an icon window for an interface like the Windows 95 Explorer, right click on the tree and check the "Show file window" menu item.  Now when you click on a node of the tree, the icon window is updated to display the contents of that folder.

Selecting folders

When you are using a dialog box and are asked to choose a folder, you can double click on the edit box to open a tree view.  Move through the tree as usual, and when you have found the right folder, press Enter or choose Open Folder from the popup menu.  To cancel the operation, close the window or press Escape.

See also:
Icon windows


Wastepaper Bin

When you drop files or folders into the bin icon, they are moved to hidden directories instead of being deleted.  If you change your mind, you can restore them to their original location.  Otherwise, you'll need to empty the bin to free up the space used by the files.

Double click on the icon to open the bin window.

How to restore files

After selecting the items, choose Restore from the popup menu to move each file or folder back to where it came from.  Alternatively, drag the items to an icon window or shortcut.  This moves them all to that location.

How to empty the bin

The popup menu has Delete and Empty commands, which deletes selected items and all trash, respectively.  If you choose Properties from the menu, you can configure the bin to clear trash automatically.


Taskbar

Each running process has a button on the bar and you click on a button to switch to that task.  If you right click instead, a popup menu lets you minimize, maximize or close the window.

The start button has a special popup menu that lets you setup the taskbar.  Choose Taskbar Properties from this menu to adjust the settings.

You can configure the taskbar to always stay on screen or hide when the cursor moves off it.  It will always pop up when the cursor reaches the bottom of the screen.

See also:

Start menu


Start menu

This nested menu is displayed when you press Start on the taskbar. Each menu item is equivalent to a program item in Program Manager.  Additionally, it can open new windows and dialogs, and programs that are launched from the Start menu will be shown by your chosen icon on the taskbar, even Windows programs.

To edit the start menu, right click on the Start button and choose Start Properties from the popup menu.


Shortcuts and aliases

Shortcuts and aliases are references -- they point to another object such as a disk drive, folder or file.  When you open or drop things into a reference, the effect is the same as if you had opened or dropped into the original object.

Shortcuts

These are icons on the desktop, and you create them by dragging an icon out of a window and releasing the mouse.  The shortcut is saved in Calmira's INI file when you quit.  To edit its properties, click on its caption and choose Properties from the menu.

Shortcuts are useful when used sparingly -- you would probably have shortcuts of your disk drives and a few important folders and utilities on your desktop.

Aliases

These are small files (with an extension ALS) containing an icon and some data that points to the original object. To create an alias, select an object, right click over it and choose Create Alias from the menu.  The alias is added to the window's contents.

Aliases are just like other files, and you can copy, move or delete them without affecting the original object.  To change their properties, right click and select the Edit Alias command.

You can use aliases to give the effect of a free floating program group: move aliases into the one folder, create a shortcut of the folder, and change its icon.  They are also useful for creating "virtual links" to other folders, to change the apparent structure of your directory tree.


File Management

Copying

1.  Ensure the destination is visible, as a window or an icon.

2.  Select which objects to copy.

3.  Drag them to the destination and release the mouse.

Moving

1.  Ensure the destination is visible, as a window or an icon.

2.  Select which objects to move.

3.  Drag them to the destination.

4.  Right click once.

5.  Release the mouse.

Deleting

1.  Select which objects to delete.

2.  Right click over one of the selected icons.

3.  Choose Delete from the popup menu.

Renaming

1.  Select an objects to rename.

2.  Right click over the icon.

3.  Choose Rename from the popup menu.

Creating a folder

1.  Open the parent folder as an icon window.

2.  Right click in the space between the icons.

3.  Select Create Folder from the menu.

Refreshing windows

When you have used another program to change files or folders, existing icon windows must be refreshed to show the correct contents.  Press F5 or click on the left label on the status bar to read the directory again.

See also:

Working with descriptions


Working with descriptions

In the absence of long filenames in Windows 3.x, Calmira allows you to use 4DOS compatible  descriptions to label your files and folders.  When you upgrade to Windows 95, you can turn the descriptions into proper long filenames.

Descriptions can either show up as popup hints (and an extra column in the list view), or be used as captions for the icons.  The File System Properties dialog lets you adjust the settings.

Adding and changing descriptions

After enabling the descriptions feature, open an icon window and select the files you want to describe.  Right click over one of them and choose the Describe command.  Calmira will prompt you for a description for each file.  Press Escape to stop adding descriptions.

To delete descriptions, simply describe the files with empty strings.

Running 4DOS sessions simultaneously

Calmira keeps a copy of the descriptions in memory for each icon window, but if you use a 4DOS box to manage files, it may modify the descriptions so that the Calmira's memory copy is out of date.  When you next use Calmira to copy files, the old descriptions are carried across.

To prevent this, select the option to maintain up to date descriptions.  This causes descriptions to be read from disk before each update, to refresh the copy in memory.

How descriptions are stored

When a directory contains a file or folder that has a description, a hidden file called descript.ion is created which stores the extra data.  When files are copied, moved or deleted, the description file is updated.

Warning: Calmira doesn't handle descriptions properly when you merge whole directory structures together  the description files are treated as normal files and will replace the description files in the target directories.


Keyboard commands

Most key combinations are shown in popup menus.  The following are available from icon windows, but are not shown in the menus:

Keys	Command	Description
F5	Refresh	Reads the contents of the folder again
Ctrl + F5	Cascade	Stacks icon windows from the top left
Shift + F5	Arrange icons	Moves icons to the bottom of the screen
Backspace	Open parent	Opens a window to the parent folder
/	Close all	Closes all icon windows
*	Close others	Keeps only the active icon window
+	Close lower	Closes windows showing a child folder
-	Close path	Closes windows showing a parent folder
\	Go to root	Opens the current drive's root directory
Shift+Ctrl+drive	Open drive	Opens the root of the specified drive
Any letter	Search	Jumps to next file starting with that letter
Ctrl+F	Find	Opens the Find dialog
Ctrl+E	Explorer	Displays the Explorer tree
Ctrl+C	Open folder	Prompts you for a folder to display
Ctrl+P	Print	Prompts you for a file to print
Ctrl+C	Copy path	Copies the icon window's path and filter to the clipboard.  Use this to paste a long path into open file dialogs etc.

Switching between windows

Press Ctrl + Tab to cycle through each window in Calmira.

Browsing folders in one or more windows

The Desktop properties dialog contains the setting Browse through folders in the same icon window.  If you hold down ALT when double clicking on a folder icon, the folder is opened using the opposite of the current setting.

See also:

Defining keyboard shortcuts


Defining keyboard shortcuts

This general keyboard-shortcut facility works from any window of Calmira, and lets you assign a Ctrl+Alt key combination to a window, menu item or desktop shortcut.  Fill the [Keyboard] section of the INI file with the desired mappings in the format caption=key.  For example,

[Keyboard]

System=F1

Drive (C:)=C

c:\windows=W

Notepad=N

When you press Ctrl+Alt together with another key, Calmira searches this list and obtains the caption.  It then searches all windows, shortcuts, and the start menu for a match (in that order), and activates the object if a matching caption is found.  If you specify a folder which is not shown in a window, then the folder is opened for you.

Finally, if nothing matches the text, the search extends to all windows on the screen, even those belonging to other applications.

In the above example, Ctrl+Alt+F1 will restore your system window.  Ctrl+Alt+C might activate a shortcut to drive C.  Ctrl+Alt+W will open the windows folder, and Ctrl+Alt+N could run Notepad if it's in the Start menu.


Multiple bin locations

You can specify which drives to store trash on, and which folders to use.  If you have more than one hard disk drive, this could speed things up because trash from each drive can be moved quickly and need not be copied to another disk.

In the [Bin locations] section, add mappings of drive=folder.  For example,

[Bin locations]

c=c:\windows\temp

d=d:\waste

f=e:\trash

This stores trash from drive C: in c:\windows\temp, etc..


Using custom icons

Supplying icons

Calmira accepts global icon settings in two ways.

The INI file [Icons] section holds a list of icon mappings in the form key=filename(index).  For example,

txt=c:\windows\progman.exe(17)

associates the string "txt" with icon 18 from Program Manager (the index starts from 0, and is optional).  So you can edit the INI file to specify your own icons.

Alternatively, if you copy icon files (ICO) into Calmira's home directory, entries like this are automatically created, the "key" being the filename without the extension.  So if you copy a file called TXT.ICO, the entry created would be txt=c:\calmira\txt.ico(0).  To search for icons in another directory, use the File System Properties dialog.

When a particular kind of icon is required, the list is searched and an icon extracted from the specified file.

Assigning icons to file types

Calmira uses registry information in WIN.INI to determine which programs to extract icons from to use for representing document files. To override these settings, simply use the above methods to supply your own icons.  The example given would set the icon used for text files, regardless of the program you use to view them.

This process can assign icons for files which normally have no specific icon.  The registry is not modified in any way -- files are just displayed differently.

Icons are only loaded when they are required (when you open an icon window containing the file types in question), but are not unloaded them until you quit the program.  Bear this in mind when deciding how many you should have.  Each icon uses around 800 bytes of memory once loaded.

Replacing built-in icons

You can also override the icons used for fixed objects.  Instead of specifying a file extension, use one of the special object names below.

Key	Used to display
_folder	Folders and minimized icon windows
_file	Ordinary files
_doc	Document files with no icon available
_tfile	Small file in list view
_tfolder	Small folder in list view
_tprog	Small program in list view
_system	Minimized system window
_explore	Minimized explorer window
_windows	Windows binary files with no icon
_msdos	MS-DOS programs
_multi	Multiple files in File Properties dialog
_finddlg	Minimized Find dialog
_rundlg	Minimized Run dialog
_hard	Hard drives
_floppy	Floppy drives
_cdrom	CD-ROM drives
_ramdisk	RAM disks
_network	Remote ot network drives
_emptbin	An empty wastepaper bin
_fullbin	A full wastepaper bin

Notes

The small icons (_tfolder, _tfile and _tprog) must occupy only the top left quadrant of the icon image, that is, a 16 x 16 square.


Environment variables

Shortcuts, aliases and start menu items can use MS-DOS environment variables in their settings.  The Target, Parameters, Command, Icon file and Working Folder fields (where applicable) can contain environment variable names (surrounded by %) like lines in MS-DOS batch files.  When you activate an item, the variable values are substituted for the names.

Special environment strings

%currentfolder% points to the directory showing in the active icon window (if none are active, the variable is empty).  This is particularly useful for the Working Folder field when you want to create or modify files in the current folder.  For instance, if you use it for a Notepad shortcut, Notepad will always start up in the directory you are viewing, so you can open and save/create files without having to hunt through the tree.

%droppedfiles% is only valid immediately after files have been dropped into a file shortcut or alias.  It contains the list of filenames, and you can place it in the Parameters field to insert the filenames between other parameters.  If %droppedfiles% is omitted, the files are just appended to the parameters list.

%calmira% points to the program's home directory.

%comspec% is defined automatically by MS-DOS, and gives the filename of the command interpreter (i.e. the MS-DOS shell), which is usually command.com.

%windir% is defined automatically by Windows and points to the Windows directory.

User defined variables

The [Environment] section of the INI file is added to Calmira's own environment after loading, so it has the same effect as the MS-DOS set command.  As with MS-DOS, don't add the % characters when making settings -- they are only used when variables are referred to.

Use this section to store your own identifiers, such as folder locations and device names.  When a folder or device changes, just edit the environment and all shortcuts, aliases and menu items will refer to the right place automatically.

Note: the icon index is not affected by the environment, so you should use something like %filename%(1) when re-mapping the icon file.


Bin Properties dialog

This controls the settings of the wastepaper bin.  You can access it by opening the bin window, and choosing Properties from the popup menu.  When the bin is hidden, the dialog can be opened from the system window.


Desktop Properties dialog

This dialog contains settings that are associated with window management as well as those relating to the desktop.  To open it, right click on the wallpaper and choose Properties from the popup menu.  If you've disabled the desktop popup menu, you can open this dialog from the system window.

Right click on minimize/maximize box to close

You can close any icon window by right clicking on the minimize/maximize buttons (as a substitute for Win95's new close button). Turn on this setting to extend the feature to cover windows belonging to any program.  You need to run the taskbar for this to work, because it relies on the taskbar's mouse controller.


File and Folder properties dialog

Open this dialog from icon windows by selecting some objects, and choosing Properties from the objects' popup menu.  You will receive different information depending on whether you selected a file, a folder or multiple items.

File attributes

If you select multiple items, some check boxes may be greyed, which indicates that items differ in this attribute.  Leave a check box greyed to prevent the particular attribute from being modified.

Note: under Windows 3.1, only version information compiled by a Microsoft resource compiler can be reliably detected.


File System properties dialog

This dialog controls the built-in file manager.  To open it, choose File System from an icon window's popup menu, or open it via the system window.

For details about file descriptions, see Working with descriptions.


Find Files dialog

This dialog lets you search for files on the whole or part of a drive.  You can open it from the start menu, desktop popup menu, system window or icon windows.

To look for multiple sets of files, separate each specification with a semi-colon.  When you press the Search button, the search takes place in the background and you can carry on with other tasks.  Files and folders are displayed in the listbox as soon as they are found.

Double click on an item to open it, or right click on the listbox to display commands that let you open an item's parent folder or delete it.  Ctrl and Shift can be used to select multiple items, and they can be dropped into other programs.


Run Program dialog

This dialog lets you start a Windows or MS-DOS program, or execute an MS-DOS command.  You can open it from the start menu, desktop menu, system window or icon windows.

If you check the DOS command check box, the text you type in is passed to your command interpreter so you can obtain directory listings etc..  Otherwise, the text is passed to Windows to execute.


Start Menu properties dialog

Open this dialog by right clicking on the Start button of the taskbar, and choose Start Properties.  This dialog is not modal, so you can switch windows and drop items into the tree.

Creating new items

There are three ways of doing this:

1.  Press the Add or Insert buttons on the toolbar.

2.  Drag and drop files and folders from icon windows straight into the tree.

3.  Press the Import Groups button to copy items from Program Manager.

Creating new sub-menus

A sub-menu starts off as a normal menu item.  When you use the Insert button or drag nodes onto it, it becomes a menu.  When the contents are deleted, it becomes an item again.

Copying and moving items and sub-menus

Simply drag a node to move it.  To drop a node into a closed sub-menu, hold down ALT before releasing the mouse button.  To copy a single item, hold down the CTRL key when dropping.

Built-in menu commands

Instead of specifying a program to run, the command line field of a menu item can open or activate a window in Calmira.  The recognised commands are in the drop-down list.  The $Folder command opens an icon window, and requires a directory name as parameter.  If wildcard characters * or ? are present in the parameter, they are used as the filter.  For example, $Folder c:\windows\*.exe displays all the executables, whereas $Folder c:\windows displays everything.

Using bitmap files in the start menu

To use a Window bitmap (bmp) file for a menu item instead of an icon, type in the full name of the bitmap file in the Icon from edit box. This bitmap should be 16 x 16 pixels, but can have any number of colours.

Adding menu separators

A dash "-" as the first character of a caption will turn the entry into a separator line.  Each item must have a different caption, so use something like -1, -2 ... for multiple separators.

See also:

Environment variables


System Properties dialog

This dialog contains global, screen display and network settings.

Advanced settings

The Advanced page contains an INI file editor that lets you modify Calmira's configuration file without using a separate text editor.  Double click on a section name to show the settings it contains.  The identifiers (on the left) are not case sensitive, but the values (on the right) are.  The order in which lines appear does not usually matter.

Many of the INI file settings can be adjusted through various dialog boxes, and these should be left alone.  You should also leave settings that are updated automatically, such as window positions.

Note: Some settings will not take effect until you restart the program.


Shortcut and Alias Properties dialog

To edit a shortcut, click once on its caption and choose Properties.  To edit an alias, right click on it and choose the Edit Alias command.

Parameters field

As well as typing in parameters, you can specify where in the command line to insert the names of files which are dropped into the shortcut or alias.  Place the string %droppedfiles% at the desired location, and when you drop any files, it will be replaced with filenames.

Use document folder setting

This controls how dropped files are passed to programs via the command line.

When the box is checked, only the filenames are passed, and the location of the first file is temporarily used as the working folder.  Since the length of the command line is limited, this feature allows more files to be dropped, but might not work with all programs.

When the box is unchecked, the full pathnames are passed.

See also:

Environment variables


Taskbar Properties dialog

Open this dialog by right clicking on the Start button and choosing Taskbar Properties.

Excluding programs from the bar

If certain programs are finding their way onto the taskbar that you would rather exclude, add the program's filename (without the path) to the exclusion list.  Optionally, leave a space after the name and enter a window classname, to exclude only a particular kind of window.

You can find class names by selecting Spy from the Start button's menu, and watching the button hints, which will now tell you the filename and classname of each task button.

Refresh interval setting

This determines how often the taskbar updates the button captions and removes any buttons for windows that have disappeared from the screen without being detected in the normal way.


System tray

The taskbar's clock can hold a few icons for commonly used utilities.  These programs are treated slightly differently from those launched by normal shortcuts:

They are not allocated a button on the taskbar, and when you minimize the program, it's icon is always hidden.  When you try to run the program from the system tray again, an existing instance is restored if possible, rather than always launching another instance.

Edit the [System tray] section to include a list of programs, which can be ordinary Windows programs.  The following example demonstrates the effect of adding a volume control and calculator:

[System Tray]

Count=2

S0=c:\sbpro\winappl\sbpmixer.exe

S1=c:\windows\calc.exe

This yields [image].


Custom drive names

Calmira does not distinguish between different types of floppy or removable drives.  You can override the default names given to disk drives by adding suitable descriptions to the [Drives] section of the INI file.

Assign a description to each drive letter that you want to describe manually, for example

[Drives]

A=3½" Floppy

B=5¼" Floppy

E=Syquest


Miscellaneous Settings

[Desktop]

; the grid size used by "Snap icons to grid" command

DeskGridX=16

DeskGridY=16

; number of columns in window attached to Explorer

FilePaneCols=4

[Display]

; the font in icon windows etc.

FontName=MS Sans Serif

FontSize=8

[Taskbar]

; the standard taskbar font

FontName=MS Sans Serif

; the pixel position of minimized icons above the bar

MinAppHeight=60

; enables/disables mouse hook for compatibility

UseMouseHook=1

; controls whether disabled child windows can be

; activated from taskbar (default = don't activate)

CheckDisabled=1

; delay before popup hints appear

HintTimer=800

; format for date and time display

24HourFormat=h:mm

12HourFormat=h:mm AM/PM

FullDateTime=dddd, mmmm d, yyyy

; text on start button

[Sounds]

; replace <None> with a WAV filename, including path

WindowOpen=<None>

WindowClose=<None>

WindowMinimize=<None>

WindowRestore=<None>

WindowMaximize=<None>

NotifyCompletion=<None>

BinDropFiles=<None>

BinEmpty=<None>

BinRestore=<None>

[Start menu]

FontName=MS Sans Serif

FontSize=10

[Start button]

FontName=Arial

FontSize=9

FontStyle=Bold

[Programs]

; this section controls the program items that appear in

; the system window.

c:\windows\progman.exe=Program Manager

c:\windows\winfil.exe=File Manager

[File system]

; 4DOS users can modify this to use a different filename

DescriptionFile=descript.ion

; controls the pixel width reserved for descriptions in list view (-1 for auto)

DescriptionWidth=-1