%N.Meb[options]

In this section:

This format code, %eb (Edit Box), provides a text editor and is by far the most complex format available. However, many applications will not require any of the embellishments detailed below. Note that %rs (Edit String) and %re (Multiline Edit Box) are simpler to use but are limited to 32768 characters.

Two arguments are required, a pointer to the buffer containing the text to be edited, and an integer specifying the maximum size of the buffer. The text should be terminated by the null (CHAR(0)) character, and new lines should consist of carriage return/line feed pairs. This does not use the standard Windows edit control and as a result there is no limit (other than the total available memory) to the size of the text area. If the second argument (the length of the buffer) is set to zero, the edit box allocates its own memory for the buffer, re-sizing it as required.

%60eb denotes an edit box that displays 60 characters on one line (which is the same as %60.1eb). %60.20eb denotes an edit box that displays 60 characters by 20 lines.

The text itself has the format of a normal DOS text file (lines of text separated by a carriage return/line feed character pair) with a closing a null terminator. The edit box can also handle text lines separated by carriage return characters only, providing this is used consistently.

In order to read/write data to a file in this format the file should be opened in binary mode.

For example:

    WINAPP
    CHARACTER*1000 buffer
    CHARACTER*80 fname
    INTEGER(2) handle,err_code
    INTEGER bytes_read,nbytes,winio@
    fname='myfile'
    CALL openr@(fname,handle,err_code)
    CALL readf@(buffer,handle,1000,bytes_read,err_code)
    CALL closef@(handle,err_code)
    i=winio@('%60.20eb',buffer,1000)
    CALL openw@(fname,handle,err_code)
    nbytes=INDEX(buffer,CHAR(0))-1
    CALL writef@(buffer,handle,nbytes,err_code)
    END

The only null character in the string must be at the end. You must include the null character when calculating the length of a string. In the above example, the Fortran INDEX intrinsic function has been used to obtain the size of the edit buffer. An alternative method is given below. Note that OPENR@ etc. are Silverfrost Fortran library routines.

[options] is a list of items surrounded by square brackets and separated by commas. The entire (square-bracketed) list may be omitted if no options are required.

hscrollbar	Supply and control a horizontal scroll bar.
limited_hscrollbar	Like hscrollbar but the user is prevented from scrolling horizontally until all characters have disappeared.
vscrollbar	Supply and control a vertical scroll bar.
no_hscroll	Inhibit all horizontal scrolling.
no_vscroll	Inhibit all vertical scrolling.
alt_edit	Changes the action of Del, Backspace, and Enter keys so that they never split or join lines.
fixed_font	Uses a fixed font for the edit box, rather than the default variable font. (However, it is preferable to use %fn (Font), with a monospaced font such as Courier New, before %eb in the format string.)
hook_focus	Causes the call-back to be called every time the box gains or loses the focus. Note that the over use of this option can cause annoying effects for the user and more importantly an infinite loop may be started if the result of an object gaining a focus is the shift of that focus to another object!
use_tabs	Uses tabs in the edit box in the normal way for an editor. Otherwise tabs are used to cycle through the various controls in the parent window.
no_frame	Removes the line around the edit box without removing the blank border (no_border removes both). This option is particularly useful for edit boxes which fill a window.
no_border	Omit the blank border that by default is placed between the text and the surrounding box.
read_only	Prevents the user from changing the text. The cursor can still be used to scroll through the text.
user_colours	The call-back function is invoked in such a way that the colours used for text and its background can be modified. This facility could be used, for example, to produce an editor which highlighted certain keywords. The use of this option is described further below.
extended	Allows CLEARWIN_STRING@('CALLBACK_REASON') to be used within a call-back function. For %eb the possible returns include 'DATA_ALTERATION'.
undo	Causes the edit box to save information to enable changes to be 'undone'. By default all changes are recorded and can be undone in reverse order. The program can also restrict the amount of undo information by calling a function. The standard call-back function 'EDIT_UNDO' is used to perform one level of undo each time it is invoked. Menus or buttons attached to this call-back will automatically become grey when no more undo information is available. The undo mechanism can reverse changes made using the keyboard/ mouse or by calling any of the edit-box related functions. However changes made by directly altering the buffer and calling WINDOW_UPDATE@ will not be recorded and cannot be reversed.
no_cursor_snap	By default if, when you move the cursor up or down, you end up off the end of the line, the cursor will snap back to the end of the line. For some purposes, such as when you are using block marks (see below), this is inconvenient. Use the no_cursor_snap option to leave the cursor in free space on the end of the line.
report_double_clicks	Responds to a mouse (left) double click by calling the call-back function rather than by marking a word.
report_right_clicks	Responds to a mouse right click by calling the call-back function rather than by looking for a pop-up menu.

EDITINFO

The edit box maintains a set of variables in a structure (called an EDIT_INFO structure) that controls the operation of the box. Normally these variables are hidden. However, much more detailed control of the edit box can be obtained by using the grave accent edit modifier and by supplying an array of the form:

