[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