aboutsummaryrefslogtreecommitdiff
path: root/libXaw/spec/TextSink
blob: 72ae3cf9985d1ac6770613e5128ede3e78dc0f77 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
.\" $Xorg: TextSink,v 1.3 2000/08/17 19:42:28 cpqbld Exp $
.NH 2
TextSink Object
.LP
.XS
	TextSink Object
.XE
.IN "TextSink object" "" "@DEF@"
.LP
.Ds 0
.TA 2.0i
.ta 2.0i
Application Header file	<X11/Xaw/TextSink.h>
.IN "TextSink.h" ""
Class Header file	<X11/Xaw/TextSinkP.h>
.IN "TextSinkP.h" ""
Class		textSinkObjectClass
.IN "textSinkObjectClass" ""
Class Name	TextSink
.IN "TextSink object" "class name"
Superclass	Object
.De
.LP
The TextSink object is the root object for all text sinks.  Any new text
sink objects should be subclasses of the TextSink Object.  The TextSink
Class contains all methods that the Text widget expects a text sink to
export.
.LP
Since all text sinks will have some resources in common, the TextSink
defines a few new resources.
.NH 3
Resources
.LP
When creating an TextSink object instance, the following resources are
retrieved from the argument list or from the resource database:
.LP
.IN "AsciiSink object" "resources"
.TS H
lw(1i) lw(1i) lw(1i) lw(.5i) lw(2i).
_
.sp 3p
.TB
Name	Class	Type	Notes	Default Value
.sp 3p
_
.TH
.R
.sp 3p
background	Background	Pixel		XtDefaultBackground
destroyCallback	Callback	XtCallbackList		NULL
foreground	Foreground	Pixel		XtDefaultForeground
.sp 3p
_
.TE
.Bg Bold
.Dc
.Sg Bold
.NH 3
Subclassing the TextSink
.IN "TextSink object" "subclassing" "@DEF@"
.LP
The only purpose of the TextSink Object is to be subclassed.  It
contains the minimum set of class methods that all text sinks must have.
While all may be inherited, the direct descendant of TextSink \fBmust
specify\fP some of them as TextSink does contain enough information to
be a valid text sink by itself.  Do not try to use
the TextSink as a valid sink for the Text widget; it is not intended
to be used as a sink by itself.
.TS H
lw(1i) lw(1.5i) lw(2i) lw(1i).
_
.sp 3p
.TB
Function	Inherit with	Public Interface	must specify
.sp 3p
_
.TH
.R
.sp 3p
DisplayText	XtInheritDisplayText	XawTextSinkDisplayText	yes
.IN "XtInheritDisplayText" ""
.IN "XawTextSinkDisplayText" ""
InsertCursor	XtInheritInsertCursor	XawTextSinkInsertCursor	yes
.IN "XtInheritInsertCursor" ""
.IN "XawTextSinkInsertCursor" ""
ClearToBackground	XtInheritClearToBackground	XawTextSinkClearToBackground	no
.IN "XtInheritClearToBackground" ""
.IN "XawTextSinkClearToBackground" ""
FindPosition	XtInheritFindPosition	XawTextSinkFindPosition	yes
.IN "XtInheritFindPosition" ""
.IN "XawTextSinkFindPosition" ""
FindDistance	XtInheritFindDistance	XawTextSinkFindDistance	yes
.IN "XtInheritFindDistance" ""
.IN "XawTextSinkFindDistance" ""
Resolve	XtInheritResolve	XawTextSinkResolve	yes
.IN "XtInheritResolve" ""
.IN "XawTextSinkResolve" ""
MaxLines	XtInheritMaxLines	XawTextSinkMaxLines	no
.IN "XtInheritMaxLines" ""
.IN "XawTextSinkMaxLines" ""
MaxHeight	XtInheritMaxHeight	XawTextSinkMaxHeight	no
.IN "XtInheritMaxHeight" ""
.IN "XawTextSinkMaxHeight" ""
SetTabs	XtInheritSetTabs	XawTextSinkSetTabs	no
.IN "XtInheritSetTabs" ""
.IN "XawTextSinkSetTabs" ""
GetCursorBounds	XtInheritGetCursorBounds	XawTextSinkGetCursorBounds	yes
.IN "XtInheritGetCursorBounds" ""
.IN "XawTextSinkGetCursorBounds" ""
_
.TE
.NH 4
Displaying Text
.LP
To display a section of the text buffer contained in the text source
use the function \fBDisplayText\fP:
.IN "TextSink object" "DisplayText" "@DEF@"
.FD 0
void DisplayText(\fIw\fP, \fIx\fP, \fIy\fP, \fIpos1\fP, \fIpos2\fP, \fIhighlight\fP)
.br
      Widget \fIw\fP;
