Clipboard toolkit

Dragonfly’s clipboard toolkit offers easy access to and manipulation of the Windows system clipboard. The dragonfly.windows.clipboard.Clipboard class forms the core of this toolkit. Each instance of this class is a container with a structure similar to the Windows system clipboard, mapping content formats to content data.

Usage examples

An instance of something contains clipboard data. The data stored within an instance can be transferred to and from the Windows system clipboard as follows: (before running this example, the text “asdf” was copied into the Windows 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 Windows 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.all 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)

Clipboard class

class Clipboard(contents=None, text=None, from_system=False)

copy_from_system(formats=None, clear=False)

Copy the Windows 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 Windows system clipboard will be cleared after its contents have been retrieved.

copy_to_system(clear=True)

Copy the contents of this instance into the Windows system clipboard.

Arguments:

• clear (boolean, default: True) – if true, the Windows system clipboard will be cleared before this instance’s contents are transferred.

get_format(format)

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()

Retrieve this instance’s text content. If no text content is available, this method returns None.

has_format(format)

Determine whether this instance has content for the given format.

Arguments:

• format (int) – the clipboard format to look for.

has_text()

Determine whether this instance has text content.