INTEGER info(24)

Note that the array size and offsets are for 32 bit applications (see below).

If more than one edit box is open, each one must have its own EDIT_INFO structure.

The following example illustrates the use of this structure, making use of the following identifiers:

Offset	Label	Description
1	h_position	Cursor horizontal character position.
2	v_position	Cursor vertical character position.
3	last_line	Total number of lines in the buffer.
4	buffer (INTEGER(7)	Address of edit buffer.
5	size	Size of buffer contents (excluding null terminator).
6	max_buffer_size	Size of memory block.
7	current_position (INTEGER(7))	Address of the position corresponding to eb_h_position/eb_v_position.
8	selection (INTEGER(7))	Address of selected text if any.
9	n_selected	Number of selected characters.
10	vk_key	Set to VK_TAB etc. if this handles a key press.
11	vk_shift	Shift state corresponding to key.
12	active	Set to the number of the edit box (1 if only one edit box is open) when a call-back is invoked, reset afterwards. This value is used to identify which edit box is associated with the current use of a call-back function.
13	modified	Set to 1 each time the buffer is modified.
14	closing	Set when buffer is about to be closed.
15	n_chars_to_colour	Count of characters to colour.
16	text_to_colour (INTEGER(7)	Address within buffer for region to colour.
17	text_colours (INTEGER(7))	Address of foreground colours.
18	background_colours (INTEGER(7))	Address of background colours.
19-24		Reserved for future enhancements.

NB. For 64 bit applications, addresses (shown as INTEGER(7) in the above table) become 64 bit integers so the offsets and size for the integer array must be adjusted accordingly. As a result it is simpler to use the TYPE that is named edit_info that is defined in clearwin.ins and used in the corresponding standard modules.

Although this structure is passed to most of the functions described below, you will not normally need to know its contents nor should you normally need to manipulate the buffer yourself. (You can do so it you wish, but you must remember to update the contents consistently and to make use of WINDOW_UPDATE@ at appropriate intervals.)

The following example takes the last example above and adapts it so that a) the edit box allocates its own buffer with address eb_buffer and b) the eb_modified flag is checked before a prompt to save the edited file.

WINAPP
INTEGER(2) handle,err_code
INTEGER i,winio@
INTEGER info(24),
1 eb_h_position,  eb_v_position,     eb_last_line,
2 eb_buffer,      eb_buffer_size,    eb_max_buffer_size,
3 eb_current_position,eb_selection,  eb_n_selected,
4 eb_vk_key,      eb_vk_shift,       eb_active,
5 eb_modified,    eb_closing,        eb_reserved(10)
  EQUIVALENCE
1 (eb_h_position,    info(1)), (eb_v_position,     info(2)),
2 (eb_last_line,     info(3)), (eb_buffer,         info(4)),
3 (eb_buffer_size,   info(5)), (eb_max_buffer_size,info(6)),
4 (eb_current_position,info(7)), (eb_selection,    info(8)),
5 (eb_n_selected,      info(9)), (eb_vk_key,       info(10)),
6 (eb_vk_shift,        info(11)),(eb_active,       info(12)),
7 (eb_modified,        info(13)),(eb_closing,      info(14)),
8 (eb_reserved,        info(15))
i=winio@('%60.20`eb','*',0,info)
IF(eb_modified.EQ.1)THEN
   i=winio@('%cnSave changes?%2nl%6bt[Yes]  %6bt[No]')
   IF(i.EQ.1)THEN
     CALL openw@('myfile',handle,err_code)
     CALL writef@(CCORE1(eb_buffer),handle,eb_buffer_size,
+                 err_code)
   ENDIF
ENDIF
END

Note the use of the Silverfrost-supplied intrinsic function CCORE1 to return the character string at the given address.

The Silverfrost-supplied intrinsic function LOC can be used when the address of a variable is required. For example, if an edit buffer is provided, the following fragment of code would give the position of any selected text in the window relative to the beginning of the file.

  CHARACTER*1000 buffer
  INTEGER position,info(24)
  .....
  i=winio@('%60.20`eb',buffer,1000,info)
  position=eb_selection-LOC(buffer)

Note also that, if an edit buffer is provided, a call-back function can be used to monitor the size of the text in the buffer and to make a call to GET_STORAGE@ if it is getting full. If the buffer overflows, the system will generate a fatal error.

%eb can take the caret (^) format modifier to indicate that a call-back function is supplied (after the address of the EDIT_INFO structure if any). This function is called whenever the contents of the box change, a key is pressed, or the cursor is moved. If the call-back function does not handle the response to control keys such as Delete, BackSpace, etc., then it should return a zero value.

This format code can also use the tilde (~) format modifier to indicate that a grey control variable is supplied. This variable should precede the call-back function (if any) in the argument list.

An edit box will almost certainly contain information that the user will not wish to lose, so it is a good idea to use the %cc (Control Closure) format to monitor the closure of the main window.

%N.Meb[options]

EDITINFO

Fortran Links

News