home *** CD-ROM | disk | FTP | other *** search
/ InfoMagic Source Code 1993 July / THE_SOURCE_CODE_CD_ROM.iso / X / mit / doc / Xaw / TextFuncs < prev    next >
Encoding:
Text File  |  1991-07-29  |  10.3 KB  |  377 lines
  1. .NH 2
  2. Text Functions
  3. .XS
  4.     Text Functions
  5. .XE
  6. .LP
  7. The following functions are provided as convenience routines for use with
  8. the Text widget.  Although many of these actions can be performed by
  9. modifying resources, these interfaces are frequently more efficient.
  10. .LP
  11. These data structures are defined in the Text widget's public header file,
  12. <X11/Xaw/Text.h>.
  13. .LP
  14. .IN "XawTextPosition" "" "@DEF@"
  15. typedef long XawTextPosition;
  16. .sp
  17. .LP
  18. Character positions in the Text widget begin at 0 and end at n+1, where
  19. n is the number of characters in the Text source widget.
  20. .LP
  21. .IN "XawTextBlock" "" "@DEF@"
  22. .Ds 0
  23. .TA .5i 1.5i 2.25i 
  24. .ta .5i 1.5i 2.25i
  25. typedef struct {
  26.     int \fIfirstPos\fP;
  27.     int \fIlength\fP;
  28.     char *\fIptr\fP;
  29.     unsigned long \fIformat\fP;
  30. } XawTextBlock, *XawTextBlockPtr;
  31. .De
  32. .LP
  33. .IN "XawTextBlockPtr" ""
  34. .IP \fIfirstPos\fP 1.0i
  35. The first position, or index, to use within the \fIptr\fP field.
  36. The value is commonly zero.
  37. .IP \fIlength\fP 1.0i
  38. The number of characters to be used from the \fIptr\fP field.
  39. The number of characters used is commonly the number of characters
  40. in \fIptr\fP, and must not be greater than the length of the string
  41. in \fIptr\fP.
  42. .IP \fIptr\fP 1.0i
  43. Contains the string to be referenced by the Text widget.
  44. .IP \fIformat\fP 1.0i
  45. This field is not currently used, but should be specified as
  46. \fBFMT8BIT\fP.
  47. .NH 3
  48. Selecting Text
  49. .LP
  50. To select a piece of text, use 
  51. .PN XawTextSetSelection :
  52. .IN "XawTextSetSelection" "" "@DEF@"
  53. .FD 0
  54. void XawTextSetSelection(\fIw\fP, \fIleft\fP, \fIright\fP)
  55. .br
  56.      Widget \fIw\fP;
  57. .br
  58.      XawTextPosition \fIleft\fP, \fIright\fP;
  59. .FN
  60. .IP \fIw\fP 1i
  61. Specifies the Text widget.
  62. .IP \fIleft\fP 1i
  63. Specifies the character position at which the selection begins.
  64. .IP \fIright\fP 1i
  65. Specifies the character position at which the selection ends.
  66. .LP
  67. If redisplay is enabled, this function highlights the text and
  68. makes it the \fBPRIMARY\fP selection.  This function does not have any
  69. effect on \fBCUT_BUFFER0\fP.
  70. .LP
  71. .NH 3
  72. Unhighlighting Text
  73. .LP
  74. To unhighlight previously highlighted text in a widget, use
  75. \fBXawTextUnsetSelection\fP:
  76. .IN "XawTextUnsetSelection" "" "@DEF@"
  77. .FD 0
  78. void XawTextUnsetSelection(\fIw\fP)
  79. .br
  80.      Widget \fIw\fP;
  81. .FN
  82. .IP \fIw\fP 1i
  83. Specifies the Text widget.
  84. .NH 3
  85. Getting Current Text Selection
  86. .LP
  87. To retrieve the text that has been selected by this
  88. text widget use \fBXawTextGetSelectionPos\fP:
  89. .IN "XawTextGetSelectionPos" "" "@DEF@"
  90. .FD 0
  91. void XawTextGetSelectionPos(\fIw\fP, \fIbegin_return\fP, \fIend_return\fP)
  92. .br
  93.      Widget \fIw\fP;
  94. .br
  95.      XawTextPosition *\fIbegin_return\fP, *\fIend_return\fP; 
  96. .FN
  97. .IP \fIw\fP 1i
  98. Specifies the Text widget.
  99. .IP \fIbegin_return\fP 1i
  100. Returns the beginning of the text selection.
  101. .IP \fIend_return\fP 1i
  102. Returns the end of the text selection.
  103. .LP
  104. If the returned values are equal, no text is currently selected.
  105. .NH 3
  106. Replacing Text
  107. .LP
  108. To modify the text in an editable Text widget use \fBXawTextReplace\fP:
  109. .IN "XawTextReplace" "" "@DEF@"
  110. .FD 0
  111. int XawTextReplace(\fIw\fP, \fIstart\fP, \fIend\fP, \fItext\fP)
  112. .br
  113.      Widget \fIw\fP;
  114. .br
  115.      XawTextPosition \fIstart\fP, \fIend\fP;
  116. .br
  117.      XawTextBlock *\fItext\fP;
  118. .FN
  119. .IP \fIw\fP 1i
  120. Specifies the Text widget.
  121. .IP \fIstart\fP 1i
  122. Specifies the starting character position of the text replacement.
  123. .IP \fIend\fP 1i
  124. Specifies the ending character position of the text replacement.
  125. .IP \fItext\fP 1i
  126. Specifies the text to be inserted into the file.  This function will not
  127. be able to replace text in read-only text widgets.  It will also only
  128. be able to append text to an append-only text widget.
  129. .LP
  130. This function may return the following values:
  131. .IP \fBXawEditDone\fP 1.25i
  132. .IN "XawEditDone" ""
  133. The text replacement was successful.
  134. .IP \fBXawPositionError\fP 1.25i
  135. .IN "XawPositionError" ""
  136. The edit mode is \fBXawtextAppend\fP and \fIstart\fP is not the position of
  137. the last character of the source.
  138. .IP \fBXawEditError\fP 1.25i
  139. .IN "XawEditError" ""
  140. Either the Source was read-only or the range to be deleted is larger
  141. than the length of the Source.
  142.  
  143. .LP
  144. The \fBXawTextReplace\fP arguments \fIstart\fP and
  145. \fIend\fP represent the text source character positions for the
  146. existing text that is to be replaced by the text in the text block.
  147. The characters from \fIstart\fP up to
  148. but not including \fIend\fP are deleted, and the characters
  149. specified on the text block are inserted in their place.  If
  150. \fIstart\fP and \fIend\fP are equal, no text is deleted and the new
  151. text is inserted after \fIstart\fP. 
  152. .NH 3
  153. Searching for Text
  154. .LP
  155. To search for a string in the Text widget, use
  156. \fBXawTextSearch\fP:
  157. .IN "XawTextSearch" "" "@DEF@"
  158. .FD 0
  159. XawTextPosition XawTextSearch(\fIw\fP, \fIdir\fP, \fItext\fP)
  160. .br
  161.       Widget \fIw\fP;
  162. .br
  163.       XawTextScanDirection \fIdir\fP;
  164. .br
  165.       XawTextBlock * \fItext\fP;
  166. .FN
  167. .IP \fIw\fP 1i
  168. Specifies the Text widget.
  169. .IP \fIdir\fP 1i
  170. Specifies the direction to search in.  Legal values are
  171. \fBXawsdLeft\fP and \fBXawsdRight\fP.
  172. .IP \fItext\fP 1i
  173. Specifies a text block structure that contains the text to search for.
  174. .LP
  175. The \fBXawTextSearch\fP function will begin at the insertion point
  176. and search in the 
  177. direction specified for a string that matches the one passed in 
  178. \fItext\fP.  If the string is found the location of the first
  179. character in the string is returned.  If the string could not be
  180. found then the value \fBXawTextSearchError\fP is returned.
  181. .NH 3
  182. Redisplaying Text
  183. .LP
  184. To redisplay a range of characters, use \fBXawTextInvalidate\fP:
  185. .IN "XawTextInvalidate" "" "@DEF@"
  186. .FD 0
  187. void XawTextInvalidate(\fIw\fP, \fIfrom\fP, \fIto\fP)
  188. .br
  189.       Widget \fIw\fP;
  190. .br
  191.       XawTextPosition \fIfrom\fP, \fIto\fP;
  192. .FN
  193. .IP \fIw\fP 1i
  194. Specifies the Text widget.
  195. .IP \fIfrom\fP 1i
  196. Specifies the start of the text to redisplay.
  197. .IP \fIto\fP 1i
  198. Specifies the end of the text to redisplay.
  199. .LP
  200. The \fBXawTextInvalidate\fP
  201. function causes the specified range of characters to be redisplayed
  202. immediately if redisplay is enabled or the next time that redisplay is
  203. enabled.
  204. .LP
  205. .sp 1
  206. To enable redisplay, use \fBXawTextEnableRedisplay\fP:
  207. .IN "XawTextEnableRedisplay" "" "@DEF@"
  208. .FD 0
  209. void XawTextEnableRedisplay(\fIw\fP)
  210. .br
  211.       Widget \fIw\fP;
  212. .FN
  213. .IP \fIw\fP 1i
  214. Specifies the Text widget.
  215. .LP
  216. The \fBXawTextEnableRedisplay\fP function flushes any changes due to
  217. batched updates when \fBXawTextDisableRedisplay\fP
  218. was called and allows future changes to be reflected immediately.
  219. .LP
  220. .sp 1
  221. To disable redisplay while making several changes, use
  222. \fBXawTextDisableRedisplay\fP.
  223. .IN "XawTextDisableRedisplay" "" "@DEF@"
  224. .FD 0
  225. void XawTextDisableRedisplay(\fIw\fP)
  226. .br
  227.        Widget \fIw\fP;
  228. .FN
  229. .IP \fIw\fP 1i
  230. Specifies the Text widget.
  231. .LP
  232. The \fBXawTextDisableRedisplay\fP function causes all changes to be
  233. batched until either \fBXawTextDisplay\fP or \fBXawTextEnableRedisplay\fP
  234. is called.
  235. .LP
  236. .sp 1
  237. To display batched updates, use \fBXawTextDisplay\fP:
  238. .IN "XawTextDisplay" "" "@DEF@" 
  239. .FD 0
  240. void XawTextDisplay(\fIw\fP)
  241. .br
  242.      Widget \fIw\fP;
  243. .FN
  244. .IP \fIw\fP 1i
  245. Specifies the Text widget.
  246. .LP
  247. The \fBXawTextDisplay\fP function forces any accumulated updates to be
  248. displayed. 
  249. .NH 3
  250. Resources Convenience Routines
  251. .LP
  252. To obtain the character position of the left-most character on the
  253. first line displayed in the widget (the value of the
  254. \fBdisplayPosition\fP resource), use \fBXawTextTopPosition\fP.
  255. .IN "XawTextTopPosition" "" @DEF@"
  256. .FD 0
  257. XawTextPosition XawTextTopPosition(\fIw\fP)
  258. .br    
  259.       Widget \fIw\fP;
  260. .FN
  261. .IP \fIw\fP 1i
  262. Specifies the Text widget.
  263. .LP
  264. .sp 1
  265. To assign a new selection array to a text widget use
  266. \fBXawTextSetSelectionArray\fP:
  267. .IN "XawTextSetSelectionArray" "" "@DEF@"
  268. .FD 0
  269. void XawTextSetSelectionArray(\fIw\fP, \fIsarray\fP)
  270. .br
  271.       Widget \fIw\fP;
  272. .br
  273.       XawTextSelectType * \fIsarray\fP;
  274. .FN
  275. .IP \fIw\fP 1i
  276. Specifies the Text widget.
  277. .IP \fIsarray\fP 1i
  278. Specifies a selection array as defined in the section called \fBText
  279. Selections for Application Programmers\fP.
  280. .LP
  281. Calling this function is equivalent to setting the value of the
  282. \fBselectionTypes\fP resource. 
  283. .LP
  284. .sp 1
  285. To move the insertion point to the specified source position, use
  286. \fBXawTextSetInsertionPoint\fP:
  287. .IN "XawTextSetInsertionPoint" "" "@DEF@"
  288. .FD 0
  289. void XawTextSetInsertionPoint(\fIw\fP, \fIposition\fP)
  290. .br        
  291.       Widget \fIw\fP;
  292. .br
  293.       XawTextPosition \fIposition\fP;
  294. .FN
  295. .IP \fIw\fP 1i
  296. Specifies the Text widget.
  297. .IP \fIposition\fP 1i
  298. Specifies the new position for the insertion point.
  299. .LP
  300. The text will be scrolled vertically if necessary to make the line
  301. containing the insertion point visible.  Calling this function is
  302. equivalent to setting the \fBinsertPosition\fP resource. 
  303. .LP
  304. .sp 1
  305. To obtain the current position of the insertion point, use
  306. \fBXawTextGetInsertionPoint\fP:
  307. .IN "XawTextGetInsertionPoint" "" "@DEF@"
  308. .FD 0
  309. XawTextPosition XawTextGetInsertionPoint(\fIw\fP)
  310. .br
  311.       Widget \fIw\fP;
  312. .FN
  313. .IP \fIw\fP 1i
  314. Specifies the Text widget.
  315. .LP
  316. The result is equivalent to retrieving the value of the
  317. \fBinsertPosition\fP resource. 
  318. .LP
  319. .sp 1
  320. To replace the text source in the specified widget, use
  321. \fBXawTextSetSource\fP:
  322. .IN "XawTextSetSource" "" "@DEF@"
  323. .FD 0
  324. void XawTextSetSource(\fIw\fP, \fIsource\fP, \fIposition\fP)
  325. .br
  326.       Widget \fIw\fP;
  327. .br
  328.       Widget \fIsource\fP;
  329. .br
  330.       XawTextPosition \fIposition\fP;
  331. .FN
  332. .IP \fIw\fP 1i
  333. Specifies the Text widget.
  334. .IP \fIsource\fP 1i
  335. Specifies the text source object.
  336. .IP \fIposition\fP 1i
  337. Specifies character position that will become the upper left hand corner
  338. of the displayed text.  This is usually set to zero.
  339. .LP
  340. A display update will be performed if redisplay is enabled.
  341. .LP
  342. .sp 1
  343. To obtain the current text source for the specified widget, use
  344. \fBXawTextGetSource\fP:
  345. .IN "XawTextGetSource" "" "@DEF@"
  346. .FD 0
  347. Widget XawTextGetSource(\fIw\fP)
  348. .br    
  349.       Widget \fIw\fP;
  350. .FN
  351. .IP \fIw\fP 1i
  352. Specifies the Text widget.
  353. .LP
  354. This function returns the text source that this Text widget is currently
  355. using.
  356. .LP
  357. .sp
  358. To enable and disable the insertion point, use
  359. \fBXawTextDisplayCaret\fP:
  360. .IN "XawTextDisplayCaret" "" "@DEF@"
  361. .FD 0
  362. void XawTextDisplayCaret(\fIw\fP, \fIvisible\fP)
  363. .br
  364.       Widget \fIw\fP;
  365. .br
  366.       Boolean \fIvisible\fP;
  367. .FN
  368. .IP \fIw\fP 1i
  369. Specifies the Text widget.
  370. .IP \fIvisible\fP 1i
  371. Specifies whether or not the caret should be displayed.
  372. .LP
  373. If \fIvisible\fP is \fBFalse\fP the insertion point will be disabled.
  374. The marker is re-enabled either by setting \fIvisible\fP to \fBTrue\fP, by
  375. calling \fBXtSetValues\fP, or by executing the \fIdisplay-caret\fP
  376. action routine.
  377.