Click on the banner to return to the Class Reference home page.

©Copyright 1996 Rogue Wave Software

RWCLIPstreambuf

RWCLIPstreambufstreambuf

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()
{
   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.\n";
   ostr << "Might as well add a double: " << d << endl;
   ostr.put('\0');        // 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 Constructors

 
RWCLIPstreambuf();
RWCLIPstreambuf(HANDLE hMem);

Public Destructor

 
~RWCLIPstreambuf();

Public Member Functions

 





HANDLE
str();