home *** CD-ROM | disk | FTP | other *** search
/ InfoMagic Source Code 1993 July / THE_SOURCE_CODE_CD_ROM.iso / X / mit / doc / Xaw / AsciiSource < prev    next >
Encoding:
Text File  |  1991-07-29  |  6.5 KB  |  208 lines
  1. .NH 2
  2. Ascii Source Object
  3. .LP
  4. .XS
  5.     AsciiSrc Object
  6. .XE
  7. .IN "AsciiSrc object" "" "@DEF@"
  8. .LP
  9. .Ds 0
  10. .TA 2.0i
  11. .ta 2.0i
  12. Application Header file    <X11/Xaw/AsciiSrc.h>
  13. .IN "AsciiSrc.h" ""
  14. Class Header file    <X11/Xaw/AsciiSrcP.h>
  15. .IN "AsciiSrcP.h" ""
  16. Class        asciiSrcObjectClass
  17. .IN "asciiSrcObjectClass" ""
  18. Class Name    AsciiSrc
  19. .IN "AsciiSrc object" "class name"
  20. Superclass    TextSource
  21. .sp 1
  22. .LP
  23. The AsciiSrc object is used by a text widget to read the text from a
  24. file or string in memory.  It understands all Latin1 characters plus Tab
  25. and Carriage Return.
  26. .LP
  27. The AsciiSrc can be either of two types: \fBXawAsciiFile\fP
  28. or \fBXawAsciiString\fP.
  29. .LP
  30. AsciiSrc objects of type \fBXawAsciiFile\fP read the text from a file and
  31. store it
  32. into an internal buffer.  This buffer may then be modified, provided the
  33. text widget is in the correct edit mode, just as if it were a source of
  34. type \fBXawAsciiString\fP.  Unlike R3 and earlier versions of the AsciiSrc,
  35. it is now possible to specify an editable disk source.  The file is not
  36. updated, however, until a call to \fBXawAsciiSave\fP is made.  When the
  37. source is in this mode the \fBuseStringInPlace\fP resource is ignored.
  38. .LP
  39. AsciiSrc objects of type \fBXawAsciiString\fP have the text buffer
  40. implemented as a string.  The string owner is responsible for allocating
  41. and managing storage for the string.
  42. .LP
  43. In the default case for AsciiSrc objects of type \fBXawAsciiString\fP,
  44. the resource \fBuseStringInPlace\fP is false,
  45. and the widget owns the string.  The initial value of the 
  46. string resource, and any update made by the application
  47. programmer to the string resource with \fBXtSetValues\fP, is copied 
  48. into memory private to the widget, and managed internally by the widget.
  49. The application writer
  50. does not need to worry about running out of buffer space
  51. (subject to the total memory available to the application).
  52. The performance does not decay linearly as the buffer grows
  53. large, as is necessarily the case when the text buffer is used
  54. in place.   The application writer must use \fBXtGetValues\fP to
  55. determine the contents of the text buffer, which will return
  56. a copy of the widget's text buffer as
  57. it existed at the time of the \fBXtGetValues\fP call.   This copy
  58. is not affected by subsequent updates to the text buffer, i.e.,
  59. it is not updated as the user types input into the text buffer.
  60. This copy is freed upon the next call to XtGetValues to 
  61. retrieve the string resource; however, to conserve memory,
  62. there is a convenience routine, \fBXawAsciiSrcFreeString\fP, allowing the
  63. application programmer to direct the widget to free the copy.
  64. .LP
  65. When the resource \fBuseStringInPlace\fP is true and the AsciiSrc object
  66. is of type \fBXawAsciiString\fP, the application
  67. is the string owner.  The widget will take the value
  68. of the string resource as its own text buffer, and the \fBlength\fP
  69. resource indicates the buffer size.   In this case
  70. the buffer contents change as the user types at the widget;
  71. it is not necessary to call \fBXtGetValues\fP on the string 
  72. resource to determine the contents of the buffer -- it will
  73. simply return the address of the application's implementation
  74. of the text buffer.
  75. .De
  76. .NH 3
  77. Resources
  78. .LP
  79. When creating an AsciiSrc object instance, the following resources are
  80. retrieved from the argument list or from the resource database:
  81. .LP
  82. .IN "AsciiSrc object" "resources"
  83. .ps 9
  84. .nr PS 9
  85. .vs 11
  86. .nr VS 11
  87. .TS H
  88. lw(1i) lw(1i) lw(1i) lw(.5i) lw(2i).
  89. _
  90. .sp 3p
  91. .TB
  92. Name    Class    Type    Notes    Default Value
  93. .sp 3p
  94. _
  95. .TH
  96. .R
  97. .sp 3p
  98. callback    Callback    XtCallbackList        NULL
  99. dataCompression    DataCompression    Boolean        True
  100. destroyCallback    Callback    Callback        NULL
  101. editType    EditType    EditMode        XawtextRead
  102. length    Length    Int    A    length of \fBstring\fP
  103. pieceSize    PieceSize    Int        BUFSIZ
  104. string    String    String        NULL
  105. type    Type    AsciiType        XawAsciiString
  106. useStringInPlace    UseStringInPlace    Boolean        False
  107. .sp 3p
  108. _
  109. .TE
  110. .ps 11
  111. .nr PS 11
  112. .vs 13
  113. .nr VS 13
  114. .Oc Bold
  115. .Dc
  116. .Od Bold
  117. .Oe
  118. .Ol Bold
  119. .Op Bold
  120. .Os Bold
  121. .Ot Bold
  122. .Ou Bold
  123. .NH 3
  124. Convenience Routines
  125. .LP
  126. The AsciiSrc has a few convenience routines that allow the
  127. application programmer quicker or easier access to some of the
  128. commonly used functionality of the AsciiSrc.
  129. .NH 4
  130. Conserving Memory
  131. .LP
  132. When the AsciiSrc widget is not in \fBuseStringInPlace\fP mode
  133. space must be allocated whenever the file is saved, or the string is 
  134. requested with a call to \fBXtGetValues\fP.  This memory is allocated on the
  135. fly, and remains valid until the next time a string needs to be allocated.
  136. You may save memory by freeing this string as soon as you are done
  137. with it by calling \fBXawAsciiSrcFreeString\fP.
  138. .FD 0
  139. void XawAsciiSourceFreeString(\fIw\fP)
  140. .IN "XawAsciiSourceFreeString" "" @DEF@
  141. .br
  142. Widget \fIw\fP;
  143. .FN
  144. .IP \fIw\fP 1i
  145. Specifies the AsciiSrc object.
  146. .LP
  147. This function will free the memory that contains the string pointer returned
  148. by \fBXtGetValues\fP.  This will normally happen automatically when
  149. the next call to \fBXtGetValues\fP occurs, or when the widget is destroyed.
  150. .NH 4
  151. Saving Files
  152. .LP
  153. To save the changes made in the current text source into a file use
  154. \fBXawAsciiSave\fP.
  155. .FD 0
  156. Boolean XawAsciiSave(\fIw\fP)
  157. .IN "XawAsciiSave" "" @DEF@
  158. .br
  159. Widget \fIw\fP;
  160. .FN
  161. .IP \fIw\fP 1i
  162. Specifies the AsciiSrc object.
  163. .LP
  164. \fBXawAsciiSave\fP returns \fBTrue\fP if the save was successful.
  165. It will update the file named in the \fBstring\fP resource.
  166. If the buffer has not been changed, no action will be taken.  This function
  167. only works on an AsciiSrc of type \fBXawAsciiFile\fP.
  168. .LP
  169. .sp 1
  170. To save the contents of the current text buffer into a named file use 
  171. \fBXawAsciiSaveAsFile\fP.
  172. .FD 0
  173. Boolean XawAsciiSaveAsFile(\fIw\fP, \fIname\fP)
  174. .IN "XawAsciiSaveAsFile" "" @DEF@
  175. .br
  176. Widget \fIw\fP;
  177. .br
  178. String \fIname\fP;
  179. .FN
  180. .IP \fIw\fP 1i
  181. Specifies the AsciiSrc object.
  182. .IP \fIname\fP 1i
  183. The name of the file to save the current buffer into.
  184. .LP
  185. This function returns \fBTrue\fP if the save was successful.
  186. \fBXawAsciiSaveAsFile\fP will work with a buffer of either type
  187. \fBXawAsciiString\fP or type \fBXawAsciiFile\fP. 
  188. .NH 4
  189. Seeing if the Source has Changed
  190. .LP
  191. To find out if the text buffer in an AsciiSrc object has changed
  192. since the last time it was saved with \fBXawAsciiSave\fP or queried
  193. .IN "XawAsciiSave" ""
  194. use \fBXawAsciiSourceChanged\fP.
  195. .FD 0
  196. Boolean XawAsciiSourceChanged(\fIw\fP)
  197. .IN "XawAsciiSourceChanged" "" @DEF@
  198. .br
  199. Widget \fIw\fP;
  200. .FN
  201. .IP \fIw\fP 1i
  202. Specifies the AsciiSrc object.
  203. .LP
  204. This function will return \fBTrue\fP if the source has changed since
  205. the last time it was saved or queried.  The internal change flag is
  206. reset whenever the string is queried via \fBXtGetValues\fP or the
  207. buffer is saved via \fBXawAsciiSave\fP.
  208.