Palm Programmer's Laboratory
Palm OS Programmer's API Reference/6
この章では Clipboard.h で定義されているクリップボード API について説明します。この章では、以下のことについて説明します。
クリップボード データ構造体 ^TOP^
ClipboardFormatType Enum ^TOP^
目的
ClipboardFormatType 列挙体（原文: enum）はクリップボードに追加される、または、クリップボードから取得されるデータの型を指定します。
Prototype
enum clipboardFormats {
clipboardText,
clipboardInk,
clipboardBitmap };
typedef enum clipboardFormats
ClipboardFormatType;
定数
- clipboardText
- テキスト データ。これは、最も一般的に使われるクリップボードです。
- clipboardInk
- 予約されています。
- clipboardBitmap
- ビットマップ データ
コメント
各型のクリップボードのデータは別々に維持されます。つまり、クリップボードにテキストの文字列を追加し、それからビットマップを追加し、それからクリップボードから clipboardText アイテムを取得する操作を行った場合、ビットマップの前に追加した文字列を受け取ります。ビットマップはテキスト データを上書きしません。逆もまた真です。
クリップボード関数 ^TOP^
ClipboardAddItem 関数 ^TOP^
目的
指定されたクリップボードに渡されたアイテムを追加します。渡されたアイテムと同じ型の現在のアイテム（がもしあれば）を置き換えます。
宣言されている場所
Clipboard.h
Prototype
void ClipboardAddItem ( const ClipboardFormatType format, const void *ptr, UInt16 length )
パラメータ
- → format
- テキスト、インク（？原文は ink）、ビットマップなど。ClipboardFormatType を参照してください。
- → ptr
- クリップボードにあるアイテムへのポインタ
- → length
- クリップボードにあるアイテムのサイズ（バイト単位）
返り値
返り値はありません。
コメント
クリップボードはこの関数に渡されるデータのコピーを作成します。そのため、クリップボードに渡したデータを解放しても、クリップボードの内容を破壊することはありません。また、クリップボードに定数データやスタック-ベースのデータを渡すこともできます。
- WARNING!
- クリップボードに null で終了する文字列を追加することはできません。
参照
ClipboardAppendItem 関数 ^TOP^
目的
クリップボードにあるアイテムにデータを付加します。
宣言されている場所
Clipboard.h
Prototype
Err ClipboardAppendItem( const ClipboardFormatType format, const void *ptr, UInt16 length )
パラメータ
- → format
- テキスト、インク（？原文は ink）、ビットマップなど。ClipboardFormatType を参照してください。この関数は clipboardType フォーマットに対してのみ使用されることを意図しています。
- → ptr
- クリップボードにあるアイテムに付加するデータへのポインタ
- → length
- クリップボードに付加するデータのサイズ（バイト単位）
'''返り値
成功時には 0 を返します。クリップボードにデータを付加するたために十分な空き容量が無い場合、memErrNotEnoughSpace を返します。
コメント
この関数は ClipboardAddItem() とは異なり、すでにあるデータを上書きしません。この関数は、いくつかの小さな分割された断片から、クリップボード上に大きなテキスト アイテムを作成することを可能にします。他のアプリケーションがクリップボードからテキストを取得するとき、クリップボードにあるアイテムは単一のものとして取得されます。
この関数は、単純に、指定されたアイテムをフォーマット解析しようとせずにクリップボード上にすでにあるアイテムに付加します。この関数は、比較的短い間隔で何度か呼び出され、アプリケーションが付加するのが終了するまで他のアプリケーションがクリップボードからテキストを取得しようとはしないという仮定に基づいています。
互換性
3.2 New Feature Set が存在する場合にのみ、実行されます。
ClipboardGetItem 関数 ^TOP^
目的
指定された型のクリップボードの内容のハンドルとクリップボード アイテムの長さを返します。
宣言されている場所
Clipboard.h
Prototype
MemHandle ClipboardGetItem( const ClipboardFormatType format, UInt16 *length )
パラメータ
- → format
- テキスト、インク（？原文は ink）、ビットマップなど。ClipboardFormatType を参照してください。
- ← length
- クリップボード アイテムの長さがここに返されます（バイト単位）
返り値
クリップボード アイテムのハンドル
コメント
返されるハンドルは実際のクリップボード チャンクへのハンドルです。返されるハンドルは、メモリを変更する API （FldSetTextHandle() など）に渡すべきものではありません。このハンドルをチャンクへ Read-only アクセスするためのものと考えてください。可能な限りすぐにクリップボードの内容をアプリケーション自身のストレージへコピーし、この関数によって返されるハンドルの代わりにそのコピーを使用してください。
この関数によって返されるハンドルを解放しないでください。それは、クリップボードに新しいアイテムが追加されたときに、解放されます。
クリップボードから取得されるテキストは null 終端子を持っていません。length パラメータを、取得した文字列のバイト長を調べるために使用しなければなりません。
