clipboard_scope Class Reference
[Windows Clipboard Library]

#include <winstl/clipboard/clipboard_scope.hpp>

Inheritance diagram for clipboard_scope:

List of all members.

---

Detailed Description

This class acquires access to the Win32 clipboard, and acts as a facade over the clipboard API.

The class provides a simple and straightforward facade to the clipboard, while at the same time acquiring and releasing ownership of the clipboard. The following code acquires access to the clipboard, and sets a string on to it:

  // 1. Set the data on the clipboard
  {
    winstl::clipboard_scope     scope;

    scope.set_data("The data");
  }

As long as no other thread/process changes the clipboard contents in the meanwhile, this can then be read back, as follows:

  // 2. Get the data from the clipboard
  {
    winstl::clipboard_scope     scope;
    char const*                 str;

    scope.get_data(str);

    std::cout << "Clipboard data: " << str << std::endl;
  }

In each case, the lifetime of the clipboard_scope is scoped with a block - { } - in order to release ownership of the clipboard.

Note:

All the methods throw an instance of clipboard_scope_exception if they fail.

Examples:

by_library/windows_clipboard/clipboard_scope/clipboard_scope.cpp.

Types
typedef clipboard_scope	class_type
	The parameterisation of the class.
typedef global_allocator< void >	allocator_type
Public Member Functions
Construction
	clipboard_scope (HWND hwndOwner=NULL) throw ( clipboard_scope_exception )
	Takes ownership of the clipboard.
	~clipboard_scope () throw ()
	Gives up ownership of the clipboard.
Attributes
allocator_type	get_allocator () const
	Returns a copy of the allocator used by the class.
Operations
void	clear () throw ( clipboard_scope_exception )
	Empties the clipboard.
HWND	owner () const
	Returns the current owner of the clipboard.
bool	is_fmt_available (UINT fmt) const
	Indicates whether a given format is available.
void	set_data (UINT fmt, HANDLE hData) throw ( clipboard_scope_exception )
	Sets the given data with the given format into the clipboard.
void	set_data (char const *str) throw ( clipboard_scope_exception )
	Sets the given text to the clipboard with CF_TEXT format.
void	set_data (char const *str, size_t n) throw ( clipboard_scope_exception )
	Sets the given text to the clipboard with CF_TEXT format.
void	set_data (wchar_t const *str) throw ( clipboard_scope_exception )
	Sets the given text to the clipboard with CF_UNICODETEXT format.
void	set_data (wchar_t const *str, size_t n) throw ( clipboard_scope_exception )
	Sets the given text to the clipboard with CF_UNICODETEXT format.
void	set_data (HBITMAP hBmp) throw ( clipboard_scope_exception )
	Sets the bitmap to the clipboard with CF_BITMAP format.
void	set_data (HDROP hDrop) throw ( clipboard_scope_exception )
	Sets the bitmap to the clipboard with CF_HDROP format.
void	set_data (HENHMETAFILE hEmf) throw ( clipboard_scope_exception )
	Sets the bitmap to the clipboard with CF_ENHMETAFILE format.
void	set_data (HPALETTE hPal) throw ( clipboard_scope_exception )
	Sets the bitmap to the clipboard with CF_PALETTE format.
HANDLE	get_data (UINT fmt) const throw ( clipboard_scope_exception )
	Gets the data with the requested format from the clipboard.
void	get_data (char const *&str) const throw ( clipboard_scope_exception )
	Gets the clipboard data with the CF_TEXT format.
void	get_data (wchar_t const *&str) const throw ( clipboard_scope_exception )
	Gets the clipboard data with the CF_UNICODETEXT format.
void	get_data (HBITMAP &hBmp) const throw ( clipboard_scope_exception )
	Gets the clipboard data with the CF_BITMAP format.
void	get_data (HDROP &hDrop) const throw ( clipboard_scope_exception )
	Gets the clipboard data with the CF_HDROP format.
void	get_data (HENHMETAFILE &hEmf) const throw ( clipboard_scope_exception )
	Gets the clipboard data with the CF_ENHMETAFILE format.
void	get_data (HPALETTE &hPal) const throw ( clipboard_scope_exception )
	Gets the clipboard data with the CF_PALETTE format.

---

Member Typedef Documentation

typedef clipboard_scope class_type

The parameterisation of the class.