.br
      Position \fIx\fP, \fIy\fP;
.br
      XawTextPosition \fIpos1\fP, \fIpos2\fP;
.br
      Boolean \fIhighlight\fP;
.FN
.IP \fIw\fP 1i
Specifies the TextSink object.
.IP \fIx\fP 1i
Specifies the x location to start drawing the text.
.IP \fIy\fP 1i
Specifies the y location to start drawing text.
.IP \fIpos1\fP 1i
Specifies the location within the text source of the first character
to be printed.
.IP \fIpos2\fP 1i
Specifies the location within the text source of the last character
to be printed.
.IP \fIhighlight\fP 1i
Specifies whether or not to paint the text region highlighted.
.LP
The Text widget will only pass one line at a time to the text sink, so
this function does not need to know how to line feed the text.  It is
acceptable for this function to just ignore Carriage Returns.  \fIx\fP
and \fIy\fP denote the upper left hand corner of the first character to
be displayed.
.NH 4
Displaying the Insert Point
.LP
The function that controls the display of the text cursor is
\fBInsertCursor\fP.  This function will be called whenever the text
widget desires to change the state of, or move the insert point.
.FD 0
void InsertCursor(\fIw\fP, \fIx\fP, \fIy\fP, \fIstate\fP)
.IN "TextSink object" "InsertCursor" "@DEF@"
.br
      Widget \fIw\fP;
.br
      Position \fIx\fP, \fIy\fP;
.br
      XawTextInsertState \fIstate\fP;
.FN
.IP \fIw\fP 1i
Specifies the TextSink object.
.IP \fIx\fP 1i
Specifies the x location of the cursor in Pixels.
.IP \fIy\fP 1i
Specifies the y location of the cursor in Pixels.
.IP \fIstate\fP 1i
Specifies the state of the cursor, may be one of \fBXawisOn\fP or
\fBXawisOff\fP.
.LP
\fIX\fP and \fIy\fP denote the upper left hand corner of the insert point.
.NH 4
Clearing Portions of the Text window
.LP
To clear a portion of the Text window to its background color, the Text
widget will call \fBClearToBackground\fP.  The TextSink object already
defines this function as calling \fBXClearArea\fP on the region passed.
This behavior will be used if you specify
\fBXtInheritClearToBackground\fP for this method.
.IN "XtInheritClearToBackground" ""
.IN "TextSink object" "ClearToBackground" "@DEF@"
.FD 0
void ClearToBackground(\fIw\fP, \fIx\fP, \fIy\fP, \fIwidth\fP, \fIheight\fP)
.br
      Widget \fIw\fP;
.br
      Position \fIx\fP, \fIy\fP;
.br
      Dimension \fIwidth\fP, \fIheight\fP;
.FN
.IP \fIw\fP 1i
Specifies the TextSink object.
.IP \fIx\fP 1i
Specifies the x location, in pixels, of the Region to clear.
.IP \fIy\fP 1i
Specifies the y location, in pixels, of the Region to clear.
.IP \fIwidth\fP 1i
Specifies the width, in pixels, of the Region to clear.
.IP \fIheight\fP 1i
Specifies the height, in pixels, of the Region to clear.
.LP
\fIX\fP and \fIy\fP denote the upper left hand corner of region to clear.
.NH 4
Finding a Text Position Given Pixel Values
.LP
To find the text character position that will be rendered at a given x
location the Text widget uses the function \fBFindPosition\fP:
.IN "TextSink object" "FindPosition" "@DEF@"
.FD 0
void FindPosition(\fIw\fP, \fIfromPos\fP, \fIfromX\fP, \fIwidth\fP, \fIstopAtWordBreak\fP, \fIpos_return\fP, \fIwidth_return\fP, \fIheight_return\fP)
.br
      Widget \fIw\fP;
