TEXTSW_CONTENTS lets you insert a text string from memory, instead of a ﬁle, into the text
subwindow. The default for this attribute is NULL.
Using xv_create() with this attribute speciﬁes the initial contents for a nonﬁle text
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
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 ﬁlled with the characters from textsw beginning at the index pos and is NULL-ter-
minated only if there were too few characters to ﬁll the buffer.
allows a client to insert the contents of a ﬁle 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:
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():
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 deﬁnitions of
“line of text.”
A screen line reﬂects 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 ﬁle line, on the other hand, can only be ter-
minated by the newline character. It is deﬁned as the span of characters starting after a new-
line character (or the beginning of the ﬁle) running through the next newline character (or the
end of the ﬁle).
Whenever the right edge of the subwindow is encountered before the newline, if the follow-
ing attribute-value pair were speciﬁed:
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 ﬁle line. From the perspective of
the display there are two lines; from the perspective of the ﬁle, only one. On the other hand,
if the following attribute-value pair were speciﬁed:
then the entire word would be displayed on the next line.
Unless otherwise speciﬁed, all text subwindow attributes and procedures use the ﬁle line deﬁ-
nition. Line indices have a zero-origin, like the character indices; that is, the ﬁrst 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 ﬁrst character of the line
containing the index to become the ﬁrst character displayed in the text subwindow. Thus, the
following call causes the text to be positioned so that the ﬁrst displayed character is the ﬁrst
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:
Conversely, the following call retrieves the index of the ﬁrst 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 ﬁle 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:
The return value is the character index for the ﬁrst 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:
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 ﬁnd this out by calling:
8.7.4 Which File Lines are Visible?
Exactly which ﬁle lines are visible on the screen is determined by calling:
textsw_file_lines_visible(textsw, top, bottom)
int *top, *bottom;
Text Subwindows 227
This routine ﬁlls in the addressed integers with the ﬁle line indices of the ﬁrst and last ﬁle
lines being displayed in the speciﬁed text subwindow.
184.108.40.206 Guaranteeing what is visible
To ensure that a particular line or character is visible, call:
The text subwindow must be displayed on the screen before this function will work.
If the character at the speciﬁed 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-
If a particular character should always be at the top of the subwindow, then calling the fol-
lowing routine is more appropriate:
220.127.116.11 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_index) xv_get(textsw, TEXTSW_INSERTION_POINT));
8.8 Finding and Matching a Pattern
A common operation performed on text is to ﬁnd a span of characters that match some speci-
ﬁcation. 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 ﬁnd the nearest span of characters that match a pattern, call:
textsw_find_bytes(textsw, first, last_plus_one, buf,
228 XView Programming Manual
Textsw_index *first, *last_plus_one;
The pattern to match is speciﬁed 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 speciﬁes 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 ﬁnd delimited text. For example, you might want to ﬁnd the
starting and ending brace in a piece of code. To ﬁnd a matching pattern, call:
textsw_match_bytes(textsw, first, last_plus_one,
end_sym, end_sym_len, field_flag)
Textsw_index *first, *last_plus_one;
char *start_sym, *end_sym;
int start_sym_len, end_sym_len;
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 ﬁeld ﬂag values to search for matches:
Begins from first and searches forward until it ﬁnds start_sym and matches it
forward with end_sym.
Begins from first and searches backward for end_sym and matches it backward
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 ﬁrst match.
Text Subwindows 229