tips:revmedia:subs20

SCRIBE

Published ByDateVersionKnowledge LevelKeywords
Revelation Technologies14 NOV 19892.XEXPERTSCRIBE

SCRIBE is Advanced Revelation's editor.

SCRIBE( inval, protect, exit_key, except_key, col, row, displen, color, flags, change, lines, exit, inpat, outpat, just, delim, mask, linelen, state )

SCRIBE is the same editor called by the full-screen editor, as well as that called at each prompt of a window. In effect, SCRIBE functions like the INPUT statement in R/BASIC. However, it offers much more power and flexibility in the form of cursor control, multi-line entry, data validation and masking, and compatibility with Advanced Revelation reserved keystrokes (such as [F5] for TCL). SCRIBE can store its environment, which can be restored for subsequent calls.

SCRIBE can handle input and editing of one or more lines. If more than one line is being displayed, full-screen editing capability is available in the form of up and down arrow keys, page up and page down, etc. SCRIBE will automatically scroll data through the window or line size defined for it by the calling parameters.

inval

Use inval to pass the data to be displayed and edited. SCRIBE also returns the edited data here. In multiline mode (lines is greater than 1), the lines of text returned in inval will be delimited by the character specified in delim.

protect

If true, protect prohibits the editing of inval data. A system message will be generated if editing is attempted. Protect defaults to false.

exit_key

Use exit_key to pass the key or key sequence that will exit SCRIBE whenever editing is enabled. Multiple exit.keys must be separated by | or @FM. In addition, exiting will under the following conditions:

  • [ <F128M>ì<F255D> ] is pressed at the top of an edit window or [ <F128M>Å<F255D> ] at the bottom.
  • [Enter] is pressed and lines is 0 (single line edit).

except_key

Use except_key to pass the key or key sequence that will exit SCRIBE whenever editing is disabled. Multiple except_keys must be separated by | or @FM. In addition, exiting will occur if [ <F128M>ì<F255D> ] is pressed at the top of an edit window or [ <F128M>Å<F255D> ] at the bottom.

col

Use col to pass an integer indicating the starting display column of the edit environment.

row

Use row to pass an integer indicating the top display row of the edit environment.

displen

Use displen to pass the display length, in columns, of the edit environment. Displen must be specified. If the length of the text entered exceeds displen, the text is scrolled horizontally.

color

Use color to pass an array of Advanced Revelation escape sequences indicating the video attributes for the edit window. The attributes default to the settings in @ENVIRON.SET. The following color fields may be set:

FieldDescription
<1>An escape sequence setting the video attributes of all text displayed.
<2>An escape sequence setting the video attributes for any defined block of text.
<3>An escape sequence setting the video attributes for text at the current line.

flags

Use flags to pass a dynamic array of SCRIBE environment parameters. The following are the definitions for the flags fields (these are also defined in the SCRIBE.FLAGS.CONSTANTS record):

EQU ST.CHAR$     TO  1
EQU NOPAINT$     TO  2
EQU UPPER.CASE$  TO  3
EQU EDIT.NAME$   TO  4
EQU FORCE.EDIT$  TO  5
EQU REPAINT$     TO  6
EQU NOSUBVALUES$ TO  7
EQU SAVE.STATE$  TO  8
EQU NOZOOM$      TO  9
EQU NO.ORIG.VAL$ TO 10
EQU EDITOR.FLAG$ TO 11
EQU KEEP.STATUS$ TO 12

The requirements for the field values are described below:

