[TxMt] Commands

Juan juanfc at lcc.uma.es
Wed Feb 7 13:53:56 UTC 2007


These are the commands you can use to communicate with the editor  
from the scripts you can write.  With these commands you can, fron  
any script, for exmple, select any part of the document (making it  
easy to write a command for showing the balancing in html..), look  
from the insertion point forward, backward, the next char, word, etc,  
etc.....

TM needs all these to be able of solve many problems that are  
impossible with the TM scheme of calling external scripts.

¡TM needs a Ruby interpreter inside it!




Alpha Commands

                                         help version: 8.1a8
                                              created: 06/17/1994  
{01:48:53 PM}
                                          last update: 12/11/2006  
{05:32:43 PM}


In this list of routines, text between '<' and '>' is a placeholder  
for a
required parameter, text between '[' and ']' is a placeholder for an
optional parameter, and the '|' signifies a choice of two or more
alternatives.  A '+' signifies that the previous symbol can be  
present one
or more times, while a '*" means zero or more times.  Some commands  
have no
parameters.

Where '-w <win>' is given as an optional window name, <win> can be  
any item
from the lists given by '[winNames -f]', '[winNames]',  
'[win::CreationOrder]',
'[win::StackOrder]', or it can be the current window  
'[win::Current]' (in
fact that is the default).  To translate from a file path to possible
window names, use the command [file::hasOpenWindows $path].  Window  
names
are case-sensitive.  A window name may contain a trailing ' <n>'  
indicator
to show it is a duplicate, and this cannot be omitted when referring  
to the
window.

The following are Alpha-specific tcl routines, defined in the core of  
the
binary.  (In addition, of course, all the standard "Tcl 8.4 Commands"  
are
available.)  In Alpha8/X, most of these commands are implemented in C,
while in Alphatk they are implemented entirely in Tcl/Tk (which are
themselves implemented in C, and have seen some Alphatk-specific
improvements).

In some cases these 'core' commands are now defined in AlphaTcl or  
Tcl, see
the referenced source files for commands coloured magenta, or try to
Command-Double-Click on their names for more information.

	--------------------------------------------------------------------

= Table Of Contents

"# Basic insertion position queries"
"# Basic insertion position movement"
"# Basic text manipulation"
"# Selection manipulation and creation"
"# Pin manipulation and creation"
"# Clipboard/scrap handling"
"# Various textual manipulations"
"# View/insertion interaction"
"# Dialogs for querying the user"
"# Search in a window"
"# Using search dialog-equivalents from Tcl"
"# Basic window creation and file-interaction"
"# Window manager"
"# Menu creation/manipulation"
"# Inter-application communication"
"# Keyboard bindings and codes"
"# Status window"
"# Filesystem"
"# Debugging"
"# Colours"
"# Keyboard macros"
"# Time related"
"# Marks"
"# Remaining commands"
"# Uncommon/unused commands"
"# Obsolete (and possibly buggy)"

	--------------------------------------------------------------------

= Basic insertion position queries

In Alpha8/X, some of the commands in the 'pos' namespace are actually  
defined
in the file "coreFixes.tcl" using global namespace building block  
commands.

• getPos [-w <win>] - return the current insertion point
• pos::lineStart [-w <win>] <pos> - return the position of the start  
of the
     line 'pos' is on.
• matchIt [-w <win>] <brace char> <pos> [<num>] - Return pos of  
matching brace.
     Recognizes parenthesis, square brackets, and curly braces.   
Optional
     third argument specifies how many characters to search.  The  
brace char
     passed to this command should be the one whose partner you wish  
to find
     (not the one you want to search for).  When searching backwards  
(i.e.
     when trying to match a right brace), 'pos' should be the last  
position
     which could be a successful match, and not the position of the  
right
     brace itself (i.e. it will usually be the position just before  
the right
     brace itself).  For example if you have the text "abc ()" so  
that ')' is
     at position 5, then 'matchIt ) 5' will fail to match, but  
'matchIt ) 4'
     will correctly return '4'.
• minPos [-w <win>] - returns the first position in the current window.
     This will normally be '0' in Alpha 8/X, but for compatibility with
     Alphatk (in which it is 1.0) should not be so assumed.
• maxPos [-w <win>] - returns the position of the last character in  
the front
     window.
• pos::nextLineStart [-w <win>] <pos> - return the position of the  
start of the
     next line after position 'pos'.
• pos::diff [-w <win>] <pos1> <pos2> returns the number of characters  
between the two
     positions in the window.  This will be negative if pos1 is after  
pos2.
• pos::math [-w <win>] <pos> ?+/- offset? ...  returns that position  
which is
     given by moving the given number of characters backwards or
     forwards in the current window.  Any number of offset arguments
     may be given, with or without spaces separating the arguments.
     For future compatibility pos::math should be used in preference
     to numerical addition: positions cannot be assumed to be simple
     integers.
• pos::compare [-w <win>] <pos1> <comparison> <pos2> returns 1 or 0  
depending
     on whether the given comparison is true or not.  Valid
     comparisons include ==, !=, <, >, <=, >= etc.  For future
     compatibility, pos::compare should be used in preference to a
     direct, numerical comparison.
• pos::toRowCol [-w <win>] <pos> - converts from absolute position to  
row, col.
• pos::toRowChar [-w <win>] <pos> - converts from absolute position  
to row, char.
• pos::fromRowCol [-w <win>] <row> <col> - converts to absolute  
position.
     Accepts optional -w parameter that allows window to be specified.
• pos::fromRowChar [-w <win>] <row> <char> - converts to absolute  
position.
     Accepts optional -w parameter that allows window to be specified.

	--------------------------------------------------------------------

= Basic insertion position movement

• backwardChar [-w <win>] - moves insertion one char back
• backwardWord [-w <win>] - moves insertion one word back
• backwardWordSelect [-w <win>] - extend selection one word back
• beginningOfBuffer [-w <win>] - move insertion to the beginning of  
the buffer
• beginningOfLine [-w <win>] - move insertion to the beginning of the  
line
• endOfBuffer [-w <win>] - move insertion to the end of the buffer
• endOfLine [-w <win>] - move insertion to the end of the line
• forwardChar [-w <win>] - move insertion one character forward
• forwardWord [-w <win>] - move insertion one word forward
• forwardWordSelect [-w <win>] - extend selection one word forward.
• goto [-w <win>] <pos> - go to the position 'pos' in the current  
window.
• gotoLine - prompt for a line in the current window and jump to it
     (used by clicking on line/row indicator in the status bar window).
• gotoMark [-w <win>] mark - go to named mark, use 'mark' in macros.
• gotoTMark [-w <win>] <name> - go to the temporary mark 'name'.
• matchBrace [-w <win>] - moves the insertion point to the character  
that
     matches the character after the current insertion point
• nextLine [-w <win>] - move insertion point to next line
• nextSentence - go to next sentence ("textFill.tcl").
• previousLine [-w <win>] - move insertion point to the previous line
• prevSentence - go to previous sentence ("textFill.tcl").

	--------------------------------------------------------------------

= Basic text manipulation

• deleteText [-w <win>] <pos1> <pos2> - remove text between 'pos1'  
and 'pos2'
• getText [-w <win>] <pos1> <pos2> - return the text between 'pos1'  
and 'pos2'.
     '-w' can be used to specify a window.
• insertText [-w <win name>] <text>* - Insert 'text' at the current  
insertion
     point. Mark is unchanged.
• lookAt [-w <name>] <pos> [<num>] - return the num characters at the
     'pos'th position of the current file, or the file named by  
<name> if
     the '-w' option is specified. The value for num must be an integer
     between 1 and 10 (default value is 1).
• replaceText [-w <win>] <pos1> <pos2> [text]+ - replaces the text  
between 'pos1'
     and 'pos2' with 'text', where 'text' can be any number of  
arguments.
     The insertion position and selection are unaffected by this  
operation,
     but 'the mark' is set to pos1.

	--------------------------------------------------------------------

= Selection manipulation and creation

• balance [-w <win>] - selects smallest set of parens, braces, or  
brackets that
     encloses the current cursor position, i.e. (), {}, and [], but  
not <>.
     If there is initially a selection, [balance] operates on the  
