Volume 7A: XView Programming Manual

8.6.2 TEXTSW_CONTENTS

TEXTSW_CONTENTS lets you insert a text string from memory, instead of a file, into the text

subwindow. The default for this attribute is NULL.

Using xv_create() with this attribute specifies the initial contents for a nonfile text

subwindow.

Using xv_set() with this attribute sets the contents of a window, as in:

xv_set(textsw, TEXTSW_CONTENTS, "text", NULL);

If you use xv_get() with this attribute, you will need to provide additional parameters, as

in:

xv_get(textsw, TEXTSW_CONTENTS, pos, buf, buf_len);

The return value is the next position to be read. The buffer array:

buf[0 ... buf_len-1]

is filled with the characters from textsw beginning at the index pos and is NULL-ter-

minated only if there were too few characters to fill the buffer.

8.6.3 TEXTSW_INSERT_FROM_FILE

TEXTSW_INSERT_FROM_FILE

allows a client to insert the contents of a file into a text

subwindow at the current insertion point. It is the programming equivalent of a user choos-

ing “Include File” from the text menu.

The code below demonstrates this attribute:

Textsw textsw;

Textsw_status status;

xv_set(textsw,

TEXTSW_STATUS, &status,

TEXTSW_INSERT_FROM_FILE, filename,

NULL);

Three status values can be returned for this attribute when the argument TEXTSW_STATUS is

passed in the same call to xv_create() or xv_set():

TEXTSW_STATUS_OKAY

TEXTSW_STATUS_CANNOT_INSERT_FROM_FILE

TEXTSW_STATUS_OUT_OF_MEMORY

Text Subwindows

Text Subwindows 225

8.7 Positioning the Text Displayed in a Text Subwindow

Usually, more text is managed by the text subwindow than can be displayed all at once. As a

result, it is often necessary to determine the indices of the characters that are being displayed

and to control exactly which portion of the text is visible.

8.7.1 Screen Lines and File Lines

When there are long lines in the text, it is necessary to distinguish between two definitions of

“line of text.”

A screen line reflects what is actually displayed on the screen. A line begins with the left-

most character in the subwindow and continues across until either a newline character or the

right edge of the subwindow is encountered. A file line, on the other hand, can only be ter-

minated by the newline character. It is defined as the span of characters starting after a new-

line character (or the beginning of the file) running through the next newline character (or the

end of the file).

Whenever the right edge of the subwindow is encountered before the newline, if the follow-

ing attribute-value pair were specified:

TEXTSW_LINE_BREAK_ACTION, TEXTSW_WRAP_AT_CHAR

then the next character and its successors would be displayed on the next lower screen line.

In this case, there would be two screen lines, but only one file line. From the perspective of

the display there are two lines; from the perspective of the file, only one. On the other hand,

if the following attribute-value pair were specified:

TEXTSW_LINE_BREAK_ACTION, TEXTSW_WRAP_AT_WORD

then the entire word would be displayed on the next line.

Unless otherwise specified, all text subwindow attributes and procedures use the file line defi-

nition. Line indices have a zero-origin, like the character indices; that is, the first line has

index 0, not 1.

8.7.2 Absolute Positioning

Two attributes are provided to allow you to specify which portion of the text is displayed in

the text subwindow.

Setting the attribute

TEXTSW_FIRST to a given index causes the first character of the line

containing the index to become the first character displayed in the text subwindow. Thus, the

following call causes the text to be positioned so that the first displayed character is the first

character of the line that contains index 1000:

xv_set(textsw, TEXTSW_FIRST, 1000, NULL);

Since the text subwindow is subclassed from the OPENWIN package and can be split into sev-

eral views, the previous code fragment would only cause the positioning of one view. To

226 XView Programming Manual

position all of the views in a text subwindow, use the attribute TEXTSW_FOR_ALL_VIEWS, as

in the following call:

xv_set(textsw,

TEXTSW_FOR_ALL_VIEWS, TRUE,

TEXTSW_FIRST, 1000,

NULL);

Conversely, the following call retrieves the index of the first displayed character:

index = (Textsw_index)xv_get(textsw, TEXTSW_FIRST);

A related attribute, useful in similar situations, is

TEXTSW_FIRST_LINE. When used in a call

on xv_set() or xv_get(), the value is a file line index within the text.

You can determine the character index that corresponds to a given line index (both zero-

origin) within the text by calling:

Textsw_index

textsw_index_for_file_line(textsw, line)

Textsw textsw;

int line;

The return value is the character index for the first character in the line, so character index 0

always corresponds to line index 0.

8.7.3 Relative Positioning

To move the text in a text subwindow up or down by a small number of lines, call the routine:

void

textsw_scroll_lines(textsw, count)

Textsw textsw;

int count;

A positive value for count causes the text to scroll up, while a negative value causes the

text to scroll down.

When calling textsw_scroll_lines(), you might want to know how many screen

lines are in the text subwindow. You can find this out by calling:

int

textsw_screen_line_count(textsw)

Textsw textsw;

8.7.4 Which File Lines are Visible?

Exactly which file lines are visible on the screen is determined by calling:

void

textsw_file_lines_visible(textsw, top, bottom)

Textsw textsw;

int *top, *bottom;

Text Subwindows

Text Subwindows 227

This routine fills in the addressed integers with the file line indices of the first and last file

lines being displayed in the specified text subwindow.

8.7.4.1 Guaranteeing what is visible

To ensure that a particular line or character is visible, call:

void

textsw_possibly_normalize(textsw, position)

Textsw textsw;

Textsw_index position;

The text subwindow must be displayed on the screen before this function will work.

If the character at the specified position is already visible, then this routine does nothing.

If it is not visible, then it repositions the text so that it is visible and at the top of the subwin-

dow.

If a particular character should always be at the top of the subwindow, then calling the fol-

lowing routine is more appropriate:

void

textsw_normalize_view(textsw, position)

Textsw textsw;

Textsw_index position;

8.7.4.2 Ensuring that the insertion point is visible

Most of the programmatic editing actions do not update the text subwindow to display the

caret, even if TEXTSW_INSERT_MAKES_VISIBLE is set. If you want to ensure that the inser-

tion point is visible, use:

textsw_possibly_normalize(textsw,

(Textsw_index) xv_get(textsw, TEXTSW_INSERTION_POINT));

8.8 Finding and Matching a Pattern

A common operation performed on text is to find a span of characters that match some speci-

fication. The text subwindow provides several rudimentary pattern matching facilities. This

section describes two functions that you can call in order to perform similar operations.

8.8.1 Matching a Span of Characters

To find the nearest span of characters that match a pattern, call:

int

textsw_find_bytes(textsw, first, last_plus_one, buf,

buf_len, flags)

228 XView Programming Manual

Textsw textsw;

Textsw_index *first, *last_plus_one;

char *buf;

unsigned buf_len;

unsigned flags;

The pattern to match is specified by buf and buf_len. The matching operation looks for

an exact and literal match—it is sensitive to case and does not recognize any kind of meta-

character in the pattern. first specifies the position at which to start the search. If flags

is 0, the search proceeds forward through the text; if flags is 1, the search proceeds back-

wards. The return value is –1 if the pattern cannot be found; otherwise it is some non-

negative value, in which case the indices addressed by first and last_plus_one will

have been updated to indicate the span of characters that match the pattern.

8.8.2 Matching a Specific Pattern

Another useful operation is to find delimited text. For example, you might want to find the

starting and ending brace in a piece of code. To find a matching pattern, call:

int

textsw_match_bytes(textsw, first, last_plus_one,

start_sym, start_sym_len,

end_sym, end_sym_len, field_flag)

Textsw textsw;

Textsw_index *first, *last_plus_one;

char *start_sym, *end_sym;

int start_sym_len, end_sym_len;

unsigned field_flag;

first stores the starting position of the pattern that you want to search for.

last_plus_one stores the cursor position of the end pattern. Its value is one position past

the text. start_sym and end_sym store the beginning position and ending position of the

pattern, respectively. start_sym_len and end_sym_len store the starting and ending

pattern’s length, respectively.

Use one of the following three field flag values to search for matches:

TEXTSW_DELIMITER_FORWARD

Begins from first and searches forward until it finds start_sym and matches it

forward with end_sym.

TEXTSW_DELIMITER_BACKWARD

Begins from first and searches backward for end_sym and matches it backward

with start_sym.

TEXTSW_DELIMITER_ENCLOSE

Begins from first and expands both directions to match start_sym and

end_sym of the next level.

If no match is found, then textsw_match_bytes() will return a value of –1. If a match

is found, then it will return the index of the first match.

Text Subwindows

Text Subwindows 229