FieldDescription
<ST.CHAR$>Pre-process commands. This must be the ASCII code for the keystroke or keystroke sequence that calls the desired process. The function key [F1], for example, would be passed as CHAR(0):CHAR(59). The associated operation will be performed after inval is displayed and prior to the processing of the keystroke buffer (the value of @DATA).
<NOPAINT$>Suppress display of text. If true, text is not initially displayed.
<UPPER.CASE$>Case conversion. If true, all text is converted to upper case.
<EDIT.NAME$>Field name. The name of the field being edited (replaces the title in the Zoom window).
<FORCE.EDIT$>Insert. If true, SCRIBE will be activated in Insert mode.
<REPAINT$>Repaint. If true, the current line is displayed upon return to the SCRIBE edit session (saved in state <SS.LAST.VAL>). If false (the default value), the current line is not displayed. If the value is 2, the entire window is displayed (the value is then reset to false). This field value may be used in association with state specifications to redisplay text.
<NOSUBVALUES>Subvalue edit. If true, subvalue editing is disabled.
<SAVE.STATE$>Save current state. If true, the current edit session parameters are automatically saved in state. SCRIBE will then update these parameters during the edit process.
<NOZOOM$>If true, Zoom mode is disabled.
<NO.ORIG.VALUES$>Suppress save of inval data. If false, and if state <SS.ORIG.VAL> is null, a copy of the original inval data is saved in state (defaults to false).
<EDITOR.FLAG$>A Boolean flag. A value of true indicates a recursive call to SCRIBE.
<KEEP.STATUS$>A Boolean flag. If true, the status line is not overwritten unless a key is pressed.

change

Change returns true or false indicating whether edit changes occurred to inval data. False is returned if no changes were made, and true is returned otherwise.

lines

Use lines to specify single or multiple line entry modes. The following listed values are operable (defaults to 1):

ValueOperation
0Single line edit.
1Single line scroll for multi-line edit. A single line is displayed, the display scrolling vertically to the next line.
nFull screen edit (where n is an integer indicating the number of display rows in the window). Delim must be specified.

key

Key returns the ASCII code for the exit key used.

inpat

Use inpat to specify input pattern data validation and conversion. Syntactically as well as operationally, this is exactly the same as an In Pattern operation in the Paint window. Multiple inpat statements are processed as logical OR values and must be delimited by @VM or |. Inpat is applied to each line if lines specifies multi-line or single line scroll mode.

outpat

Use outpat to specify output pattern conversion (applied line by line). Syntactically as well as operationally, this is exactly the same as an Out Pattern operation in the Paint window (see the Paint documentation for more details).

just

Use just to specify display line justification. The possible values are:

ValueOperation
LLeft justified
RRight justified
CCenter justified
TText (text lines will wrap). Delim delimits each line.
TNText nonjustified (text lines will wrap).

delim

Use delim to specify the character used to delimit multiple lines of data in SCRIBE. This may be an accepted Advanced Revelation delimiter (e.g. @FM), an ASCII code, or a literal character. If delim is null, only single line text entry is enabled, regardless of any other specifications (this will cause the display of inval data to be suppressed if lines specifies multiline mode).

mask

Use mask to specify an input mask. This indicates to the user the length of data expected to be input. The mask is displayed at the current edit line. If mask is a single character, it is repeated for the length of the line.

linelen

Use linelen to specify the maximum length of the edit line (defaults to 64K). If * (asterisk) is specified, the value of displen is used. A carriage return is generated at the end of the line, unless just is T or TN.

state

Use state to pass a dynamic array (delimited with @RM) of edit session parameters. These parameters are saved in state, allowing recall of a specified edit environment. If flags <SAVE.STATE$> is set to true, SCRIBE saves the current edit environment (as opposed to a specified edit environment) in state, automatically maintaining (updating) these values during the edit session. Any existing state parameters are overwritten.

Note that the state specifications save but do not redisplay the edit session data. This data may be redisplayed by setting the flags <REPAINT$> field (see above).

If state is null, any previous state settings are cleared. The following fields are defined for state (these are also defined in the SCRIBE.STATE.CONSTANTS record):

EQU SS.ORIG.VAL    TO  1
EQU SS.LAST.VAL    TO  2
EQU SS.TOP         TO  3
EQU SS.MVD         TO  4
EQU SS.START       TO  5
EQU SS.POS         TO  6
EQU SS.EDITOR.ON   TO  7
EQU SS.INSERT      TO  8
EQU SS.FIND        TO  9
EQU SS.REPLACE     TO 10
EQU SS.STATE       TO 11
EQU SS.BLOCK.START TO 12
EQU SS.BLOCK.END   TO 13

The requirements for the field values are described below:

