Syntax of Alpha's core commands
Alpha
Version:9.2.3 - "Suhail"
Last update:2021-05-21 14:43:28




This page gives access to the syntax of all Alpha's core commands in alphabetical order. There is also an alphabetical index at the end of this page. In the page Alpha Commands, you can find the commands grouped thematically.
A - B - C - D - E - F - G - I - K - L - M - N - O - P - Q - R - S - T - U - W

A


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.
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.
alphaUpdate subcommand ?options?
This command manages Alpha's software updates. The following subcommands are available:
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
Additional information for developers: the method argument can also be the name of any Cocoa method of the NSApplication class that accepts a single nullable argument, like runPageLayout, showHelp. If the method does not exist, it is ignored, otherwise it is invoked with a nil argument.
applescript subcommand ?options?
The command lets you execute AppleScript code from a file or from a text string. See detailed informations in the [applescript] reference file.

B


backSpace ?-w win?
Delete selection, or a single char before the current insertion point if no selection.
backwardChar ?-w win?
Move the insertion point one character back.
backwardCharSelect ?-w win?
Extend selection one character back.
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.
backwardWord ?-w win?
Move the insertion point one word back.
backwardWordSelect ?-w win?
Extend selection one word 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.
beep
Play the system beep.
beginningBufferSelect ?-w win?
Extend selection to the beginning of the buffer.
beginningLineSelect ?-w win?
Extend selection to the beginning of the line.
beginningOfBuffer ?-w win?
Move insertion to the beginning of the buffer.
beginningOfLine ?-w win?
Move insertion to the beginning of the line.
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.
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.
bringToFront winName
Bring named window to front. The command raises an error if there is no such window.
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).

C


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.
centerRedraw ?-w win?
Redraw window with current line in the middle (if at all possible).
clearUndo ?-w win?
Clear the stack of undoable operations.
colorRef subcommand ?options?
Create and manipulate colors. The available subcommands are: See detailed informations in the [colorRef] reference file.
contactRef subcommand ?options?
Manipulate the system-wide Address Book database. See detailed informations in the [contactRef] reference file.
countLines ?-i? str
Return the number of lines contained in a string. This command handles the LF, CR and CRLF symbols correctly, as well as the following Unicode characters: U+0085 (NEXT LINE), U+2028 (LINE SEPARATOR) and U+2029 (PARAGRAPH SEPARATOR).
If the -i option is specified, the command ignores a possible trailing newline symbol.

D


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.
diffFiles ?options? file1 file2
Perform a diff between two regular files. The possible options are:
-bIgnore changes in the amount of white space.
-BIgnore changes whose lines are all blank.
-cReport only diff codes.
-EIgnore changes due to tab expansion.
-iIgnore case differences in file contents.
-lSpecify kind of line endings for the files.
-qOutput only whether files differ.
-tTreat all files as text files.
-wIgnore all white space.
--end of options
The value of the -l option is a list {e1 ?e2?} of one or two integers that specify the kind of line endings used by the files. The possible values are indicated in the next table:
NameValueDescription
Undefined0let Alpha guess
Mac1CR
Unix2LF
Windows3CRLF
If the second value e2 is not specified, it is equal to e1. If the -l option is not specified at all, Alpha attempts to guess.
If the command detects that the files are binary, it raises an error unless option -q or option -t is specified: with -q, the command executes a binary (byte by byte) comparison and tells whether the files differ or not. The -t option forces a textual comparison.
The return value of the command can take three forms:
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.
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.
dumpObj ?-f (m | m/n)? ?-a? ?-r? ?-u? vars...
Write the contents of the Tcl_Obj (in memory) corresponding to the specified variables. By default, this command writes the stored UTF-16 bytes (in hexadecimal) of all the Tcl_Obj's corresponding to the specified arguments. It may also write the corresponding string representation (in UTF-8 hexadecimal).
The options have the following meaning:
-aboth UTF-8 and UTF-16 representations
-fformat of hexadecimal string
-rraw (no headers)
-uUTF-8 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 elements per block. Note that an element corresponds to 4 bytes in UTF-16 and 2 bytes in UTF-8.
If no option -f is specified, then the full string is printed without any spaces.
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 -u -- $var1 $var2
dumpObj -a -r -- $var1 $var2
dumpObj -f 4/2 -- $var1 $var2

