xdg-shell

xdg_wm_base
xdg_wm_base_add_listenerハンドラ設定
xdg_wm_base_destroy破棄
xdg_wm_base_create_positionerxdg_positioner を作成
xdg_wm_base_get_xdg_surfacexdg_surface を作成
xdg_wm_base_pongping に応答
xdg_surface
xdg_surface_add_listenerハンドラ設定
xdg_surface_destroy破棄
xdg_surface_get_toplevelxdg_toplevel の作成
xdg_surface_get_popupxdg_popup の作成
xdg_surface_set_window_geometry実体の範囲をセット
xdg_surface_ack_configureconfigure イベントへの応答
xdg_toplevel
xdg_toplevel_add_listenerハンドラ設定
xdg_toplevel_destroyウィンドウの破棄
xdg_toplevel_set_parent親をセット
xdg_toplevel_set_titleタイトル設定
xdg_toplevel_set_app_idアプリケーション識別子を設定
xdg_toplevel_show_window_menuウィンドウメニューの表示
xdg_toplevel_moveユーザー操作による移動を開始
xdg_toplevel_resizeユーザー操作によるサイズ変更を開始
xdg_toplevel_set_max_sizeウィンドウの最大サイズを設定
xdg_toplevel_set_min_sizeウィンドウの最小サイズを設定
xdg_toplevel_set_maximized最大化
xdg_toplevel_unset_maximized最大化を戻す
xdg_toplevel_set_fullscreenフルスクリーンにする
xdg_toplevel_unset_fullscreenフルスクリーンを戻す
xdg_toplevel_set_minimized最小化する
xdg_popup
xdg_popup_add_listenerハンドラ設定
xdg_popup_destroy破棄
xdg_popup_grab明示的にグラブ
xdg_positioner
xdg_positioner_destroy破棄
xdg_positioner_set_sizeサイズをセット
xdg_positioner_set_anchor_rect親のアンカー矩形をセット
xdg_positioner_set_anchorアンカー矩形の辺をセット
xdg_positioner_set_gravity配置方向をセット
xdg_positioner_set_constraint_adjustment位置とサイズの調整の設定
xdg_positioner_set_offsetオフセット位置をセット
xdg_wm_base
int xdg_wm_base_add_listener(struct xdg_wm_base *xdg_wm_base,
    const struct xdg_wm_base_listener *listener, void *data);
void (*ping)(void *data, struct xdg_wm_base *xdg_wm_base, uint32_t serial);
ping
クライアントが応答可能かどうか。pong を実行する。
void xdg_wm_base_destroy(struct xdg_wm_base *xdg_wm_base);
破棄
struct xdg_positioner *xdg_wm_base_create_positioner(struct xdg_wm_base *xdg_wm_base);
サーフェスを配置するための xdg_positioner を作成。
struct xdg_surface *xdg_wm_base_get_xdg_surface(
    struct xdg_wm_base *xdg_wm_base, struct wl_surface *surface);
ウィンドウ用の xdg_surface を作成する。
void xdg_wm_base_pong(struct xdg_wm_base *xdg_wm_base, uint32_t serial);
ping イベントに応答する。
xdg_surface
int xdg_surface_add_listener(struct xdg_surface *xdg_surface,
    const struct xdg_surface_listener *listener, void *data);
void (*configure)(void *data, struct xdg_surface *xdg_surface, uint32_t serial);
configure
ウィンドウの状態が確定した。

クライアントは、ウィンドウの新しい状態を commit する前に、xdg_surface_ack_configure() を実行する必要がある。

複数の configure イベントが来た場合、最後の configure イベント以外は無視できる。
void xdg_surface_destroy(struct xdg_surface *xdg_surface);
破棄
struct xdg_toplevel *xdg_surface_get_toplevel(struct xdg_surface *xdg_surface);
サーフェスをトップレベルウィンドウにする。
struct xdg_popup *xdg_surface_get_popup(struct xdg_surface *xdg_surface,
    struct xdg_surface *parent, struct xdg_positioner *positioner);
サーフェスをポップアップウィンドウにする。
void xdg_surface_set_window_geometry(struct xdg_surface *xdg_surface,
    int32_t x, int32_t y, int32_t width, int32_t height);
ウィンドウの実体範囲 (影などの部分を除いた範囲) をセット。

