File: AsciiSource.xml

package info (click to toggle)
libxaw 2%3A1.0.13-1.1
  • links: PTS, VCS
  • area: main
  • in suites: bullseye, sid
  • size: 4,396 kB
  • sloc: ansic: 37,290; xml: 19,657; sh: 11,262; makefile: 297
file content (368 lines) | stat: -rw-r--r-- 12,121 bytes parent folder | download | duplicates (4)
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
<sect1 id="Ascii_Source_Object_and_Multi_Source_Object">
<title>Ascii Source Object and Multi Source Object</title>
<para>
<!-- .LP -->
<!-- .XS -->
<!-- 	AsciiSrc Object -->
<!-- .XE -->
<!-- .IN "AsciiSrc object" "" "@DEF@" -->
</para>
<para>
<!-- .LP -->
<literallayout class="monospaced">
<!-- .TA 2.0i -->
<!-- .ta 2.0i -->
Application Header file	&lt;X11/Xaw/AsciiSrc.h&gt; or &lt;X11/Xaw/MultiSrc.h&gt;
<!-- .IN "AsciiSrc.h" "" -->
Class Header file	&lt;X11/Xaw/AsciiSrcP.h&gt; or  &lt;X11/Xaw/MultiSrcP.h&gt;
<!-- .IN "AsciiSrcP.h" "" -->
Class		asciiSrcObjectClass or multiSrcObjectClass
<!-- .IN "asciiSrcObjectClass" "" -->
Class Name	AsciiSrc or MultiSrc
<!-- .IN "AsciiSrc object" "class name" -->
Superclass	TextSource
</literallayout>
</para>
<para>
<!-- .LP -->
The AsciiSrc or MultiSrc object is used by a text widget to read the text from a
file or string in memory.  Depending on its <function>international</function> resource, an
AsciiText widget will create one or the other of these when the AsciiText
itself is created.  Both types are nearly identical; the following discussion
applies to both, with MultiSrc differences noted only as they occur.
</para>
<para>
<!-- .LP -->
The AsciiSrc understands all Latin1 characters plus Tab
and Carriage Return.  \fIThe MultiSrc understands any set of character sets that
the underlying X implementation's internationalization handles.\fP
</para>
<para>
<!-- .LP -->
The AsciiSrc can be either of two types: <function>XawAsciiFile</function>
or <function>XawAsciiString</function>.
</para>
<para>
<!-- .LP -->
AsciiSrc objects of type <function>XawAsciiFile</function> read the text from a file and
store it
into an internal buffer.  This buffer may then be modified, provided the
text widget is in the correct edit mode, just as if it were a source of
type <function>XawAsciiString</function>.  Unlike R3 and earlier versions of the AsciiSrc,
it is now possible to specify an editable disk source.  The file is not
updated, however, until a call to <xref linkend='XawAsciiSave' xrefstyle='select: title'/> is made.  When the
source is in this mode the <function>useStringInPlace</function> resource is ignored.
</para>
<para>
<!-- .LP -->
AsciiSrc objects of type <function>XawAsciiString</function> have the text buffer
implemented as a string.
\fIMultiSrc objects of type <function>XawAsciiString</function> have the text buffer
implemented as a wide character string.\fP
The string owner is responsible for allocating and managing storage for the
string.
</para>
<para>
<!-- .LP -->
In the default case for AsciiSrc objects of type <function>XawAsciiString</function>,
the resource <function>useStringInPlace</function> is false,
and the widget owns the string.  The initial value of the
string resource, and any update made by the application
programmer to the string resource with <xref linkend='XtSetValues' xrefstyle='select: title'/>, is copied
into memory private to the widget, and managed internally by the widget.
The application writer
does not need to worry about running out of buffer space
(subject to the total memory available to the application).
The performance does not decay linearly as the buffer grows
large, as is necessarily the case when the text buffer is used
in place.   The application writer must use <xref linkend='XtGetValues' xrefstyle='select: title'/> to
determine the contents of the text buffer, which will return
a copy of the widget's text buffer as
it existed at the time of the <xref linkend='XtGetValues' xrefstyle='select: title'/> call.   This copy
is not affected by subsequent updates to the text buffer, i.e.,
it is not updated as the user types input into the text buffer.
This copy is freed upon the next call to XtGetValues to
retrieve the string resource; however, to conserve memory,
there is a convenience routine, <xref linkend='XawAsciiSourceFreeString' xrefstyle='select: title'/>, allowing the
application programmer to direct the widget to free the copy.
</para>
<para>
<!-- .LP -->
When the resource <function>useStringInPlace</function> is true and the AsciiSrc object
is of type <function>XawAsciiString</function>, the application
is the string owner.  The widget will take the value
of the string resource as its own text buffer, and the <function>length</function>
resource indicates the buffer size.   In this case
the buffer contents change as the user types at the widget;
it is not necessary to call <xref linkend='XtGetValues' xrefstyle='select: title'/> on the string
resource to determine the contents of the buffer-it will
simply return the address of the application's implementation
of the text buffer.
</para>
<sect2 id='AsciiSource::Resources'>
<title>Resources</title>
<para>
<!-- .LP -->
When creating an AsciiSrc object instance, the following resources are
retrieved from the argument list or from the resource database:
</para>
<para>
<!-- .LP -->
<!-- .IN "AsciiSrc object" "resources" -->
<informaltable>
  <tgroup cols='5' align='center'>
  <colspec colname='c1'/>
  <colspec colname='c2'/>
  <colspec colname='c3'/>
  <colspec colname='c4'/>
  <colspec colname='c5'/>
  <thead>
    <row>
      <entry>Name</entry>
      <entry>Class</entry>
      <entry>Type</entry>
      <entry>Notes</entry>
      <entry>Default Value</entry>
    </row>
  </thead>
  <tbody>
    <row>
      <entry>callback</entry>
      <entry>Callback</entry>
      <entry>XtCallbackList</entry>
      <entry></entry>
      <entry>NULL</entry>
    </row>
    <row>
      <entry>dataCompression</entry>
      <entry>DataCompression</entry>
      <entry>Boolean</entry>
      <entry></entry>
      <entry>True</entry>
    </row>
    <row>
      <entry>destroyCallback</entry>
      <entry>Callback</entry>
      <entry>Callback</entry>
      <entry></entry>
      <entry>NULL</entry>
    </row>
    <row>
      <entry>editType</entry>
      <entry>EditType</entry>
      <entry>EditMode</entry>
      <entry></entry>
      <entry>XawtextRead</entry>
    </row>
    <row>
      <entry>length</entry>
      <entry>Length</entry>
      <entry>Int</entry>
      <entry>A</entry>
      <entry>length of <function>string</function></entry>
    </row>
    <row>
      <entry>pieceSize</entry>
      <entry>PieceSize</entry>
      <entry>Int</entry>
      <entry></entry>
      <entry>BUFSIZ</entry>
    </row>
    <row>
      <entry>string</entry>
      <entry>String</entry>
      <entry>String</entry>
      <entry></entry>
      <entry>NULL</entry>
    </row>
    <row>
      <entry>type</entry>
      <entry>Type</entry>
      <entry>AsciiType</entry>
      <entry></entry>
      <entry>XawAsciiString</entry>
    </row>
    <row>
      <entry>useStringInPlace</entry>
      <entry>UseStringInPlace</entry>
      <entry>Boolean</entry>
      <entry></entry>
      <entry>False</entry>
    </row>
    <row>
      <entry>_</entry>
    </row>
  </tbody>
  </tgroup>