dumpViews ?options? (token | win)
Print information about a view's hierarchy of subviews. The last argument is either the token of a view or a root window (typically obtained with the [view create] or [view root] commands respectively), or the name of a document window. This command is useful only for debugging purpose.
This command prints out the entire hierarchy of views (not only the views created by Alpha). Each view is identified by its address in memory.
The options specify which information is requested. Possible options are:
-bprint bounds
-cprint count of subviews
-fprint frame
-kprint token (if any)
-mprint flexibility (autoresizing mask)
-rprint whether the view's coordinate system is flipped
-sstart from superview (if exists)
-tprint tag
-vprint whether the view is visible
If no options are specified, the command prints the count of subviews and the frame by default.

E


endBufferSelect ?-w win?
Extend selection to the end of the buffer.
endLineSelect ?-w win?
Extend selection to the end 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.
exchangePointAndPin ?-w win?
Exchange the current pin (set with the setPin command) with the current insertion point.
executeURL ?-b bundleID? url
Open an URL. This can be a web URL as well as a file URL. The -b option lets you 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.

F


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.
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.
forwardChar ?-w win?
Move insertion one character forward.
forwardCharSelect ?-w win?
Extend selection one character forward.
forwardWord ?-w win?
Move insertion one word forward.
forwardWordSelect ?-w win?
Extend selection one word forward.

