X11 Clipboard Discussion
If you are a Windows user, you may not understand how the X11 "clipboard" works. Before telling you about the clipboard functions in XAUT, I'd like to discuss how you can expect the XAUT commands to work.
The first important point regards why I put scare quotes around the word "clipboard" in the previous paragraph. In X11, data that can be copy/pasted or drag/dropped, or whatever, are called "selections." The clipboard is one type of selection, but it is not the only type. Generally speaking, there are two selections that you will encounter—the primary selection and the clipboard selection.
Primary Selection: The primary selection changes whenever you highlight text. You do not need to explicitly copy it to the "clipboard", it's available as soon as you are done selecting. If you select something else somewhere else, then the first selection is gone. In fact, in a well-behaved client, any selected content will immediately become deselected when you select something else, even if that selection is in another program. An example: I use SciTE as my windowed editor daily. I have SciTE setup such that if I type ctrl + f, it will often times select the text where my cursor is sitting and use that as the search term. So imagine I have a terminal open and I select text without doing anything else. That selection is now my primary selection. Now suppose I alt + tab to SciTE and hit ctrl + f. SciTE will select the text where my cursor is and bring up the find dialog. In addition to that, the content in the terminal window will cease to be selected.
Clipboard Selection: The clipboard selection is intended to work like the "clipboard" in that popular operating system. One must take an explicit action to put content there—typically a key combination (e.g. ctrl + c), or a menu choice (e.g. Edit->Copy).
X11 does not access or store the data at all, it simply knows who has it. If a program requests that data, then X11 passes on the request to the proper program. The program requesting the data and the program which is holding the data negotiate the data type. If the two programs have no data type in common (think copy image in image editor, try to paste into text editor), then nothing pastes.
In its current iteration, XAUT knows about text. That's it. So you can put text into a selection, you can get text out of a selection. Trying to get the data from e.g. an image will almost certainly return nothing at all.
Another important point is that XAUT creates an invisible window which holds content you put into a selection. That window stays in the background servicing any request for data until another program asks for control of the selection. So basically the final bits of your script may not exit until you copy data in another program.
Finally, there is another selection type I have not yet mentioned—the secondary selection. I have included this in XAUT for completeness sake, but this is very uncommonly used. In fact, I do not know of even one other program that allows access to the secondary selection. It would be pretty surprising if using get_secondary would return any values, and if you were to put any content there, then it's likely the hidden window will last until forceably killed. So basically the secondary selection is there if you need it, but be sure you know what you are doing before you do use it!
Clipboard Object Functions
Function Synopsis
| Function | Brief Description |
|---|---|
| get_primary() | Gets the current data in the primary selection. |
| get_secondary() | Gets the current data in the secondary selection. |
| get_clipboard() | Gets the current data in the clipboard selection. |
| put_primary(str) | Puts data into the primary selection. |
| put_secondary(str) | Puts data into the secondary selection. |
| put_clipboard(str) | Puts data into the clipboard selection. |
Function:
get_primary()
Gets the current data in the primary selection. Note that the data currently in the primary selection must be text or compatible with text, otherwise the program will return null.
Parameters:
(none)Return Value:
The data in the primary selection.Example(s):
import xaut
cb = xaut.clipboard()
primary = cb.get_primary()
print("The primary content was %s") % (primary)
Function:
get_secondary()
Gets the current data in the secondary selection. Note that the data currently in the secondary selection must be text or compatible with text, otherwise the program will return null.
Note also that it is very uncommon to use the secondary selection. It's highly likely that this function will return nothing at all.
Parameters:
(none)Return Value:
The data in the secondary selection.Example(s):
import xaut
cb = xaut.clipboard()
secondary = cb.get_secondary()
print("The secondary content was %s") % (secondary)
Function:
get_clipboard()
Gets the current data in the clipboard selection. Note that the data currently in the clipboard selection must be text or compatible with text, otherwise the program will return null.
Parameters:
(none)Return Value:
The data in the clipboard selection.Example(s):
import xaut
cb = xaut.clipboard()
clip = cb.get_clipboard()
print("The clipboard content was %s") % (clip)
Function:
put_primary(str)
Puts current data into the primary selection. Note that the data passed must be text.
Note also that most programs will lose their selection when this function is called.
Parameters:
| Param | Req | Description |
|---|---|---|
| str | yes | The text to put into the selection. |
Return Value:
(none)Example(s):
import xaut
cb = xaut.clipboard()
cb.put_primary("This content came from XAUT")
Function:
put_secondary(str)
Puts current data into the secondary selection. Note that the data passed must be text.
Note also that it is extremely unusual for a program to use the secondary selection. It's likely that if you use this, all that will happen is that you create a hidden window that doesn't go away until killed forceably.
Parameters:
| Param | Req | Description |
|---|---|---|
| str | yes | The text to put into the selection. |
Return Value:
(none)Example(s):
import xaut
cb = xaut.clipboard()
cb.put_secondary("This content came from XAUT")
Function:
put_clipboard(str)
Puts current data into the clipboard selection. Note that the data passed must be text.
Parameters:
| Param | Req | Description |
|---|---|---|
| str | yes | The text to put into the selection. |
Return Value:
(none)Example(s):
import xaut
cb = xaut.clipboard()
cb.put_clipboard("This content came from XAUT")