</informaltable>
<!-- .Oc Bold -->
<!-- .Dc -->
<!-- .Od Bold -->
<!-- .Oe -->
<!-- .Ol Bold -->
<!-- .Op Bold -->
<!-- .Os Bold -->
<!-- .Ot Bold -->
<!-- .Ou Bold -->
</para>
</sect2>
<sect2 id='AsciiSource::Convenience_Routines'>
<title>Convenience Routines</title>
<para>
<!-- .LP -->
The AsciiSrc has a few convenience routines that allow the
application programmer quicker or easier access to some of the
commonly used functionality of the AsciiSrc.
</para>
<sect3 id="Conserving_Memory">
<title>Conserving Memory</title>
<para>
<!-- .LP -->
When the AsciiSrc widget is not in <function>useStringInPlace</function> mode
space must be allocated whenever the file is saved, or the string is
requested with a call to <xref linkend='XtGetValues' xrefstyle='select: title'/>.  This memory is allocated on the
fly, and remains valid until the next time a string needs to be allocated.
You may save memory by freeing this string as soon as you are done
with it by calling <xref linkend='XawAsciiSourceFreeString' xrefstyle='select: title'/>.
<funcsynopsis id='XawAsciiSourceFreeString'>
<funcprototype>
  <funcdef>void<function> XawAsciiSourceFreeString</function></funcdef>
  <paramdef>Widget<parameter> w</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
  <varlistentry>
    <term>
      <emphasis remap='I'>w</emphasis>
    </term>
    <listitem>
      <para>
