Volume 7A: XView Programming Manual

The text can then be read via the usual file input utilities, or the file itself can be passed off to

another routine or program.

It is, however, useful to be able to directly examine the text in the text subwindow. You can

do this using the TEXTSW_CONTENTS attribute. The code fragment below illustrates how to

use TEXTSW_CONTENTS to get a span of characters from the text subwindow. It gets 1000

characters beginning at position 500 out of the text subwindow and places them into a NULL-

terminated string.

#define TO_READ 1000

char buf[TO_READ+1];

Textsw_index next_pos;

next_pos = (Textsw_index) xv_get(textsw, TEXTSW_CONTENTS, 500,

buf, TO_READ);

if (next_pos != 500+TO_READ) {

/* handle error case */

} else

buf[TO_READ] = ’\0’;

8.4.5 Deleting Text

You can delete a contiguous span of characters from a text subwindow by calling:

Textsw_index

textsw_delete(textsw, first, last_plus_one)

Textsw textsw;

Textsw_index first, last_plus_one;

first specifies the first character of the span that will be deleted; last_plus_one speci-

fies the first character after the span that will not be deleted. first should be less than or

equal to last_plus_one. To delete to the end of the text, pass the special value

TEXTSW_INFINITY for last_plus_one.

The return value is the number of characters deleted or:

last_plus_one - first

unless the specified span is read-only. If the insertion point is in the span being deleted, it

will be left at first.

A side effect of calling textsw_delete() is that the deleted characters become the con-

tents of the global Clipboard. To remove the characters from the text subwindow without

affecting the Clipboard, call:

Textsw_index

textsw_erase(textsw, first, last_plus_one)

Textsw textsw;

Textsw_index first, last_plus_one;

Again, the return value is the number of characters removed, and last_plus_one can be

TEXTSW_INFINITY.

Both of these procedures will return 0 if the operation fails.

220 XView Programming Manual

8.4.6 Emulating an Editing Character

You can emulate the behavior of an editing character, such as CTRL-H, with

textsw_edit():

Textsw_index

textsw_edit(textsw, unit, count, direction)

Textsw textsw;

unsigned unit, count, direction;

Depending on the value of unit, this routine will erase either a character, a word, or a line.

Set unit to:

• TEXTSW_UNIT_IS_CHAR to erase individual characters.

• TEXTSW_UNIT_IS_WORD to erase the span of characters that make up a word (including

any intervening white space or other nonword characters).

• TEXTSW_UNIT_IS_LINE to erase all characters in the line on one side of the insertion

point.

If the direction parameter is 0, the operation will affect characters after the insertion

point; otherwise, it will affect characters before the insertion point.

The count parameter determines the number of times the operation will be applied. Set it to

1 to do the edit once or to a value greater than 1 to do multiple edits in a single call.

textsw_edit() returns the number of characters actually removed.

For example, suppose you want to interpret the function key F7 as meaning delete word for-

ward. On receiving the event code for the F7 key, you would make the call:

textsw_edit(textsw, TEXTSW_UNIT_IS_WORD, 1, NULL);

8.4.7 Replacing Characters

While a span of characters can be replaced by calling textsw_erase() followed by

textsw_insert(), character replacement is done most efficiently by calling:

Textsw_index

textsw_replace_bytes(textsw, first, last_plus_one, buf, buf_len)

Textsw textsw;

Textsw_index first, last_plus_one;

char *buf;

int buf_len;

The span of characters to be replaced is specified by first and last_plus_one, just as

in the call to textsw_erase(). The new characters are specified by buf and buf_len,

just as in the call to textsw_insert(). Once again, if last_plus_one is

TEXTSW_INFINITY, the replace operation affects all characters from first to the end of the

text. If the insertion point is in the span being replaced, it will be left at:

first + buf_len

Text Subwindows

Text Subwindows 221

The return value is the net number of bytes inserted. The number is negative if the original

string is longer than the one that replaces it. If a problem occurs when an attempt is made to

replace a span, it will return an error code of 0.

textsw_replace_bytes(), like textsw_erase(), does not put the characters it

removes on the global Clipboard.

8.4.8 The Editing Log

All text subwindows allow the user to undo editing actions. The TEXTSW package keeps a

running log of all the edits. If a file is associated with the text subwindow, this log is kept in

a file in the /tmp directory. This file can grow until the file system in which this directory

resides runs out of space. To limit the size of the edit log and to avoid filling up all of /tmp,

the user can set the text wrap-around size with TEXTSW_WRAPAROUND_SIZE. If there is no

associated file, the edit log is kept in memory, and the maximum size of the log is controlled

by the attribute TEXTSW_MEMORY_MAXIMUM, which defaults to 20,000 bytes.

Unfortunately, once a memory-resident edit log has reached its maximum size, no more char-

acters can be inserted into or removed from the text subwindow. In particular, since deletions

as well as insertions are logged, space cannot be recovered by deleting characters.

It is important to understand how the edit log works, since you might want to use a text

subwindow with no associated file to implement a temporary scratch area or error message

log. If such a text subwindow is used for a long time, the default limit of 20,000 bytes might

well be reached, and either the user or your code will be unable to insert any more characters,

even though only a few characters might be visible in the text subwindow. Therefore, it is

recommended to set

TEXTSW_MEMORY_MAXIMUM to a much higher value, say 200,000.

8.4.9 Which File is Being Edited?

To find out the name of the file in the text subwindow, call:

int

textsw_append_file_name(textsw, name)

Textsw textsw;

char *name;

If the text subwindow is editing memory, then this routine will return a nonzero value.

Otherwise, it will return 0 and append the name of the file to the end of name. The following

code gets the name of the current file:

char name[BUFSIZ];

name[0] = ’\0’;

if (textsw_append_file_name(textsw, name) == 0)

printf("File name is: %s\n", name);

222 XView Programming Manual

8.4.9.1 Interactions with the file system

Suppose the current file is called myfile. If the user chooses textsw_save()), the follow-

ing sequence of file operations occurs:

• myfile is copied to myfile%.

• The contents of myfile% are combined with information from the edit log file

(/tmp/TextProcess-id.Counter) and written over myfile, thereby preserving all its permis-

sions, etc.

• The edit log file is removed from /tmp.

If myfile is a symbolic link to ../some_dir/otherfile, then the backup file is created as

../some_dir/otherfile%.

Keep in mind that the user can change the current directory by selecting “Load File” or “Set

Directory” from the text subwindow menu. If myfile is a relative path name, then both the

copy to myfile% and the save take place in the current directory.

8.5 Saving Edits in a Subwindow

To save any edits made to a file currently loaded into a text subwindow call:

unsigned

textsw_save(textsw, locx, locy)

Textsw textsw;

int locx, locy;

locx and locy are relative to the upper-left corner of the text subwindow and are used to

position the upper-left corner of the alert should the save fail for some reason—usually they

should be 0. The return value is 0 if and only if the save succeeded.

8.5.1 Storing Edits

The text subwindow might not contain a file, or the client might wish to place the edited ver-

sion of the text (whether or not the original text came from a file) in some specific file. To

store the contents of a text subwindow to a file, call:

unsigned

textsw_store_file(textsw, filename, locx, locy)

Textsw textsw;

char *filename;

int locx, locy;

Again, locx and locy are used to position the upper-left corner of the message box. The

return value is 0 if and only if the store succeeded.

By default, this call changes the file that the text subwindow is editing, so that subsequent

saves will save the edits to the new file. To override this policy, set the attribute

TEXTSW_STORE_CHANGES_FILE to FALSE.

Text Subwindows

Text Subwindows 223

8.5.2 Discarding Edits

To discard the edits performed on the contents of a text subwindow, call:

void

textsw_reset(textsw, locx, locy)

Textsw textsw;

int locx, locy;

locx and locy are as above. Note that if the text subwindow contains a file that has not

been edited, the effect of textsw_reset is to unload the file and replace it by memory

provided by the TEXTSW package; thus, the user will see an absolutely empty text subwindow.

Alternatively, if the text subwindow was already editing memory, then another, untouched,

piece of primary memory will be provided and the edited piece will be deallocated.

8.6 Setting the Contents of a Text Subwindow

The rest of this chapter describes the other functions that are available for text subwindows.

These features include setting the contents of a subwindow, setting the primary selection, and

dealing with multiple or split views.

You might want to set the initial contents of a text subwindow that your application uses. To

set the initial contents of a text subwindow, use one of three attributes:

TEXTSW_INSERT_FROM_FILE, TEXTSW_FILE_CONTENTS, and TEXTSW_CONTENTS. Each

attribute is illustrated in code fragments given below.

8.6.1 TEXTSW_FILE_CONTENTS

The attribute

TEXTSW_FILE_CONTENTS

allows a client to initialize the text subwindow con-

tents from a file yet still edit the contents in memory. The user can return a text subwindow

to its initial state after an editing session by choosing “Undo All Edits” in the text menu.

The code fragment below shows how you would use this attribute:

extern char *filename;

xv_set(textsw,

TEXTSW_FILE_CONTENTS, filename,

TEXTSW_FIRST, 0,

NULL);

When the client calls the undo routine and filename is not a null string, the memory used

by the text subwindow is reinitialized with the contents of the file specified by filename.

When the client calls the undo routine and the filename is a null string, the memory used

by the text subwindow is reinitialized with the previous contents of the text subwindow.

224 XView Programming Manual