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

Get Volume 7A: XView Programming Manual now with O’Reilly online learning.

O’Reilly members experience live online training, plus books, videos, and digital content from 200+ publishers.