Alpha Commands
Alpha
Version:9.2.3 - "Suhail"
Last update:2021-05-21 14:43:28




This document contains information about all the Alpha-specific Tcl commands defined in the core of the application.
It groups the commands thematically. 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 documentation page which is referenced from the syntax window by a hyperlink.
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.
If you are an AlphaTcl developer and you want to migrate old AlphaX code to AlphaCocoa, the following pages may be useful for finding replacements for obsolete or renamed commands : Commands Status and Commands Changes.

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
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.
• alphaUpdate subcommand ?options?
This command manages Alpha's software updates. The following subcommands are available:
• 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:
• 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.
• quit
Quit the application. This call invokes the quitHook.
• 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.
• 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.

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 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:
• 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.
• 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. 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.
• 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.
• 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).
• 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 implements 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
-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).
• 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.

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.
• predicate subcommand ?options?
Create and manipulate predicate objects. The available subcommands are: See detailed informations in the [predicate] 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 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.

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 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.
• 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.
• 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).
• 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).
• 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.
• spellchecker
This command lets you interact with the OS X spell checker to check the spelling in a document window.

Fonts handling


• 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.
• showFontPanel
Display the font selection panel. Selecting a font or size from this panel automatically effects the current document window.

Window manager


• bringToFront winName
Bring named window to front. The command raises an error if there is no such window.
• 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.
• 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.
• 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.
• 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|-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.
• 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 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.
• 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.
• screen subcommand ?options?
Get information about the screens currently connected to the machine. The available subcommands are:
• 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.
• 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)

• 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.
• toolbarItem subcommand ?args?
Create and manage toolbar items. The available subcommands are: See detailed informations in the [toolbarItem] 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? ?(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.

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

Bindings and actions


• 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.
• macroRef subcommand ?options?
Create and manipulate sequences of recorded commands. The available subcommands are: See detailed informations in the [macroRef] 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.

Graphic interface


• 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)? ?-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

• nslog string
Write a string in the system console (for debugging purpose).

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? ?(-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.
• 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

• 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): -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.

Time related


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