Reimplemented from global_allocator< void >.

---

Constructor & Destructor Documentation

clipboard_scope

(

HWND

hwndOwner = NULL

)

throw ( clipboard_scope_exception ) [explicit]

Takes ownership of the clipboard.

Parameters:

hwndOwner

Window to be associated as owner of the clipboard. May be NULL, in which case the current thread owns the clipboard.

~clipboard_scope

(

)

throw ()

Gives up ownership of the clipboard.

---

Member Function Documentation

allocator_type get_allocator

(

)

const

Returns a copy of the allocator used by the class.

Examples:

by_library/windows_clipboard/clipboard_scope/clipboard_scope.cpp.

void clear

(

)

throw ( clipboard_scope_exception )

Empties the clipboard.

HWND owner

(

)

const

Returns the current owner of the clipboard.

bool is_fmt_available

(

UINT

fmt

)

const

Indicates whether a given format is available.

void set_data	(	UINT	fmt,
		HANDLE	hData
	)			throw ( clipboard_scope_exception )

Sets the given data with the given format into the clipboard.

Examples:

by_library/windows_clipboard/clipboard_scope/clipboard_scope.cpp.

void set_data

(

char const *

str

)

throw ( clipboard_scope_exception )

Sets the given text to the clipboard with CF_TEXT format.

void set_data	(	char const *	str,
		size_t	n
	)			throw ( clipboard_scope_exception )

Sets the given text to the clipboard with CF_TEXT format.

void set_data

(

wchar_t const *

str

)

throw ( clipboard_scope_exception )

Sets the given text to the clipboard with CF_UNICODETEXT format.

void set_data	(	wchar_t const *	str,
		size_t	n
	)			throw ( clipboard_scope_exception )

Sets the given text to the clipboard with CF_UNICODETEXT format.

void set_data

(

HBITMAP

hBmp

)

throw ( clipboard_scope_exception )

Sets the bitmap to the clipboard with CF_BITMAP format.

void set_data

(

HDROP

hDrop

)

throw ( clipboard_scope_exception )

Sets the bitmap to the clipboard with CF_HDROP format.

void set_data

(

HENHMETAFILE

hEmf

)

throw ( clipboard_scope_exception )

Sets the bitmap to the clipboard with CF_ENHMETAFILE format.

void set_data

(

HPALETTE

hPal

)

throw ( clipboard_scope_exception )

Sets the bitmap to the clipboard with CF_PALETTE format.

HANDLE get_data

(

UINT

fmt

)

const throw ( clipboard_scope_exception )

Gets the data with the requested format from the clipboard.

Note:

The handle must be used before the clipboard_scope destructor is invoked, or its contents copied

Examples:

by_library/windows_clipboard/clipboard_scope/clipboard_scope.cpp.

void get_data

(

char const *&

str

)

const throw ( clipboard_scope_exception )

Gets the clipboard data with the CF_TEXT format.

Note:

The string pointer must be used before the clipboard_scope destructor is invoked, or its contents copied

void get_data

(

wchar_t const *&

str

)

const throw ( clipboard_scope_exception )

Gets the clipboard data with the CF_UNICODETEXT format.

Note:

The string pointer must be used before the clipboard_scope destructor is invoked, or its contents copied

void get_data

(

HBITMAP &

hBmp

)

const throw ( clipboard_scope_exception )

Gets the clipboard data with the CF_BITMAP format.

Note:

The bitmap handle must be used before the clipboard_scope destructor is invoked, or its contents copied

void get_data

(

HDROP &

hDrop

)

const throw ( clipboard_scope_exception )

Gets the clipboard data with the CF_HDROP format.

Note:

The drop handle must be used before the clipboard_scope destructor is invoked, or its contents copied

void get_data

(

HENHMETAFILE &

hEmf

)

const throw ( clipboard_scope_exception )

Gets the clipboard data with the CF_ENHMETAFILE format.

Note:

The metafile handle must be used before the clipboard_scope destructor is invoked, or its contents copied

void get_data

(

HPALETTE &

hPal

)

const throw ( clipboard_scope_exception )

Gets the clipboard data with the CF_PALETTE format.

Note:

The palette handle must be used before the clipboard_scope destructor is invoked, or its contents copied

---

The documentation for this class was generated from the following file:

• winstl/clipboard/clipboard_scope.hpp