RWCLIPstreambuf(3C++) RWCLIPstreambuf(3C++)
NameRWCLIPstreambuf - Rogue Wave library class
Synopsis
#include <rw/winstrea.h>
#include <iostream.h>
iostream str( new RWCLIPstreambuf() );
Description
Class RWCLIPstreambuf is a specialized streambuf that gets and puts
sequences of characters to Microsoft Windows global memory. It can be
used to exchange data through Windows clipboard facility. The class has
two modes of operation: dynamic and static. In dynamic mode, memory is
allocated and reallocated as needed. If too many characters are inserted
into the internal buffer for its present size, then it will be resized
and old characters copied over into any new memory as necessary. This is
transparent to the user. It is expected that this mode would be used
primarily for "insertions," i.e., clipboard "cuts" and "copies." In
static mode, the buffer streambuf is constructed from a specific piece of
memory. No reallocations will be done. It is expected that this mode
would be used primarily for "extractions," i.e., clipboard "pastes." In
dynamic mode, the RWCLIPstreambuf "owns" any allocated memory until the
member function str() is called, which "freezes" the buffer and returns
an unlocked Windows handle to it. The effect of any further insertions
is undefined. Until str() has been called, it is the responsibility of
the RWCLIPstreambuf destructor to free any allocated memory. After the
call to str(), it becomes the user's responsibility. In static mode, the
user has the responsibility for freeing the memory handle. However,
because the constructor locks and dereferences the handle, you should not
free the memory until either the destructor or str() has been called,
either of which will unlock the handle.
Persistence
None
Example
//Instructions: compile as a Windows program.
//Run this program, then using your favorite text editor or word
//processor, select paste and see the result!
#include <rw/winstrea.h>
#include <stdlib.h>
#include <iostream.h>
#include <windows.h>
void postToClipboard(HWND owner);
main()
{
Page 1
RWCLIPstreambuf(3C++) RWCLIPstreambuf(3C++)
postToClipboard(NULL);
return 0;
}
// PASS YOUR WINDOW HANDLE TO THIS FUNCTION THEN PASS YOUR VALUES
// TO THE CLIPBOARD USING ostr.
void postToClipboard(HWND owner)
{
//Build the clipstream buffer on the heap
RWCLIPstreambuf* buf = new
RWCLIPstreambuf();
ostream ostr(buf);
double d = 12.34;
ostr << "Some text to be exchanged through the clipboard.0;
ostr << "Might as well add a double: " << d << endl;
ostr.put(' '); // Include the terminating null
// Lock the streambuf, get its handle:
HANDLE hMem = buf->str();
OpenClipboard(owner);
EmptyClipboard();
SetClipboardData(CF_TEXT, hMem);
CloseClipboard();
// Don't delete the buffer!. Windows is now responsible for it.
}
The owner of the clipboard is passed in as parameter "owner". A
conventional ostream is created, except that it uses an RWCLIPstreambuf
as its associated streambuf. It can be used much like any other ostream,
such as cout, except that characters will be inserted into Windows global
memory. Some text and a double is inserted into the ostream. Finally,
member function str() is called which returns a Windows HANDLE. The
clipboard is then opened, emptied, and the new data put into it with
format CF_TEXT which, in this case, is appropriate because a simple
ostream was used to format the output. If a specializing virtual streams
class such as RWbostream or RWpostream had been used instead, the format
is not so simple. In this case, the user might want to register his or
her own format, using the Windows function RegisterClipboardFormat().
Public ConstructorsRWCLIPstreambuf();
Constructs an empty RWCLIPstreambuf in dynamic mode. The results can be
used anywhere any other streambuf can be used. Memory to accomodate new
characters will be allocated as needed.
RWCLIPstreambuf(HANDLE hMem);
Constructs an RWCLIPstreambuf in static mode, using the memory block with
global handle hMem. The effect of gets and puts beyond the size of this
Page 2
RWCLIPstreambuf(3C++) RWCLIPstreambuf(3C++)
memory block is unspecified.
Public Destructor
~RWCLIPstreambuf();
If member function str() has not been called, the destructor unlocks the
handle and, if in dynamic mode, also frees it.
Public Member Functions
Because RWCLIPstreambuf inherits from streambuf, any of the latter's
member functions can be used. Furthermore, RWCLIPstreambuf has been
designed to be analogous to strstreambuf. However, note that the return
type of str() is a HANDLE, rather than a char*.
HANDLE
str();
Returns an (unlocked) HANDLE to the global memory being used. The
RWCLIPstreambuf should now be regarded as "frozen": the effect of
inserting any more characters is undefined. If the RWCLIPstreambuf was
constructed in dynamic mode, and nothing has been inserted, then the
returned HANDLE may be NULL. If it was constructed in static mode, then
the returned handle will be the handle used to construct the
RWCLIPstreambuf.
Page 3
