home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Bila Vrana
/
BILA_VRANA.iso
/
028A
/
AUROR.ZIP
/
FUNCTION.DOX
< prev
next >
Wrap
Text File
|
1996-07-17
|
381KB
|
8,809 lines
The AML Function Reference
──────────────────────────
This Function Reference documents all macro language Statements,
Builtin functions, and Library functions for The Aurora Macro Language
(AML). Several editor Extension functions are also documented. For a
macro language tutorial, see the Language Reference. For information
on how to install, configure, and use Aurora, see the 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) 1996 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 three sections:
1. Language Statements
2. Functions (builtin functions and library functions)
3. Events (builtin events)
Topics are sorted alphabetically within each section.
Statements are indicated by the label [Statement], library functions
are indicates by [Lib], and extension functions are indicated by
[Ext]. Builtin functions and events are not labeled. Each library
function is also labeled with the object where it is defined.
┌─────────────────────────────────────────────────────────────────────┐
│ Language Statements │
└─────────────────────────────────────────────────────────────────────┘
break [Statement]
──────────────────────────────────────────────────────────────────────
remarks: The 'break' statement will force an unconditional exit
from 'for', '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 " + (geteventname 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
constant [Statement]
──────────────────────────────────────────────────────────────────────
format: constant identifier = expression [, constant ...]
constant function
:
end / endfunction
remarks: This statment defines symbolic constants or compile-time
functions. 'expression' is evaluated at compile-time
without generating any object code. The lifetime of all
constants is limited to the macro language compilation
process.
The 'constant function' statement defines functions which
are called at compile-time to return constant values.
Commas may be used to define multiple constants in one
constant statement. The 'const' keyword is a synonym for
'constant'.
returns: nothing
see also: #exec, forward, function, include, variable
example: constant five = 5
constant six = 2 * 3
msgbox five * six // displays '30'
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
event [Statement]
──────────────────────────────────────────────────────────────────────
format: event <key or event> (arg1 arg2 ...)
:
end / endevent
The 'end' keyword is not required if this statement is
followed by another 'event', 'key' or 'function'
statement.
remarks: This statement defines an event handling function in the
current object with the event name: <key or event>.
Evaluation and arguments are handled in the same way as
the 'function' statement (see the 'function' statement).
For all events generated by the editor except <char>, an
eventcode is passed as the first argument. The <char>
event handling function is passed the Ascii character
entered as the first argument, and the eventcode as the
second argument.
returns: nothing
see also: arg, forward, function, key
example: key <ctrl c> (keycode)
say "you pressed <ctrl c>, keycode=" + keycode
end
#exec [Statement]
──────────────────────────────────────────────────────────────────────
format: #exec
:
#endexec
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 #exec-#execend group.
Any functions defined within the #exec block are
evaluated at compile time when called. Public object
variables which are assigned values within the #exec
block group are treated as constants when referenced
outside the #exec block.
returns: nothing
see also: constant, forward, function, include, set, variable
for [Statement]
──────────────────────────────────────────────────────────────────────
format: for variable = start to/downto limit [ step/by expr ] do
expressions
end / endfor
The keywords 'step' and 'by' are optional. The keyword
'do' is also optional, but may make the statement easier
to read.
remarks: The 'for' statement evaluates 'expressions' repeatedly,
assigning a new value to 'variable' for each iteration of
the loop.
The value of the 'start' expression is initially assigned
to 'variable' and the loop terminates when the value of
the 'limit' expression has been exceeded. 'limit' is
tested before the first iteration of the loop. Both the
'start' and 'limit' expressions are evaluated only once
at the first iteration of the loop.
If the keyword 'to' is specified, the variable is
incremented for each iteration of the loop, otherwise the
variable is decremented.
If the keyword 'step' is specified, the 'step' expression
defines a fixed value by which the loop variable is
incremented or decremented.
If the keyword 'by' is specified, the value of the 'by'
expression is assigned to the loop variable at each
iteration. No scalar comparsion (less than or greater
than) is performed at each loop iteration when 'by' is
specified.
The 'break' or 'return' statements can be used to force
an exit from the loop.
returns: nothing
see also: break, loop, repeat, return, while
forward [function/object] identifier [Statement]
──────────────────────────────────────────────────────────────────────
remarks: This keyword defines the specified identifier as a
function name or an object name. If the function or
object keyword is not specified, then 'function' is
assumed.
If a function or object is referenced before it is
defined, then the 'forward' keyword must be used to
inform the compiler that the identifier is a function
name or an object name.
returns: nothing
see also: function, key, variable
function [Statement]
──────────────────────────────────────────────────────────────────────
format: function functionname (arg1 arg2 ...)
:
end / endfunction
The 'end' keyword is not required if this statement is
followed by another 'function', 'event', or 'key'
statement.
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, event, forward, key, setfunction
example: function hello (name)
say "Hello " + name + '!'
end
#if [Statement]
──────────────────────────────────────────────────────────────────────
format: #if if_expr
source code
#elseif elseif_expr
source code
:
#else
source code
#end / #endif
The '#elseif' and '#else' clauses are optional.
remarks: This statement is evaluated at compile-time. The
expression 'if_expr' is evaluated. If TRUE, then the
source code in the #if clause is compiled. If not TRUE,
then the expression 'elseif_expr' is evaluated. If
'elseif_expr' is TRUE, then the source code in the
#elseif clause is compiled, otherwise the source code in
the '#else' clause (if present) is compiled. Multiple
'#elseif' clauses may be specified.
returns: nothing
see also: constant, #exec
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
TRUE, then the expressions in the 'if' clause are
evaluated. If not TRUE, then the expression 'elseif_expr'
is evaluated. If 'elseif_expr' 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 '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"
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
as constants or within an '#exec-#execend' group.
This statement will include both macro source (.Aml)
files and compiled macro (.X) files.
returns: nothing
see also: constant, #exec
example: include "d:\\macros.aml"
include drive + path + filename
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', 'event', or 'function'
statement.
remarks: This statement defines an keyboard event handling
function in the current object with the event name: <key
or event>. Evaluation and arguments are handled in the
same way as the 'function' statement (see the 'function'
statement).
For all keyboard events generated by the editor except
<char>, an eventcode is passed as the first argument. The
<char> event handling function is passed the Ascii
character entered as the first argument, and the
eventcode as the second argument.
returns: nothing
see also: arg, event, forward, function, setfunction
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 public object
variables whose value is the keyword color. If the value
is null, then the keyword color defined by 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
loop [Statement]
──────────────────────────────────────────────────────────────────────
format: loop [ expression times ]
expressions
end / endloop
remarks: The 'loop' statement evaluates 'expressions' repeatedly
until a 'break' or 'return' statement is encountered. An
optional 'times' expression may be specified to limit the
number of iterations.
returns: nothing
see also: break, for, 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.
If the object name 'entry' is specified from within an
external macro, then the current object is changed back
to what the current object was when the external macro
was invoked.
Note that the 'object' statement will also terminate
(serve as an 'end' statement for) the 'function',
'event', or 'key' statements.
returns: nothing
see also: createobject, destroyobject, function, getcurrobj,
inheritkeys, loadobject, object?, settype, setobjtype
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, for, loop, return, while
example: variable 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
variable identifier, [variable...] [Statement]
──────────────────────────────────────────────────────────────────────
remarks: This keyword defines the specified identifier as a
variable name, and initializes it to zero.
If a variable is referenced in a statement before the
statement in which it is assigned a value (and is 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.
Commas may be used to define multiple variables in one
variable statement. The keyword 'var' is a synonym for
'variable'.
returns: nothing
see also: forward
example: function count (b)
variable 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, for, 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.
actualcol apparentcolumn row buffer
──────────────────────────────────────────────────────────────────────
remarks: Gets the actual column for an apparent (visible) column
in the specified line. If the row and buffer are not
specified, the current line and buffer are assumed.
The apparent and actual columns may differ if the line
contains tab characters (Ascii 9) which are displayed as
spaces (see 'setbuftabs').
returns: the actual column if successful, otherwise null.
see also: apparentcol, getbuftabs, setbuftabs
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
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 horizontal center of the
window.
returns: nothing
see also: adjustrow
example: adjustcol
// attempts to scroll the window so that the cursor
// is horizontally 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 vertical center of the window.
returns: nothing
see also: adjustcol
example: adjustrow
// attempts to scroll the window so that the cursor
// is vertically 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
apparentcol actualcol row buffer
──────────────────────────────────────────────────────────────────────
remarks: Gets the apparent (visible) column for an actual column
in the specified line. If the row and buffer are not
specified, the current line and buffer are assumed.
The apparent and actual columns may differ if the line
contains tab characters (Ascii 9) which are displayed as
spaces (see 'setbuftabs').
returns: the actual column if successful, otherwise null.
see also: actualcol, getbuftabs, setbuftabs
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 is: " + (arg 1)
end
abc 1 2 3 // displays: '3 args passed, first is: 1'
array size
──────────────────────────────────────────────────────────────────────
remarks: Creates an array of 'size' elements, where each element
in the array is initialized to the null string. 'size'
cannot be greater than 2000.
returns: an array
see also: array?
array? expression
──────────────────────────────────────────────────────────────────────
remarks: Tests if the specified expression is an array.
returns: TRUE if the exression is an array, otherwise null.
see also: array
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, okbox, pickfile, popup, 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 two-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: variable 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 one-line box
prompt. The parameters and return values are identical to
the 'askbox' function.
returns: see askbox.
see also: ask, askbox, askline
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
book? bookmark
──────────────────────────────────────────────────────────────────────
remarks: Tests if the specified bookmark exists.
returns: TRUE if the bookmark exists, otherwise null.
see also: setbook
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
break?
──────────────────────────────────────────────────────────────────────
remarks: Tests if <ctrl break> was pressed.
returns: TRUE if <ctrl break> was pressed, otherwise null.
see also: breakoff
breakoff
──────────────────────────────────────────────────────────────────────
remarks: Clears the break flag that was turned on by pressing the
<ctrl break> key. Calling this function will stop <ctrl
break> from exiting loops and beeps.
returns: nothing
see also: break?
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: 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: bufferflag
bufferflag opt=[-+?cdhmprt] buffer
──────────────────────────────────────────────────────────────────────
remarks: Turns buffer flags on or off, or tests if a buffer flag
is turned on. If 'buffer' is null or not specified, the
current buffer is assumed. The following flags can be
specified:
c - clear all 'dirty' or modified lines (set only)
d - directory buffer (query only)
This flag can be used to test if a buffer was
initially loaded as a directory.
h - hidden buffer
This flag can be used to hide a buffer from the
'getprevbuf' function. This will effectively
prevent temporary or internal buffers from being
displayed on editor buffer lists.
m - buffer 'modified' flag
p - process 'dirty' or modified lines
r - buffer read/only (protected) flag
t - truncated buffer (query only)
This flag can be used to test if the specified
buffer has been truncated when loaded. Truncation
can occur if <ctrl break> was pressed while
loading the file.
- - turn specified flags off
+ - turn specified flags on
? - return true if specified flags are on
If flags are specified without -, +, or ?, then they will
be turned on and any other flags not specified will be
turned off.
returns: TRUE if '?' is specified with flags that are on,
otherwise null
see also: bufchanged?, lineflag
example: bufferflag "-m" // turn off the buffer-modified flag
bufferflag "c" // clear all modified lines
bufferflag "r" // make current buffer read/only
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 bitwise-ORed together:
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 one byte character
strings whose Ascii value is the numeric argument.
returns: The concatenated string of all arguments converted to one
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 two byte binary
character strings.
returns: The concatenated string of all arguments converted to two
byte strings.
see also: bin2int, char, char4
example: char2 6261h // returns "ab"
char4 number1 number2 ...
──────────────────────────────────────────────────────────────────────
remarks: Converts its numeric arguments to four byte binary
character strings.
returns: The concatenated string of all arguments converted to
four byte strings.
see also: bin2int, char, char2
example: char4 64636261h // returns "abcd"
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'. If a file
handle is not specified, then the file handle returned
from the most recent openfile call is assumed.
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: the new cursor column 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.
If the color -1 is specified, the default window mark
color is used. If the color -2 is specified, the cursor
is hidden.
returns: TRUE if successful, otherwise null.
see also: colormark, 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.
If the color -1 is specified, the default window mark
color is used. If the color -2 is specified, the mark is
hidden.
returns: TRUE if successful, otherwise null.
see also: colorcursor, 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 object code in the file 'destfile'. 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
1314 - unexpected keyword
1315 - invalid redefinition
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
1504 - statement must be at top level
1507 - can't redefine builtin function
1508 - duplicated function argument
1701 - too many variables
1703 - function or expression too large
1704, 1705, 1707, 1708 - internal stack overflow
1706 - out of symbol space
any other code - fatal compilation error
see also: eval, geterror, runmacro, seterror
example: compilemacro "c:\\aurora\\macro\\utility.aml"
"c:\\aurora\\macro\\utility.x"
concat string1 string2 ...
──────────────────────────────────────────────────────────────────────
remarks: Concatenates all of its arguments. All arguments may be
numeric. The concatenation operator (+) may also be used
to concatenate strings, but at least one operand must be
non-numeric.
returns: the concatenated string of all the arguments.
see also: copystr
example: concat "Red" "Green" "Blue" // returns "RedGreenBlue"
concat 1 2 3 // returns "123"
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
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
createcursor cursor buffer
──────────────────────────────────────────────────────────────────────
remarks: This function creates a new cursor. If the specified
cursor already exists, this function will fail. If
'cursor' is null or not specified, a unique cursorid will
be assigned. If 'buffer' is null or not specified, the
current buffer is assumed.
The new cursor will become the current cursor for the
buffer.
returns: Non-zero if successful, otherwise zero.
see also: cursor?, destroycursor, setcursor
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: directory?, file?, 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
createobject object parent1 parent2 ...
──────────────────────────────────────────────────────────────────────
remarks: Creates a new object. If 'object' is not specified, a
unique object name will be assigned. If the inheritance
path 'parent1 parent2 ...' is specified, then the object
will inherit public functions and object variables from
the objects 'parent1', 'parent2', etc.
This function can be used to create objects dynamically.
Unlike the 'object' statement, this function does not
modify the current object.
returns: the new objectid if successful, otherwise null.
see also: destroyobject, loadobject, object, object?, setobjtype
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: createcursor, cursor?, 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, halt, system
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: Destroys the specified object. If 'object' is not
specified, the current object is assumed.
If possible, the object is destroyed immediately,
otherwise the object will be destroyed when it is no
longer referenced.
returns: TRUE if the object is destroyed immediately, otherwise
null.
see also: createobject, loadobject, object, object?, resident,
runmacro
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?
destroyvar variable object
──────────────────────────────────────────────────────────────────────
remarks: Destroys the public object variable defined by 'variable'
in the specified object. If 'object' is not specified,
then the current object is assumed.
returns: nothing
see also: function?, lookup, set, variable?
example: destroyvar "TempVar"
destroyvar "Temp" + "Var" "edit"
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
directory? directory path
──────────────────────────────────────────────────────────────────────
remarks: Tests for the existence of a directory in the specified
path. This function is identical to the locatefile
function when option 'd' is specified (see 'locatefile').
returns: The fully qualified directory if found, otherwise null.
see also: file?, locatefile
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: the new cursor line number 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, 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?
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
fbreak [Lib][fmgr]
──────────────────────────────────────────────────────────────────────
remarks: Breaks out of the current 'fcommand' call.
returns: nothing
see also: fcommand
fcommand function arg1 arg2 ... [Lib][fmgr]
──────────────────────────────────────────────────────────────────────
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: fbreak, fmark, fmark?
example: fcommand "setfileattr" attribute
// calls the function 'setfileattr' (passing the value
// of the variable 'attribute') in the current event
// object for all marked files in the current
// file manager window
fgetfile [Lib][fmgr]
──────────────────────────────────────────────────────────────────────
remarks: Gets the fully qualified file or directory name at the
current line in the current file manager window.
returns: a fully qualified file or directory name.
fgetopt [Lib][fmgr]
──────────────────────────────────────────────────────────────────────
remarks: Retrieves the file manager options of the current file
manager window.
returns: the current file manager option settings
see also: fgetsort
fgetsort [Lib][fmgr]
──────────────────────────────────────────────────────────────────────
remarks: Retrieves the sort order of the current file manager
window as a one character string (n/s/d/e/o).
returns: the current file manager sort order
see also: fgetopt, fsort
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
file? file path
──────────────────────────────────────────────────────────────────────
remarks: Tests for the existence of a file in the specified path.
This function is identical to the locatefile function
when option 'f' is specified (see 'locatefile').
returns: The fully qualified file if found, otherwise null.
see also: directory?, locatefile
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: getfileattr, setfileattr
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: nextfile, prevfile
filepos position opt=[ace] handle
──────────────────────────────────────────────────────────────────────
remarks: Changes the current position in the open file specified
by 'handle'. If a file handle is not specified, then the
file handle returned from the most recent openfile call
is assumed.
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 - the position is an absolute position in the file (1
is the first position)
c - the position is an offset from the current position
e - the 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 'string' is
not specified, a single blank is assumed. 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 Regexp.dox).
* - 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
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, the marked state of the
current file or directory is toggled.
returns: nothing
see also: fbreak, fcommand, 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: fbreak, fcommand, 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
foldoptions opt=[lr] fillchar window
──────────────────────────────────────────────────────────────────────
remarks: Sets options for displaying closed folds. If 'window' is
not specified, the current window is assumed. The
following options may be specified:
l - attempt to display the fold size left-justified at
the end of the line.
r - attempt to display the fold size right-justified at
the right edge of the window
If no options are specifed, then the fold size is not
displayed.
If 'fillchar' character is specified, then fold lines are
padded with the specified fill character.
returns: nothing
see also: getfold
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. If no components are specified, all possible
components are 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
fsort opt=[ednos] [Lib][fmgr]
──────────────────────────────────────────────────────────────────────
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: fgetopt, fgetsort, pickfile
example: fsort 'n' // sort by file name
fsort 's' // sort by size (descending)
fstatus [Lib][fmgr]
──────────────────────────────────────────────────────────────────────
remarks: Updates the status line of the current file manager
window.
returns: nothing
function? function object
──────────────────────────────────────────────────────────────────────
remarks: Tests for the existence of a public function defined by
'function' in the object defined by 'object'. If 'object'
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: destroyvar, lookup, set, variable?
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
fupdate file fmgroptions [Lib][fmgr]
──────────────────────────────────────────────────────────────────────
remarks: Updates the current file manager window without reloading
the directory (as the reopen command does). If file
manager options are not specified, the file manager
options associated with the current window are used.
If 'file' is specified, the current line is replaced with
the specified file. If no file is specified, then the
entire file manager window is updated.
returns: nothing
see also: fgetopt, 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 line length associated with a binary buffer. If the
buffer is not binary, then zero is returned.
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
getbuftabs buffer
──────────────────────────────────────────────────────────────────────
remarks: Gets the tab width used for displaying real tabs. If
'buffer' is not specified, the current buffer is assumed.
returns: the tab width
see also: setbuftabs
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: getrealtext, 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 - clip the height, width, or coordinate with the
visible portion of the display.
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
getcurrfile
──────────────────────────────────────────────────────────────────────
remarks: Gets the name of the macro language file being currently
compiled or executed.
returns: If called from within the constant or #exec statements,
the name of the file being currently compiled is
returned, otherwise the name of the file being currently
executed is returned.
see also: constant, #exec, geterror
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 format
──────────────────────────────────────────────────────────────────────
remarks: Gets the current date in the specified format. If
'format' is not specified, the format previously passed
to the 'international' function is assumed.
See the 'international' function for a list of valid date
formats.
returns: The current date.
see also: getfileinfo, getrawtime, gettime, international
getdialog ref1 ref2 ... [Lib][a]
──────────────────────────────────────────────────────────────────────
remarks: Displays the current dialog box as a modal dialog box
(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
variable field1
variable 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 variable
──────────────────────────────────────────────────────────────────────
remarks: Gets the value of the specified environment variable.
'variable' 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 'loadobject'
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'
and 'seterror' functions for additional
information).
If no options are specified, 'c' is assumed.
returns: Information based on the options specified.
see also: compilemacro, eval, runmacro, seterror
geteventcode eventname
──────────────────────────────────────────────────────────────────────
remarks: Gets the event code for the specified event name.
returns: an event code
see also: geteventname
example: say "The keycode for <ctrl b> is: " +
(geteventcode "<ctrl b>")
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 the object where events are dispatched by the editor.
returns: The current event objectid.
see also: seteventobj
getexe
──────────────────────────────────────────────────────────────────────
remarks: Gets the name of the currently executing editor .Exe
file, without the path or file extension.
returns: The editor .Exe name.
see also: getversion getos
getfileinfo filename opt=[adtrs]
──────────────────────────────────────────────────────────────────────
remarks: Retrieves information about the specified file or
directory. Any one of the following options may be
specified:
a - return the file attributes as a 4-character string
d - return the file date in international format
t - return the file time in international format
r - return the file date and time in raw format
s - return the file size in bytes
If option 'r' is specified, the raw time will contain '0'
for the day-of-the-week and hundredths of a second (see
'getrawtime').
returns: Information based on the options specified
see also: getdate, getrawtime, gettime
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, foldoptions, 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][a]
──────────────────────────────────────────────────────────────────────
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: geteventcode, geteventname
example: say "you pressed keycode: " + getkey
geteventname eventcode
──────────────────────────────────────────────────────────────────────
remarks: Gets the event name for the specified event code.
returns: an event name
see also: geteventcode
example: say "You pressed the key: " + (geteventname (getkey))
getlinebeg row buffer
──────────────────────────────────────────────────────────────────────
remarks: Gets the column of the first non-blank, non-tab 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, non-tab character,
otherwise null.
see also: getlinelen, getlinesize
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, non-tab character in the line is returned. For
binary buffers, the position of the last character in the
line is returned.
see also: getbinarylen, getlinebeg, getlinesize
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.
getlinesize row buffer
──────────────────────────────────────────────────────────────────────
remarks: Gets the length of a line. This function is nearly
identical to the getlinelen function, except that the
returned line length includes trailing blanks and tabs.
returns: the actual line length
see also: getlinebeg, getlinelen
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' 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=[vml]
──────────────────────────────────────────────────────────────────────
remarks: Gets information about the operating system. One of the
following options may be specified:
v - return the major Dos version number
m - return the minor Dos version number
l - return TRUE if long filenames are supported
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: Color.aml, 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, getfileinfo, gettime
getrealtext col length row buffer
──────────────────────────────────────────────────────────────────────
remarks: Retrieves text within a line. This function is nearly
identical to the gettext function, except that it returns
the text at the original physical memory location in the
buffer (unlike the gettext function, which returns a
copy).
The text returned from this function must be used
immediately, since the editor automatically changes
memory contents as needed.
This function is useful when the actual physical address
of buffer text is needed for machine language functions,
or for optimizing macros where the text will be used
immediately.
returns: a line or a portion of a line
see also: getchar, gettext
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
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
getsyntax window
──────────────────────────────────────────────────────────────────────
remarks: Retrieves the syntax highlighting object associated with
a window. If 'window' is not specified, the current
window is assumed.
returns: a syntax highlighting object
see also: setsyntax
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 one 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, getrealtext
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 one 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 format
──────────────────────────────────────────────────────────────────────
remarks: Gets the current time in the specified format. If
'format' is not specified, the format previously passed
to the 'international' function is assumed. If the format
is -1, the international format is assumed, but with
seconds added (if not already present).
See the 'international' function for a list of valid time
formats.
returns: The current time.
see also: getdate, getfileinfo, getrawtime, international
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 window
──────────────────────────────────────────────────────────────────────
remarks: Gets the title bar controls for a window. If 'window' is
not specified, the current window is assumed.
returns: a string containing all the title bar controls
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][a]
──────────────────────────────────────────────────────────────────────
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][a]
──────────────────────────────────────────────────────────────────────
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][a]
──────────────────────────────────────────────────────────────────────
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: the new cursor line number 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
one and row one 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, machine, system
hex2bin hexstring
──────────────────────────────────────────────────────────────────────
remarks: Converts a hexadecimal string, composed of only the
characters 0-9 and A-F or a-f, to a binary string.
returns: a binary string.
see also: bin2hex
example: hex2bin "61" // returns 'a'
hex2bin "616263" // returns 'abc'
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
'height' is one, 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
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: object, objtype?, settype, setobjtype
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 one.
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=[bxdfhkvqscu] 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 '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 one.
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 dateopt datesep timeopt timesep thousandssep
──────────────────────────────────────────────────────────────────────
remarks: Defines international system settings. The following
settings can be specified:
dateopt - The date format to use [0-2]:
0 = mm dd yy
1 = dd mm yy
2 = yy mm dd
datesep - The character used to separate days,
months, and years
timeopt - The time format to use [0-3]:
0 = 12hr
1 = 24hr
2 = 12hr with seconds
3 = 24hr with seconds
timesep - The character used to separate hours,
minutes, and seconds
thousandssep - 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, one is
assumed. If 'buffer' is null or not specified, the
current buffer is assumed.
returns: the new cursor column 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, or tests if a line flag is
turned 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 modified or 'dirty' flag
- - turn specified flags off
+ - turn specified flags on
? - return true if specified flags are on
If flags are specified without -, +, or ?, then they will
be turned on and any other flags not specified will be
turned off.
returns: TRUE if '?' is specified with flags that are on,
otherwise null
see also: bufferflag
example: lineflag "-m"
// turns off the modified flag for the current buffer
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=[bxdfhkvqscu] trunc comment
──────────────────────────────────────────────────────────────────────
remarks: Loads a 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 when loading
files:
b - load the file in binary mode. The third argument
specifies the binary line length.
x - disable conversion of fold comments to folds
The following options may be specified when loading
directories:
d - include subdirectories
f - include normal files
h - include hidden/system files
k - shows file sizes in 1k increments
q - qualify names with the directory name. This option
can only be specified with option 'v'.
s - load the directory in 'short' format (name only,
starting at column one). This option can only be
specified with option 'v'.
v - load the directory in variable format
c - show names capitalized
l - show names in lowercase
u - show names in uppercase
If options 'c', 'l', or 'u' are not specified, names are
shown 'as-is' from the operating system.
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 one or two 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
loadobject file object arg3 arg4 ...
──────────────────────────────────────────────────────────────────────
remarks: Loads an object from a file. This function is similar to
the 'runmacro' function, with the following differences:
- the loaded object (macro) automatically remains
resident - 'resident ON' is not required.
- the loaded object does not initially inherit anything
from any other objects.
- the current event object is not modified
- the objectid is returned
returns: the objectid of the loaded object
see also: createobject, destroyobject, object, resident, runmacro
locase string
──────────────────────────────────────────────────────────────────────
remarks: Converts a string to lowercase.
returns: the string in lowercase.
see also: upcase flipcase
example: locase "PEACHES" // returns "peaches"
locatefile filespec path opt=[df]
──────────────────────────────────────────────────────────────────────
remarks: Searches a path for a filename or directory. 'path' can
be a list of paths separated by semicolons (;) (as
specified in the Dos 'PATH' environment string).
Any of the following options may be specified:
d - search for a directory
f - search for a file
If no options are specified, then 'df' is assumed.
returns: the fully qualified filename or directory if found,
otherwise null.
see also: createdir, directory?, file?, 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 "macro" "d:\\aurora" 'd'
// returns d:\macro\aurora, if macro is a directory
// in d:\aurora
lookup variable object
──────────────────────────────────────────────────────────────────────
remarks: Gets the value of a public object variable defined by
'variable' in the object defined by 'object'. If 'object'
is not specified, the current object is assumed.
returns: the value of the object variable if it exists, otherwise
null.
see also: function?, set, variable?
example: lookup "VidCols"
lookup "Vid" + "Cols" "prf"
lookup myvar
// returns the value of an object variable whose
// name is the value of 'myvar'
machine code arg1 arg2 ..
──────────────────────────────────────────────────────────────────────
remarks: Executes machine-level code. This function executes the
string specified by 'code' directly as 80x86 machine
language code, passing the arguments arg1, arg2 on the
stack. The machine code must not contain any external
fixups or relocation items - all references must be
relative the code itself. The stack size should not be
assumed to be larger than 300 bytes.
Parameters are passed on the stack from right to left,
using the 'C' calling convention. Numbers are passed as
long integers (4 bytes), with the high order word pushed
first, followed by the low order word. Strings are passed
as segment:offset far pointers (4 bytes) to the string
contents, with the segment pushed first, followed by the
offset.
On entry to the machine code, the register ax contains
the number of parameters passed, and register bx contains
a 'type mask', where each bit indicates the argument type
(numeric=0, string=1). For example, if one argument is
passed and the first bit of bx is On, then the argument
is a string (far pointer), otherwise it is a number (long
integer).
The machine code is executed with a far call, and
therefore must return with a far return. Do not pop any
arguments off the stack - this will be done by the
machine function. Only register bp must be preserved, if
used).
returns: a long integer, with the high word equal to register dx
and the low word equal to register ax at the time the
machine code returns.
example: see macro\machine.aml and macro\machine.asm
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
──────────────────────────────────────────────────────────────────────
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 (in Dos) after
loading, increasing 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: the new cursor line number 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 event is sent by the editor library (Lib.x) when
sounding the PC speaker to call attention to a message.
This event can be used to customize the alarm sound.
'onalarm' is sent directly to 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 event is sent by the editor library (Lib.x) when a
file or file manager window is closed and removed from
memory.
'onclose' is sent directly to 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
onclosedlg button windowid [Lib][a]
──────────────────────────────────────────────────────────────────────
remarks: This event is sent by the editor library (Lib.x) to the
dialog box notification object when a dialog box is
closed. The button used to close the dialog box is passed
as the first argument, and the windowid of the dialog box
is passed as the second argument.
returns: none required
see also: dialog, ondialog
oncomment filename comment1 comment2 [Lib][a]
──────────────────────────────────────────────────────────────────────
remarks: This event is sent by the editor library (Lib.x) and
extension code (Ext.aml) to retrieve the language
comments associated with a filename.
'oncomment' is sent directly to 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.
ondesk [Lib][a]
──────────────────────────────────────────────────────────────────────
remarks: This event is sent by the editor library (Lib.x) after
the desktop is restored via the restoredesk function.
returns: none required
ondialog keycode [Lib][a]
──────────────────────────────────────────────────────────────────────
remarks: This event is sent by the editor library (Lib.x) to the
dialog box notification object when an unrecognized
dialog box key is entered from the dialog box. The
keycode of the key as passed as the first argument.
returns: none required
see also: onclosedlg
onentry dosarg1 dosarg2 ... [Lib]
──────────────────────────────────────────────────────────────────────
remarks: This event is queued by the editor library (Lib.x) after
the default macro file A.x is loaded and executed.
'onentry' 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 sent 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 event is sent by the editor library (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 sent directly to 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 event is sent by the editor library (Lib.x) after
the focus is switched to another file or file manager
window. 'onfocus' is sent directly to 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 event is sent 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 sent directly to 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 event is sent 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 sent directly to the current event object
and is passed the hotkey character.
returns: none required
see also: onfound
onkillfocus [Lib]
──────────────────────────────────────────────────────────────────────
remarks: This event is sent by the editor library (Lib.x) when a
window is about to lose the focus. 'onkillfocus' is sent
directly to the current event object and is not passed
any parameters.
returns: none required
see also: onfocus
onname filespec options [Lib][a]
──────────────────────────────────────────────────────────────────────
remarks: This event is sent whenever an edit window or file
manager window title bar is set, or whenever a
filename/filespec needs to be formatted using the
NameStyle configuration setting. The onname event
handling function returns the formatted filename.
The option 't' is passed if the filename is to be
displayed on a window title bar. This allows the onname
event handling function do optional 'name compression'
for long names (i.e. c:\dir\...\file.ext).
This event is sent from many locations in Lib.x, Ext.aml,
and external macros. The event handling functon for
onname is located in Ext.aml. Note that onname is not
called for each file in a file manager listing when the
listing is initially opened.
returns: the formatted name
example: see the configuration file Ext.aml
onopen options [Lib]
──────────────────────────────────────────────────────────────────────
remarks: This event is sent by the editor library (Lib.x) whenever
a new file or file manager window is opened. This event
is only sent once when the file is initially opened, or
when the file manager window is initially created (not
when switching to other files or windows).
'onopen' 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, setting tabs, etc.
'onopen' is sent directly to 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
onsave filename [Ext][edit]
──────────────────────────────────────────────────────────────────────
remarks: This event is sent by the editor extension code (Ext.aml)
immediately before a file is saved. 'onsave' is sent
directly to the current event object. The name of the
file being saved is passed to 'onsave'.
returns: none required
see also: onclose, onopen
onsyntax filename [Lib][a]
──────────────────────────────────────────────────────────────────────
remarks: This event is sent by the editor library (Lib.x) and
extension code (Ext.aml) to retrieve the syntax
highlighting object to be associated with a filename.
'onsyntax' is sent directly to 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 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 variable 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
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"
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 handy 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.
The overriding object is 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 address must be a segment:offset address.
The maximum length is 16000.
returns: a copy of the specified Dos memory area.
see also: poke
example: peek 0 100
// returns the first 100 bytes of memory
peek 0xb8000000 40
// returns 40 bytes starting at B800:0000
pickfile filespec title title2 bufname sortopt fmgropt [Lib][a]
──────────────────────────────────────────────────────────────────────
remarks: Displays a file selection menu based on 'filespec'. The
following additional parameters can be specified:
title - an optional main menu title
title2 - an optional right-justified menu title
bufname - an optional buffer name to be used for the
menu. If a buffer name is specified, the window
size and position will be saved and associated
with the buffer name.
sortopt - 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 FmgrSort
variable in Config.aml is assumed.
fmgropt - one of the following options can be specified:
v - variable length format
d - show subdirectories
f - show files
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 FmgrOpt
variable in Config.aml is assumed.
returns: The selected file or directory, or null if nothing was
selected.
see also: popup
example: pickfile "c:\\*.*" "Select a file"
// displays a file selection menu for the C drive
pickfile "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
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 segment:offset address. Obviously, this
function should be used with care.
returns: nothing
see also: peek
example: poke 0xb8000000 "T E S T "
// copy "T E S T " to B800:0000
popcursor opt=[ad] buffer
──────────────────────────────────────────────────────────────────────
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 buffer title width height object [Lib][a]
──────────────────────────────────────────────────────────────────────
remarks: Displays a buffer in a popup menu. If 'buffer' is not
specified, the current buffer is assumed. 'buffer' can
also be the name of a menu defined with the 'menu'
statement.
The following parameters can also be specified:
title - the popup window title.
width - 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.
height - the menu height. If none is specified, the
lesser of the screen rows or the menu rows is
assumed.
object - the event handling object to be associated with
the popup menu (note that this object must be
derived from the pre-defined 'popup' object).
If specified, the window event handling object
for the popup window will be set to this object,
allowing for customized keyboard/event behavior.
The events 'onopen' and 'onclose' will be sent
to the object when the popup menu is opened and
closed.
If the 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, the
menu item description line is returned.
If no item was selected from the menu, the null string is
returned.
see also: getmenu, menu, pickfile
example: popup "files" "Select a File"
// displays the menu buffer 'files' with the title
// 'Select a File'
popup "files" '' 25 10
// displays the buffer 'files' with no title,
// 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 Regexp.dox)
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 init
──────────────────────────────────────────────────────────────────────
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 init
──────────────────────────────────────────────────────────────────────
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.
'device' is the printer device to use. Filenames or
device names such as prn, lpt1, lpt2, etc. can be
specified. If the device is null or not specified, then
prn 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).
'init' specifies a device-specific string to send to the
the printer before printing. Typically, this string will
contain control codes for setting the current font,
portrait/landscape orientation, etc.
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 public 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: geteventcode, getkey, sendkey
example: keycode = getkey // gets a keycode...
queuekey keycode // and queues it for execution
queueobject object function arg1 arg2 ...
──────────────────────────────────────────────────────────────────────
remarks: Queues a public 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 length handle
──────────────────────────────────────────────────────────────────────
remarks: Reads 'length' characters from the current position in
the open file specified by 'handle'. If 'length' is not
specified, a length of 16000 is assumed. If a file handle
is not specified, then the file handle returned from the
most recent openfile call is assumed.
The '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 'length' operator on
the returned string.
see also: closefile, filepos, openfile, writefile
example: // reads the first 100 bytes of file.txt into 'str'
if openfile "c:\\file.txt" <> -1 then
str = readfile 100
closefile
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, fupdate, 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.
resident [0/1]
──────────────────────────────────────────────────────────────────────
remarks: Forces the currently executing macro (invoked by the
runmacro function) to remain resident or to be discarded
after the macro is finished executing.
If 1 is specified, the macro (the object created by
runmacro) will remain resident. Any functions or object
variables defined in the macro will also remain resident.
The macro can be removed later by explicitly destroying
the runmacro object with the 'destroyobject' function.
If 0 specified, the macro will be discarded (the object
created by runmacro will be destroyed).
returns: nothing
see also: destroyobject, loadobject, runmacro
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 opt=[c] [Lib][a]
──────────────────────────────────────────────────────────────────────
remarks: Displays the current desktop. The current desktop is set
by the 'opendesk', 'currdesk', and 'openhistory'
functions. The 'begdesk' and 'enddesk' functions also
change the current desktop.
If option 'c' is specified, the existing desktop is
cleared before displaying the new desktop.
returns: nothing
see also: begdesk, currdesk, enddesk, opendesk, openhistory,
savedesk
example: opendesk "c:\\desktop.dst"
// loads the previously saved desktop in d:\desktop.dst
// 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,
then one is assumed. If 'buffer' is null or not
specified, the current buffer is assumed.
returns: the new cursor column 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: the new cursor line number 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 object arg3 arg4 ...
──────────────────────────────────────────────────────────────────────
remarks: Runs the executable macro contained in the specified
filename. The macro is loaded into a new object descended
from the current event object, and executed. Arguments
passed to the macro are the same arguments passed to the
loadobject function.
If 'object' is not specified, a unique object name is
generated.
Normally, when the macro is finished executing, the new
object created by runmacro is destroyed and the macro is
discarded. However, if the 'resident ON' statement is
issued from within the macro, the macro will remain
resident until the object is explicitly destroyed with
the 'destroyobject' function.
returns: The return value from executing the macro.
see also: compilemacro, destroyobject, eval, loadobject, resident
example: runmacro "c:\\aurora\\macro\\mymacro.x"
save filename [Ext][a]
──────────────────────────────────────────────────────────────────────
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 'filename'
is not specified, the buffer name is assumed. If 'buffer'
is null or not specified, then the current buffer is
assumed.
The following options may be specified:
a - append to end of the file when saving
b - save the file in binary mode, with no line
delimiters
e - entab the buffer while saving. The tabwidth is
specified after the 'e' option - for example: 'e8'.
t - trim trailing blanks and tabs from each line
x - disable conversion of folds to fold comments
z - append ctrl-z (Ascii 26) to the end of the file
when saving
'delimiter' specifies a one or two 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 used 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 one 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.dst"
// save the current desktop to c:\desktop.dst
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
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"
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 Regexp.dox)
returns: The absolute position in the file where the search string
was found (starting with one), or zero if not found. If
the scan was interrupted by <ctrl break>, then zero 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
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
variables SearchOpt and ReplaceOpt in Config.aml 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, 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 function arg1 arg2 ...
──────────────────────────────────────────────────────────────────────
remarks: Calls a public function in the current event object whose
name is the value of 'function', 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, in the current event object.
returns: nothing
see also: geteventcode, getkey, queuekey, send, sendobject
example: keycode = getkey // gets a keycode...
sendkey keycode // and executes it immediately
sendobject object function arg1 arg2 ...
──────────────────────────────────────────────────────────────────────
remarks: Calls a public function in the specified object whose
name is the value of 'function', 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" + '>'
set variable value object
──────────────────────────────────────────────────────────────────────
remarks: Assigns a value to a public object variable in the
specified object. If an object is not specified, the
current object is assumed. If the variable does not
already exist, then it is created.
returns: nothing
see also: destroyvar, lookup, setfunction, variable?
example: set "Two" 2
set "number" 1 + 2 + x - 4
set "TabWidth" 4 "edit"
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 bchr3
window
──────────────────────────────────────────────────────────────────────
remarks: Changes the border style of a window. If 'window' is not
specified, the current window is assumed. 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
bchr3 - hex view divider 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 one:
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
setbuftabs tabwidth buffer
──────────────────────────────────────────────────────────────────────
remarks: Sets the tab width used for displaying real tabs. If
'buffer' is not specified, the current buffer is assumed.
If the tabwidth is zero, then real tabs are displayed
as-is (Ascii 9). Note that this function will also clear
the undo/redo stack.
returns: nothing
see also: getbuftabs, undo, redo
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
seterror errorcode errorstring
──────────────────────────────────────────────────────────────────────
remarks: Generates an AML compiler error with the specified error
code when called from within a constant function or
#exec-#endexec block at compile-time. Any error code can
be specified, including new user-defined errorcodes. Both
the errorcode and errorstring (if specified) can be
retrieved later via the 'geterror' function.
This function can be useful in checking for any number of
user-defined error conditions at compile time, such as
invalid arguments passed to a constant function, required
files or resources not found, etc.
returns: nothing
see also: geterror
seteventobj object
──────────────────────────────────────────────────────────────────────
remarks: Changes the current event object to the specified object.
The current event object is the object 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
setfileattr 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: setfileattr "c:\\file.txt" 'r'
// makes c:\\file.txt a read-only file
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
setfunction function expression object
──────────────────────────────────────────────────────────────────────
remarks: Changes the definition of a public function in the
specified object to the macro source code in the string
'expression'. If an object is not specified, the current
object is assumed. If the function does not already
exist, then it is created.
This statement can be used to change the definition of a
function at run-time.
returns: nothing
see also: destroyvar, function?, lookup, set
example: setfunction "<ctrl d>" "beep 400 400" "edit"
// assigns the macro code 'beep 400 400' to <ctrl d>
// in the object 'edit'
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
setobjtype object parentobj1 parentobj2...
──────────────────────────────────────────────────────────────────────
remarks: Sets the inheritance path of the specified object to
parentobj1, parentobj2, etc. After this function is
called, the specified object will inherit functions and
object variables from parentobj1, parentobj2, etc.
returns: nothing
see also: inheritkeys, object, objtype?, settype
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: getsyntax, keyword
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] object [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
h - Hex view
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
If setting 'x' is turned on, 'object' defines the syntax
highlighting object to use. If 'object' is not specified,
the 'onsyntax' event is sent to obtain the syntax
highlighting object.
After the 'settings' argument, 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
An object may be specified
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 the 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, and should be used when specifying 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
settype parentobj parentobj2 ...
──────────────────────────────────────────────────────────────────────
remarks: Sets the inheritance path of the current object to
parentobj1, parentobj2, etc. After this function is
called, the current object will inherit functions and
object variables from parentobj1, parentobj2, etc.
returns: nothing
see also: inheritkeys, object, objtype?, setobjtype
example: settype "win"
// the current object now inherits functions and
// object variables from the object 'win'
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: getwinobj, seteventobj
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 bitwise-ORed together:
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
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 based at 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 column
──────────────────────────────────────────────────────────────────────
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 line marks, the text between 'column' and the end of
the line is used as the sort key. If 'column' is not
specified, one is assumed.
For all other marks, the entire line is used as the sort
key. In any 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 one 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
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 Regexp.dox)
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=[bcdfin] symbols1 symbols2 stringchars stringlit
numeric eolcom1 startcol1 eolcom2 startcol2 opencom1
closecom1 opencom2 closecom2 backscan keywordcolor
symbol1color symbol2color 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 - enable highlighting for the cursor line
d - enable highlighting for closed fold lines
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:
symbols1 - defines a set of 1-character symbols to
be highlighted. A maximum of 40 symbols
can be specified.
symbols2 - defines an alternate set of 1-character
symbols to be highlighted with a different
color. A maximum of 40 symbols can be
specified for symbols1 and symbols2
combined.
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
(500 line max)
The following syntax highlighting colors attributes may
also be specified:
keywordcolor stringcolor eolcom2color
symbol1color numericcolor comment1color
symbol2color eolcom1color 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
system 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 the 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
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).
If 'tabwidth' is negative, then spaces are converted into
tab characters (entab). Spaces occurring on a line after
a single quote, double quote, or tab character 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=[hvlr] limit [Lib][win]
──────────────────────────────────────────────────────────────────────
remarks: Tiles all non-minimized windows on the screen, and sets
the maximize/restore title bar controls correctly for
each window. See the 'tilewindow' function for a
description of the options and the 'limit' argument.
returns: nothing
see also: cascade, splitwin, tilewindow
tilewindow opt=[hvlb] limit splitnum 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:
h - favors horizontal splits
v - favors vertical splits
l - tile only the specified window and any other
windows which display the same buffer
r - reverses the tiling order by starting with the
nth window on the screen, where n='limit'
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: copyfile, setfileattr
trackmouse [Lib][a]
──────────────────────────────────────────────────────────────────────
remarks: Moves the cursor to the mouse pointer in the current
buffer.
returns: nothing
see also: getmousex, getmousey, mousepos, virtocol, virtorow
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
up rows buffer
──────────────────────────────────────────────────────────────────────
remarks: Moves the cursor upward. 'rows' specifies the number of
lines to move. If 'rows' is not specified, then one is
assumed. If 'buffer' is null or not specified, the
current buffer is assumed.
returns: the new cursor line number 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: oldmark = usemark 'T'
// set the default markid to 'T'
:
usemark oldmark
// always restore the default markid
variable? variable object
──────────────────────────────────────────────────────────────────────
remarks: Tests if the specified public variable exists in the
object 'objectname'. If 'objectname' is not specified,
the current object is assumed. Parent objects will also
be checked.
returns: TRUE if the variable exists, otherwise null.
see also: function?, lookup
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 functionn [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 function [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 function is also called
when an edit field is updated from history.
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, or tests if a window flag
is turned on. If 'window' is null or not specified, the
current window is assumed. The following flags can be
specified:
h - display the hex-view. The following additional
flags can be specified:
1 - display the hardware cursor on the first hex
character
2 - display the hardware cursor on the second hex
character
If flags 1 and 2 are off, the hardware cursor is
displayed the in normal text portion of the window.
p - send the <paint> event 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 - send the <status> event in the window event object
before the status line is updated. The return value
of <status> will become the actual status line,
allowing the status line to be customized.
z - resizeable window
- - turn specified flags off
+ - turn specified flags on
? - return true if specified flags are on
If flags are specified without -, +, or ?, then they will
be turned on and any other flags not specified will be
turned off.
returns: TRUE if '?' is specified with flags that are on,
otherwise null
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, but
also provides support for the following window settings:
- Hex View
- Live Word Wrap
- Match Character
- Standard Word Wrap
- Translate
returns: nothing
see also: instext, ovltext, writetext
example: write "some text"
writefile string opt=[k] handle
──────────────────────────────────────────────────────────────────────
remarks: Writes the specified string at the current position in
the open file specified by 'handle'. If a file handle is
not specified, then the file handle returned from the
most recent openfile call is assumed.
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, write
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"
┌─────────────────────────────────────────────────────────────────────┐
│ Builtin Events │
└─────────────────────────────────────────────────────────────────────┘
<compiling> filename linenumber
──────────────────────────────────────────────────────────────────────
remarks: This event is sent by the editor (A.exe) while a macro
language source file is being compiled, and can be used
to show progress during macro compilation.
<compiling> is sent directly to 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, <compiling> is sent again with no arguments.
returns: none required
see also: <loading>, <printing>, <saving>
example: see the configuration file Ext.aml
<destroy>
──────────────────────────────────────────────────────────────────────
remarks: This event is sent by the editor (A.exe) to an object
immediately before it is destroyed. It can be used to
perform cleanup tasks in external macros, such as closing
windows, setting flags, destroying buffers, timers, etc.
returns: None required
<display>
──────────────────────────────────────────────────────────────────────
remarks: This event is sent by the editor (A.exe) to the current
event object immediately after the display is updated.
see also: <paint>, <status>
<loading> linenumber
──────────────────────────────────────────────────────────────────────
remarks: This event is sent by the editor (A.exe) as a file is
being loaded, and can be used to show progress when
loading a file.
<loading> is sent directly to the current event object
and is passed the line number of the last line loaded.
After the file is loaded, <loading> is sent again with no
arguments.
returns: none required
see also: <compiling>, <printing>, <saving>
example: see the configuration file Ext.aml
<paint>
──────────────────────────────────────────────────────────────────────
remarks: This event is sent 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).
<paint> can be used to perform custom drawing or
highlighting of the window client area.
<paint> 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: <status>, windowflag
<printing> linenumber
──────────────────────────────────────────────────────────────────────
remarks: This event is called by the editor (A.exe) as a file is
being printed, and can be used to show progress when
printing a file.
<printing> is sent directly to the current event object
and is passed the line number of the last line printed.
After the file is printed, <printing> is sent again with
no arguments.
returns: none required
see also: <compiling>, <loading>, <saving>
example: see the configuration file Ext.aml
<saving> linenumber
──────────────────────────────────────────────────────────────────────
remarks: This event is sent by the editor (A.exe) as a file is
being saved, and can be used to show progress when saving
a file.
<saving> is sent directly to the current event object and
is passed the line number of the last line saved. After
the file is saved, <saving> is sent again with no
arguments.
returns: none required
see also: <compiling>, <loading>, <printing>
example: see the configuration file Ext.aml
<status>
──────────────────────────────────────────────────────────────────────
remarks: This event is sent 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 return value of <status> will become the
actual status line, allowing the status line to be
customized.
<status> is sent directly to 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: <display>, <paint>, windowflag