Specifies the AsciiSrc object.
    </para>
  </listitem>
  </varlistentry>
</variablelist>
</para>
<para>
<!-- .LP -->
This function will free the memory that contains the string pointer returned
by <xref linkend='XtGetValues' xrefstyle='select: title'/>.  This will normally happen automatically when
the next call to <xref linkend='XtGetValues' xrefstyle='select: title'/> occurs, or when the widget is destroyed.
</para>
</sect3>
<sect3 id="Saving_Files">
<title>Saving Files</title>
<para>
<!-- .LP -->
To save the changes made in the current text source into a file use
<xref linkend='XawAsciiSave' xrefstyle='select: title'/>.
<funcsynopsis id='XawAsciiSave'>
<funcprototype>
  <funcdef>Boolean<function> XawAsciiSave</function></funcdef>
  <paramdef>Widget<parameter> w</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
  <varlistentry>
    <term>
      <emphasis remap='I'>w</emphasis>
    </term>
    <listitem>
      <para>
Specifies the AsciiSrc object.
    </para>
  </listitem>
  </varlistentry>
</variablelist>
</para>
<para>
<!-- .LP -->
<xref linkend='XawAsciiSave' xrefstyle='select: title'/> returns <function>True</function> if the save was successful.
It will update the file named in the <function>string</function> resource.
If the buffer has not been changed, no action will be taken.  This function
only works on an AsciiSrc of type <function>XawAsciiFile</function>.
</para>
<para>
<!-- .LP -->
<!-- .sp 1 -->
To save the contents of the current text buffer into a named file use
<xref linkend='XawAsciiSaveAsFile' xrefstyle='select: title'/>.
<funcsynopsis id='XawAsciiSaveAsFile'>
<funcprototype>
  <funcdef>Boolean<function> XawAsciiSaveAsFile</function></funcdef>
  <paramdef>Widget<parameter> w</parameter></paramdef>
  <paramdef>String<parameter> name</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
  <varlistentry>
    <term>
      <emphasis remap='I'>w</emphasis>
    </term>
    <listitem>
      <para>
Specifies the AsciiSrc object.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>name</emphasis>
    </term>
    <listitem>
      <para>
The name of the file to save the current buffer into.
    </para>
  </listitem>
  </varlistentry>
</variablelist>
</para>
<para>
<!-- .LP -->
This function returns <function>True</function> if the save was successful.
<xref linkend='XawAsciiSaveAsFile' xrefstyle='select: title'/> will work with a buffer of either type
<function>XawAsciiString</function> or type <function>XawAsciiFile</function>.
</para>
</sect3>
<sect3 id="Seeing_if_the_Source_has_Changed">
<title>Seeing if the Source has Changed</title>
<para>
<!-- .LP -->
To find out if the text buffer in an AsciiSrc object has changed
since the last time it was saved with <xref linkend='XawAsciiSave' xrefstyle='select: title'/> or queried
<!-- .IN "XawAsciiSave" "" -->
use <xref linkend='XawAsciiSourceChanged' xrefstyle='select: title'/>.
<funcsynopsis id='XawAsciiSourceChanged'>
<funcprototype>
  <funcdef>Boolean<function> XawAsciiSourceChanged</function></funcdef>
  <paramdef>Widget<parameter> w</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
  <varlistentry>
    <term>
      <emphasis remap='I'>w</emphasis>
    </term>
    <listitem>
      <para>
Specifies the AsciiSrc object.
    </para>
  </listitem>
  </varlistentry>
</variablelist>
</para>
<para>
<!-- .LP -->
This function will return <function>True</function> if the source has changed since
the last time it was saved or queried.  The internal change flag is
reset whenever the string is queried via <xref linkend='XtGetValues' xrefstyle='select: title'/> or the
buffer is saved via <xref linkend='XawAsciiSave' xrefstyle='select: title'/>.

</para>
</sect3>
</sect2>
</sect1>