G


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:
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.
getEscapes ?-w win? ?(-bgColor|-color|-hypertext|-strike|-tip|-underline)?
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 assumed to be -color by default.
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.
getFont ?-prompt str? ?-sample str? ?-title str? ?-defaut font?
Prompt the user to select a font and a size. The command also displays the system font panel: fonts are selected in the font panel and echoed in the dialog. Press the OK button to end up the selection and validate the choice. The returned value is a font specification (i-e a Tcl dictionary with name and size keys), or an error if the Cancel button was pressed.
The -prompt option specifies a text to display at the top of the dialog. If it is not specified, a default string is used.
The -title option specifies a title for the dialog. By default, there is no title.
The -sample option specifies a string to use as sample text. This sample text is displayed using the currently selected font: each time the user changes the font in the font panel, the sample field is updated.
The -default option specifies a default font to display as a suggestion in the dialog. If it is not specified, the default font preference is used.
getFontInfo font ?option?
If an option is specified, return the value for this option. Otherwise return a dictionary of key/value pairs for all 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
capHeightheight of a capital letter above the baseline
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
xHeightdistance between the baseline and the mean line of lower-case letters
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.
getGeometry ?-w win? ?(-c|-d)?
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 entire window, including title bar and toolbar.
If the -c flag is specified, the command returns the window's content rectangle in screen coordinates. This is the region beneath the toolbar.
If the -d flag is specified, the command returns the window's document rectangle in screen coordinates. This includes the toolbar and the content rectangle.
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

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.
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 screen. The main screen refers to the screen containing the window that is currently receiving keyboard events.
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.
If you need to get the frame dimensions of another screen (in a multi display installation), see the [screen] command.
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).
getPin ?-w win?
Return the current pin position in the specified window.
getPos ?-w win?
Return the current position of the insertion point.
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.
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.
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
bottomBarHeightheight of message bar at bottom of window
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
encodingfile'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)
leftMarginWidthwidth of the line numbers margin
lineHeightdefault line height of a line of text with the current font
lineNumbersdisplay the left margin with line numbers (0|1)
linkDetectionautomatic detection of hyperlinks (0|1)
needsBreakwindow has lines longer than needsBreakColumn 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 of kind shell (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
textContainersize of the bounding rectangle containing the entire text
textFrameframe of the text pane view (including non visible parts) in local coordinates
textReplacementis automatic text replacement enabled (0|1)
toolbarthe token of the window's toolbar (empty string if no toolbar)
topBarHeightheight of control bar (containing popups and path)
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.
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.

I


imageRef subcommand ?options?
Create and manipulate image objects. The available subcommands are: See detailed informations in the [imageRef] reference file.
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:
-bgColor token
-color token
-cursor name
-hypertext proc
-spelling num
-strike num
-style num
-tip str
-underline num
The range argument is a two-element list containing the start and end positions.
The -color and -bgColor options expect 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.
The -tip option attaches a tooltip to the specified range of text. If the cursor hovers over this block of text, a tooltip window appears showing the specified string. Note that the cursor in the text area is an I-beam: the top of the I-beam must be positionned over the block of text for the tooltip window to pop up.
The -cursor option lets you define a mouse cursor to display when the mouse hovers over the specified range of text. Cursors are designated by name. The possible names are given in the following table:
CursorName
arrow
crosshair
IBeam
IBeamHorizontal
closedHand
openHand
pointingHand
resizeDown
resizeLeft
resizeLeftRight
resizeRight
resizeUp
resizeUpDown
contextualMenu
dragCopy
dragLink
operationNotAllowed
disappearingItem

insertToTop ?-w win?
Make the line that the insertion point is on the first line shown. See also the analogous command [displayPos].
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.

K


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.
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.

L


largestPrefix list
Return the longest prefix contained in all strings of list.
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 of the subcommand 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:
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.
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
-truncate strset the truncation mode
-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.
The -truncate option sets the truncation mode used to display items that are too long to fit in the width of the table. It takes the same values as the -truncate option of the Table View view (see the possible values here).
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.

M


macroRef subcommand ?options?
Create and manipulate sequences of recorded commands. The available subcommands are: See detailed informations in the [macroRef] reference file.
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.
matchBrace ?-w win?
Move the insertion point to the character that matches the character after the current insertion point.
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. In both cases, this is the position at which the command should start looking for the matching brace. To be more specific: In both cases, this is the 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 num specifies how many characters to search, starting from the specified position. When looking forward, this restricts the search to the interval [pos,pos+num] if pos+num is less than the length of the text. When looking backwards, this restricts the search to the interval [pos-num,pos-1] if pos-num is ≥ 0.
maxPos ?-w win?
Return the position of the last character in the specified window. This is the number of characters in the window.
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.
minPos ?-w win?
Return the position of the first character in the specified window. This command exists for compatibility reasons. It always returns 0.
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.
mousePos ?(-s|-p|-w)?
Return the mouse position as a list of two coordinates. Depending on the specified option, the position is returned in different coordinate systems:
-sscreen coordinates
-pcurrent pane coordinates
-wwindow coordinates
Option -s is the default. Options -p and -w will raise an error if no window is open.
moveInsertionHere ?-w win? ?-last?
Move the insertion point to the first (or last if the -last option is specified) line displayed.
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.
movieRef
Create and manipulate movie objects. The available subcommands are: See detailed informations in the [movieRef] reference file.
mtime ?-locale str? ?-format str? time ?kind?
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 -locale option lets you specify the locale to use for formatting the date and time strings. If this option is not specified, the current locale of your system is used. The value of this option is a locale identifier using the usual Unix syntax language[_country] (like en, en_US, en_GB, fr_FR, etc.)
The -format option lets you specify a template string containing date format patterns. For full details regarding the patterns syntax, see Unicode Technical Standard #35. Note that the date format components given in the template are arranged appropriately for the specified locale. The returned string may not contain exactly those components given in the template string, but may have locale-specific adjustments applied. Here are some examples using the american and japanese locales respectively:
«» mtime -locale en_US -format EdMMM [now]
Sat, Oct 5
«» mtime -locale ja_JP -format EdMMM [now]
10月5日(土)
Alternatively, the optional kind argument specifies the format in which the date is displayed. The possible format values are: abbreviated, full, long, offset, short, standard. These values may be abbreviated. 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. Here are some examples (using the en_US locale) to demonstrate the different kinds:
abbreviatedOct 5, 2019 1:52:56 PM
fullSaturday, October 5, 2019 1:52:56 PM Central European Summer Time
longOctober 5, 2019 1:52:56 PM GMT+2
offset2019-10-05 13:52:56 GMT+2
short10/5/19 1:52 PM
standard2019-10-05 13:52:56
If the -format option is specified, the kind argument is ignored. If no -format option and no kind argument are specified, the command uses the standard kind.
If the -format option is specified, the returned value is a single string. Otherwise, it is a two-element list: the first element is the date, the second one is the time. To get a single string, use the [join] command.

N


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 implements the down-arrow functionality.
nextLineSelect ?-w win?
Extend selection to the next line.
now ?(-mac|-abs)?
Return the current time in seconds. If no argument is specified, it is the number of seconds that have elapsed since January 1 1970 00:00:00 GMT (aka the Unix epoch): this value is suitable for use with Alpha's [mtime] command and with Tcl's [file atime] and [file mtime] commands.
With the -mac option, it is the number of seconds since Midnight Jan 1, 1904 (aka the Mac epoch). 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.
nslog string
Write a string in the system console (for debugging purpose).

O


oneSpace ?-w win?
Convert white space (any combination of space and tabulation characters) surrounding the insertion point into a single space.
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).
openLine ?-w win?
Insert a new line following the current one and move the insertion point to it.
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 Popup32(1 << 5)
No Info Popup64(1 << 6)
No Mode Popup128(1 << 7)
No Message Bar256(1 << 8)
No Vertical Scrollbar512(1 << 9)
No Horizontal Scrollbar1024(1 << 10)
No Close Button2048(1 << 11)
No Collapse Button4096(1 << 12)
No Zoom Button8192(1 << 13)
Not Resizable16384(1 << 14)
No Path Control32768(1 << 15)
No Line Numbers65536(1 << 16)
No Coloring131072(1 << 17)
Show Invisibles262144(1 << 18)
Link Detection524288(1 << 19)
Dash Substitution1048576(1 << 20)
Data Detection2097152(1 << 21)
Quote Substitution4194304(1 << 22)
Text Replacement8388608(1 << 23)
Spelling Correction16777216(1 << 24)
Continuous Spell Checking33554432(1 << 25)
Grammar Checking67108864(1 << 26)
Incremental Searching134217728(1 << 27)
Smart Insert Delete268435456(1 << 28)
By default, the attributes are set to 0.