ウィンドウの位置やサイズをセットするものではない。
commit 時に適用される。

設定されると、それを解除することはできない。
新しいサブサーフェスまたは wl_buffer がアタッチされても、この関数が実行されるまでは範囲は変化しない。
void xdg_surface_ack_configure(struct xdg_surface *xdg_surface, uint32_t serial);
configure イベント時にサーフェスを commit する場合、commit の前に実行する必要がある。
serial は configure イベントで渡された値をそのまま渡す。

例えば、トップレベルの場合、コンポーザーはこの情報を使用して、最大化状態またはフルスクリーン状態の時、サーフェスを左上に移動させることができる。

この関数の直後にすぐに commit する必要はない。
次回の commit の前に、何回か ack_configure を実行することもできる。
xdg_toplevel
int xdg_toplevel_add_listener(
    struct xdg_toplevel *xdg_toplevel,
    const struct xdg_toplevel_listener *listener, void *data);
void (*configure)(void *data, struct xdg_toplevel *xdg_toplevel,
    int32_t width, int32_t height, struct wl_array *states);

void (*close)(void *data, struct xdg_toplevel *xdg_toplevel);
configure
サイズ変更や状態の変更があった時。
ただし、この変更はすぐには適用されない。

width か height が 0 の場合は、状態の変更のみ。

states は、各値が uint32_t (enum xdg_toplevel_state) の wl_array 配列になっている。

XDG_TOPLEVEL_STATE_MAXIMIZED = 1,
XDG_TOPLEVEL_STATE_FULLSCREEN = 2,
XDG_TOPLEVEL_STATE_RESIZING = 3,
XDG_TOPLEVEL_STATE_ACTIVATED = 4,
▼ ver 2 から
XDG_TOPLEVEL_STATE_TILED_LEFT = 5,
XDG_TOPLEVEL_STATE_TILED_RIGHT = 6,
XDG_TOPLEVEL_STATE_TILED_TOP = 7,
XDG_TOPLEVEL_STATE_TILED_BOTTOM = 8,
close
ユーザーによってウィンドウを閉じる要求が行われた時。

サーバー側の操作などでアプリを閉じる操作が実行された時。
クライアントはこの要求を無視したりしてもよい。
void xdg_toplevel_destroy(struct xdg_toplevel *xdg_toplevel);
ウィンドウを非表示にして破棄する。
void xdg_toplevel_set_parent(struct xdg_toplevel *xdg_toplevel,
    struct xdg_toplevel *parent);
このサーフェスの「親」を設定する。

親のウィンドウよりも常に前面に表示される。

親は、このサーフェスが表示されている限りは、常に表示されている状態でなければならない。
ダイアログ・ツールボックスなどで使う。
void xdg_toplevel_set_title(struct xdg_toplevel *xdg_toplevel, const char *title);
短いタイトルを UTF-8 で設定する。
タスクバーなどで表示されたりする。
void xdg_toplevel_set_app_id(struct xdg_toplevel *xdg_toplevel, const char *app_id);
アプリケーション識別子を設定する。

app_id は、サーフェスが属するアプリケーションの一般的なクラス名。
推奨されるのは、アプリケーションの .desktop ファイルの、拡張子を除く名前。
"abc.desktop" なら "abc"。

コンポーザーはこれを使用して複数のウィンドウをグループ化したり、新しいアプリケーションを起動する方法を決定したりすることができる。

D-Bus 起動可能アプリケーションの場合、ID は D-Bus サービス名として使用される。
void xdg_toplevel_show_window_menu(struct xdg_toplevel *xdg_toplevel,
    struct wl_seat *seat, uint32_t serial, int32_t x, int32_t y);
サーバー側の実装によるウィンドウメニュー (タイトルバーを右クリックした時などのメニュー) を実行させる。
ボタンやキーなどの押し時に実行する。

x, y は親サーフェス座標。
void xdg_toplevel_move(struct xdg_toplevel *xdg_toplevel,
    struct wl_seat *seat, uint32_t serial);
ユーザー操作によるウィンドウ位置の移動を開始させる。

ウィンドウがフルスクリーンや最大化の状態の時や、serial 値が有効でない場合は、サーバーはこの要求を無視することができる。

カーソル形状はサーバー側で変更される。
移動が完了したときにデバイスのフォーカスが戻ってくるという保証はない。
void xdg_toplevel_resize(struct xdg_toplevel *xdg_toplevel,
    struct wl_seat *seat, uint32_t serial, uint32_t edges);
