home *** CD-ROM | disk | FTP | other *** search
/ InfoMagic Source Code 1993 July / THE_SOURCE_CODE_CD_ROM.iso / X / mit / doc / Xaw / TextSink < prev    next >
Encoding:
Text File  |  1989-12-22  |  13.2 KB  |  440 lines

  1. .NH 2
  2. TextSink Object
  3. .LP
  4. .XS
  5.     TextSink Object
  6. .XE
  7. .IN "TextSink object" "" "@DEF@"
  8. .LP
  9. .Ds 0
  10. .TA 2.0i
  11. .ta 2.0i
  12. Application Header file    <X11/Xaw/TextSink.h>
  13. .IN "TextSink.h" ""
  14. Class Header file    <X11/Xaw/TextSinkP.h>
  15. .IN "TextSinkP.h" ""
  16. Class        textSinkObjectClass
  17. .IN "textSinkObjectClass" ""
  18. Class Name    TextSink
  19. .IN "TextSink object" "class name"
  20. Superclass    Object
  21. .sp 1
  22. .LP
  23. The TextSink object is the root object for all text sinks.  Any new text
  24. sink objects should be subclasses of the TextSink Object.  The TextSink
  25. Class contains all methods that the Text widget expects a text sink to
  26. export.
  27. .LP
  28. Since all text sinks will have some resources in common, the TextSink
  29. defines a few new resources.
  30. .De
  31. .NH 3
  32. Resources
  33. .LP
  34. When creating an TextSink object instance, the following resources are
  35. retrieved from the argument list or from the resource database:
  36. .LP
  37. .IN "AsciiSink object" "resources"
  38. .ps 9
  39. .nr PS 9
  40. .vs 11
  41. .nr VS 11
  42. .TS H
  43. lw(1i) lw(1i) lw(1i) lw(.5i) lw(2i).
  44. _
  45. .sp 3p
  46. .TB
  47. Name    Class    Type    Notes    Default Value
  48. .sp 3p
  49. _
  50. .TH
  51. .R
  52. .sp 3p
  53. background    Background    Pixel        XtDefaultBackground
  54. destroyCallback    Callback    XtCallbackList        NULL
  55. font    Font    XFontStruct*        XtDefaultFont
  56. foreground    Foreground    Pixel        XtDefaultForeground
  57. .sp 3p
  58. _
  59. .TE
  60. .ps 11
  61. .nr PS 11
  62. .vs 13
  63. .nr VS 13
  64. .Bg Bold
  65. One foreground color is provided in TextSink.
  66. .Dc
  67. .Sf Bold
  68. .Sg Bold
  69. .NH 3
  70. Subclassing the TextSink
  71. .IN "TextSink object" "subclassing" "@DEF@"
  72. .LP
  73. The only purpose of the TextSink Object is to be subclassed.  It
  74. contains the minimum set of class methods that all text sinks must have.
  75. While all may be inherited, the direct descendant of TextSink \fBmust
  76. specify\fP some of them as TextSink does contain enough information to
  77. be a valid text sink by itself.  Do not try to use 
  78. the TextSink as a valid sink for the Text widget, it is not intended
  79. to be used as a sink by itself and bad things will probably happen.
  80. .ps 9
  81. .nr PS 9
  82. .vs 11
  83. .nr VS 11
  84. .TS H
  85. lw(1i) lw(1.5i) lw(2i) lw(1i).
  86. _
  87. .sp 3p
  88. .TB
  89. Function    Inherit with    Public Interface    must specify
  90. .sp 3p
  91. _
  92. .TH
  93. .R
  94. .sp 3p
  95. DisplayText    XtInheritDisplayText    XawTextSinkDisplayText    yes
  96. .IN "XtInheritDisplayText" ""
  97. .IN "XawTextSinkDisplayText" ""
  98. InsertCursor    XtInheritInsertCursor    XawTextSinkInsertCursor    yes
  99. .IN "XtInheritInsertCursor" ""
  100. .IN "XawTextSinkInsertCursor" ""
  101. ClearToBackground    XtInheritClearToBackground    XawTextSinkClearToBackground    no
  102. .IN "XtInheritClearToBackground" ""
  103. .IN "XawTextSinkClearToBackground" ""
  104. FindPosition    XtInheritFindPosition    XawTextSinkFindPosition    yes
  105. .IN "XtInheritFindPosition" ""
  106. .IN "XawTextSinkFindPosition" ""
  107. FindDistance    XtInheritFindDistance    XawTextSinkFindDistance    yes
  108. .IN "XtInheritFindDistance" ""
  109. .IN "XawTextSinkFindDistance" ""
  110. Resolve    XtInheritResolve    XawTextSinkResolve    yes
  111. .IN "XtInheritResolve" ""
  112. .IN "XawTextSinkResolve" ""
  113. MaxLines    XtInheritMaxLines    XawTextSinkMaxLines    no
  114. .IN "XtInheritMaxLines" ""
  115. .IN "XawTextSinkMaxLines" ""
  116. MaxHeight    XtInheritMaxHeight    XawTextSinkMaxHeight    no
  117. .IN "XtInheritMaxHeight" ""
  118. .IN "XawTextSinkMaxHeight" ""
  119. SetTabs    XtInheritSetTabs    XawTextSinkSetTabs    no
  120. .IN "XtInheritSetTabs" ""
  121. .IN "XawTextSinkSetTabs" ""
  122. GetCursorBounds    XtInheritGetCursorBounds    XawTextSinkGetCursorBounds    yes
  123. .IN "XtInheritGetCursorBounds" ""
  124. .IN "XawTextSinkGetCursorBounds" ""
  125. _
  126. .TE
  127. .ps 11
  128. .nr PS 11
  129. .vs 13
  130. .nr VS 13
  131. .NH 4
  132. Displaying Text
  133. .LP
  134. To display a section of the text buffer contained in the text source
  135. use the function \fBDisplayText\fP:
  136. .IN "TextSink object" "DisplayText" "@DEF@"
  137. .FD 0
  138. void DisplayText(\fIw\fP, \fIx\fP, \fIy\fP, \fIpos1\fP, \fIpos2\fP, \fIhighlight\fP)
  139. .br
  140.       Widget \fIw\fP;
  141. .br
  142.       Position \fIx\fP, \fIy\fP;
  143. .br
  144.       XawTextPosition \fIpos1\fP, \fIpos2\fP;
  145. .br
  146.       Boolean \fIhighlight\fP;
  147. .FN
  148. .IP \fIw\fP 1i
  149. Specifies the TextSink object.
  150. .IP \fIx\fP 1i
  151. Specifies the x location to start drawing the text.
  152. .IP \fIy\fP 1i
  153. Specifies the y location to start drawing text.
  154. .IP \fIpos1\fP 1i
  155. Specifies the location within the text source of the first character
  156. to be printed.
  157. .IP \fIpos2\fP 1i
  158. Specifies the location within the text source of the last character
  159. to be printed.
  160. .IP \fIhighlight\fP 1i
  161. Specifies whether or not to paint the text region highlighted.
  162. .LP
  163. The Text widget will only pass one line at a time to the text sink, so
  164. this function does not need to know how to line feed the text.  It is
  165. acceptable for this function to just ignore Carriage Returns.  \fIx\fP
  166. and \fIy\fP denote the upper left hand corner of the first character to
  167. be displayed.
  168. .NH 4
  169. Displaying the Insert Point
  170. .LP
  171. The function that controls the display of the text cursor is
  172. \fBInsertCursor\fP.  This function will be called whenever the text
  173. widget desires to change the state of, or move the insert point.
  174. .FD 0
  175. void InsertCursor(\fIw\fP, \fIx\fP, \fIy\fP, \fIstate\fP)
  176. .IN "TextSink object" "InsertCursor" "@DEF@"
  177. .br
  178.       Widget \fIw\fP;
  179. .br
  180.       Position \fIx\fP, \fIy\fP;
  181. .br
  182.       XawTextInsertState \fIstate\fP;
  183. .FN
  184. .IP \fIw\fP 1i
  185. Specifies the TextSink object.
  186. .IP \fIx\fP 1i
  187. Specifies the x location of the cursor in Pixels.
  188. .IP \fIy\fP 1i
  189. Specifies the y location of the cursor in Pixels.
  190. .IP \fIstate\fP 1i
  191. Specifies the state of the cursor, may be one of \fBXawisOn\fP or
  192. \fBXawisOff\fP.
  193. .LP
  194. \fIX\fP and \fIy\fP denote the upper left hand corner of the insert point.
  195. .NH 4
  196. Clearing Portions of the Text window
  197. .LP
  198. To clear a portion of the Text window to its background color, the Text
  199. widget will call \fBClearToBackground\fP.  The TextSink object already
  200. defines this function as calling \fBXClearArea\fP on the region passed.
  201. This behavior will be used if you specify
  202. \fBXtInheritClearToBackground\fP for this method.
  203. .IN "XtInheritClearToBackground" ""
  204. .IN "TextSink object" "ClearToBackground" "@DEF@"
  205. .FD 0
  206. void ClearToBackground(\fIw\fP, \fIx\fP, \fIy\fP, \fIwidth\fP, \fIheight\fP)
  207. .br
  208.       Widget \fIw\fP;
  209. .br
  210.       Position \fIx\fP, \fIy\fP;
  211. .br
  212.       Dimension \fIwidth\fP, \fIheight\fP;
  213. .FN
  214. .IP \fIw\fP 1i
  215. Specifies the TextSink object.
  216. .IP \fIx\fP 1i
  217. Specifies the x location, in pixels, of the Region to clear.
  218. .IP \fIy\fP 1i
  219. Specifies the y location, in pixels, of the Region to clear.
  220. .IP \fIwidth\fP 1i
  221. Specifies the width, in pixels, of the Region to clear.
  222. .IP \fIheight\fP 1i
  223. Specifies the height, in pixels, of the Region to clear.
  224. .LP
  225. \fIX\fP and \fIy\fP denote the upper left hand corner of region to clear.
  226. .NH 4
  227. Finding a Text Position Given Pixel Values
  228. .LP
  229. To find the text character position that will be rendered at a given x
  230. location the Text widget uses the function \fBFindPosition\fP:
  231. .IN "TextSink object" "FindPosition" "@DEF@"
  232. .FD 0
  233. void FindPosition(\fIw\fP, \fIfromPos\fP, \fIfromX\fP, \fIwidth\fP, \fIstopAtWordBreak\fP, \fIpos_return\fP, \fIwidth_return\fP, \fIheight_return\fP)
  234. .br
  235.       Widget \fIw\fP;
  236. .br
  237.       XawTextPosition \fIfromPos\fP;
  238. .br
  239.       int \fIfromX\fP, \fIwidth\fP;
  240. .br
  241.       Boolean \fIstopAtWordBreak\fP;
  242. .br
  243.       XawTextPosition \fI*pos_return\fP;
  244. .br
  245.       int \fI*width_return\fP, \fI*height_return\fP;
  246. .FN
  247. .IP \fIw\fP 1.25i
  248. Specifies the TextSink object.
  249. .IP \fIfromPos\fP 1.25i
  250. Specifies a reference position, usually the first character in this line.
  251. This character is always to the left of the desired character location.
  252. .IP \fIfromX\fP 1.25i
  253. Specifies the distance that the left edge of \fIfromPos\fP is from the
  254. left edge of the window.  This is the reference x location for the
  255. reference position.
  256. .IP \fIwidth\fP 1.25i
  257. Specifies the distance, in pixels, from the reference position to the
  258. desired character position.
  259. .IP \fIstopAtWordBreak\fP 1.25i
  260. Specifies whether or not the position that is returned should be forced
  261. to be on a word boundary.
  262. .IP \fIpos_return\fP 1.25i
  263. Returns the character position that corresponds to the location that has
  264. been specified, or the work break immediately to the left of the
  265. position if \fIstopAtWordBreak\fP is \fBTrue\fP.
  266. .IP \fIwidth_return\fP 1.25i
  267. Returns the actual distance between \fIfromPos\fP and \fIpos_return\fI.
  268. .IP \fIheight_return\fP 1.25i
  269. Returns the maximum height of the text between \fIfromPos\fP and
  270. \fIpos_return\fI.
  271. .LP
  272. This function need make no attempt to deal with line feeds.  The text
  273. widget will only call it one line at a time.
  274. .LP
  275. .sp
  276. Another means of finding a text position is provided by the \fBResolve\fP
  277. function:
  278. .IN "TextSink object" "Resolve" "@DEF@"
  279. .FD 0
  280. void Resolve(\fIw\fP, \fIfromPos\fP, \fIfromX\fP, \fIwidth\fP, \fIpos_return\fP)
  281. .br
  282.       Widget \fIw\fP;
  283. .br
  284.       XawTextPosition \fIfromPos\fP;
  285. .br
  286.       int \fIfromX\fP, \fIwidth\fP;
  287. .br
  288.       XawTextPosition \fI*pos_return\fP;
  289. .FN
  290. .IP \fIw\fP 1i
  291. Specifies the TextSink object.
  292. .IP \fIfromPos\fP 1i
  293. Specifies a reference position, usually the first character in this line.
  294. This character is always to the left of the desired character location.
  295. .IP \fIfromX\fP 1i
  296. Specifies the distance that the left edge of \fIfromPos\fP is from the
  297. left edge of the window.  This is the reference x location for the
  298. reference position.
  299. .IP \fIwidth\fP 1i
  300. Specifies the distance, in pixels, from the reference position to the
  301. desired character position.
  302. .IP \fIpos_return\fP 1i
  303. Returns the character position that corresponds to the
  304. location that has been specified, or the word break immediately to the left
  305. if \fIstopAtWordBreak\fP is \fBTrue\fP.
  306. .LP
  307. This function need make no attempt to deal with line feeds.  The text
  308. widget will only call it one line at a time.  This is a more convenient
  309. interface to the \fBFindPosition\fP function, and provides a subset of its
  310. functionality.
  311. .IN "FindPosition" ""
  312. .NH 4
  313. Finding the Distance Between two Text Positions
  314. .LP
  315. To find the distance in pixels between two text positions on the same
  316. line use the function \fBFindDistance\fP.
  317. .IN "TextSink object" "FindDistance" "@DEF@"
  318. .FD 0
  319. void FindDistance(\fIw\fP, \fIfromPos\fP, \fIfromX\fP, \fItoPos\fP, \fIwidth_return\fP, \fIpos_return\fP, \fIheight_return\fP)
  320. .br
  321.       Widget \fIw\fP;
  322. .br
  323.       XawTextPosition \fIfromPos\fP, \fItoPos\fP;
  324. .br
  325.       int \fIfromX\fP;
  326. .br
  327.       XawTextPosition \fI*pos_return\fP;
  328. .br
  329.       int \fI*width_return\fP, \fI*height_return\fP;
  330. .FN
  331. .IP \fIw\fP 1i
  332. Specifies the TextSink object.
  333. .IP \fIfromPos\fP 1i
  334. Specifies the text buffer position, in characters, of the first position.
  335. .IP \fIfromX\fP 1i
  336. Specifies the distance that the left edge of \fIfromPos\fP is from the
  337. left edge of the window.  This is the reference x location for the
  338. reference position.
  339. .IP \fItoPos\fP 1i
  340. Specifies the text buffer position, in characters, of the second position.
  341. .IP \fIresWidth\fP 1i
  342. Return the actual distance between \fIfromPos\fP
  343. and \fIpos_return\fI.
  344. .IP \fIresPos\fP 1i
  345. Returns the character position that corresponds to the actual character
  346. position used for \fItoPos\fP in the calculations.  This may be
  347. different than \fItoPos\fP, for example if \fIfromPos\fP and \fItoPos\fP
  348. are on different lines in the file.
  349. .IP \fIheight_return\fP 1i 
  350. Returns the maximum height of the text between \fIfromPos\fP and
  351. \fIpos_return\fP.
  352. .LP
  353. This function need make no attempt to deal with line feeds.  The Text
  354. widget will only call it one line at a time.
  355. .NH 4
  356. Finding the Size of the Drawing area
  357. .LP
  358. To find the maximum number of lines that will fit into the current Text
  359. widget, use the function \fBMaxLines\fP.  The TextSink already defines
  360. this function to compute the maximum number of lines by using the height
  361. of \fBfont\fP.
  362. .IN "TextSink object" "MaxLines" "@DEF@"
  363. .FD 0
  364. int MaxLines(\fIw\fP, \fIheight\fP)
  365. .br
  366.       Widget \fIw\fP;
  367. .br
  368.       Dimension \fIheight\fP;
  369. .FN
  370. .IP \fIw\fP 1i
  371. Specifies the TextSink object.
  372. .IP \fIheight\fP 1i
  373. Specifies the height of the current drawing area.
  374. .LP
  375. Returns the maximum number of lines that will fit in \fIheight\fP.
  376. .LP
  377. .sp
  378. To find the height required for a given number of text lines, use
  379. the function \fBMaxHeight\fP.  The TextSink already defines this
  380. function to compute the maximum height of the window by using the
  381. height of \fBfont\fP. 
  382. .IN "TextSink object" "MaxHeight" "@DEF@"
  383. .FD 0
  384. int MaxHeight(\fIw\fP, \fIlines\fP)
  385. .br
  386.       Widget \fIw\fP;
  387. .br
  388.       int \fIlines\fP;
  389. .FN
  390. .IP \fIw\fP 1i
  391. Specifies the TextSink object.
  392. .IP \fIheight\fP 1i
  393. Specifies the height of the current drawing area.
  394. .LP
  395. Returns the height that will be taken up by the number of lines passed.
  396. .NH 4
  397. Setting the Tab Stops
  398. .LP
  399. To set the tab stops for a text sink use the \fBSetTabs\fP function.
  400. The TextSink already defines this function to set the tab x location in
  401. pixels to be the number of characters times the figure width of
  402. \fBfont\fP.
  403. .IN "TextSink object" "SetTabs" "@DEF@"
  404. .FD 0
  405. void SetTabs(\fIw\fP, \fItab_count\fP, \fItabs\fP)
  406. .br
  407.       Widget \fIw\fP;
  408. .br
  409.       int \fItab_count\fP, \fI*tabs\fP;
  410. .FN
  411. .IP \fIw\fP 1i
  412. Specifies the TextSink object.
  413. .IP \fItab_count\fP 1i
  414. Specifies the number of tabs passed in \fItabs\fP.
  415. .IP \fItabs\fP 1i
  416. Specifies the position, in characters, of the tab stops.  
  417. .LP
  418. This function is responsible for the converting character positions passed
  419. to it into whatever internal positions the TextSink uses for tab placement.
  420. .NH 4
  421. Getting the Insert Point's Size and Location
  422. .LP
  423. To get the size and location of the insert point use the
  424. \fBGetCursorBounds\fP function.
  425. .IN "TextSink object" "GetCursorBounds" "@DEF@"
  426. .FD 0
  427. void GetCursorBounds(\fIw\fP, \fIrect_return\fP)
  428. .br
  429. Widget \fIw\fP;
  430. .br
  431. XRectangle \fI*rect_return\fP;
  432. .FN
  433. .IP \fIw\fP 1i
  434. Specifies the TextSinkObject.
  435. .IP \fIrect_return\fP 1i
  436. Returns the location and size of the insert point.
  437. .LP
  438. \fIRect\fP will be filled with the current size and location of the
  439. insert point.
  440.