FieldDescription
<SS.ORIG.VAL>Original inval data (flags <SAVE.STATE$> must be false).
<SS.LAST.VAL>Contents of current display line.
<SS.TOP>Top display row of window.
<SS.MVD>Display row of current line.
<SS.START>Starting display column.
<SS.POS>Cursor location (display column) in current line.
<SS.EDITOR.ON>Edit flag. A setting of true enables editing; false disables it.
<SS.INSERT>Stores the current insert mode (true = insert, false = overstrike). The default insert mode is read out of @INSERT if the editor is toggled.
<SS.FIND>Current search string.
<SS.REPLACE>Current replacement string.
<SS.STATE>Changes in edit status. Notice which values are passed to SCRIBE and those set by SCRIBE. The status is indicated by the following values:

null - No changes (set by SCRIBE).
1 - Changes in current row preceding inpat operations (set by SCRIBE).
2 - Process current row through inpat (passed to SCRIBE).
3 - Process full edit session through inpat (passed to SCRIBE).
<SS.BLOCK.START>Starting row of current block.
<SS.BLOCK.END>Ending row of current block.

The following is a list of the argument list parameters in which SCRIBE passes values, a description of the value returned, and any conditions governing the return of this value:

Parameter ValueDescriptionConditions
invalEdited inval dataNone. Always returned.
keyThe key pressed to exit SCRIBENone. Always returned.
changeTrue or false (1 or 0)None. Always returned.
stateCurrent edit session parametersSCRIBE must have been called with flags <SAVE.STATE$> set to true.
Specified edit session parametersSCRIBE must have been called with flags <SAVE.STATE$> set to false and the specified edit session parameters set in state.
The original (unedited) value of invalSCRIBE must have been called with flags <NO.ORIG.VAL$> set to false and state as null.
/* This program prompts the user for information about the 
location of a window on the screen, and then calls SCRIBE to 
edit data within the window.  When SCRIBE is exited, the 
program reports on the return value of certain parameters.

The program loops through and re-calls SCRIBE until the user 
chooses to quit.  At each iteration, the user can 
reinitialize the data passed to SCRIBE. */

$INSERT INCLUDE, SCRIBE.FLAGS.CONSTANTS
$INSERT INCLUDE, SCRIBE.STATE.CONSTANTS
$INSERT INCLUDE, LOGICAL
$INSERT INCLUDE, WINDOW.POINTERS

DECLARE SUBROUTINE MSG, SCRIBE, BORDER.UP, INPUT.CHAR
DECLARE FUNCTION VIDEO.RW

EQU null        TO ""
EQU F9          TO CHAR(0):CHAR(67)
EQU esc         TO CHAR(27)
EQU cursor.down TO CHAR(0):CHAR(80)

verrors        = ""
verrors<1>     = "Out of memory during read attempt"
verrors<2>     = "Display is not memory-mapped"
verrors<3>     = "Col or Row is out of range"
verrors<4>     = "Left col is greater than right col, or"
verrors<4,1>   = "top row is greater than bottom row"
verrors<5>     = "MODE is not 'C', 'R', 'W'"
verrors<6>     = "Size of saved image is less than area to be restored"

* use VIDEO.RW to save and clear screen area
vstatus = VIDEO.RW(0,0, @CRTWIDE-1, @CRTHIGH-1, "R", image1)
IF vstatus THEN
    MSG(verrors<vstatus>, "", "", "")
    STOP
END
VIDEO.RW(0,0, @CRTWIDE-1, @CRTHIGH-1, "C","") ; * clear 
window
IF vstatus THEN
    MSG(verrors<vstatus>, "", "", "")
    STOP
END

* create background (read background char from current environment)

bchar = CHAR(@ENVIRON.SET<2>)
background = 5           ;* background video attribute
foreground = 14           ;* foreground video attribute
color = (background * 16) + foreground   ;* color formula
color = CHAR(color)
attributes = bchar:color
vstatus = VIDEO.RW(0,10, @CRTWIDE-1, @CRTHIGH-1, "C", attributes)
IF vstatus THEN
    MSG(verrors<vstatus>, "", "", "")
    STOP
END

* prompt for size and location of box