P


pageBack ?-w win?
Display previous screenful.
pageForward ?-w win?
Display next screenful.
pageSetup ?-w win?
Display the printing Page Setup dialog for the specified window.
pasteboard subcommand ?options?
Manipulate the standard pasteboards. The available subcommands are: See detailed informations in the [pasteboard] reference file.
$pdfToken subcommand ?options?
This command is generated for each PDFView view created with the [view create PDFView] command. The actual name of the command is the view's token (designated by $pdfToken below). See detailed informations in the [$pdfToken] reference file.
peekEvent ?-mask str? ?-delay num?
This command looks in the events queue for some type of event and executes it. This is useful for intercepting mouse clicks or keyboard events during the execution of a lengthy operation (such as a long while loop).
The -mask option indicates the events you want to allow. Its value is the sum of one or more flags with the following meaning:
EventFlag
Mouse Down1
Key Down2
The default value is 1.
The -delay option specifies a timeout. It indicates how long the command should wait until a requested event occurs. Its value is a floating value corresponding to a duration in seconds (for instance, set it to 0.001 for 1 millisecond). The default value is 0.0 which means that the command will just look if a requested event has been received and will immediately stop waiting. A value -1 on the contrary means waiting without limit.
popover subcommand ?options?
Create and manipulate popover windows. The available subcommands are: See detailed informations in the [popover] reference file.
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. Note that row numbers are 1-based and column numbers are 0-based.
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.
predicate subcommand ?options?
Create and manipulate predicate objects. The available subcommands are: See detailed informations in the [predicate] reference file.
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.
prevLineSelect ?-w win?
Extend selection to the previous line.
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]. The previous position is recorded by the core when a [goto] command is executed, when some text is inserted or deleted, and when the user clicks in another part of the window.
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.
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.
processAsync ?-tag str? ?-priority (1-4)? task ?notification?
This is an experimental command to process some pieces of code asynchronously on a separate thread. The task argument is a Tcl proc to execute asynchronously: the command schedules the task and returns immediately. The notification argument is optional: it specifies the name of another proc to invoke when the task completes successfully.
In case a notification proc is specified, one may also specify a -tag option in order to identify the task: its value can be any token and will be passed as an argument in the notification proc.
The -priority option indicates the priority of the scheduled task. Its value is an integer between 1 and 4 (the default is 3) with the following meaning:
1background priority
2low priority
3default priority
4high priority
Caveats:
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.
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 you specify the width in pixels of the dialog window. The -lines option lets you 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.

