1<sect1 id="TextSrc_Object">
2<title>TextSrc Object</title>
3<literallayout class="monospaced">
4Application Header file &lt;X11/Xaw/TextSrc.h&gt;
5Class Header file       &lt;X11/Xaw/TextSrcP.h&gt;
6Class                   textSrcObjectClass
7Class Name              TextSrc
8Superclass              Object
9</literallayout>
10
11<para>
12<!-- .LP -->
13The TextSrc object is the root object for all text sources.  Any new text
14source objects should be subclasses of the TextSrc Object.  The
15TextSrc Class contains all methods the Text widget expects a text
16source to export.
17</para>
18
19<para>
20<!-- .LP -->
21Since all text sources will have some resources in common the
22TextSrc defines a few new resources.
23</para>
24
25<sect2 id='TextSource::Resources'>
26<title>Resources</title>
27<para>
28When creating an TextSrc object instance, the following resources are
29retrieved from the argument list or from the resource database:
30</para>
31
32<informaltable>
33  <tgroup cols='5' align='center'>
34  <colspec colname='c1'/>
35  <colspec colname='c2'/>
36  <colspec colname='c3'/>
37  <colspec colname='c4'/>
38  <colspec colname='c5'/>
39  <thead>
40    <row>
41      <entry>Name</entry>
42      <entry>Class</entry>
43      <entry>Type</entry>
44      <entry>Notes</entry>
45      <entry>Default Value</entry>
46    </row>
47  </thead>
48  <tbody>
49    <row>
50      <entry>destroyCallback</entry>
51      <entry>Callback</entry>
52      <entry>XtCallbackList</entry>
53      <entry></entry>
54      <entry>NULL</entry>
55    </row>
56    <row>
57      <entry>editType</entry>
58      <entry>EditType</entry>
59      <entry>EditMode</entry>
60      <entry></entry>
61      <entry>NULL</entry>
62    </row>
63  </tbody>
64  </tgroup>
65</informaltable>
66</sect2>
67
68<sect2 id="Subclassing_the_TextSrc">
69<title>Subclassing the TextSrc</title>
70<para>
71The only purpose of the TextSrc Object is to be subclassed.  It contains
72the minimum set of class methods that all text sources must have.  All
73class methods of the TextSrc must be defined, as the Text widget uses
74them all.  While all may be inherited, the direct descendant of TextSrc
75<function>must</function> specify some of them as TextSrc does not contain enough
76information to be a valid text source by itself.  Do not try to use the
77TextSrc as a valid source for the Text widget; it is not intended to be
78used as a source by itself and bad things will probably happen.
79</para>
80
81<informaltable>
82  <tgroup cols='4' align='center'>
83  <colspec colname='c1'/>
84  <colspec colname='c2'/>
85  <colspec colname='c3'/>
86  <colspec colname='c4'/>
87  <thead>
88    <row>
89      <entry>Function</entry>
90      <entry>Inherit with</entry>
91      <entry>Public Interface</entry>
92      <entry>must specify</entry>
93    </row>
94  </thead>
95  <tbody>
96    <row>
97      <entry>Read</entry>
98      <entry>XtInheritRead</entry>
99      <entry>XawTextSourceRead</entry>
100      <entry>yes</entry>
101    </row>
102    <row>
103      <entry>Replace</entry>
104      <entry>XtInheritReplace</entry>
105      <entry>XawTextSourceReplace</entry>
106      <entry>no</entry>
107    </row>
108    <row>
109      <entry>Scan</entry>
110      <entry>XtInheritScan</entry>
111      <entry>XawTextSourceScan</entry>
112      <entry>yes</entry>
113    </row>
114    <row>
115      <entry>Search</entry>
116      <entry>XtInheritSearch</entry>
117      <entry>XawTextSourceSearch</entry>
118      <entry>no</entry>
119    </row>
120    <row>
121      <entry>SetSelection</entry>
122      <entry>XtInheritSetSelection</entry>
123      <entry>XawTextSourceSetSelection</entry>
124      <entry>no</entry>
125    </row>
126    <row>
127      <entry>ConvertSelection</entry>
128      <entry>XtInheritConvertSelection</entry>
129      <entry>XawTextSourceConvertSelection</entry>
130      <entry>no</entry>
131    </row>
132  </tbody>
133  </tgroup>
134</informaltable>
135
136<sect3 id='Reading_Text'>
137<title>Reading Text.</title>
138<para>
139<!-- .LP -->
140To read the text in a text source use the <xref linkend='Read' xrefstyle='select: title'/> function:
141<indexterm significance="preferred"><primary>TextSrc object</primary><secondary>Read</secondary></indexterm>
142</para>
143<funcsynopsis id='Read'>
144<funcprototype>
145  <funcdef>XawTextPosition<function> Read</function></funcdef>
146  <paramdef>Widget<parameter> w</parameter></paramdef>
147  <paramdef>XawTextPosition<parameter> pos</parameter></paramdef>
148  <paramdef>XawTextBlock<parameter> *text_return</parameter></paramdef>
149  <paramdef>int<parameter> length</parameter></paramdef>
150</funcprototype>
151</funcsynopsis>
152
153<!-- .FN -->
154<variablelist>
155  <varlistentry>
156    <term>
157      <emphasis remap='I'>w</emphasis>
158    </term>
159    <listitem>
160      <para>
161Specifies the TextSrc object.
162      </para>
163    </listitem>
164  </varlistentry>
165  <varlistentry>
166    <term>
167      <emphasis remap='I'>pos</emphasis>
168    </term>
169    <listitem>
170      <para>
171Specifies the position of the first character to be read from the text buffer.
172      </para>
173    </listitem>
174  </varlistentry>
175  <varlistentry>
176    <term><emphasis remap='I'>text</emphasis></term>
177    <listitem>
178      <para>
179Returns the text read from the source.
180      </para>
181    </listitem>
182  </varlistentry>
183  <varlistentry>
184    <term>
185      <emphasis remap='I'>length</emphasis>
186    </term>
187    <listitem>
188      <para>
189Specifies the maximum number of characters the TextSrc should
190return to the application in <emphasis remap='I'>text_return</emphasis>.
191      </para>
192    </listitem>
193  </varlistentry>
194</variablelist>
195
196<para>
197This function returns the text position immediately after the
198characters read from the
199text buffer.  The function is not required to read <emphasis remap='I'>length</emphasis>
200characters if that many characters are in the file, it may break at
201any point that is convenient to the internal structure of the
202source.  It may take several calls to <xref linkend='Read' xrefstyle='select: title'/> before the desired
203portion of the text buffer is fully retrieved.
204</para>
205</sect3>
206
207<sect3 id='TextSource::Replacing_Text'>
208<title>Replacing Text.</title>
209<para>
210To replace or edit the text in a text buffer use the <xref linkend='Replace' xrefstyle='select: title'/> function:
211</para>
212
213<funcsynopsis id='Replace'>
214<funcprototype>
215  <funcdef>XawTextPosition<function> Replace</function></funcdef>
216  <paramdef>Widget<parameter> w</parameter></paramdef>
217  <paramdef>XawTextPositionstart,<parameter> end</parameter></paramdef>
218  <paramdef>XawTextBlock<parameter> *text</parameter></paramdef>
219</funcprototype>
220</funcsynopsis>
221
222<variablelist>
223  <varlistentry>
224    <term><emphasis remap='I'>w</emphasis></term>
225    <listitem>
226      <para>
227Specifies the TextSrc object.
228      </para>
229    </listitem>
230  </varlistentry>
231  <varlistentry>
232    <term><emphasis remap='I'>start</emphasis></term>
233    <listitem>
234      <para>
235Specifies the position of the first character to be removed from the text
236buffer.  This is also the location to begin inserting the new text.
237      </para>
238    </listitem>
239  </varlistentry>
240  <varlistentry>
241    <term><emphasis remap='I'>end</emphasis></term>
242    <listitem>
243      <para>
244Specifies the position immediately after the last character to be
245removed from the text buffer.
246      </para>
247    </listitem>
248  </varlistentry>
249  <varlistentry>
250    <term><emphasis remap='I'>text</emphasis></term>
251    <listitem>
252      <para>
253Specifies the text to be added to the text source.
254      </para>
255    </listitem>
256  </varlistentry>
257</variablelist>
258
259<para>
260This function can return any of the following values:
261</para>
262
263<variablelist>
264  <varlistentry>
265    <term><function>XawEditDone</function></term>
266    <listitem>
267      <para>
268The text replacement was successful.
269      </para>
270    </listitem>
271  </varlistentry>
272  <varlistentry>
273    <term><function>XawPositionError</function></term>
274    <listitem>
275      <para>
276<indexterm><primary>XawPositionError</primary></indexterm>
277The edit mode is <function>XawtextAppend</function> and <function>start</function> is not the last
278character of the source.
279      </para>
280    </listitem>
281  </varlistentry>
282  <varlistentry>
283    <term><function>XawEditError</function></term>
284    <listitem>
285      <para>
286<indexterm><primary>XawEditError</primary></indexterm>
287Either the Source was read-only or the range to be deleted is larger
288than the length of the Source.
289      </para>
290    </listitem>
291  </varlistentry>
292</variablelist>
293
294<para>
295<!-- .LP -->
296The <xref linkend='Replace' xrefstyle='select: title'/> arguments <function>start</function> and <function>end</function> represent the
297text source character positions for the existing text that is to be
298replaced by the text in the text block.  The characters from
299<emphasis remap='I'>start</emphasis> up to but not including <emphasis remap='I'>end</emphasis> are deleted, and the
300buffer specified by the text block is inserted in their
301place.  If <emphasis remap='I'>start</emphasis> and <emphasis remap='I'>end</emphasis> are equal, no text is deleted and
302the new text is inserted after <emphasis remap='I'>start</emphasis>.
303</para>
304</sect3>
305
306<sect3 id="Scanning_the_TextSrc">
307<title>Scanning the TextSrc</title>
308<para>
309To search the text source for one of the predefined boundary types use
310the <xref linkend='Scan' xrefstyle='select: title'/> function:
311</para>
312
313<funcsynopsis id='Scan'>
314<funcprototype>
315  <funcdef>XawTextPosition<function> Scan</function></funcdef>
316  <paramdef>Widget<parameter> w</parameter></paramdef>
317  <paramdef>XawTextPosition<parameter> position</parameter></paramdef>
318  <paramdef>XawTextScanType<parameter> type</parameter></paramdef>
319  <paramdef>XawTextScanDirection<parameter> dir</parameter></paramdef>
320  <paramdef>int<parameter> count</parameter></paramdef>
321  <paramdef>Boolean<parameter> include</parameter></paramdef>
322</funcprototype>
323</funcsynopsis>
324
325
326<variablelist>
327  <varlistentry>
328    <term><emphasis remap='I'>w</emphasis></term>
329    <listitem>
330      <para>
331Specifies the TextSrc object.
332      </para>
333    </listitem>
334  </varlistentry>
335  <varlistentry>
336    <term><emphasis remap='I'>position</emphasis></term>
337    <listitem>
338      <para>
339Specifies the position to begin scanning the source.
340      </para>
341    </listitem>
342  </varlistentry>
343  <varlistentry>
344    <term><emphasis remap='I'>type</emphasis></term>
345    <listitem>
346      <para>
347Specifies the type of boundary to scan for, may be one of:
348<function>XawstPosition</function>, <function>XawstWhiteSpace</function>, <function>XawstEOL</function>,
349<function>XawstParagraph</function>, <function>XawstAll</function>.  The exact meaning of these
350boundaries is left up to the individual text source.
351      </para>
352    </listitem>
353  </varlistentry>
354  <varlistentry>
355    <term><emphasis remap='I'>dir</emphasis></term>
356    <listitem>
357      <para>
358Specifies the direction to scan, may be either <function>XawsdLeft</function> to search
359<indexterm><primary>XawsdLeft</primary></indexterm>
360backward, or <function>XawsdRight</function> to search forward.
361<indexterm><primary>XawsdRight</primary></indexterm>
362      </para>
363    </listitem>
364  </varlistentry>
365  <varlistentry>
366    <term><emphasis remap='I'>count</emphasis></term>
367    <listitem>
368      <para>
369Specifies the number of boundaries to scan for.
370      </para>
371    </listitem>
372  </varlistentry>
373  <varlistentry>
374    <term><emphasis remap='I'>include</emphasis></term>
375    <listitem>
376      <para>
377Specifies whether the boundary itself should be included in the scan.
378      </para>
379    </listitem>
380  </varlistentry>
381</variablelist>
382
383<para>
384<!-- .LP -->
385The <xref linkend='Scan' xrefstyle='select: title'/> function returns the position in the text source of the desired
386boundary.  It is expected to return a valid address for
387all calls made to it, thus if a particular request is made that would take
388the text widget beyond the end of the source it must return the
389position of that end.
390</para>
391</sect3>
392
393<sect3 id="Searching_through_a_TextSrc">
394<title>Searching through a TextSrc</title>
395<para>
396To search for a particular string use the <xref linkend='Search' xrefstyle='select: title'/> function.
397</para>
398
399<funcsynopsis id='Search'>
400<funcprototype>
401  <funcdef>XawTextPosition<function> Search</function></funcdef>
402  <paramdef>Widget<parameter> w</parameter></paramdef>
403  <paramdef>XawTextPosition<parameter> position</parameter></paramdef>
404  <paramdef>XawTextScanDirection<parameter> dir</parameter></paramdef>
405  <paramdef>XawTextBlock<parameter> *text</parameter></paramdef>
406</funcprototype>
407</funcsynopsis>
408
409<variablelist>
410  <varlistentry>
411    <term><emphasis remap='I'>w</emphasis></term>
412    <listitem>
413      <para>
414Specifies the TextSrc object.
415      </para>
416    </listitem>
417  </varlistentry>
418  <varlistentry>
419    <term><emphasis remap='I'>position</emphasis></term>
420    <listitem>
421      <para>
422Specifies the position to begin the search.
423      </para>
424    </listitem>
425  </varlistentry>
426  <varlistentry>
427    <term><emphasis remap='I'>dir</emphasis></term>
428    <listitem>
429      <para>
430Specifies the direction to search, may be either <function>XawsdLeft</function> to search
431<indexterm><primary>XawsdLeft</primary></indexterm>
432backward, or <function>XawsdRight</function> to search forward.
433<indexterm><primary>XawsdRight</primary></indexterm>
434      </para>
435    </listitem>
436  </varlistentry>
437  <varlistentry>
438    <term><emphasis remap='I'>text</emphasis></term>
439    <listitem>
440      <para>
441Specifies a text block containing the text to search for.
442      </para>
443    </listitem>
444  </varlistentry>
445</variablelist>
446
447<para>
448This function will search through the text buffer attempting to find a
449match for the string in the text block.  If a match is found in the
450direction specified, then the character location of the first character
451in the string is returned.  If no text was found then
452<function>XawTextSearchError</function> is returned.
453</para>
454
455</sect3>
456
457<sect3 id="Text_Selections">
458<title>Text Selections</title>
459
460<para>
461<!-- .LP -->
462While many selection types are handled by the Text widget, text sources
463may have selection types unknown to the Text widget.  When a selection
464conversion is requested by the X server the Text widget will first call
465the <function>ConvertSelection</function> function, to attempt the selection
466conversion.
467</para>
468
469<funcsynopsis id='ConvertSelections'>
470<funcprototype>
471  <funcdef>Boolean<function> ConvertSelections</function></funcdef>
472  <paramdef>Widget<parameter> w</parameter></paramdef>
473  <paramdef>Atom*selection,*target,<parameter> *type</parameter></paramdef>
474  <paramdef>caddr_t<parameter> *value_return</parameter></paramdef>
475  <paramdef>unsignedlong<parameter> *length_return</parameter></paramdef>
476  <paramdef>int<parameter> *format_return</parameter></paramdef>
477</funcprototype>
478</funcsynopsis>
479
480<variablelist>
481  <varlistentry>
482    <term>
483      <emphasis remap='I'>w</emphasis>
484    </term>
485    <listitem>
486      <para>
487Specifies the TextSrc object.
488      </para>
489    </listitem>
490  </varlistentry>
491  <varlistentry>
492    <term>
493      <emphasis remap='I'>selection</emphasis>
494    </term>
495    <listitem>
496      <para>
497Specifies the type of selection that was requested (e.g. <function>PRIMARY</function>).
498      </para>
499    </listitem>
500  </varlistentry>
501  <varlistentry>
502    <term>
503      <emphasis remap='I'>target</emphasis>
504    </term>
505    <listitem>
506      <para>
507Specifies the type of the selection that has been requested, which
508indicates the desired information about the selection (e.g. Filename,
509Text, Window).
510      </para>
511    </listitem>
512  </varlistentry>
513  <varlistentry>
514    <term>
515      <emphasis remap='I'>type</emphasis>
516    </term>
517    <listitem>
518      <para>
519Specifies a pointer to the atom into which the property type of the converted
520value of the selection is to be stored.  For instance, either file
521name or text might have property type <function>XA_STRING</function>.
522      </para>
523    </listitem>
524  </varlistentry>
525  <varlistentry>
526    <term>
527      <emphasis remap='I'>value_return</emphasis>
528    </term>
529    <listitem>
530      <para>
531Returns a pointer into which a pointer to the converted value of the
532selection
533is to be stored.  The selection owner is responsible for allocating
534this storage.  The memory is considered owned by the toolkit, and is
535freed by XtFree when the Intrinsics selection mechanism is done with it.
536      </para>
537    </listitem>
538  </varlistentry>
539  <varlistentry>
540    <term>
541      <emphasis remap='I'>length_return</emphasis>
542    </term>
543    <listitem>
544      <para>
545Returns a pointer into which the number of elements in value is to be stored.
546The size of each element is determined by <emphasis remap='I'>format</emphasis>.
547      </para>
548    </listitem>
549  </varlistentry>
550  <varlistentry>
551    <term>
552      <emphasis remap='I'>format_return</emphasis>
553    </term>
554    <listitem>
555      <para>
556Returns a pointer into which the size in bits of the data elements of the
557selection value is to be stored.
558      </para>
559    </listitem>
560  </varlistentry>
561</variablelist>
562
563<para>
564If this function returns <function>True</function> then the Text widget will assume
565that the source has taken care of converting the selection, Otherwise the
566Text widget will attempt to convert the selection itself.
567</para>
568
569<para>
570If the source needs to know when the text selection is modified it
571should define a <xref linkend='SetSelection' xrefstyle='select: title'/> procedure:
572</para>
573
574<funcsynopsis id='SetSelection'>
575<funcprototype>
576  <funcdef>void<function> SetSelection</function></funcdef>
577  <paramdef>Widget<parameter> w</parameter></paramdef>
578  <paramdef>XawTextPositionstart,<parameter> end</parameter></paramdef>
579  <paramdef>Atom<parameter> selection</parameter></paramdef>
580</funcprototype>
581</funcsynopsis>
582
583<variablelist>
584  <varlistentry>
585    <term><emphasis remap='I'>w</emphasis></term>
586    <listitem>
587      <para>
588Specifies the TextSrc object.
589      </para>
590    </listitem>
591  </varlistentry>
592  <varlistentry>
593    <term><emphasis remap='I'>start</emphasis></term>
594    <listitem>
595      <para>
596Specifies the character position of the beginning of the new text selection.
597      </para>
598    </listitem>
599  </varlistentry>
600  <varlistentry>
601    <term><emphasis remap='I'>end</emphasis></term>
602    <listitem>
603      <para>
604Specifies the character position of the end of the new text selection.
605      </para>
606    </listitem>
607  </varlistentry>
608  <varlistentry>
609    <term><emphasis remap='I'>selection</emphasis></term>
610    <listitem>
611      <para>
612Specifies the type of selection that was requested (e.g. <function>PRIMARY</function>).
613      </para>
614    </listitem>
615  </varlistentry>
616</variablelist>
617
618</sect3>
619</sect2>
620</sect1>
621