Tools.h++ 7.0 クラスライブラリ・リファレンスマニュアル: RWCLIPstreambuf

バナーをクリックすれば目次に戻ります

Copyright 1999 Rogue Wave Software
Copyright 1999 Sun Microsystems, Inc.

## RWCLIPstreambuf

### 形式

  RWCLIPstreambuf streambuf

### 説明

      #include <rw/winstrea.h>
      #include <iostream.h>
      iostream str( new RWCLIPstreambuf() );

  クラス RWCLIPstreambuf は、Microsoft Windows 大域メモリーとの間で一連の文字を読み書きするために特殊化された streambuf です。Windows クリップボード機能を通してデータを交換するのに使用できます。

  このクラスには、動的と静的の 2 つの動作モードがあります。動的モードでは、必要に応じてメモリーの割り当てと再割り当てが行われます。内部バッファーの現在のサイズに比べて挿入する文字数が多すぎる場合、バッファーのサイズが変更され、必要に応じて古い文字が新しいメモリーにコピーされます。これはユーザーにはわかりません。このモードは、主に「挿入」、すなわちクリップボードの「カットアンドコピー」に使用されます。静的モードでは、バッファー streambuf は特定のメモリー領域から作成されます。再割り当ては行われません。このモードは、主に「抽出」、すなわちクリップボードの「ペースト」に使用されます。

  動的モードでは、RWCLIPstreambuf は、メンバー関数 `str()` が呼び出されるまで、割り当てられたメモリーを「所有」します。`str()` はバッファーを「フリーズ」し、ロック解除された Windows ハンドルを RWCLIPstreambuf に返します。それ以上挿入した場合の影響は定義されていません。`str()` が呼び出されるまでは、割り当てられたメモリーを解放するのは RWCLIPstreambuf デストラクタの責任です。`str()` が呼び出された後は、ユーザーの責任になります。

  静的モードでは、メモリーハンドルを解放するのはユーザーの責任です。ただし、コンストラクタがハンドルをロックして間接参照するので、デストラクタか `str()` が呼び出されるまで、ユーザーはメモリーを解放してはなりません。デストラクタと `str()` のどちらかがハンドルをロック解除します。

### 持続性

  なし

### 例

      //命令: Windows プログラムとしてコンパイルする
      //このプログラムを実行し、好みのテキストエディタかワープロで、ペーストを選択
      //して結果を確認すること

      #include <rw/winstrea.h>

      #include <stdlib.h>
      #include <iostream.h>
      #include <windows.h>

      void postToClipboard(HWND owner);

      main()
      {
         postToClipboard(NULL);

         return 0;
      }

      // Windows の HANDLE をこの関数に渡し、ostr を使ってクリップボードに値を
      // 渡す

      void postToClipboard(HWND owner)
      {
         //clipstream バッファーをヒープに構築する
         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');        // 終端ヌルを付ける

         // streambuf をロックして、そのハンドルを獲得する
         HANDLE hMem = buf->str();

         OpenClipboard(owner);
         EmptyClipboard();
         SetClipboardData(CF_TEXT, hMem);
         CloseClipboard();

         // バッファーは削除しないこと。現在、それは Windows の責任である
      }

  クリップボードの所有者は、パラメータ「Owner」として渡されます。作成されるのは従来型の ostream ですが、関連する streambuf として RWCLIPstreambuf を使用するところだけが異なります。Windows 大域メモリーに文字が挿入される以外は、`cout` などの他の ostream とほぼ同様に使用できます。

  いくつかのテキストと倍精度浮動小数点数が ostream に挿入されます。最後に、Windows の HANDLE を返すメンバー関数 `str()` が呼び出されます。クリップボードが開いて空になり、`CF_TEXT` 形式で新しいデータが入れられます。単純な ostream を使って出力がフォーマットされたので、この場合は `CF_TEXT` が適切です。その代わりに、RWbostream や RWpostream などの特殊化仮想ストリームクラスが使われた場合、形式はもっと複雑になります。この場合、ユーザーは Windows 関数 `RegisterClipboardFormat()` を使って自分の形式を登録しておくことができます。

### 公開コンストラクタ

      RWCLIPstreambuf();

    空の RWCLIPstreambuf を動的モードで作成します。結果は、他の streambuf を使用できる場合はどこでも使用できます。必要に応じて、新しい文字を入れるメモリーが割り当てられます。

      RWCLIPstreambuf(HANDLE hMem);

    大域ハンドル `hMem` を持つメモリーブロックを使って、RWCLIPstreambuf を静的モードで構築します。このメモリーブロックのサイズを超えて、獲得と挿入を行った場合の影響は規定されていません。

### 公開デストラクタ

      ~RWCLIPstreambuf();

    メンバー関数 `str()` が呼び出されていない場合、デストラクタはハンドルをロック解除し、動的モードであればそれを解放します。

### 公開メンバー関数

    RWCLIPstreambuf は streambuf から継承するので、後者のメンバー関数のどれでも使用できます。さらに、RWCLIPstreambuf は strstreambuf に類似した設計となっています。ただし、`str()` の戻り型は `char*` ではなく `HANDLE` ですので注意してください。

      HANDLE
      str();

    使用する大域メモリーへの (ロック解除された) `HANDLE` を返します。ここで、RWCLIPstreambuf は「フリーズしている」ものとみなす必要があります。それ以上文字を挿入した場合の影響は定義されていません。RWCLIPstreambuf が動的モードで構築され、何も挿入されていない場合は、`NULL` の `HANDLE` が返されることがあります。静的モードで構築された場合は、RWCLIPstreambuf を構築するのに使用したハンドルが返されます。