Q


quit
Quit the application. This call invokes the quitHook.

R


rectangularHiliteToPin ?-w win?
Create a rectangular selection between the pin position and the insertion point.
redo ?-w win?
Redo the next action that has been undone but not redone.
refresh ?-w win?
Redraw the specified window and re-color it. This call is not expensive: it applies coloring to the visible range of the current text pane and invalidates the rest so that re-coloring of the rest of the document will be performed only when necessary. Note that this command first removes all coloring escapes before recoloring.
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): -bgColor, -color, -cursor, -hypertext, -spelling, -strike, -style, -tip, -underline. If no option is specified, then all kinds of stylistic marking are removed. The range argument (if specified) is a two-element list containing the start and end positions. If no range is specified, the command applies to the entire window.
resourceData ?-w win? (delete|save)
With the save subcommand, this command records some document related informations as file system extended attributes. Currently, the following data are saved: The delete subcommand deletes any previously recorded extended attributes. This removes only the attributes that belong to Alpha (see the table below).
Note that the extended attributes are automatically saved by the core if the recordState property of the document is set to 1 (see the [getWinInfo] and [setWinInfo] commands).
If the -w option is not specified, the command applies to the current window. If the window does not correspond to a file on disk, the command raises an error.
Extended attributes can be manipulated from a Terminal window using the xattr command line tool (see the xattr manual page). The following table gives the extended attribute names used by Alpha:
PropertyAttribute nameType
Encoding"net.sf.alpha.enc" string
Selection"net.sf.alpha.sel" 2 integers
Geometry"net.sf.alpha.geo" 4 floats
TabSize"net.sf.alpha.tab" 1 integer
Font"net.sf.alpha.font" string
Wrapping"net.sf.alpha.wrap" boolean
Line Breaking"net.sf.alpha.break" boolean
The value of the encoding attribute has the form name;value where name is the IANA (Internet Assigned Numbers Authority) name of the encoding and value is the number defined by the Core Foundations framework for this encoding. The selection is recorded as 2 long integers corresponding to the current position and the end of the selection (equal to the current position if the selection is empty). The window geometry is recorded as 4 floating numbers corresponding to the usual {x,y,w,h} format. The tab size attribute is an integer, the font attribute is a string and the wrapping attribute is a boolean value (0 or 1).
restart ?-d delay?
Quit the application and restart. If the user cancels the quit operation (during the review of unsaved documents), then the command is aborted.
The -d option specifies a delay in seconds before restarting. The default value is 2 seconds.
Technically, to perform the restart, Alpha sends an AppleEvent to an internal helper application called AlphaUpdater, then quits. The helper application asks the System, after the specified delay, to launch Alpha.
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 0).
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. Note that row numbers are 1-based and column numbers are 0-based.
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).