.br
      XawTextPosition \fIfromPos\fP;
.br
      int \fIfromX\fP, \fIwidth\fP;
.br
      Boolean \fIstopAtWordBreak\fP;
.br
      XawTextPosition \fI*pos_return\fP;
.br
      int \fI*width_return\fP, \fI*height_return\fP;
.FN
.IP \fIw\fP 1.25i
Specifies the TextSink object.
.IP \fIfromPos\fP 1.25i
Specifies a reference position, usually the first character in this line.
This character is always to the left of the desired character location.
.IP \fIfromX\fP 1.25i
Specifies the distance that the left edge of \fIfromPos\fP is from the
left edge of the window.  This is the reference x location for the
reference position.
.IP \fIwidth\fP 1.25i
Specifies the distance, in pixels, from the reference position to the
desired character position.
.IP \fIstopAtWordBreak\fP 1.25i
Specifies whether or not the position that is returned should be forced
to be on a word boundary.
.IP \fIpos_return\fP 1.25i
Returns the character position that corresponds to the location that has
been specified, or the work break immediately to the left of the
position if \fIstopAtWordBreak\fP is \fBTrue\fP.
.IP \fIwidth_return\fP 1.25i
Returns the actual distance between \fIfromPos\fP and \fIpos_return\fI.
.IP \fIheight_return\fP 1.25i
Returns the maximum height of the text between \fIfromPos\fP and
\fIpos_return\fI.
.LP
This function need make no attempt to deal with line feeds.  The text
widget will only call it one line at a time.
.LP
.sp
Another means of finding a text position is provided by the \fBResolve\fP
function:
.IN "TextSink object" "Resolve" "@DEF@"
.FD 0
void Resolve(\fIw\fP, \fIfromPos\fP, \fIfromX\fP, \fIwidth\fP, \fIpos_return\fP)
.br
      Widget \fIw\fP;
.br
      XawTextPosition \fIfromPos\fP;
.br
      int \fIfromX\fP, \fIwidth\fP;
.br
      XawTextPosition \fI*pos_return\fP;
.FN
.IP \fIw\fP 1i
Specifies the TextSink object.
.IP \fIfromPos\fP 1i
Specifies a reference position, usually the first character in this line.
This character is always to the left of the desired character location.
.IP \fIfromX\fP 1i
Specifies the distance that the left edge of \fIfromPos\fP is from the
left edge of the window.  This is the reference x location for the
reference position.
.IP \fIwidth\fP 1i
Specifies the distance, in pixels, from the reference position to the
desired character position.
.IP \fIpos_return\fP 1i
Returns the character position that corresponds to the
location that has been specified, or the word break immediately to the left
if \fIstopAtWordBreak\fP is \fBTrue\fP.
.LP
This function need make no attempt to deal with line feeds.  The text
widget will only call it one line at a time.  This is a more convenient
interface to the \fBFindPosition\fP function, and provides a subset of its
functionality.
.IN "FindPosition" ""
.NH 4
Finding the Distance Between two Text Positions
.LP
To find the distance in pixels between two text positions on the same
line use the function \fBFindDistance\fP.
.IN "TextSink object" "FindDistance" "@DEF@"
.FD 0
void FindDistance(\fIw\fP, \fIfromPos\fP, \fIfromX\fP, \fItoPos\fP, \fIwidth_return\fP, \fIpos_return\fP, \fIheight_return\fP)
.br
      Widget \fIw\fP;
.br
      XawTextPosition \fIfromPos\fP, \fItoPos\fP;
.br
      int \fIfromX\fP;
