Copyright ã 1993 Jeremy Slade.

You are free to use all or any parts of the Locus project
however you wish, just give credit where credit is due.
The author (Jeremy Slade) shall not be held responsible
for any damages that result out of use or misuse of any
part of this project.

Locus User's Manual
Version 1.0
JGS Mon May 27 09:37:29 MDT 1993

Overview

Introduction

	Locus is a yet another Dock extender (sort of).  The main philosophy behind Locus is to be a tool to give you immediate access to your files, applications, etc, and then to go away and not interfere when you are doing something else.  It is just another way of doing the same thing that several other applications do.  Each has its strong points and weaknesses, depending on how you will be using it, etc.

Disclaimer

	Locus is provided free of charge, without warranty of any kind.  You are free to use Locus without compensation to the author (Jeremy Slade).  There is no guarantee of any kind as to the suitability of this software to any purpose.  The user is solely responsible for all damages arising out of any use, misuse, or inability to use this software.
	This software is completely unsupported by the author.  You may do what you wish with it.  Send all comments, suggestions, etc, to: /dev/null.  I will be incom- municado for the next two years.  If it's terribly important, you can probably find a way to contact me.  Otherwise, wait until I get back (BTW - I will be looking for a job when I return :-) )

Basic Operation - Quick-Start Guide

	The following section contains basic information on how to begin using Locus right out of the box -- or more appropriately, the archive.   I am assuming you've figured out how to unarchive the Locus distribution package since you are reading this file...
	My first recommendation is that you put Locus on your Dock, as that it where it is most useful, or at least in one of the standard application paths searched by the Workspace: ~/Apps, /LocalApps, etc.  This is necessary because the file structure used by Locus is actually a file package (a directory), and Workspace must be able to find Locus in order for these 'files' to be usable.  Once this is done, launch Locus and away you go.

Locus' Default Directory

	By default, Locus looks for it's Folders in a directory in ~/Library called Locus.  When you first run Locus, it will check if this path exists and create if necessary.

The Default Folder -- Dock.locus

	Once the default path has been created, Locus will 'open' the default Folder, which is called Dock.locus.  Initially, this folder is empty, and before you can do anything with it you must create a group in which to add the items that you wish to have access to:

Creating a New Group

	To create a group, choose the "New Group" menu item in the Folders menu (Cmd-n).  A new group named "UNNAMED" will be created.  You will see the group added to the group selector in the Folder window, and then the Inspector panel will automatically be opened to inspect the new group.  From there you change the name of the group, along with many other options.

Adding Items to the Group

	Finally, you must add Items to your group.  Items can be applications, directories, text files, etc..  There are several methods for doing this.  You can choose the "Add..." menu item from the Items menu, or you can drag and drop them from another application (Workspace) onto any of the following: the Folder itself, the Activator, or the App Icon ( NOTE: dropping on the App Icon is not supported in this version ).  The Items will be added to the Group, and are now ready to use:

Launching the Items

	The main point of Locus is to give you fast access to those Items that you have added to your Folders.  There are several methods for launching/opening the Items at this point: double-clicking, "Launch" from the Items menu, Enter or Return.  This will cause the selected Items to be opened using the Workspace Manager.  There are several options for determining the specific behavior available through the Item inspector.

Using Locus

Folder

	The Folder is the basic organizational unit used by Locus.  Each Folder is stored as separate file, and shown in its own window when it is opened in Locus.  Folders consist of one or more Groups, which can be chosen using the Group selector pop-up list in the Folder window.  The current Group is shown in a scrollable browser that occupies the rest of the Folder window.
	Most actions operate on the key Folder and the current Group within that Folder.  Simply click in another Folder Window to make it the key Folder.  The window itself can be moved and resized, and it's size and position will be remembered the next time the Folder is opened.

Startup Folders

	By default, Locus will create (if necessary) and open a default Folder in ~/Library/Locus called Dock.locus when the program is first started.  You can change this behavior to have Locus automatically open any number of Folders (including none).  This is done through the "Startup Folders" option of the Preferences panel ( See Preferences below ).  If Locus is auto-launched from the Dock, Locus will automatically launch all items marked for auto-launching in each Folder as it is opened.

Groups

	A Folder contains one or more Groups, which allow you to organize similar Items together.  A group can contain any number of Items, which can be any type of file or directory.  Each group within the Folder can be given a unique name to describe it; these names appear in the Group selector in the Folder window.
	Each Group can also be assigned a command-key equivalent which can be used to quickly select that Group within the key Folder.  The key equivalent can be any alphanumeric character (the keys on the keyboard), but you should note that if you choose a key that is also used by a menu item, the group's key equivalent takes precedence over the menu item.  This only applies when the Folder the Group is in is the key Folder.
	Each Group can also be associated with a default path, such as ~/Apps.  This path is used as the root path for all relatively-specified items within the Group, and the OpenPanel used to add Items to the Group is automatically set to this path.  Items not contained in the default path are still accepted.

