Beijing Paradise BBS Backup

home *** CD-ROM | disk | FTP | other *** search

/ Beijing Paradise BBS Backup / PARADISE.ISO / software / BBSDOORW / AUROR21A.ZIP / FUNCTION.DOX < prev next >

Wrap

Text File | 1995-09-01 | 362KB | 8,397 lines

The AML Function Reference ────────────────────────── This Function Reference documents all macro language Statements, Builtin functions, and Library functions. Several editor Extension functions are also documented. For a complete description of the Aurora Macro Language (AML), see the Aurora Macro Language Reference. For information on how to install, configure, and use Aurora, see the Aurora Editor Users Guide. To use the Function Reference within a macro: move the cursor to a function name or statement keyword and press <shift f2>. You can use <shift f2> in any document, including the Language Reference (LANGUAGE.DOX) and the Function Quick Reference (QUICKFUN.DOX). You can also navigate through this document by moving the cursor to the 'see also' keywords and pressing <shift f2>. ────────────────────────────────────────────────────────────────────── Copyright (C) 1995 by nuText Systems. All rights reserved worldwide. No parts of this document may be copied in part or in whole, except as provided in the License in the accompanying documentation. ────────────────────────────────────────────────────────────────────── This document is divided into two sections: 1. Language Statements 2. Functions (builtin functions and library functions) Statements and functions are sorted alphabetically in each section. Statements are indicated by the label [Statement], library functions are indicates by [Lib], and extension functions are indicated by [Ext]. Builtin functions are not labeled. Each library function also displays the object where it is defined (i.e [Lib][edit]). ┌─────────────────────────────────────────────────────────────────────┐ │ Language Statements │ └─────────────────────────────────────────────────────────────────────┘ break [Statement] ────────────────────────────────────────────────────────────────────── remarks: The 'break' statement will force an unconditional exit from 'loop', 'repeat', and 'while' loops. returns: nothing see also: loop, repeat, while example: loop keycode = getkey case keycode when <esc> // <esc> exits the loop break otherwise say "you pressed " + (getkeyname keycode) end end case [Statement] ────────────────────────────────────────────────────────────────────── format: case case_expr when when_expr expressions when when_expr, when_expr, when_expr expressions . . otherwise expressions end / endcase The 'otherwise' clause is optional. remarks: The 'case' statement evaluates 'case_expr', and then evaluates each 'when' expression in order, until one is found whose value is equal to the value of 'case_expr'. If a matching 'when' expression is found, the expressions associated with the 'when' statement are evaluated. Multiple 'when' expressions (separated by commas) may be specified within a single 'when' clause. If no matching 'when' expressions are found, then the 'otherwise' clause (if present) is evaluated. returns: The value of the last expression evaluated in the 'when' or 'otherwise' clause. see also: if, if? example: case value when 1 say "value is one" when 3, 7 say "value is three or seven" when "abc" + "d" say "value is abcd" otherwise say "value is " + value end value = case value when 1 "one" when 2 "two" otherwise "undefined" end databuf [Statement] ────────────────────────────────────────────────────────────────────── format: databuf buffer . . end / enddatabuf remarks: This statement creates a new buffer and initializes the buffer with data, or adds data to the end of an existing buffer. 'buffer' specifies the bufferid. Each expression listed within the databuf-end group becomes a separate line in the buffer. At least one line is required. This statement is generally used to define an 'inline' data buffer in a macro, without requiring a separate file to be loaded. returns: nothing see also: createbbuf, createbuf, destroybuf example: databuf "abc" // bufferid 'abc' "first line" // 1st line x + 5 - y // 2rd line y // 3th line "a string" // 4th line end define [Statement] ────────────────────────────────────────────────────────────────────── format: define . . end / enddefine remarks: This statement defines a section of macro code which is executed at compile-time. No object code is generated for any expressions contained within the define-end group. Any functions defined within the define-end group are evaluated at compile time when called. Similarly, object variables which are assigned values within the define-end group are treated as constants when referenced outside the define-end group. returns: nothing see also: forward, function, include, set, var forward identifier [Statement] ────────────────────────────────────────────────────────────────────── remarks: This keyword defines the specified identifier as a function name. If a function is called before it is defined with the 'function' statement, the 'forward' keyword must be used to inform the compiler that the identifier is a function name. returns: nothing see also: function, key, var function [Statement] ────────────────────────────────────────────────────────────────────── format: function functionname (arg1 arg2 ...) . . end / endfunction remarks: This statement defines a function in the current object with the name 'functionname'. Expressions contained within the function definition will be evaluated when the function is called. Function arguments can be referenced as variables within the function by listing them within parentheses after the function name. Note that arguments can also be referenced with the 'arg' function (see the 'arg' function). returns: nothing see also: arg, forward, key example: function hello (name) say "Hello " + name + '!' end if [Statement] ────────────────────────────────────────────────────────────────────── format: if if_expr then expressions elseif elseif_expr then expressions . . else expressions end / endif The 'elseif' and 'else' clauses are optional. The keyword 'then' is also optional, but may make the statement easier to read. remarks: The 'if' statement evaluates the expression 'if_expr'. If the value is TRUE (not zero and not null), then the expressions in the 'if' clause are evaluated. If the value is not TRUE, then the expression 'elseif_expr' is evaluated. If the value is TRUE, then the expressions in the 'elseif' clause are evaluated, otherwise the expressions in the 'else' clause (if present) are evaluated. Multiple 'elseif' clauses may be specified. returns: The value of the last expression evaluated in the 'if', 'elseif', or 'else' clauses. see also: case, if? if? if_expr then_expr else_expr [Statement] ────────────────────────────────────────────────────────────────────── remarks: The 'if?' statement is a shorter form of the 'if' statement (see the 'if' statement'). The keywords 'then', 'elseif', and 'else' are not used. The expression 'else_expr' is optional. The 'if?' statement is primarily intended for use within expressions, where it may be more convenient than the 'if' statement. returns: The value of 'then_expr' or 'else_expr'. see also: case, if example: string1 = if? a == 1 "a is one" "a is not one" key [Statement] ────────────────────────────────────────────────────────────────────── format: key <key or event> (arg1 arg2 ...) . . end / endkey The 'end' keyword is not required if this statement is followed by another 'key' or 'function' statement. remarks: This statement defines an keyboard event handling function in the current object with for the event name: <key or event>. Expressions contained within the function definition will be evaluated whenever the event is is sent to the current object. Function arguments can be referenced as variables within the function by listing them within parentheses after the function name. Note that arguments can also be referenced with the 'arg' function (see the 'arg' function). For all keyboard events generated by the editor except <char>, a keycode is passed as the first argument. The <char> event handling function is passed the ASCII character entered as the first argument, and the keycode as the second argument. returns: nothing see also: arg, forward, function example: key <ctrl c> (keycode) say "you pressed <ctrl c>, keycode=" + keycode end keyword keyword1, keyword2, ... [Statement] ────────────────────────────────────────────────────────────────────── remarks: This statement inserts 'keyword1', 'keyword2', etc. as syntax highlighting keywords in the current (executing) object. The keywords must be separated by commas. Syntax highlighting keywords are stored as object variables whose value is the keyword color. If the value is null, then the keyword color defined in the 'syntax' function is assumed. The 'keyword' statement always assigns a value of null to the object variable. returns: nothing see also: setsyntax, syntax example: see the configuration file SYNTAX.AML include expression [Statement] ────────────────────────────────────────────────────────────────────── remarks: This statement includes the macro language file defined by 'expression' at the current source code location. The specified expression is always evaluated at compile time. Any user-defined variables or functions referenced within the expression must have been previously defined within a 'define-end' group. This statement will include both macro source (.AML) files and compiled macro (.X) files. returns: nothing see also: define example: include "d:\\macros.aml" include drive + path + filename loop [Statement] ────────────────────────────────────────────────────────────────────── format: loop expressions end / endloop remarks: The 'loop' statement evaluates 'expressions' repeatedly until a 'break' or 'return' statement is encountered. returns: nothing see also: break, repeat, return, while menu [Statement] ────────────────────────────────────────────────────────────────────── format: menu menuname item description1 expressions1 item description2 expressions2 . . end / endmenu remarks: This statement creates a new menu buffer with the bufferid 'menuname'. 'description1', 'description2', etc. are the text strings associated with each item on the menu. Each description may contain one ampersand character (&) indicating that the character following it is to be highlighted. 'expressions1', 'expressions2', etc. are macro expressions to be associated with the menu items. These expressions can be retrieved and evaluated when a menu item is selected (see the 'getmenu' function). returns: The new menu bufferid if successful, otherwise null. see also: asciibuf, createbbuf, destroybuf, loadbuf, menubar, popup example: menu "Colors" item "&Red" say "you selected red" item "&Green" say "you selected green" item "&Blue" say "you selected blue" end menubar [Statement] ────────────────────────────────────────────────────────────────────── format: menubar window bar[1-4] item description1 expressions1 item description2 expressions2 . . end / endmenubar remarks: This statement creates or changes a menu bar for a window. If 'window' is null, then the current window is assumed. 'description1', 'description2', etc. are the text strings associated with each item on the menu bar. Each description may contain one ampersand character (&) indicating that the character following it is to be highlighted. If a pair of ampersand characters (&&) is specified, the character is highlighted with the window title bar control color. 'expressions1', 'expressions2', etc. are macro expressions to be associated with the menu bar items. These expressions can be retrieved and evaluated when a menu bar item is selected (see the 'getmenubar' function). Up to four menu bars can be defined for one window. 'bar' specifies which of the four menu bars is being defined, and can be one of the following values: 1 - the primary menu bar at the top of the window, under the north title bar (if any) 2 - menu bar 2 directly underneath the primary menu bar 3 - menu bar 3 directly underneath menu bar 2 4 - menu bar 4 at the bottom of the window, above the south title bar (if any) If 'bar' is null, then 1 is assumed. returns: TRUE if successful, otherwise null. see also: getmenubar, menu example: menubar '' 1 // primary menu bar item "&Red" say "you selected red" item "&Green" say "you selected green" item "&Blue" say "you selected blue" end object [Statement] ────────────────────────────────────────────────────────────────────── format: object objectname ( parent1 parent2 ... ) The inheritance list (parent1 parent2 ...) is optional. remarks: This statement changes the current (executing) object to 'objectname'. If the object does not exist, then it is created. If the inheritance path '(parent1 parent2 ...)' is specified, then the object will inherit functions and object variables from the objects 'parent1', 'parent2', etc. The 'object' statement can not be used within the scope of the 'function' statement. returns: nothing see also: destroyobject, function, getcurrobj, inheritfrom, inheritkeys, object? example: object abc // makes 'abc' the current object (and creates it // if it doesn't exist) object abc (def xyz) // makes 'abc' the current object (and creates it // if it doesn't exist). 'abc' will inherit // code and data from objects 'def' and 'xyz' ref variable [Statement] ────────────────────────────────────────────────────────────────────── remarks: The 'ref' keyword can be used to return more than one value from a function. When 'ref' is specified immediately before a local or global variable in a function call, it indicates that the variable is to be passed 'by reference' to the function. If the variable is modified in the called function, it is also modified where it was called. returns: nothing example: function modify (c d) c = 13 d = 14 end function callmod a = 1 b = 2 modify ref a ref b return a + b // returns 27 end repeat [Statement] ────────────────────────────────────────────────────────────────────── format: repeat expressions until until_expr remarks: The 'repeat' statement evaluates 'expressions' repeatedly until the value of the expression 'until_expr' is TRUE (not zero and not null). 'until_expr' is tested after the first iteration of the loop. The 'break' or 'return' statements can be used to force an exit from the loop. returns: null see also: break, loop, return, while example: var i repeat // counts from 0 to 9 say "i is " + i delay 500 i = i + 1 until i == 10 return expression [Statement] ────────────────────────────────────────────────────────────────────── remarks: This statement returns the value of 'expression' immediately and unconditionally to the calling function. returns: the value of the specified expression. example: return "The value is: 13" // returns a string return 6 + 7 // returns 13 return // returns the null string set variable expression [Statement] ────────────────────────────────────────────────────────────────────── remarks: Assigns the value of 'expression' to an object variable in the current (executing) object. Leading underscores are ignored. returns: nothing see also: function?, lookup, setobj, setx, setxfun, setxobj, unsetx example: set Two 2 set _Two 2 // underscore is ignored set number 1 + 2 + x - 4 set abc_string 'a' + b + 'c' set "A variable" 2 setobj variable expression objexpression [Statement] ────────────────────────────────────────────────────────────────────── remarks: Assigns the value of 'expression' to an object variable in the object defined by 'objexpression'. An object must be specified returns: nothing see also: function?, lookup, set, setx, setxfun, setxobj, unsetx example: setobj Two 2 "edit" setobj Two 2 "ed" + "it" setx varexpression expression [Statement] ────────────────────────────────────────────────────────────────────── remarks: Assigns the value of 'expression' to an object variable defined by 'varexpression' in the current object. returns: nothing see also: function?, lookup, set, setobj, setxfun, setxobj, unsetx example: setx "FourTeen" 14 setx "Four" + "Teen" 8 + 6 // assigns 14 to the object // variable "FourTeen" variable = "Fourteen" // assigns 14 to the object setx variable 14 // variable "FourTeen" setxfun funexpression expression objexpression [Statement] ────────────────────────────────────────────────────────────────────── remarks: Changes the function definition of the function 'funexpression' in the object 'objexpression' to the macro source code in the string 'expression'. An object must be specified. This statement can be used to change the definition of a function to macro source code which is not known at compile-time. returns: nothing see also: function?, lookup, set, setobj, setx, setxobj, unsetx example: setxfun "<ctrl d>" "beep 400 400" "edit" // assigns the macro code 'beep 400 400' to <ctrl d> // in the object 'edit' setxobj varexpression expression objexpression [Statement] ────────────────────────────────────────────────────────────────────── remarks: Assigns the value of 'expression' to an object variable defined by 'varexpression' in the object defined by 'objexpression'. An object must be specified. returns: nothing see also: function?, lookup, set, setobj, setx, setxfun, unsetx example: setxobj "Four" + "Teen" 8 + 6 "edit" // assigns 14 to the object variable 'Fourteen' in // the object 'edit' var identifier [Statement] ────────────────────────────────────────────────────────────────────── remarks: This keyword defines the specified identifier as a variable name, and initializes it to zero when entering a macro or function. If a variable is referenced before it is assigned a value (and not referenced in a function argument list), then this keyword must be used to inform the compiler that the specified identifier is a variable name. returns: nothing see also: forward example: function count (b) var a while a < b do a = a + 1 end end while [Statement] ────────────────────────────────────────────────────────────────────── format: while while_expr do expressions end / endwhile The keyword 'do' is optional, but may make the statement easier to read. remarks: The 'while' statement evaluates 'expressions' repeatedly while the expression 'while_expr' is TRUE (not zero and not null). 'while_expr' is tested before the first iteration of the loop. The 'break' or 'return' statements can be used to force an exit from the loop. returns: null see also: break, loop, repeat, return ┌─────────────────────────────────────────────────────────────────────┐ │ Functions │ └─────────────────────────────────────────────────────────────────────┘ about [Lib][a] ────────────────────────────────────────────────────────────────────── remarks: Displays an about box with the editor version, and the date and time. returns: The button pressed (Ok), or null if nothing was pressed. see also: finddlg, repldlg, scandlg addhistory historybuffer string [Lib][a] ────────────────────────────────────────────────────────────────────── remarks: Adds 'string' to the specified history buffer and makes it the most recently used history string. The history buffer is created if it does not exist. returns: nothing see also: askhistory, gethiststr, pophistory example: addhistory "_load" "C:\\FILE.TXT" // adds C:\FILE.TXT to the history buffer '_load' addhistory "_find" "apples" // adds 'apples' to the history buffer '_find' addline string col row buffer ────────────────────────────────────────────────────────────────────── remarks: Inserts a new line containing the specified string into a buffer. This function is almost identical to the 'insline' function, except that new lines are added to the end of the buffer if 'row' is not specified (see 'insline'). returns: TRUE if successful, otherwise null. see also: delline, insline, insabove, joinline, splitline example: addline // adds a new blank line to the end of the // current buffer addline "Last line" // adds a new line with the text 'Last line' // after the last line in the current buffer adjustcol col window ────────────────────────────────────────────────────────────────────── remarks: Scrolls a window left or right relative to the position of the cursor in the window. If 'window' is not specified, the current window is assumed. This function does not move the cursor in the buffer. The window is scrolled so that the cursor appears 'col' minus 1 columns from the left edge of the client area. If 'col' is not specified, the window is scrolled to a position that leaves the cursor in the vertical center of the window. returns: nothing see also: adjustrow example: adjustcol // attempts to scroll the window so that the cursor // is vertically centered in the window. adjustcol 3 // attempts to scroll the window so that the cursor // is 3 columns from the left edge of the window adjustrow row window ────────────────────────────────────────────────────────────────────── remarks: Scrolls a window up or down relative to the position of the cursor in the window. If 'window' is not specified, the current window is assumed. This function does not move the cursor in the buffer. The window is scrolled so that the cursor appears 'row' minus 1 lines from the top edge of the client area. If 'row' is not specified, the window is scrolled to a position that leaves the cursor in the horizontal center of the window. returns: nothing see also: adjustcol example: adjustrow // attempts to scroll the window so that the cursor // is horizontally centered in the window. adjustrow 3 // attempts to scroll the window so that the cursor // is 3 rows from the top edge of the window actualrow (+/-)lines row buffer ────────────────────────────────────────────────────────────────────── remarks: This function returns the actual line number which is the apparent distance on the screen of 'lines' lines away from the specified row. If 'buffer' is null or not specified, then the current buffer is assumed. If 'row' is not specified, then the line at the cursor is assumed. returns: A line number if successful, otherwise null. see also: apparentrow, fold?, getfold example: actualrow -5 // returns the line number which appears to be 5 // lines above the current line on the screen apparentrow (+/-)lines row buffer ────────────────────────────────────────────────────────────────────── remarks: This function returns the apparent line number on the screen which is the actual distance of 'lines' lines away from the specified row. If 'buffer' is null or not specified, then the current buffer is assumed. If 'row' is not specified, then the line at the cursor is assumed. returns: A line number if successful, otherwise null. see also: actualrow, fold?, getfold example: apparentrow 5 // returns the apparent line number on the screen // of the line 5 lines below the current line arg n ────────────────────────────────────────────────────────────────────── remarks: Retrieves the 'nth' argument, or the number of arguments passed to the currently executing function. If 'n' is zero or not specified, then the number of arguments is returned, otherwise the 'nth' argument is returned. returns: A function argument or the number of function arguments. see also: function, key example: function abc say (arg) + " args passed, first arg is: " + (arg 1) end abc 1 2 3 // displays: '3 args passed, first is: 1' asciibuf buffer ────────────────────────────────────────────────────────────────────── remarks: This function creates a new buffer containing an ASCII chart with 256 lines - one for each ASCII character. The new buffer will become the current buffer. If 'buffer' is null or not specified, a unique bufferid will be assigned. Note: this function will not display the new buffer in a window. The 'popup' or 'openbuf' library functions should be used to display the buffer. returns: The new bufferid if successful, otherwise null. see also: asciibuf, createbbuf, destroybuf, loadbuf, menu, openbuf, popup ask prompt history init title opt=[c12d] width [Ext][a] ────────────────────────────────────────────────────────────────────── remarks: Prompts the user to enter a string. The following parameters may be specified: prompt - the prompt displayed to the user history - the history buffer to use in the prompt init - the initial value to place in the prompt title - the prompt title (dialog boxes only) width - the prompt width (dialog boxes only) The following 'prompt style' options may also be specified: c - command line prompt 1 - one-line box prompt 2 - two-line box prompt d - dialog box prompt If no options are specified, the value of 'PromptStyle' in CONFIG.AML is used as the default prompt style. If a history bufferid is specified and does not already exist, then it is created. Note that entered strings are not automatically added to the history buffer (the 'addhistory' function must be used). returns: This function returns the string entered. If nothing is entered and the <enter> key is pressed, then one blank (ASCII 32) is returned. If the prompt is cancelled, then null is returned. see also: addhistory, askfile, okbox, popup, repldlg, scandlg, yncbox example: ask "Enter a string" // prompts for a string ask "Enter a file name" "_load" "C:\\FILE.TXT" // prompts for a string, initializing the prompt with // C:\FILE.TXT. The "_load" history buffer is // available within the prompt ask "Enter a string" '' "initial string" "Enter" 'd' 20 // prompts for a string using a dialog box prompt of // width 20 with the title 'Enter". The prompt // is initialized with "initial string". askbox refvalue prompt history init [Lib][a] ────────────────────────────────────────────────────────────────────── remarks: Prompts the user to enter a string in a 2-line box prompt. The following parameters may be specified: refvalue - the variable to hold the return string prompt - the prompt displayed to the user history - the history buffer to use in the prompt init - the initial value to place in the prompt If a history bufferid is specified and does not already exist, then it is created. Note that entered strings are not automatically added to the history buffer (the 'addhistory' function must be used). returns: TRUE if a string was entered, or null if the prompt was cancelled. The user string is returned in the variable 'refvalue' (passed by reference). see also: addhistory, ask, askbox1, askline example: var value // prompt for a string if askbox ref value "File name?" _load "FILE.TXT" then // user string is returned in 'value' msgbox "You entered " + value end askbox1 refvalue prompt history init [Lib][a] ────────────────────────────────────────────────────────────────────── remarks: Prompts the user to enter a string in a 1-line box prompt. The parameters and return values are identical to the 'askbox' function. returns: see askbox. see also: ask, askbox, askline askfile filespec title sortoptions fmgroptions bufname [Lib][a] ────────────────────────────────────────────────────────────────────── remarks: Displays a file selection menu based on 'filespec'. The following parameters can be specified: title - the menu title sortoptions - One of the following sort options can be specified: d - file date/time (descending) e - file extension n - file name o - DOS default order s - file size (descending) If no options are specified, the setting 'FmgrSort' in CONFIG.AML is assumed. fmgroptions - One of the following options can be specified: d - show subdirectories h - show hidden & system files k - show file sizes in 1k increments 1 - show directories first when sorting by name If no options are specified, the setting 'FmgrOpt' in CONFIG.AML is assumed. bufname - A buffer name to be used for the menu. If a buffer name is specified, the menu will 'remember' its window and cursor positions, and associate them with the buffer name. returns: The selected file or directory, or null if nothing was selected. see also: popup example: askfile "C:\\*.*" "Select a file" // displays a file selection menu for the C drive askfile "C:\\*.*" "Select a file" 's' 'dk' // displays a file selection menu for the C drive, // sorted by file size. The menu will show // subdirectories, and file sizes in 1k increments askhistory [Lib][prompt] ────────────────────────────────────────────────────────────────────── remarks: Displays a history popup menu for the current prompt. If a string is selected, it is entered automatically into the prompt. This function is only for use within prompts. returns: The string selected from the popup menu, or null if nothing was selected or the history buffer does not exist. see also: pophistory askline refvalue prompt history init [Lib][a] ────────────────────────────────────────────────────────────────────── remarks: Prompts the user to enter a string in a command-line prompt. The parameters and return values are identical to the 'askbox' function. returns: see askbox. see also: ask, askbox, askbox1 assignkey [Lib][mon] ────────────────────────────────────────────────────────────────────── remarks: Assigns the current scrap key macro to a key. The user is prompted to enter the key. If the key macro is assigned, the scrap macro is erased. Note: key macros cannot be assigned to multi-keys with this function. returns: nothing see also: assignkey, openkey, playing?, savekey, setting base number newbase ────────────────────────────────────────────────────────────────────── remarks: Converts a decimal or hexadecimal number to a string representing a number of any base from 2 to 36. returns: a string representing the number in base 'newbase'. see also: bin2hex, hex2bin example: base 45 16 // returns "2D" base 45 8 // returns "55" base 45 2 // returns "101101" beep frequency milliseconds ────────────────────────────────────────────────────────────────────── remarks: Beeps the PC speaker at the specified frequency (in Hz) for the specified number of milliseconds. If 'milliseconds' is omitted, the speaker will sound indefinitely until the next call to this function. If no arguments are passed to this function, then the speaker is turned off. returns: nothing see also: delay example: beep 500 1000 // beeps at 500Hz for 1 second beep 800 // beeps at 800Hz indefinitely beep // turns sound off begdesk [Lib][a] ────────────────────────────────────────────────────────────────────── remarks: Clears the current desktop and marks the beginning of a series of window 'close' calls which add each closed window to the current desktop. This would typically be used for exiting the editor and saving all open windows as the current desktop. returns: nothing see also: close, enddesk bin2hex binarystring ────────────────────────────────────────────────────────────────────── remarks: Converts a binary string into a string representing its hexadecimal value returns: a hexadecimal string. see also: hex2bin example: bin2hex 'a' // returns "61" bin2hex 'abc' // returns "616263" bin2int binarystring ────────────────────────────────────────────────────────────────────── remarks: Converts 1, 2, or 4 byte binary strings into integers. returns: an integer. see also: char, char2, char4 example: bin2int 'a' // returns 97 bin2int 'ab' // returns 25185 bin2int 'abcd' // returns 1684234849 blink [0/1] ────────────────────────────────────────────────────────────────────── remarks: Enables (1) or disables (0) the video blink mode. Disabling the video blink mode allows the brighter background colors (128-255) to be used. returns: nothing see also: display bootpath filename ────────────────────────────────────────────────────────────────────── remarks: Converts an unqualified or partially qualified filename into a fully-qualified filename based on the editor 'bootpath' (the location of the main editor .EXE file). returns: a fully qualified filename or directory specification. see also: getbootpath, qualify example: bootpath "KBD.AML" // returns C:\AURORA\KBD.AML if 'C:\AURORA' is the // editor bootpath bufchanged? buffer ────────────────────────────────────────────────────────────────────── remarks: Tests if a buffer is modified by checking the buffer 'modified' flag. If 'buffer' is null or not specified, the current buffer is assumed. returns: non-zero if the buffer is modified, otherwise null. see also: bufchanged?, bufferflag buffer? buffer ────────────────────────────────────────────────────────────────────── remarks: Tests if a buffer exists. If 'buffer' is null or not specified, the current buffer is assumed. returns: TRUE if the buffer exists, otherwise null. see also: trunc? bufferflag opt=[cdmr-] buffer ────────────────────────────────────────────────────────────────────── remarks: Turns buffer flags on or off. If 'buffer' is null or not specified, the current buffer is assumed. The following flags can be specified: d - process 'dirty' or modified lines m - buffer 'modified' flag r - buffer read/only (protected) flag - - turns off flags If option '-' is specified, any other specified flags will be turned off, otherwise all specified flags will be turned on. The following option can also be specified: c - clear all 'dirty' or modified lines returns: nothing see also: bufchanged?, bufferflag?, lineflag, lineflag? example: bufferflag "-m" // turn off the buffer-modified flag bufferflag "c" // clear all modified lines bufferflag "r" // make current buffer read/only bufferflag? opt=[dmr] buffer ────────────────────────────────────────────────────────────────────── remarks: Tests if buffer flags are on. If 'buffer' is null or not specified, the current buffer is assumed. The following flags can be specified: d - process 'dirty' or modified lines m - buffer 'modified' flag r - buffer read/only (protected) flag returns: non-zero if any of the specified buffer flags are ON, otherwise null. see also: bufchanged?, bufferflag example: bufferflag? "m" // returns non-zero if the current // buffer has been modified button title x y width height [Lib][a] ────────────────────────────────────────────────────────────────────── remarks: Adds a button window control to the current dialog box. The button window becomes the current window. The following parameters may be specified: title - the button title x - the button x-position in the dialog box y - the button y-position in the dialog box width - the button width (if not specified, the button is sized to accomodate the title) height - the button heigth (if not specified, the button height is 1) returns: The button window id. see also: field, dialog, groupbox, listbox, whenenter example: dialog "Test Dialog Box" 40 5 // create a dialog box button "O&k" 18 2 8 // add a button getdialog // display the dialog box button? buttonmask ────────────────────────────────────────────────────────────────────── remarks: Tests if the specified mouse button(s) are currently pressed down. 'buttonmask' can be any combination of the following values OR'ed together (bitwise): 01h - left button is down 02h - right button is down 04h - center button is down If 'buttonmask' is not specified, then 07h is assumed. returns: Non-zero if the specified button keys are down, otherwise zero. example: button? // test if any mouse buttons are down button? 2 // test if the right mouse button is down call funexpression arg1 arg2 ... ────────────────────────────────────────────────────────────────────── remarks: Calls a function in the current object whose name is the value of 'funexpression', passing the arguments 'arg1', 'arg2', etc. returns: The return value of 'funexpression'. see also: eval, pass, send, sendobject example: call "beep" 400 400 call "be" + "ep" 400 400 cascade [Lib][win] ────────────────────────────────────────────────────────────────────── remarks: Cascades all non-minimized windows on the screen. returns: nothing see also: splitwin, tile caseblock opt=[lu] mark ────────────────────────────────────────────────────────────────────── remarks: Changes the case of marked text. If 'mark' is not specified, then the default markid is assumed. Any combination of the following options may be specified: l - change text to lower case u - change text to upper case If options 'l' and 'u' are both specified, the case of each character in the mark is toggled. If no options are specified, then 'u' is assumed. returns: TRUE if successful, otherwise null. see also: flipcase, locase, upcase char number1 number2 ... ────────────────────────────────────────────────────────────────────── remarks: Converts its numeric arguments to 1 byte character strings whose ASCII value is the numeric argument. returns: The concatenated string of all arguments converted to 1 byte strings. see also: bin2int, char2, char4 example: char 97 // returns "a" char 65 66 67 // returns "ABC" char2 number1 number2 ... ────────────────────────────────────────────────────────────────────── remarks: Converts its numeric arguments to 2 byte binary character strings. returns: The concatenated string of all arguments converted to 2 byte strings. see also: bin2int, char, char4 example: char2 6261h // returns "ab" char4 number1 number2 ... ────────────────────────────────────────────────────────────────────── remarks: Converts its numeric arguments to 4 byte binary character strings. returns: The concatenated string of all arguments converted to 4 byte strings. see also: bin2int, char, char2 example: char4 64636261h // returns "abcd" chgfileattr filename attributes=[ahrs] ────────────────────────────────────────────────────────────────────── remarks: Changes the attributes of the file 'filename'. Any of the following attributes can be specified: a - archive h - hidden r - read-only s - system null - no attributes returns: Non-zero if successful, otherwise zero. see also: fileattr? example: chgfileattr "C:\\FILE.TXT" "r" // makes C:\\FILE.TXT a read-only file close opt=[s] [Lib][win,edit_fmgr,prompt] [Ext][edit] ────────────────────────────────────────────────────────────────────── remarks: Closes the current window. If the buffer in the window is not displayed in any other windows, the buffer is also destroyed. If option 's' is specified and the window is an edit window, the file is saved. returns: nothing see also: open, save, setname example: close // closes the current window close 's' // saves the current buffer and closes the current // window closefile handle ────────────────────────────────────────────────────────────────────── remarks: Closes a file handle opened with 'openfile'. returns: nothing see also: filepos, openfile, readfile, writefile closefold opt=[s] row buffer ────────────────────────────────────────────────────────────────────── remarks: Closes the open fold spanning the specified row. If 'buffer' is null or not specified, then the current buffer is assumed. If 'row' is not specified, then the line at the cursor is assumed. If option 's' is specified, all open subfolds within the fold are also closed. returns: the number of folds closed see also: createfold, destroyfold, foldblock, getfold, openfold example: closefold // closes the open fold spanning the current line in // the current buffer, leaving any subfolds open closemouse ────────────────────────────────────────────────────────────────────── remarks: Deactivates the mouse driver and removes the mouse pointer from the screen. When this function is called, mouse events will no longer be processed by the event queue. returns: nothing see also: openmouse col col buffer ────────────────────────────────────────────────────────────────────── remarks: Moves the cursor to the specified column, but does not change the row. If 'buffer' is null or not specified, the current buffer is assumed. returns: TRUE if successful, otherwise null. see also: gotopos, row example: col 1 // moves the cursor to column 1 of the current line // in the current buffer col getlinelen + 1 // moves the cursor one column past the end of the // current line in the current buffer colorcursor color cursor ────────────────────────────────────────────────────────────────────── remarks: Changes the color of a cursor to the attribute 'color'. If 'cursor' is not specified, the current 'cursor' in the current buffer is assumed. returns: TRUE if successful, otherwise null. see also: getcolor, getcurrcurs, setcolor example: colorcursor 95 // changes the color of the current cursor to // white on magenta colormark color mark ────────────────────────────────────────────────────────────────────── remarks: Changes the mark color to the attribute 'color'. If this function is not used, the window mark color is assumed. This function allows individual marks to have different colors. If 'mark' is not specified, the default markid is assumed. returns: TRUE if successful, otherwise null. see also: getcolor, setcolor example: colormark 95 // changes the color of the current mark to // white on magenta compilemacro sourcefile destfile ────────────────────────────────────────────────────────────────────── remarks: Compiles the macro source file 'sourcefile' and places the compiled macro object code in the file 'destfile'. Compiler error information can be retrieved with the 'geterror' function. returns: Null if the compilation was successful, otherwise one of the following compiler error codes: 1001 - can't open file 1002, 1003 - read error 1004 - not an executable macro file 1031 - write error 1032 - can't open compiler output file 1101 - no closing quote 1102 - no closing bracket 1103 - invalid symbol 1104 - invalid key or event 1301 - no terminator 1302 - unexpected end of source 1303 - no closing parenthesis 1310 - unexpected argument 1311 - unexpected terminator 1312 - unexpected function 1313 - unexpected operator 1318 - invalid number 1319 - identifier not defined (the identifier name can be retrieved with the 'geterror' function, using option 's') 1320 - bad assignment 1330 - bad when clause 1336 - improperly placed break 1337 - invalid reference 1501 - can't open include file (the include file name can be retrieved with the 'geterror' function, option 's') 1502 - include level exceeded 1503 - can't include compiled file in expression 1504 - include must be at top level 1505 - define can't be nested 1506 - function must be at top level 1507 - can't redefine builtin function 1508 - duplicated function argument 1509 - object statement not permitted 1701 - too many variables 1702 - too many function arguments 1703 - function or expression too large 1704, 1705 - internal stack overflow 1706 - out of symbol space 1707 - internal stack overflow any other code - fatal compilation error see also: eval, geterror, includemacro, runmacro example: compilemacro "c:\\aurora\\macro\\utility.aml" "c:\\aurora\\macro\\utility.x" concat string1 string2 ... ────────────────────────────────────────────────────────────────────── remarks: Concatenates all of its arguments. Note: the concatenation operator (+) may also be used to concatenate strings. returns: the concatenated string of all the arguments. see also: copystr example: concat "Red" "Green" "Blue" // returns "RedGreenBlue" copyblock mark buffer col row ────────────────────────────────────────────────────────────────────── remarks: Copies marked text after the position 'col','row' in the specified buffer. The text is inserted at the new position and the mark is also moved to the new position. If 'mark' is not specified, the default markid is assumed. If 'buffer' is null or not specified, the current buffer is assumed. If 'col' and 'row' are not specified, the current cursor position is assumed. returns: TRUE if successful, otherwise null. see also: copyblockover, moveblock copyblockover mark buffer col row ────────────────────────────────────────────────────────────────────── remarks: Copies marked text to 'col','row' in the specified buffer. The text is overlaid at the new position (not inserted) and the mark is moved to the new location. If 'mark' is not specified, the default markid is assumed. If 'buffer' is null or not specified, the current buffer is assumed. If 'col' and 'row' are not specified, the current cursor position is assumed. returns: TRUE if successful, otherwise null. see also: copyblock, moveblock copyfile sourcefile destfile opt=[au] ────────────────────────────────────────────────────────────────────── remarks: Copies the file 'sourcefile' to 'destfile'. Any of the following options can be specified: a - append the sourcefile to the destination file u - update the destination file date/time returns: Non-zero if successful, otherwise zero. see also: deletefile, renamefile copymark oldmark newmark ────────────────────────────────────────────────────────────────────── remarks: Creates a new mark with the markid 'newmark' by making a copy of 'oldmark'. If 'newmark' is not specified, a unique markid will be assigned. The new mark will reside in the same buffer as 'oldmark' and have the same size and type. The new mark becomes the current mark for the buffer. returns: TRUE if successful, otherwise null. see also: markchar, markcolumn, markline, markstream example: copymark '*' 'T' // create a temporary copy of a mark . . destroymark 'T' // destroy the temporary mark copystr string count ────────────────────────────────────────────────────────────────────── remarks: Concatenates a string with itself for 'count' number of times. returns: the argument string copied 'count' times. see also: concat, pad, sizeof example: copystr "Red" 4 // returns "RedRedRedRed" copywin [Lib][edit] ────────────────────────────────────────────────────────────────────── remarks: Copies the current edit window. The new edit window will display the same file in memory as the original window. returns: TRUE if successful, otherwise null. see also: splitwin createbuf buffer line1 line2 ... ────────────────────────────────────────────────────────────────────── remarks: This function creates a new buffer with the specified bufferid. If the bufferid is already in use, this function will fail. If 'buffer' is null or not specified, a unique bufferid will be assigned. The new buffer will become the current buffer. Initial lines can be placed in the buffer with the arguments 'line1', 'line2', etc. If no lines are specified, one blank line is assumed. Note: this function will not display the new buffer in a window. The 'openbuf' library function should be used to display the buffer. returns: The new bufferid if successful, otherwise null. see also: asciibuf, buffer?, createbbuf, destroybuf, loadbuf, menu, openbuf example: createbuf // creates a new buffer and returns a // unique bufferid createbuf "abc" // creates new buffer with the // bufferid "abc" createbuf '' // creates a new buffer with 2 lines "First Line" // and returns a unique bufferid "Second Line" createbbuf buffer line1 line2 ... ────────────────────────────────────────────────────────────────────── remarks: This function creates a new binary buffer with the bufferid 'buffer'. By default, when a binary buffer is saved, line delimiter characters are not appended to the end of each line. This function is almost identical to the 'createbuf' function, except that a binary buffer is created (see 'createbuf'). returns: The new bufferid if successful, otherwise null. see also: asciibuf, buffer?, createbuf, destroybuf, loadbuf, menu createdir path ────────────────────────────────────────────────────────────────────── remarks: Creates a new directory specified by 'path'. Only one directory in the path can be created at a time. returns: Non-zero if successful, otherwise zero. see also: locatefile createfold opt=[c] row buffer ────────────────────────────────────────────────────────────────────── remarks: Creates a one-line text fold. If 'buffer' is null or not specified, then the current buffer is assumed. If 'row' is not specified, then the line at the cursor is assumed. If option 'c' is specified, the fold is created 'closed', otherwise the fold is created 'open'. returns: non-zero if successful, otherwise null. see also: closefold, destroyfold, foldblock, foldline, getfold, openfold example: createfold // creates an open fold on the current line in // the current buffer createwindow window ────────────────────────────────────────────────────────────────────── remarks: Creates a new window. If 'window' is null or not specified, a unique windowid will be assigned. The new window will become the current window. The new window will be sized to cover the entire physical screen and will not have any borders or frame controls. To add frame controls to the window, see the 'setframe' function. To change the border size and style, see the 'setborder' function. The window event object will be set to the current (executing) object. To change the window event object, see the 'setwinobj' function. This function can be used to create simple video output windows, or windows that display buffers. returns: The new windowid if successful, otherwise null. see also: destroywindow, setwinobj, window? example: createwindow // create a new window setframe "b" // add borders setborder "1i" // set the border style setcolor 0 127 // set border color setcolor 5 112 // set text color settitle "Hello World!" // set window title sizewindow 6 5 72 20 "ad" // size the window setshadow 2 1 // add shadows to the window currbook bookmark ────────────────────────────────────────────────────────────────────── remarks: Makes the specified bookmark the current bookmark by moving it to the top of the bookmark list in the current buffer. returns: TRUE if successful, otherwise null. see also: getcurrbook currbuf buffer ────────────────────────────────────────────────────────────────────── remarks: Makes the specified buffer the current buffer by moving it to the top of the buffer list. returns: nothing see also: getcurrbuf, gotobuf currcursor cursor ────────────────────────────────────────────────────────────────────── remarks: Makes the specified cursor the current cursor by moving it to the top of the cursor list in the current buffer. returns: TRUE if successful, otherwise null. see also: getcurrcurs currdesk [Lib][a] ────────────────────────────────────────────────────────────────────── remarks: Sets the 'current' desktop to the current window layout on the screen. The current desktop can be restored later with the 'restoredesk' function, or saved to a file with the 'savedesk' function. returns: nothing see also: begdesk, enddesk, opendesk, openhistory, restoredesk, savedesk currmark mark ────────────────────────────────────────────────────────────────────── remarks: Makes the specified mark the current mark by moving it to the top of the mark list in the current buffer. Marks at the top of the mark list have higher priority when displayed on the screen. returns: TRUE if successful, otherwise null. see also: getcurrmark currpath path ────────────────────────────────────────────────────────────────────── remarks: Changes the current DOS path to 'path' for the disk drive specified in 'path'. returns: Non-zero if successful, otherwise zero. see also: getcurrpath example: currpath "d:\\abc" // changes the current path for the D drive to 'abc' currwin window [Lib][a] ────────────────────────────────────────────────────────────────────── remarks: Brings the specified window to the top of the screen and makes it the current window. returns: nothing see also: getcurrwin cursor? cursor ────────────────────────────────────────────────────────────────────── remarks: Tests if a cursor exists. If 'cursor' is null or not specified, then the current cursor for the current buffer is assumed. returns: TRUE if the cursor exists, otherwise null. see also: destroycursor, setcursor cursorsize overtop overbot instop insbot ────────────────────────────────────────────────────────────────────── remarks: Sets the physical cursor size for insert and overstrike modes in windows which display a buffer. 'overtop' and 'overbot' specify the cursor top and bottom in overstrike mode. 'instop' and 'insbot' specify the cursor top and bottom in insert mode. The cursor top and bottom must be numbers from 0 to 99 and indicate the distance of the top and bottom of the cursor from the top of the character cell, on a scale of 0 to 99. returns: nothing see also: hidecursor, showcursor defext filename extension [Ext][a] ────────────────────────────────────────────────────────────────────── remarks: Appends the default extension 'extension' to the specified filename if the filename has no extension. returns: a filename with the default extension. see also: forceext example: defext "file" "doc" // returns 'file.doc' defext "file.txt" "doc" // returns 'file.txt' defext "file." "doc" // returns 'file.' delay milliseconds ────────────────────────────────────────────────────────────────────── remarks: Suspends execution of the editor for the specified number of milliseconds. returns: nothing see also: beep, exec, halt example: delay 1000 // delay for 1 second delchar count col row buffer ────────────────────────────────────────────────────────────────────── remarks: Deletes text on a line in a buffer. If 'buffer' is null or not specified, then the current buffer is assumed. The text at the specified 'col' and 'row' are deleted. If 'col' are 'row' are not specified, the text at the cursor is deleted. 'count' specifies the number of characters to delete. If 'count' is not specified, 1 is assumed. returns: TRUE if successful, otherwise null. see also: instext, ovltext, text example: delchar // deletes the character at the cursor in the // current buffer delchar 4 // deletes 4 characters at the cursor in the // current buffer delchar 1 5 20 "abc" // deletes the character at column 5, line 20 // in the buffer "abc" deleteblock mark ────────────────────────────────────────────────────────────────────── remarks: Deletes marked text and destroys the mark. If 'mark' is not specified, the default markid is assumed. returns: TRUE if successful, otherwise null. see also: copyblock deletefile filename ────────────────────────────────────────────────────────────────────── remarks: Deletes the specified filename. 'filename' may also specify an empty directory. returns: TRUE if successful, otherwise null. see also: copyfile, renamefile deletewin [Lib][a] ────────────────────────────────────────────────────────────────────── remarks: Deletes the current window. For edit windows, the buffer in the window is not destroyed. returns: nothing see also: close delline count row buffer ────────────────────────────────────────────────────────────────────── remarks: Deletes a line or lines in a buffer. If 'buffer' is null or not specified, the current buffer is assumed. If 'row' is specified, lines are deleted starting with 'row', otherwise lines are deleted at the cursor. 'count' specifies the number of lines to delete. If 'count' is not specified, 1 is assumed. returns: the line number of the line deleted if successful, otherwise null. see also: addline, insabove, insline, joinline, splitline example: delline // deletes the line at cursor in the current buffer delline 4 // deletes the line at cursor and 3 lines below // it in the current buffer delline 1 1 "abc" // deletes the first line in the buffer "abc" if delline > getrow then // deletes the current line and tests if it was the // last line . . end destroybook bookmark ────────────────────────────────────────────────────────────────────── remarks: Destroys a bookmark created with the 'setbook' function. If 'bookmark' is not specified, the current bookmark is assumed. returns: TRUE if successful, otherwise null. see also: setbook destroybuf buffer ────────────────────────────────────────────────────────────────────── remarks: Destroys a buffer, If 'buffer' is null or not specified, then the current buffer is destroyed. All windows, cursors, bookmarks, and marks associated with the buffer will also be destroyed. The previous buffer in the buffer list will become the current buffer. returns: nothing see also: createbbuf, createbuf, loadbuf destroycursor cursor ────────────────────────────────────────────────────────────────────── remarks: Destroys the specified cursor, and any window in which the cursor is displayed. If 'cursor' is not specified, then the current cursor in the current buffer is destroyed. If the buffer contains more than one cursor, the next cursor in the cursor list will become the current cursor. returns: TRUE if successful, otherwise null. see also: getcurswin, setcursor destroyfold opt=[s] row buffer ────────────────────────────────────────────────────────────────────── remarks: Destroys a closed fold. If 'buffer' is null or not specified, then the current buffer is assumed. If 'row' is not specified, then the line at the cursor is assumed. If option 's' is specified, all closed subfolds within the fold are also destroyed. returns: the number of folds destroyed see also: closefold, createfold, foldblock, foldline, getfold, openfold example: destroyfold // destroys the closed fold at the current line in the // current buffer, leaving subfolds intact destroymark mark ────────────────────────────────────────────────────────────────────── remarks: Destroys a mark created with the markline, markcolumn, markchar, markstream, or copymark functions. The text within the mark is not affected. If 'mark' is not specified, the default markid is assumed. returns: TRUE if successful, otherwise null. see also: copymark, markchar, markcolumn, markline, markstream destroyobject object ────────────────────────────────────────────────────────────────────── remarks: Flags the specified object to be destroyed. The object will actually be destroyed the next time the editor is idle. If 'object' is not specified, then the current object is assumed. returns: nothing see also: object, object?, runmacro, stayresident destroytimer timerid ────────────────────────────────────────────────────────────────────── remarks: Stops and destroys the timer identified by 'timerid'. This function will destroy both interval and alarm timers. returns: nothing see also: setalarm, settimer, timer? destroywindow window ────────────────────────────────────────────────────────────────────── remarks: Destroys a window and removes it from the screen. If 'window' is null or not specified, then the current window is destroyed. Any child windows of 'window' are also destroyed. The previous window in the window list will become the current window. returns: nothing see also: createwindow, window? dialog title width height opt=[cp] object [Lib][a] ────────────────────────────────────────────────────────────────────── remarks: Creates a main dialog box window to which dialog box controls may be added. The new dialog box becomes the current window and the 'current' dialog box. The following parameters may be specified: title - the dialog box title width - the dialog box width height - the dialog box height object - the name of an object to be notified when dialog box events occur The following options may also be specified: c - center the dialog box title (if this option is not specified, the title is left-justified) p - remember the dialog box position after closing (if this option is not specified, the dialog box will be centered) returns: The dialog box window id. see also: button, field, getdialog, groupbox, listbox, showdialog example: dialog "Test Dialog Box" 40 5 // create a dialog box getdialog // display the dialog box dir? filespec [Lib][a] ────────────────────────────────────────────────────────────────────── remarks: Tests if 'filespec' specifies a directory. returns: TRUE if filespec specifies a directory, otherwise null. example: dir? "file.txt" // returns null dir? "*.txt" // returns true dir? "c:" // returns true dispatch ────────────────────────────────────────────────────────────────────── remarks: This function reads the next event from the event queue and 'dispatches' it by calling a user-defined event handling function associated with the event. If no events are on the queue, this function waits for an event to appear on the queue. returns: TRUE if the 'endprocess' function was not called in the user event-handling function, otherwise null. see also: endprocess, process display opt=[f] ────────────────────────────────────────────────────────────────────── remarks: Updates the display. Any windows, buffers, and marks, and cursors which have been modified are redrawn. Specifying option 'f' forces the entire display to be redrawn (the background, all windows, etc.), even if nothing has been modified within the editor. This can be used to restore the display after another program, utility, or DOS command has overwritten it. returns: TRUE if the display was updated, otherwise null. see also: setdisplay down rows buffer ────────────────────────────────────────────────────────────────────── remarks: Moves the cursor downward. 'rows' specifies the number of lines to move. If 'rows' is not specified, 1 is assumed. If 'buffer' is null or not specified, the current buffer is assumed. returns: TRUE if successful, otherwise null. see also: left, right, up example: down // moves the cursor down 1 row down 5 // moves the cursor down 5 rows enddesk [Lib][a] ────────────────────────────────────────────────────────────────────── remarks: Marks the end of a series of window 'close' calls which add the closed window to the current desktop. returns: nothing see also: begdesk endprocess ────────────────────────────────────────────────────────────────────── remarks: Posts a special internal 'quit' event to the event queue. When the editor processes this event, the current editor 'process' is terminated, and the editor returns to the previous process (or to DOS if there is no previous process). The internal 'quit' event forces the 'dispatch' function to return null, and the 'process' function call to return. returns: TRUE if successful, otherwise null. see also: dispatch, process eotstring titleid window ────────────────────────────────────────────────────────────────────── remarks: Sets the end-of-text line for a window which displays a buffer to a window title previously set with the 'settitle' function. If 'window' is not specified, the current window is assumed. 'titleid' specifies which one of the 5 window titles should be used. The title should be hidden with settitle option 'z' (see 'settitle'). If 'titleid' is not specified, then the 'end-of-text line is removed. If 'titleid' is -1, then the end-of-text line defaults to: "≡≡≡≡≡≡ End of Text ≡≡≡≡≡≡". returns: nothing see also: gettitle, settitle example: eotstring // removes the end-of-text line in the current window eotstring -1 // sets the end-of-text line to // '≡≡≡≡≡≡ End of Text ≡≡≡≡≡≡' erasekey opt=[a] [Lib][a] ────────────────────────────────────────────────────────────────────── remarks: Erases the current scrap key macro. If option 'a' is specified, all current key macros are erased. returns: TRUE if successful, otherwise null. see also: openkey, playkey, savekey, setting eval string object ────────────────────────────────────────────────────────────────────── remarks: Compiles and evaluates a macro language source code string in the specified object. If 'object' is not specified, the current object is assumed. This function can also evaluate compiled expressions. Note that local and global variables defined outside of the scope of the eval string are not accessible from within the 'eval' function. returns: The result of evaluating the macro source string. The 'geterror' function can also be called to return an error code. The error code is zero if the string compiled successfully. see also: compilemacro, geterror, includemacro, runmacro example: eval "beep 700 300" // beeps the speaker a = 40 x = eval '3 + ' + a [1] // x is '7' event? ────────────────────────────────────────────────────────────────────── remarks: Test if one or more events are currently in the event queue, including keyboard, mouse, and user-defined events. returns: TRUE if an event is in the queue, otherwise null. see also: geteventcount, keyhit?, shiftkey? eventobject object ────────────────────────────────────────────────────────────────────── remarks: Changes the current event object to the specified object. The current event object is where events are dispatched by the editor. If 'object' is not specified, the current (executing) object is assumed. Note: if a window has been associated with an event object via the 'setwinobj' function, the current event object is automatically changed to the window object when the window becomes the current window. returns: TRUE if successful, otherwise null. see also: geteventobj, setwinobj exec program opt=[chk] ────────────────────────────────────────────────────────────────────── remarks: Executes a DOS program. Any of the following options may be specified: c - clears the screen before executing h - displays the header "Type EXIT to return" after executing the program k - prompts the user with a keypress to return to the editor Since DOS 'PATH' is not searched, 'program' should be fully qualified or reside in the current directory. If the path of the program is not known, the function 'locatefile' can be used to search the DOS path. returns: the DOS errorlevel see also: delay, halt, locatefile extendmark col row mark ────────────────────────────────────────────────────────────────────── remarks: Extends a mark to the position defined by 'col','row'. If 'col' and 'row' are not specified then the current cursor position is assumed. If 'mark' is not specified, the default markid is assumed. returns: nothing see also: markchar, markcolumn, markline, markstream, stopmark fdobrk [Lib][fmgr] ────────────────────────────────────────────────────────────────────── remarks: Breaks out of the current 'fdomark' call. returns: nothing see also: fdomark fdomark function arg1 arg2 ... ────────────────────────────────────────────────────────────────────── remarks: Calls the specified function once for each marked file in the current file manager window. If no files are marked, the function is called only once for the file or directory at the current line in the file manager. The function is called in the current event object. The fully qualified file name and the arguments 'arg1', 'arg2', etc. are passed to the function in following order: filename arg1 arg2 ... returns: nothing see also: fdobrk, fmark, fmark? example: fdomark "chgfileattr" attribute // calls the function 'chgfileattr' (passing the value // of the variable 'attribute') in the current event // object for all marked files in the current // file manager window field title x y width initvalue history [Lib][a] ────────────────────────────────────────────────────────────────────── remarks: Adds an edit field window control to the current dialog box. The edit field window becomes the current window. The following parameters may be specified: title - the edit field title or prompt. If the last character of the title is '>', the title will be displayed to the left of the edit field, otherwise the title will be displayed above the edit field. x - the edit field x-position in the dialog box y - the edit field y-position in the dialog box width - the edit field width initvalue - the initial value (if any) to be placed in the edit field history - the history buffer (if any) to be associated with the edit field returns: The edit field window id. see also: button, dialog, groupbox, listbox, whenenter example: dialog "Test Dialog Box" 40 5 // create a dialog box field "Enter string: " 18 2 8 "inital value" // add an edit field control getdialog // display the dialog box fileattr? filename attributes=[adhrsv] ────────────────────────────────────────────────────────────────────── remarks: Tests if 'filename' has the specified file attributes. Any combination of the following attributes can be specified: a - archive d - directory h - hidden r - read only s - system v - volume returns: Non-zero if any of the specified attributes are present, otherwise null. see also: chgfileattr example: if fileattr? "C:\\FILE.TXT" 'r' then // test for say "Read Only!" // read-only file else // before saving savebuf "C:\\FILE.TXT" end filelist [Lib][a] ────────────────────────────────────────────────────────────────────── remarks: Displays a popup menu of buffers which have not been 'hidden'. Selecting a buffer will make it the current buffer and display it in the current edit window. The buffer previously displayed in the edit window will not be destroyed. returns: the bufferid selected, or null if nothing was selected. see also: hidebuf, nextfile, prevfile filepos handle position opt=[ace] ────────────────────────────────────────────────────────────────────── remarks: Changes the current position in the open file specified by 'handle'. The new position depends on the value of 'position', the current position, and the options specified. One of the following options may be specified: a - 'position' is an absolute position in the file (1 is the first position) c - 'position' is an offset from the current position e - 'position' is an offset from the end of the file. If no options are specified, then 'a' is assumed. returns: The new absolute position in the file (1 is the first position) if successful, otherwise null. see also: closefile, openfile, readfile, writefile fillblock string mark ────────────────────────────────────────────────────────────────────── remarks: Fills a mark with the specified string. If 'mark' is not specified, the default markid is assumed. returns: TRUE if successful, otherwise null. see also: copystr fillrect length height char col row ────────────────────────────────────────────────────────────────────── remarks: Fills a rectangular area in the current video window with the specified character. 'length' and 'height' specify the dimensions of the rectangular area. 'col' and 'row' specify the upper left corner of the rectangle. If 'col' and 'row' are not specified, the current cursor position is assumed. returns: nothing see also: gotoscreen, hilite, writeline, writestr example: xd = getcoord 'x1' yd = getcoord 'y1' hilite xd yd (getcolor text_color) 1 1 fillrect xd yd ' ' 1 1 // clear the current video window (fill with blanks) find searchstring opt=[abfgilnorswx*[~] mark buffer ────────────────────────────────────────────────────────────────────── remarks: Searches for the specified search string in a buffer, mark, or line. If 'buffer' is not specified, the current buffer is assumed. Various combinations of the following search options may be specified: a - find all occurrences b - limit the search to the specified mark f - search for closed text folds g - start the search from the beginning or end of the buffer, mark, or line i - ignore case during the search l - limit the search to the current line n - prevent the cursor position from being updated o - search for open text folds r - search in reverse towards the beginning of the buffer, rather than towards the end of the buffer s - skip closed text folds w - search for 'whole words' only x - check for regular expression characters in the search string (see 'Regular Expression Searching'). * - force the search to begin at the current cursor position instead of the next character position [ - search for the first character also found in the search string. Character ranges can be specified (a-zA-Z, etc.) ~ - search for the first character not found in the search string. Character ranges can be specified (a-zA-Z, etc.) If the string is found, and options 'a' and 'n' are not specified, then the cursor is moved to the beginning of the matched string, otherwise the cursor does not move. returns: If option 'a' is specified, the number of occurrences found is returned, otherwise the length of the matched string is returned. If nothing is found, then null is returned. see also: replace, search example: find "apples" // searches for the string 'apples' (case sensitive) // starting at one char to the right of the cursor // and searching toward the end of the buffer find "apples" "*ir" // searches for 'apples' (case insensitive) starting at // the cursor position and searching toward the // beginning of the buffer find "apples" "bgw" // searches for 'apples' (whole words only), limiting // the search to the current mark and starting from // the beginning of the mark find "{apples}|{oranges}" "agx" // returns the total number of occurrences of the // strings 'apples' and 'oranges' (using regular // expressions) in the current buffer. The cursor is // not moved. find "a-zA-Z" "[gl" // Moves the cursor to the first alphabetic character // in the current line find "^ *$" "agx" // Counts the number of blank lines in the current // buffer using regular expressions findbuf buffername ────────────────────────────────────────────────────────────────────── remarks: Finds the first buffer in the buffer list with the specified buffer name. A buffer name can be associated with a buffer by using the 'setbufname' function. For most ordinary editing buffers, the buffer name is usually a fully qualified file name. returns: The first bufferid with specified name if successful, otherwise null. see also: getcurrbuf, getprevbuf, setbufname example: findbuf "C:\\FILE.TXT" // returns the bufferid of the buffer with the // name C:\FILE.TXT finddlg [Lib][edit] ────────────────────────────────────────────────────────────────────── remarks: Displays a find dialog box. returns: the search multi-string (searchstring/options) to be used when searching, or null if nothing is specified. see also: about, repldlg, scandlg flipcase string ────────────────────────────────────────────────────────────────────── remarks: Toggles the case of each character in the string. returns: the 'flipcased' string. see also: locase, upcase example: flipcase "Oranges" // returns "oRANGES" fmark opt=[amu] [Lib][fmgr] ────────────────────────────────────────────────────────────────────── remarks: Marks or unmarks files in the current file manager window. The following options can be specified: a - unmarks all files when specified with option 'u', otherwise all files are marked. m - marks the file or directory at the cursor. If option 'a' is specified, all files are marked. u - unmarks the file or directory at the cursor. If option 'a' is specified, all files and directories are unmarked. If no options are specified, 'm' is assumed. returns: nothing see also: fdobrk, fdomark, fmark? example: fmark // mark the file or directory at the cursor fmark "ma" // mark all files fmark "ua" // unmark all files and directories fmark? [Lib][fmgr] ────────────────────────────────────────────────────────────────────── remarks: Tests if any files or directories are marked in the current file manager window. returns: Non-zero if a file or directory is marked, otherwise null. see also: fdobrk, fdomark, fmark? fold? opt=[contbsl] row buffer ────────────────────────────────────────────────────────────────────── remarks: This function is a synonym for the 'getfold' function. Calling this function with no arguments is useful for testing whether or not a closed fold exists on the current line in the current buffer. returns: see the 'getfold' function. see also: getfold foldblock opt=[cdkos] mark ────────────────────────────────────────────────────────────────────── remarks: Manipulates folds within a mark. If 'mark' is not specified, the default markid is assumed. The following options may be specified: c - Closes open folds in the mark. If option 's' is also specified, all subfolds are also closed. d - Destroys folds in the mark. The following options may also be specified: s - destroys subfolds c - destroys closed folds o - destroys open folds If option 'd' is specified and options 'o' or 'c' are not specified, then 'dco' is assumed. k - Creates a fold spanning the mark. If option 'o' is also specified, then the fold is created 'open', otherwise the fold is created 'closed'. o - Opens closed folds in the mark. If option 's' is also specified, all subfolds are also opened. If no options are specified, then 'k' is assumed. returns: the number of folds opened, closed, or destroyed. see also: actualrow, apparentrow, closefold, createfold, destroyfold, fold?, getfold, openfold example: foldblock // creates a new closed fold spanning the default mark foldblock 'ds' // destroys all open and closed folds and subfolds // in the default mark foldblock 'o' // opens all top level closed folds in the default mark foldblock 'cs' // closes all open folds and subfolds in the default // mark foldline opt=[u] [Ext][edit] ────────────────────────────────────────────────────────────────────── remarks: Folds or unfolds the current line in the current buffer. If option 'u' is specified, the line is unfolded, otherwise the line is folded. returns: nothing see also: actualrow, apparentrow, closefold, createfold, destroyfold, fold?, foldblock, getfold, openfold forceext filename extension [Ext][a] ────────────────────────────────────────────────────────────────────── remarks: Forces a filename to have the specified extension. returns: a filename with the specified extension. see also: defext example: forceext "file" "doc" // returns 'file.doc' forceext "file.txt" "doc" // returns 'file.doc' formatblock leftmarg rightmarg opt=[kjr] mark ────────────────────────────────────────────────────────────────────── remarks: Reformats marked text. If 'mark' is not specified, the default markid is assumed. For column marks, the text is reformatted to fit between the left and right edges of the mark. For all other marks, the text is reformatted to fit between 'leftmarg' and 'rightmarg'. Any combination of the following options may be specified: j - the text is both left and right justified (blanks are inserted to pad text to the right margin) k - attempts to preserve spaces during the reformat r - maintains the indenting relationship between the first and second line of the text returns: TRUE if successful, otherwise null. see also: justblock example: formatblock 5 50 "kr" // reformats the text within a line mark to fit between // columns 5 and 50, preserving spaces and // maintaining the relationship between the first // and second lines in the mark. frame? components window ────────────────────────────────────────────────────────────────────── remarks: Tests if the specified window frame components are present. If 'window' is not specified, the current window is assumed. See the 'setframe' function for a list of window component options. returns: Non-zero if any of the specified components are present. see also: setframe example: frame? "bn" // returns non-zero if the current window has a // border or a north title bar fscanstr [Lib][fmgr] ────────────────────────────────────────────────────────────────────── remarks: Returns the scan string (if any) used to generate the current file manager window. returns: a scan search string in multi-string format see also: ftype? fsort opt=[ednos] [Lib][a] ────────────────────────────────────────────────────────────────────── remarks: Sorts files and directories in the current file manager window. One of the following options can be specified: d - sorts by date and time (descending order) e - sorts by file extension n - sorts by file name o - arrange in the DOS default order s - sorts by file size (descending order) If no options are specified, 'o' is assumed. returns: nothing see also: askfile example: fsort 'n' // sort by file name fsort 's' // sort by size (descending) ftype? opt=[is] [Lib][fmgr] ────────────────────────────────────────────────────────────────────── remarks: Tests the current file manager window 'type'. One of the following options can be specified: i - an 'include file' picklist s - generated by the 'file scanning' process returns: TRUE if successful, otherwise null. see also fscanstr example: if ftype 's' then // is this a scan window? . . end function? funexpression objexpression ────────────────────────────────────────────────────────────────────── remarks: Tests for the existence of a function defined by 'funexpression' in the object defined by 'objexpression'. If 'objexpression' is not specified, then the current object is assumed. The inheritance hierarchy of the specified object may also be searched for the function. returns: Non-zero if the function exists, otherwise null. see also: lookup, set, setobj, setx, setxfun, setxobj, unsetx example: function? "function?" // returns non-zero function? "markword" "edit" // tests if the 'markword' function is accessible // from within the object 'edit' fup [Lib][fmgr] ────────────────────────────────────────────────────────────────────── remarks: Reloads the current file manager window with the parent directory of the currently displayed directory. returns: TRUE if successful, otherwise null. see also: open, reopen getattr x y ────────────────────────────────────────────────────────────────────── remarks: Gets the color at the specified x,y position in the current video output window. If x or y are not specified, the current video cursor position is assumed. returns: the color at x,y see also: fillrect, getstr, getx, gety, gotoxy, gotoscreen, hilite, writeline, writestr getbinarylen buffer ────────────────────────────────────────────────────────────────────── remarks: Gets the binary line length that was used to load a binary buffer. If 'buffer' is null or not specified, then the current buffer is assumed. This function can also be used to test if a buffer is a binary buffer. returns: The binary line length associated with a buffer. see also: createbbuf, insertbuf, loadbuf getbookbuf bookmark ────────────────────────────────────────────────────────────────────── remarks: Retrieves the buffer associated with a bookmark. If 'bookmark' is not specified, the current 'bookmark' in the current buffer is assumed. returns: The bufferid associated with the bookmark if successful, otherwise null. see also: getcurrbook getbootpath ────────────────────────────────────────────────────────────────────── remarks: Retrieves the editor 'boot' path. The boot path is the location of the editor .EXE file currently executing. returns: The boot path. see also: bootpath, setbootpath getborder opt=[xyt] window ────────────────────────────────────────────────────────────────────── remarks: Retrieves information about a window border. If 'window' is not specified, the current window is assumed. One of the following options can be specified: x - returns the width of the left and right borders y - returns the width of the top and bottom borders t - returns the border type, See the 'setborder' function for a description of border types. returns: Information based on the options specified. see also: setborder getbotwin ────────────────────────────────────────────────────────────────────── remarks: Gets the bottommost window on the screen. returns: the windowid of the bottommost window on the screen see also: getcurrwin getbufname buffer ────────────────────────────────────────────────────────────────────── remarks: Retrieves the descriptive name associated with a buffer. If 'buffer' is null or not specified, then the current buffer is assumed. A buffer name can be associated with a buffer by using the 'setbufname' function. For most ordinary editing buffers, the buffer name is usually a fully qualified file name. returns: The descriptive name associated with a buffer. see also: findbuf, setbufname getchar col row buffer ────────────────────────────────────────────────────────────────────── remarks: Retrieves the character at the specified column and row in the buffer 'buffer'. If 'buffer' is null or not specified, then the current buffer is assumed. If 'col' and 'row' are not specified, then the character at the cursor is retrieved. If the column is beyond the end of a line, null is returned. returns: A one-character string if successful, otherwise null. see also: gettext example: getchar // returns the character at the cursor in the // current buffer getchar 3 5 // returns the character at column 3, line 5 in the // current buffer getchar 1 1 "abc" // returns the first character in the buffer "abc" getchild window opt=[bt] ────────────────────────────────────────────────────────────────────── remarks: Gets a child window for a window. If 'window' is not specified, the current window is assumed. The following options may be specified: b - returns the bottommost child window t - returns the topmost child window returns: the windowid of the topmost or bottommost child window if successful, otherwise null. see also: getparent, setnextwin, setparent, setprevwin getcol buffer ────────────────────────────────────────────────────────────────────── remarks: Gets the column position of the cursor. If 'buffer is null or not specified, the current buffer is assumed. returns: The current cursor column position. see also: getrow getcolor component window ────────────────────────────────────────────────────────────────────── remarks: Gets the color of a window component. If 'window' is not specified, the current window is assumed. See the 'setcolor' function for 'component' values. returns: the color of the specified window component. see also: setcolor example: getcolor 5 // returns the text color of the current window getcolor 6 // returns the mark color of the current window getcoord opt=[ltrb1xyd] window ────────────────────────────────────────────────────────────────────── remarks: Retrieves the coordinates and dimensions of a window. If 'window' is not specified, the current window is assumed. The following options may be specified: l - returns the virtual left edge of the window t - returns the virtual top edge of the window r - returns the virtual right edge of the window b - returns the virtual bottom edge of the window x - returns the window width (the width of the client area if option '1' is specified) y - returns the window height (the height of the client area if option '1' is specified) d - returns the height or width of the 'visible' portion of the window on the screen, when used with the 'x' or 'y' options above 0 - returns a main window coordinate 1 - returns a client window coordinate. If not specified, main window coordinates are assumed. returns: Information based on the options specified. see also: movewindow, sizewindow example: getcoord "l" // return the virtual coordinate of the left edge of // the current window getcoord "1xd" // returns the visible width of the current window // client area on the screen getcurrbook buffer ────────────────────────────────────────────────────────────────────── remarks: Retrieves the current bookmark for the specified buffer. If 'buffer' is null or not specified, the current buffer is assumed. returns: The current bookmarkid for a buffer. see also: currbook getcurrbuf ────────────────────────────────────────────────────────────────────── remarks: Gets the current buffer at the top of the buffer list. returns: The current bufferid if successful, otherwise null. see also: findbuf, getprevbuf, gotobuf getcurrcurs buffer ────────────────────────────────────────────────────────────────────── remarks: Retrieves the current cursorid for the specified buffer. If 'buffer' is null or not specified, the current buffer is assumed. returns: The current cursorid for a buffer. see also: currcursor, destroycursor, setcursor getcurrmark buffer ────────────────────────────────────────────────────────────────────── remarks: Retrieves the current markid for the specified buffer. If 'buffer' is null or not specified, the current buffer is assumed. returns: The current markid for a buffer. see also: currmark getcurrobj ────────────────────────────────────────────────────────────────────── remarks: Gets the current (executing) object where this function is called. returns: The current object. see also: object getcurrpath drive ────────────────────────────────────────────────────────────────────── remarks: Retrieves the current path for the specified disk drive. If 'drive' is not specified, the current drive is assumed. If a drive is specified, it must be specified with a colon: 'C:', 'D:', etc. returns: The current fully qualified path for the specified drive. see also: currpath getcurrwin opt=[c] ────────────────────────────────────────────────────────────────────── remarks: Gets the current (topmost) window on the screen. If no options are specified, the topmost non-child window is returned. If option 'c' is specified, the topmost window is returned, whether or not the window is a child window. returns: the current windowid see also: getbotwin, gotowindow getcursbuf cursor ────────────────────────────────────────────────────────────────────── remarks: Retrieves the buffer associated with a cursor. If 'cursor' is not specified, the current 'cursor' in the current buffer is assumed. returns: The bufferid associated with the cursor if successful, otherwise null. see also: getcurrbook getcurswin cursor ────────────────────────────────────────────────────────────────────── remarks: Retrieves the windowid, if any, associated with a cursor. If 'cursor' is not specified, the current 'cursor' in the current buffer is assumed. returns: The windowid associated with a cursor if successful, otherwise null. see also: getwincurs getdate ────────────────────────────────────────────────────────────────────── remarks: Gets the current date in the format set by the 'international' function. returns: The current date. see also: getrawtime, gettime, international getdialog ref1 ref2 ... [Lib][a] ────────────────────────────────────────────────────────────────────── remarks: Displays the current dialog box as a 'modal' dialog box (any existing windows on the screen cannot be placed on top of a modal dialog box). This function does not return until the dialog box has been closed. The current dialog box control values are returned in the variables (ref1, ref2, etc.) passed by reference to this function. The order of the return values is the same order in which the dialog box controls were defined. The following values are returned for each control: button - null field - the contents of the edit field group - the checked items in the group box, in 'initvalue' format (see the 'groupbox' function) listbox - the line at the cursor within the list box returns: The title of the button pressed to close the window. If <enter> is pressed then 'Ok' is returned. If <esc> is pressed, then null is returned. If the 'close' function is called from within a dialog box event-handling function (defined with 'whenenter' or 'whenselect'), then the first argument passed to 'close' is returned. Dialog box control values are also returned in variables passed by reference to this function. see also: dialog, showdialog, whenenter, whenselect example: dialog "Test Dialog Box" 40 17 field "Enter string1: " 18 2 8 field "Enter string2: " 18 4 8 var field1 var field2 // display the dialog box, and get return values if (getdialog ref field1 ref field2) == 'Ok' then : : end getdisk opt=[cfmnv] drive ────────────────────────────────────────────────────────────────────── remarks: Retrieves information about the specified disk drive. If a drive is not specified, the current drive is assumed. The following options can be specified: c - returns the total drive capacity f - returns the free space on the drive m - returns a string composed of all available disk drive letters. If option 'n' is also specified, each drive letter is followed by '2' if a network drive or '1' if not a network drive v - returns the volume name for the drive returns: Information based on the specified options. see also: getcurrpath example: getdisk 'f' // returns the free space on the current drive getdisk 'v' "c:" // returns the volume name for drive C getenv environvariable ────────────────────────────────────────────────────────────────────── remarks: Gets the value of the specified environment variable. 'environvariable' must be in upper case. returns: The value of an environment variable if successful, otherwise null. see also: getos example: getenv "PATH" // returns the DOS 'PATH' string geterror opt=[cfkls] ────────────────────────────────────────────────────────────────────── remarks: Retrieves error information after compiling macro source code with the 'compilemacro' or 'eval' functions, or executing macros with the 'runmacro' and 'includemacro' functions. One of the following options can be specified: c - error code (zero if successful) f - source filename where the error occurred k - column in the source file where the error occurred l - line in the source file where the error occurred s - an error information string. The string contents depend on the error code (see the 'compilemacro' function for additional information). If no options are specified, 'c' is assumed. returns: Information based on the options specified. see also: compilemacro, eval, includemacro, runmacro geteventcount ────────────────────────────────────────────────────────────────────── remarks: Gets the number of real physical events (keyboard and mouse) which have occurred in the current editing session. returns: The number of real events. see also: event?, keyhit?, shiftkey? geteventobj ────────────────────────────────────────────────────────────────────── remarks: Gets the current event object. The current event object is where events are dispatched by the editor. returns: The current event objectid. see also: eventobject getexe ────────────────────────────────────────────────────────────────────── remarks: Gets the name of the currently executing editor .EXE file, without path information or the .EXE extension. returns: The editor .EXE name. see also: getversion getos getffile [Lib][fmgr] ────────────────────────────────────────────────────────────────────── remarks: Gets the fully qualified file or directory name on the current line in the current file manager window. returns: a fully qualified file or directory name. see also: openf getfold opt=[contbsl] row buffer ────────────────────────────────────────────────────────────────────── remarks: Returns information about a fold at the specified row in a buffer. If 'buffer' is null or not specified, then the current buffer is assumed. If 'row' is not specified, then the line at the cursor is assumed. The following options may be specified: l - Returns the line number of the top or bottom row in an open fold. The following options may also be specified: t - returns the top line number b - returns the bottom line number If options 't' and 'b' are not specified, then 't' is assumed. n - Returns the total number of folds in the buffer ('row' is ignored). The following options may be specified: c - returns the total number of closed folds o - returns the total number of open folds If options 'c' and 'o' are not specified, then 'co' (both open and closed folds) is assumed. s - returns the number of lines in the closed fold at the specified row. If none of the above options are specified, then the following options may be used to test whether or not the current line is on a fold boundary: c - returns true if the specified row is on the top or bottom line of a closed fold. o - returns true if the specified row is on the top or bottom line of an open fold. t - returns true if the specified row is on the top line of a fold. b - returns true if the specified row is on the bottom line of a fold. If no options are specified, then 'ct' is assumed. returns: Information based on the options specified. see also: actualrow, apparentrow, closefold, createfold, destroyfold, fold?, foldblock, openfold example: getfold // returns true if a closed fold exists at the cursor // in the current buffer getfold 'ot' // returns true if the cursor is on the top line of // an open fold getfold 'ns' // returns the total number of closed folds in the // current buffer getfold 's' // returns the number of lines in the closed fold at // the cursor in the current buffer gethistname [Lib] ────────────────────────────────────────────────────────────────────── remarks: Gets the history bufferid for the current prompt. This function is only for use within prompts. returns: the history bufferid for the current prompt. see also: addhistory, askhistory, gethiststr, pophistory gethiststr historybuffer [Lib][a] ────────────────────────────────────────────────────────────────────── remarks: Gets the most recently used (or added) string for the specified history buffer. returns: the most recently used history string. see also: addhistory, askhistory, pophistory example: addhistory "_find" "apples" say (gethiststr "_find") // displays 'apples' getkey opt=[ds] ────────────────────────────────────────────────────────────────────── remarks: Waits for a key to be entered, bypassing the editor event queue. The display is updated if needed. The following options may be specified: d - disable updating of the display s - include scancodes for non-function (typeable) keys returns: A keycode for the key pressed. see also: getkeycode, getkeyname example: say "you pressed keycode: " + getkey getkeycode keyname ────────────────────────────────────────────────────────────────────── remarks: Gets the key code for the specified key name. returns: a key code see also: getkeyname example: say "The keycode for <ctrl b> is: " + (getkeycode "<ctrl b>") getkeyname keycode ────────────────────────────────────────────────────────────────────── remarks: Gets the key name for the specified key code. returns: a key name see also: getkeycode example: say "You pressed the key: " + (getkeyname (getkey)) getlinebeg row buffer ────────────────────────────────────────────────────────────────────── remarks: Gets the column of the first non-blank character in a line. If 'buffer' is null or not specified, then the current buffer is assumed. If 'row' is not specified, then the line at the cursor is assumed. returns: The column of the first non-blank character, otherwise null. see also: getlinelen example: getlinebeg // returns the first non-blank column of the current // line in the current buffer getlinelen 1 // returns the first non-blank column of the first // line in the current buffer getlinebeg 5 "abc" // returns the first non-blank column of line 5 in // buffer "abc" getlinelen row buffer ────────────────────────────────────────────────────────────────────── remarks: Gets the length of a line. If 'buffer' is null or not specified, then the current buffer is assumed. If 'row' is not specified, then the line at the cursor is assumed. returns: For non-binary buffers, the position of the last non-blank character in the line is returned. For binary buffers, the position of the last character in the line is returned. see also: getbinarylen, getlinebeg example: getlinelen // returns the length of the line at the cursor in // the current buffer getlinelen 1 // returns the length of the first line in the // current buffer getlinelen 5 "abc" // returns the length of line 5 in the buffer "abc" getlines buffer ────────────────────────────────────────────────────────────────────── remarks: Gets the total number of lines in a buffer. If 'buffer' is null or not specified, then the current buffer is assumed. A buffer will always have at least one line. returns: The number of lines in a buffer. getloadinfo opt=[dfst] ────────────────────────────────────────────────────────────────────── remarks: Obtains information about the file or directory which was loaded by the most recent 'loadbuf' or 'insertbuf' function call. One of the following options can be specified: d - return the number of subdirectories for a directory load f - return the number of files for a directory load s - return total size of all files for a directory load t - return the load type: 0 for files, 1 for directories returns: Information based on the options specified. see also: insertbuf, loadbuf getmarkbot mark ────────────────────────────────────────────────────────────────────── remarks: Gets the bottommost line of a mark. If 'mark' is not specified, the default markid is assumed. returns: The bottommost line of the mark if successful, otherwise null. see also: getmarkleft, getmarkright, getmarktop getmarkbuf mark ────────────────────────────────────────────────────────────────────── remarks: Retrieves the buffer associated with a mark. If 'mark' is not specified, the default markid is assumed. returns: The bufferid of the buffer associated with the mark if successful, otherwise null. see also: getcurrmark getmarkcols mark ────────────────────────────────────────────────────────────────────── remarks: Gets the width of a mark. For line marks, 16001 is returned. For column, character, and stream marks, the end column minus the start column plus 1 is returned. If 'mark' is not specified, the default markid is assumed. returns: The mark width if successful, otherwise null. see also: getmarkrows getmarkleft mark ────────────────────────────────────────────────────────────────────── remarks: Gets the leftmost column of a mark. For line marks, zero is returned. For character and stream marks, the starting column of the mark is returned. If 'mark' is not specified, the default markid is assumed. returns: The leftmost column of the mark if successful, otherwise null. see also: getmarkbot, getmarkright, getmarktop getmarkright mark ────────────────────────────────────────────────────────────────────── remarks: Gets the rightmost column of a mark. For line marks, 16001 is returned. For character and stream marks, the ending column of the mark is returned. If 'mark' is not specified, the default markid is assumed. returns: The rightmost column of the mark if successful, otherwise null. see also: getmarkbot, getmarkleft, getmarktop getmarkrows mark ────────────────────────────────────────────────────────────────────── remarks: Gets the mark height (the number of lines spanned by the mark). If 'mark' is not specified, the default markid is assumed. returns: The mark height if successful, otherwise null. see also: getmarkcols getmarktop mark ────────────────────────────────────────────────────────────────────── remarks: Gets the topmost line of a mark. If 'mark' is not specified, the default markid is assumed. returns: The topmost line of the mark if successful, otherwise null. see also: getmarkbot, getmarkleft, getmarkright getmarktype mark ────────────────────────────────────────────────────────────────────── remarks: Gets the mark type (column, line, character, or stream). If 'mark' is not specified, the default markid is assumed. returns: A one-byte string indicating the mark type: l - line mark k - column mark c - character mark s - stream mark see also: markchar, markcolumn, markline, markstream getmarkuse ────────────────────────────────────────────────────────────────────── remarks: Gets the default markid. returns: the default markid. see also: usemark getmenu opt=[hwnxym] row menubuffer ────────────────────────────────────────────────────────────────────── remarks: Retrieves information about a menu buffer created with the 'menu' keyword. 'menubuffer' specifies the name of the menu. If 'menubuffer' is null or not specified, then the current buffer is assumed. If 'row' is not specified, then the line at the cursor is assumed. One of the following options can be specified. h - return the menu highlight column for the row m - return TRUE if the buffer is a menu buffer n - return the menu item description text w - return the menu width y - return the cursor row at last menu exit x - return the menu item compiled macro code (if any) returns: Information based on the options specified. see also: menu getmenubar opt=[cfnosw] menubar[1-4] item window ────────────────────────────────────────────────────────────────────── remarks: Retrieves information about a menu bar. If 'window' is not specified, the current window is assumed. 'menubar' (1-4) specifies one of the 4 possible menu bars for a window. If 'menubar' is not specified, 1 is assumed (the primary menu bar). 'item' is an integer specifying the relative position of a menu bar item from the beginning of the menu bar. If 'item' is not specified, the current highlighted menu bar item is assumed. The following options may be specified: c - returns the highlighted character for a menu bar item f - returns the menu bar item function string n - returns the total number of menu bar items o - returns the offset (in columns) of the menu bar item description text from the beginning of the menu bar s - returns the menu bar item description text w - returns the menu bar width (for west menus only) If no options are specified, the current highlighted menu bar item is returned. returns: Information based on the options specified see also: hilitebar, menubar example: getmenubar // returns the currently highlighted item on the // primary menu bar (tests if an item is highlighted) getmenubar 'n' 2 // returns the total number of menu bar items for // menu bar 2 getmenubar 's' '' 3 // returns the description for the third menu bar item // on the primary menu bar getmousex opt=[e] ────────────────────────────────────────────────────────────────────── remarks: Gets the virtual X coordinate of the mouse pointer. If option 'e' is specified, the X coordinate where the last mouse event occurred is returned. returns: the mouse virtual X coordinate see also: getmousex, mousepos getmousey opt=[e] ────────────────────────────────────────────────────────────────────── remarks: Gets the virtual Y coordinate of the mouse pointer. If option 'e' is specified, the Y coordinate where the last mouse event occurred is returned. returns: the mouse virtual Y coordinate see also: getmousey, mousepos getnextwin window opt=[z] ────────────────────────────────────────────────────────────────────── remarks: Gets the window after 'window' the window list. If 'window' is not specified, the current window is assumed. If option 'z' is specified, any window may be returned, otherwise only a window at the same child-level as 'window' is returned. returns: the windowid of the next window if successful, otherwise null. see also: getchild, getprevwin getos opt=[vm] ────────────────────────────────────────────────────────────────────── remarks: Gets the operating system name or the operating system version. One of the following options may be specified: v - return the major OS version number m - return the minor OS version number If no options are specified, the operation system name 'DOS' is returned. returns: The operating system name or version. see also: getversion getpalette position ────────────────────────────────────────────────────────────────────── remarks: Retrieves a color attribute from a 100-byte user-defined palette area defined with the 'setpalette' function. If no position is specified, the entire palette area is returned. The editor library code (LIB.X) expects color attributes to be in the positions defined in COLOR.AML. returns: a numeric color attribute, or the 100-byte palette. see also: setpalatte getparent window ────────────────────────────────────────────────────────────────────── remarks: Gets the parent window of a window. If 'window' is not specified, the current window is assumed. returns: the windowid of the parent window if successful, otherwise null. see also: getchild, setparent getprevbook bookmark ────────────────────────────────────────────────────────────────────── remarks: Gets the bookmark preceding 'bookmark' in the bookmark list for the current buffer. If 'bookmark' is not specified, the current 'bookmark' in the current buffer is assumed. returns: The bookmarkid of the previous bookmark if successful, otherwise null. see also: currbook getprevbuf buffer ────────────────────────────────────────────────────────────────────── remarks: Gets the buffer before 'buffer' in the buffer list. If 'buffer' is null or not specified, then the current buffer is assumed. returns: The previous bufferid, or null if no previous buffer exists. see also: findbuf, getcurrbuf example: buffer = getcurrbuf // cycles through existing while buffer do // buffers buffer = getprevbuf buffer end getprevcurs cursor ────────────────────────────────────────────────────────────────────── remarks: Gets the cursor before 'cursor' in the cursor list for the current buffer. If 'cursor' is not specified, the current 'cursor' in the current buffer is assumed. returns: The cursorid of the previous cursor if successful, otherwise null. see also: currcursor getprevmark mark ────────────────────────────────────────────────────────────────────── remarks: Gets the mark preceding 'mark' in the mark list for the current buffer. If 'mark' is not specified, the default markid is assumed. returns: The markid of the previous mark if successful, otherwise null. see also: currmark getprevwin window opt=[z] ────────────────────────────────────────────────────────────────────── remarks: Gets the window before 'window' the window list. If 'window' is not specified, the current window is assumed. If option 'z' is specified, any window may be returned, otherwise only a window at the same child-level as 'window' is returned. returns: the windowid of the previous window if successful, otherwise null. see also: getchild, getnextwin getrawtime ────────────────────────────────────────────────────────────────────── remarks: Gets the current date and time in a 17 character string. The format of the string is as follows: format: YYYYMMDDWhhmmssuu where: YYYY = year MM = month [1-12] DD = day [1-31] W = day of the week [0-6, 0=sunday] hh = hour [0-23] mm = minutes [0-59] ss = seconds [0-59] uu = hundredths of a second [0-99] returns: The current date and time in raw format. see also: getdate, gettime getregion virtualX virtualY window ────────────────────────────────────────────────────────────────────── remarks: Returns an integer code identifying the region of a window containing the virtual screen coordinate 'virtualX', 'virtualY'. If 'window' is not specified, the current window is assumed. If 'virtualX' and 'virtualY' are not specified, the current mouse position is assumed. This function is useful for determining where a mouse click occurred. The following table shows the integer codes and the corresponding window regions: code region ──── ────── 0 'virtualX', 'virtualY' is not in the window 1 client area 2 north border 3 east border 4 south border 5 west border 6 northwest border corner 7 northeast border corner 8 southeast border corner 9 southwest border corner 11 north title bar 12 south title bar 13 west title 14 east title 19 vertical & horizontal scroll bar intersection 21 vertical scroll bar up arrow 22 vertical scroll bar down arrow 23 vertical scroll bar page-up bar 24 vertical scroll bar page-down bar 25 vertical scroll bar thumb 31 horizontal scroll bar left arrow 32 horizontal scroll bar right arrow 33 horizontal scroll bar page-left bar 34 horizontal scroll bar page-right bar 35 horizontal scroll bar thumb 51 - 100 window title bar controls from left to right 101 - 200 primary menu bar items from left to right 201 - 300 menu bar 2 items from left to right 301 - 400 menu bar 3 items from left to right 401 - 500 menu bar 4 items from left to right 501 - 600 menu bar 5 items from top to bottom returns: a window region code. example: function <lbutton> // determine where a left mouse case getregion // button click occurred when 1 ... // client area? when 11 ... // north title bar? . . end end getrow buffer ────────────────────────────────────────────────────────────────────── remarks: Gets the current line number of the cursor. If 'buffer' is null or not specified, the current buffer is assumed. returns: The current line number of the cursor. see also: getcol, getlines getsettings [Lib][mon] ────────────────────────────────────────────────────────────────────── remarks: Gets the current window settings as they appear on the edit window title bar. See the 'setting' command for a description of window settings. returns: a string containing the current window settings. see also: setting, setting? getstr length x y ────────────────────────────────────────────────────────────────────── remarks: Gets a string of the specified length at the specified x,y position in the current video output window. If x or y are not specified, the current video cursor position is assumed. returns: the string at x,y see also: fillrect, getattr, getx, gety, gotoxy, gotoscreen, hilite, writeline, writestr gettext col length row buffer ────────────────────────────────────────────────────────────────────── remarks: Retrieves text within a line in the specified buffer. If 'buffer' is null or not specified, then the current buffer is assumed. If 'row' is not specified, then the line at the cursor is assumed. If 'col' is not specified, then column 1 is assumed. If 'length' is not specified, then the length from the specified column to the end of the line is assumed. If 'col' is beyond the end of the line, then null is returned. returns: A copy of a line (or portion of the line) if successful, otherwise null. see also: getchar example: gettext // returns the line at the cursor in the current buffer gettext 3 // returns the portion of the current line from // column 3 to the end of the line gettext 3 5 // returns 5 characters at column 3, on the current line // in the current buffer gettext 3 5 20 "abc" // returns 5 characters at column 3, line 20 in the // buffer "abc" gettitle titleid[1-5] window opt=[h] ────────────────────────────────────────────────────────────────────── remarks: Gets a window title string for a window. If 'window' is not specified, the current window is assumed. 'titleid' specifies which window title to retrieve. If 'titleid' is zero, then 1 is assumed (the primary title). If option 'h' is specified, then this function returns the highlighted position within the title string. returns: a window title string. see also: settitle example: gettitle // returns title 1 for the current window gettitle 3 "abc" // returns title 3 for window "abc" gettime ────────────────────────────────────────────────────────────────────── remarks: Gets the current time in the format set by the 'international' function. returns: The current time. see also: getdate, getrawtime getversion ────────────────────────────────────────────────────────────────────── remarks: Gets the current version of the editor. returns: The current version (major and minor) of the editor as a string. see also: getexe, getos getvidbot ────────────────────────────────────────────────────────────────────── remarks: Gets the virtual coordinate of the bottommost row of the physical screen. returns: the bottom edge of the physical screen. see also: getvidleft, getvidright, getvidrows, getvidtop getvidcols ────────────────────────────────────────────────────────────────────── remarks: Gets the number of columns on the screen. returns: the number of columns on the screen. see also: getvidleft, getvidright, getvidrows getvidleft ────────────────────────────────────────────────────────────────────── remarks: Gets the virtual coordinate of the leftmost column of the physical screen. returns: the left edge of the physical screen. see also: getvidbot, getvidcols, getvidright, getvidtop getvidright ────────────────────────────────────────────────────────────────────── remarks: Gets the virtual coordinate of the rightmost column of the physical screen. returns: the right edge of the physical screen. see also: getvidbot, getvidcols, getvidleft, getvidtop getvidrows ────────────────────────────────────────────────────────────────────── remarks: Gets the number of rows on the screen. returns: the number of rows on the screen. see also: getvidbot, getvidcols, getvidtop getvidtop ────────────────────────────────────────────────────────────────────── remarks: Gets the virtual coordinate of the topmost row of the physical screen. returns: the top edge of the physical screen. see also: getvidbot, getvidleft, getvidright, getvidrows getviewbot window ────────────────────────────────────────────────────────────────────── remarks: Gets the line number of the bottommost visible row in a window. If 'window' is not specified, the current window is assumed. returns: the bottommost visible row in a window. see also: getviewleft, getviewright, getviewtop getviewcols window ────────────────────────────────────────────────────────────────────── remarks: Gets the number of visible columns in a window. If 'window' is not specified, the current window is assumed. returns: the number of visible columns. see also: getviewleft, getviewright, getviewrows getviewleft window ────────────────────────────────────────────────────────────────────── remarks: Gets the leftmost column in a window. If 'window' is not specified, the current window is assumed. returns: the leftmost column in a window. see also: getviewbot, getviewright, getviewtop getviewright window ────────────────────────────────────────────────────────────────────── remarks: Gets the rightmost visible column in a window. If 'window' is not specified, the current window is assumed. returns: the rightmost visible column in a window. see also: getviewbot, getviewleft, getviewtop getviewrows window ────────────────────────────────────────────────────────────────────── remarks: Gets the number of visible rows in a window. If 'window' is not specified, the current window is assumed. returns: the number of visible rows. see also: getviewbot, getviewcols, getviewtop getviewtop window ────────────────────────────────────────────────────────────────────── remarks: Gets the line number of the topmost row in a window. If 'window' is not specified, the current window is assumed. returns: the topmost row in a window. see also: getviewbot, getviewleft, getviewright getwinbuf window ────────────────────────────────────────────────────────────────────── remarks: Gets the buffer associated with a window. If 'window' is not specified, the current window is assumed. returns: the bufferid associated with the window is successful, otherwise null. see also: getwincurs, setwincurs getwincount window ────────────────────────────────────────────────────────────────────── remarks: Gets the number of windows on the screen. If 'window' is specified, this function returns the number of child windows attached to 'window'. returns: the number of windows on the screen, or the number of child windows attached to a window. see also: getchild, setparent getwinctrl n window ────────────────────────────────────────────────────────────────────── remarks: Gets the 'nth' title bar control for a window. If 'window' is not specified, the current window is assumed. returns: a one-character title bar control see also: setwinctrl getwincurs window ────────────────────────────────────────────────────────────────────── remarks: Gets the cursor associated with a window. If 'window' is not specified, the current window is assumed. Only cursors associated with a buffer are returned. returns: the cursorid of the window cursor if successful, otherwise null. see also: getwinbuf, setwincurs getwinobj window ────────────────────────────────────────────────────────────────────── remarks: Gets the event object associated with a window. If 'window' is not specified, the current window is assumed. returns: the window event object. see also: setwinobj getwinscr virtualX virtualY window ────────────────────────────────────────────────────────────────────── remarks: Translates a virtual x,y coordinate in a scroll bar to a column or row in a window. If 'window' is not specified, the current window is assumed. This function can be used to translate a mouse pointer position in a scroll bar to a position in a window. returns: A window column if virtualX, virtualY lies within a horizontal scroll bar, or a window row if virtualX, virtualY lies within a vertical scroll bar, otherwise null. see also: getviewbot, getviewleft, getviewright, getviewtop getx ────────────────────────────────────────────────────────────────────── remarks: Gets the cursor column in the current video window. This function is ignored for windows which contain a buffer. returns: the cursor column in the current video window see also: fillrect, getattr, getstr, gety, gotoxy, gotoscreen, hilite, writeline, writestr gety ────────────────────────────────────────────────────────────────────── remarks: Gets the cursor row in the current video window. This function is ignored for windows which contain a buffer. returns: the cursor row in the current video window see also: fillrect, getattr, getstr, getx, gotoxy, gotoscreen, hilite, writeline, writestr gotobar item [Lib][edit_fmgr] ────────────────────────────────────────────────────────────────────── remarks: Activates the specified menu bar item from the primary menu bar. 'item' specifies the menu bar item or the menu bar description text. returns: nothing see also: getmenubar, gotobar2, menubar example: gotobar 1 // highlights the 'File' menu bar item gotobar "File" // highlights the 'File' menu bar item gotobar2 item [Lib][edit_fmgr] ────────────────────────────────────────────────────────────────────── remarks: Activates the specified menu bar item on the toolbar of an edit window, or the drive bar of a file manager window. 'item' specifies the menu bar item or the menu bar description text. returns: nothing see also: getmenubar, gotobar, menubar gotobook bookmark ────────────────────────────────────────────────────────────────────── remarks: Moves the cursor to a bookmark. Only the current cursor in the buffer associated with the bookmark is moved. If 'bookmark' is not specified, the current 'bookmark' in the current buffer is assumed. returns: TRUE if successful, otherwise null. see also: getcurrbook, setbook gotobuf buffer ────────────────────────────────────────────────────────────────────── remarks: Makes the specified buffer the current buffer. If 'buffer' is not specified, the buffer at the top of the buffer list becomes the current buffer. Unlike the 'currbuf' function, the position of the buffer in the buffer list is not changed. returns: The previous current buffer if successful, otherwise null. see also: currbuf, findbuf, getcurrbuf example: oldbuffer = gotobuf 'abc' // switch to buffer 'abc' . . gotobuf oldbuffer // switch back to the old buffer gotomatch char-pairs [Lib][a] ────────────────────────────────────────────────────────────────────── remarks: Finds the matching character for a character specified in 'char-pairs'. returns: Non-zero if found, otherwise null. example: gotomatch "(){}[]<>" gotomenu pulldown [Lib][edit_fmgr] ────────────────────────────────────────────────────────────────────── remarks: Displays the specified pulldown menu from the primary menu bar. 'pulldown' specifies the menu bar item or menu bar item description for the pulldown menu. returns: nothing see also: getmenu, menu, submenu example: gotomenu 1 // displays the 'File' pulldown menu gotomenu "File" gotopos col row buffer ────────────────────────────────────────────────────────────────────── remarks: Moves the cursor to the specified column and row. If 'buffer' is null or not specified, the current buffer is assumed. returns: TRUE if successful, otherwise null. see also: col row movepos example: gotopos 1 1 // moves the cursor to column one of the first line gotoscreen ────────────────────────────────────────────────────────────────────── remarks: Changes all video functions to operate immediately on the actual physical screen. The physical screen becomes the current window for all builtin video functions. Column 1 and row 1 are located at the upper left corner of the screen. This function can be used to perform custom drawing of the display. returns: nothing see also: fillrect, getattr, getstr, getx, gety, gotowindow, gotoxy, hilite, writeline, writestr gotowindow window ────────────────────────────────────────────────────────────────────── remarks: Makes the specified window the current window. If 'window' is not specified, the topmost window on the screen becomes the current window. Note that this function does not change the ordering of windows on the screen. It changes the 'current' or default window referenced in builtin window functions. returns: The previous current window if successful, otherwise null. see also: getcurrwin, gotoscreen gotoxy col row ────────────────────────────────────────────────────────────────────── remarks: Moves the cursor to the specified column and row in the current video window. This function is ignored for windows which contain a buffer. returns: nothing see also: fillrect, getattr, getstr, getx, gety, gotoscreen, hilite, writeline, writestr groupbox title x y buffer width initvalue valuemap [Lib][a] ────────────────────────────────────────────────────────────────────── remarks: Adds a group box window control to the current dialog box. The group box window becomes the current window. The group box may contain check boxes or radio buttons. The following parameters may be specified: title - the group box title x - the group box x-position in the dialog box y - the group box y-position in the dialog box buffer - the menu buffer to display in the group box width - the group box width (if not specified, the title width or widest menu item width is used, whichever is widest) initvalue - the values (if any) used to intialize the group box. Initial values are entered as a string of one-character codes, with each character representing a checked menu item from a string of possible choices specified by the 'valuemap' argument. If 'initvalue' is not specified, the first menu item is checked. valuemap - a string of possible choices of one-character codes for 'initvalue', which each character representing a menu item. The first character in the string represents the first menu item, the second character represents the second menu item, and so on. A group box menu item is a check box if the characters '[ ]' are the the first 4 characters in the menu item. The menu item is a radio button if the characters ' ( )' are the the first 4 characters in the menu item. returns: The group box window id. see also: button, dialog, field, listbox, setgroupbox, whenenter, whenselect example: dialog "Test Dialog Box" 40 8 // create a dialog box groupbox 'Group Box:' 22 2 ( menu '' item " [ ] &Apples" item " [ ] &Oranges" item " [ ] &Melons" item " [ ] &Bananas" end ) 15 'am' 'aomb' // add a group box containing check boxes, initially // checking the first and third menu items getdialog // display the dialog box halt ────────────────────────────────────────────────────────────────────── remarks: Terminates the execution of the editor immediately and unconditionally. returns: nothing see also: delay, exec hex2bin hexstring ────────────────────────────────────────────────────────────────────── remarks: Converts a hexadecimal string, composed of only the characters 0-9 and A-F, to a binary string. returns: a binary string. see also: bin2hex example: hex2bin "61" // returns 'a' hex2bin "616263" // returns 'abc' hidebuf buffer ────────────────────────────────────────────────────────────────────── remarks: Hides a buffer from the 'getprevbuf' function. If 'buffer' is null or not specified, then the current buffer is assumed. This function can used to prevent temporary or internal buffers from being displayed on editor buffer lists. returns: nothing see also: getprevbuf hidecursor ────────────────────────────────────────────────────────────────────── remarks: Hides the physical cursor in the current window. If the current window contains a buffer, the effects of this function are temporary and will disappear the next time the display is updated. returns: nothing see also: showcursor hidemouse ────────────────────────────────────────────────────────────────────── remarks: Hides the mouse pointer. returns: nothing see also: showmouse hidewindow window ────────────────────────────────────────────────────────────────────── remarks: Hides a window temporarily. If 'window' is null or not specified, then the current window is assumed. The window will be shown again the next time the display is updated. returns: nothing see also: showwindow hilite length height color col row ────────────────────────────────────────────────────────────────────── remarks: Highlights a rectangular area in the current window with the specified color attribute. 'length' and 'height' specify the dimensions of the highlighted rectangle. 'col' and 'row' specify the upper left corner of the rectangle. If 'col' and 'row' are not specified, the current cursor position is assumed. If the current window displays a buffer, the effects of this function are temporary and will disappear the next time the display is updated. If the current window does not display a buffer and the 'height' is 1, the current cursor position is moved to the right of the highlighted area. returns: nothing see also: fillrect, getattr, getstr, getx, gety, gotoscreen, gotoxy, writeline, writestr example: hilite 6 1 95 // highlights a word at the cursor of length 6 // with the color 'white on magenta' hilitebar menubar[1-4] item window ────────────────────────────────────────────────────────────────────── remarks: Highlights or un-highlights a menu bar item in a window. There can only be one highlighted item per menu bar. If 'window' is not specified, the current window is assumed. 'menubar' specifies one of the 4 available menu bars in the window. If 'menubar' is not specified, 1 is assumed (the primary menu bar). 'item' indicates the relative position of the menu bar item from the beginning of the menu bar (1 for the first item, 2 for the second item, and so on). If 'item' is null or zero, then the highlight is removed from any currently highlighted item in the menu bar. returns: If successful, the offset (in character positions) of the specified menu bar item from the beginning of the menu bar, otherwise null. see also: getmenubar, menubar example: hilitebar // removes the highlight from the primary menu bar hilitebar 2 5 // highlights item 5 on menu bar 2 icompare string1 string2 ... ────────────────────────────────────────────────────────────────────── remarks: Tests if 'string1' is equal to any of the following arguments, ignoring case. returns: TRUE if the comparison succeeds, otherwise null. see also: flipcase, locase, upcase example: icompare "apples" "Apples" // returns TRUE icompare "apples" "oranges" // returns null includemacro filename arg2 arg3 ... ────────────────────────────────────────────────────────────────────── remarks: Loads the compiled macro code in the file 'filename' and executes it in the current event object. The 'filename' is passed to the macro as the first argument, followed by the optional arguments 'arg2', 'arg3', etc. returns: The return value from executing the macro. see also: compilemacro, eval, runmacro example: includemacro "C:\\AURORA\\MACRO\\MYMACRO.X" inheritfrom objexpression1 objexpression2 ... ────────────────────────────────────────────────────────────────────── remarks: Sets the inheritance path of the current object to the specified objects. After this function is called, the current object will inherit functions and object variables from the objects specified by objexpression1, objexpression2, etc. returns: nothing see also: inheritkeys, object, objtype? example: inheritfrom "win" // the current object now inherits functions and // object variables from the object 'win' inheritkeys [0/1] object ────────────────────────────────────────────────────────────────────── remarks: Enables (1) or disables (0) the inheritance of keyboard events for the specified object. If 'object' is not specified, then the current object is assumed. When an object is initially created, keyboard inheritance is enabled. returns: nothing see also: inheritfrom, object, objtype? inmark? col row buffer ────────────────────────────────────────────────────────────────────── remarks: Tests if the specified column and row position lies within a mark. If 'col' and 'row' are not specified, then the current cursor position is assumed. If 'buffer' is not specified, the current buffer is assumed. returns: The topmost markid containing 'col','row', otherwise null. see also: mark? example: if inmark? then // if cursor is within a mark deleteblock // then delete the mark text else // otherwise.. delchar // delete the char at the cursor end insabove string col row buffer ────────────────────────────────────────────────────────────────────── remarks: Inserts a new line containing the specified string into a buffer. If 'buffer' is null or not specified, then the current buffer is assumed. If 'row' is specified, the new line is inserted before the specified row, otherwise the new line is inserted before the line at the cursor. If 'col' is specified, the string is placed at the specified column, otherwise the string is placed at column 1. returns: TRUE if successful, otherwise null. see also: addline, delline, insline, joinline, splitline example: insabove // inserts a new line above the line at the cursor // in the current buffer insabove "New line" 1 6 // inserts a new line with the text " New line" // above line 6 in the current buffer insabove "New line" 1 1 "abc" // inserts a new line with the text "New line" // above line 1 in the buffer "abc" insert? buffer ────────────────────────────────────────────────────────────────────── remarks: Tests if the cursor is in insert or overstrike mode. If 'buffer' is null or not specified, the current buffer is assumed. returns: TRUE if the cursor is in insert mode, otherwise null. see also: setcursor, writetext insertbuf filespec buffer delim/binlen opt=[bdfhkx] trunc comment linenumber ────────────────────────────────────────────────────────────────────── remarks: Inserts a file or directory into an existing buffer. If 'buffer' is null or not specified, the current buffer is assumed. The file is inserted after the line 'linenumber'. If 'linenumber' is not specified, then the file is loaded after the current cursor position in the buffer. All other arguments and options are identical to the 'loadbuf' function (see the 'loadbuf' function). returns: The bufferid if successful, otherwise null. see also: asciibuf, createbbuf, createbuf, destroybuf, getloadinfo, loadbuf, menu example: insertbuf "c:\\file.txt" // loads "c:\file.txt" into the current buffer after // the current line in the buffer insertbuf "c:\\file.txt" "abc" 32 'b' '' '' 1000 // loads "c:\file.txt" with a binary line length // of 32, and inserts it after line 1000 of the // buffer "abc" insline string col row buffer ────────────────────────────────────────────────────────────────────── remarks: Inserts a new line containing the specified string into a buffer. If 'buffer' is null or not specified, then the current buffer is assumed. If 'row' is specified, the new line is inserted after the specified row, otherwise the new line is inserted after the line at the cursor. If 'col' is specified, the string is placed at the specified column, otherwise the string is placed at column 1. returns: TRUE if successful, otherwise null. see also: addline, delline, insabove, joinline, splitline example: insline // inserts a new line after the line at the cursor // in the current buffer insline "New line" 1 (getlines) // inserts a new line with the text "New line" // after the last line in the current buffer insline "New line" 1 1 "abc" // inserts a new line with the text "New line" // after line 1 in the buffer "abc" instext string col row buffer ────────────────────────────────────────────────────────────────────── remarks: Inserts the specified string into a buffer at the specified row and column. If 'buffer' is null or not specified, the current buffer is assumed. If 'col' and 'row' are not specified, then the string is inserted at the current cursor position. returns: TRUE if successful, otherwise null. see also: delchar, ovltext example: instext "some text" // inserts 'some text' at the cursor in the current // buffer instext "some text" 2 20 // inserts 'some text' at column 2, line 20 in the // current buffer instext "some text" 1 1 "abc" // inserts 'some text' at column 1, line 1 in the // buffer 'abc' international dateformat dateseparator timeformat timeseparator thousandsseparator ────────────────────────────────────────────────────────────────────── remarks: Defines international system settings. The following settings can be specified: dateformat - The date format to use [0-2]: 0 = mmddyy 1 = ddmmyy 2 = yymmdd dateseparator - The character used to separate days, months, and years timeformat - The time format to use [0-3]: 0 = 12hr 1 = 24hr 2 = 12hr with seconds 3 = 24hr with seconds timeseparator - The character used to separate hours, minutes, and seconds thousandsseparator - The character used to separate thousands-groups in large numbers returns: nothing see also: getdate, gettime, thousands joinline col row buffer ────────────────────────────────────────────────────────────────────── remarks: Joins two lines into one line in a buffer. If 'buffer' is null or not specified, then the current buffer is assumed. 'row' specifies the first of two lines to be joined, and 'col' specifies the column in the first line where the second line is to be appended. If 'col' is less than or equal to the length of the first line, then the second line is appended to the end of the first line. If 'row' and 'col' are not specified, the current cursor position is assumed. returns: TRUE if successful, otherwise null. see also: delline, insabove, insline, splitline example: joinline // joins the line below the cursor to the current line // at the cursor position in the current buffer joinline 1 // appends the line below the cursor to the current line // in the current buffer joinstr delimit+quote string1 string2 ... ────────────────────────────────────────────────────────────────────── remarks: This function joins any number of strings together into an editor 'multistring'. This differs from normal string concatenation in the following ways: - The delimiter character 'delimit' is inserted between the component strings. - The character 'quote' is inserted before any occurrences of the 'delimit' character or the 'quote' character in the resulting string. If the 'delimit' or 'quote' character are not specified, then the default delimiter character is a slash (/) and the default quote character is a backquote (`). returns: a multistring see also: splitstr example: joinstr '' "abc" "def" "xyz" // returns "abc/def/xyz" joinstr '' "abc" "d/ef" "xyz" // returns "abc/d`/ef/xyz" joinstr "|\\" "abc" "x|yz" // returns "abc|x\|yz" justblock opt=[clr] mark leftmarg rightmarg ────────────────────────────────────────────────────────────────────── remarks: Left justifies, right justifies, or centers marked text. If 'mark' is not specified, the default markid is assumed. For column marks, the text is justified to fit between the left and right edges of the mark. For all other marks, the text is justified to fit between 'leftmarg' and 'rightmarg'. One of the following options may be specified: c - center the text l - left justify the text r - right justify the text If no options are specified, then 'l' is assumed. returns: TRUE if successful, otherwise null. see also: formatblock kbdoptions opt=[egw] ────────────────────────────────────────────────────────────────────── remarks: Sets various keyboard options. Any of the following options may be specified: e - enable enhanced keyboard keys g - enable unshifted grey keypad function keys (<grey*>, <grey->, <grey+>) w - enable shifted white keypad function keys (<shift del>, <shift ins>, <shift end>, etc.) returns: nothing keyhit? ────────────────────────────────────────────────────────────────────── remarks: Test if non-shift key has been pressed. returns: TRUE if a key has been pressed and not processed, otherwise null. see also: event?, shiftkey? lastpos buffer ────────────────────────────────────────────────────────────────────── remarks: Moves the cursor to the last cursor position. If 'buffer' is null or not specified, the current buffer is assumed. returns: TRUE if successful, otherwise null. see also: gotopos left cols buffer ────────────────────────────────────────────────────────────────────── remarks: Moves the cursor to the left. 'cols' specifies the number of columns to move. If 'cols' is not specified, 1 is assumed. If 'buffer' is null or not specified, the current buffer is assumed. returns: TRUE if successful, otherwise null. see also: down, right, up example: left // moves the cursor left 1 column left 5 // moves the cursor left 5 columns lineflag opt=[m-] row buffer ────────────────────────────────────────────────────────────────────── remarks: Turns line flags ON or OFF. If 'buffer' is null or not specified, the current buffer is assumed. If 'row' is not specified, the line at the cursor is assumed. The following flags can be specified: m - line 'dirty' or modified flag - - turns off flags If option '-' is specified, any other specified flags will be turned off, otherwise all specified flags will be turned on. returns: nothing see also: bufferflag, bufferflag?, lineflag? example: lineflag "-m" // turns off the modified flag for the current buffer lineflag? opt=[m] row buffer ────────────────────────────────────────────────────────────────────── remarks: Tests if line flags are ON. If 'buffer' is null or not specified, the current buffer is assumed. If 'row' is not specified, the line at the cursor is assumed. The following flags can be specified: m - line 'dirty' or modified flag returns: non-zero if any of the specified line flags are ON, otherwise null. see also: bufferflag, bufferflag?, lineflag listbox title x y buffer width height [Lib][a] ────────────────────────────────────────────────────────────────────── remarks: Adds a list box window control to the current dialog box. The listbox window becomes the current window. A list box displays a buffer in scrollable window, allowing a line to be selected from the buffer. The following parameters may be specified: title - the list box title x - the list box x-position in the dialog box y - the list box y-position in the dialog box buffer - the buffer to display in the list box width - the list box width (if not specified, the title width is used) height - the list box height (if not specified, the number of lines in the buffer is used) returns: The group box window id. see also: button, dialog, field, groupbox, whenenter, whenselect example: dialog "Test Dialog Box" 40 17 // create a dialog box listbox "&Listbox:" 3 2 (loadbuf "C:\\*.*") 16 12 // add a list box displaying a directory of drive C getdialog // display the dialog box loadbuf filespec buffer delim/binlen opt=[bdhkx1] trunc comment ────────────────────────────────────────────────────────────────────── remarks: Loads the specified file or directory into a new buffer. If 'buffer' is null or not specified, a unique bufferid will be assigned. The new buffer will become the current buffer. The buffer name of the new buffer will automatically be set to 'filespec'. The 'setbufname' function is generally not required (see 'setbufname'). The following options may be specified: b - loads the file in binary mode. The third argument specifies the binary line length. d - includes subdirectories when loading directories h - includes hidden/system files when loading directories k - shows file sizes in 1k increments when loading directories x - disables conversion of fold comments to folds 1 - sorts subdirectories first when loading directories If option 'b' is specified, the file is loaded in binary mode and the third argument specifies a fixed binary line length. If the third argument is not specified, the default binary line length is 64. If option 'b' is not specified, the third argument specifies a 1 or 2 byte line delimiter string to use. If the third argument is not specified, a line delimiter of 0D0Ah (CR/LF) is assumed. The argument 'trunc' specifies the length at which lines are truncated. If 'trunc' is zero or not specified, the editor maximum (16000) is assumed. The argument 'comment' specifies the fold comment string to look for when converting fold comments to text folds during the loading process. Specifying option 'x' disables the conversion. Note: this function will not display the new buffer in a window. The 'openbuf' or 'popup' library functions should be used to display the buffer. returns: The new bufferid if successful, otherwise null. see also: asciibuf, createbbuf, createbuf, destroybuf, getloadinfo, insertbuf, menu, popup, setbufname example: loadbuf "c:\\file.txt" // loads 'c:\file.txt' into a new buffer (using line // delimiter CR/LF) and returns a unique bufferid loadbuf "c:\\file.txt" "abc" // loads 'c:\file.txt' into a new buffer with the // bufferid 'abc' loadbuf "c:\\file.txt" '' (hex2bin "0A") // loads 'c:\file.txt' into a new buffer using line // delimiter '0A' (LF) and returns a unique bufferid loadbuf "c:\\file.txt" '' 25 'b' // loads 'c:\file.txt' into a new binary buffer with // a fixed line length of 25 and returns a unique // bufferid locase string ────────────────────────────────────────────────────────────────────── remarks: Converts a string to lowercase. returns: the string in lowercase. see also: upcase flipcase example: locase "PEACHES" // returns "peaches" locatefile filename path opt=[d] ────────────────────────────────────────────────────────────────────── remarks: Searches a path for a filename. 'path' can be a sequence of paths separated by semicolons (;) (as specified in the DOS 'PATH' environment string). If option 'd' is specified, then 'filename' must be a directory and the path is searched for directories only. This function returns the fully qualified filename or directory if found, otherwise it returns null. returns: TRUE if successful, otherwise null. see also: createdir, scanfile example: locatefile "FILE.TXT" "C:\\" // returns C:\FILE.TXT, if FILE.TXT is found in C:\ locatefile "FILE.TXT" (getenv "PATH") // returns FILE.TXT (fully qualified), if FILE.TXT is // found in the DOS PATH locatefile "MACROS" "D:\\AURORA" 'd' // returns D:\MACROS\AURORA, if MACROS is a directory // in D:\AURORA lookup varexpression objexpression opt=[e] ────────────────────────────────────────────────────────────────────── remarks: Gets the value of an object variable defined by 'varexpression' in the object defined by 'objexpression'. If 'objexpression' is not specified, the current object is assumed. If option 'e' is specified, then this function only tests for the existence of the object variable. returns: If option 'e' is not specified, this function returns the value of an object variable. If option 'e' is specified, this function returns non-zero if the object variable exists, otherwise it returns null. see also: function?, set, setobj, setx, setxfun, setxobj, unsetx example: lookup "VidCols" lookup "Vid" + "Cols" "prf" lookup variable // returns the value of an object variable whose // name is the value of 'variable' mark? mark ────────────────────────────────────────────────────────────────────── remarks: Tests if a mark exists. If 'mark' is not specified, then the default markid is assumed. returns: TRUE if the mark exists, otherwise null. see also: inmark? markchar startcol endcol toprow botrow mark buffer ────────────────────────────────────────────────────────────────────── remarks: Creates, extends, or modifies a character mark. A character mark designates a stream of one or more characters in a buffer. If 'buffer' is null or not specified, the current buffer is assumed. If 'mark' is not specified, the default markid is assumed. If the mark does not exist then a new mark is created. If the mark already exists and is not located in the specified buffer, then it is moved there. The mark will be sized to span from 'startcol','toprow' to 'endcol','botrow'. If none of these are specified, then the cursor line and column are assumed and the mark is left 'open' (moving the cursor resizes the mark). If the mark was already open, then it is closed. returns: The markid of the new mark if created, otherwise null. see also: destroymark, extendmark, markcolumn, markline, markstream, stopmark example: markchar // marks the character at the cursor using the default // markid and leaves the mark 'open'. markcolumn leftcol rightcol toprow botrow mark buffer ────────────────────────────────────────────────────────────────────── remarks: Creates, extends, or modifies a rectangular column mark. If 'buffer' is null or not specified, then the current buffer is assumed. If 'mark' is not specified, the default markid is assumed. If the mark does not exist then a new mark is created. If the mark already exists and is not located in the specified buffer, then it is moved there. The mark will be sized to span from 'leftcol','toprow' to 'rightcol','botrow'. If none of these are specified, then the cursor line and column are assumed and the mark is left 'open' (moving the cursor resizes the mark). If the mark was already open, then it is closed. returns: The markid of the new mark if created, otherwise null. see also: destroymark, extendmark, markchar, markline, markstream, stopmark example: markcolumn // marks the character at the cursor using the default // markid and leaves the mark 'open'. markcolumn 1 1 1 (getlines) // marks the first column of the entire buffer using // the default markid markline toprow botrow mark buffer ────────────────────────────────────────────────────────────────────── remarks: Creates, extends, or modifies a line mark. If 'buffer' is null or not specified, then the current buffer is assumed. If 'mark' is not specified, the default markid is assumed. If the mark does not exist then a new mark is created. If the mark already exists and is not located in the specified buffer, then it is moved there. The mark will be sized to span from 'toprow' to 'botrow'. If 'toprow' and 'botrow' are not specified, then the line at the cursor is assumed and the mark is left 'open' (moving the cursor resizes the mark). If the mark was already open, then it is closed. returns: The markid of the new mark if created, otherwise null. see also: destroymark, extendmark, markchar, markcolumn, markstream, stopmark example: markline // marks the current line in the current buffer using // the default markid, and leaves the mark 'open' markline 1 (getlines) // marks the entire buffer using the default markid markline '' '' 'T' // marks the current line using the markid 'T' markstream startcol endcol toprow botrow mark buffer ────────────────────────────────────────────────────────────────────── remarks: Creates, extends, or modifies a stream mark. A stream mark designates a stream of zero or more characters in a buffer and does not include 'endcol' on the row 'botrow'. If 'buffer' is null or not specified, then the current buffer is assumed. If 'mark' is not specified, the default markid is assumed. If the mark does not exist then a new mark is created. If the mark already exists and is not located in the specified buffer, then it is moved there. The mark will be sized to span from 'startcol','toprow' to 'endcol','botrow'. If none of these are specified, then the cursor line and column are assumed and the mark is left 'open' (moving the cursor resizes the mark). If the mark was already open, then it is closed. returns: The markid of the new mark if created, otherwise null. see also: destroymark, extendmark, markchar, markcolumn, markline, stopmark example: markstream // opens a stream mark at the cursor position with the // default markid. Characters will not be marked // until the cursor is moved. max? window [Lib][a] ────────────────────────────────────────────────────────────────────── remarks: Tests if a window is maximized. If 'window' is not specified, the current window is assumed. returns: TRUE if the window is maximized, otherwise null. see also: min? maxems size ────────────────────────────────────────────────────────────────────── remarks: Specifies the maximum amount of EMS memory the editor may use, in 1K increments. If -1 is specified, the maximum available EMS will be used. All available XMS memory will be used before EMS memory is used. Note: this function may only be called once during an edit session. An EMS driver must be installed before EMS memory can be used. returns: Non-zero if successful, otherwise zero. see also: maxxms, memoptions, swapfiles maximize window [Lib][a] ────────────────────────────────────────────────────────────────────── remarks: Maximizes the specified window. If 'window' is not specified, the current window is assumed. returns: nothing see also: max?, min?, minimize, restore maxxms size-in-K ────────────────────────────────────────────────────────────────────── remarks: Specifies the maximum amount of XMS memory the editor may use, in 1K increments. If -1 is specified, the maximum available XMS will be used. Note: this function may only be called once during an edit session. An XMS driver must be installed before XMS memory can be used. returns: Non-zero if successful, otherwise zero. see also: maxems, memoptions, swapfiles memoptions opt=[o] ────────────────────────────────────────────────────────────────────── remarks: Specifies memory usage options. The following options may be specified: o - allows large files to left open after loading (this can increase performance when loading large files). returns: nothing see also: maxems, maxxms, swapfiles min? window [Lib][a] ────────────────────────────────────────────────────────────────────── remarks: Tests if a window is minimized. If 'window' is not specified, the current window is assumed. returns: TRUE if the window is minimized, otherwise null. see also: max? minimize window [Lib][a] ────────────────────────────────────────────────────────────────────── remarks: Minimizes the specified window. If 'window' is not specified, the current window is assumed. returns: nothing see also: max?, maximize, min?, restore mono? ────────────────────────────────────────────────────────────────────── remarks: Tests if the editor is operating in monochrome mode. returns: TRUE if the editor is in monochrome mode, otherwise null. mousepos virtualX virtualY ────────────────────────────────────────────────────────────────────── remarks: Moves the mouse pointer to the specified virtual X and virtual Y coordinates on the screen. returns: nothing see also: getmousex, getmousey, openmouse example: mousepos 16000 16000 // moves the mouse pointer to the upper left // of the virtual screen at startup mousepos 15999 + getvidcols 15999 + getvidrows // moves the mouse pointer to the lower right // of the virtual screen at startup mousesense horz vert doublespeed ────────────────────────────────────────────────────────────────────── remarks: Changes the mouse sensitivity by setting the horizontal mickey-to-pixel and vertical mickey-to-pixel ratios, and by setting the double speed threshold. The default mouse sensitivity after calling 'openmouse' are: Horz mickey-to-pixel ratio: 8 Vert mickey-to-pixel ratio: 16 Double speed threshold: 64 Lower numbers for these parameters result in increased sensitivity. returns: nothing see also: openmouse example: mousesense 5 12 50 // more sensitive mouse moveblock mark buffer col row ────────────────────────────────────────────────────────────────────── remarks: Moves marked text after the specified column and row position in the specified buffer. The text is inserted at the new position and the mark is moved to the new position. If 'mark' is not specified, the default markid is assumed. If 'buffer' is null or not specified, the current buffer is assumed. If 'col' and 'row' are not specified, the current cursor position is assumed. returns: TRUE if successful, otherwise null. see also: copyblock, copyblockover movepos (+/-)cols (+/-)rows buffer ────────────────────────────────────────────────────────────────────── remarks: Moves the cursor a relative number of columns and rows away from the current position. If 'buffer' is null or not specified, the current buffer is assumed. returns: TRUE if successful, otherwise null. see also: col, down, gotopos, left, right, row, up example: movepos 2 3 // moves the cursor right 2 columns and down 3 rows movewindow x y opt=[acdrswz1] window relativewindow ────────────────────────────────────────────────────────────────────── remarks: Changes the position of a window. If 'window' is not specified, the current window is assumed. 'x' and 'y' specify the new window coordinates. See the 'sizewindow' function for a description of the coordinates and available options. This call is nearly identical to the 'sizewindow' function, except that only the position of the window can be changed. returns: TRUE if successful, otherwise null. see also: getcoord, sizewindow msgbox message title opt=[b] [Lib][a] ────────────────────────────────────────────────────────────────────── remarks: Displays the specified message in a popup window with an 'Ok' button. If a title is not specified, 'Message' is assumed. If option 'b' is specified, the PC speaker beeps. returns: nothing see also: okbox, say, shortbox, yncbox example: msgbox "Hello World" nextfile [Lib][edit] ────────────────────────────────────────────────────────────────────── remarks: Makes the next buffer in the buffer list the current buffer, and displays it in the current edit window. The buffer previously displayed in the edit window will not be destroyed. returns: nothing see also: filelist, prevfile nexthist [Lib][prompt] ────────────────────────────────────────────────────────────────────── remarks: Displays the next history string in a prompt. This function is only for use within prompts. returns: nothing see also: gethistname, prevhist nextwindow [Lib][win] ────────────────────────────────────────────────────────────────────── remarks: Switches the focus to the next window on the screen. returns: nothing see also: prevwindow object? object ────────────────────────────────────────────────────────────────────── remarks: Tests if an object exists. If 'object' is not specified, then the current object is assumed. returns: TRUE if the object exists, otherwise null. see also: destroyobject, object, objtype? objtype? parentobj object ────────────────────────────────────────────────────────────────────── remarks: Tests if the object 'parentobj' is located in the inheritance path of the specified object. If 'object' is not specified, the current object is assumed. returns: TRUE if 'parentobj' is a parent object of 'object', otherwise null. see also: inheritfrom, object, object?, wintype? okbox message title [Lib][a] ────────────────────────────────────────────────────────────────────── remarks: Displays the specified message in a popup window with 'Ok' and 'Cancel' buttons. If a title is not specified, 'Message' is assumed. returns: The name of the button pressed (Ok or Cancel), or null if no button was pressed. see also: msgbox, say, shortbox, yncbox example: if (okbox "Delete the file?" "Delete") == 'Ok' then . . end onalarm [Lib] ────────────────────────────────────────────────────────────────────── remarks: This user-defined function is called by the editor library code (LIB.X) when sounding the PC speaker to call attention to a message. This function can be used to customize the alarm sound. 'onalarm' is called directly in the current event object and is not passed any parameters. returns: none required example: function onalarm // customized alarm sound beep 950 30 beep 750 30 end onclose [Lib] ────────────────────────────────────────────────────────────────────── remarks: This user-defined function is called by the editor library code (LIB.X) when a file or file manager window is closed and removed from memory. 'onclose' is called directly in the current event object and is not passed any parameters. returns: none required see also: onfocus, onopen, onsave example: see the configuration file EXT.AML oncomment filename comment1 comment2 [Lib][a] ────────────────────────────────────────────────────────────────────── remarks: This user-defined function is called by the editor library (LIB.X) and extension code (EXT.AML) to return the language comments associated with a filename. 'oncomment' is called directly in the current event object and is passed the filename as the first argument. 'comment1' and 'comment2' are passed by reference and should be modified within 'oncomment' to return comment symbols. returns: comment1 and comment2 (by reference) example: see EXT.AML. oncompiling filename linenumber ────────────────────────────────────────────────────────────────────── remarks: This user-defined function is called by the editor (A.EXE) while a macro language source file is being compiled, and can be used to show progress during macro compilation. 'oncompiling' is called directly in the current event object and is passed the name of the file being compiled and the line number of the last line compiled. After the file is compiled, 'oncompiling' is called again with no arguments. returns: none required see also: onloading, onprinting, onsaving example: see the configuration file EXT.AML ondraw ────────────────────────────────────────────────────────────────────── remarks: This user-defined function is called by the editor (A.EXE) immediately after a window client area is updated (the 'd' window flag must be turned on - see the 'windowflag' function). This function can be used to perform custom drawing or highlighting of the window client area. 'ondraw' is called directly in the window event object with no arguments. Before calling this function, the editor sets the current window, current event object, and current buffer to those values associated with the window being drawn. returns: none required see also: onstatus, windowflag onentry dosarg1 dosarg2 ... [Lib] ────────────────────────────────────────────────────────────────────── remarks: This user-defined function is called by the editor library code (LIB.X) after the default macro file A.X is loaded and executed. This function is typically used to perform a variety of editor initialization tasks, load DOS command line files, and process user-defined command line options. 'onentry' is queued for execution (not called directly), and executes in the current event object. Any arguments passed to A.EXE on the DOS command line are also passed to 'onentry'. returns: none required see also: onexit example: see the configuration file EXT.AML onexit [Lib] ────────────────────────────────────────────────────────────────────── remarks: This user-defined function is called by the editor library code (LIB.X) when an edit session is ended and control is returned to DOS. This function is typically used to perform a variety of final-exit cleanup tasks. 'onexit' is called directly in the current event object and is not passed any parameters. returns: none required see also: onentry example: see the configuration file EXT.AML onfocus [Lib] ────────────────────────────────────────────────────────────────────── remarks: This user-defined function is called by the editor library code (LIB.X) after the focus is switched to another file or file manager window. 'onfocus' is called directly in the current event object and is not passed any parameters. returns: none required see also: onclose, onkillfocus, onopen, onsave onfound stringlength [Ext][edit] ────────────────────────────────────────────────────────────────────── remarks: This user-defined function is called by the editor library (LIB.X) and extension code (EXT.AML) when a string is found in the current buffer. Typically, this function is used to change the window view and/or highlight the string found. 'onfound' is called directly in the current event object and is passed the length of the string. returns: none required see also: onhotkey example: function onfound (length) . . // highlights the string found with the color // white on magenta hilite length 1 95 end onhotkey character [Ext][edit] ────────────────────────────────────────────────────────────────────── remarks: This user-defined function is called by the editor library (LIB.X) and extension code (EXT.AML) when a when a hotkey is entered from the file manager or a file picklist. Typically, this function is used to jump to a file beginning with the hotkey character 'onhotkey' is called directly in the current event object and is passed the hotkey character. returns: none required see also: onfound onkillfocus [Lib] ────────────────────────────────────────────────────────────────────── remarks: This user-defined function is called by the editor library code (LIB.X) when a window is about to lose the focus. 'onkillfocus' is called directly in the current event object and is not passed any parameters. returns: none required see also: onfocus onloading linenumber ────────────────────────────────────────────────────────────────────── remarks: This user-defined function is called by the editor (A.EXE) as a file is being loaded, and can be used to show progress when loading a file. 'onloading' is called directly in the current event object and is passed the line number of the last line loaded. After the file is loaded, 'onloading' is called again with no arguments. returns: none required see also: oncompiling, onprinting, onsaving example: see the configuration file EXT.AML onopen options [Lib] ────────────────────────────────────────────────────────────────────── remarks: This user-defined function is called by the editor library code (LIB.X) whenever a new file or file manager window is opened. This function is only called once when the file is initially opened, or when the file manager window is initially created (not when switching to other files or windows). This function can be used to perform a variety of initialization tasks on the newly opened file, such as turning on settings based on file extension, altering the position in the file, checking for tab expansion, etc. 'onopen' is called directly in the current event object after the file or directory is loaded and before the window is displayed. The open options used to open the window are passed to 'onopen'. returns: none required see also: onclose, onfocus, onsave onprinting linenumber ────────────────────────────────────────────────────────────────────── remarks: This user-defined function is called by the editor (A.EXE) as a file is being printed, and can be used to show progress when printing a file. 'onprinting' is called directly in the current event object and is passed the line number of the last line printed. After the file is printed, 'onprinting' is called again with no arguments. returns: none required see also: oncompiling, onloading, onsaving example: see the configuration file EXT.AML onsave filename [Ext][edit] ────────────────────────────────────────────────────────────────────── remarks: This user-defined function is called by the editor extension code (EXT.AML) immediately before a file is saved. 'onsave' is called directly in the current event object. The name of the file being saved is passed to 'onsave'. returns: none required see also: onclose, onopen onsaving linenumber ────────────────────────────────────────────────────────────────────── remarks: This user-defined function is called by the editor (A.EXE) as a file is being saved, and can be used to show progress when saving a file. 'onsaving' is called directly in the current event object and is passed the line number of the last line saved. After the file is saved, 'onsaving' is called again with no arguments. returns: none required see also: oncompiling, onloading, onprinting example: see the configuration file EXT.AML onscanning filename position [Lib] ────────────────────────────────────────────────────────────────────── remarks: This user-defined function is called by the editor library code (LIB.X) as files are being scanned for a string, and can be used to show progress during the scan. 'onscanning' is called directly in the current event object before each file is scanned, and is passed the file name as the first argument. If the string is found in the file, 'onscanning' is called again with the same file name as the first argument, and a second argument which is the position (in bytes) in the file where the string was found. After all files are scanning, 'onscanning' is called again with no arguments. returns: none required see also: scanfiles example: see the configuration file EXT.AML. onstatus ────────────────────────────────────────────────────────────────────── remarks: This user-defined function is called by the editor (A.EXE) immediately before an edit window status line is updated (the 's' window flag must be turned on - see the 'windowflag' function). The user-defined return value of 'onstatus' will become the actual status line, allowing the status line to be customized. 'onstatus' is called directly in the window event object with no arguments. Before calling this function, the editor sets the current window, current event object, and current buffer to those values associated with the window being drawn. returns: The new user-defined status line see also: ondraw, windowflag onsyntax filename [Lib][a] ────────────────────────────────────────────────────────────────────── remarks: This user-defined function is called by the editor library (LIB.X) and extension code (EXT.AML) to return the syntax highlighting object associated with a filename. 'onsyntax' is called directly in the current event object and is passed the filename. 'onsyntax' should return the syntax highlighting object associated with the filename. returns: a syntax highlighting object. example: see SYNTAX.AML. open filespec opt=[bcefilhnprvz] [Lib][a] ────────────────────────────────────────────────────────────────────── remarks: Opens the specified file or directory. If a file is specified, then an edit window is opened, otherwise a file manager window is opened. If nothing is specified, then the directory '*.*' is assumed. The following open options may be specified: b - opens the file in binary mode. The binary line length can be specified after the option 'b'. For example, open "file.ext" "b20" In the example above, a file is opened with a binary line length of 20. If a binary line length is not specified, the 'BinaryLength' configuration variable in CONFIG.AML is assumed. c - cascades the window with other windows when loading. e - loads the file into the current edit window. The previous buffer in the window is not destroyed. f - opens the window in 'full-screen' mode (maximized, with all the borders visible). i - inserts the file at the cursor in the current edit window. If a directory is specified, then the user is prompted to select a file. l - specifies the line in the file where the cursor should be placed after loading. The line number is specified after the option 'l'. For example: open "file.ext" "l541" In the example above, a file is opened and the cursor is placed on line 541. h - tiles the window horizontally with other windows on the screen when loading. n - minimizes the window when loading. p - ignores history (the last window and cursor position) when loading the file or directory. This temporarily overrides the 'SavePosition' configuration setting in CONFIG.AML r - replaces the file in the current window with the new file. The previous buffer in the window is destroyed. v - tiles the window vertically with other windows on the screen when loading. z - maximizes the window when loading. returns: the bufferid of the file or directory if successful, otherwise null. see also: close, openbuf, opennew, reopen, save, setname example: open "C:\\FILE.TXT" // opens the file C:\FILE.TXT open "C:\\FILE.TXT" "pz" // opens the file C:\FILE.TXT in a maximized window, // ignoring history open "D:\\*.TXT" 'f' // opens a full-screen file manager window displaying // all files with the extension ".TXT" in the root // directory of the D drive. open "C:\\FILE.TXT" "el23" // opens the file C:\FILE.TXT and displays it in the // current edit window. The cursor is placed on // line 23. openbuf buffer opt=[ceflhnprvz] [Lib][a] ────────────────────────────────────────────────────────────────────── remarks: Displays an existing buffer in a new edit window. Any open options except 'b' and 'i' may be specified. See the 'open' function for a description of open options. This function allows buffers to be created and manipulated within the editor before being displayed in a window. The buffer should previously have been assigned a buffer name (a fully qualified file name). If the buffer was created with the 'loadbuf' function, the buffer name will have automatically been set to the file name where the buffer was loaded, otherwise the 'setbufname' function should be used to assign a buffer name. returns: nothing see also: close, createbbuf, createbuf, loadbuf, open, opennew, reopen, save, setname example: openbuf (loadbuf "C:\\FILE.TXT") 'z' // load C:\FILE.TXT and display it in a maximized // window buffer = createbuf // create a new buffer if buffer then setbufname "C:\\FILE.TXT" // set the buffer name openbuf buffer // display the buffer end opendesk filename [Lib][a] ────────────────────────────────────────────────────────────────────── remarks: Loads a previously saved desktop from the specified filename and makes it the current desktop. The desktop does not become visible until the 'restoredesk' function is called. returns: Non-zero if successful, otherwise zero see also: begdesk, currdesk, enddesk, restoredesk, savedesk openf file opt=[bcefilhnprvz1q] [Lib][fmgr] ────────────────────────────────────────────────────────────────────── remarks: Opens a file with the specified options from the current file manager window. This call is a low level call intended for use within the file manager. See the 'open' function for a description of the available options. In addition to the options supported by the 'open' function, the following options are also supported: 1 - opens only the file or directory on the current line, even if multiple files are marked. q - closes the file manager window when loading. returns: TRUE if successful, otherwise null. see also: fdomark, open openfile filename opt=[rwc] ────────────────────────────────────────────────────────────────────── remarks: Opens the specified file for reading and/or writing. The following options can be specified: c - create a new file or truncate the file if it already exists r - open the file for reading w - open the file for writing If no options are specified, 'r' is assumed. returns: A file handle if successful, otherwise -1. see also: closefile, filepos, readfile, writefile openhistory filename [Lib][a] ────────────────────────────────────────────────────────────────────── remarks: Opens the specified history file and replaces all existing history buffers with the history in the file. The current desktop is also replaced with the desktop saved in the history file. returns: Non-zero if successful, otherwise null. see also: savehistory openfold opt=[s] row buffer ────────────────────────────────────────────────────────────────────── remarks: Opens a closed fold. If 'buffer' is null or not specified, then the current buffer is assumed. If 'row' is not specified, then the line at the cursor is assumed. If option 's' is specified, all closed subfolds within the fold are also opened. returns: the number of folds opened see also: closefold, createfold, destroyfold, foldblock, getfold example: openfold // opens the closed fold at the current line in the // current buffer, leaving any subfolds closed openkey filename [Lib][a] ────────────────────────────────────────────────────────────────────── remarks: Opens a key macro file saved with the 'savekey' function. If there is a name conflict with any currently defined key macros, the key macros in the opened file will replace the current key macros. returns: TRUE if successful, otherwise null. see also: savekey opennew filename opt=[ceflhnprvz] [Ext][a] ────────────────────────────────────────────────────────────────────── remarks: Creates a new buffer and displays it in an edit window. If 'filename' is not specified, the name "NEW.TXT" is assumed. See the 'open' function for a description of valid open options. returns: nothing see also: close, open, openbuf, reopen, save, setname example: opennew "NEW.C" openmouse opt=[dr] ────────────────────────────────────────────────────────────────────── remarks Initializes the mouse. If successful, the mouse pointer is displayed at the center of the screen and the event queue will process mouse events. For this function to return successfully, a mouse driver such as MOUSE.COM or MOUSE.SYS must be installed before the editor is started. Any combination of the following options can be specified: d - hides the mouse pointer when a key is pressed. The mouse pointer is re-displayed when the mouse is used again. r - reverses the mouse buttons returns: TRUE is successful, otherwise null see also: closemouse ovltext string col row buffer ────────────────────────────────────────────────────────────────────── remarks: This function overlays a string onto a buffer at the specified row and column. If 'buffer' is null or not specified, then the current buffer is assumed. If 'col' and 'row' are not specified, then the current cursor position is assumed. returns: TRUE if successful, otherwise null. see also: delchar, instext example: ovltext "some text" // overlays "some text" at the cursor in the current // buffer ovltext "some text" 2 20 // overlays "some text" at column 2, line 20 in the // current buffer ovltext "some text" 1 1 "abc" // overlays "some text" at column 1, line 1 in the // buffer "abc" pad string field opt=[lr] padstring ────────────────────────────────────────────────────────────────────── remarks: Left or right justifies the specified string within a field of length 'field'. One of the following options may be specified: l - left justifies the string r - right justifies the string If no options are specified, then 'r' is assumed. 'padstring' is the string used to pad unused positions in the field. If 'padstring' is not specified, then blanks are assumed. returns: A padded left or right justified string. see also: copystr, sizeof example: pad 123 7 // returns " 123" pad 123 7 'l' // returns "123 " pad 123 7 'r' '.' // returns "....123" pagedown (+/-)lines window ────────────────────────────────────────────────────────────────────── remarks: Scrolls the text in a window down one page, plus or minus the specified number of lines. The default page size is the number of visible rows on the screen minus one row. The cursor is moved by the same amount that the text scrolls. If 'window' is not specified, the current window is assumed. The value of 'lines' is added to the page size. returns: TRUE if successful, otherwise null. see also: pageup example: pagedown // scrolls down one page pagedown 1 // scrolls down one page and one line pagedown -(getviewrows / 2) // scrolls down one half page pageup (+/-)lines window ────────────────────────────────────────────────────────────────────── remarks: Scrolls the text in a window up one page, plus or minus the specified number of lines. The default page size is the number of visible rows on the screen minus one row. The cursor is moved by the same amount that the text scrolls. If 'window' is not specified, the current window is assumed. The value of 'lines' is added to the page size. returns: TRUE if successful, otherwise null. see also: pagedown example: pageup // scrolls up one page pageup 1 // scrolls up one page and one line pageup -(getviewrows / 2) // scrolls up one half page pan (+/-)cols (+/-)rows ────────────────────────────────────────────────────────────────────── remarks: Pans to a new relative location on the virtual screen by changing the mapping of the physical video device (the screen) to the virtual video device. 'cols' and 'rows' specify the relative distance in screen columns and rows from the current position. returns: TRUE if successful, otherwise null see also: panto example: pan 2 -2 // pans right 2 columns and up 2 rows pankey [Lib][win] ────────────────────────────────────────────────────────────────────── remarks: Pans through the virtual screen by using the cursor keys. returns: nothing see also: sizekey panto virtualX virtualY ────────────────────────────────────────────────────────────────────── remarks: Pans to a new absolute location on the virtual screen by changing the mapping of the physical video device (the screen) to the virtual video device. 'virtualX' and 'virtualY' specify an absolute X,Y coordinate on the virtual screen where the upper left corner of the physical screen is to be located. The virtual video device is 64000 x 64000 characters. When the editor is initially invoked, physical screen is placed at 16000,16000 in the virtual screen. returns: TRUE if successful, otherwise null see also: panto example: panto 8000 10000 // pans to column 8000, row 10000 parse searchstr string opt=[irwx] ref1 ref2 ... ────────────────────────────────────────────────────────────────────── remarks: Parses substrings (or substring positions) within a string into local or global variables. This function can be very convenient for parsing almost any string with only one function call. See the 'pos' function for a description of valid search options. If search option 'x' (regular expressions) is specified, and 'tagged' patterns (enclosed within the {} grouping operators) are specified in the search string, any tagged patterns found are returned in the variables (ref1, ref2, etc.) passed by reference to this function. If search option 'x' is not specified (or tagged patterns are not specified) the positions of successive occurrences of 'searchstr' within 'string' are returned in the variables (ref1, ref2, etc.) passed by reference to this function. returns: The position in the string where the first occurrence of 'searchstr' is found. Substrings (or substring positions) are returned in variables passed by reference to this function. see also: pos, poschar, posnot, sub example: parse "{[0-9]#}.*{[0-9]#}.*{[0-9]#}" str 'x' ref a ref b ref c // parses 'str', and places the first three numbers // found in variables a, b, and c. str = "bacdaae" parse "a" str '' ref x ref y ref z // after this function call: x=2, y=5, z=6 pass arg1 arg2 ... ────────────────────────────────────────────────────────────────────── remarks: Calls the current executing function in the parent object(s) of the current (executing) object, passing the arguments 'arg1', 'arg2', etc. This function can be used to intercept an event or function call for pre-processing or post-processing. returns: The return value from the function call. see also: call, eval, passprev, send, sendobject example: function <lbutton> . // pre-processing . pass // pass control to <lbutton> in a parent object . // post-processing . end passprev arg1 arg2 ... ────────────────────────────────────────────────────────────────────── remarks: Calls the current executing function in the 'preempted' object (if any) of the current object, passing the arguments 'arg1', 'arg2', etc. In all other respects, this function is identical to the 'pass' function. A 'preempted' object is an object which has been temporarily overridden by an object with the same name, defined from within an external macro executed with the 'runmacro' function. Individual functions are temporarily replaced or 'preempted' from within the macro by simply redefining the functions in an object with the same name as the object to be overridden. This allows detailed, temporary modifications to be made to an existing object, without adding new objects to the object hierarchy. The modifications will disappear when the macro is finished executing. This function allows you to access an older overridden or 'preempted' function from within the newer overriding or 'preempting' function. returns: The return value from the function call. see also: call, eval, pass, send, sendobject peek address length ────────────────────────────────────────────────────────────────────── remarks: Gets the portion of DOS memory specified by 'address' and 'length'. The specified address must be an absolute 32-bit address, not a segmented address. The maximum length is 16000. returns: a string representing a copy of the specified DOS memory area. see also: poke example: peek 0 100 // returns the first 100 bytes of memory playkey keyname [Lib][mon] ────────────────────────────────────────────────────────────────────── remarks: Plays the key macro assigned to the specified key. If 'keyname' is not specified, the current scrap key macro is assumed. returns: TRUE if successful, otherwise null. see also: assignkey, openkey, playing?, savekey, setting example: playkey // plays the current scrap key macro playkey "<ctrl b>" // plays the key macro assigned to <ctrl b> playing? keyname ────────────────────────────────────────────────────────────────────── remarks: Tests if a key macro is currently playing. If 'keyname' is not specified, the current scrap key macro is assumed. returns: nothing see also: assignkey, openkey, playkey, savekey, setting poke address string ────────────────────────────────────────────────────────────────────── remarks: Copies a string to the specified DOS memory address. 'address' must be an absolute 32-bit address, not a segmented address. Obviously, this function should be used with care. returns: nothing see also: peek popcursor buffer opt=[ad] ────────────────────────────────────────────────────────────────────── remarks: If no options are specified, this function pops a position from the internal cursor stack, and moves the cursor to the popped position. The popped position must have been placed on the stack with the 'pushcursor' function. If 'buffer' is null or not specified, the current buffer is assumed. Any combination of the following options may be specified: a - pops all positions from the cursor stack d - don't move the cursor to the popped position returns: nothing see also: pushcursor pophistory historybuffer title [Lib][a] ────────────────────────────────────────────────────────────────────── remarks: Displays a history popup menu for the specified history buffer, with an optional menu title. returns: The string selected from the popup menu. Returns null if nothing was selected or the history buffer does not exist. see also: askhistory example: pophistory "_load" // displays a popup menu for the "_load" history buffer pophistory "_load" "Select a File" // displays a popup menu for the "_load" history buffer // with the title 'Select a File' popup menuname title menuwidth menuheight [Lib][a] ────────────────────────────────────────────────────────────────────── remarks: Displays the popup menu 'menuname'. 'menuname' can be the name of a menu defined with the 'menu' statement, or a bufferid. The following parameters can also be specified: title - the popup window title. menuwidth - the menu width. If none is specified, and the menu was defined with the 'menu' function, the length of the longest line determines the menu width. menuheight - the menu height. If none is specified, the lesser of the screen rows or the menu rows is assumed. If the menu or buffer has been named with 'setbufname', it will remember the previous window and cursor position each time it is displayed. returns: For popup menus defined with the 'menu' statement, the macro expression associated with the menu item is evaluated and the result is returned. If no macro expression is associated with menu item or the menu was not defined with the 'menu' statement, then the menu item description line is returned. If no item was selected from the menu, then the null string is returned. see also: askfile, getmenu, menu example: popup "files" "Select a File" // displays the popup menu 'files' with the title // 'Select a File' popup "files" '' 25 10 // displays the popup menu 'files' with no title and // a width of 25 columns and a height of 10 rows pos searchstr string opt=[irwx] ────────────────────────────────────────────────────────────────────── remarks: Searches for the specified search string within 'string'. Any of the following search options may be specified: i - ignore case r - search in reverse from the end of the string w - whole words only x - use regular expressions (see 'Regular Expression Searching') returns: The position in 'string' where the first occurrence of the search string is found, or zero if nothing is found. see also: parse, poschar, posnot, sub example: pos 'p' "apples" // returns 2 pos 'p' "apples" 'r' // returns 3 pos 'ES' "apples" 'i' // returns 5 poschar charclass string opt=[r] ────────────────────────────────────────────────────────────────────── remarks: Searches for the first character in 'string' which is found in 'charclass'. Character ranges such as 'a-z' or 'A-Z' can be specified. If option 'r' is specified, the search proceeds from the end of string to the beginning of the string. returns: The position in the string where the first character was found, or zero if not found. see also: parse, pos, posnot, sub example: poschar "abc" "123b5a78" // returns 4 poschar "abc" "123b5a78" 'r' // returns 6 poschar "apples" "oranges" // returns 3 poschar "c-f" "oranges" // returns 6 posnot charclass string opt=[r] ────────────────────────────────────────────────────────────────────── remarks: Searches for the first character in 'string' which is not found in 'charclass'. Character ranges such as 'a-z' or 'A-Z' can be specified. If option 'r' is specified, the search proceeds from the end of string to the beginning of the string. returns: The position in the string where the first character not in 'charclass' was found, or zero if not found. see also: parse, pos, poschar, sub example: posnot "abc" "abc123ab" // returns 4 posnot "abc" "abc123ab" 'r' // returns 6 posnot "oranges" "apples" // returns 2 posnot "a-r" "oranges" // returns 7 prevfile [Lib][edit] ────────────────────────────────────────────────────────────────────── remarks: Makes the previous buffer in the buffer list the current buffer, and displays it in the current edit window. The buffer previously displayed in the edit window will not be destroyed. returns: nothing see also: filelist, nextfile prevhist [Lib][prompt] ────────────────────────────────────────────────────────────────────── remarks: Displays the previous history string in a prompt. This function is only for use within prompts. returns: nothing see also: gethistname, nexthist prevwindow [Lib][win] ────────────────────────────────────────────────────────────────────── remarks: Switches the focus to the previous window on the screen. returns: nothing see also: nextwindow printblock device header mark ────────────────────────────────────────────────────────────────────── remarks: Prints marked text. The text is printed using the printer settings specified with the 'printformat' function. If 'mark' is not specified, the default markid is assumed. All other arguments are identical to the 'printbuf' function (see 'printbuf'). returns: TRUE if successful, otherwise null. see also: printbuf, printformat printbuf device header buffer ────────────────────────────────────────────────────────────────────── remarks: Prints a buffer. The text is printed using the printer settings specified with the 'printformat' function. If 'buffer' is null or not specified, then the current buffer is assumed. 'header' specifies a string to place on the header and/or footer of each page. Print headers and/or footers must be enabled with the 'printformat' function (see the 'printformat' function). 'device' is the printer device to use. Filenames or device names such as 'prn', 'lpt1', 'lpt2', etc. can be specified. If 'device' is null or not specified, then 'prn' is assumed. returns: TRUE if successful, otherwise null. see also: printblock, printformat example: printbuf // prints the current buffer to the device 'prn' printbuf "c:\\print.txt" // prints the current buffer to the file 'c:\\print.txt' printbuf "lpt1" "Inventory" "abc" // prints the buffer 'abc' to the device 'prn' using // the header/footer 'Inventory' printformat printer opt=[efhlps] pagesize leftmarg topmarg rightmarg bottommarg linespace copies ────────────────────────────────────────────────────────────────────── remarks: Changes the current printer settings. The following printer settings can be specified: printer - reserved for future use pagesize - specifies the lines per page of printed output. This includes the top margin and the bottom margin. After the specified lines per page have been printed, a formfeed character (ASCII 12) will be sent to the printer and a new page will be started. If 'pagesize' is zero, printing will be continuous (no formfeed characters will be sent to the printer) and 'topmarg', 'bottommarg', and the option 'p' will be ignored. linespace - specifies the number of lines to advance after printing each line of output. A value of 1 generates single-spaced output, 2 generates double-spaced output, and so on. copies - specifies the number of copies to print. topmarg - specifies the number of blank lines to precede printed output at the top of each page. This value is included in 'pagesize'. 'topmarg' is ignored if 'pagesize' is zero. bottommarg - specifies the number of blank lines to follow printed output at the bottom of each page. This value is included in 'pagesize'. 'bottommarg' is ignored if 'pagesize' is zero. leftmarg - specifies the number of blank columns to precede the printed output on each line. rightmarg - specifies the column position at which to truncate each printed line. This column position is relative to column zero of the printed output, not the file being printed. If zero is specified, lines are not truncated. Any of the following print options can also be specified: h - prints a header at the top of each page. The header is specified in the 'printbuf' or 'printblock' functions when printing. This option is ignored if 'pagesize' is zero. f - prints a footer at the bottom of each page. The footer is specified in the 'printbuf' or 'printblock' functions when printing. This option is ignored if 'pagesize' is zero. s - adds a separator line after the header line and before the footer line. p - prints a right justified page number on the header and footer lines. If neither a header or footer was specified, a blank header line is assumed. This option is ignored if 'pagesize' is zero. l - prints a line number at the beginning of each line. e - sends a formfeed character to the printer when printing is completed. returns: nothing see also: printblock, printbuf process ────────────────────────────────────────────────────────────────────── remarks: Creates an editor subprocess by invoking the editor recursively. This function does not return until the 'endprocess' function is called. The effect of this function is equivalent to the following loop: while dispatch do . . end returns: nothing see also: dispatch, endprocess purgequeue ────────────────────────────────────────────────────────────────────── remarks: Removes all events from the event queue. returns: nothing see also: queue, queueobject, sizequeue pushcursor buffer ────────────────────────────────────────────────────────────────────── remarks: Saves the cursor position on an internal cursor stack which is unique for each buffer. If 'buffer' is null or not specified, the current buffer is assumed. returns: nothing see also: popcursor qualify filename filespec ────────────────────────────────────────────────────────────────────── remarks: Converts an unqualified or partially qualified filename into a fully-qualified filename, including drive and directory. 'filespec' is used as the 'template' for the qualification. If 'filespec' is not specified, the current drive and path are assumed. returns: a fully qualified filename or directory specification. see also: bootpath, getbootpath example: qualify "file.txt" // returns C:\FILE.TXT if C:\ is the current path qualify "file.txt" "e:\\doc" // returns E:\DOC\FILE.TXT queue function arg1 arg2 ... ────────────────────────────────────────────────────────────────────── remarks: Queues a function call for later execution. The specified function and arguments 'arg1', 'arg2', etc. are placed on on the event queue. When the editor is idle, it will read the event queue and attempt to call the function in the current event object. returns: TRUE if successful, otherwise null. see also: purgequeue, queueobject, sizequeue example: queue "abc" 1 2 4 // queues the function call 'abc 1 2 4' for later // execution in the current event object queuekey keycode1 keycode2 ... ────────────────────────────────────────────────────────────────────── remarks: Pushes the specified keycodes onto the editor event queue for later execution. returns: nothing see also: getkey, getkeycode, sendkey example: keycode = getkey // gets a keycode... queuekey keycode // and queues it for execution queueobject object function arg1 arg2 ... ────────────────────────────────────────────────────────────────────── remarks: Queues a function call for later execution in a specific object. The specified object, function, and arguments 'arg1', 'arg2', etc. are placed on the event queue. When the editor is idle, it will read the event queue and attempt to call the function in the specified object. returns: TRUE if successful, otherwise null. see also: purgequeue, queue, sizequeue example: queueobject "edit" "abc" 1 2 4 // queues the function call 'abc 1 2 4' for later // execution in the object 'edit' rand seed ────────────────────────────────────────────────────────────────────── remarks: Generates a random number between 0 and 2147483647. The random number generator can be initialized by specifying a random number 'seed'. Note: the editor library initializes the random number generator with a value based on the current time when the editor is started. returns: a random number. example: rand 12345 // initializes the random number generator rand mod 100 // returns a random number between 0 and 99 readfile handle length ────────────────────────────────────────────────────────────────────── remarks: Reads 'length' characters from the current position in the open file specified by 'handle'. 'length' may not exceed 16000. The current position in the file is advanced by the amount of characters read. returns: The data read from the file if successful, otherwise null. The number of characters actually read from the file can be determined by using the 'sizeof' function on the returned string. see also: closefile, filepos, openfile, writefile example: handle = openfile "C:\\FILE.TXT" // reads the first if handle <> -1 then // 100 bytes of str = readfile handle 100 // C:\FILE.TXT into closefile handle // the variable 'str' end redo buffer ────────────────────────────────────────────────────────────────────── remarks: Reverses the changes made by the last 'undo' function call for a specific buffer. If 'buffer' is null or not specified, then the current buffer is assumed. returns: TRUE if successful, otherwise null. see also: undo, undobegin, undocursor, undoend renamefile filename newfilename ────────────────────────────────────────────────────────────────────── remarks: Renames the the specified filename to 'newfilename'. A directory can also be renamed to another directory on the same drive. returns: TRUE if successful, otherwise null. see also: copyfile, deletefile reopen filename [Ext][edit_fmgr] ────────────────────────────────────────────────────────────────────── remarks: Reloads the current window with the specified file or directory. If 'filename' is not specified, the buffer name of the current buffer is assumed. The previous file or directory is destroyed. returns: nothing see also: close, open, openbuf, opennew, save, setname example: reopen // refreshes the current file from disk reopen "C:\\FILE.TXT" // loads C:\FILE.TXT into the current window, // destroying the existing buffer in the window replace searchstr replacestr opt=[abfgilnorswx*[~] mark buffer ────────────────────────────────────────────────────────────────────── remarks: Searches for the specified search string within a buffer, mark, or line, and replaces it with 'replstr'. If 'buffer' is not specified, the current buffer is assumed. See the 'find' function for a list of available search options. If option 'a' is specified, all occurrences of the 'searchstr' found will be replaced with 'replacestr'. If option 'a' is not specified, then only the first occurrence of the search string is replaced. If the string is found and neither of the search options 'a' or 'n' are specified, then the cursor is moved to the beginning of the found string, otherwise the cursor does not move. returns: If option 'a' is specified, the number of replacements made is returned, otherwise the length of the replaced string is returned. If nothing is found, then null is returned. see also: find, search example: replace "apples" "oranges" // replaces the next occurrence of 'apples' with // 'oranges' in the current buffer, starting at one // character after the cursor position replace "apples" "oranges" "ag" // replaces all occurrences of 'apples' with 'oranges' // in the current buffer and returns the number of // occurrences. The cursor is not moved. repldlg [Lib][edit] ────────────────────────────────────────────────────────────────────── remarks: Displays a find and replace dialog box. returns: the search and replace multi-string (searchstr / replacestr / options) to be used for the searching and replacing, or null if nothing is specified see also: about, finddlg, scandlg restore window [Lib][a] ────────────────────────────────────────────────────────────────────── remarks: Restores the specified window. If 'window' is not specified, the current window is assumed. returns: nothing see also: max?, maximize, min?, minimize restoredesk [Lib][a] ────────────────────────────────────────────────────────────────────── remarks: Removes all existing windows on the screen and makes the current desktop visible. The current desktop is set by the 'opendesk', 'currdesk', and 'openhistory' functions. The 'begdesk' and 'enddesk' functions also change the current desktop. returns: nothing see also: begdesk, currdesk, enddesk, opendesk, openhistory, savedesk example: opendesk "C:\\DESKTOP.DSK" // loads the previously saved desktop in C:\DESKTOP.DSK // and makes it the current desktop restoredesk // makes the current desktop visible right cols buffer ────────────────────────────────────────────────────────────────────── remarks: Moves the cursor to the right. 'cols' specifies the number of columns to move. If 'cols' is not specified, 1 is assumed. If 'buffer' is null or not specified, the current buffer is assumed. returns: TRUE if successful, otherwise null. see also: down, left, up example: right // moves the cursor right 1 column right 5 // moves the cursor right 5 columns rollcol (+/-)cols window ────────────────────────────────────────────────────────────────────── remarks: Scrolls the text in a window left or right, relative to the current position. If 'window' is not specified, the current window is assumed. The cursor is moved by the same amount that the text scrolls. 'cols' specifies the number of columns to scroll. Positive numbers scroll right and negative numbers scroll left. returns: TRUE if successful, otherwise null. see also: rollrow example: rollcol 4 // scrolls right 4 columns rollcol -1 // scrolls left 1 column rollrow rows window ────────────────────────────────────────────────────────────────────── remarks: Scrolls the text in window up or down, relative to the current position. If 'window' is not specified, the current window is assumed. The cursor is moved by the same amount that the text scrolls. 'rows' specifies the number of lines to scroll. Positive numbers scroll down and negative numbers scroll up. returns: TRUE if successful, otherwise null. see also: rollcol example: rollrow 4 // scrolls down 4 rows rollrow -1 // scrolls up 1 row row row buffer ────────────────────────────────────────────────────────────────────── remarks: Moves the cursor to the specified row, but does not change the column. If 'buffer' is null or not specified, the current buffer is assumed. returns: TRUE if successful, otherwise null. see also: col, gotopos example: row 1 // moves the cursor to line 1 in the current buffer row (getlines) // moves the cursor to the last line in the current // buffer runmacro filename arg2 arg3 ... ────────────────────────────────────────────────────────────────────── remarks: Runs the compiled macro code in the specified filename. The macro code is loaded into a temporary object which is descended from the current event object. The macro code is then executed in the temporary object and is passed the 'filename' followed by the optional arguments 'arg2', 'arg3', etc. Normally, when the macro is finished executing, the temporary object is destroyed and the macro is discarded. However, if the 'stayresident' function is called from within the macro, the macro will remain resident until the temporary object created by 'runmacro' is explicitly destroyed with the 'destroyobject' function. returns: The return value from executing the macro. see also: compilemacro, destroyobject, eval, includemacro, stayresident example: runmacro "c:\\aurora\\macro\\mymacro.x" save filename [Ext][edit] ────────────────────────────────────────────────────────────────────── remarks: Saves the current buffer to the specified filename. If a filename is not specified, the buffer name of the current buffer is assumed. If the backup setting in the current window is ON, the file is backed-up before saving. returns: Non-zero if successful, otherwise zero. see also: close, open, setname, setting, setting? example: save // saves the current buffer to the file name specified // by the name of the buffer save "C:\SAVE.TXT" // saves the current buffer to C:\SAVE.TXT saveblock filename opt=[abetxz] mark delimiter filedelim comment1 comment2 ────────────────────────────────────────────────────────────────────── remarks: Saves marked text to the specified filename. If 'mark' is not specified, the default markid is assumed. All other arguments and options are identical to the 'savebuf' function (see 'savebuf'). returns: TRUE if successful, otherwise null. see also: loadbuf, savebuf savebuf filename opt=[abetxz] buffer delimiter filedlm comment1 comment2 ────────────────────────────────────────────────────────────────────── remarks: Saves a buffer to the specified filename. If 'buffer' is null or not specified, then the current buffer is assumed. The following options may be specified: a - appends to end of the file when saving b - saves the file in binary mode, with no line delimiters e - entabs the buffer while saving. The tabwidth is specified after the 'e' option - for example: 'e8'. t - trims trailing blanks from each line x - disables conversion of folds to fold comments z - appends ctrl-z (ASCII 26) to the end of the file when saving 'delimiter' specifies a 1 or 2 byte line delimiter string to be appended to the end of each line in the saved file. If 'delimiter' is null or not specified, then the line delimiter specified when loading the file is assumed. If the buffer was not loaded but created new, then a line delimiter of 0D0Ah (CR/LF) is assumed. 'filedlm' specifies an alternate 1 byte file delimiter to save at the end of the file. 'comment1' and 'comment2' specify the opening and closing comment strings to be used when converting text folds to fold comments during the saving process. Specifying option 'x' disables the saving of folds as fold comments. returns: TRUE if successful, otherwise null. see also: createbbuf, createbuf, destroybuf, loadbuf, saveblock example: savebuf "c:\\file.txt" // saves the current buffer to the file 'c:\file.txt', // and overwrites any previous data in the file. // The file is saved with CR/LF line delimiters. savebuf "c:\\file.txt" 'b' "abc" // saves the buffer 'abc' to 'c:\file.txt' in binary // mode, with no line delimiters savebuf "c:\\file.txt" 't' '' (hex2bin "0A") (char 0) // saves the current buffer to 'c:\file.txt' and // trims trailing blanks from each line. The file // is saved with '0A' (LF) line delimiters and a // file delimiter of ASCII 0. savedesk filename [Lib][a] ────────────────────────────────────────────────────────────────────── remarks: Saves the current desktop to the specified filename. The current desktop is set by the 'opendesk', 'currdesk', and 'openhistory' functions. The 'begdesk' and 'enddesk' functions also change the current desktop. returns: TRUE is successful, otherwise null. see also: begdesk, currdesk, enddesk, opendesk, restoredesk example: currdesk // set current desktop to the current window layout savedesk "C:\\DESKTOP.DSK" // save the current desktop to C:\DESKTOP.DSK savehistory filename [Lib][a] ────────────────────────────────────────────────────────────────────── remarks: Saves all existing history buffers and the current desktop to the specified filename. returns: TRUE if successful, otherwise null. see also: openhistory savekey filename [Lib][a] ────────────────────────────────────────────────────────────────────── remarks: Saves all current key macros to the specified filename. The key macros can be reloaded later with the 'openkey' function. returns: TRUE if successful, otherwise null. see also: openkey saveobject object filename ────────────────────────────────────────────────────────────────────── remarks: Saves an object to the specified filename as executable macro code. If 'object' is not specified, then the current object is assumed. returns: TRUE if successful, otherwise null. see also: includemacro, runmacro say message opt=[b] ────────────────────────────────────────────────────────────────────── remarks: Displays the specified message at the location of the primary title (title 1) of the current window. If option 'b' is specified, the PC speaker beeps. The message is cleared the next time the display is updated. returns: nothing see also: msgbox, okbox, shortbox, yncbox example: say "Hello World" scandlg [Lib][edit_fmgr] ────────────────────────────────────────────────────────────────────── remarks: Displays a file scan dialog box. returns: the scan multi-string (searchstr / filespec / options) to be used for the scan, or null if nothing is specified see also: about, finddlg, repldlg scanfile filename searchstr opt=[iwx] delimiter ────────────────────────────────────────────────────────────────────── remarks: Scans the specified filename for the string 'searchstr'. 'delimiter' specifies the line delimiter used to separate lines in the file. If 'delimiter' is not specified, then CR/LF (0D0Ah) is assumed. Any of the following options may be specified: i - ignores case during the scan w - scans for whole words only x - checks for regular expression chars in the search string (see 'Regular Expression Searching') returns: The absolute position in the file where the search string was found (starting with 1), or zero if not found. If the scan was interrupted by <ctrl break>, then -1 is returned. see also: find, replace example: scanfile "C:\\FILE.TXT" "apples" "i" // returns the first position in C:\FILE.TXT where // 'apples' is found (ignoring case), or zero if // not found scanfiles filespec searchstr opt=[iwx] [Lib][a] ────────────────────────────────────────────────────────────────────── remarks: Scans multiple files specified by 'filespec' for the specified search string. A file manager window is displayed listing all files in which the string was found. When a file is opened from the file manager window, the cursor is positioned at the first occurrence of the search string. The 'findlast' function can be used to find other occurrences. Any of the following search options can be specified: i - ignore case during the search w - search for whole words only x - check for regular expression chars in the search string (see 'Regular Expression Searching') returns: The number of files in which the search string is found, or null if the search string is not found, or -2 if the filespec is not found. see also: findlast, search example: scanfiles "D:\\*.TXT" "apples" "iw" // scans all files with the extension .TXT in the // root directory of the D drive for the string // 'apples', ignoring case, whole words only. scrollcol column window ────────────────────────────────────────────────────────────────────── remarks: Scrolls the text in window so that 'column' is the leftmost column in the window. The cursor is moved by the same amount that the text scrolls. If 'window' is not specified, the current window is assumed. returns: TRUE if successful, otherwise null. see also: scrollrow example: scrollcol 4 // scrolls the current window so that the leftmost // column in the window is 4. The cursor moves // accordingly. scrollrow row window ────────────────────────────────────────────────────────────────────── remarks: Scrolls the text in window so that 'row' is the topmost line in the window. The cursor is moved by the same amount that the text scrolls. If 'window' is not specified, the current window is assumed. returns: TRUE if successful, otherwise null. see also: scrollcol example: scrollrow 4 // scrolls the current window so that the topmost // line in the window is 4. The cursor moves // accordingly. search searchstr/replstr/options reverse repeat [Ext][a] ────────────────────────────────────────────────────────────────────── remarks: Searches for the specified search string in the current buffer, and optionally replaces it with 'replstr'. This function provides a higher level interface to the 'find' and 'replace' builtin functions. The parameters 'searchstr/replstr/options' are entered together as one argument in multi-string format (see the 'joinstr' and 'splitstr' functions). If no search options are explicitly specified, the configuration variables 'SearchOpt' and 'ReplaceOpt' are assumed. See the 'find' function for a description of valid search options. If 'replstr' is specified and option 'a' (replace all) is not specified, the editor will prompt for each replacement. If 'reverse' is 'r', then the search proceeds in the reverse direction from the direction specified in the search options. If 'repeat' is TRUE, then search option 'g' (global search) will be ignored if specified. returns: The same values as the 'find' and 'replace' builtin functions, depending on the action performed (find or replace) and the search options specified (see the 'find' and 'replace' functions). see also: find, findlast, joinstr, replace, scanfiles, splitstr example: search "apples" // searches for the string 'apples' (case sensitive) // starting at one char to the right of the cursor // and searching toward the end of the buffer search "apples/ir*" // searches for 'apples' (case insensitive) starting at // the cursor position and searching toward the // beginning of the buffer search "app'/les/bgw" // searches for 'app/les' (whole words only), limiting // the search to the current mark and starting from // the beginning of the mark search "apples/oranges/ag" // replaces all occurrences of 'apples' with 'oranges' // in the current buffer and returns the number of // occurrences. The cursor is not moved. send funexpression arg1 arg2 ... ────────────────────────────────────────────────────────────────────── remarks: Calls a function in the current event object whose name is the value of 'funexpression', passing the optional arguments 'arg1', 'arg2', etc. returns: The return value from calling the specified function. see also: call, eval, pass, sendkey, sendobject example: send <ctrl b> // simulates <ctrl b> send '<' + "ctrl b" + '>' // simulates <ctrl b> sendkey keycode1 keycode2 ... ────────────────────────────────────────────────────────────────────── remarks: Executes the specified keycodes immediately and synchronously. returns: nothing see also: getkey, getkeycode, queuekey, send, sendobject example: keycode = getkey // gets a keycode... sendkey keycode // and executes it immediately sendobject objexpression funexpression arg1 arg2 ... ────────────────────────────────────────────────────────────────────── remarks: Calls a function in the object 'objexpression' whose name is the value of 'funexpression', passing the optional arguments 'arg1', 'arg2', etc. returns: The return value from calling the specified function. see also: call, eval, pass, send, sendkey example: sendobject "edit" <ctrl b> sendobject "edit" '<' + "ctrl b" + '>' setalarm timerid year mon day dayofweek hour min second object function arg1 arg2 ... ────────────────────────────────────────────────────────────────────── remarks: Sets a timer to call 'function' automatically at the specified date and time. If '-1' is specified for for any of the date or time parameters, the timer will call the function for any value of that parameter (the parameter becomes a 'wildcard'). If -1 is specified for any of the arguments, the timer is a 'repeating' timer and is not destroyed, otherwise the timer is automatically destroyed after the function call. The function is called in the specified object, passing the optional arguments 'arg1', 'arg2', etc. If 'object' is not specified, the current event object is assumed. 'timerid' uniquely identifies the timer. If a timerid is not specified, a unique timerid is generated. A maximum of 16 timerid's may be active at one time. returns: The timerid if successful, otherwise null. see also: destroytimer, setrepeat, settimer, timer? example setalarm "xyz" // timerid 'xyz' -1 // any year -1 // any month -1 // any day -1 // any day of the week 22 // 10 o'clock at night 0 // zero minutes 0 // zero seconds '' // send to current event object "abc" // function 'abc' // the above example sets timer 'xyz' to call the function // 'abc' at 10 o'clock every night in the current event // object setbook bookmark buffer ────────────────────────────────────────────────────────────────────── remarks: Creates a new bookmark or modifies an existing bookmark. The bookmark is placed at the current cursor position in the specified buffer. If the buffer is null or not specified, the current buffer is assumed. returns: The bookmarkid if a bookmark is created, or TRUE if an existing bookmark is modified, otherwise null. see also: destroybook example: setbook 'A' // places bookmark "A" at the cursor position setbootpath path ────────────────────────────────────────────────────────────────────── remarks: Changes the editor 'boot' path for the current session. returns: nothing see also: bootpath, getbootpath setborder opt=[ios012345] xd yd cornerX cornerY bchr1 bchr2 window ────────────────────────────────────────────────────────────────────── remarks: Changes the border style of a window. If 'window' is not specified, the current window is assumed. Note that the window must first be configured to allow borders by calling the 'setframe' function. The following parameters can be specified: xd - left and right border thickness yd - top and bottom border thickness cornerX - amount or horz overlap on the border corners cornerY - amount or vert overlap on the border corners bchr1 - border fill character bchr2 - border corner fill character The following options can also be specified: i - inward 3D effect o - outward 3D effect s - attempts to change the size of other parts of the window to accommodate the new border style, without changing the overall size of the window. 0 - use 'expanded' borders (the default) For the following options, the 'xd', 'yd', 'cornerX', and 'cornerY', 'bchr1', and 'bchr2' parameters are ignored, and the horizontal and vertical border thickness is always 1: 1 - single line 2 - double horizontal 3 - double vertical 4 - double line 5 - solid 6 - blank Specifying no options or parameters removes any existing borders. returns: nothing see also: getborder, setframe, setshadow example: setborder // removes the border setborder "1i" // sets the border style to a single-line border with // an inward 3D effect setborder '0' 2 2 3 3 // sets the border style to an 'expanded' border with // border width 2 and corner size 3 setbufname name buffer ────────────────────────────────────────────────────────────────────── remarks: Associates a descriptive name with a buffer. If 'buffer' is null or not specified, then the current buffer is assumed. The buffer name is used by editor library functions to identify the current buffer, and is usually a fully qualified file name. Note: the 'loadbuf' function will automatically set the buffer name to the file name where the buffer was loaded ('setbufname' is not required). returns: nothing see also: getbufname setcolor component color window ────────────────────────────────────────────────────────────────────── remarks: Changes the color attribute of a window component. If 'window' is not specified, the current window is assumed. The following values can be specified for 'component': 0 - border 1 - border corners 2 - north and east titles 3 - south and west titles 4 - title bar controls 5 - text 6 - marks 7 - scroll bars 8 - menus 9 - menu character highlight 10 - menu disable 11 - menu bar highlight 12 - end-of-text line 13 - border highlight color 14 - folds 15 - modified lines 16 - modified line at the cursor 17 - open fold begin 18 - open fold end returns: nothing see also: getcolor example: setcolor 5 95 // sets the window text color to white on magenta setcolor 6 32 // sets the mark default color to black on green setcursor opt=[rhiv+-] cursor buffer ────────────────────────────────────────────────────────────────────── remarks: Creates a new cursor or changes the state of an existing cursor. If 'buffer' is null or not specified, then the current buffer is assumed. If 'cursor' is not specified, the current cursor is assumed. If 'cursor' refers to an existing cursor, it is modified according to the options specified, otherwise a new cursor is created. If a new cursor is created, it becomes the current cursor. Any of the following options may be specified: i - cursor is in insert mode h - cursor is hidden v - blinking hardware cursor indicates position - - turns off any specified options + - turns on any specified options returns: The cursorid if a cursor is created, or TRUE if an existing cursor is modified successfully, otherwise null. see also: cursor?, destroycursor setdisplay [-1/0/1] ────────────────────────────────────────────────────────────────────── remarks: Enables (1) or disables (0) updating of the display. Note that any operations involving window sizing, movement, or reordering will still update the display, even if the display is disabled with this function. If -1 is specified, the display is 'validated' and the next screen update will be skipped. This allows you to draw on the text in an Edit or File Manager window, leaving your changes visible until the following screen update. returns: nothing see also: display example: setdisplay OFF // disable display for faster execution playkey // play the scrap key macro setdisplay ON // enable the display writestr "Hello" // write 'Hello' in an edit window setdisplay -1 // allow it to remain visible setdraw opt=[01234] window [Lib][a] ────────────────────────────────────────────────────────────────────── remarks: Changes the line drawing style for an edit window. If 'window' is not specified, the current window is assumed. One of the following options can be specified: 0 - single lines 1 - double horizontal lines 2 - double vertical lines 3 - double horizontal and vertical lines 4 - eraser returns: nothing see also: setting example: setdraw 3 // sets the line drawing style to double horizontal // and vertical lines setframe opt=[bwneshvm2345z>+-] window westwidth eastwidth ────────────────────────────────────────────────────────────────────── remarks: Adds or removes window frame components. If 'window' is not specified, the current window is assumed. Any of the following options can be specified: + - add specified components to the window - - remove specified components from the window (if neither '+' or '-' are specified, then the window frame components are replaced) b - border e - east title bar h - horizontal scroll bar m - primary menu bar n - north title bar s - south title bar v - vertical scroll bar w - west title bar z - south title controls 2 - menu bar 2 (north) 3 - menu bar 3 (north) 4 - menu bar 4 (south) 5 - menu bar 5 (west) > - place north title bar in the window border (for bordertype > 0) < - place south title bar in the window border (for bordertype > 0) Specifying no options will remove all window frame components. The following parameters can also be specified: westwidth - the width of the west title, if present eastwidth - the width of the east title, if present returns: nothing see also: frame?, setborder, setshadow example: setframe // removes all frame components from the current window setframe "bn" // replaces the current window frame components with // a border and a north title bar setframe "+s" // adds a south title bar to the current window setgroupbox initvalue valuemap window [Lib][a] ────────────────────────────────────────────────────────────────────── remarks: Re-initializes the checked/unchecked state of check boxes and radio buttons in a group box, after the group box has already been created. If 'window' (the group box window id) is not specified, the current window is assumed. See the 'group' function for a description of 'initvalue' and 'valuemap'. returns: nothing see also: dialog, group, whenenter, whenselect setname filename [Lib][edit] ────────────────────────────────────────────────────────────────────── remarks: Changes the buffer name in the current edit window to the specified filename. The primary window title (title 1) is also changed. returns: 1 if successful, -1 if the filename is invalid, or -2 if the filename is already loaded. see also: close, open, save, setbufname, settitle setnextwin nextwindow window ────────────────────────────────────────────────────────────────────── remarks: Changes the order of windows on the screen by placing 'nextwindow' on top of 'window'. If 'window' is not specified, the current window is assumed. returns: Non-zero if successful, otherwise null. see also: getnextwin, getprevwin, setprevwin setpalette position charstring ────────────────────────────────────────────────────────────────────── remarks: Fills a 100-byte user-defined color palette area with 'charstring', starting at the specified position in the palette. The editor library code (LIB.X) expects color attributes to be in the positions defined in COLOR.AML. returns: nothing see also: getpalatte example: see COLOR.AML setparent parent window ────────────────────────────────────────────────────────────────────── remarks: Makes 'parent' the parent window of 'window'. If 'window' is not specified, the current window is assumed. returns: Non-zero if successful, otherwise null. see also: getparent setprevwin prevwindow window ────────────────────────────────────────────────────────────────────── remarks: Changes the order of windows on the screen by placing 'window' on top of 'prevwindow'. If 'window' is not specified, the current window is assumed. returns: Non-zero if successful, otherwise null. see also: getnextwin, getprevwin, setnextwin setrepeat timerid milliseconds object function arg1 arg2 ... ────────────────────────────────────────────────────────────────────── remarks: Sets a timer to call 'function' automatically at regular intervals. 'milliseconds' specifies the time interval in milliseconds. The first function call will occur after the specified time interval has expired (not after the 'setrepeat' call). The function is called in the specified object, passing the optional arguments 'arg1', 'arg2', etc. If 'object' is not specified, the current event object is assumed. 'timerid' uniquely identifies the timer. If a timerid is not specified, a unique timerid is generated. A maximum of 16 timerid's may be active at one time. returns: The timerid if successful, otherwise null. see also: destroytimer, setalarm, settimer, timer? example: setrepeat "xyz" 1000 '' "abc" // sets timerid 'xyz' to call the function 'abc' every // second in the current event object setrepeat "t1" 0 '' "idle" // sets timerid 't1' to call the function 'idle' // repeatedly in the current event object whenever // the editor is idle setshadow right bottom window ────────────────────────────────────────────────────────────────────── remarks: Adds or removes window shadows. If 'window' is not specified, the current window is assumed. 'bottom' and 'right' specify the shadow thickness on the bottom and right borders. If 'bottom' and 'right' are zero or null, the shadow is removed. returns: nothing see also: setborder, setframe, setshadow2 example: setshadow // removes any shadows from the current window setshadow 2 1 // sets the shadow thickness to 2 on the right border // and 1 on the bottom border setshadow2 color window ────────────────────────────────────────────────────────────────────── remarks: Adds or removes a one-half width shadow. If 'window' is not specified, the current window is assumed. 'color' specifies the shadow color. This function is intended for use with stationary windows on a blank background (such as dialog box controls). returns: nothing see also: setshadow setsyntax [0/1] object window ────────────────────────────────────────────────────────────────────── remarks: Enables (1) or disables (0) syntax highlighting for a window. If 'window' is not specified, the current window is assumed. Specifying 'object' will change the syntax highlighting object associated with the window. returns: nothing see also: keyword, setsyntax settimer timerid milliseconds object function arg1 arg2 ... ────────────────────────────────────────────────────────────────────── remarks: Sets a timer to call 'function' automatically after a specified time interval. 'milliseconds' specifies the time interval in milliseconds. The timer is automatically destroyed when the function is called. The function is called in the specified object, passing the optional arguments 'arg1', 'arg2', etc. If 'object' is not specified, the current event object is assumed. 'timerid' uniquely identifies the timer. If a timerid is not specified, a unique timerid is generated. A maximum of 16 timerid's may be active at one time. returns: The timerid if successful, otherwise null. see also: destroytimer, setalarm, setrepeat, timer? example: settimer "xyz" 1000 '' "abc" // sets timerid 'xyz' to call the function 'abc' one // second later in the current event object setting settings [0/1/2/-1] [Lib][edit] ────────────────────────────────────────────────────────────────────── remarks: Changes or toggles the specified window settings. Any combination of the following settings may be specified: a - Autoindent b - Backup d - Draw Mode i - Insert Mode l - Live Word Wrap m - Match Character s - Smart tabs t - Translate u - Undo enabled v - Variable tabs w - Word Wrap (standard) x - Syntax Highlighting After the 'settings' parameter, one of the following values can be specified: 0 - turns specified settings OFF 1 - turns specified settings ON -1 - toggles specified settings 2 - sets specified settings to default values returns: nothing see also: getsettings, setting? example: settings "abu" 1 // turns ON autoindent, backup, and undo settings "xd" 0 // turns OFF syntax highlighting and drawmode settings "w" -1 // toggles word wrap setting? settings [Lib][mon] ────────────────────────────────────────────────────────────────────── remarks: Tests if any of the specified window settings are ON. See the 'setting' command for a description of window settings. returns: Non-zero if one of the specified settings is ON, otherwise null. see also: getsettings, setting example: setting? "lw" // tests if word wrap or live word wrap are ON settitle string opt=[nsewlcrdxh1z] titleid[1-5] window ────────────────────────────────────────────────────────────────────── remarks: Changes a window title. If 'window' is null or not specified, then the current window is assumed. Each window can have up to 5 titles. 'titleid' (1-5) specifies which window title to change. If the 'titleid' is null or not specified, then 1 (the primary title) is assumed. Any combination of the following options can be specified: e - places the title on east title bar n - places the title on north title bar s - places the title on south title bar w - places the title on west title bar l - left justifies the title c - centers the title r - right justifies the title d - redraws the window title immediately after this function call x - sets the title to the 'default status line'. The status line displays information about the buffer (if any) displayed in the window. h - checks for the highlight character "&". Specifying "&" before a character in the title indicates that the character is to be highlighted. 1 - the title is not padded with spaces. Normally the title is padded with one space if it is left or right justified. z - hides the title. This can be used to associate a string with a window by storing it as a hidden window title. This option must also be used to specify a title for the end-of-text line (see the 'eotstring' function). If no options are specified, and the title has not been previously set, the options 'nl1' are assumed. If the title has been previously set, then the options of the previous title are assumed. returns: TRUE if successful, otherwise null. see also: eotstring, gettitle example: settitle "Hello World" // sets window title 1 to 'Hello World' settitle "Hello World" "cs" 3 // sets window title 3 to 'Hello World' and // centers it on the south title bar setvideo cols rows color fillstring ────────────────────────────────────────────────────────────────────── remarks: Changes the video mode and/or sets the background color attribute and background fill string. Either operation can be done separately or simultaneously. When changing the video mode, 'cols' must be 40 or 80 and 'rows' must be 12, 14, 21, 25, 28, 43, or 50. If 'cols' or 'rows' are zero or null, the video mode is not changed. Specifying either 'color' or 'fillstring' changes the video background. If 'color' is not specified, black (0) is assumed. If 'fillstring' is not specified, blanks are assumed. The maximum size of 'fillstring' is 50 characters. returns: TRUE if successful, otherwise null. see also: videomode setwinctrl controlstring rightcontrol window ────────────────────────────────────────────────────────────────────── remarks: Changes the one-character title bar controls for a window. If 'window' is not specified, the current window is assumed. Controls are normally placed on the north title bar unless south title bar controls are specified with the 'setframe' function. 'controlstring' is a string of the one-character title bar controls to appear on the title bar from left to right. By default, controls are left justified on the title bar. If specified, 'rightcontrol' defines the character position in 'controlstring' of the first right justified control. returns: TRUE if successful, otherwise null. see also: getwinctrl example: setwinctrl "" // places one left justified control () on the // title bar setwinctrl "≡" 2 // places 3 controls on the title bar. (≡) is // left justified, () and () are right justified setwincurs cursor window ────────────────────────────────────────────────────────────────────── remarks: Attaches a cursor to a window and associates a buffer with a window. If 'window' is not specified, the current window is assumed. When a cursor is attached to a window, the window will display the buffer associated with the cursor. If 'cursor' is null or not specified, then the cursor is detached from the window and the window will no longer display a buffer. Only one cursor may be associated with a window at one time. Windows that do not display a buffer do not need to use this call. returns: TRUE if successful, otherwise null. see also: getwincurs setwinobj object window ────────────────────────────────────────────────────────────────────── remarks: Sets the window event object associated with a window. If 'window' is not specified, the current window is assumed. This function also changes the current event object to 'object'. Whenever a window becomes the current window, the current event object is set to the window event object. This allows an object 'class' to be associated with an individual window. returns: nothing see also: eventobject, getwinobj example: setwinobj "edit" // sets the event object for the current window to // 'edit', and also changes the current event object // to 'edit' shiftblock (+/-)cols mark fillchar ────────────────────────────────────────────────────────────────────── remarks: Shifts marked text to the left or to the right. If 'mark' is not specified, the default markid is assumed. 'cols' specifies the number of columns to shift. Positive values shift text to the right and negative values shift text to the left. 'fillchar' is the character to use when filling empty spaces created by shifting to the right. If 'fillchar' is not specified, blanks (ASCII 32) are assumed. returns: TRUE if successful, otherwise null. see also: delchar, instext example: shiftblock -1 // shifts the text in default markid one space to the // left shiftblock 1 '' '>' // shifts the text in the default markid one space to // the right, filling empty spaces with '>' shiftkey? shiftstate ────────────────────────────────────────────────────────────────────── remarks: Tests if the specified shift key(s) are currently pressed down. 'shiftstate' can be any combination of the following values OR'ed together bitwise: 01h - right shift key down 10h - scroll lock ON 02h - left shift key down 20h - num lock ON 04h - ctrl key down 40h - caps lock ON 08h - alt key down 80h - insert ON If shiftstate is not specified, then a value of 03h (right and left shift keys) is assumed. returns: Non-zero if the specified shift keys are down, otherwise zero. see also: event?, keyhit? example: shiftkey? // tests if the left or right shift keys are pressed shiftkey? 12h // tests if the <ctrl> or <alt> keys are pressed shortbox message title opt=[b] [Lib][a] ────────────────────────────────────────────────────────────────────── remarks: Displays the specified message in a popup window without an 'Ok' button. If a title is not specified, 'Message' is assumed. If option 'b' is specified, the PC speaker beeps. returns: nothing see also: msgbox, okbox, say, yncbox example: shortbox "This is a message with a beep!" 'b' showcursor top bottom ────────────────────────────────────────────────────────────────────── remarks: Shows the physical cursor in the current window. If the current window contains a buffer, the effects of this function are temporary and may disappear the next time the display is updated. If 'top' and 'bottom' are specified, the physical cursor size is changed. 'top' and 'bottom' indicate the distance of the top and bottom of the cursor from the top of the character cell, on a scale of 0 to 99. returns: nothing see also: hidecursor example: showcursor 0 99 // sets the cursor size to fill the entire char cell showcursor 50 99 // sets the cursor size to fill the bottom half of // the character cell showdialog [Lib][a] ────────────────────────────────────────────────────────────────────── remarks: Tags the current dialog box as a 'modeless' dialog box. The dialog box will function as an independent window on the desktop (existing windows on the screen can be placed on top of a modeless dialog box). This function returns immediately, without actually displaying the dialog box. The 'whenenter' and 'whenselect' functions can be used to process events from dialog box controls. returns: nothing see also: dialog, getdialog, whenenter, whenselect example: dialog "Test Dialog Box" 40 8 button "O&k" 17 2 8 // tag the dialog box as modeless showdialog showentry ────────────────────────────────────────────────────────────────────── remarks: Temporarily displays the screen as it appeared in DOS immediately before the editor was started. Pressing any key or mouse button will restore the editor screen. returns: nothing see also: display showmouse ────────────────────────────────────────────────────────────────────── remarks: Shows the mouse pointer. returns: nothing see also: hidemouse showwindow window ────────────────────────────────────────────────────────────────────── remarks: Re-displays a window that was previously hidden with the 'hidewindow' function. If 'window' is null or not specified, then the current window is assumed. returns: nothing see also: hidewindow sizekey [Lib][win] ────────────────────────────────────────────────────────────────────── remarks: Resizes the current window using the cursor keys. returns: nothing see also: pankey, sizewin sizeof string ────────────────────────────────────────────────────────────────────── remarks: Gets the size of a string in bytes. returns: the number of characters in the string. see also: copystr, pad example: sizeof "apples" // returns 6 sizeof '' // returns 0 sizeof "ab" + "bc" // returns 4 sizeof 50 + 51 // returns 3 sizequeue size ────────────────────────────────────────────────────────────────────── remarks: Removes all events from the event queue and changes the event queue size to 'size' events. Values of 5 through 200 may be specified. The default queue size is 20 when the editor is started. returns: Non-zero if successful, otherwise zero. see also: dispatch, process sizewin l t r b reps opt=[acdrswz1] window [Lib][win] ────────────────────────────────────────────────────────────────────── remarks: Resizes the specified window. If 'window' is not specified, the current window is assumed. This function is nearly identical to the 'sizewindow' builtin function, except that the window title bar controls are set properly after resizing, and 'reps' (sizing repetitions) can be specified. returns: nothing see also: movewindow, sizewindow sizewindow l t r b opt=[acdrswz1] window relativewindow ────────────────────────────────────────────────────────────────────── remarks: Changes the size and position of a window. If 'window' is not specified, the current window is assumed. When a window is resized, all parts of the window are redrawn immediately. 'l', 't', 'r', and 'b' specify the new window coordinates. The following options can be specified: a - The coordinates are absolute and are relative to an 'origin'. The location of the origin depends on which of the following options are also specified: d - the origin is located at the top left corner of the physical screen w - the origin is located at the top left corner of the window 'relativewindow' 1 - the origin is located at the top left corner of the client area of the window 'relativewindow' z - the origin is located at the virtual coordinates (0,0) If option 'a' is specified and none of the above options are specified, then 'd' is assumed. r - the coordinates are relative to another rectangle on the screen. 'l', 't', 'r', and 'b' specify relative offsets from the left, top, right, and bottom edges of the rectangle. The location of the rectangle depends on which of the following options are also specified: d - the rectangle is the physical screen w - the rectangle is the main window area of the window 'relativewindow' 1 - the rectangle is the client area of the window 'relativewindow' z - the rectangle is the main window area of the window being resized (relative to itself, in other words) If option 'r' is specified and none of the above options are specified, then 'z' is assumed. c - the coordinates specify the size of the client area of the window being sized, not the entire window. s - scrolls the window to keep the cursor visible, if needed If no options are specified, options 'rz' are assumed. returns: TRUE if successful, otherwise null. see also: getcoord, movewindow example: sizewindow -1 -1 1 1 // expands the current window size by 1 in all four // directions sizewindow 0 0 0 0 "rd" // sizes the current window to fill the entire screen // with all the borders visible sizewindow 6 5 72 20 "ad" // sizes the current window relative to the upper // left corner of the screen sizewindow 6 5 72 20 "a1" '' "abc" // sizes the current window relative to the upper // left corner of the client area of window 'abc' sortblock opt=[di] mark ────────────────────────────────────────────────────────────────────── remarks: Sorts marked lines. If 'mark' is not specified, the default markid is assumed. For column marks, the text between the left and right edges of the mark is used as the sort key. For all other marks, the entire line is used as the sort key. In either case, all lines spanned by the mark are sorted, not just the text within the mark. One of the following options may be specified: d - sort in descending order i - ignore case when sorting returns: TRUE if successful, otherwise null. speaker [0/1] ────────────────────────────────────────────────────────────────────── remarks: Enables (1) or disables (0) sound from the PC speaker. returns: nothing see also: beep splitline col row buffer ────────────────────────────────────────────────────────────────────── remarks: Splits one line into two lines in a buffer. If 'buffer' is null or not specified, then the current buffer is assumed. 'row' specifies which line is to be split and 'col' specifies the column where the split is to occur. If 'row' and 'col' are not specified, the current cursor position is assumed. All characters after, and including the specified column are moved to column 1 in a new line after the line to be split. returns: TRUE if successful, otherwise null. see also: delline, insabove, insline, joinline example: splitline // splits the current line at the cursor in the // current buffer splitline 10 // splits the current line at column 10 splitstr delimit+quote multistring ref1 ref2 ... ────────────────────────────────────────────────────────────────────── remarks: Splits an editor 'multistring' (created by the 'joinstr' function) into individual strings. The 'delimit' and 'quote' characters are used as delimiters and literal quoting characters to separate the string (see 'joinstr' above). If 'delimit' and 'quote' are not specified, then the default delimiter character is a slash (/) and the default quote character is a backquote (`). 'ref1', 'ref2', etc. refer to variables passed by reference which are to contain the resulting component strings (see the 'ref' keyword). returns: This function returns the number of component strings in the multistring. The actual component strings are returned in variables passed by reference to this function. see also: joinstr, ref example: splitstr '' "abc/def/xyz" ref a ref b ref c // returns 'abc' in a, 'def' in b, and 'xyz' in c. // the entire function call returns '3' splitstr "|\\" "abc|x\|yz" ref a ref b // returns 'abc' in a, and 'x|yz' in b. // the entire function call returns '2' splitwin opt=[hv] [Lib][edit] ────────────────────────────────────────────────────────────────────── remarks: Splits the current edit window. The following options may be specified: h - favor horizontal splits v - favor vertical splits returns: TRUE if successful, otherwise null. see also: copywin stayresident ────────────────────────────────────────────────────────────────────── remarks: Forces the currently executing macro (invoked by the runmacro function) to remain resident within the editor after the macro is finished executing. Any functions, object variables, or global variables defined in the macro will also remain resident. The macro will remain resident until the temporary object created by 'runmacro' is explicitly destroyed with the 'destroyobject' function. returns: nothing see also: destroyobject, runmacro stopmark mark ────────────────────────────────────────────────────────────────────── remarks: Closes an 'open' mark created with the markline, markcolumn, markchar, or markstream functions. This stops the automatic extension of the mark when the cursor is moved. If 'mark' is not specified, the default markid is assumed. returns: nothing see also: extendmark, markchar, markcolumn, markline, markstream example: markline // marks the current line stopmark // stop cursor extension of the mark sub searchstr replacestr string opt=[irwx] ────────────────────────────────────────────────────────────────────── remarks: Replaces all occurrences of 'searchstr' found in 'string' with 'replacestr'. Any of the following search options may be specified: i - ignore case r - search in reverse from the end of the string w - whole words only x - use regular expressions (see 'Regular Expression Searching') Specifying a null replace string will remove all occurrences of 'searchstr' within 'string'. returns: The new string resulting from the substitution of 'replacestr' for all occurrences of the search string. see also: pos, poschar, posnot example: sub 'p' '112' "apples" // returns 'a112112les' sub 'es' 'y' "apples" // returns 'apply' sub 'PL' '' "apples" 'i' // returns 'apes' submenu menuname [Lib][a] ────────────────────────────────────────────────────────────────────── remarks: Displays the specified menu as a submenu. This function is only intended for use within a pulldown menu. returns: nothing see also: getmenu, gotomenu, menu swapfiles swapfile1 swapfile2 swapfile3 ────────────────────────────────────────────────────────────────────── remarks: Defines swap files for the editor to use in low memory situations. If available, EMS and XMS memory will always be used before the swap files are created. 'swapfile2' will only be used when there is no room on the drive containing 'swapfile1', and 'swapfile3' will only be used when there is no room on the drive containing 'swapfile2'. All swap files should be on different drives. Note: this function may only be called once during an edit session. returns: TRUE if successful, otherwise null. see also: maxems, maxxms, memoptions syntax opt=[bcin] symbols stringchars stringlit numeric eolcom1 startcol1 eolcom2 startcol2 opencom1 closecom1 opencom2 closecom2 backscan keywordcolor symbolcolor stringcolor numericcolor eolcomment1color eolcomment2color comment1color comment2color ────────────────────────────────────────────────────────────────────── remarks: Defines a syntax highlighting template for the current (executing) object. A syntax highlighting template can be customized to highlight the source code of almost any programming language, or even text files. Any of the following syntax highlighting options can be specified: b - highlighting shows through marked blocks c - disable highlighting on the line at the cursor f - use only the foreground portion of the specified colors, and use the existing background color of the window i - ignore keyword case n - automatically highlight numbers The following parameters can also be specified: symbols - defines a set of one-character language symbols to be highlighted. A maximum of 40 symbols can be specified. stringchars - defines up to 3 one-character string symbols used to enclose highlighted character strings. stringlit - the character used to indicate a literal character in a character string. numeric - the character (if any) used to indicate a numeric value. eolcom1 - single line comment symbol 1 (10 char max) startcol1 - the required start column for 'eolcom1'. If not specified, all columns are checked. eolcom2 - single line comment symbol 2 (10 char max) startcol2 - the required start column for 'eolcom2'. If not specified, all columns all checked. opencom1 - the start symbol for multiline comment 1 (10 char max) closecom1 - the end symbol for multiline comment 1 (10 char max) opencom2 - the start symbol for multiline comment 2 (10 char max) closecom2 - the end symbol for multiline comment 2 (10 char max) backscan - the number of lines to scan backwards to check if a multiline comment is in effect (400 line max) The following syntax highlighting colors may also be specified: keywordcolor symbolcolor stringcolor numericcolor eolcom1color eolcom2color comment1color comment2color If option 'f' is specified, and the window foreground color is equal to the foreground portion (lower 4 bits) of any of the above colors, then the background portions (upper 4 bits) of these colors are used as alternate foreground colors. This allows you to change the window color without having to change the syntax highlighting color definitions. returns: nothing see also: keyword, setsyntax example: see the configuration file SYNTAX.AML tabblock (+/-)tabwidth[1-64] mark ────────────────────────────────────────────────────────────────────── remarks: Entabs or detabs marked text. If 'mark' is not specified, the default markid is assumed. 'tabwidth' specifies the tab width to use. If 'tabwidth' is not specified, then 8 is assumed. If 'tabwidth' is positive, then tab characters (ASCII 9) are converted into spaces (detab). Tab characters within single or double quotes are ignored. If 'tabwidth' is negative, then spaces are converted into tab characters (entab). Spaces occurring after a single or double quote on a line will not be entabbed. returns: TRUE if successful, otherwise null. thousands number ────────────────────────────────────────────────────────────────────── remarks: Converts a number into a thousands-separated string. The 'international' function determines what thousands separator character is used. returns: a thousands-separated string. see also: international example: thousands 12345678 // returns '12,345,678' tile opt=[hv] [Lib][win] ────────────────────────────────────────────────────────────────────── remarks: Tiles all non-minimized windows on the screen. The following options may be specified: h - favor horizontal tiling v - favor vertical tiling returns: nothing see also: cascade, splitwin tilewindow opt=[hvlb] splitnum limit window ────────────────────────────────────────────────────────────────────── remarks: Tiles windows on the screen, or 'splits' a window into tiles. If 'window' is not specified, the current window is assumed. 'limit' specifies the maximum number of tiles. If 'limit' is null or zero, then all windows are tiled. 'splitnum' specifies the maximum number of tiles that can be oriented in one direction before the next tile is oriented in a perpendicular direction. If 'splitnum' is null or zero, 2 is assumed. The following options can be specified: b - reverses the tiling order by starting with the bottom window on the screen h - favors horizontal splits l - tile only the specified window and any other windows which display the same buffer v - favors vertical splits If no options are specified, then 'h' is assumed. returns: TRUE if successful, otherwise null. see also: getcoord, movewindow, sizewindow example: tilewindow // tiles all windows horizontally on the screen tilewindow 'lv' // vertically tiles any windows which display // the same buffer as the current window timer? timerid ────────────────────────────────────────────────────────────────────── remarks: Tests if the specified timer is active. returns: TRUE if timerid is active, otherwise null. see also: destroytimer, setalarm, settimer toolbar [Lib][edit] ────────────────────────────────────────────────────────────────────── remarks: Toggles the display of a toolbar on the current edit window. The toolbar is defined in MENU.AML. returns: nothing see also: togglestyle touchfile filename ────────────────────────────────────────────────────────────────────── remarks: Changes the last-modified date and time for the specified file to the current date and time. returns: Non-zero if successful, otherwise zero. see also: chgfileattr, copyfile trackmouse [Lib][a] ────────────────────────────────────────────────────────────────────── remarks: Moves the cursor to the mouse pointer in the current buffer. returns: nothing see also: getmousex, getmousey, mousepos, virtocol, virtorow trunc? buffer ────────────────────────────────────────────────────────────────────── remarks: Tests if the specified buffer has been truncated when loaded. Truncation can occur if <ctrl break> was pressed while loading the file. If 'buffer' is null or not specified, the current buffer is assumed. returns: TRUE if the buffer was truncated, otherwise null. see also: buffer? undo buffer ────────────────────────────────────────────────────────────────────── remarks: Reverses the changes made by the last undoable function (or group of functions marked with undobegin - undoend) for a specific buffer. If 'buffer' is null or not specified, then the current buffer is assumed. returns: TRUE if successful, otherwise null. see also: redo, undobegin, undoend undobegin ────────────────────────────────────────────────────────────────────── remarks: Marks the beginning of a group of function calls which are considered to be one 'undoable/redoable' editing operation. The group is terminated by a matching 'undoend' function. 'undobegin' and 'undoend' pairs may be nested. Undo/redo information for all undoable function calls within this group is saved as one undoable operation on the undo/redo stack for each operation's buffer. The follow types of editing functions are undoable: - functions which modify buffers - functions which create or modify marks - functions which create or modify text folds The current cursor position, window size, and window view, are also saved on the undo/redo stack. When the 'undo' or 'redo' functions are called, all undoable editing operations within the group are 'undone' together at one time. returns: nothing see also: redo, undo, undocursor, undoend example: undobegin // groups 3 editing operations delline // together as one undoable writetext "some text" // operation insline "new line" undoend undocursor buffer ────────────────────────────────────────────────────────────────────── remarks: Saves the current window size, window view, and cursor position on the undo/redo stack as one undoable operation. If 'buffer' is null or not specified, then the current buffer is assumed. returns: nothing see also: redo, undo, undobegin, undoend undoend ────────────────────────────────────────────────────────────────────── remarks: Marks the end of a group of undoable/redoable function calls started with the 'undobegin' function (see 'undobegin' above). returns: nothing see also: redo, undo, undobegin undosize size buffer ────────────────────────────────────────────────────────────────────── remarks: Sets the undo/redo stack size for a buffer to 'size' editing operations. If 'buffer' is null or not specified, the current buffer is assumed. Setting the undo/redo stack size to zero disables undo/redo for the specified buffer. The stack size determines the maximum number of undoable editing operations (single or group) that will be saved for each buffer. When an undoable operation is performed and the size limit is exceeded, the undo information for the least-recently performed operation is discarded. When a buffer is initially created, the undo/redo stack size is set to zero (undo is disabled). Whenever the undo/redo stack size is changed with this function, all previous undo/redo information for the buffer is erased. returns: nothing see also: redo, undo, undobegin, undoend example: undosize // disables undo for the current buffer undosize 200 // deletes the current undo stack and sets the undo // stack size for the current buffer to 200 // editing operations unsetx varexpression objexpression ────────────────────────────────────────────────────────────────────── remarks: Destroys the object variable defined by 'varexpression' in the specified object. If 'objexpression' is not specified, then the current object is assumed. returns: nothing see also: function?, lookup, set, setobj, setx, setxfun, setxobj example: unsetx "TempVar" unsetx "Temp" + "Var" "edit" up rows buffer ────────────────────────────────────────────────────────────────────── remarks: Moves the cursor upward. 'rows' specifies the number of lines to move. If 'rows' is not specified, 1 is assumed. If 'buffer' is null or not specified, the current buffer is assumed. returns: TRUE if successful, otherwise null. see also: down, left, right example: up // moves the cursor up 1 row up 5 // moves the cursor up 5 rows upcase string ────────────────────────────────────────────────────────────────────── remarks: Converts a string to uppercase. returns: the string in uppercase. see also: flipcase, locase example: upcase "peaches" // returns "PEACHES" usemark mark ────────────────────────────────────────────────────────────────────── remarks: Sets the default markid to 'mark'. If 'mark' is not specified, the markid '*' is assumed. When the editor is started, the default markid is '*'. returns: The previous default markid. see also: getmarkuse example: oldid = usemark 'T' // set the default markid to 'T' . . usemark oldid // always restore the default markid videoborder color ────────────────────────────────────────────────────────────────────── remarks: Changes the video overscan border color to the specified color. returns: nothing videomode cols rows [Lib][a] ────────────────────────────────────────────────────────────────────── remarks: Changes the current video mode to 'cols' x 'rows'. 'cols' must be 40 or 80 and 'rows' must be 12, 14, 21, 25, 28, 43, or 50. returns: nothing see also: setvideo example: videomode 80 28 // change the video mode to 80 x 28 videomode 80 50 // change the video mode to 80 x 50 virtocol virtualX window ────────────────────────────────────────────────────────────────────── remarks: Converts a virtual screen X-coordinate to a column in a window. If 'window' is not specified, the current window is assumed. If 'virtualX' is not specified, the current mouse pointer position is assumed. returns: the window column. see also: virtorow example: say (virtocol) // displays the column in the current window where // the mouse pointer is located virtorow virtualY window ────────────────────────────────────────────────────────────────────── remarks: Converts a virtual screen Y-coordinate to a row in a window. If 'window' is not specified, the current window is assumed. If 'virtualY' is not specified, the current mouse pointer position is assumed. returns: the window row. see also: virtocol example: say (virtorow) // displays the row in the current window where // the mouse pointer is located whenenter functionname [Lib][a] ────────────────────────────────────────────────────────────────────── remarks: Defines an event-handling function to be called by the most recently defined dialog box control, when the control has the focus and the <enter> key (or equivalent) is pressed. The control 'id' (a number indicating the order in which the control was defined) is passed to the event-handling function. returns: nothing see also: dialog, getdialog, showdialog, whenselect example: dialog "Test Dialog Box" 40 8 button "&Test" 17 4 8 whenenter "testbutton" // beep when the 'Test' button is pressed function testbutton (id) msgbox "You pressed control #" + id end getdialog whenselect functionname [Lib][a] ────────────────────────────────────────────────────────────────────── remarks: Defines an event-handling function to be called by the most recently defined group box or list box control, when an item is selected within the control (without pressing <enter> or the equivalent). The control 'id' (a number indicating the order in which the control was defined) is passed to the event-handling function. returns: nothing see also: dialog, getdialog, showdialog, whenenter example: dialog "Test Dialog Box" 40 8 groupbox 'Radio Buttons: ' 10 2 ( menu '' item " ( ) Beep at &200hz" item " ( ) Beep at &400hz" item " ( ) Beep at &600hz" end ) whenselect "radio" function radio (id) beep getrow * 200 500 end getdialog window? window ────────────────────────────────────────────────────────────────────── remarks: Tests if a window exists. If 'window' is not specified, the current window is assumed. returns: TRUE if the window exists, otherwise null. see also: frame?, wintype? windowflag opt=[ds-] window ────────────────────────────────────────────────────────────────────── remarks: Turns window flags on or off. If 'window' is null or not specified, the current window is assumed. The following flags can be specified: d - flags the window to call the function 'ondraw' in the window event object after the window client area is updated. This allows custom drawing or highlighting of the window client area to be performed. s - flags the window to call the function 'onstatus' in the window event object before the status line is updated (edit windows only). The user-defined return value of 'onstatus' will become the actual status line, allowing the status line to be customized. - - turns off flags If option '-' is specified, any other specified flags will be turned off, otherwise all specified flags will be turned on. returns: nothing see also: ondraw, onstatus winlist [Lib][a] ────────────────────────────────────────────────────────────────────── remarks: Displays a list of open windows. If a window is selected, it becomes the current window. returns: nothing see also: currwin wintype? object window ────────────────────────────────────────────────────────────────────── remarks: Tests if the specified object is located in the inheritance path of the window event object. If 'window' is not specified, the current window is assumed. returns: TRUE if 'object' is located in the inheritance path of the window event object, otherwise null. see also: objtype? example: wintype? "edit_fmgr" // tests if the object 'edit_fmgr' is located in the // inheritance path of the window (tests if the // window is a fmgr window or an edit window) write string [Ext][edit,prompt] ────────────────────────────────────────────────────────────────────── remarks: Enters a string into the current buffer at the cursor position, and moves the cursor to the end of the string. If the cursor is in insert mode, the string is inserted into the text, otherwise the string is overlaid onto the text. This function is similar to the 'writetext' function. However, the 'write' function provides support for the following window settings: - Live Word Wrap - MatchCharacter - Standard Word Wrap - Translate returns: nothing see also: instext, ovltext, writetext example: write "some text" writefile handle string opt=[k] ────────────────────────────────────────────────────────────────────── remarks: Writes the specified string at the current position in the open file specified by 'handle'. The current position in the file is advanced by the number of characters written. If option 'k' is specified, the file date and time are not modified. returns: The number of characters written if successful, otherwise null. see also: closefile, filepos, openfile, readfile writeline string color col row ────────────────────────────────────────────────────────────────────── remarks: Displays the specified string in the current window using the color attribute 'color'. If 'col' and 'row' are not specified, the current cursor position is assumed. If 'color' is not specified, the window 'text' color is assumed (see 'setcolor'). The current cursor position is moved to column one of the next row. If the cursor was on the last row in the window, the window contents are scrolled up by one line. If the current window contains a buffer, the effects of this function (except for cursor movement) are temporary and will disappear the next time the display is updated. returns: nothing see also: fillrect, getattr, getstr, getx, gety, gotoscreen, gotoxy, hilite, writestr example: writeline "some text" // writes the string 'some text' at the cursor and // moves the cursor to the next line writeline "some text" 95 // writes the string 'some text' at the cursor with the // color white on magenta, and moves the cursor to // the next line writestr string color col row ────────────────────────────────────────────────────────────────────── remarks: Displays the specified string in the current window using the color attribute 'color'. If 'col' and 'row' are not specified, the current cursor position is assumed. If 'color' is not specified, the window 'text' color is assumed (see 'setcolor'). The current cursor position is moved one column past the end of the string. If the current window contains a buffer, the effects of this function (except for cursor movement) are temporary and will disappear the next time the display is updated. returns: nothing see also: fillrect, getattr, getstr, getx, gety, gotoscreen, gotoxy, hilite, writeline example: writestr "some text" // writes the string 'some text' at the cursor writestr "some text" 95 // writes the string 'some text' at the cursor with the // color white on magenta writetext string col row buffer ────────────────────────────────────────────────────────────────────── remarks: Enters a string into a buffer at the specified row and column, and moves the cursor to the end of the string. If the cursor is in insert mode, then the text is inserted, otherwise the text is overlaid. If 'buffer' is null or not specified, then the current buffer is assumed. If 'col' and 'row' are not specified, then the string is inserted at the current cursor position. returns: TRUE if successful, otherwise null. see also: delchar, ovltext example: writetext "some text" // writes 'some text' at the cursor in the current // buffer writetext "some text" 2 20 // writes 'some text' at column 2, line 20 in the // current buffer writetext "some text" 1 1 "abc" // writes 'some text' at column 1, line 1 in the // buffer "abc" yncbox message title [Lib][a] ────────────────────────────────────────────────────────────────────── remarks: Displays the specified message in a popup window with 'Yes', 'No', and 'Cancel' buttons. If a title is not specified, 'Message' is assumed. returns: The name of the button pressed (Yes, No, or Cancel), or null if no button was pressed. see also: msgbox, okbox, say, shortbox example: yncbox "Replace the string?" "Replace"