Open Document Help
Name:Open Document
Version:1.5
Last update:2019-10-17 13:28:47



The Open Document package offers a variety of Open Document options for opening various types of files.
When it is activated (via the Features Preferences dialog), the File ↣ Open menu item is replaced by a submenu of the same name. It contains commands to open a file via the status bar prompt, and to quickly search through a hierarchy of files for a given file pattern.
This package serves four main purposes:
  1. It provides a method for users to open existing files, using any criteria or method provided by other packages.
  2. It provides a user interface to change the Current Working Directory.
  3. The user can create pre-defined matching criteria for repeated use.
  4. It provides an interface to the various Open File preferences, such as Open Packages and Show Invisible Files.

Introduction

Several different Alpha menus and features attempt to make it easier for you to quickly locate and open a file that you wish to edit. There are many different methods for doing so: by collecting a list of files in filesets, by remembering recent files or directories, by assigning keyboard shortcuts to open favorite files, etc. You aren't expected to learn and use all of these methods, as each user's style is somewhat different. One of Alpha's goals is to provide with a variety of tools from which you can choose to make your editing sessions easier.
Related packages include: This particular package collects several of these methods, and replaces the File ↣ Open command with a submenu of the same name. If you want to give this package a try, click here to temporarily turn on this feature. It will be turned off the next time that you restart Alpha. Click here to restore the previous File ↣ Open menu item.

The 'File Open' Menu

The new File ↣ Open menu includes all of the possible Open Document options that have been registered by other AlphaTcl packages (such as from a remote site or via a pre-defined fileset). You can select any of them to evaluate the associated script.
Click some of these hyperlinks for an example: Selecting the File ↣ Open ↣ Local File menu item presents a dialog that looks like this which uses the Open Document Preferences described below to present a list of editable files.

Open Via Status Prompt

The menu command File ↣ Open ↣ via Status Prompt allows you to type in the name of the file that you're looking for. The initial path is always the Current Working Directory which you are able to change at any time. See the Current Working Directory section below for more information. While you are typing the name of the file, you can ... Type ../ to move one level higher.
Tip: You can use the File ↣ Open ↣ Current Directory menu to change the Current Working Directory. If you enjoy entering commands in the status prompt, you can also press Escape-X and type pwd followed by Return to display the Current Working Directory in the status bar, or you can type cd <directory> to change the directory.
Tip: If the current path ends with a file separator, typing that key again will also trigger a list-pick completion dialog. So if the current directory is too low in your hierarchy, you can type ..// to get a list-pick with the contents one level up. The one thing you cannot do is press Delete to remove the text of the initial directory.

File Matching Queries

The middle section of the File ↣ Open menu includes options for searching any local path hierarchy to find a matching file. For example, if you want to open a .tex file in your Dissertation folder whose name includes draft-1-1, you can select File ↣ Open ↣ Matching File Query and be presented with a dialog that looks like this and fill in the appropriate values, as in 
    draft-1-1
    .tex
    /Documents/Dissertation
Alpha will then recursively search through the specified Search Path and locate any matching files. If only one file matches the criteria, then it is opened automatically. If there are several options, they will be presented in a list-pick dialog, and you can choose one (or more) of the files that you want to open. The values that you enter will be saved and used as the next defaults when this menu item is called in the future, and saved between editing sessions. If you don't know the exact name of the folder to search, you can press the Browse Path button to browse a file-system Find Folder dialog, or select an option from the Current Working Directory list.
The File ↣ Open ↣ Fileset Query is very similar, but in this case you simply select the name of a pre-defined fileset to specify which files will be queried. For more information about creating filesets, see the Filesets Help file.
Tip: the File name pattern doesn't have to include the full name of the file you're looking for, or even the proper start of its name. For example, the pattern notes in your Dissertation folder could match all of 
    /Documents/Dissertation/write-up/chapter1/chapter1-notes.txt
    /Documents/Dissertation/write-up/chapter4/chapter4-notes.txt
    /Documents/Dissertation/misc/notesToSort.txt
    /Documents/Dissertation/misc/oldNotes.txt