Display Mode and Display Options

	In this version, Locus will display the items in the group in one of two basic ways, each of which has certain specific options.
	The Large Browse mode shows the most information about the item, but it also takes up the most space.  In this mode, Locus will show the item's normal 48x48 icon, along with the the item's path in one of several formats.  If the item is an Application, it will show if the item is currently running, using the three dots below the lower left corner of the icon.  If the item is a directory, it will show the directory that will be the root of the new File Viewer created in Workspace (if any).  If the item is a regular file, it will show the name of the Application used to open the item, if it is something other than the default Application set in the Workspace.
	The Small Browse mode shows less information about the items, but allows more items to be seen at once.  In this mode, Locus displays the item's path, optionally with a miniaturized (24x24) version of the icon.
	The item's path can be shown in several different formats.  These are pretty self explanatory, so I will not discuss them here.  There are also several specific display options that apply to different modes.  You should be able to figure them all out with a little bit a playing.

Allowed File Types

	Locus allows you to filter the types of files that are generally allowed in a group.  The group maintains a list of allowed file types, which are them extensions such as "tiff", or "locus".  If you try to add an item whose extension is not in the list, it will be ignored.  These restrictions can be temporarily disabled by setting the "No restrictions" option.

Dynamic Items

	Constantly adding or removing items from a group when the actual files are added or removed from a directory can be a hassle, so Locus can dynamically search the directories and and them for you.  These 'dynamic' items aren't saved when the group is saved (unless you make a modification to it), and can be updated automatically on some interval and/or manually on command.
	The dynamic items to be searched for a specified using shell-style file matching expressions, such as "*.h" or "Chapter[1-7].rtf".  Locus will search the default path for all files matching these expressions and automatically add them to the group.  You can also specify files in a subdirectory relative to the default path, such as "Sounds/*.snd", or give the full path: "/NextApps/*".
	Locus automatically updates the dynamic items in all the groups when a folder is first opened.  You can have it automatically update periodically after that, or explicitly them by choosing the "Dynamic Update" menu item in the Group menu (Cmd-D).

Items

	Items specify Applications, directories, or files that you want Locus to remember so that you can quickly access them on demand, without having to search through the File Viewer or OpenPanel.  An Item is just the full path to the file, along with certain options to control how it is used by Locus.
	All items can be set to be AutoLaunched and/or GroupLaunched.  When Locus is auto-launched from the Dock at login, all items in the startup folders that are set for AutoLaunch are automatically opened.  This can be simulated at any time using the "AutoLaunch" menu item in the Folder menu, which will open all AutoLaunch items in the key folder.  Choosing the "Launch" menu item in the Group menu will automatically open all items in that group that are set for GroupLaunch.  This can be used to quickly open a given set of commonly used files or applications.
	Items also have different options depending on what kind of file they represent.  The different categories and the options for each are described below:

Application-type Items

	Application-type Items are the files that are executable, as well as files(directories) that have the extension of ".app"  The only option for this type of item is whether or not to hide the Application's App Icon when it is launched (if it even has one).

File-type Items

	File-type items are any type of file that is not executable and not a directory.  With file-type items, you can specify the application (name or full path) that will be used to open the file, if you don't want to use the default application from the Workspace.

Directory-type Items

	For directory-type items, you can specify whether or not to create a new File Viewer in Workspace Manager in which to display the directory.  If you don't want to create a new viewer, then the main File Viewer is moved to display the directory represented by the item.  If a new viewer is created, it will be rooted at the directory specified by the "Rooted at" option, or "/" if none is given.

Adding Items to Groups

	There are two different methods for adding new items to a group.  The "Add..." menu item in the Item menu will bring up an OpenPanel, set to the group's default path, that can be used to choose items.  This method is limited in that it does not allow you to choose directories.
	The other method is by dragging files from other applications, such as the Workspace, and dropping them onto Locus.  This can be done on the Folder window, the Activator, or the App Icon.  Dropping onto the Activator or App Icon adds the items to the key folder; dropping onto any folder window adds the items to that folder.  There must be a current group in the folder you are attempting to drag into.
	Items can also be cut, copied, and pasted between groups.  Simply select the items you wish to copy, and use cmd-c or cmd-x co place them on the pasteboard, and cmd-v to paste them into the new group.  The selected items can be removed from a group by cutting them out, by hitting the delete key, or using the "Delete" menu item in the Item menu (cmd-d).  Items can also be move to a new position within a group by control-clicking on it (only does one at a time) and dragging it to the new location.

