Alpha Commands
Alpha
Version:9.0b2
Last update:2017-04-04 14:39:39




This document contains information about all the Alpha-specific Tcl commands defined in the core of the application.
The page Alphabetical Commands presents the commands in alphabetical order. There is also an alphabetical index at the end of this document.
In Alpha, most of these commands are implemented in Objective C but, in some cases, they are now defined in AlphaTcl. In addition, of course, all the standard Tcl 8.6 commands are available. Some complex commands also have an exhaustive reference file: they are indicated in the text.
In this list of commands, text between angle brackets '< >' is a placeholder for a required parameter, text between question marks '?' is a placeholder for an optional parameter, and the vertical bar '|' signifies a choice of two or more alternatives. A '+' signifies that the previous symbol can be present one or more times, while an asterisk '*' means zero or more times. Some commands have no parameters.
Many commands accept an optional window argument ?-w win?, where win can be any item from the list given by [winNames]. If it is not specified, the command applies to the current window or raises an error if no window is open. Window names are case-sensitive.

Application


appExec method
This command executes various tasks at the application's level. The possible values for the method argument are:
aboutPanelDisplay the About window
characterPanelOpen the character palette
colorPanelOpen the color palette
hideHide all Alpha's windows and next application is activated
hideOthersHide windows of all other applications
miniaturizeAllMiniaturize all Alpha's windows
terminateQuit Alpha
unhideRestore hidden windows to the screen
unhideAllUnhide all applications, including Alpha

beep
Play the system beep.
getAppInfo subcommand ?option ?value??
Return information about Alpha or other applications. The syntax can take different forms (explained below): The options have the following meaning:
OptionDescription
-bbundle identifier
-kkind
-nname
-pprocess identifier
-sapplication signature
The subcommands have the following meaning:

quit
Quit the application. This call invokes the quitHook.

Basic insertion position queries