ユーザー操作によるウィンドウサイズの変更を開始する。
edges
XDG_TOPLEVEL_RESIZE_EDGE_NONE = 0,
XDG_TOPLEVEL_RESIZE_EDGE_TOP = 1,
XDG_TOPLEVEL_RESIZE_EDGE_BOTTOM = 2,
XDG_TOPLEVEL_RESIZE_EDGE_LEFT = 4,
XDG_TOPLEVEL_RESIZE_EDGE_TOP_LEFT = 5,
XDG_TOPLEVEL_RESIZE_EDGE_BOTTOM_LEFT = 6,
XDG_TOPLEVEL_RESIZE_EDGE_RIGHT = 8,
XDG_TOPLEVEL_RESIZE_EDGE_TOP_RIGHT = 9,
XDG_TOPLEVEL_RESIZE_EDGE_BOTTOM_RIGHT = 10,
void xdg_toplevel_set_max_size(
    struct xdg_toplevel *xdg_toplevel, int32_t width, int32_t height);
ウィンドウの最大サイズを設定する。
commit 時に適用される。

ただし、サーバーはこの値を無視する場合があるため、信頼すべきではない。

設定されていない場合、または値が 0 の場合、最大サイズは「なし」となる。

最大サイズをサーフェスの最小サイズよりも小さく要求することは不正であり、プロトコルエラーが発生する。
幅と高さに負の値を使用すると、プロトコルエラーが発生する。
void xdg_toplevel_set_min_size(struct xdg_toplevel *xdg_toplevel,
    int32_t width, int32_t height);
ウィンドウの最小サイズを設定
void xdg_toplevel_set_maximized(struct xdg_toplevel *xdg_toplevel);
ウィンドウを最大化する。

この要求の後、サーバーは configure イベントを送る。
クライアントは、イベントで状態を取得し、最大化状態の描画や設定を行う。

サーフェスがすでに最大化されている場合、サーバーは "最大化" 状態の configure イベントを発生させる。
void xdg_toplevel_unset_maximized(struct xdg_toplevel *xdg_toplevel);
ウィンドウの最大化を元に戻す。
動作は最大化時とほぼ同じ。
void xdg_toplevel_set_fullscreen(struct xdg_toplevel *xdg_toplevel,
    struct wl_output *output);
ウィンドウをフルスクリーンの状態にする。

output は出力先。NULL でサーバーが自動選択する。

サーフェスのサイズが出力全体に広げられない場合は、中央に表示し、周りを黒色にする。
void xdg_toplevel_unset_fullscreen(struct xdg_toplevel *xdg_toplevel);
フルスクリーンを戻す
void xdg_toplevel_set_minimized(struct xdg_toplevel *xdg_toplevel);
ウィンドウを最小化する。

現在最小化されているかどうかを確認する方法はない。

最小化されている時の状態を描画する場合は、wl_surface:frame イベントを使用する。
これは、Alt-Tab 時などでウィンドウ一覧を表示する時のプレビュー画面として機能する。
xdg_popup
int xdg_popup_add_listener(struct xdg_popup *xdg_popup,
    const struct xdg_popup_listener *listener, void *data);
void (*configure)(void *data, struct xdg_popup *xdg_popup,
    int32_t x, int32_t y, int32_t width, int32_t height);

void (*popup_done)(void *data, struct xdg_popup *xdg_popup);
configure
位置・サイズが変化する時。
位置は親からの相対位置。
popup_done
ポップアップが終了した時。
xdg_popup_destroy() で破棄する。
void xdg_popup_destroy(struct xdg_popup *xdg_popup);
破棄
void xdg_popup_grab(struct xdg_popup *xdg_popup,
    struct wl_seat *seat, uint32_t serial);
ポップアップ開始時に明示的にグラブする。

ポップアップが閉じられるか、破棄された時、グラブは解除される。

サーバーがグラブを拒否した場合、ポップアップは解除される。
この時、ポップアップがネストされている場合は、すべてのポップアップが解除される。

ポップアップの親は、トップレベルか、明示的なグラブを持つ別のポップアップであること。

親がポップアップの場合は、一番最後に作成したものから順に破棄すること。
ネストされた一番最後のポップアップが破棄された場合は、親のポップアップがグラブされる。

