home *** CD-ROM | disk | FTP | other *** search
/ Celestin Apprentice 2 / Apprentice-Release2.iso / Source Code / C / Libraries / stdwin / Doc / seldoc.ms < prev    next >
Encoding:
Text File  |  1991-02-28  |  11.8 KB  |  401 lines  |  [TEXT/????]
  1. .\" To format, use (di)troff -ms; and make sure macros.ms is around!
  2. .so macros.ms
  3. .SH
  4. Using X11 Selections and Cut Buffers in STDWIN
  5. .LP
  6. The C STDWIN interface has been extended to support the
  7. .I selection
  8. mechanism used by X11.
  9. Support for the ring of 8 cut buffers is also provided.
  10. .PP
  11. This document assumes you are familiar with STDWIN as a programmer and
  12. with X11 as an end user (at least xterm experience and some idea of the
  13. client-server model).
  14. .NH
  15. What are Selections?
  16. .LP
  17. X11 supports an arbitrary number of selections, but version 1.0 of the
  18. ICCCM (Inter-Client Communication Conventions Manual, by David Rosenthal)
  19. requires only that clients support three selections called PRIMARY,
  20. SECONDARY and CLIPBOARD.
  21. I will further reference these in lower case.
  22. .PP
  23. The
  24. .I "primary selection"
  25. is the mechanism you normally use to transfer data interactively
  26. between clients (or within one client).
  27. In xterm and text-oriented toolkit clients, you make a primary
  28. selection by dragging with the left mouse button.
  29. The contents of the selection are highlighted using inverse video.
  30. The contents of the primary selection can be pasted into the same or
  31. another (toolkit) client by pressing the middle mouse button.
  32. .PP
  33. Conventions for use of the
  34. .I "secondary selection"
  35. are less well-known.
  36. It is used as the second argument of operations with two arguments,
  37. such as swap or replace operations.
  38. There is no default support for it in the toolkit, but it is
  39. possible to customize toolkit clients to use it.
  40. .PP
  41. The
  42. .I clipboard
  43. is intended to hold data that the user has deleted and wants to insert
  44. somewhere later.
  45. It is supported by the standard X11 client
  46. .I xclipboard ,
  47. which displays the current contents of the clipboard.
  48. Other toolkit clients can be customized to use it.
  49. .NH
  50. Selections From the Client's Point of View
  51. .LP
  52. It is important to realize that the contents of selections are
  53. transferred between clients at the time they are pasted; selections are
  54. not normally stored by the server.
  55. At any time, a selection is ``owned'' by at most one client, the
  56. .I "selection owner" .
  57. Different selections may be owned by different clients.
  58. The server keeps track of selection owners.
  59. When a client wants to become owner of a particular selection, it tells
  60. the server so, and the server will send the previous owner an event to
  61. tell it that it no longer owns the selection.
  62. .PP
  63. The protocol to transfer the contents of a selection between clients is
  64. fairly involved.
  65. Somewhat simplified, it works as follows:
  66. .IP \(bu
  67. A client requests the contents of a selection from the server.
  68. .IP \(bu 2
  69. The server sends the owner an event asking ``please give me this
  70. selection.''
  71. .IP \(bu 2
  72. The owner stores the contents of the selection as a
  73. .I property\(dg
  74. .FS
  75. \(dg
  76. A window
  77. .I property
  78. is a named arbitrary piece of data associated with a window, stored by
  79. the server.
  80. .FE
  81. on the requestor's window, and sends an event back (via the server)
  82. telling the requestor that the selection is stored.
  83. .IP \(bu 2
  84. The requestor fetches the contents of the property, and deletes
  85. the property.
  86. .PP
  87. Various complications are possible:
  88. .IP \(bu 2
  89. Race conditions: a client may be slow to respond to a mouse click, and
  90. the impatient user may have clicked again in another client's window.
  91. When the first client finally decides it wants to become selection
  92. owner, the second client may already own it.
  93. .IP \(bu
  94. Crashes: a selection owner may crash before it has responded to a
  95. request for the selection's contents.
  96. .IP \(bu
  97. Space limitations on the server.
  98. .IP \(bu
  99. Negotiations about the type of the selection: a string could be stored
  100. in simple ASCII or in a special format that retains font information,
  101. and in fact a selection may contain a picture or an arbitrarily
  102. complicated data structure that only a few clients know about.
  103. .NH
  104. The STDWIN Interface to Selections
  105. .LP
  106. STDWIN simplifies the concept of a selection somewhat and takes care of
  107. most details of communicating with other clients.
  108. In STDWIN, selections are always ASCII strings and only the three
  109. standard selections are supported.
  110. The strings are null-terminated but may also contain embedded null
  111. characters, so a length is always provided.
  112. .PP
  113. The header
  114. .cW <stdwin.h>
  115. defines constants that identify the selections:
  116. .cW WS_PRIMARY ,
  117. .cW WS_SECONDARY ,
  118. and
  119. .cW WS_CLIPBOARD .
  120. The application calls the function
  121. .cW wsetselection()
  122. to become owner of a selection.
  123. It may later receive an event of type
  124. .cW WE_LOST_SEL
  125. telling it that it lost ownership again.
  126. It is also possible to voluntarily give up selection ownership by
  127. calling
  128. .cW wresetselection() .
  129. To access the contents of a selection, whether you own it or not, call
  130. the function
  131. .cW wgetselection() .
  132. Transfer of selection contents to other clients is done automatically by
  133. .cW wgetevent()
  134. and
  135. .cW wpollevent() .
  136. Detailed descriptions of the new functions follow:
  137. .NH 2
  138. Function \*<wsetselection()\*>
  139. .LP
  140. .sC L
  141. bool wsetselection(win, sel, data, len)
  142. WINDOW *win;
  143. int sel;
  144. char *data;
  145. int len;
  146. .eC
  147. .LP
  148. Parameters:
  149. .IP \*<win\*> 6n
  150. Specifies a window that will be associated with the selection.
  151. This has no other meaning that limiting the lifetime of the selection to
  152. the lifetime of the window.
  153. It will not be reported in
  154. .cW WE_LOST_SEL
  155. events.
  156. .IP \*<sel\*>
  157. Specifies which selection should be set.
  158. It should be one of the codes
  159. .cW WS_PRIMARY ,
  160. .cW WS_SECONDARY ,
  161. or
  162. .cW WS_CLIPBOARD .
  163. .IP \*<data\*>
  164. Specifies the data comprising the selection's contents.
  165. This need not be null-terminated.
  166. It is copied to a safe place by the function so it can be sent to
  167. other clients later.
  168. .IP \*<len\*>
  169. Specifies the length of the data, not including a terminating null byte.
  170. .LP
  171. This function attempts to acquirpe ownership of the specified selection.
  172. This may fail because of race conditions.
  173. The function returns nonzero if it succeeds.
  174. If it fails, the application should give the user visual feedback of the
  175. failure,
  176. .I e.g. ,
  177. by not inverting the selected text.
  178. .NH 2
  179. Function \*<wresetselection()\*>
  180. .LP
  181. .sC L
  182. void wresetselection(sel)
  183. int sel;
  184. .eC
  185. .LP
  186. Parameters:
  187. .IP \*<sel\*> 6n
  188. Specifies which selection should be reset.
  189. It should be one of the codes
  190. .cW WS_PRIMARY ,
  191. .cW WS_SECONDARY ,
  192. or
  193. .cW WS_CLIPBOARD .
  194. .LP
  195. If the application owns the specified selection, this function cancels
  196. ownership.
  197. No
  198. .cW WE_LOST_SEL
  199. events are generated for the selection.
  200. .NH 2
  201. Function \*<wgetselection()\*>
  202. .LP
  203. .sC L
  204. char *wgetselection(sel, plen)
  205. int sel;
  206. int *plen;
  207. .eC
  208. Parameters:
  209. .IP \*<sel\*> 6n
  210. Specifies which selection should be retrieved.
  211. It should be one of the codes
  212. .cW WS_PRIMARY ,
  213. .cW WS_SECONDARY ,
  214. or
  215. .cW WS_CLIPBOARD .
  216. .IP \*<plen\*>
  217. Into this parameter, the length of the data is returned, excluding the
  218. terminating null byte.
  219. .LP
  220. This function retrieves the contents of the specified selection.
  221. If it succeeds, a pointer to its data is returned.
  222. The data is terminated by a null byte but may contain null bytes, so the
  223. length is returned separately.
  224. The data pointer points to space internal to the STDWIN library.
  225. It remains valid until the next call involving selections.
  226. If the selection could not be retrieved somehow, a NULL pointer is
  227. returned.
  228. Selections longer that 32K may be truncated.
  229. Since the transfer mechanism requires the use of a window, a NULL
  230. pointer is returned when the application currently has no windows open.
  231. .NH 2
  232. The \*<WE_LOST_SEL\*> event type
  233. .LP
  234. A STDWIN application receives this event type when it owns a selection
  235. (a call to
  236. .cW wsetselection()
  237. has succeeded) and another client has become the new owner.
  238. The
  239. .cW window
  240. member of the
  241. .cW EVENT
  242. is set to
  243. .cW NULL .
  244. The
  245. .cW u.sel
  246. union member is set to the code for the selection.
  247. This event is not generated when selection ownership is given up by
  248. calling
  249. .cW wresetselection()
  250. or by deleting its window.
  251. .NH
  252. The STDWIN Interface to Cut Buffers
  253. .LP
  254. For compatibility with old STDWIN or X11 clients and Andrew clients,
  255. an interface to the cut buffer interface is also provided.
  256. This is a ring of 8 buffers maintained at the server.
  257. The following functions are available:
  258. .NH 2
  259. Function \*<wsetcutbuffer()\*>
  260. .LP
  261. .sC L
  262. void wsetcutbuffer(ibuffer, data, len)
  263. int ibuffer;
  264. char *data;
  265. int len;
  266. .eC
  267. .LP
  268. Parameters:
  269. .IP \*<ibuffer\*> 10n
  270. Specifies which buffer should be set, in the range [0 ... 7].
  271. .IP \*<data\*>
  272. Specifies the data.
  273. It need not be null-terminated.
  274. .IP \*<len\*>
  275. Specifies the length of the data, excluding a terminating null byte.
  276. .LP
  277. This function sets the contents of the specified cut buffer to the given
  278. data.
  279. No indication of success or failure is given.
  280. .NH 2
  281. Function \*<wgetcutbuffer()\*>
  282. .LP
  283. .sC L
  284. char *wgetcutbuffer(ibuffer, plen)
  285. int ibuffer;
  286. int *plen;
  287. .eC
  288. .LP
  289. Parameters:
  290. .IP \*<ibuffer\*> 10n
  291. Specifies which buffer should be retrieved, in the range [0 ... 7].
  292. .IP \*<plen\*>
  293. Returns the length of the data, excluding the terminating null byte.
  294. .LP
  295. This function returns the contents of the specified cut buffer,
  296. terminated by a null byte.
  297. If the cut buffer is not accessible, it returns
  298. .cW NULL .
  299. .NH 2
  300. Function \*<wrotatecutbuffers()\*>
  301. .LP
  302. .sC L
  303. void wrotatecutbuffers(n)
  304. int n;
  305. .eC
  306. .LP
  307. Parameters:
  308. .IP \*<n\*> 4n
  309. Specifies the amount of rotation.
  310. This may be negative.
  311. .LP
  312. The cut buffers are rotated as follows:
  313. buffer n gets the contents of buffer 0, buffer n+1 (mod 8) gets the
  314. contents of buffer 1, etc.
  315. .NH 2
  316. Function \*<wsetclip()\*>
  317. .LP
  318. .sC L
  319. void wsetclip(data, len)
  320. char *data;
  321. int len;
  322. .eC
  323. This function is equivalent to
  324. .sC
  325. wsetcutbuffer(0, data, len);
  326. wrotatecutbuffers(1);
  327. .eC
  328. .NH 2
  329. Function \*<wgetclip()\*>
  330. .LP
  331. .sC L
  332. char *wgetclip()
  333. .eC
  334. This function is equivalent to
  335. .sC
  336. int len;
  337. return wgetcutbuffer(0, &len);
  338. .eC
  339. (It throws away the length.)
  340. .NH
  341. Suggested Usage
  342. .LP
  343. To conform to X11 conventions, STDWIN applications should normally use
  344. the primary selection, but use the cut buffers as a ``fall-back''
  345. mechanism.
  346. .PP
  347. When the user has selected some text, the application should transfer
  348. the text to cut buffer 0 and rotate the buffers (the easiest way to do
  349. this is to call
  350. .cW wsetclip() ),
  351. and then call
  352. .cW wsetselection()
  353. to set the primary selection to the text.
  354. If the latter call fails, the inverse video on the selected text should
  355. be removed.
  356. The inverse video should also be removed when a
  357. .cW WE_LOST_SEL
  358. event is received.
  359. If there is a text insertion point associated with the selection, it
  360. should be left at the position indicated by the last mouse click, or to
  361. the beginning of the selected text.
  362. .PP
  363. When the user desires to paste some text, the applcation should first
  364. get the contents of the primary selection, and if this returns a NULL
  365. pointer, it should get the contents of cut buffer 0.
  366. If this returns a NULL pointer as well, the paste request should be
  367. refused (with a beep, or something similar).
  368. .PP
  369. The conventions for selecting and pasting text are:
  370. .IP \(bu 2
  371. Dragging with the left (first) mouse button is used to make a selection.
  372. Double-clicking selects ``words.''
  373. .IP \(bu
  374. Clicking with the middle mouse button requests a ``paste'' operation.
  375. It does not move the insert point to the position of the click.
  376. .IP \(bu
  377. Clicking with the right mouse button extends the selection at the end
  378. closest to the button click.
  379. .NH
  380. Selections and Macintosh STDWIN
  381. .LP
  382. The Macintosh user interface standards prescribe only a single cut
  383. buffer, called the Clipboard.
  384. For source compatibility with STDWIN applications developed for X11,
  385. dummy versions of the selection functions are provided:
  386. .cW wsetselection()
  387. and
  388. .cW wgetselection()
  389. always fail, and
  390. .cW wresetselection()
  391. is ignored.
  392. Versions of the cut buffer functions are provided that identify cut
  393. buffer 0 with the Macintosh Clipboard and ignore the other cut buffers.
  394. .PP
  395. The net effect is that STDWIN applications written for X11 selections
  396. that use the cut buffers as a fall-back mechanism will support the
  397. Macintosh Clipboard, albeit with an X11-like interface.
  398. Macintosh applications are encouraged to provide a standard Edit menu
  399. with the operations Cut, Copy and Paste and the standard shortcuts for
  400. them: Command-X, Command-C and Command-V.
  401.