left = 10
MSG("Enter leftmost column location", "R", left,"")
top = 5
MSG("Enter topmost row location", "R", top,"")
width = 20
MSG("Enter width of window", "R", width,"")
depth = 8
MSG("Enter depth of window", "R", depth,"")
right = left + width
bottom = top + depth

* read only boxed area, store away
VIDEO.RW(left, top, right, bottom, "R", image2)

* clear boxed area and put border around it
VIDEO.RW(left, top, right, bottom, "C", "")
BORDER.UP(left, top, right, bottom, 1, CURATR()) ; * add border

* actual processing loop
done   = false    ; * flag for LOOP..REPEAT
first.time = true ; * flag indicating first time thru loop
resp  = "Y"       ; * default response for message call
state  = null     ; * initialize scribe state to null (new)
LOOP
    IF NOT( first.time ) THEN
MSG("Do you wish to call SCRIBE again?","RC",resp,"")
IF resp EQ "Y" THEN
* determine whether to re-initialize the default data
redo = "N"
MSG("Re-initialize IVAL (Y/N)?", "RC", redo, "")
IF redo EQ "Y" THEN
* set IVAL and STATE to null
ival = null ; state = null
END ; * if redo eq "y"
END ; * if resp eq "y"
END ; * if not( first.time )

UNTIL resp NE "Y" DO

/* call SCRIBE to fit into existing window if first time, 
load IVAL w/ default data, otherwise accept existing data */

IF first.time THEN
* note use of @VM as delimiter (as in DELIM)
ival = "This is a" :@VM: "sample call" :@VM: "to SCRIBE"
END ; * if first.time

protect = false           ; * protects IVAL if true
exit_key  = esc:@FM:F9    ; * keys that cause exit
except_key = cursor.down  ; * causes exit w/ editor OFF
col = left+1              ; * left column
row = top +1              ; * top row
displen = (right-left-2)  ; * display length
color = null              ; * video attr (null = default)
* load values out of the environment
color<<1>> = @XW<ctext>
color<<2>> = @XW<csel>        ; *  for edit window
color<<3>> = @XW<ccomment>

flags                 = null   ;* environment flags for SCRIBE
flags<ST.CHAR$>     = null
flags<NOPAINT$>     = false
flags<UPPER.CASE$>  = false
flags<EDIT.NAME$>   = "SCRIBE SAMPLE"
flags<FORCE.EDIT$>  = true
flags<REPAINT$>     = 0
flags<NOSUBVALUES$> = false
flags<SAVE.STATE$>  = true
flags<NOZOOM$>      = false
flags<NO.ORIG.VAL$> = false
change  = null
lines   = (bottom-top)-2
exit    = null
inpat   = null
outpat  = null
just    = "L"
delim   = @VM
mask    = null
linelen = displen+1

* STATE contains information about the last time SCRIBE was called

IF first.time THEN state = null

SCRIBE(ival, protect, exit_key, except_key, col, row, displen, color, flags, change, lines, exit, inpat, outpat, just, delim, mask, linelen, state)

first.time = false

* any value returned from the window?
IF ival THEN
MSG("Value = ":ival,"","","")
END

IF flags<SAVE.STATE$> THEN
SS = state
CONVERT @RM TO @FM IN SS
string = ""
string<1,1> = "Orig value = ":SS<SS.ORIG.VAL>
string<1,3> = "New value = ":IVAL
MSG(string,"","","")
MSG("Cleanup status = ":SS<SS.STATE>,"","","")
END

* display values of change and key variables
string = null
string<1,1> = "CHANGE = ":CHANGE
string<1,2> = "EXIT = ":SEQ(exit[1,1]):" ":SEQ(exit[2,1])
MSG(string,"","","")

REPEAT

* clean up
vstatus = VIDEO.RW(left, top, right, bottom, "W", image2)
IF vstatus THEN
    MSG(verrors<vstatus>, "", "", "")
    STOP
END

vstatus = VIDEO.RW(0,0, @CRTWIDE-1, @CRTHIGH-1, "W", image1)
IF vstatus THEN
    MSG(verrors<vstatus>, "", "", "")
    STOP
END

STOP
  • tips/revmedia/subs20.txt
  • Last modified: 2024/06/19 20:20
  • by 127.0.0.1