SCRIBE
Published By | Date | Version | Knowledge Level | Keywords |
---|---|---|---|---|
Revelation Technologies | 14 NOV 1989 | 2.X | EXPERT | SCRIBE |
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 )
Using SCRIBE
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:
Field | Description |
---|---|
<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:
Field | Description |
---|---|
<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):
Value | Operation |
---|---|
0 | Single line edit. |
1 | Single line scroll for multi-line edit. A single line is displayed, the display scrolling vertically to the next line. |
n | Full 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:
Value | Operation |
---|---|
L | Left justified |
R | Right justified |
C | Center justified |
T | Text (text lines will wrap). Delim delimits each line. |
TN | Text 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:
Field | Description |
---|---|
<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. |
Values Returned
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 Value | Description | Conditions |
---|---|---|
inval | Edited inval data | None. Always returned. |
key | The key pressed to exit SCRIBE | None. Always returned. |
change | True or false (1 or 0) | None. Always returned. |
state | Current edit session parameters | SCRIBE must have been called with flags <SAVE.STATE$> set to true. |
Specified edit session parameters | SCRIBE 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 inval | SCRIBE must have been called with flags <NO.ORIG.VAL$> set to false and state as null. |
Correct Use of SCRIBE
/* 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