New Document Help
Name:New Document
Version:1.3
Last update:2019-11-27 14:12:49



The New Document package offers a variety of New Document options for creating new windows, including a preset list of template options created by other packages in AlphaTcl, as well as different new window handlers as described below. After the package has been activated (from the Features Preferences dialog), the File ↣ New menu item is replaced by a submenu of the same name.

The New Document Menu

The new File ↣ New menu includes all of the possible New Document options that have been registered by other AlphaTcl packages (such as creating a new e-mail message, or inserting a template for a new HTML or LaTeX document). You can select any of them to evaluate the associated script.
Click some of these hyperlinks for an example: Selecting the menu item File ↣ New ↣ Create A New presents a dialog that looks like this which includes the entire list of the preset options. Select File ↣ New ↣ New Text Window to only be prompted for a window name. When you create a new document/text window, your New Document Handler is used to complete the process, as described below.
If you simply want to open a new untitled window without being prompted any further for window names or other options, then select the menu item File ↣ New Document ↣ Untitled Window. You can assign a keyboard shortcut to this item, as well as to any other File ↣ New item by selecting File ↣ New Document ↣ New Document Shortcuts.

New Document Preferences

For new windows which aren't templates, this package has some different preferences to help determine how many additional options should be presented. These preferences are available by selecting the Prefs button in the File ↣ New ↣ Create A new dialog, or (after the package has been activated) by the File ↣ New ↣ New Document Prefs menu item. Click here to display the New Document Preferences panel.
The options include:
Untitled Docs Are Empty
Set this preference to always open untitled windows without any extra template information created by your New Document Handler.
New Document Handler
Initially set to Alpha, this preference determines which package should handle new open windows. Alpha will simply open a new window, without prompting you for any additional information.
The package Document Projects creates an additional handler that you can select. The Doc Projects handler will optionally add header info at the top of the window, or insert additional template information. (You have to activate the Document Projects feature to have access to this handler). Many of the Doc Projects headers are only useful after you have created your identity and defined some projects -- see the Document Projects Help window for more information.

Contextual Menu Module

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

Note For Developers

Any package can declare a new type of document to be added to the set of dialog panes simply by adding to the newDocTypes array, as in 
    array set newDocTypes [list "New LaTeX Doc" {TeX::newLaTeXDocument}]
Actually the New is no longer necessary, and will be stripped from the name of the item, so it is sufficient to just use 
    array set newDocTypes [list "LaTeX Doc" {TeX::newLaTeXDocument}]
The submenu File ↣ New offers all of these options, plus some extras that are defined by this package. If any of them require open windows, add an entry to the newDocTypesRequire array, as in 
    array set newDocTypesRequire [list "New HTML With Content" 1]
where the number indicates the number of required windows. If you don't want ellipses to be automatically added to the end of the menu item's name, add an entry to the newDocTypesDots array, as in 
    array set newDocTypesDots [list "Untitled Window" "0"]
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 New Document package also provides an interface with New Document Handlers such as the one found in the Document Projects package. Any use of new can be applied with [file::newDocument] instead, and if the user has selected the documentProjects handler for new documents, the info will first be passed to the handler before opening the new window. Default settings will not deviate from standard behavior beyond the initial dialog.

Known problems

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

License and Disclaimer

Copyright (c) 1997-2019, Vince Darley and Contributors.
Contributors: Craig Barton Upright.
All rights reserved.
The New 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 VINCE DARLEY 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.