グラブされているサーフェスでは、すべてのサーフェス上のポインタイベントを取得する。
serial
ボタン、キー押しなどのユーザーアクション時のイベントのシリアル。
xdg_positioner
void xdg_positioner_destroy(struct xdg_positioner *xdg_positioner);
破棄
void xdg_positioner_set_size(struct xdg_positioner *xdg_positioner,
    int32_t width, int32_t height);
ウィンドウのサイズを設定する。
void xdg_positioner_set_anchor_rect(struct xdg_positioner *xdg_positioner,
    int32_t x, int32_t y, int32_t width, int32_t height);
親サーフェス座標でのアンカー矩形を指定。
子サーフェスは、この矩形を基準として配置される。
void xdg_positioner_set_anchor(struct xdg_positioner *xdg_positioner, uint32_t anchor);
配置される時に、アンカー矩形のどの辺を基準にするかを指定する。

TOP + LEFT なら、アンカー矩形の左上に合わせて配置する。

値が一つだけなら、辺の中央に置かれる。
NONE なら、矩形の中央位置となる。
anchor
XDG_POSITIONER_ANCHOR_NONE = 0,
XDG_POSITIONER_ANCHOR_TOP = 1,
XDG_POSITIONER_ANCHOR_BOTTOM = 2,
XDG_POSITIONER_ANCHOR_LEFT = 3,
XDG_POSITIONER_ANCHOR_RIGHT = 4,
XDG_POSITIONER_ANCHOR_TOP_LEFT = 5,
XDG_POSITIONER_ANCHOR_BOTTOM_LEFT = 6,
XDG_POSITIONER_ANCHOR_TOP_RIGHT = 7,
XDG_POSITIONER_ANCHOR_BOTTOM_RIGHT = 8,
void xdg_positioner_set_gravity(
    struct xdg_positioner *xdg_positioner, uint32_t gravity);
アンカーポイントからの、サーフェスの配置方向を設定する。

値が2つ指定されている場合、子は指定された方向に配置される。
値が1つのみの場合、指定されていない軸では、中央揃えされる。
gravity
XDG_POSITIONER_GRAVITY_NONE = 0,
XDG_POSITIONER_GRAVITY_TOP = 1,
XDG_POSITIONER_GRAVITY_BOTTOM = 2,
XDG_POSITIONER_GRAVITY_LEFT = 3,
XDG_POSITIONER_GRAVITY_RIGHT = 4,
XDG_POSITIONER_GRAVITY_TOP_LEFT = 5,
XDG_POSITIONER_GRAVITY_BOTTOM_LEFT = 6,
XDG_POSITIONER_GRAVITY_TOP_RIGHT = 7,
XDG_POSITIONER_GRAVITY_BOTTOM_RIGHT = 8,
void xdg_positioner_set_constraint_adjustment(
    struct xdg_positioner *xdg_positioner, uint32_t constraint_adjustment);
最初に設定した位置とサイズで配置した時に、ウィンドウが画面をはみ出す場合、サーバーによって位置またはサイズを自動で調整するように指定できる。

X, Y 軸ごとに、複数のフラグで指定する。

指定されていない軸は、調整を許可しないという意味になる。
1つの軸に複数の値が指定されている場合は、優先順によって、適切なものが1つ使われる。
デフォルトは NONE。
constraint_adjustment
XDG_POSITIONER_CONSTRAINT_ADJUSTMENT_NONE = 0
XDG_POSITIONER_CONSTRAINT_ADJUSTMENT_SLIDE_X = 1
XDG_POSITIONER_CONSTRAINT_ADJUSTMENT_SLIDE_Y = 2
XDG_POSITIONER_CONSTRAINT_ADJUSTMENT_FLIP_X = 4
XDG_POSITIONER_CONSTRAINT_ADJUSTMENT_FLIP_Y = 8
XDG_POSITIONER_CONSTRAINT_ADJUSTMENT_RESIZE_X = 16
XDG_POSITIONER_CONSTRAINT_ADJUSTMENT_RESIZE_Y = 32

SLIDE は、位置をずらす。
FLIP は、位置を反転する。
RESIZE は、サイズを変更する。
void xdg_positioner_set_offset(
    struct xdg_positioner *xdg_positioner, int32_t x, int32_t y);
指定値分、表示位置をずらす。