position
     that starts the selection.  Starting from the initial position it
     searches backward until it finds one of the enclosers: (, {, or  
[.  It
     ignores any of these characters which is preceded by a  
backslash.  When
     (if) it finds one then it looks in the other direction for the  
matching
     character, again ignoring escaped characters.  An error is  
thrown if any
     of this fails, and the cursor is returned to the initial position.
• backwardCharSelect [-w <win>] - extends selection one char back
• beginningBufferSelect [-w <win>] - extend selection to the  
beginning of the
     buffer
• beginningLineSelect [-w <win>] - extend selection to the beginning  
of the line
• deleteSelection [-w <win>] - delete current position, don't save
• endBufferSelect [-w <win>] - extend selection to the end of the buffer
• endLineSelect [-w <win>] - extend selection to the end of line
• forwardCharSelect [-w <win>] - extend selection one character forward
• getSelect [-w <win>] - return the currently selected text, if any.
• nextLineSelect [-w <win>] - extend selection to the next line
• prevLineSelect [-w <win>] - extend selection to the previous line
• selectText [-w <win>] <pos1> <pos2> - (formerly [select].)  Selects  
the text
     between 'pos1' and 'pos2'.
• selEnd [-w <win>] - returns the end of the hilited selection, or  
the current
     insertion point if no text is selected.

	--------------------------------------------------------------------

= Pin manipulation and creation

• exchangePointAndPin [-w <win>] - exchange the current 'pin' w/ the  
current
     insertion point
• getPin [-w <win>] - return the current pin.
• hiliteToPin [-w <win>] - This is the 'Hilite' from the 'Edit' menu. If
     there is a currently hilited selection, the selection is unhilited,
     leaving the pin and the insertion point around the old  
selection. If
     there is not a selection, the region between the insertion point  
and
     the pin is selected.
• rectangularHiliteToPin [-w <win>] - creates a rectangular selection  
between
     the pin and the insertion point.
• setPin [-w <win>] - set the pin position to the insertion point

	--------------------------------------------------------------------

= Clipboard/scrap handling

All of [copy] [cut] and [paste] and defined in AlphaTcl.

• alpha::copyRegion [-w <win>] - copy region
• alpha::cutRegion [-w <win>] - deletes and saves region
• alpha::pasteRegion [-w <win>] - insert the last chunk of text  
created by
     [alpha::cutRegion] or [alpha::copyRegion]
• clear [-w <win>] - clear selected text.  ("textManip.tcl")
• getScrap - returns system TEXT scrap.
• putScrap [<string>]+ - Concatenate strings together into the system
     scrap.  The scrap can be appended to through calls of the form  
'putScrap
     [getScrap] " another word"'.

	--------------------------------------------------------------------

= Various textual manipulations
Former core commands which are implemented in AlphaTcl are in  
"textManip.tcl"
unless stated otherwise.

• backSpace [-w <win>] - delete selection, or a single char if no  
selection.
• backwardDeleteWord [-w <win>] - deletes previous word
• capitalizeRegion [-w <win>] - capitalize first word in selected region
• capitalizeWord [-w <win>] - capitalize the character at the cursor  
location,
     and downcase the remaining text of the word to the right of the  
cursor,
     leaving the cursor at the end of the word.
• deleteChar [-w <win>] - delete char AFTER cursor
• deleteWord [-w <win>] - delete word after cursor
• downcaseRegion [-w <win>] - changes all letters to lowercase in  
current
     region.  Original region remains selected.
• downcaseWord [-w <win>] - changes all letters to lowercase in  
current word
     from the cursor position to the end of the word, leaving the  
cursor at
     the end of the word.
• fold [-w <win> (info|hide|show) ?args?] - queries or hides or shows  
blocks
     of text in the given window.  This command is only available in  
Alphatk.
• killLine [-w <win>] - kill text from insertion point to the end of the
     line.  If the line has no text, delete the line and move  
succeeding lines
     up one.
• oneSpace [-w <win>] - converts whitespace surrounding insertion into a
     single space.
• openLine [-w <win>] - insert a new line following the current one  
and move
     the insertion point to it
• redo [-w <win>] - redo the next action that has been undone but not  
redone
• spacesToTabs [-w <win>] ?from to? - convert spaces in selection to  
tabs.
• tab [-w <win>] - insert a tab
• tabsToSpaces [-w <win>] ?from to? - convert tabs in selection to  
spaces.
• undo [-w <win>] - undo the last action that has not been undone
• upcaseRegion [-w <win>] - convert all letters to uppercase in the  
current
     region.  Original region remains selected.
• upcaseWord [-w <win>] - convert all letters to uppercase in the  
current word
	from the cursor position to the end of the word, leaving the cursor  
at the
     end of the word.
• wrapText [-w <win>] <pos0> <pos1> - wrap each line found in the region
     between the two positions.  (See "textFill.tcl")
• yank [-w <win>] - insert the last piece of deleted text of less  
than 1k.
     Consecutive deletes are concatenated together.
• zapNonPrintables [-w <win>] - removes chars < ascii 32, except for  
LF's
     and CR's.

	--------------------------------------------------------------------

= View/insertion interaction

• alpha::blink [-w <win>] <pos> - blink cursor at 'pos'
• centerRedraw [-w <win>] - redraw window with current line in the  
middle.
• display [-w <win>] <pos> - move pos's line to top of screen.
• insertToTop [-w <win>] - make the line that the insertion point is  
on the
     first line shown
• moveInsertionHere [-w <win>] [-last] - move the insertion point to the
     first (or last) line displayed
• pageBack [-w <win>] - display prev screenful, move the insertion  
point if
     'moveInsertion' enabled
• pageForward [-w <win>] - display next screenful, move the insertion  
point if
     'moveInsertion' enabled
• scrollDownLine [-w <win>] - same action as that which occurs when  
the down
     arrow in the vertical scrollbar is selected
• scrollLeftCol [-w <win>] - same action as that which occurs when  
the left
     arrow in the horizontal scrollbar is selected
• scrollRightCol [-w <win>] - same action as that which occurs when  
the right
     arrow in the horizontal scrollbar is selected
• scrollUpLine [-w <win>] - same action as that which occurs when the  
up arrow
     in the vertical scrollbar is selected

	--------------------------------------------------------------------

= Dialogs for querying the user

• alert [-t stop|caution|note|plain] [-k okText] [-c cancelText] [-o  
otherText]
             [-h] [-K ok|cancel|other|help] [-C ok|cancel|other|help| 
none]
             <error_string> [explanation_string]
     This command will display 'error_string' in a standard alert box.
     If present, 'explanation_string' will be displayed in the small
     System font.  The dialog format will be determined by the flags:
     The '-t' flag specifies the icon that will be displayed with the
     dialog.  The '-h' flag specifies that the Help button should be
     displayed.  The '-k' flag specifies the text of the button in the
     OK position (default value is "OK").  '-c' flag specifies the text
     of the button in the Cancel position (default value is "Cancel").
     '-o' flag specifies the text of the button in the leftmost
     position (default value is "Don't Save").  The '-K' flag specifies
     which button acts as the default button.  The '-C' flag specifies
     which button acts as the Cancel button.  If 'cancelText' or
     'otherText' is an empty string, the corresponding button will be
     omitted.  There must be a button in the OK position and there must
     be a default button (setting the default button to 'other' and an
     empty otherText will remove the default ring, but return or enter
     will still select the OK button).  The command will return the
     name of the button that was pressed.
• alertnote <args> - display a message in a standard OS alert box.   
If more
     than one argument is given, the first is displayed in boldface,  
and the
     remaining arguments are joined by " " and displayed in a smaller  
font
     below the first.  Otherwise the entire message is in a smaller  
font.
     The only button in the alert box is "OK", and the return value  
is the
     empty string.
• askyesno [-y <yesButton>] [-n <noButton>] [-c] [--] <prompt> - display
     'prompt' in an OS alert box with the push buttons Yes and No.  The
     command will return the string "yes" or "no".  The '-c' flag  
specifies
     that a cancel button be used as well (with return value "cancel").
     Optional arguments '-y name -n name' may be specified, which  
change the
     names of the yes/no buttons (but the return strings are unchanged).
     "--" indicates the end of switches.  Note that Tcl's [if] will  
treat both
     "yes" and "true" as "1", while "no" and "false" are interpreted  
as "0".
• buttonAlert <prompt> [<button>…] - create a dialog w/ the specified  
buttons,
     returning the one selected.
• colorTriple [<prompt>] [<red> <green> <blue>] - prompts the user to  
choose
     color. If specified, the input RGB value is used as the initial  
color on
     the colorpicker.
• dialog [<-w width>|<-h height>|<-b title l t r b>|<-c title val l t  
r b>|
             <-t text l t r b>|<-e text l t r b>|<-r text val l t r b>|
             ...

     Create and display a dialog.  '-w' and '-h' allow width and  
height of
     dialog window to be set.  '-b', '-c', '-r', '-t', '-e' and '-p'  
allow
     buttons, checkboxes, radio buttons, static text, and editable  
text to be
     created, respectively.  All control types require specification  
of a
     title or text, together with left, top, right, and bottom  
coordinates.
     Checkboxes and radioboxes have an additional parameter, the default
     value.  At least one button must be specified.  The return value  
is a
     list containing resulting values for all buttons, radioboxes,  
checkboxes,
     and editable textboxes (static text is ignored).  Buttons have  
value '1'
     if chosen, '0' otherwise.  The dialog box exits at the first button
     press.  The arguments listed above are the ones most commonly  
used, but
     section 2.1 of the "Dialogs Help" .pdf file has information  
about the most
     current set available, as well as the optional "-tag" "-action"  
etc.
     arguments that allow for scripts to be called when a control is  
selected.

     The proc: dialog::make and the proc: dialog::make_paged make it  
much
     easier to create dialogs, avoiding the need to wrestle with the  
core
     'dialog' command directly, as described in "Dialogs Help".

• findFile [<path>] - open a file in a new window. An optional path  
parameter
     specifies a default directory or file.
• getControlInfo <id> <attribute> - returns the attribute value of  
the dialog
     control associated with <id>, where <id> has been returned by  
Alpha(tk)'s
     core.  Valid values for 'attribute' are 'value', 'font', 'state'
     'contents' or 'help'.
     (Available in Alphatk and AlphaX >= 8.1a1)
• getControlValue <id> - returns the value of the dialog control  
associated
     with <id>, where <id> has been returned by Alpha(tk)'s core.
     (Available in Alphatk and AlphaX >= 8.1a1)
• get_directory ?-p <prompt>? ?-openPackages <num>? \
       ?-showInvisibleFiles <num>? [<default>]
     display a GetDirectory navigation dialog and request the user to  
select
     a folder. The command will return the selected folder's full  
path name,
     or an error if the Cancel button was selected. An optional path
     parameter specifies a default directory. The -p option specifies a
     prompt to display in the dialog. The other parameters have the same
     meaning as with the getfile command.
• getfile ?-types <typeslist>? ?-openPackages <num>? \
        ?-showInvisibleFiles <num>? [<prompt>] [<path>]
     display a GetFile navigation dialog and return the full path  
name of
     the selected file, or an error if Cancel button was selected. An
     optional path parameter specifies a default directory or file. On
     AlphaX, the -openPackages option specifies whether bundled  
applications
     should be seen as a folder (to make their contents accessible)  
or not
     and the -showInvisibleFiles option specifies whether invisible  
files
     should be listed in the dialog.
• listpick [options…] <list> - Display a dialog with the list  
displayed in a
     List Manager list.  If the user presses the Cancel button, an  
error is
     returned.  If the user selects the OK button, or double clicks  
an item in
     the list, that item will be returned.  Valid options include

       -w <width>    - the width of the dialog.
       -h <height>   - the height of the dialog.
       -p <prompt>   - the prompt text at the top of the dialog.
       -l            - allow multiple items to be selected, return a  
list.
       -L <def list> - a list of default item(s) to be initially  
selected.
                       if accompanied by -l, all items in the -L list  
will be
                       specified, otherwise only the first item is  
selected.
       -indices      - return a list of the <list> indices chosen
       --            - next arg is the list.

• prompt <prompt> <default> [<name> <menu item>*] - prompt dialog to
     the user with a prompt string and a default value.  The prompt  
dialog
     can optionally include a popup menu specified by 'name' and the
     succeeding strings.  Selection of the popup menu items inserts  
the item
     text into the editable dialog item.  'Prompt' returns the value  
of the
     editable item.  If the 'Cancel' button is selected, the tcl  
returns an
     error and your script will be stopped unless you execute the  
command
     from 'catch'.
• putfile <prompt> <original> - display an SFPutFile() and return the  
full
     path name of the selected file, or an empty string if CANCEL  
button was
     selected. Original is the default name displayed for the user.
• setFontsTabs ?-w win? ?-font name? ?-fontsize size? ?-tabsize tab?  
- if
     none of the font/fontsize/tabsize attributes are given, then  
bring up a
     font and tab dialog for the specified window (or the current  
window if
     -w was not given).  Otherwise set the appropriate attribute of the
     appropriate window to the values given.
• setControlInfo <id> <attribute> <value> - set the attribute value  
of the
     dialog control associated with <id>, where <id> has been  
returned by
     Alpha(tk)'s core.  Valid values for 'attribute' are 'value',  
'font',
     'state' 'contents' or 'help'.  If the attribute is 'value' and  
if the
     value given will not fit in the available space, this command  
throws an
     error, the value of which is the available width, in pixels.
     (Available in Alphatk and AlphaX >= 8.1a1)
• setControlValue <id> <value> - set the value of the dialog control
     associated with <id>, where <id> has been returned by Alpha 
(tk)'s core.
     If the value will not fit in the available space, this command  
throws
     an error, the value of which is the available width, in pixels.
     (Available in Alphatk and AlphaX >= 8.1a1)
• setRGB <col> red green blue - define one of Alpha(tk)'s colours.

	--------------------------------------------------------------------

= Search in a window

• search [-w <win>] [options…] <pattern> <pos> - search for 'pattern'  
from
     position 'pos'.  Valid options include

       -f <num>      - go forward?
       -r <num>      - regular expression?
       -i <num>      - ignore case?
       -m <num>      - match words?
       -all          - return all matches (else just first match)
       -wrap         - if the search reaches the end of the window wrap
                       around to the beginning and continue searching
                       (similarly when searching backwards, wrap from
                       beginning to end).
       -n            - failed search still returns TCL_OK, but null  
string.
       -l <limit>    - limit on how search goes.
       -s            - save previous search string and search flags  
(obsolete).
       --            - next arg is the pattern.

     If the search succeeds, a list of two positions will be returned,
     unless '-all' was given, when the list will contain 2 positions for
     each correct match (note: it is a flat list).  The first is the
     starting position of the match, the second is one past the last
     character.  If no '-n', an error is thrown if no match was found.
     For the regular expression syntax which may be used, see
     "Regular Expressions".

     To search from the beginning of the buffer, use 'search -s -f 1 ...
     [minPos]' and to search backwards from the end, use 'search -s -f 0
     ...  [maxPos]'.  See also 'performSearch' which can be used for
     simulated interactive searching (where the search result is
     selected, for example).

     'pos' is the first position at which a search may match (whether
     searching forwards or backwards). 'limit', if given, is the first
     position at which a search will not match.

     Backwards searches: The interpretation of 'pos' is such that
     backwards searches may match immediately at 'pos', in which case  
the
     entire matched range will be outside the apparent [limit,pos]  
search
     region.  This is a somewhat controversial behaviour which _may_ be
     adjusted in the future if steps can be taken to ensure none of the
     code in AlphaTcl breaks.

     Also, for various reasons, backwards searches (particularly with
     regexps) are slower than forward searches.

	--------------------------------------------------------------------

= Using search dialog-equivalents from Tcl

Implemented entirely in AlphaTcl, see the source files "supersearch.tcl"
and "interactiveSearch.tcl".

• enterReplaceString - use current selection, if any, for future  
replacements
     (in search dialog).
• enterSearchString - use current selection, if any, for future  
searches.
• find - bring up the find dialog
• findAgain - repeat search forward
• findAgainBackward - repeat search backward
• findInNextFile - search next file.
• performSearch  [options…] <pattern> <pos> - as for 'search' but  
also selects
     the range of characters which are found, and ensures Alpha's  
internal
     state is consistent for following replace/replaceAll/...  commands.
• replace - replace the current selection
• replaceAll - replace all further occurrences in the current file or  
set
     of files.
• replace&FindAgain - replace the current selection and find next  
occurrence.
• replaceString [<str>] - specifies replacement string. Returns current
     replacement string if no arg.
• searchString [<str>] - allows search string to be specified. Returns
     current searchstring if no arg.
• quickFind - incremental search: searches w/o a dialog, searches as  
you type
     the search pattern.  Does not do regular expression searches.   
'matchWords'
     automatically set to false.
• quickFindRegexp - incremental regexp search
• reverseQuickFind - reverse incremental search, see 'quickFind'.

	--------------------------------------------------------------------

= Basic window creation and file-interaction

• edit [-r] [-c] [-w] [-mode <val>] [-encoding <val>] [-tabsize <val>]
     [-g <l> <t> <w> <h>] [--] <name> - Open a file in new window.  '-c'
     means don't prompt for duplicate win if file already open (just
     bring to already open window to the front).  '-r' means open the
     file read-only.  The '-g' option allows left and top coords to be
     specified, plus width, and height.  All or none.  '-w' allows  
you to
     bypass the "Wrap" dialog for files with long rows.  This procedure
     may also be able to cope with <name> values which are not obviously
     files (e.g. remote files, .zip archives, etc) if appropriate hooks
     are activated, and may take a different action (e.g. run an
     installer) with some <name> values.  To force Alpha to open <name>
     in a new window, the more fundamental command 'editDocument' could
     be used.  However that is rarely required.  The return value of  
this
     command is the name of the window which was opened (or the existing
     window if a duplicate was not wanted).  Alphatk supports an
     additional [-tabbed <tabWinTitle>] argument which, if given, places
     the window as a tab inside the tabbed window which has title
     tabWinTitle.
• editDocument <args> - ensure that initial window settings are in  
place.
     See fuller documentation in the file "coreImplementations.tcl".
     AlphaTcl code should only be calling the command: edit .
• new [-g <l> <t> <w> <h>] [-tabsize <val>] [-mode <val>] [-dirty <val>]
     [-shell <val>] [-info <val>] [-n <name>] - opens an untitled  
window. Can
     optionally provide left and top coordinates, plus width and height.
     All or none.  Alphatk supports an additional [-tabbed  
<tabWinTitle>]
     argument which, if given, places the window as a tab inside the  
tabbed
     window which has title tabWinTitle.  If the "-info" argument is  
given,
     the window will be automatically locked, with "<val>" inserted  
as the
     text, and the cursor will be placed at the beginning of the new  
window.
• revert [-w <win>] - revert the file to its last saved version
• save ?<win>? - save current window, or given window.  If the window  
has
     never been saved, then this will be re-routed, internally, to  
'saveAs'.
• saveAs ?-f? [def name] - save current window with new name. Optionally
     takes a default filename.  Returns complete path of saved file,  
if ok hit,
     otherwise TCL_ERROR returned.  If '-f' flag given, then we force  
the save
     without any standard-file dialog.
• saveResources [win] - save resource information for current window, or
     given window. The window must not be read-only, or a shell  
window, and
     needs to have a file associated with it.  The file's  
modification date
     and finder information will not be changed by saving the resource
     information. (Only available and relevant for Alpha 8/X).

	--------------------------------------------------------------------

= Window manager

• bringToFront <winName> - Bring named window to front.
• closeAll - close all windows
• floatIcon [-n <window name>] <resID> [<resID> ...] - make a little  
floating window
     containing small icons with the specified resource IDs.
• floatMenu <subcommand> [options] - manage floating palettes with  
commands
     from menus already created by the command: Menu .  Subcommands  
include
     "create", "delete", "hide", "list", "move", "show", and "top".   
floating
     menu palettes.  Complete documentation in the AlphaTcl Wiki at
     <http://www.purl.org/net/alpha/Wiki/Commands/FloatMenuCommand>.
• getGeometry [-s] [win] - return a Tcl list containing the left, top,
     width, and height of the 'content rectangle' of the current or  
given
     window (this includes scrollbars and text editing areas, but
     excludes the window border and title).  With the '-s' flag, returns
     the entire structure rectangle, including the window border and
     title.
• getMainDevice - return a list containing the left, top, right, and  
bottom
     of the rectangle defining the main device.
• getWinInfo [-w <win>] <arr> - Creates an array in current context
     containing info about either the current or a specified window.   
This
     array should be considered read-only.  It has fields 'state',
     'platform', 'read-only', 'tabsize', 'split' (if window is split,  
it is
     the percentage of the top pane, 0 otherwise), 'linesdisp' (num  
lines
     that can be seen in the window), 'currline' (first line  
displayed), and
     'dirty', 'font', 'fontsize' and 'encoding'.  Alphatk will also  
return a
     'shell' entry if that is set.  The proc: win::getInfo is the
     preferred interface to this information.  Alpha 8/X may also  
provide the
     'hasSpurious' (inconsistent line endings), 'needsWrap' (some  
lines are
     longer than the paragraph width), 'paneNum' (which pane is  
active in a
     split window, 0 for top, 1 for bottom) entries.
• icon [-f <winName>] [-c|-o|-t|-q] [-g <h> <v>] - Having to do w/
     iconifying windows.  '-c' means close (iconify) window, '-o'  
open, '-t'
     toggle open/close, '-q' returns either a '1' for an iconified  
window or a
     '0' for an uniconified window, and '-g' moves the icon to  
horizontal
     position <h> and vertical position 'v'.  Options are executed as  
they are
     parsed, so the '-f' option, if present, should always be first.
• killWindow [-w <win>] - kill window.  This closes the current window,
     calling preCloseHook, closeHook, etc as appropriate.  Note that  
if the
     window is dirty (has unsaved changes), and the user accepts the  
closure
     of the window, then 'dirtyHook' will not be called (AlphaTcl's core
     uses 'preCloseHook' to capture the fact that a dirty window is  
being
     closed, and thereby keep a correct count of the number of dirty
     windows).
• mousePos - Returns list <row,col> of mouse position, if the mouse is
     currently over the active window.  Otherwise, return error  
(catch w/
     'catch').
• moveWin [win name] <left> <top> - moves current or specified window.
     The window name can be "StatusWin".  This command attempt to move
     the window so the top-left corner of the window contents (not
     including the titlebar) is at the specified position.  Alpha may
     constrain the action to ensure the window is onscreen.
• otherPane [-w <win>] - If window is split, select the other pane.
• saveAll - save all currently open windows.
• setWinInfo [-w <win>] <field> <arg> - Sets a piece of data about  
either
     the current or a specified window.  Settable fields:
      platform     - lineendings for the window (mac/unix/dos)
      read-only    - is the window editable?
      tabsize      - character widths used for the tab character (\t)
      dirty        - does the window contain unsaved changes/edits.
      font         - the font name used for the window's contents
      fontsize     - the font size used for the widnow's contents
      shell        - if set, means that dirty flag and undo/redo is  
ignored
      state        - (ignored by Alphatk)
	 colortags    - list of tags for colouring of keywords
	 bindtags     - list of tags for keyboard bindings
	 wordbreak    - the regexp defintion of the end of a word
     Alphatk also provides
      encoding     - the character encoding which will be used to  
save this
                     window to disk
      linenumbers  - show a margin on the left edge of the window  
showing
                     line numbers.
      horscrollbar - include a horizontal scrollbar in the window
      wrap         - controls real soft wrapping (none/char/word)
     The proc: win::setInfo is the preferred interface to this  
information.
     Alpha 8/X may also provide the 'hasSpurious' (inconsistent line  
endings),
     and 'needsWrap' (some lines are longer than the paragraph width)  
entries.
• sizeWin [win name] <width> <height> - sets size of current or  
specified window.
     The window name can be "StatusWin", although only the width can  
be changed.
     This command attempt to adjust the size of the window contents (not
     including the titlebar) to the specified size.  Including the
     titlebar, the height will of course be larger than that given.  In
     addition, Alpha may have minimum and maximum allowed sizes, which
     will be applied as constraints to the given width, height.
• toggleSplitWindow [-w <win>] [percent] - toggle having window split  
into
     two panes. Optional arg specifies percent of window to allocate  
to the
     first pane.
• toggleScrollbar [-w <win>] - toggles horizontal scrollbar on  
frontmost window.
     Will not succeed if scrollbar scrolled.
• toolbar <subcommand> [args] - (AlphaX only) interact with the Toolbar
     object located at the top of the document windows.  Subcommands  
include
     "add", "configure", "create", "delete", "hide", "items",  
"remove", "set",
     and "show".  Complete documentation can be found in the AlphaTcl  
Wiki at
     <http://www.purl.org/net/Alpha/Wiki/Commands/ToolbarCommand>.
• windowVisibility [-w <win>] ?<hidden|normal|minimized>? - get or  
set the
     visibility state of a window: it is one of hidden, normal, or
     minimized. If the last argument is not specified, the command  
returns
     the current state.
• wins - return window boundaries for all windows.
• winNames [-f] - return a list of all open windows, ordered from
     frontmost window to backmost window, followed by any windows  
which are
     not really ordered (e.g. minimized, hidden windows, or those  
which are
     in the process of being created).  If the '-f' option is specified,
     complete pathnames are returned.  In both cases, when any  
window's name
     (as shown in the Open Windows menu) is not unique, ' <n>' (n =  
2,3...)
     is added to the window name to ensure a unique final path  
component.
     This can be removed (on an element by element basis) with
     'win::StripCount'.  The first element of this list is always the  
same
     as [win::Current].  The order of iconified/minimized windows is not
     necessarily defined, so they may just be listed, for example, in an
     arbitrary order after all normal windows.
• win::Current - returns the full name of the current window, or the  
empty
     string if no windows are currently open.  This is always the  
same as
     [lindex [winNames -f] 0].  Note that if a window is currently in  
the
     process of being opened (e.g. this function is called from, e.g.,
     openHook) then [win::Current] will not necessarily return the new
     window name (for example it might be being opened in a hidden  
state).
• zoom - zooms the current window

	--------------------------------------------------------------------

= Menu creation/manipulation

• addHelpMenu <item> - add 'item' to the OS Help menu. No menu  
conversion
     done, i.e. all items appear as given without being massaged in  
any way.
     In Alpha8/X/tk, 'item' can be a submenu created with the 'Menu'  
command.
• addMenuItem [-m] [-l <meta-characters>] <menu name> <item name>  
[<index>] -
     Convert item to menu form and add to specified menu.  The menu  
must have
     already been created by the command: Menu .  If '-m' specified,  
menu form
     conversion is not done.  The '-l' option allows you to use menu  
meta
     characters as text of menu items.  If the '-l' option is used, the
     <meta-characters> string is interpreted for menu item  
attributes, and
     meta-characters in <item name> are included in the menu item text
     literally.  For example:

	addMenuItem -m -l "/B" File "Hello/C"

     would appear as the text "Hello/C" in the menu, and have "B" as its
     command equivalent.  The "index" should be an integer greater  
than 0,
     indicating where the item should be placed.  (Do not use "0" or  
"end".)
     If not specified, the item will be inserted at the end of the menu.

• deleteMenuItem [-m] <menu name> <item name> - Convert item to menu  
form
     and delete from specified menu.  If '-m' is supplied, no menu form
     conversion is done.  The "item" should not include any meta  
characters,
     so to remove an item previously inserted with the command:  
addMenuItem
     one could use constructions like this:

	addMenuItem -m -l "/B" File "Hello/C<O"
	deleteMenuItem -m File "Hello/C<O"

	addMenuItem -m File "Hello/C<O"
	deleteMenuItem -m File "Hello"

• enableMenuItem [-m] <menuName> <item text> <on|off> - Either enable or
     disable the menu item of user menu 'menuName' that has text  
'<item text>'.
     Note that unless the menu is not only created, but also already  
inserted,
     this command has no effect.
• insertMenu <name> ?<name>...? - insert the previously created user
     menu(s) given by the 'name' argument(s) into the menuBar.
• markMenuItem [-m] <menuName> <item text> <on|off> [<mark char>] -
     Either mark or unmark the menu item of user menu 'menuName' that  
has text
     '<item text>'.  Note that unless the menu is not only created,  
but also
     already inserted, this command has no effect.
• Menu [-i <num][-m] [-M <mode>]  [-n <name|num>] [-p <procname>] [- 
s] <list> -
     Defines a new menu named 'name' (if provided w/ '-n' option)  
with items
     'list'.  The menu is not yet inserted into the menubar.  The menu
     commands may be nested for heirarchical menus, such as in the  
filesets
     menus.  By default Alpha massages the item names in the 'list'  
to make them
     look better in the menus.

       -c            Ignore any menu meta-chars. Can also be done on  
a per-item
                     basis by appending an ampersand ('&') to the end  
of an item.
       -m            No menu form. If not supplied, each menu item is  
split into
                     words at each capitalized letter.
       -M <mode>     Specifies that any bindings created by the menu are
                     specific to a given mode.  This is important  
because
                     mode-specific bindings over-ride global bindings.
       -n <name>     Name the menu. Not necessary for submenus.
       -n <num>      Resource id of icon suite to use for menu title.  
'ics#'
                     is the only resource that is really necessary.
       -p <name>     The tcl proc named by 'name' is called w/ the  
menu's name
                     and the item's contents when the item is chosen.
       -s            Use system menu definition proc (faster).

     See the "Extending Alpha # Menu Creation Syntax" section for more
     information about meta characters which can be used for  
individual items.

• menuNames - list all menus created by the command: Menu during the  
current
     editing session.
• menu::inserted <name> - is the given menu 'name' currently inserted  
into
     the menubar.  Returns "1" if it is, otherwise "0".
• removeMenu <name> ?<name>...? - remove menu(s) given by the 'name'
     argument(s) from the menubar.

	--------------------------------------------------------------------

= Inter-application communication

-- See TclAE Help

• icGetPref [<-t <type>] <pref name> - Gets preference from
     Internet Config.  '-t' allows type to be set, '0' returns a string
     (default), '1' returns a path name, commonly used for helper  
apps.  A <pref
     name> of 'all' returns all valid preferences.
• icOpen - Opens Internet Config
• launch -f <name> - launch the named app into the background. Note that
     for some yet unexplained reason, some applications (MicroSoft  
Word) won't
     launch completely in the background.  'launch'ing such  
applications won't
     insert the application into any system menu that specifies running
     applications (although "About the Finder..."  will list it.  The  
only way
     to get to such an app is through Alpha's 'switchTo', after which  
the
     application will finish launching.  The '-f' option gets around  
this by
     launching the application in the foreground instead.
• nameFromAppl '<app sig>' - Interrogates the desktop database for  
the first
     existing app that has the desired signature.  <app sig> is four  
chars
     inside single quotes.  Returns the full path to the executable.
• processes - returns info of active processes. A list of lists, each
     sublist contain a file-name, an application signature, the  
application
     memory size, and the number of ticks the application has been  
active.
• switchTo <appName> - Switches to application 'appName'.
• sendOpenEvent [filler] <app name> <file name> - Send an open doc  
event to
     another currently running application.  If 'filler' is noReply,  
then a
     reply is not requested.  Otherwise, we wait for a reply and  
'filler' is
     ignored.

	--------------------------------------------------------------------

= Keyboard bindings and codes

• ascii <char> [<modifier>] <script> [<mode>] - bind the given character
     with optional modifiers to the specified script, optionally for  
only
     a given mode.  <char> is a Tcl integer giving the character code
     corresponding to that key.  <modifier> is, if it is present, a  
string
     specifying which additional modifier keys that must be pressed for
     the binding to be activated.  The first character of this string  
must
     be < and the last must be >.  Remaining characters correspond to
     modifier keys as follows:


           c   - command modifier
           o   - option modifier
           s   - shift modifier
           z   - control modifier
           e   - escape modifier (activated by the startEscape command)
           A-Z - any capitalized character, for a control-<char> prefix
                 (activated by the prefixChar command)


     <script> is any Tcl script, usually a procedure call, that will be
     evaluated whenever the bound key combination is pressed.  <mode>  
is,
     if present, the name of the mode in which this binding should take
     effect.  If there is no <mode> argument then the binding will be
     global.  See "Keyboard Shortcuts" for more information.
• Bind <char> [<modifier>] <script> [<mode>] - bind the given character
     with optional modifiers to the specified script, optionally for  
only a
     given mode.  <char> specifies one of (1) a Tcl integer with the  
character
     code as in 'ascii', (2) a particular key either as an explicit  
character
     with a straight single quote (apostrophe) on both sides, such as  
'a', or
     (3) a "special" key such as Enter, Home, etc.  The string  
'\r' (including
     the single quotes) can be used to bind the Return key.  The Tab  
key can
     only be bound using "0x30" (without the double quotes).  See the
     explanation under "ascii" for more information, and the help file
     "Keyboard Shortcuts" for a complete list of special keys and  
examples.
• bindingList [<mode>] - return list of bindings. The optional <mode>
     argument restricts the output to the bindings specific to that  
mode.
     It can be "global" which is equivalent to the command with no  
option.
• deleteModeBindings <mode> - Delete all bindings for specified mode.
• describeBinding - display the binding of the next typed key sequence.
• getAscii - displays the ASCII code for character at current  
insertion point
• getChar - waits for a keystroke, returns ascii.
• getModifiers - returns current modifiers mask. "OR" of several values,
     cmdKey                      = 0x01,      /* Bit 0 of high byte */
     shiftKey                    = 0x02,      /* Bit 1 of high byte */
     alphaLock                   = 0x04,      /* Bit 2 of high byte */
     optionKey                   = 0x08,      /* Bit 3 of high byte */
     controlKey                  = 0x10,      /* Bit 4 of high byte */
     rightShiftKey               = 0x20,      /* Bit 5 of high byte */
     rightOptionKey              = 0x40,      /* Bit 6 of high byte */
     rightControlKey             = 0x80,      /* Bit 7 of high byte */
• insertAscii - prompt for an ASCII code and insert into text.
• keyAscii - insert ascii representation (in decimal) of the keydown  
event,
     plus a modifier string, if necessary.
• keyCode - insert the key code along w/ a string representing and  
modifiers
     into the current window. Used by the Alpha Dev menu to create  
bindings.
• prefixChar ?msg msg? - used to further modify the next keystroke
     combination.  If any arguments are given, they are used to form a
     message presented to the user in the status bar when this keystroke
     is triggered (if none are given then 'Prefix ...' is the message).
• startEscape - used to further modify the next keystroke combination,
     in the same manner as using the shift key in the next keystroke
• unascii <char> [<modifier>] <script> [<mode>] - unbind the ascii
     character previously bound using 'ascii'
• unBind <char> [<modifier>] <script> [<mode>] - unbind the keyboard
     character previously bound using 'Bind'.

	--------------------------------------------------------------------

= Status window

• coreKeyPrompt <thePrompt> - prompt the user for a single (possible
     modified) keypress.  Returns a two item list consisting of the  
key and a
     modifier specification.  If Shift was pressed, this be reflected  
in the
     modifiers but the key will also be returned in UPPER CASE.
• displayMode <mode> - Up to four characters of the 'mode' string are
     displayed in the status line at the bottom of a window.  Note
     that in Alpha 8/X at present this will throw an error if passed
     the empty string.  In Alphatk an empty string will lead to the  
removal
     of the popup mode, wrap, encoding, etc. menus from the status bar.
• displayPlatform <string> - Sets the text string to show as the  
label in
     the menu button which controls the 'platform' popup menu in the  
status
     bar.  Typically this is used internally by AlphaTcl to set this  
label
     to one of 'mac', 'unix' or 'dos' to reflect the current window's
     line-endings (mac = CR, unix = LF, dos = CRLF).  To change the
     line-endings in use for the current window, see 'setWinInfo'.
• displayWrap <string> - Sets the text string to show as the label in  
the
     menu button which controls the 'line wrap' popup menu in the  
status bar.
     Typically it is used internally by AlphaTcl to set this label to  
one of
     'none', or 'auto' (additionally 'visual-char', 'visual-word' in
     Alphatk).  To change the actual wrap style of the current  
window, set
     your mode's 'Line Wrap' preference.
• displayEncoding <string> - Sets the text string to show as the  
label in the
     menu button which controls the 'encoding' popup menu in the  
status bar.
     Typically it is used internally by AlphaTcl to set this label to  
the
     current window's encoding ('macRoman', 'utf-8', etc).  This is only
     available in Alphatk.
• execute - prompt user for a function or macro. The tab key acts as a
     "completion" command.
• progressBar <subcommand> [args] - (AlphaX only) manage a progress  
bar in
     the status window.  Subcommands include "configure", "hide", and  
"show".
     Complete documentation can be found in the AlphaTcl Wiki at
     <http://www.purl.org/net/Alpha/Wiki/Commands/ProgressBarCommand>.
• status::msg <string> - prints 'string' on the status line.  (This
     should be used in preference to the older 'message' which conflicts
     with Tk).
• statusPrompt <prompt> [<func>] - Prompt in the status window. If  
'func'
     is present, call this routine at each key-press with the current  
contents
     of the status line and the key, insert into statusline whatever  
is returned
     by the func.  Command-v pastes the current (<80 char) clipboard  
contents on
     the status line.  Also see the proc: status::prompt which is  
more flexible.

	--------------------------------------------------------------------

= Filesystem

• getFileInfo <file> <arr> - Given a file or folder name, creates an  
array
     called 'arr' in the current context, containing fields 'created',
     'modified', 'creator', 'type', 'datalen', and 'resourcelen'.  
These last
     four fields are ignored in the case of a directory. 'created' and
     'modified' are in a form suitable for the command 'mtime'. On  
Alphatk
     with non-MacOS platforms, the 'type' entry is always 'TEXT' and the
     'creator' entry is just the <file> given. On AlphaX, there is a
     'bundle' field to tell whether the item is a bundle (directory
     displayed as a file) or not. There is also a 'hidden' field  
indicating
     if the file is visible or not. Most (all in Tcl 8.5) fields of
     getFileInfo can be accessed through 'file attributes', 'file mtime'
     etc., which are preferred.
• getStandardFolder [-create] folderType [domain] - (AlphaX only)  
Wrap the
     ToolBox function of the same name.  It returns the full path of  
certain
     system-related directories.  Optionally this function can create  
(or
     attempt to create, depending on the permissions) the folders  
when they do
     not exist already.  Complete documentation in the AlphaTcl Wiki at
     <http://www.purl.org/net/Alpha/Wiki/Commands/GetStandardFolder>
• ls - unix style directory listing, described in "Shells"
• setFileInfo <file> <field> [arg] - set some information for files.
     Settable fields are 'modified', 'created', 'creator', and  
'type'. All
     take an argument except 'resourcelen' which just removes the  
resource
     fork. 'file' is a complete pathname. On AlphaX, there is a 'hidden'
     field to make the file invisible in the Finder. Most (all in Tcl  
8.5)
     fields of setFileInfo can be accessed through 'file attributes',  
'file
     mtime' etc., which are preferred.

	--------------------------------------------------------------------

= Debugging

• echo <string>* - echo the strings (used in shells).
• evaluate [-w <win>] ?script? - evaluates given text, else hilited  
text,
    or entire window if nothing is hilited.  'evaluat'ing means that  
whatever
    Tcl code (procs, bindings or macro definitions etc) is present in  
the
    evaluated text take effect
• tclShell - open the Tcl shell.

	--------------------------------------------------------------------

= Colours

• colorTagKeywords [options] <colortag> <keyword list> - Set keywords
     to color for the given tag. Valid options are:

        -a			  Keywords will be *added* to existing <colortag>
                    keywords.  The new keywords can be a different
                    color to older keywords.
        -k <color>		Keyword color.
        -C          All keywords for this colortag are case-sensitive.

     No other options are allowed.  This command may be evaluated
     repeatedly for a given colortag, to declare multiple sets of
     color+keywords.  However the '-C' flag applies to all keywords
     with all colours, and need therefore only be given once -- it
     should be given (or not, if undesired) the first time that
     colorTagKeywords is called for the given colortag.  So a typical
     usage will be:

       colorTagKeywords -C foo {}
       colorTagKeywords -a -k blue foo {list of keywords}
       colorTagKeywords -a -k magenta foo {list of keywords}

     (This command is only in Alphatk 8.3fc5 and Alpha 8.0b16 or newer,
     and in Alpha 8/X there is a limit of 20 characters for  
<colortag> and
     of 40 characters for any individual keyword)
• dumpColors - dump current foreground and background colors into the
     current buffer in Alpha-readable format.
• getColors [-w <win>] - returns list of colors/hypertext for current  
document
     or for the window specified with the -w option. Format is list  
of lists,
     each sublist consisting of file offset, color index, and possibly a
     hypertext command.
• insertColorEscape [-w <win>] <pos> <color ind> [hypertext func] -  
Create a
     color or style "point" for documentation purposes.  Look at the  
file
     "colorsMenu.tcl" for examples.  The hypertext func is only used  
when the
     "point" is underlined.  See 'getColors' for info about the  
current file.
     You should now use the proc: text::color and the proc:  
text::hyper instead
     of this function.
• refresh [-w <win>] - redraw the window colours, required in Alpha8/ 
X after
     applying colours with [text::color], this is a dummy proc in  
Alphatk.
• regModeKeywords [options] <mode> <keyword list> - Set keywords and  
comments
     that Alpha can recognize to color them.  Specifically, in mode  
<mode>,
     every keyword specified in the list is colored non-black (blue, by
     default).  Comments, if specified by '-e' or '-b' below, are  
colored red by
     default.    Each keyword must be shorter than 40 characters in  
Alpha8/X.

       -a              Keywords will be *added* to existing mode  
keywords.
                       The new keywords can be a different color than  
older
                       keywords.  This flag can also be used to  
modify other
                       attributes.
       -b <beg> <end>  Specify a pair of strings that bracket a comment.
       -C              Keywords are case sensitive.  When used it  
should be
                       the first regModeKeywords statement done in a  
mode.
                       Use an empty <keyword list> e.g. {}, like
                       this 'regModeKeywords -C Tcl {}'
       -c <color>      Comment color.
       -e <commentstr> Specify a string that begins comments that  
last to
                       the end of the line.
       -f <color>      'Function' color, which will color any word  
preceding '('
       -i <char>       Specify a character to display differently.
                       Commonly used for curly braces, etc.
       -I <color>      Color of above characters.
       -k <color>      Keyword color.
       -m <c>          Specify a magic character. Every word  
beginning with the
                       magic character is a keyword.
       -s <color>      String color. Alpha8/X can color single-line  
strings only,
                       using the simple heuristic of assuming the  
first two double
                       quotes constitute a string.

• removeColorEscapes [-w <win>] - remove color escapes from topmost  
window.

	--------------------------------------------------------------------

= Keyboard macros

• iterationCount - allows actions to be repeated many times.
     "control-u 44 =" inserts 44 '='s into current window.  Also can  
be used to
     execute any function or macro (including the keyboard macro)  
many times.
     Defaults to 4.
• macro::current - return the most recently recorded keyboard macro  
as a proc.
• macro::endRecording - stop recording keyboard macro
• macro::execute - execute the current keyboard macro
• macro::startRecording - start recording keyboard macro
• macro::recording - are we currently recording?

	--------------------------------------------------------------------

= Time related

• cvttime - convert input time to/from some epoch (+/- 0x7c25b080).
• mtime <time> [long|short|abbrev] - return a date and time string using
     the Macintosh International Utilities.  The long/short/abbrev  
specification
     corresponds to the date.  These are the following formats:

       short     3/16/92 9:20:46 PM
       abbrev    Mon, Mar 16, 1992 9:20:49 PM
       long      Monday, March 16, 1992 9:20:43 PM

     The returned value actually is in the form of a list.  To get  
text as
     above, run the result through 'join', as in "join [mtime [now]  
short]".
• now - return the current time as Macintosh seconds. This is the number
     of seconds that have elapsed since Midnight Jan 1, 1904.
• ticks - return the current TickCount. Ticks are 60ths of a seconds.
     TickCount is the number of ticks since the Macintosh was  
started.  The
     command:

       puts stdout [expr "[ticks] / 60"]

     will print the number of seconds since the Macintosh was booted.

	--------------------------------------------------------------------

= Marks

• createTMark [-w <win>] <name> <pos> - create a temporary 'mark' at
     location 'pos'.
• getNamedMarks [-w <win>] [-n] - return list of all permanent marks
     in open files.  Each element of a list describes one mark as a  
sublist of
     the mark's name, the complete pathname of the mark's file, the  
position of
     the first character in the first line displayed, the current  
position, and
     the end of the selection if text is hilited, or the current  
position again
     if there is no hilited section.  '-w' allows window name to be  
applied as
     filter, '-n' means only names will be returned.
• getTMarks [-w <win>] - return a list of temporary marks. Each item  
of the
     returned list is a sublist containing the mark name, the  
complete pathname
     of the mark, and the start and finish of the selection named by  
the mark.
     The following is an example of the result:

       {{temp1 External:file.c 1312 1315} {temp2 Internal:it.h 111 111}}

• removeNamedMark [-w window] [-n name] - remove a mark previously  
set by
      'setNamedMark'.  If neither -w nor -n are specified, presents  
the user with
      a dialog containing all marks from all open windows.  If only - 
w is
      specified, presents the user with a dialog containing all marks  
from the
      specified window.  If both -w and -n are specified, the mark  
'name' is
      removed from 'window'.  If only -n is specified, the mark  
'name' is removed
      from the current window.
• removeTMark [-w <win>] <name> - remove temporary mark.
• setNamedMark [-w <win>] [name disp pos end] - set named mark. If
     optional arguments are present, the mark is created without  
prompting
     user.  'disp' is the character position of the start of the first
     line to be displayed, while 'pos' and 'end' bracket the text to be
     selected.

	--------------------------------------------------------------------

= Remaining commands

(in alphabetical order) --

   some of these still need placing in other sections of this document.

• abbreviateText <font> <string> <width> - return an abbreviated  
string that
     will fit in the given pixel-length specificed by "width".  The  
"font"
     argument can be either an integer or a font name.  In the case  
of an
     integer, it is precisely a theme font ID. Allowable values  
include these
     specified below in the command: getTextDimensions .  It is  
possible to
     use either the integer value or its symbolic name.  So, for  
instance, one
     can use either:

	abbreviateText kThemeLabelFont $HOME 125
	abbreviateText 6 $HOME 125
	
     Limited support for using Font names (such as monaco or geneva)  
exists
     but is discouraged to ensure cross-platform compatibility;  
integers from
     the set {0 1 2 3} are fully supported in both AlphaX and Alphatk.

• abortEm - aborts whatever is currently happening
• tags::createFile - In "tags.tcl".
• tags::find - In "tags.tcl".
• beep [-volume num] [-list | sndName]? where -volume and -list are  
switches,
     while num and sndName are variables. Example:
       beep -volume 3 "click in set 5"
     will play at volume 3 the sound named "click in set 5" in the  
Alpha's snd
     resource.  Any sound stored in that resource can be used as  
well, so feel
     free to paste a sound (with ResEdit) in the snd resource to have it
     available.
• breakIntoLines <string> [fillColumn [leftFillColumn]] - return  
'string'
     with carriage returns and spaces inserted to satisfy  
'leftFillColumn'
     and 'fillColumn' variables (unless values are given for these).
     ("paragraphs.tcl")
• getTextDimensions [options] <text> - returns the rectangular
     bounds of <text> in pixels. Bounds are returned as
     {left ascent right descent} around the (0,0) origin
     of the line of text. The font, size and display width can be
     specified with the following options (later options override
     earlier ones). If not otherwise specified, the default font
     and size are used.  If '-width' is given, then newlines will
     trigger the creation of a new line in the height calculation, but
     otherwise they will be treated just as spaces.  Currently tabs
     are treated as the size of an ordinary character.

       -w <win>        Use the font and size of the specified window
       -font <font>    Use the specified font (integer or name).
                       Special Appearance Manager meta fonts (which
                       affect the font, size, and style) can be
                       specified as one of

                          0 or kThemeSystemFont
                          1 or kThemeSmallSystemFont
                          2 or kThemeSmallEmphasizedSystemFont
                          3 or kThemeViewsFont

                 The remaining ID's are only available in AlphaX

                          4 or kThemeEmphasizedSystemFont
                          5 or kThemeApplicationFont
                          6 or kThemeLabelFont
                          7 or kThemeSystemFontDetail
                          8 or kThemeSystemFontDetailEmphasized
                        100 or kThemeMenuTitleFont
                        101 or kThemeMenuItemFont
                        102 or kThemeMenuItemMarkFont
                        103 or kThemeMenuItemCmdKeyFont
                        104 or kThemeWindowTitleFont
                        105 or kThemePushButtonFont
                        106 or kThemeUtilityWindowTitleFont
                        107 or kThemeAlertHeaderFont

                 The remaining ID's are available in OS 10.2 or greater
                        108 or kThemeToolbarFont
					   200 or kThemeCurrentPortFont

       -size <size>    Point size (positive integer). Whether
                       given earlier or later, if an Appearance
                       Manager meta font is specified, this size
                       setting is ignored.
       -width <width>  Measure the text in a box of specified width,
                       wrapped to as many lines as necessary.
                       If this option is missing or set to zero, the
                       bounds of the text as a single line is returned.
       --              End of tags

     This command introduced in 8.0b9. Not available on 68k.
• getThemeMetrics <arr> - Fills <arr> with the sizes of the
     interface elements in the current environment. This command
     introduced in 8.0b9.  It populates the array with the following
     keys (some of these are not currently produced on Alphatk, but
     they will be in the future):

     ScrollBarWidth: The width of a scroll bar.  For horizontal scroll
     bars, this measurement is actually the scroll bar height.

     SmallScrollBarWidth: The width of a small scroll bar.  For
     horizontal scroll bars, this measurement is actually the scroll bar
     height.

     CheckBoxHeight: The height of the non-label part of a check box
     control.

     RadioButtonHeight: The height of the non-label part of a radio
     button control.

     EditTextWhitespace: The amount of white space surrounding the text
     rectangle of the text inside of an Edit Text control.  If you  
select
     all of the text in an Edit Text control, this white space is
     visible.  The metric is the number of pixels, per side, that the
     text rectangle is outset to create the whitespace rectangle.

     EditTextFrameOutset: The thickness of the Edit Text frame that
     surrounds the whitespace rectangle (which surrounds the text
     rectangle).  The metric is the number of pixels, per side, that the
     frame rectangle is outset from the whitespace rectangle.

     ListBoxFrameOutset: The number of pixels that the list box frame is
     outset from the content of the list box.

     FocusRectOutset: This is a deprecated metric and you should not use
     it.  This metric describes how far from a control the focus
     rectangle was drawn, but control focus drawing no longer uses this
     information.

     ImageWellThickness: The thickness of the frame drawn by
     DrawThemeGenericWell.

     ScrollBarOverlap: The number of pixels a scrollbar should overlap
     any bounding box which surrounds it and scrollable content.  This
     also includes the window frame when a scrollbar is along an edge of
     the window.

     LargeTabHeight: The height of the large tab of a tab control.

     LargeTabCapsWidth: The width of the caps, or end pieces, of the
     large tabs of a tab control.

     TabFrameOverlap: The amount you must add to the tab height,
     kThemeMetricLargeTabHeight, to find the rectangle height to use  
with
     the various tab drawing primitives.  This amount is also the amount
     that each tab overlaps the tab pane.

     TabIndentOrStyle: If less than zero, this indicates that the text
     should be centered on each tab.  If greater than zero, the text
     should be justified, according to the system script direction, and
     the amount is the offset from the edge at which the text should
     start drawing.

     TabOverlap: The amount of space that every tab's drawing rectangle
     overlapsthat of the tab on either side of it.

     SmallTabHeight: The height of the small tab of a tab control.  This
     includes the pixels that overlap the tab pane and/or tab pane bar.

     SmallTabCapsWidth: The width of the caps, or end pieces, of the
     small tabs of a tab control.

     PushButtonHeight: The height and the width of the push button
     control.

     ListHeaderHeight: The height of the list header field of the data
     browser control.

     DisclosureTriangleHeight: The height of a disclosure triangle
     control.  This triangle is the not the center of the disclosure
     button, but its own control.

     DisclosureTriangleWidth: The width of a disclosure triangle  
control.

     LittleArrowsHeight: The height of a little arrows control.

     LittleArrowsWidth: The width of a little arrows control.

     PopupButtonHeight: The height of a popup button control.

     SmallPopupButtonHeight: The height of a small popup button control.

     LargeProgressBarThickness: The height of the large progress bar,  
not
     including its shadow.

     PullDownHeight: This metric is not used.

     SmallPullDownHeight: This metric is not used.

     ResizeControlHeight: The height of the window grow box control.

     SmallResizeControlHeight: The width of the window grow box control.

     HSliderHeight: The height of the horizontal slider control.

     HSliderTickHeight: The height of the tick marks for a horizontal
     slider control.

     VSliderWidth: The width of the vertical slider control.

     VSliderTickWidth: The width of the tick marks for a vertical slider
     control.

     TitleBarControlsHeight: The height of the title bar widgets (grow,
     close, and zoom boxes) for a document window.

     CheckBoxWidth: The width of the non-label part of a check box
     control.

     RadioButtonWidth: The width of the non-label part of a radio button
     control.

     NormalProgressBarThickness: The height of the normal progress bar,
     not including its shadow.

     ProgressBarShadowOutset: The number of pixels of shadow depth drawn
     below the progress bar.

     SmallProgressBarShadowOutset: The number of pixels of shadow depth
     drawn below the small progress bar.

     PrimaryGroupBoxContentInset: The number of pixels that the content
     of a primary group box is inset from the bounds of the control.

     SecondaryGroupBoxContentInset: The number of pixels that the  
content
     of a secondary group box is from the bounds of the control.

     MenuMarkColumnWidth: The width allocated to draw the mark character
     in a menu.

     MenuExcludedMarkColumnWidth: The width allocated for the mark
     character in a menu item when the menu has the attribute
     kMenuAttrExcludesMarkColumn.

     MenuMarkIndent: The indent into the interior of the mark column at
     which the mark character is drawn.

     MenuTextLeadingEdgeMargin: The whitespace at the leading edge of
     menu item text.

     MenuTextTrailingEdgeMargin: The whitespace at the trailing edge of
     menu item text.

     MenuIndentWidth: The width per indent level of a menu item.  This
     indent is set by the SetMenuItemIndent function.

     MenuIconTrailingEdgeMargin: The whitespace at the trailing edge  
of a
     menu icon, if the item also has text.

     DisclosureButtonHeight: The height of a disclosure button.  (Mac OS
     X only.)

     RoundButtonSize: The height and the width of the round button
     control.  (Mac OS X only.)

     SmallCheckBoxHeight: The height of the non-label part of a small
     check box control.  (Mac OS X only.)

     DisclosureButtonWidth: The width of a disclosure button.  (Mac OS X
     only.)

     SmallDisclosureButtonHeight: The height of a small disclosure
     button.  (Mac OS X only.)

     SmallDisclosureButtonWidth: The width of a small disclosure button.
     (Mac OS X only.)

     PaneSplitterHeight: The height (or width if vertical) of a pane
     splitter.  (Mac OS X only.)

     SmallPushButtonHeight: The height of the small push button control.
     (Mac OS X only.)

     SmallRadioButtonHeight: The height of the non-label part of a small
     radio button control.  (Mac OS X only.)

     RelevanceIndicatorHeight: The height of the relevance indicator
     control.  (Mac OS X only.)

     LargeRoundButtonSize: The height and the width of the large round
     button control.  (Mac OS X only.)

     SmallHSliderHeight: The height of the small, horizontal slider
     control.  (Mac OS X only.)

     SmallHSliderTickHeight: The height of the tick marks for a small,
     horizontal slider control.  (Mac OS X only.)

     SmallVSliderWidth: The width of the small, vertical slider control.
     (Mac OS X only.)

     SmallVSliderTickWidth: The width of the tick marks for a small,
     vertical slider control.  (Mac OS X only.)

     SmallCheckBoxWidth: The width of the non-label part of a small  
check
     box control.  (Mac OS X only.)

     SmallRadioButtonWidth: The width of the non-label part of a small
     radio button control.  (Mac OS X only.)

     SmallHSliderMinThumbWidth: The minimum width of the thumb of a
     small, horizontal slider control.  (Mac OS X only.)

     SmallVSliderMinThumbHeight: The minimum width of the thumb of a
     small, vertical slider control.  (Mac OS X only.)

     SmallHSliderTickOffset: The offset of the tick marks from the
     appropriate side of a small horizontal slider control.  (Mac OS X
     only.)

     SmallVSliderTickOffset: The offset of the tick marks from the
     appropriate side of a small vertical slider control.  (Mac OS X
     only.)
• linkVar - link a Tcl variable to a preexisting internal variable of  
the
     same name (only meaningful on Alpha 7/8/X).
• pageSetup - display the printing PageSetup dialog.
• print ?win? - print front window
• quit - quits ALPHA
• version - Return string of the form "AlphaX 8.0a8, Sunday, 23 March  
2003"

	--------------------------------------------------------------------

= Uncommon/unused commands

Probably best to avoid using these.

• specToPathName [hex data] - given an FSSpec in hex form (as that
     returned by AEbuild, for instance), return a complete pathname.

	--------------------------------------------------------------------

= Obsolete (and possibly buggy)

These WILL be removed in a future version (if they haven't been  
already).

• addAlphaChars <chars> - Add <chars> to the list of characters that  
internally
     are caught by the 'isalnum' and 'isalpha' calls.  Can be used to  
augment
     the list of characters that the \w pattern in a regular  
expression responds
     to.  Use w/ care.  (only supported in Alpha 8/X).
• AEBuild [<flags>] <app (name|creator)> <aesuite> <aeevent> [<event  
parameters>]*  -
     *** Deprecated in favor of [tclAE::send], "TclAE Help" ***
     Build and send an apple-event.  'AEBuild' is apple's code of the  
same name.
     Each "event parameter" is two parameters, a parameter type and  
the data for
     the parameter.  See the "AEGizmos" help file for more details.  
Flags include:

       -r            Wait for reply.
       -q            Queue reply, in which case 'handleReply' (in  
appleEvents.tcl)
                     is called with the reply as a parameter.
       -t <timeout>  Specifies the timeout in ticks.
• closeFloat - close the top floating window.  This command is  
deprecated;
     use [floatMenu delete [floatMenu top]] instead.
• dosc [<-c 'sign' | -n appName>] [-k 'clas'] [-e 'evnt'] <-s string  
| -f fileName> [<-t timeout|-r>]
     *** Deprecated in favor of [tclAE::send], "TclAE Help" ***
     Send an AppleEvent, by default class 'misc', event 'dosc'.

       -c 'sign'     "sign" is a four-letter creator signature of a
                     running application.
       -n appName    "appName" is the name of a running application.
       -k 'clas'     "clas" is a four-letter event class.
       -e 'evnt'     "evnt" is a four-letter event class.
       -s string     "string" is the text of a script to send to the  
other app.
       -f fileName   "fileName" is the complete or relative pathname  
of a file
                     the other application should execute.
       -t timeout    "timeout" is the number of ticks Alpha should  
wait for
                     a response. A timeout of "0" means wait forever.
       -r            Do not wait for reply.
       -q            Queue reply.

     If neither of the '-c' and '-n' options is chosen, the PPC  
Browser is used.
     Either '-s' or '-f' must be chosen.  Thus, you can have "Alpha  
5.02" and
     "Alpha 5.02 Copy" sending Apple events to each other, or they  
can send
     events to a remote server such as Apple's ToolServer.
• eventHandler [class] [event] [proc]
     *** Deprecated in favor of [tclAE::installEventHandler], "TclAE  
Help" ***
     Register 'proc' to handle the class and event specified.  Class and
     event are each 4 char args.  'proc' takes a single argument that
     specifies the incoming event according to the syntax here.   
There is
     currently no provision for a reply.
• float -m <menu> [<-h|-w|-l|-t|-M> <val>] [-n winname] [-z tag] -
     Takes a created menu (not necessarily in the menubar), and makes a
     floating window out of it.  Returns integer tag that is used to  
remove
     the window.  With no arguments, returns all currently defined  
menus.
     -h through -M change width, height, left margin, top margin, and  
margin
     between buttons.  -z allows a ten-char tag to be specified for
     'floatShowHide'.  Deprecated; use the command: floatMenu instead.
• floatShowHide <on|off> <tag> - Shows or hides all floats w/  
specified tag.
     Tags of current modes are automatically shown/hidden.  This  
command is
     deprecated; use the [floatMenu <show|hide> token] instead.
• getline <prompt> <default> - display an OS alert box with prompt  
displayed, a
     text edit field with default initially in the field, and with  
the push
     buttons OK, Cancel.. The command will return the text entered  
into the
     text edit field by the user, or an empty string if the user  
selected the
     Cancel button.  This core command is now obsolete; use the proc:  
getLine
     instead and take advantage of its additional arguments.
• icURL <URL> - passes arg to Internet Config, if present. Error if not
     present.  You should use [url::execute] instead (icURL is  
deprecated).
• largestPrefix <list> - return the longest prefix contained in all
     strings of 'list'.
• unfloat <float num> - removes specified floating window. W/ no options
     lists all floating windows.  Deprecated; use [floatMenu delete  
token].
• watchCursor - turns the cursor into a a watch cursor.




More information about the textmate mailing list