Launching Items

	You can launch the selected items in any of several ways: the "Launch" menu item in the Item menu (cmd-l), by double-clicking on them, or by hitting Enter or Return.  If you 'launch' an application that is already running, that application will be activated.

Custom Icons for Items

	Locus allows you to supply your own custom icons to be used to display items of various types ( i.e. items with certain extensions ).  In the default Library path automatically created at startup, Locus also creates a directory called Icons.  In this directory, you can place tiff or eps files containing the images you wish to display in place of the standard icons obtained from workspace.  These images do not have to be the standard size (48x48, or 24x24 for small icons); they will be scaled to the proper size automatically.
	You specify which items use the custom icons by the name of the image file.  For example, if you had a special tiff file to be used by all items with an extension of "snd", it would be named "snd.large.tiff" for the standard (48x48) size.  An image specifically for the 24x24 size would be called "snd.small.tiff".  If you only supply a large image, it will be scaled for use in the small browse mode, but not vice versa.

The Activator

	One of Locus' key features as a Dock extender is the fact that it can totally disappear when not in you, but come back immediately when needed with minimal effort.  This is achieved through use of the Activator.  The Activator consists of narrow bars lining the edges of your screen, which when clicked on will instantly activate Locus (or deactivate it if already active).  This obviates the need to double-click on Locus' icon in order to activate it, and is much easier and faster.
	Through the Preferences panel, you can choose which bars of the Activator will be shown, and also the color of the bars.  You can also choose whether to have the Activator float above the other windows (at the same level as the Dock), or always be behind all windows.  The Activator can also be used as a dragging destination for adding new items to the current group.

Preferences

	The Preferences panel enables you to control Locus' general behavior.  The various options are divided into three sub-panels, which can be chosen via the pop-up list at the top of the Preferences panel.

General Options

	In this sub-panel, you can toggle various options that control how Locus will behave.  These options are:
	
· Hide on AutoLaunch: If Locus is Auto-launched from the Dock at login, it will remain hidden until specifically activated.
· Hide on Deactivate: If this options is on (default), then all Folder windows will be hidden when you switch to a different Application.
· Verify Actions: Locus will prompt you to verify certain actions such as deleting items or groups.
· AutoSave: Locus will automatically save your Folders when changes are made to them.
· Add through Activator: This option enables or disables the Activator as a destination for dragging in new items.
· Add through App Icon: This option enables or disables the App Icon as a destination for dragging in new items.

	This sub-panel also has controls for setting the Activator options, as discussed above.

Startup Folders

	This sub-panel allows you to choose which Folders are automatically opened when Locus is launched.  To a new Folder, click on the Add button, which will bring up an OpenPanel from which you can choose the Folders.  Clicking on the Remove button will remove the selected Folders from the startup list.

Default Viewer Frame

	This sub-panel controls the default size and location used when creating a new folder.  When you create a new folder, it is automatically sized to the size specified in this panel, but the placement of the window is determined by the folder that is currently the key folder.  If there is a key folder, then the new folder will be stacked on top of it.  If there isn't already a key folder, the new folder will be placed at the location specified in this panel.

Summary Of Menus

	This section gives a brief description of the action performed by each of the menu items in Locus.  Standard menu items such as Hide and Quit are not discussed.

Folder

	Open...	Open a Folder using an OpenPanel
	New	Create a new Folder
	Save	Save the key Folder
	Save As...	Save the key Folder under a new name
	Save All	Save all Folders that have been changed
	Revert	Restore key Folder to last saved state
	AutoLaunch	Simulate an auto-launch for the key Folder
	
Group

	New Group	Create a new Group within the key Folder
	Delete Group	Delete the current Group from the key Folder
	Launch Group	Launch all Items in the current Group that are mark for GroupLaunch
	Sort	Sort the Items in the current Group alphabetically ( not case sensitive )
	Clean up	Remove all Items in the current Group that aren't in the Allowed Types list.
	Dynamic Update	Update the Dynamic Items in the current Group
	
Item

	Add...	Add new Items to the current Group using an OpenPanel
	Launch	Launch the selected Items in the current Group
	Delete	Remove the selected Items from the current Group
	
Tools

	Inspector...	Brings up the Inspector Panel
	Hide on deactivate	Toggles the Hide on Deactivate preference setting.  This change will not be saved unless you select the Set button in the Preferences Panel.

Summary

	Locus has many other subtle features that I will not take the time to discuss.  They are easy to find with a little playing around, and full source code is included.  If you find something you don't like, fix it yourself or find somebody else to do it.  This is provided as an example, and I like to think that I did one or two things right in the program.  Hopefully someone will learn something from having the source code available, and many people will find that Locus is a worthwile tool to keep around.