
.. _RefClipboard:

Clipboard toolkit
============================================================================

Dragonfly's clipboard toolkit offers easy access to and manipulation of 
the Windows system clipboard.  The 
:class:`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 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
----------------------------------------------------------------------------

.. autoclass:: dragonfly.windows.clipboard.Clipboard
   :members:
