Clipboard toolkit
Dragonfly’s clipboard toolkit offers easy access to and manipulation of
the system clipboard. The Clipboard
class forms the core
of this toolkit. Each instance of this class is a container with a
structure similar to the system clipboard, mapping content formats to
content data.
Dragonfly chooses the clipboard class to alias as Clipboard
based
on the platform:
dragonfly.windows.win32_clipboard.Win32Clipboard
is used on Windows.
dragonfly.windows.x11_clipboard.XselClipboard
is used on X11/Linux. This class requires thexclip
program.
dragonfly.windows.pyperclip_clipboard.PyperclipClipboard
is used on other platforms, such as macOS or Linux.
API differences
All platform clipboard classes have the same API, plus any platform-specific formats. The following two basic formats are always available:
format_text
– ANSI text format (format int: 1)
format_unicode
– Unicode text format (format int: 13)
The basic clipboard format constants used should match those used on
Windows, e.g. format_unicode
is represented by 13 (CF_UNICODETEXT
).
To be safe, use the format_*
attributes defined by the clipboard class.
Usage examples
An instance of something contains clipboard data. The data stored within an instance can be transferred to and from the system clipboard as follows: (before running this example, the text “asdf” was copied into the system clipboard)
>>> from dragonfly.windows.clipboard import Clipboard
>>> instance = Clipboard() # Create empty instance.
>>> print(instance)
Clipboard()
>>> instance.copy_from_system() # Retrieve from system clipboard.
>>> print(instance)
Clipboard(unicode=u'asdf', text, oemtext, locale)
>>> # The line above shows that *instance* now contains content for
>>> # 4 different clipboard formats: unicode, text, oemtext, locale.
>>> # The unicode format content is also displayed.
>>> instance.copy_to_system() # Transfer back to system clipboard.
The situation frequently occurs that a developer would like to use the system clipboard to perform some task without the data currently stored in it being lost. This backing up and restoring can easily be achieved as follows:
>>> from dragonfly.windows.clipboard import Clipboard
>>> # Initialize instance with system clipboard content.
... original = Clipboard(from_system=True)
>>> print(original)
Clipboard(unicode=u'asdf', text, oemtext, locale)
>>> # Use the system clipboard to do something.
... temporary = Clipboard({Clipboard.format_unicode: u"custom content"})
>>> print(temporary)
Clipboard(unicode=u'custom content')
>>> temporary.copy_to_system()
>>> from dragonfly import Key
>>> Key("c-v").execute()
>>> # Restore original system clipboard content.
... print(Clipboard(from_system=True)) # Show system clipboard contents.
Clipboard(unicode=u'custom content', text, oemtext, locale)
>>> original.copy_to_system()
>>> print(Clipboard(from_system=True)) # Show system clipboard contents.
Clipboard(unicode=u'asdf', text, oemtext, locale)
Base Clipboard class
- class BaseClipboard(contents=None, text=None, from_system=False)[source]
Base clipboard class.
- classmethod convert_format_content(format, content)[source]
Convert content for the given format, if necessary, and return it.
- This method operates on the following formats:
text – encodes content to a binary string, if necessary and if possible.
unicode – decodes content to a text string, if necessary and if possible.
hdrop – converts content into a tuple of file paths, if necessary and if possible.
String content must be a list of existing, absolute file paths separated by new lines and/or null characters. All specified file paths must be absolute paths referring to existing files on the system.
If the content cannot be converted for the given format, an error is raised.
- Arguments:
format (int) – the clipboard format to convert.
content (string) – the clipboard contents to convert.
- copy_from_system(formats=None, clear=False)[source]
Copy the system clipboard contents into this instance.
- Arguments:
formats (iterable, default: None) – if not None, only the given content formats will be retrieved. If None, all available formats will be retrieved.
clear (boolean, default: False) – if true, the system clipboard will be cleared after its contents have been retrieved.
- copy_to_system(clear=True)[source]
Copy the contents of this instance into the system clipboard.
- Arguments:
clear (boolean, default: True) – if true, the system clipboard will be cleared before this instance’s contents are transferred.
- get_available_formats()[source]
Retrieve a list of this instance’s available formats.
The preferred text format, if available, will always be the first on the list followed by any remaining formats in numerical order.
- get_format(format)[source]
Retrieved this instance’s content for the given format.
- Arguments:
format (int) – the clipboard format to retrieve.
If the given format is not available, a ValueError is raised.
- get_text()[source]
Retrieve this instance’s text content. If no text content is available, this method returns None.
- has_format(format)[source]
Determine whether this instance has content for the given format.
- Arguments:
format (int) – the clipboard format to look for.
- set_format(format, content)[source]
Set this instance’s content for the given format.
- Arguments:
format (int) – the clipboard format to set.
content (string) – the clipboard contents to set.
If the given format is not available, a ValueError is raised.
If None is given as the content, any content stored for the given format will be cleared.
- classmethod set_system_text(content)[source]
Set the system clipboard text.
- Arguments:
content (string) – the clipboard contents to set.
If None is given as the content, text on the system clipboard will be cleared.
- set_text(content)[source]
Set the text content for this instance.
- Arguments:
content (string) – the text content to set.
If None is given as the content, any text content stored in this instance will be cleared.
- classmethod synchronized_changes(timeout, step=0.001, formats=None, initial_clipboard=None)[source]
Context manager for synchronizing local and system clipboard changes. This takes the same arguments as the
wait_for_change()
method.- Arguments:
timeout (float) – timeout in seconds.
step (float, default: 0.001) – number of seconds between each check.
formats (iterable, default: None) – if not None, only changes to the given content formats will register. If None, all formats will be observed.
initial_clipboard (Clipboard, default: None) – if a clipboard is given, the method will wait until the system clipboard differs from the instance’s contents.
Use with a Python ‘with’ block:
from dragonfly import Clipboard, Key # Copy the selected text with Ctrl+C and wait until a system # clipboard change is detected. timeout = 3 with Clipboard.synchronized_changes(timeout): Key("c-c", use_hardware=True).execute() # Retrieve the system text. text = Clipboard.get_system_text()
- property text
Retrieve this instance’s text content. If no text content is available, this method returns None.
- classmethod wait_for_change(timeout, step=0.001, formats=None, initial_clipboard=None)[source]
Wait (poll) for the system clipboard to change.
This is a blocking method which returns whether or not the system clipboard changed within a specified timeout period.
- Arguments:
timeout (float) – timeout in seconds.
step (float, default: 0.001) – number of seconds between each check.
formats (iterable, default: None) – if not None, only changes to the given content formats will register. If None, all formats will be observed.
initial_clipboard (Clipboard, default: None) – if a clipboard is given, the method will wait until the system clipboard differs from the instance’s contents.
Windows Clipboard class
- class Win32Clipboard(contents=None, text=None, from_system=False)[source]
Class for interacting with the Windows system clipboard.
This is Dragonfly’s default clipboard class on Windows.
- copy_from_system(formats=None, clear=False)[source]
Copy the system clipboard contents into this instance.
- Arguments:
formats (iterable, default: None) – if not None, only the given content formats will be retrieved. If None, all available formats will be retrieved.
clear (boolean, default: False) – if true, the system clipboard will be cleared after its contents have been retrieved.
- copy_to_system(clear=True)[source]
Copy the contents of this instance into the system clipboard.
- Arguments:
clear (boolean, default: True) – if true, the system clipboard will be cleared before this instance’s contents are transferred.
- classmethod set_system_text(content)[source]
Set the system clipboard text.
- Arguments:
content (string) – the clipboard contents to set.
If None is given as the content, text on the system clipboard will be cleared.
- classmethod synchronized_changes(timeout, step=0.001, formats=None, initial_clipboard=None)[source]
Context manager for synchronizing local and system clipboard changes. This takes the same arguments as the
wait_for_change()
method.- Arguments:
timeout (float) – timeout in seconds.
step (float, default: 0.001) – number of seconds between each check.
formats (iterable, default: None) – if not None, only changes to the given content formats will register. If None, all formats will be observed.
initial_clipboard (Clipboard, default: None) – if a clipboard is given, the method will wait until the system clipboard differs from the instance’s contents.
Use with a Python ‘with’ block:
from dragonfly import Clipboard, Key # Copy the selected text with Ctrl+C and wait until a system # clipboard change is detected. timeout = 3 with Clipboard.synchronized_changes(timeout): Key("c-c", use_hardware=True).execute() # Retrieve the system text. text = Clipboard.get_system_text()
- classmethod wait_for_change(timeout, step=0.001, formats=None, initial_clipboard=None)[source]
Wait (poll) for the system clipboard to change.
This is a blocking method which returns whether or not the system clipboard changed within a specified timeout period.
- Arguments:
timeout (float) – timeout in seconds.
step (float, default: 0.001) – number of seconds between each check.
formats (iterable, default: None) – if not None, only changes to the given content formats will register. If None, all formats will be observed.
initial_clipboard (Clipboard, default: None) – if a clipboard is given, the method will wait until the system clipboard differs from the instance’s contents.
Windows Clipboard context manager
- class win32_clipboard_ctx(timeout=0.5, step=0.001)[source]
Python context manager for safely opening the Windows clipboard by polling for access, timing out after the specified number of seconds.
- Arguments:
timeout (float, default: 0.5) – timeout in seconds.
step (float, default: 0.001) – number of seconds between each attempt to open the clipboard.
- Notes:
The polling is necessary because the clipboard is a shared resource which may be in use by another process.
Nested usage will not close the clipboard early.
Use with a Python ‘with’ block:
with win32_clipboard_ctx(): # Do clipboard operation(s). win32clipboard.EmptyClipboard()
X11 Clipboard classes
- class BaseX11Clipboard(contents=None, text=None, from_system=False)[source]
Base X11 clipboard class.
- copy_from_system(formats=None, clear=False)[source]
Copy the system clipboard contents into this instance.
- Arguments:
formats (iterable, default: None) – if not None, only the given content formats will be retrieved. If None, all available formats will be retrieved.
clear (boolean, default: False) – if true, the system clipboard will be cleared after its contents have been retrieved.
- copy_to_system(clear=True)[source]
Copy the contents of this instance into the system clipboard.
- Arguments:
clear (boolean, default: True) – if true, the system clipboard will be cleared before this instance’s contents are transferred.
- format_x_clipboard = 13
Format for the clipboard X selection (alias of format_unicode).
- format_x_primary = 65536
Format for the primary X selection.
- format_x_secondary = 65537
Format for the secondary X selection.
Pyperclip Clipboard class
- class PyperclipClipboard(contents=None, text=None, from_system=False)[source]
Class for interacting with the system clipboard via the pyperclip Python package.
This is Dragonfly’s default clipboard class on platforms other than Windows.
Note
This class does work on Windows, however the Windows
dragonfly.windows.win32_clipboard.Win32Clipboard
class should be used instead because this class doesn’t support as many clipboard formats.- copy_from_system(formats=None, clear=False)[source]
Copy the system clipboard contents into this instance.
- Arguments:
formats (iterable, default: None) – if not None, only the given content formats will be retrieved. If None, all available formats will be retrieved.
clear (boolean, default: False) – if true, the system clipboard will be cleared after its contents have been retrieved.