1<sect1 id="Ascii_Source_Object_and_Multi_Source_Object">
2<title>Ascii Source Object and Multi Source Object</title>
3<para>
4<!-- .LP -->
5<!-- .XS -->
6<!-- 	AsciiSrc Object -->
7<!-- .XE -->
8<indexterm significance="preferred"><primary>AsciiSrc object</primary></indexterm>
9</para>
10<para>
11<!-- .LP -->
12<literallayout class="monospaced">
13<!-- .TA 2.0i -->
14<!-- .ta 2.0i -->
15Application Header file	&lt;X11/Xaw/AsciiSrc.h&gt; or &lt;X11/Xaw/MultiSrc.h&gt;
16<indexterm><primary>AsciiSrc.h</primary></indexterm>
17Class Header file	&lt;X11/Xaw/AsciiSrcP.h&gt; or  &lt;X11/Xaw/MultiSrcP.h&gt;
18<indexterm><primary>AsciiSrcP.h</primary></indexterm>
19Class		asciiSrcObjectClass or multiSrcObjectClass
20<indexterm><primary>asciiSrcObjectClass</primary></indexterm>
21Class Name	AsciiSrc or MultiSrc
22<indexterm><primary>AsciiSrc object</primary><secondary>class name</secondary></indexterm>
23Superclass	TextSource
24</literallayout>
25</para>
26<para>
27<!-- .LP -->
28The AsciiSrc or MultiSrc object is used by a text widget to read the text from a
29file or string in memory.  Depending on its <function>international</function> resource, an
30AsciiText widget will create one or the other of these when the AsciiText
31itself is created.  Both types are nearly identical; the following discussion
32applies to both, with MultiSrc differences noted only as they occur.
33</para>
34<para>
35<!-- .LP -->
36The AsciiSrc understands all Latin1 characters plus Tab and Carriage Return.
37<emphasis remap='I'>The MultiSrc understands any set of character sets that
38the underlying X implementation's internationalization handles.</emphasis>
39</para>
40<para>
41<!-- .LP -->
42The AsciiSrc can be either of two types: <function>XawAsciiFile</function>
43or <function>XawAsciiString</function>.
44</para>
45<para>
46<!-- .LP -->
47AsciiSrc objects of type <function>XawAsciiFile</function> read the text from a file and
48store it
49into an internal buffer.  This buffer may then be modified, provided the
50text widget is in the correct edit mode, just as if it were a source of
51type <function>XawAsciiString</function>.  Unlike R3 and earlier versions of the AsciiSrc,
52it is now possible to specify an editable disk source.  The file is not
53updated, however, until a call to <xref linkend='XawAsciiSave' xrefstyle='select: title'/> is made.  When the
54source is in this mode the <function>useStringInPlace</function> resource is ignored.
55</para>
56<para>
57<!-- .LP -->
58AsciiSrc objects of type <function>XawAsciiString</function> have the text buffer
59implemented as a string.
60<emphasis remap='I'>MultiSrc objects of type <function>XawAsciiString</function>
61have the text buffer implemented as a wide character string.</emphasis>
62The string owner is responsible for allocating and managing storage for the
63string.
64</para>
65<para>
66<!-- .LP -->
67In the default case for AsciiSrc objects of type <function>XawAsciiString</function>,
68the resource <function>useStringInPlace</function> is false,
69and the widget owns the string.  The initial value of the
70string resource, and any update made by the application
71programmer to the string resource with <xref linkend='XtSetValues' xrefstyle='select: title'/>, is copied
72into memory private to the widget, and managed internally by the widget.
73The application writer
74does not need to worry about running out of buffer space
75(subject to the total memory available to the application).
76The performance does not decay linearly as the buffer grows
77large, as is necessarily the case when the text buffer is used
78in place.   The application writer must use <xref linkend='XtGetValues' xrefstyle='select: title'/> to
79determine the contents of the text buffer, which will return
80a copy of the widget's text buffer as
81it existed at the time of the <xref linkend='XtGetValues' xrefstyle='select: title'/> call.   This copy
82is not affected by subsequent updates to the text buffer, i.e.,
83it is not updated as the user types input into the text buffer.
84This copy is freed upon the next call to XtGetValues to
85retrieve the string resource; however, to conserve memory,
86there is a convenience routine, <xref linkend='XawAsciiSourceFreeString' xrefstyle='select: title'/>, allowing the
87application programmer to direct the widget to free the copy.
88</para>
89<para>
90<!-- .LP -->
91When the resource <function>useStringInPlace</function> is true and the AsciiSrc object
92is of type <function>XawAsciiString</function>, the application
93is the string owner.  The widget will take the value
94of the string resource as its own text buffer, and the <function>length</function>
95resource indicates the buffer size.   In this case
96the buffer contents change as the user types at the widget;
97it is not necessary to call <xref linkend='XtGetValues' xrefstyle='select: title'/> on the string
98resource to determine the contents of the buffer-it will
99simply return the address of the application's implementation
100of the text buffer.
101</para>
102<sect2 id='AsciiSource::Resources'>
103<title>Resources</title>
104<para>
105<!-- .LP -->
106When creating an AsciiSrc object instance, the following resources are
107retrieved from the argument list or from the resource database:
108</para>
109<para>
110<!-- .LP -->
111<indexterm><primary>AsciiSrc object</primary><secondary>resources</secondary></indexterm>
112<informaltable>
113  <tgroup cols='5' align='center'>
114  <colspec colname='c1'/>
115  <colspec colname='c2'/>
116  <colspec colname='c3'/>
117  <colspec colname='c4'/>
118  <colspec colname='c5'/>
119  <thead>
120    <row>
121      <entry>Name</entry>
122      <entry>Class</entry>
123      <entry>Type</entry>
124      <entry>Notes</entry>
125      <entry>Default Value</entry>
126    </row>
127  </thead>
128  <tbody>
129    <row>
130      <entry>callback</entry>
131      <entry>Callback</entry>
132      <entry>XtCallbackList</entry>
133      <entry></entry>
134      <entry>NULL</entry>
135    </row>
136    <row>
137      <entry>dataCompression</entry>
138      <entry>DataCompression</entry>
139      <entry>Boolean</entry>
140      <entry></entry>
141      <entry>True</entry>
142    </row>
143    <row>
144      <entry>destroyCallback</entry>
145      <entry>Callback</entry>
146      <entry>Callback</entry>
147      <entry></entry>
148      <entry>NULL</entry>
149    </row>
150    <row>
151      <entry>editType</entry>
152      <entry>EditType</entry>
153      <entry>EditMode</entry>
154      <entry></entry>
155      <entry>XawtextRead</entry>
156    </row>
157    <row>
158      <entry>length</entry>
159      <entry>Length</entry>
160      <entry>Int</entry>
161      <entry>A</entry>
162      <entry>length of <function>string</function></entry>
163    </row>
164    <row>
165      <entry>pieceSize</entry>
166      <entry>PieceSize</entry>
167      <entry>Int</entry>
168      <entry></entry>
169      <entry>BUFSIZ</entry>
170    </row>
171    <row>
172      <entry>string</entry>
173      <entry>String</entry>
174      <entry>String</entry>
175      <entry></entry>
176      <entry>NULL</entry>
177    </row>
178    <row>
179      <entry>type</entry>
180      <entry>Type</entry>
181      <entry>AsciiType</entry>
182      <entry></entry>
183      <entry>XawAsciiString</entry>
184    </row>
185    <row>
186      <entry>useStringInPlace</entry>
187      <entry>UseStringInPlace</entry>
188      <entry>Boolean</entry>
189      <entry></entry>
190      <entry>False</entry>
191    </row>
192    <row>
193      <entry>_</entry>
194    </row>
195  </tbody>
196  </tgroup>
197</informaltable>
198<!-- .Oc Bold -->
199<!-- .Dc -->
200<!-- .Od Bold -->
201<!-- .Oe -->
202<!-- .Ol Bold -->
203<!-- .Op Bold -->
204<!-- .Os Bold -->
205<!-- .Ot Bold -->
206<!-- .Ou Bold -->
207</para>
208</sect2>
209<sect2 id='AsciiSource::Convenience_Routines'>
210<title>Convenience Routines</title>
211<para>
212<!-- .LP -->
213The AsciiSrc has a few convenience routines that allow the
214application programmer quicker or easier access to some of the
215commonly used functionality of the AsciiSrc.
216</para>
217<sect3 id="Conserving_Memory">
218<title>Conserving Memory</title>
219<para>
220<!-- .LP -->
221When the AsciiSrc widget is not in <function>useStringInPlace</function> mode
222space must be allocated whenever the file is saved, or the string is
223requested with a call to <xref linkend='XtGetValues' xrefstyle='select: title'/>.  This memory is allocated on the
224fly, and remains valid until the next time a string needs to be allocated.
225You may save memory by freeing this string as soon as you are done
226with it by calling <xref linkend='XawAsciiSourceFreeString' xrefstyle='select: title'/>.
227<funcsynopsis id='XawAsciiSourceFreeString'>
228<funcprototype>
229  <funcdef>void<function> XawAsciiSourceFreeString</function></funcdef>
230  <paramdef>Widget<parameter> w</parameter></paramdef>
231</funcprototype>
232</funcsynopsis>
233<!-- .FN -->
234<variablelist>
235  <varlistentry>
236    <term>
237      <emphasis remap='I'>w</emphasis>
238    </term>
239    <listitem>
240      <para>
241Specifies the AsciiSrc object.
242    </para>
243  </listitem>
244  </varlistentry>
245</variablelist>
246</para>
247<para>
248<!-- .LP -->
249This function will free the memory that contains the string pointer returned
250by <xref linkend='XtGetValues' xrefstyle='select: title'/>.  This will normally happen automatically when
251the next call to <xref linkend='XtGetValues' xrefstyle='select: title'/> occurs, or when the widget is destroyed.
252</para>
253</sect3>
254<sect3 id="Saving_Files">
255<title>Saving Files</title>
256<para>
257<!-- .LP -->
258To save the changes made in the current text source into a file use
259<xref linkend='XawAsciiSave' xrefstyle='select: title'/>.
260<funcsynopsis id='XawAsciiSave'>
261<funcprototype>
262  <funcdef>Boolean<function> XawAsciiSave</function></funcdef>
263  <paramdef>Widget<parameter> w</parameter></paramdef>
264</funcprototype>
265</funcsynopsis>
266<!-- .FN -->
267<variablelist>
268  <varlistentry>
269    <term>
270      <emphasis remap='I'>w</emphasis>
271    </term>
272    <listitem>
273      <para>
274Specifies the AsciiSrc object.
275    </para>
276  </listitem>
277  </varlistentry>
278</variablelist>
279</para>
280<para>
281<!-- .LP -->
282<xref linkend='XawAsciiSave' xrefstyle='select: title'/> returns <function>True</function> if the save was successful.
283It will update the file named in the <function>string</function> resource.
284If the buffer has not been changed, no action will be taken.  This function
285only works on an AsciiSrc of type <function>XawAsciiFile</function>.
286</para>
287<para>
288<!-- .LP -->
289<!-- .sp 1 -->
290To save the contents of the current text buffer into a named file use
291<xref linkend='XawAsciiSaveAsFile' xrefstyle='select: title'/>.
292<funcsynopsis id='XawAsciiSaveAsFile'>
293<funcprototype>
294  <funcdef>Boolean<function> XawAsciiSaveAsFile</function></funcdef>
295  <paramdef>Widget<parameter> w</parameter></paramdef>
296  <paramdef>String<parameter> name</parameter></paramdef>
297</funcprototype>
298</funcsynopsis>
299<!-- .FN -->
300<variablelist>
301  <varlistentry>
302    <term>
303      <emphasis remap='I'>w</emphasis>
304    </term>
305    <listitem>
306      <para>
307Specifies the AsciiSrc object.
308      </para>
309    </listitem>
310  </varlistentry>
311  <varlistentry>
312    <term>
313      <emphasis remap='I'>name</emphasis>
314    </term>
315    <listitem>
316      <para>
317The name of the file to save the current buffer into.
318    </para>
319  </listitem>
320  </varlistentry>
321</variablelist>
322</para>
323<para>
324<!-- .LP -->
325This function returns <function>True</function> if the save was successful.
326<xref linkend='XawAsciiSaveAsFile' xrefstyle='select: title'/> will work with a buffer of either type
327<function>XawAsciiString</function> or type <function>XawAsciiFile</function>.
328</para>
329</sect3>
330<sect3 id="Seeing_if_the_Source_has_Changed">
331<title>Seeing if the Source has Changed</title>
332<para>
333<!-- .LP -->
334To find out if the text buffer in an AsciiSrc object has changed
335since the last time it was saved with <xref linkend='XawAsciiSave' xrefstyle='select: title'/> or queried
336<indexterm><primary>XawAsciiSave</primary></indexterm>
337use <xref linkend='XawAsciiSourceChanged' xrefstyle='select: title'/>.
338<funcsynopsis id='XawAsciiSourceChanged'>
339<funcprototype>
340  <funcdef>Boolean<function> XawAsciiSourceChanged</function></funcdef>
341  <paramdef>Widget<parameter> w</parameter></paramdef>
342</funcprototype>
343</funcsynopsis>
344<!-- .FN -->
345<variablelist>
346  <varlistentry>
347    <term>
348      <emphasis remap='I'>w</emphasis>
349    </term>
350    <listitem>
351      <para>
352Specifies the AsciiSrc object.
353    </para>
354  </listitem>
355  </varlistentry>
356</variablelist>
357</para>
358<para>
359<!-- .LP -->
360This function will return <function>True</function> if the source has changed since
361the last time it was saved or queried.  The internal change flag is
362reset whenever the string is queried via <xref linkend='XtGetValues' xrefstyle='select: title'/> or the
363buffer is saved via <xref linkend='XawAsciiSave' xrefstyle='select: title'/>.
364
365</para>
366</sect3>
367</sect2>
368</sect1>
369