.br
      XawTextPosition \fI*pos_return\fP;
.br
      int \fI*width_return\fP, \fI*height_return\fP;
.FN
.IP \fIw\fP 1i
Specifies the TextSink object.
.IP \fIfromPos\fP 1i
Specifies the text buffer position, in characters, of the first position.
.IP \fIfromX\fP 1i
Specifies the distance that the left edge of \fIfromPos\fP is from the
left edge of the window.  This is the reference x location for the
reference position.
.IP \fItoPos\fP 1i
Specifies the text buffer position, in characters, of the second position.
.IP \fIresWidth\fP 1i
Return the actual distance between \fIfromPos\fP
and \fIpos_return\fI.
.IP \fIresPos\fP 1i
Returns the character position that corresponds to the actual character
position used for \fItoPos\fP in the calculations.  This may be
different than \fItoPos\fP, for example if \fIfromPos\fP and \fItoPos\fP
are on different lines in the file.
.IP \fIheight_return\fP 1i
Returns the maximum height of the text between \fIfromPos\fP and
\fIpos_return\fP.
.LP
This function need make no attempt to deal with line feeds.  The Text
widget will only call it one line at a time.
.NH 4
Finding the Size of the Drawing area
.LP
To find the maximum number of lines that will fit into the current Text
widget, use the function \fBMaxLines\fP.  The TextSink already defines
this function to compute the maximum number of lines by using the height
of \fBfont\fP.
.IN "TextSink object" "MaxLines" "@DEF@"
.FD 0
int MaxLines(\fIw\fP, \fIheight\fP)
.br
      Widget \fIw\fP;
.br
      Dimension \fIheight\fP;
.FN
.IP \fIw\fP 1i
Specifies the TextSink object.
.IP \fIheight\fP 1i
Specifies the height of the current drawing area.
.LP
Returns the maximum number of lines that will fit in \fIheight\fP.
.LP
.sp
To find the height required for a given number of text lines, use
the function \fBMaxHeight\fP.  The TextSink already defines this
function to compute the maximum height of the window by using the
height of \fBfont\fP.
.IN "TextSink object" "MaxHeight" "@DEF@"
.FD 0
int MaxHeight(\fIw\fP, \fIlines\fP)
.br
      Widget \fIw\fP;
.br
      int \fIlines\fP;
.FN
.IP \fIw\fP 1i
Specifies the TextSink object.
.IP \fIheight\fP 1i
Specifies the height of the current drawing area.
.LP
Returns the height that will be taken up by the number of lines passed.
.NH 4
Setting the Tab Stops
.LP
To set the tab stops for a text sink use the \fBSetTabs\fP function.
The TextSink already defines this function to set the tab x location in
pixels to be the number of characters times the figure width of
\fBfont\fP.
.IN "TextSink object" "SetTabs" "@DEF@"
.FD 0
void SetTabs(\fIw\fP, \fItab_count\fP, \fItabs\fP)
.br
      Widget \fIw\fP;
.br
      int \fItab_count\fP, \fI*tabs\fP;
.FN
.IP \fIw\fP 1i
Specifies the TextSink object.
.IP \fItab_count\fP 1i
Specifies the number of tabs passed in \fItabs\fP.
.IP \fItabs\fP 1i
Specifies the position, in characters, of the tab stops.
.LP
This function is responsible for the converting character positions passed
to it into whatever internal positions the TextSink uses for tab placement.
.NH 4
Getting the Insert Point's Size and Location
.LP
To get the size and location of the insert point use the
\fBGetCursorBounds\fP function.
.IN "TextSink object" "GetCursorBounds" "@DEF@"
.FD 0
void GetCursorBounds(\fIw\fP, \fIrect_return\fP)
.br
Widget \fIw\fP;
.br
XRectangle \fI*rect_return\fP;
.FN
.IP \fIw\fP 1i
Specifies the TextSinkObject.
.IP \fIrect_return\fP 1i
Returns the location and size of the insert point.
.LP
\fIRect\fP will be filled with the current size and location of the
insert point.