| wl_data_device_manager | |
| wl_data_device_manager_destroy | 破棄 |
|---|---|
| wl_data_device_manager_create_data_source | wl_data_source の作成 |
| wl_data_device_manager_get_data_device | wl_data_device の作成 |
| wl_data_device | |
| wl_data_device_add_listener | ハンドラ設定 |
| wl_data_device_destroy | 破棄 |
| wl_data_device_release | 解放 |
| wl_data_device_start_drag | D&D の開始を要求 |
| wl_data_device_set_selection | クリップボードにデータをセット |
| wl_data_offer | |
| wl_data_offer_add_listener | ハンドラ設定 |
| wl_data_offer_accept | 指定 MIME を受け取ることを通知する |
| wl_data_offer_receive | データの送信を要求 |
| wl_data_offer_destroy | 破棄 |
| wl_data_offer_finish | D&D 処理の終了を通知 |
| wl_data_offer_set_actions | アクションを設定 |
| wl_data_source | |
| wl_data_source_add_listener | ハンドラ設定 |
| wl_data_source_offer | 対応する MIME タイプの追加 |
| wl_data_source_destroy | 破棄 |
| wl_data_source_set_actions | アクションを設定 |
wl_data_device_manager
struct wl_data_source *wl_data_device_manager_create_data_source(
struct wl_data_device_manager *wl_data_device_manager);
wl_data_source の作成
struct wl_data_device *wl_data_device_manager_get_data_device(
struct wl_data_device_manager *wl_data_device_manager,
struct wl_seat *seat);
wl_data_device の作成
wl_data_device
int wl_data_device_add_listener(struct wl_data_device *wl_data_device,
const struct wl_data_device_listener *listener, void *data);
void (*data_offer)(void *data, struct wl_data_device *data_device, struct wl_data_offer *id);
void (*enter)(void *data, struct wl_data_device *data_device, uint32_t serial,
struct wl_surface *surface, wl_fixed_t x, wl_fixed_t y, struct wl_data_offer *id);
void (*leave)(void *data, struct wl_data_device *data_device);
void (*motion)(void *data, struct wl_data_device *data_device,
uint32_t time, wl_fixed_t x, wl_fixed_t y);
void (*drop)(void *data, struct wl_data_device *data_device)
void (*selection)(void *data, struct wl_data_device *data_device, struct wl_data_offer *id);
data_offer
データの変更により、新しい wl_data_offer が作成された時。
[D&D] enter または [クリップボード] selection の前に来る。
この直後に、wl_data_offer:offer イベントが送信され、提供する MIME タイプが送られる。
[D&D] enter または [クリップボード] selection の前に来る。
この直後に、wl_data_offer:offer イベントが送信され、提供する MIME タイプが送られる。
enter
D&D ポインタが、クライアントが所有するサーフェスに入ると送信される。
leave
D&D ポインタがサーフェスから離れ、セッションが終了すると送信される。
クライアントは、この時点で wl_data_offer を破棄する必要がある。
クライアントは、この時点で wl_data_offer を破棄する必要がある。
motion
クライアントが管理しているサーフェス内で D&D ポインタが移動したときに送信される。
drop
ドロップを受け付けている状態で、ユーザーがボタンを離して、D&D 操作が終了した時。
wl_data_offer:action イベントで最後に受け取ったアクションを元に、COPY または MOVE であれば、wl_data_offer_receive() でデータを受信できる。
ver 3 以降では、wl_data_offer_finish() を実行して、操作が終了したことを通知する。
ASK の場合、クライアント側でメニューを出すなどした後、wl_data_offer_set_actions() で結果のアクションを指定、または wl_data_offer_destroy() で操作をキャンセルする必要がある。
wl_data_offer:action イベントで最後に受け取ったアクションを元に、COPY または MOVE であれば、wl_data_offer_receive() でデータを受信できる。
ver 3 以降では、wl_data_offer_finish() を実行して、操作が終了したことを通知する。
ASK の場合、クライアント側でメニューを出すなどした後、wl_data_offer_set_actions() で結果のアクションを指定、または wl_data_offer_destroy() で操作をキャンセルする必要がある。
selection
クリップボードに現在セットされているデータの wl_data_offer が通知される。
クリップボードにセットされているデータがない場合は、NULL が渡される。
キーボードフォーカスを受け取る直前、または、クライアントにキーボードフォーカスがある時に新しいクリップボードデータが設定された場合、送信される。
この直前には、MIME タイプを通知するために、wl_data_device:data_offer イベントと wl_data_offer:offer イベントが呼ばれる。
渡された wl_data_offer は、次にこのイベントが呼ばれるまで、または、クライアントがキーボードフォーカスを失うまで有効である。
クライアントは、このイベント内で、前回の wl_data_offer を破棄しなければならない。
クリップボードにセットされているデータがない場合は、NULL が渡される。
キーボードフォーカスを受け取る直前、または、クライアントにキーボードフォーカスがある時に新しいクリップボードデータが設定された場合、送信される。
この直前には、MIME タイプを通知するために、wl_data_device:data_offer イベントと wl_data_offer:offer イベントが呼ばれる。
渡された wl_data_offer は、次にこのイベントが呼ばれるまで、または、クライアントがキーボードフォーカスを失うまで有効である。
クライアントは、このイベント内で、前回の wl_data_offer を破棄しなければならない。
void wl_data_device_destroy(struct wl_data_device *wl_data_device);
ver 2 以降では、wl_data_device_release() を使う。
void wl_data_device_release(struct wl_data_device *wl_data_device);
wl_data_device_manager のバージョンが WL_DATA_DEVICE_RELEASE_SINCE_VERSION 以上なら、destroy の代わりにこちらを使う。
ver 2 から
ver 2 から
void wl_data_device_start_drag(struct wl_data_device *wl_data_device,
struct wl_data_source *source, struct wl_surface *origin,
struct wl_surface *icon, uint32_t serial);
D&D を行う側が、D&D を開始するように要求する。
source は、データソース。
NULL の場合、クライアント内部での D&D 操作となる。
ポインタの enter/leave/motion イベントは、この関数を実行したクライアントにのみ送信される。
origin は、ドラッグが始まるサーフェス。
serial は、ボタン押しイベント時に渡されたシリアル値。
icon は、カーソル形状のサーフェス (NULL 可)。
開始時は、左上がホットスポットとなっているが、開始後に wl_surface_attach() を実行することによって、位置を変更できる。
なお、形状変更時は wl_surface_commit() で適用させる必要がある。
アイコンの surface には、D&D アイコンの役割が与えられる。
サーフェスに既に別の役割がある場合は、プロトコルエラーが発生する。
wl_surface がアイコンサーフェスとして使用されなくなるまで、アイコンサーフェスの現在の入力領域と保留中の入力領域はクリアされ、wl_surface_set_input_region() は無視される。
アイコンとしての使用が終了すると、現在の入力領域と保留中の入力領域は未定義になる。
source は、データソース。
NULL の場合、クライアント内部での D&D 操作となる。
ポインタの enter/leave/motion イベントは、この関数を実行したクライアントにのみ送信される。
origin は、ドラッグが始まるサーフェス。
serial は、ボタン押しイベント時に渡されたシリアル値。
icon は、カーソル形状のサーフェス (NULL 可)。
開始時は、左上がホットスポットとなっているが、開始後に wl_surface_attach() を実行することによって、位置を変更できる。
なお、形状変更時は wl_surface_commit() で適用させる必要がある。
アイコンの surface には、D&D アイコンの役割が与えられる。
サーフェスに既に別の役割がある場合は、プロトコルエラーが発生する。
wl_surface がアイコンサーフェスとして使用されなくなるまで、アイコンサーフェスの現在の入力領域と保留中の入力領域はクリアされ、wl_surface_set_input_region() は無視される。
アイコンとしての使用が終了すると、現在の入力領域と保留中の入力領域は未定義になる。
void wl_data_device_set_selection(struct wl_data_device *wl_data_device,
struct wl_data_source *source, uint32_t serial);
source をクリップボードのデータとして設定する。
この時点で、現在クリップボードのデータを持っているのは、このクライアントとなり、データの送信が要求されたら対応する必要がある。
クリップボードの所有権を放棄したい場合は、source を NULL に設定する。
serial は、他のすべてのイベントで最後に取得したシリアル値。
この時点で、現在クリップボードのデータを持っているのは、このクライアントとなり、データの送信が要求されたら対応する必要がある。
クリップボードの所有権を放棄したい場合は、source を NULL に設定する。
serial は、他のすべてのイベントで最後に取得したシリアル値。
wl_data_offer
int wl_data_offer_add_listener(struct wl_data_offer *data_offer,
const struct wl_data_offer_listener *listener, void *data);
void (*offer)(void *data, struct wl_data_offer *data_offer, const char *mime_type); ▼ ver 3 から void (*source_actions)(void *data, struct wl_data_offer *data_offer, uint32_t source_actions); void (*action)(void *data, struct wl_data_offer *data_offer, uint32_t dnd_action);
offer
提供されている MIME タイプが送られてくる。
wl_data_offer の作成直後に送信される。
１つの MIME タイプごとにイベントが来る。
wl_data_offer の作成直後に送信される。
１つの MIME タイプごとにイベントが来る。
source_actions
D&D 実行元が対応しているアクションが通知される。
wl_data_device:enter の直前、または、D&D 中に wl_data_source_set_actions() でアクションが変更されるたびに送信される。
ver 3 から
wl_data_device:enter の直前、または、D&D 中に wl_data_source_set_actions() でアクションが変更されるたびに送信される。
ver 3 から
action
サーバーによって最終的に選択されたアクション (1つ or なし) が提示される。
wl_data_offer_set_actions() で、受け取る側のアクションが変更されると、D&D 操作中に複数回送信される。
ドロップ時には、このイベントで最後に受け取ったアクション、または、ASK の場合は wl_data_offer_set_actions() で最後に設定されたアクションを実行する必要がある。
サーバは、D&D 中に Ctrl などの装飾が押された時に、選択したアクションを変更することもできる。
wl_data_device:drop の前に、(装飾キーが押されたために) 選択されたアクションが変更されることがある。
ASK アクションの場合にも、アクションの変更が起こる可能性がある。
この段階で起こるアクションの変更は、常にクライアント間の交渉の結果であり、サーバーは関与できない。
ASK アクションでは、最終的な wl_data_offer_set_actions() および wl_data_offer_accept() は、wl_data_offer_finish() の前に実行する必要がある。
ver 3 から
wl_data_offer_set_actions() で、受け取る側のアクションが変更されると、D&D 操作中に複数回送信される。
ドロップ時には、このイベントで最後に受け取ったアクション、または、ASK の場合は wl_data_offer_set_actions() で最後に設定されたアクションを実行する必要がある。
サーバは、D&D 中に Ctrl などの装飾が押された時に、選択したアクションを変更することもできる。
wl_data_device:drop の前に、(装飾キーが押されたために) 選択されたアクションが変更されることがある。
ASK アクションの場合にも、アクションの変更が起こる可能性がある。
この段階で起こるアクションの変更は、常にクライアント間の交渉の結果であり、サーバーは関与できない。
ASK アクションでは、最終的な wl_data_offer_set_actions() および wl_data_offer_accept() は、wl_data_offer_finish() の前に実行する必要がある。
ver 3 から
void wl_data_offer_accept(struct wl_data_offer *wl_data_offer,
uint32_t serial, const char *mime_type);
D&D を受け取る側が、指定された MIME タイプを受け入れることを示す。
serial は、enter 時の値。
ver 2:
クライアントが指定 MIME タイプを受け取れるかを調べるために使われる。
D&D が成功するかどうかは別。
ver 3:
NULL の場合は、D&D を受け入れない。
受け入れる場合は、ソース側が対応しているタイプのいずれかを指定する。
NULL を設定後にドロップされた場合、D&D 操作はキャンセルされ、ソース側は wl_data_source:cancelled を受け取る。
受け取る側は、wl_data_source:action とこの関数で、ドロップの受け入れ状態を設定する必要がある。
serial は、enter 時の値。
ver 2:
クライアントが指定 MIME タイプを受け取れるかを調べるために使われる。
D&D が成功するかどうかは別。
ver 3:
NULL の場合は、D&D を受け入れない。
受け入れる場合は、ソース側が対応しているタイプのいずれかを指定する。
NULL を設定後にドロップされた場合、D&D 操作はキャンセルされ、ソース側は wl_data_source:cancelled を受け取る。
受け取る側は、wl_data_source:action とこの関数で、ドロップの受け入れ状態を設定する必要がある。
void wl_data_offer_receive(struct wl_data_offer *wl_data_offer,
const char *mime_type, int32_t fd);
MIME タイプを指定して、ソース側に対して、データの送信を要求する。
転送は渡されたファイルディスクリプタ（通常は pipe で作成）を介して行われる。
ソース側は、要求された MIME タイプのデータを書き込んだ後、fd をクローズする。
ソース側が対応していない MIME タイプでも、そのまま send イベントが要求される。
D&D を受け取る側では、データが受け取れるものかどうかを判断するために、先取りしてデータを取得したりすることができる。
転送は渡されたファイルディスクリプタ（通常は pipe で作成）を介して行われる。
ソース側は、要求された MIME タイプのデータを書き込んだ後、fd をクローズする。
ソース側が対応していない MIME タイプでも、そのまま send イベントが要求される。
D&D を受け取る側では、データが受け取れるものかどうかを判断するために、先取りしてデータを取得したりすることができる。
void wl_data_offer_finish(struct wl_data_offer *wl_data_offer);
D&D を受け取る側が、データの受信後に操作を正常に終了したことを通知する。
データの受信が終了した後に実行する。
この要求を受け取ると、コンポジタは受け取る側のクライアントに wl_data_source:dnd_finished を発行する。
この後に wl_data_offer_destroy() を実行するとエラーになる。
また、wl_data_offer_accept() で MIME タイプ を NULL に指定した後、または、wl_data_offer:action でアクションが NONE になっている状態で、この要求を実行すると、エラーが発生する。
ver 3 から
データの受信が終了した後に実行する。
この要求を受け取ると、コンポジタは受け取る側のクライアントに wl_data_source:dnd_finished を発行する。
この後に wl_data_offer_destroy() を実行するとエラーになる。
また、wl_data_offer_accept() で MIME タイプ を NULL に指定した後、または、wl_data_offer:action でアクションが NONE になっている状態で、この要求を実行すると、エラーが発生する。
ver 3 から
void wl_data_offer_set_actions(struct wl_data_offer *wl_data_offer,
uint32_t dnd_actions, uint32_t preferred_action);
D&D を受け取る側が対応可能なアクションを設定する。
サーバーがアクションを変更する場合、wl_data_source:action と wl_data_offer:action イベントを発生させることがある。
wl_data_device:enter/motion イベント時の応答として、複数回実行できる。
指定したアクションが実行できない場合、ソース側は wl_drag_source:cancelled を受け取る。
引数の dnd_actions、preferred_action は、wl_data_device_manager_dnd_actions 列挙型の値。
dnd_actions は、受け付けるアクションの複数のフラグ。
preferred_action は、優先されるアクション。dnd_actions で指定したうちのいずれか一つ。
ASK を受け付ける場合、受け取る側は、wl_data_offer_receive() でデータの送信を要求した後、wl_data_offer_set_actions() で、最終的に実行するアクション (ASK 以外) を指定する。
その後、wl_data_offer_finish() を実行して、ユーザーが選択したアクションを伝える。
最終的なアクションが wl_data_offer:source_actions で渡された中にない場合は、エラーが発生する。
ユーザ側でキャンセルが選択された場合など、ASK が却下された時は、クライアントは即座に wl_data_offer_destroy() を実行する必要がある。
ver 3 から
サーバーがアクションを変更する場合、wl_data_source:action と wl_data_offer:action イベントを発生させることがある。
wl_data_device:enter/motion イベント時の応答として、複数回実行できる。
指定したアクションが実行できない場合、ソース側は wl_drag_source:cancelled を受け取る。
引数の dnd_actions、preferred_action は、wl_data_device_manager_dnd_actions 列挙型の値。
dnd_actions は、受け付けるアクションの複数のフラグ。
preferred_action は、優先されるアクション。dnd_actions で指定したうちのいずれか一つ。
WL_DATA_DEVICE_MANAGER_DND_ACTION_NONE = 0 WL_DATA_DEVICE_MANAGER_DND_ACTION_COPY = 1 WL_DATA_DEVICE_MANAGER_DND_ACTION_MOVE = 2 WL_DATA_DEVICE_MANAGER_DND_ACTION_ASK = 4
ASK を受け付ける場合、受け取る側は、wl_data_offer_receive() でデータの送信を要求した後、wl_data_offer_set_actions() で、最終的に実行するアクション (ASK 以外) を指定する。
その後、wl_data_offer_finish() を実行して、ユーザーが選択したアクションを伝える。
最終的なアクションが wl_data_offer:source_actions で渡された中にない場合は、エラーが発生する。
ユーザ側でキャンセルが選択された場合など、ASK が却下された時は、クライアントは即座に wl_data_offer_destroy() を実行する必要がある。
ver 3 から
wl_data_source
int wl_data_source_add_listener(struct wl_data_source *wl_data_source,
const struct wl_data_source_listener *listener, void *data);
void (*target)(void *data, struct wl_data_source *wl_data_source, const char *mime_type);
void (*send)(void *data, struct wl_data_source *wl_data_source,
const char *mime_type, int32_t fd);
void (*cancelled)(void *data, struct wl_data_source *wl_data_source);
void (*dnd_drop_performed)(void *data, struct wl_data_source *wl_data_source);
void (*dnd_finished)(void *data, struct wl_data_source *wl_data_source);
void (*action)(void *data, struct wl_data_source *wl_data_source, uint32_t dnd_action);
target
D&D を受け入れる側で、ポインタの enter/move イベントが受け入れられた時に送信される。
受け取る側がドロップを受け付けない状態の場合、mime_type は NULL となる。
受け取る側がドロップを受け付けない状態の場合、mime_type は NULL となる。
send
サーバーや他のクライアントからデータを要求された時。
fd に write() で書き込んでデータを送信し、close() で閉じる。
fd に write() で書き込んでデータを送信し、close() で閉じる。
cancelled
この時点で、渡された wl_data_source は有効ではないため、この wl_data_source を破棄する必要がある。
これが起こる原因はいくつかある。
・ クライアントがデータを持っている状態で、他のクライアントがクリップボードデータをセットして、置き換わった時。
・ D&D 時、受け取る側が提供された MIME タイプのいずれも受け入れなかった。
・ D&D 時、受け取る側とソース側でアクションが一致しなかった。
・ D&D 時、ボタンを離した先が有効なサーフェス上ではなかった。
・ サーバーが D&D 操作をキャンセルした（サーバー側のタイムアウトなど）。
これが起こる原因はいくつかある。
・ クライアントがデータを持っている状態で、他のクライアントがクリップボードデータをセットして、置き換わった時。
・ D&D 時、受け取る側が提供された MIME タイプのいずれも受け入れなかった。
・ D&D 時、受け取る側とソース側でアクションが一致しなかった。
・ D&D 時、ボタンを離した先が有効なサーフェス上ではなかった。
・ サーバーが D&D 操作をキャンセルした（サーバー側のタイムアウトなど）。
dnd_drop_performed
ユーザーがボタンを離して、受け取る側がドロップを受け付けた時。
wl_data_device:drop の後に来る。
操作のキャンセル時は発生せず、wl_data_source:cancelled が発生する。
wl_data_source はこの後も使用される可能性があるため、ここでは破棄しないこと。
ver 3 から
wl_data_device:drop の後に来る。
操作のキャンセル時は発生せず、wl_data_source:cancelled が発生する。
wl_data_source はこの後も使用される可能性があるため、ここでは破棄しないこと。
ver 3 から
dnd_finished
D&D 処理がすべて終了した。
ソース側は wl_data_source を自由に破棄し、関連するすべてのデータを解放することができる。
アクションが MOVE だった場合、ソース側は移動元データを削除できる。
ver 3 から
ソース側は wl_data_source を自由に破棄し、関連するすべてのデータを解放することができる。
アクションが MOVE だった場合、ソース側は移動元データを削除できる。
ver 3 から
action
サーバーが最終的に選択したアクション (１つまたは無し) が示される。
D&D 操作中、主に wl_data_offer_set_actions() によって、受け取る側が対応アクションを変更した時、wl_data_device がサーフェスに入る/離れるときに、複数回送信されます。
ASK アクション時は、wl_data_source:dnd_drop_performed の後にこのイベントが来る。
この場合、最終的な wl_data_source:action イベントは wl_data_source:dnd_finished の直前に発生する。
選択されたアクションは変更される可能性がある (ASK → MOVE など)。
したがって、最終アクションの実行は常に wl_data_offer:dnd_finished 時に行う必要がある。
D&D 実行元では、このアクションを元に、対応したカーソル形状へと変更できる。
ver 3 から
D&D 操作中、主に wl_data_offer_set_actions() によって、受け取る側が対応アクションを変更した時、wl_data_device がサーフェスに入る/離れるときに、複数回送信されます。
ASK アクション時は、wl_data_source:dnd_drop_performed の後にこのイベントが来る。
この場合、最終的な wl_data_source:action イベントは wl_data_source:dnd_finished の直前に発生する。
選択されたアクションは変更される可能性がある (ASK → MOVE など)。
したがって、最終アクションの実行は常に wl_data_offer:dnd_finished 時に行う必要がある。
D&D 実行元では、このアクションを元に、対応したカーソル形状へと変更できる。
ver 3 から
void wl_data_source_offer(struct wl_data_source *wl_data_source, const char *mime_type);
ソースとして対応している MIME タイプを追加する。
複数のタイプを提供するために複数回呼び出すことができる。
複数のタイプを提供するために複数回呼び出すことができる。
void wl_data_source_set_actions(struct wl_data_source *wl_data_source, uint32_t dnd_actions);
ソース側が対応可能なアクションを設定する。
wl_data_device_start_drag() の前に一度だけ行う必要がある。
サーバーが状況に応じてアクションを変更する場合、wl_data_source:action と wl_data_offer:action イベントを発生させることがある。
dnd_actions 引数は、wl_data_device_manager_dnd_actions 列挙型のフラグ値。
ver 3 から
wl_data_device_start_drag() の前に一度だけ行う必要がある。
サーバーが状況に応じてアクションを変更する場合、wl_data_source:action と wl_data_offer:action イベントを発生させることがある。
dnd_actions 引数は、wl_data_device_manager_dnd_actions 列挙型のフラグ値。
ver 3 から