S


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.
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.
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.
scanFile ?matching-options? ?-l? ?(-m|-M)? ?(-all|-c|-s)? ?-e enc? ?-f pos? ?-t pos? ?-n? ?--? pattern file
Scan a file for a regular expression. By default, the command returns the index ranges (start and end positions in the file) of the first match found, or raises an error if no match is found. If the -n option is specified, the command returns an empty string rather than raising an error when no match is found.
If the -l option is specified, the command returns line ranges instead of character index ranges. If the -c option is specified, the command returns the count of matches (or the count of matching lines if the -l option is specified).
The -s option tells the command to report only the success status (1 if there is a match, 0 otherwise). The -all option tells the command to return all the matches and not only the first one. The -l, -m, -M and -all options are ignored if the -s option is specified.
The -f and -t options (which stand for from and to respectively) specify start and end positions to perform the search. By default, the command searches the entire file.
If the -m option is specified, the command returns the matches themselves rather than their indices. If it used in conjunction with the -l option, it returns the entire lines that contain the matches.
If the -M option is specified, the command appends the matches to the index or line ranges. The return value in that case is a list of two-element sublists: the first element of each sublist is the character index range (or line range if -l is specified) and the second element is the corresponding match itself (or matching block of lines if -l is specified).
Note that, with the -l option, if a line contains several matches, it is reported only once. The -m and -M options are mutually exclusive. If both were specified, the command raises an error.
The -e option lets you specify the file's encoding. By default, if this option is not specified, the command tries to read the file in UTF-8 encoding: if it fails, it will retry with MacRoman encoding. If that also fails, it tries to guess the encoding. The supported encoding names are the same as for the transcode command: see Encoding Names.
The following switches specify the regular expression's matching options:
-i (0|1)ignore case (default 0)
-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)
This command scans the file on disk, that is to say the file does not have to be edited in Alpha. If you want to match a regular expression in a document window, you should use the search command instead.
screen subcommand ?options?
Get information about the screens currently connected to the machine. The available subcommands are:
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.
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 limlimit 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)
-wi (0|1)width 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 (when searching forwards) or before which (when searching backwards) a search may match.
The limit argument, if given, is the first position at which (when searching forwards) or before which (when searching backwards) a match will be rejected.
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.
The -l option automatically adjusts the limit position so that it does not exceed the end of the document.
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 options -di and -wi are supported only for literal searches (i-e if the -r option is set to 0). If -di is set to 1, diacritic marks are ignored: for example, ö is equal to o. If -wi is set to 1, differences in characters that have full-width and half-width forms are ignored: for example, japanese katakana (Unicode U+30AB) is equal to (Unicode U+FF76).
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.
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.
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.
setGeometry ?-w win? ?(-c|-d)? {x y w h}
Set the dimensions of a window. The dimensions are specified by 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.
The -c and -d options have the same meaning as with the [getGeometry] command.
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.
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.
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)
encodingfile'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)
needsBreakwindow has lines longer than needsBreakColumn 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 of kind shell (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 breakingregular expression
wrapapply soft wrapping (0|1)

shellExec ?-outProc proc? ?-errProc proc? ?-stopProc proc? ?-timeout num? ?-success val? ?-preserve? ?--? scriptPath ?argList?
Execute a shell command synchronously. The scriptPath argument is the full path of the shell script to execute. This path may contain shell symbols like .. or ~. The argList argument is a Tcl list containing the arguments to pass to the shell command.
The -outProc and -errProc options specify Tcl callbacks which will be invoked each time new data is received on the stdout or stderr channels of the shell command respectively. If only -outProc is specified, then the -errProc option is automatically set to the same value. These callbacks are Tcl procs accepting a single argument which represents the received data. The callbacks are optional: if they are not specified, the shellExec command returns the entire output of the executed shell command upon completion.
The -timeout specifies a timeout in seconds. If the elapsed time since the shell command was launched exceeds the timeout, the shell command will receive an interrupt signal. By default, there is no timeout.
The -stopProc option specifies a Tcl proc which is invoked periodically to ask whether the execution should be interrupted. This proc takes no argument and should return 1 to interrupt the execution, or 0 otherwise.
By default, the command succeeds if the shell command terminates with a 0 status (which is usual practice with shell commands). The -success option can be used to specify another value for successful termination. If the termination status differs from the expected success value, the shellExec command raises an error.
The '--' switch indicates the end of the shellExec command's options.
The -preserve option is very technical. Normally, the system applies a Unicode formD decomposition to all the arguments contained in argList. For some command line tools, this can be undesirable. The -preserve option tells the command to keep the arguments verbatim, that is, to pass them as they are, without decomposing.
showFontPanel
Display the font selection panel. Selecting a font or size from this panel automatically effects the current document window.
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.
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.
spellchecker
This command lets you interact with the OS X spell checker to check the spelling in a document window.
status subcommand ?options?
The command executes tasks related to the status bar. The available subcommands are: See detailed informations in the [status] reference file.
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 (integer)
-sapplication signature (four-char code)
If the application is not already running, the command will launch it (provided it is available on the machine). The use of application signatures is deprecated: the -s option is maintained for legacy reasons but should be avoided.
If the command is used with no arguments, it activates (that is to say brings to the front) Alpha itself.
If the command is invoked with only the value argument, the option -n is assumed.
synctex subcommand ?options?
This command manages the TeX synchronizers which allow two-way synchronization between a LaTeX source file and its PDF output. See detailed informations in the [synctex] reference file.

T


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.
$editorToken subcommand ?options?
This command is generated for each TextView view created with the [view create TextView] command. The actual name of the command is the view's token (designated by $editorToken below). See detailed informations in the [$editorToken] reference file.
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.
toolbar subcommand ?args?
Create and manage toolbars. The available subcommands are: See detailed informations in the [toolbar] reference file.
toolbarItem subcommand ?args?
Create and manage toolbar items. The available subcommands are: See detailed informations in the [toolbarItem] reference file.
transcode subcommand ?options?
Perform encoding operations. The available subcommands are: See detailed informations in the [transcode] reference file.

U


undo ?-w win?
Undo the last action that has not been undone.
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

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.
urlComp
This command lets you manipulate the components of an Uniform Resource Locator (URL). The available subcommands are: See detailed informations in the [urlComp] reference file.

W


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.
winExec ?-w win? method
This command executes various high level UI actions concerning document windows. The possible values for the action method are:
deminiaturizeDe-minimize the window
mergeAllWindowsMerge all separate windows into one window that contains multiple tabs
miniaturizeDisplay the minimized window in the Dock
newWindowForTabCreate a new tab (simulates the plus button)
nextTabSelect the next tabbed window
orderBackMove the window to the back of its level
orderFrontMove the window to the front of its level
orderOutHide the window
previousTabSelect the previous tabbed window
tabToNewWindowMove a tabbed window to a separate window
toggleFullScreenTake the window into or out of fullscreen mode
toggleTabBarShow or hide the tab bar
toggleTabOverviewShow or hide the tabs overview grid
toggleToolbarShownShow or hide the toolbar
zoomSimulate the user clicking the zoom box
The orderBack and orderFront methods move the window to the back (resp. the front) of its level in the screen list, without changing either the key window or the main window. If you want to make a window the key window (that is to say the window that receives the keyboard events) when bringing it to the front, use the makeKeyAndOrderFront method.
The toggleTabBar method can be used to show the tab bar in a window that doesn’t have tabs.
Note that some of the action methods are available only in versions 10.12 or greater of Mac OS X: mergeAllWindows, nextTab, previousTab, tabToNewWindow, toggleTabBar. The toggleTabOverview method is available in version 10.13 or greater of Mac OS X. On earlier versions of the system, these methods are no-ops.
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.
windowOrder ?-w <win>? (-above|-below) otherwin
Reposition the window win (or the frontmost window if -w is not specified) relative to otherwin.
With the -above option, the window is ordered immediately in front of otherwin. If otherwin was the current window, then win becomes current window.
With the -below option, the window is ordered immediately behind otherwin. If win was the current window, then the document window that was in second position (whichever it is, not necessarily otherwin) becomes the current window.
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, otherwise it sets the state to the specified value.

Alphabetical Index