specs/AsciiSource.xml

   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 <!-- .IN "AsciiSrc object" "" "@DEF@" -->
   9 </para>
  10 <para>
  11 <!-- .LP -->
  12 <literallayout class="monospaced">
  13 <!-- .TA 2.0i -->
  14 <!-- .ta 2.0i -->
  15 Application Header file &lt;X11/Xaw/AsciiSrc.h&gt; or &lt;X11/Xaw/MultiSrc.h&gt;
  16 <!-- .IN "AsciiSrc.h" "" -->
  17 Class Header file       &lt;X11/Xaw/AsciiSrcP.h&gt; or  &lt;X11/Xaw/MultiSrcP.h&gt;
  18 <!-- .IN "AsciiSrcP.h" "" -->
  19 Class           asciiSrcObjectClass or multiSrcObjectClass
  20 <!-- .IN "asciiSrcObjectClass" "" -->
  21 Class Name      AsciiSrc or MultiSrc
  22 <!-- .IN "AsciiSrc object" "class name" -->
  23 Superclass      TextSource
  24 </literallayout>
  25 </para>
  26 <para>
  27 <!-- .LP -->
  28 The AsciiSrc or MultiSrc object is used by a text widget to read the text from a
  29 file or string in memory.  Depending on its <function>international</function> resource, an
  30 AsciiText widget will create one or the other of these when the AsciiText
  31 itself is created.  Both types are nearly identical; the following discussion
  32 applies to both, with MultiSrc differences noted only as they occur.
  33 </para>
  34 <para>
  35 <!-- .LP -->
  36 The AsciiSrc understands all Latin1 characters plus Tab
  37 and Carriage Return.  \fIThe MultiSrc understands any set of character sets that
  38 the underlying X implementation's internationalization handles.\fP
  39 </para>
  40 <para>
  41 <!-- .LP -->
  42 The AsciiSrc can be either of two types: <function>XawAsciiFile</function>
  43 or <function>XawAsciiString</function>.
  44 </para>
  45 <para>
  46 <!-- .LP -->
  47 AsciiSrc objects of type <function>XawAsciiFile</function> read the text from a file and
  48 store it
  49 into an internal buffer.  This buffer may then be modified, provided the
  50 text widget is in the correct edit mode, just as if it were a source of
  51 type <function>XawAsciiString</function>.  Unlike R3 and earlier versions of the AsciiSrc,
  52 it is now possible to specify an editable disk source.  The file is not
  53 updated, however, until a call to <function>XawAsciiSave</function> is made.  When the
  54 source is in this mode the <function>useStringInPlace</function> resource is ignored.
  55 </para>
  56 <para>
  57 <!-- .LP -->
  58 AsciiSrc objects of type <function>XawAsciiString</function> have the text buffer
  59 implemented as a string.
  60 \fIMultiSrc objects of type <function>XawAsciiString</function> have the text buffer
  61 implemented as a wide character string.\fP
  62 The string owner is responsible for allocating and managing storage for the
  63 string.
  64 </para>
  65 <para>
  66 <!-- .LP -->
  67 In the default case for AsciiSrc objects of type <function>XawAsciiString</function>,
  68 the resource <function>useStringInPlace</function> is false,
  69 and the widget owns the string.  The initial value of the
  70 string resource, and any update made by the application
  71 programmer to the string resource with <function>XtSetValues</function>, is copied
  72 into memory private to the widget, and managed internally by the widget.
  73 The application writer
  74 does not need to worry about running out of buffer space
  75 (subject to the total memory available to the application).
  76 The performance does not decay linearly as the buffer grows
  77 large, as is necessarily the case when the text buffer is used
  78 in place.   The application writer must use <function>XtGetValues</function> to
  79 determine the contents of the text buffer, which will return
  80 a copy of the widget's text buffer as
  81 it existed at the time of the <function>XtGetValues</function> call.   This copy
  82 is not affected by subsequent updates to the text buffer, i.e.,
  83 it is not updated as the user types input into the text buffer.
  84 This copy is freed upon the next call to XtGetValues to
  85 retrieve the string resource; however, to conserve memory,
  86 there is a convenience routine, <function>XawAsciiSourceFreeString</function>, allowing the
  87 application programmer to direct the widget to free the copy.
  88 </para>
  89 <para>
  90 <!-- .LP -->
  91 When the resource <function>useStringInPlace</function> is true and the AsciiSrc object
  92 is of type <function>XawAsciiString</function>, the application
  93 is the string owner.  The widget will take the value
  94 of the string resource as its own text buffer, and the <function>length</function>
  95 resource indicates the buffer size.   In this case
  96 the buffer contents change as the user types at the widget;
  97 it is not necessary to call <function>XtGetValues</function> on the string
  98 resource to determine the contents of the buffer-it will
  99 simply return the address of the application's implementation
 100 of the text buffer.
 101 </para>
 102 <sect2 id="asciisource_resources">
 103 <title>Resources</title>
 104 <para>
 105 <!-- .LP -->
 106 When creating an AsciiSrc object instance, the following resources are
 107 retrieved from the argument list or from the resource database:
 108 </para>
 109 <para>
 110 <!-- .LP -->
 111 <!-- .IN "AsciiSrc object" "resources" -->
 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 -->
 213 The AsciiSrc has a few convenience routines that allow the
 214 application programmer quicker or easier access to some of the
 215 commonly used functionality of the AsciiSrc.
 216 </para>
 217 <sect3 id="Conserving_Memory">
 218 <title>Conserving Memory</title>
 219 <para>
 220 <!-- .LP -->
 221 When the AsciiSrc widget is not in <function>useStringInPlace</function> mode
 222 space must be allocated whenever the file is saved, or the string is
 223 requested with a call to <function>XtGetValues</function>.  This memory is allocated on the
 224 fly, and remains valid until the next time a string needs to be allocated.
 225 You may save memory by freeing this string as soon as you are done
 226 with it by calling <function>XawAsciiSourceFreeString</function>.
 227 <funcsynopsis>
 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>
 241 Specifies the AsciiSrc object.
 242     </para>
 243   </listitem>
 244   </varlistentry>
 245 </variablelist>
 246 </para>
 247 <para>
 248 <!-- .LP -->
 249 This function will free the memory that contains the string pointer returned
 250 by <function>XtGetValues</function>.  This will normally happen automatically when
 251 the next call to <function>XtGetValues</function> 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 -->
 258 To save the changes made in the current text source into a file use
 259 <function>XawAsciiSave</function>.
 260 <funcsynopsis>
 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>
 274 Specifies the AsciiSrc object.
 275     </para>
 276   </listitem>
 277   </varlistentry>
 278 </variablelist>
 279 </para>
 280 <para>
 281 <!-- .LP -->
 282 <function>XawAsciiSave</function> returns <function>True</function> if the save was successful.
 283 It will update the file named in the <function>string</function> resource.
 284 If the buffer has not been changed, no action will be taken.  This function
 285 only works on an AsciiSrc of type <function>XawAsciiFile</function>.
 286 </para>
 287 <para>
 288 <!-- .LP -->
 289 <!-- .sp 1 -->
 290 To save the contents of the current text buffer into a named file use
 291 <function>XawAsciiSaveAsFile</function>.
 292 <funcsynopsis>
 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>
 307 Specifies 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>
 317 The name of the file to save the current buffer into.
 318     </para>
 319   </listitem>
 320   </varlistentry>
 321 </variablelist>
 322 </para>
 323 <para>
 324 <!-- .LP -->
 325 This function returns <function>True</function> if the save was successful.
 326 <function>XawAsciiSaveAsFile</function> 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 -->
 334 To find out if the text buffer in an AsciiSrc object has changed
 335 since the last time it was saved with <function>XawAsciiSave</function> or queried
 336 <!-- .IN "XawAsciiSave" "" -->
 337 use <function>XawAsciiSourceChanged</function>.
 338 <funcsynopsis>
 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>
 352 Specifies the AsciiSrc object.
 353     </para>
 354   </listitem>
 355   </varlistentry>
 356 </variablelist>
 357 </para>
 358 <para>
 359 <!-- .LP -->
 360 This function will return <function>True</function> if the source has changed since
 361 the last time it was saved or queried.  The internal change flag is
 362 reset whenever the string is queried via <function>XtGetValues</function> or the
 363 buffer is saved via <function>XawAsciiSave</function>.
 364
 365 </para>
 366 </sect3>
 367 </sect2>
 368 </sect1>