blinkPos ?-w win? pos1 ?pos2?
Flash a portion of text. If only pos1 is specified, the command flashes the character located at this position. If both pos1 and pos2 are specified, the entire range of characters between pos1 and pos2 is flashed. The command raises an error if invalid positions are specified. pos2 may be smaller than pos1.
displayPos ?-w win? ?pos?
Move the line containing position pos to the top of the document window. If the pos argument is not specified, the command applies to the current insertion position.
getPos ?-w win?
Return the current position of the insertion point.
hiliteToPreviousPosition ?-w win?
Hilite the text from the current insertion point to the previous insertion position if there is no selection, otherwise clear the selection. The previous position is obtained with the
[prevPos] command.
linePos subcommand ?-w win? ?{pos1 ?pos2?}?
Return the beginning or end positions of the line(s) containing the range specified by the last argument. The value of the last argument can be a single position or a list of two positions representing an interval. If it is not specified, the command applies to the current insertion position of the document. The provided positions pos1 and pos2 are adjusted if necessary to ensure that their range is within the bounds of the document. If pos1 only is specified, pos2 is assumed equal to pos1. Different positions can be obtained depending on the specified subcommand. Possible values are:
startPosition of the first character of the line containing the beginning of the range.
endPosition of the first character of the terminator of the line containing the end of the range.
nextPosition of the first character past the terminator of the line containing the end of the range.
rangeInterval of positions representing the line(s) containing the range, including the line termination characters.
allAll three positions: start, end and next in that order.
A line is delimited by any of these characters, the longest possible sequence being preferred to any shorter:
matchIt ?-w win? brace pos ?num?
Return the position of the matching brace. This command supports parentheses (), curly braces {}, square brackets [], and angle braces <>. The brace character passed to this command should be the one whose partner you wish to find (not the one you want to search for). This determines the direction of the search: for instance, if you specify a closing parenthesis ), the command will look backwards for the matching opening parenthesis (.
The second argument specifies the position from where to start the search: this is not the position of the original brace. This argument is the first position when looking forwards (respectively the last position when looking backwards) where a matching brace can be found. To be more specific: In both cases, this is the limit value which should be specified as the pos argument. The returned position can't be less than pos when looking forwards and can't be more than pos when looking backwards. 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.
The optional third argument specifies how many characters to search starting from the specified position.
maxPos ?-w win?
Return the position of the last character in the specified window. This is the number of characters in the window.
minPos ?-w win?
Return the position of the first character in the specified window. This command exists for compatibility reasons. It always returns 0.
posToRowCol ?-w win? ?-v? pos
Convert from absolute position to row and column values. It raises an error if the pos argument is out of range. The values are returned as a two-element list corresponding to the row and column indices respectively.
The
-v option is used to calculate virtual column values taking into account the size of the tabulations. For instance, if a line starts with a tabulation followed by a letter A, the A is at actual position (column) 1 in the row but at virtual position 4 if the tabulation size for the window is set to 4. Examples:
StringTrue colVirtual col
tab|14
A+tab|24
AB+tab|34
ABC+tab|44
ABCD+tab|58
This table indicates the true and virtual positions of the vertical bar assuming the string is at the beginning of a line and tabSize=4.
prevPos ?-w win?
Return the previous insertion position (the one which was current just before the new current position was set). This is useful mainly to implement procs like
[hiliteToPreviousPosition].
rowColToPos ?-w win? ?-v? row col
Return the absolute position of the character located at the given row and column values. It raises an error if the row argument is out of range.
If the col argument exceeds the end position of the given row, the command returns the position corresponding to the end of this row.
If the
-v option is specified, the col argument is interpreted as a virtual index taking into account the size of the tabulations (see explanations with the [posToRowCol] command).
setPos ?-w win? pos
Set the position of the insertion point at pos. This command is different from the goto command as it does not scroll the text to make the new position visible. As a side effect, it removes any existing selection.

Basic insertion position movement


backwardChar ?-w win?
Move the insertion point one character back.
backwardWord ?-w win?
Move the insertion point 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 specified window.
When no pos argument is specified, the command is meant for asynchronous use: it prompts for a position in the specified window and jumps to it. When run asynchronously, this command returns immediately and should not be used in a Tcl script.
gotoColumn ?-w win? ?col?
If col is specified, the command sets the current position to the given column on the current row and makes it visible. If the value of col is greater than the length of the row, the command jumps to the actual end of the line.
When no col argument is specified, the command is meant for asynchronous use: it prompts for a column in the specified window and jumps to it (equivalent to clicking on the column indicator at the bottom of the window). When run asynchronously, this command returns immediately and should not be used in a Tcl script.
gotoLine ?-w win? ?row?
If row is specified, the command sets the current position to the beginning of this row and makes it visible. If the value of row is greater than the number of lines in the document, the command jumps to the beginning of the last line.
When no row argument is specified, the command is meant for asynchronous use: it prompts for a line in the specified window and jumps to it (equivalent to clicking on the row indicator at the bottom of the window). When run asynchronously, this command returns immediately and should not be used in a Tcl script.
matchBrace ?-w win?
Move the insertion point to the character that matches the character after the current insertion point.
nextLine ?-w win?
Move the insertion point to the next line, except if there is a selection, in which case the insertion point is moved to the end of the selection. This proc is really only for implementing the down-arrow functionality.
previousLine ?-w win?
Move insertion point to the previous line, except if there is a selection, in which case the insertion point is moved to the beginning of the selection. This proc implements the up-arrow functionality.
scroll (up|down|left|right) ?-w win? ?-page? ?amount?
Scroll the current pane of a document window in the specified direction. If the
-page option is specified, the command scrolls by a full page's width or height worth. Otherwise, the scrolling quantity is equal to the default line height when moving vertically or the default horizontal scroll amount when moving horizontally. The count argument is an integer to multiply the scrolling amount. Its default value is 1.

Basic text manipulation


abbreviateText ?-font dict? ?-break mode? ?--? string width
Return an abbreviated string that will fit in the given pixel length specified by the width argument.
The
-font option has the same meaning as with the [getTextDimensions] command. See the file Alpha Fonts to know how fonts are specified. If no font is specified, the default is to use the system font at size 10.
The -break option specifies where the string argument should be truncated. The possible values are:
headtruncate at the start of the string
middletruncate in the middle of the string
tailtruncate at the end of the string
The default is tail.
The '
--' option indicates the end of the options.
getKey ?-p str? ?-a? ?-b? ?-c? ?-d? ?-k? ?-m?
Capture a key combo. The command prompts the user to enter a key combo, i-e to press a key on the keyboard, with or without modifier keys. The command returns the keydown event in various forms depending on the chosen options.
This command returns a list which may contain the modifiers, the character code and the key code (in that order). You specify which elements you want using any of the following options:
If none of these options is specified, -c is assumed.
You may additionally specify a format with the following options:
The -p option specifies a prompt string to display in the status bar. If it is not specified, the command displays a default string asking to enter a key combo.
The
-b option returns the key combo in a format suitable for use with the [binding] command. By default, it assumes the -c option, but specifying the -k option is possible in order to get a virtual key binding.
Here are some examples of the output of the command in the case of a ⌘A combo (note that the ascii code of 'a' is 97 and that the corresponding key on the keyboard has code 12):
CommandResult
getKeya
getKey -mc
getKey -m -cc a
getKey -m -c -d16 a
getKey -m -c -a -d16 97
getKey -m -c -kc a 12
getKey -bc 'a'
getKey -b -kcv 12

getTextDimensions ?-float? ?-font dict? ?-width num? string
Return the dimensions of the enclosing box for the string drawn with the given options. The options have the following meaning:
The result is a list of two values corresponding to the width and height of the bounding rectangle.
insertUnicode ?-w win? ?code?
Insert the character corresponding to the specified hexadecimal code-point at the current position. The code argument designates the code-point of the character (not its UTF8 or UTF16 representations). When no code argument is specified, the command is asynchronous: it displays a sheet window and prompts for a code to insert.
lookAt ?-w win? pos ?num?
Return the num characters at position pos of the specified window. The default value for the optional num argument is 1. If there are less than num characters at the given position, the command returns the existing characters.
text subcommand ?-w win? ?options?
Interact programmatically with the text buffer of the specified window. The available subcommands are:
See detailed informations in the [text] reference file.
transcode subcommand ?options?
Perform encoding operations. The available subcommands are:
See detailed informations in the [transcode] reference file.
unicodeNormalize form string
Apply normalization to the Unicode internal representation of a string (as defined in the
Unicode Standard Annex #15). The possible values for the form argument are:
FormCCanonical Decomposition followed by Canonical Composition
FormKCCompatibility Decomposition followed by Canonical Composition
FormDCanonical Decomposition
FormKDCompatibility Decomposition

Selection manipulation and creation


backwardCharSelect ?-w win?
Extend selection one character back.
balance ?-w win?
Select the smallest set of parentheses, braces, or brackets that encloses the current cursor position, i.e. pairs (), {}, and [] (but not <>). Starting from the initial position, the command searches backward until it finds one of the opening 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.
beginningBufferSelect ?-w win?
Extend selection to the beginning of the buffer.
beginningLineSelect ?-w win?
Extend selection to the beginning of the line.
endBufferSelect ?-w win?
Extend selection to the end of the buffer.
endLineSelect ?-w win?
Extend selection to the end of the line.
forwardCharSelect ?-w win?
Extend selection one character forward.
nextLineSelect ?-w win?
Extend selection to the next line.
prevLineSelect ?-w win?
Extend selection to the previous line.
selEnd ?-w win?
Return the end of the hilited selection, or the current insertion point if no text is selected. In the case of a multiple selection, this is the end of the first selected range.
selection subcommand ?-w win? ?options?
This command is used to manipulate single or multiple selections in a text document. The available subcommands are:
See detailed informations in the [selection] reference file.

Pin manipulation and creation


exchangePointAndPin ?-w win?
Exchange the current pin (set with the setPin command) with the current insertion point.
getPin ?-w win?
Return the current pin position in the specified window.
hiliteToPin ?-w win?
Hilite the text from the insertion point to the pin position if there is no selection, otherwise clear the selection.
rectangularHiliteToPin ?-w win?
Create a rectangular selection between the pin position and the insertion point.
setPin ?-w win? ?pos?
Set the pin position to the position specified by the pos argument or to the current insertion point if there is no pos argument.

Clipboard handling


pasteboard subcommand ?options?
Manipulate the standard pasteboards. The available subcommands are:
See detailed informations in the [pasteboard] reference file.

Various textual manipulations


backSpace ?-w win?
Delete selection, or a single char before the current insertion point if no selection.
backwardDeleteWord ?-w win?
Delete word before cursor. If the cursor is in the middle of a word, only the part before the cursor is deleted.
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.
clearUndo ?-w win?
Clear the stack of undoable operations.
deleteChar ?-w win?
If there is a selection delete it, otherwise delete character after cursor.
deleteWord ?-w win?
Delete word after cursor. If the cursor is in the middle of a word, only the part after the cursor is deleted.
downcaseWord ?-w win?
Change 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.
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.
largestPrefix list
Return the longest prefix contained in all strings of list.
oneSpace ?-w win?
Convert white space (any combination of space and tabulation characters) surrounding the insertion point 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.
undo ?-w win?
Undo the last action that has not been undone.
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.

View/insertion interaction


centerRedraw ?-w win?
Redraw window with current line in the middle (if at all possible).
insertToTop ?-w win?
Make the line that the insertion point is on the first line shown. See also the analogous command
[displayPos].
moveInsertionHere ?-w win? ?-last?
Move the insertion point to the first (or last if the
-last option is specified) line displayed.
pageBack ?-w win?
Display previous screenful.
pageForward ?-w win?
Display next screenful.

Dialogs for querying the user


alert ?-w win? ?-t (critical|info|warning)? ?-k okStr? ?-c cancelStr? ?-o otherStr? ?-title titleStr? ?-index? ?--? message ?explanation?
This command will display the message string in a standard alert box. If present, the explanation string will be displayed in the small System font. The options have the following meaning:
If cancelStr or otherStr is an empty string or is not specified, the corresponding button will be omitted. There is always at least one button (it is the default button in the -k position).
By default, the command returns the name of the button that was pressed but, if the
-index option is specified, it returns the button's index (starting at 0 for the rightmost button).
If the -w option is specified, the alert is displayed in a sheet window attached to the window designated by the win argument. Otherwise, the alert is displayed as a modal dialog.
alertnote ?-w win? title ?args?
Display a message in a standard OS X alert box. If more than one argument is given, the first is displayed in boldface, and the remaining arguments are joined by a space and displayed in a smaller font below the first. Otherwise the entire message is in the smaller font. The only button in the alert box is OK and the return value is the empty string.
If the -w option is specified, the alert is displayed in a sheet window attached to the window designated by the win argument. Otherwise, it is displayed as a modal dialog.
buttonAlert ?-w win? ?-title str? ?-index? ?--? text button ?button...?
Create a dialog with an arbitrary number of buttons. One must specify at least one button. The alert's dimensions are calculated automatically depending on the size of the text argument. The
-title option specifies a string displayed in boldface.
If the -w option is specified, the alert is displayed in a sheet window attached to the window designated by the win argument. Otherwise, the alert is displayed as a modal dialog.
By default, the command returns the name of the selected button but, if the
-index option is specified, it returns the button's index (starting at 0 for the rightmost button).
listpick ?options? list
Display a dialog with the list displayed in a table view. 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 are:
-attributes numattributes of the list view
-cancel strtext of the Cancel button
-header listheaders at the top of the list view columns
-height numheight of the dialog
-indicesuse indices rather than names
-lsynonym of -multi (deprecated)
-L lista list of default item(s) to be initially selected
-multiallow multiple items to be selected, return a list
-num numnumber of columns in the list view (default is 1)
-ok strtext of the OK button
-prompt strprompt text at the top of the dialog
-width numwidth of the dialog
--end of options
The
-attributes option takes the same values as the -attr option of the Table View view (see the table of possible values). If the -attributes option is not specified, the command sets the following flags by default: AllowsTypeSelect, UsesAlternatingRowBackgroundColors, AllowsColumnResizing, AllowsEmptySelection. If there is only one column, the NoHeader attribute is also set by default.
If the -num option is specified with value n, the list of items is a list of n-element sublists: each sublist corresponds to the n elements displayed in a row.
If accompanied by -multi, all items in the -L list will be selected, otherwise only the first item is selected.
If the
-indices option is specified, the command returns a list of the indices of the selected items and, in that case, the -L option expects a list of the indices of the default item(s) to be initially selected.
prompt ?-w <win>? ?-width num? ?-lines num? ?-title str? ?--? ?message? ?default? ?menuitem*?
Display a dialog to the user with a message string and an editable field. The default argument specifies a default string for the editable field. If menuitem arguments are specified, the edit field is a combobox containing these items: selection of an item from the popup list inserts it into the editable field. The command returns the value of the editable item. If the Cancel button is selected, the command raises an error. The
-width option lets specify the width in pixels of the dialog window. The -lines option lets specify the number of lines of the edit text (but it is ignored in the case of a combobox). The -title option specifies a title to display in the title bar of the window. The size of the dialog is automatically adjusted to the dimensions of the message string. The -- option indicates the end of the options.
If the -w option is specified, the dialog is run as a sheet attached to the corresponding window. Otherwise, the prompt is displayed as a modal dialog.
showFontPanel
Display the font selection panel. Selecting a font or size from this panel automatically effects the current document window.

Search in a window


findBar subcommand ?-w win? ?options?
Interact with the Find Bar available for each pane in a document window. The available subcommands are:
When the document window is split into several panes, all these subcommands apply to the current pane.
See detailed informations in the [findBar] reference file.
search ?-w win? ?options? pattern pos
Search for pattern starting from position pos. The available options are:
-f (0|1)search backward or forward (default 1)
-r (0|1)pattern is a regular expression (default 0)
-i (0|1)ignore case (default 0)
-m (0|1)match words (default 0)
-l poslimit on how far search goes
-allreturn all matches
-wrapwrap around
-nfailed search returns empty string rather than raising an error
--end of the options
For a literal search (-r 0), one can additionally specify the following:
-di (0|1)diacritics insensitive (default 0)
For a regular expression search (-r 1), one can additionally specify the following:
-d (0|1)allow dot to match any character, including line separators (default 0)
-ml (0|1)allow ^ and $ to match the start and end of lines (default 1)
-u (0|1)treat only \n as a line separator (default 0)
-uts (0|1)use Unicode text segmentation to specify word boundaries (default 0)
-x (0|1)allow spaces and #-prefixed comments in the pattern (default 0)

The pos argument is the first position at which a search may match (whether searching forwards or backwards). The limit argument, if given, is the first position at which a search will not match.
If the search succeeds, a list of two positions will be returned, unless the option
-all was given, in which case the command returns a list of two-element sublists for each correct match. The first element is the starting position of the match, the second is one past the last character. If there is no -n option, an error is thrown if no match was found: it is common practice to wrap this command in a [catch] statement to capture the error.
When the -wrap option is specified, then if the search reaches the end of the window, it wraps around to the beginning and continues searching (similarly when searching backwards, it wraps from beginning to end). Note that 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.
For the syntax of regular expressions, see the
Regular Expressions help file. Note that, by default, the Match Lines option (-ml) is set to 1 for regular expression searches (see the Flag Options section).
The option -di is supported only for literal searches (i-e if the -r option is set to 0). If it is set to 1, diacritic marks are ignored: for example, ö is equal to o.
The options -d, -ml, -u, -uts and -x are meaningful only if the -r option is set to 1. If the -u option is set to 0, all standard line separators are used, otherwise only the Unix line separator \n is used. The -i, -d, -ml, -x options can also be set in the regular expression pattern itself using (?ismx-ismx) directives. The -uts option enables Unicode text segmentation (word boundaries) as defined in the Unicode Standard Annex UAX #29.

Documents


openWindow ?-name str? ?-attributes num? ?-encoding name? ?-geom {l b w h}? ?-text str? ?-bar token? ?-adjust (0|1)? ?-wrap (0|1)?
Open a new window not related to a file on disk. The
-name option specifies the title of the window.
The
-geom option specifies the position and size of the window: its value is a list of four numbers corresponding respectively to the x-coord and y-coord of the bottom left corner in screen coordinates and the width and height.
The
-adjust option is used to automatically adjust the geometry of the window to the screen dimensions. The default value is given by the global preference Force Main Screen.
The
-bar option specifies the token of a toolbar to insert at the top of the window (see the [toolbar] command).
The -wrap option is used to specify soft wrapping: by default, a document is opened without text wrapping.
The
-encoding option specifies the encoding of the new window: this is the encoding which will be used when the window is saved. Its default value is given by the outputEncoding preference.
The
-attributes option controls window and text properties. Its value is a sum of flags with the following meaning:
DescriptionDecimal valuePower of 2
No Toolbar1(1 << 0)
No Dirty State2(1 << 1)
No Vcs Popup4(1 << 2)
No Parse Popup8(1 << 3)
No Marks Popup16(1 << 4)
No Split Handle32(1 << 5)
No Message Bar64(1 << 6)
No Vertical Scrollbar128(1 << 7)
No Horizontal Scrollbar256(1 << 8)
No Close Button512(1 << 9)
No Collapse Button1024(1 << 10)
No Zoom Button2048(1 << 11)
Not Resizable4096(1 << 12)
No Path Control8192(1 << 13)
No Line Numbers16384(1 << 14)
No Coloring32768(1 << 15)
Show Invisibles65536(1 << 16)
Link Detection131072(1 << 17)
Dash Substitution262144(1 << 18)
Data Detection524288(1 << 19)
Quote Substitution1048576(1 << 20)
Text Replacement2097152(1 << 21)
Spelling Correction4194304(1 << 22)
Continuous Spell Checking8388608(1 << 23)
Grammar Checking16777216(1 << 24)
Incremental Searching33554432(1 << 25)
Smart Insert Delete67108864(1 << 26)
By default, the attributes are set to 0.
openFile ?-attributes num? ?-encoding name? ?-geom {l b w h}? ?-bar token? ?-adjust (0|1)? ?-wrap (0|1)? path
Open a text file with path given by the last argument in a new document window. The
-adjust, -attributes, -bar, -geom and -wrap options have the exact same meaning as with the [openWindow] command.
The -encoding option specifies the encoding of the new document: this is the encoding which will be used to read the contents of the file. Its default value is given by the inputEncoding preference.
The command returns the full name of the window (including the copy number if any).
pageSetup ?-w win?
Display the printing Page Setup dialog for the specified window.
print ?-w win? ?-ask (0|1)?
Print the specified window. The
-ask option specifies whether to present the printing dialog giving the user the opportunity to cancel the operation (the default value is 1). If the -ask option is set to 0, the document is printed unconditionally.
revert ?-w win? ?-ask (0|1)?
Revert the file to its last saved version. The
-ask option specifies whether to present an alert dialog giving the user the opportunity to cancel the operation (the default value is 1).
save ?-w win?
Save the specified window. If the window has never been saved before (that is to say is not linked to a file), then this will be re-routed, internally, to the
[saveAs] command.
saveAs ?-w win? ?-file path? ?-encoding enc? ?-ask (0|1)?
Save the specified window with a new name. The
-encoding option specifies the output encoding. The -ask option specifies whether a save panel should be presented to select the target file's location (the default value is 0). The -file option has different meanings depending on the -ask option: On success, the command returns the complete path of the saved file, otherwise it raises an error.

Fonts handling


getFontInfo font ?option?
If an option is specified, return the value for this option. Otherwise return a dictionary of key/value pairs for all the possible options. The currently available options are:
angleamount that the font is slanted in degrees counterclockwise from the vertical
ascendertop y-coordinate, offset from the baseline, of the longest ascender
boundRectunion of the bounding rectangles of every glyph in the font
capHeightcap height of the font
countnumber of glyphs in the font
descenderbottom y coordinate, offset from the baseline, of the longest descender
displayNamename, including family and face, localized for the user's language
familyfamily name
fixedindicates if the font has fixed size
leadingleading of the font
maxAdvancemaximum advancement
namename of the font
renderingrendering mode
sizepoint size of the font
xHeightx-height of the font
The rendering mode returned by the rendering option can have one of the following values:
0Default
1Antialiased
2Integer Advancements
3Antialiased Integer Advancements

getFontList ?-mask num?
If no argument is specified, return the list of available fixed-size fonts. If the
-mask option is specified, the command returns all the fonts corresponding to the specified value (not only fixed-size fonts). The value of this option is an additive value containing some of the following flags:
Italic1
Bold2
Unbold4
Narrow16
Expanded32
Condensed64
Small Caps128
Poster256
Compressed512
Fixed Size1024
If the -mask option is explicitely set to 0 (rather than being unspecified), the command returns the list of all available font families. The following pairs of flags are mutually exclusive: Condensed and Expanded, Bold and Unbold.

Window manager


bringToFront winName
Bring named window to front. The command raises an error if there is no such window.
getGeometry ?-w win? ?-c?
Return a Tcl list of the form {x y w h} where x and y are the x-coord and y-coord of the lower left corner in screen coordinates and w and h are the width and height of the window, including the title bar and the tool bar. If the
-c flag is specified, the command returns the window's content rectangle in screen coordinates.
getMainDevice ?-v?
Return a list containing the x-coord and y-coord of the origin and the width and height of the rectangle defining the main device. If the
-v option is specified, return only the visible frame: in that case, the returned rectangle is always based on the current user-interface settings and does not include the area currently occupied by the dock and menu bar.
getWinInfo ?-w win? (option|all)
Retrieve information about the properties of a document window. The option argument is the name of a property. Supported properties are:
bindtagslist of bind tags
charWidthwidth of a character in the current font
coloringis syntax coloring enabled
colortagslist of color tags
continuousSpellCheckingis continuous spell checking enabled (0|1)
currLinenumber of the first displayed line
dashSubstitutionis automatic dash substitution enabled (0|1)
dataDetectionis automatic data detection enabled (0|1)
dirtydirty state of the window (0|1)
dispRangerange of displayed characters
encodingwindow's encoding
fontwindow's font (specified as a dictionary)
grammarCheckingis grammar checking enabled (0|1)
hasSpuriouswindow has inconsistent end of lines (0|1)
hasURLwindow corresponds to a file (0|1)
incrementalSearchingis incremental searching in FindBar enabled (0|1)
lineHeightheight of a physical line with the current font
lineNumbersdisplay the left margin with line numbers (0|1)
linkDetectionautomatic detection of hyperlinks (0|1)
needsWrapwindow has lines longer than needsWrapColumn preference (0|1)
numColumnslength in chars of the longest line (not including eol)
numDispLinesnumber of displayed lines
numLinesnumber of lines in the document
paneNumindex of the current pane
platformkind of end-of-line symbols (macintosh, unix, windows)
quoteSubstitutionis automatic quotation mark substitution enabled (0|1)
readOnlyis the window in read-only mode (0|1)
recordStateremember the window's state (0|1)
shellis the window in shell mode (0|1)
showInvisiblesdisplay invisible characters (0|1)
smartInsertDeletesmart insertion of space around words (0|1)
spellingCorrectionspelling correction (0|1)
spinis the spinning progress indicator visible (0|1)
splitis the window split in subpanes (0|1)
tabsizesize of tabulations
textReplacementis automatic text replacement enabled (0|1)
toolbarthe token of the window's toolbar (empty string if no toolbar)
undois the undo manager enabled (0|1)
wordbreakword break regular expression
wrapapply soft wrapping (0|1)
If the keyword
all is specified (instead of an option), then all the properties are returned in a dictionary where the keys are the property names.
killWindow ?-w win?
Close the current window, calling preCloseHook, closeHook, etc., as appropriate. If the window is dirty (has unsaved changes), the user is presented a dialog to accept the closure of the window.
mousePos ?-s?
Return the mouse position as a list of two coordinates. If the
-s option is specified, the command returns the position in screen coordinates. Otherwise it returns the position in the coordinate system of the current pane of the currently active window if the mouse is over this pane, or raises an error if it is not (it is common practice to use this command inside a catch command).
moveWin ?-w win? ?-t? xcoord ycoord
Move the specified window. The command positions the bottom-left corner (or the top-left corner if the
-t option is specified) of the window's frame rectangle at given point (xcoord,ycoord) in screen coordinates. The application may constrain the action to ensure the window remains onscreen and below the status bar.
refresh ?-w win?
Redraw the specified window and recolor it. This call is not expensive: it applies to the visible range of the current text pane and invalidates the rest of the document so that recoloring will be performed when necessary.
saveAll ?-f?
Save all currently open windows. If the
-f option is specified, only windows corresponding to a file on disk are saved. This command is not atomic: if saving fails for one of the windows, the command raises an error and the execution is interrupted.
setWinInfo ?-w win? option value ?option value...?
Set properties of document windows. The available options are:
bindtagslist of bind tags
coloringis syntax coloring enabled
colortagslist of color tags
continuousSpellCheckingis continuous spell checking enabled (0|1)
dashSubstitutionis automatic dash substitution enabled (0|1)
dataDetectionis automatic data detection enabled (0|1)
dirtydirty state of the window (0|1)
encodingwindow's encoding
fontwindow's font (specified as a dictionary)
grammarCheckingis grammar checking enabled (0|1)
hasSpuriouswindow has inconsistent end of lines (0|1)
incrementalSearchingis incremental searching in FindBar enabled (0|1)
lineNumbersdisplay the left margin with line numbers (0|1)
linkDetectionautomatic detection of hyperlinks (0|1)
needsWrapwindow has lines longer than needsWrapColumn preference (0|1)
platformkind of end-of-line symbols. Possible values: macintosh, unix, windows.
quoteSubstitutionis automatic quotation mark substitution enabled (0|1)
readOnlyis the window in read-only mode (0|1)
recordStateremember the window's state (0|1)
shellis the window in shell mode (0|1)
showInvisiblesdisplay invisible characters (0|1)
smartInsertDeletesmart insertion of space around words (0|1)
spellingCorrectionspelling correction (0|1)
spinis the spinning progress indicator visible (0|1)
tabsizesize of tabulations
textReplacementis automatic text replacement enabled (0|1)
undois the undo manager enabled (0|1)
wordbreakword break regular expression
wrapapply soft wrapping (0|1)

sizeWin ?-w win? ?-a? ?-c? ?-t? width height
Set the size of the specified window. If the
-c option is specified, the new dimensions apply to the content area (see the [getGeometry] command), otherwise they apply to the entire window structure. The bottom left corner (or the top left corner if the -t option is specified) is left at its current position.
The
-a option installs an animation in order to perform a smooth resize.
toolbar subcommand ?args?
Create and manage toolbars. The available subcommands are:
See detailed informations in the [toolbar] reference file.
winCurrent
Return the full name of the current window, or the empty string if no windows are currently open. For legacy reasons, the library also defines a [win::Current] proc which is an alias for this command.
winNames ?-fullpath? ?-nocount?
Return a list of all open document windows. If the
-fullpath option is specified, complete path names are returned. If the -nocount option is specified, the count suffix n (n = 2,3...) added to duplicate window names is stripped.
The returned list is always arranged according to the front-to-back ordering on the screen.
Note that this command does not take into account the windows created with the
[view] command: use [view list] instead to list these objects.
winPane ?-w win? subcommand ?options?
Create and manipulate subpanes of the specified window. The available subcommands are:
By default, a window is split vertically (stacked panes).
See detailed informations in the [winPane] reference file.
windowVisibility ?-w win? ?-below otherwin? ?(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.
The
-below option is used only with the normal state. It lets you specify another window the window is to be placed behind.

Menu handling


floatMenu subcommand ?options?
Manage floating palettes with buttons corresponding to the items of menus already created with the
[menuRef] command. The available subcommands are:: See detailed informations in the [floatMenu] reference file.
menuBar subcommand
Manipulate the menu bar. The available subcommands are:
See detailed informations in the [menuBar] reference file.
menuItem subcommand ?options?
Manipulate menu items in a menu. The available subcommands are:
See detailed informations in the [menuItem] reference file.
menuRef subcommand ?options?
Create and manipulate menus. The available subcommands are:
See detailed informations in the [menuRef] reference file.

Inter-application communication


executeURL ?-b bundleID? url
Open an URL. This can be a web URL as well as a file URL. The
-b option lets specify the bundle identifier of the application which should be used to open the URL. If it is not specified, the default application declared by the system is used.
switchTo ?(-b | -n | -p | -s) value?
Switch to the specified application. The application can be designated using one of the following options:
OptionDescription
-bbundle identifier
-nname or path of application
-pprocess identifier
-sapplication signature
If the application is not already running, the command will launch it provided it is available on the machine.
If the command is used with no arguments, it activates Alpha itself.

Bindings and codes


binding subcommand ?options?
Create and manipulate keyboard shortcuts. The available subcommands are:
The modifiers are specified as a combination of the following letters:
LetterDescription
cthe Command () key
sthe Shift () key
othe Option () key
zthe Control () key
vto specify a virtual key code
See detailed informations in the
[binding] reference file.
getModifiers
Return the current keyboard modifiers mask. It is a combination of the following base-2 values:
KeyHexadecimalDecimal
ShiftLock0x011
Shift0x022
Control0x044
Option0x088
Command0x1016
NumericPad0x2032
Help0x4064
Function0x80128
The Option modifier is also known as Alternate. The ShiftLock modifier is also known as AlphaShift. The Function modifier corresponds to the fn key (not to be confused with the F1, F2, etc. keys).
linkVar name
Link a Tcl variable name to a preexisting internal variable. This command is mainly used to link an AlphaTcl preference to a C variable defined in the core of the application, so that any changes made to the preference are immediately reflected in the core variable and vice-versa. Note that this link cannot be established only from AlphaTcl: the core itself must already know about the name variable.
prefixBinding ?-infix regex? ?-prompt str?
Build composite bindings. For instance, to create a binding ctrl-a opt-b, one must create a binding for ctrl-a and associate it with this command, then define a binding for opt-b with ctrl-a prefix. See the documentation of the
[binding] command.
The -infix option is used to build composite bindings with an infix so that the user can execute for instance ctrl-a 5 opt-b (here the infix is 5 and means that the action linked to the combo will receive the value 5 as an additional argument which it can interpret in different ways). The value of the -infix option is a regular expression which describes which values are considered an infix: for instance [1-5r] means that the infix could be a digit between 1 and 5 or the letter r.
The
-prompt option is used to provide a string to display in the status bar of the application. If it is not specified, the command displays a default string.
See the
Bindings with an infix section in the reference for the [binding] command.

Graphic interface


displayMode string
Set the text to display as the title of the Mode Info popup button in the document toolbar. Typically it is used internally by AlphaTcl to set this label to the current window's mode (TeX, Html, etc).
displayPlatform string
Set the text to display as the title of the File Info popup button in the document toolbar. This is used internally by AlphaTcl to set the label to Mac, Unix or Windows to reflect the current window's line-endings (Mac = CR, Unix = LF, Windows = CRLF). To change programmatically the line-endings in use for the current window, see the
[setWinInfo] command.
popover subcommand ?options?
Create and manipulate popover windows. The available subcommands are:
See detailed informations in the [popover] reference file.
progressBar subcommand ?options?
Manage the progress bar contained in the status bar of the application. The available subcommands are:
See detailed informations in the [progressBar] reference file.
status subcommand ?options?
The command executes tasks related to the status bar. The available subcommands are:
See detailed informations in the [status] reference file.
view subcommand ?options?
Create and manipulate new kinds of root windows, dialogs, sheet dialogs, palettes and the subviews or widgets (buttons, indicators, lists, menus, etc.) they contain. This is the command used to create and control all the dialogs in the AlphaTcl library. The available subcommands are:
See detailed informations in the [view] reference file.

File System


getDirectory ?-w win? ?-prompt string? ?-multi (0|1)? ?-openPackages (0|1)? ?-showInvisibleFiles (0|1) ?-view token? ?--? ?path?
Display a Get Directory navigation dialog and return the full path name of the selected folder(s), or an error if the Cancel button was selected. An optional path parameter specifies a directory to open the panel in. The other optional parameters have the same meaning as with the
[getFile] command.
getFile ?-w win? ?-prompt string? ?-types typeslist? ?-multi (0|1)? ?-openPackages (0|1)? ?-showInvisibleFiles (0|1)? ?-view token? ?--? ?path?
Display a Get File navigation dialog and return the full path name of the selected file(s), or an error if the Cancel button was selected. The optional path argument specifies a directory to open the panel in.
The
-prompt option specifies a line of text to display in the dialog. The -multi option allows to select multiple files at a time. The -openPackages option specifies whether bundled applications should be seen as folders (to make their contents accessible) or not. The -showInvisibleFiles option specifies whether invisible files should be listed in the dialog. The -types option specifies a list of the file types the user can save the file as: a file type can be a common file extension, or a UTI. The -view option specifies an accessory view: its value is a token obtained with [view create]. The -- parameter indicates the end of the options.
If the -w option is specified, the dialog is displayed in a sheet window attached to the window designated by the win argument. Otherwise, it is displayed as a modal dialog.
getFileInfo path (option|all)
Given a file or folder path, return the information corresponding to the option argument. Available options are:
If the specified argument is all, the command returns a dictionary of key/value pairs for all the possible options. Otherwise, it returns the value corresponding to the specified option.
Note that some options can also be accessed through Tcl commands such as
[file attributes], [file mtime], etc. This command does not resolve aliases or symlinks.
getLocation ?-w win? ?-prompt string? ?-openPackages (0|1)? ?-showInvisibleFiles (0|1)? ?-view token? ?--? ?path?
Display a navigation dialog where the user can specify a parent folder and a name, and return the full path name of the specified object (which does not have to exist necessarily), or an error if the Cancel button was selected. The optional path argument is used to set a default location in the file system and to create a default name displayed for the user. The other optional parameters have the same meaning as with the
[getFile] command.
getStandardFolder ?-create? name ?domain?
Return the full path of certain system-related directories. Possible values for the domain argument are: local, network, system, or user. The default is system. The name argument is a symbolic name designating the requested folder. If the
-create option is specified, the command attempts to create the corresponding folder if it does not exist already (success depends on the permissions).
See detailed informations in the
[getStandardFolder] reference file.
setFileInfo file option value ?option value...?
Set some information for files. Available options are:
Note that many options of this command can also be set through Tcl commands such as
[file attributes], [file mtime] etc.

Debugging


dumpObj ?-f (m|m/n)? ?-S? ?-t? ?-U? vars...
Write the contents of the Tcl_Obj (in memory) corresponding to the specified variables. This command writes the stored UTF-16 bytes (in hexadecimal) and the corresponding string representation (in UTF-8 hexadecimal or in ascii) of all the Tcl_Obj's corresponding to the specified arguments.
The options have the following meaning:
-fformat of hexadecimal string
-Sno UTF-16 representation
-Uno UTF-8 representation
-tadd text representation
--end of options

The value of the
-f option can take the form m or m/n where m is the number of blocks per row and n is the number of characters per block.
Specifying both -S and -U implies the -t option.
This command is useful only for low-level debugging. Here are a few examples displaying the contents of two variables named var1 and var2:
    dumpObj $var1 $var2
    dumpObj -S -U -- $var1 $var2
    dumpObj -f 16/2 -t -S -- $var1 $var2

Media


colorRef subcommand ?options?
Create and manipulate colors. The available subcommands are:
See detailed informations in the [colorRef] reference file.
imageRef subcommand ?options?
Create and manipulate image objects. The available subcommands are:
See detailed informations in the [imageRef] reference file.
movieRef
Create and manipulate movie objects. The available subcommands are:
See detailed informations in the [movieRef] reference file.
soundRef subcommand ?options?
Create and manipulate sound objects. The available subcommands are:
See detailed informations in the [soundRef] reference file.
speech subcommand ?options?
This command interacts with the speech synthesizer. The available subcommands are:
See detailed informations in the [speech] reference file.

Coloring


getEscapes ?-w win? ?(-color|-hypertext|-underline|-strike)?
Return a list of colored, underlined or hypertext sections in the window specified with the -w option (or the current window if -w is not specified). The returned value is a list of lists, each sublist consisting of a start position, an end position and a value which depends on the kind of escapes specified in the last argument:
Only one of the options can be specifed at a time. If the last argument is not specified, it is -color by default.
insertEscapes ?-w win? ?option value...? range
Apply a stylistic marking (color, font style, underlines, etc.) to a range of text. The marking is specified by different options with the following syntax:
-color token
-hypertext proc
-spelling num
-strike num
-style num
-underline num
The
-color option expects a color token (typically obtained with the [colorRef] command).
The -style option specifies a font style. Its value is a combination of the following additive flags:
normal0
italic1
bold2
The
-underline option and the -strike option are used to underline or strike through a range of text. Their value is the sum of two constants specifying respectively the kind of line and the pattern. Possible values are:
KindValue
Single line1
Double line2
Thick line3
PatternValue
Solid0
Dot10
Dash20
Dash-Dot30
Dash-Dot-Dot40
The
-spelling option is a temporary marker used to display spelling indicators for the range of text. The possible values are:
Spelling1
Grammar2
The
-hypertext option attaches a script to execute or an URL to open when the user clicks on the specified range of text. This is useful to create hyperlinks. This option causes the corresponding section to be colored in blue and underlined.
modeColoring subcommand ?args?
This command is used to manipulate syntax coloring schemes. It accepts various subcommands and additional arguments. The available subcommands are:
See detailed informations in the [modeColoring] reference file.
removeEscapes ?-w win? ?options? ?range?
Remove stylistic marking (colors, text styles, underlines, etc.) from a range of text. The kind of marking to remove can be specified using the following options (see the
[insertEscapes] command): -color, -hypertext, -spelling, -strike, -style, -underline. If no option is specified, then all kinds of stylistic marking are removed. If no range is specified, the command applies to the entire window.

Time related


mtime time ?format?
Return date and time strings given a Mac epoch time (i-e a time specified as the number of seconds that have elapsed since Midnight Jan 1, 1904, as typically obtained from the
[now] command).
The optional format argument specifies the format in which the date is displayed. The possible format values are: abbrev, full, long, offset, short, standard. The default value is standard which corresponds to the fixed format YYYY-MM-DD HH:MM:SS. The offset format is like the standard format but also appends the time zone offset. The other formats provide localized date and time using the current locale.
The returned value is a two-elements list: the first element is the date, the second one is the time. To get a single string use the [join] command.
now ?(-unix|-abs)?
Return the current time in seconds. If no argument is specified, it is the number of seconds that have elapsed since Midnight Jan 1, 1904 (aka the Mac epoch): this value is suitable for use with Alpha's
[mtime] command. With the -unix option, it is the number of seconds since January 1 1970 00:00:00 GMT (aka the Unix epoch): this value is suitable for use with Tcl's [file atime] and [file mtime] commands. With the -abs option, it is the time measured in seconds relative to the absolute reference date of Jan 1 2001 00:00:00 GMT.
ticks ?(-m|-n)?
Return the number of ticks since the machine was started. If no option is specified, the value is in milliseconds. With option
-m, it is in microseconds and with option -n in nanoseconds.

Marks


mark subcommand ?-w win? ?args?
Manipulate the marks in the window specified by the -w option. There are two kinds of marks: user marks which are set by the user or the marking procs and are visible in the interface, and temporary marks which are meant to be used programmatically by the packages in order to perform some operations and are not exposed in the interface. Temporary marks are specified with the
-temp option. The available subcommands are: The disp argument is the character position of the start of the first line to be displayed, while pos and end bracket the text to be selected. If pos and end are not specified, they are equal to disp by default; if only end is not specified, it is equal to pos. The -n option means that only mark names are returned, without the associated positions.
See detailed informations in the
[mark] reference file.

Alphabetical Index