Case sensitivity for these patterns is dependent upon your OS; in the MacOS the file Readme is the same as readme and README.
You can also create some Pre-Set File Matching Queries and assign them unique keyboard shortcuts. When these items are selected, a dialog will appear asking you for a file pattern to search for. All pre-set queries are saved between editing sessions, and you can edit or delete them by selecting File ↣ Open ↣ Pre-Set Queries menu commands: Pre-Set Queries.
Here's an example, one that AlphaTcl developers might find useful: 
    AlphaTcl
    /Applications/Alpha/
    .tcl
    Command-F1
Tip: If you have several pre-set Matching File Queries set up, you might find it cumbersome to assign (and remember) a unique keyboard shortcut for each one. The File ↣ Open ↣ Open With Pre-Set Query menu item will present all of them in a list-pick dialog for you to choose from, and you could just assign one shortcut to this menu command.
The File ↣ Open ↣ List Local Files has a similar dialog but will present all results in a new window.
This dialog allows you to specify that the search string is the complete name of the file you're looking for, or the start, middle, or end.
You'll notice that in both of these dialogs there is a text field named Patterns to ignore -- this should contain a list of any strings that you do not want included in the results. These must follow the syntax found in the File Patterns section of the Alpha Manual. This field should contain a list of items, each separated by a space. These patterns will apply to the full file path, including parent directories.
One such pattern might be *~ to ignore backup files created by Alpha. These patterns are _not_ case sensitive, so *bak will ignore a file named text.BAK .

Current Working Directory

Alpha maintains a Current Working Directory that can be used as a default location for locating files. This is the path returned by the Tcl command [pwd] , and is set by the command [cd] . Using the menu command File ↣ Open ↣ Current Directory ↣ Set Default Directory you set the initial working directory to be chosen whenever Alpha is launched.
The File ↣ Open ↣ Current Directory ↣ Set Working Directory command opens a dialog to select and set the working directory to any existing local folder. You can also use the File ↣ Open ↣ Current Directory menu to change the current working directory to any recent folder you have used. The list of saved working directories is used in the pop-up menus in several Open Document dialogs, allowing you to quickly choose from your most commonly used file hierarchies.
Once the Current Working Directory has been set, select the menu command File ↣ Open ↣ via Status Prompt to open a status bar prompt into which you can type the path of a file relative to this directory.

Open Document Preferences

There are several global preferences that affect how items are presented in the standard File ↣ Open dialog, such as invisible files, package contents, etc. These preferences are specific to the platform that you are using, and the Alpha ↣ Preferences ↣ Global Preferences ↣ Files menu item allows you to change them. Click here to display the Files Preferences panel.
The File ↣ Open ↣ Open Document Prefs menu lists the flag preferences as toggleable menu items, allowing you to change them on the fly as your needs change.
The File ↣ Open ↣ Open Document Shortcuts menu item allows to add or change any of the default shortcuts associated with these menu items.

Contextual Menu Module

A contextual menu module called Open Document is also available which provides a submenu with all Open Document options. Click here to display the Contextual Menu Preferences panel.
It is not necessary to formally turn on this package in order to have access to this CM module.

Note For Developers

Any package can declare a new type of open-file method to be added to the menu simply by adding to the openDocTypes array, as in 
    array set openDocTypes [list "Open Via Fileset" {file::openViaFileset}]
Modes can include such a statement in their [alpha::mode] initialization argument if they want such an option to be available even if the mode has not yet been loaded.
The submenu File ↣ Open offers all of these options, plus some extras that are defined by this package.

Known problems

Please report any problem or bug you encounter to Alpha's Bug Tracker.

License and Disclaimer

Copyright (c) 2004-2019, Craig Barton Upright and Contributors.
Contributors: Joachim Kock.
All rights reserved.
The Open Document package is free software and distributed under the terms of the new BSD license:
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL CRAIG BARTON UPRIGHT OR THE CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.