From 0af53d1e780343c1407472af597cf660e90b8d9c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marek=20Marczykowski-G=C3=B3recki?= Date: Sun, 7 Feb 2016 20:40:16 +0100 Subject: [PATCH] Fix GUI protocol doc formatting --- developers/fundamentals/gui.md | 381 ++++++++++++++++++++++----------- 1 file changed, 261 insertions(+), 120 deletions(-) diff --git a/developers/fundamentals/gui.md b/developers/fundamentals/gui.md index f7f47f48..e8565e27 100644 --- a/developers/fundamentals/gui.md +++ b/developers/fundamentals/gui.md @@ -119,68 +119,138 @@ struct msghdr { The header is followed by message-specific data. -~~~ -|Message name|Structure after header|Action| -|:-----------|:---------------------|:-----| -|MSG_CLIPBOARD_DATA|amorphic blob (length determined by the "window" field)|Store the received clipboard content (not parsing in any way)| -|MSG_CREATE|` struct msg_create { ` - ` uint32_t x; ` - ` uint32_t y; ` - ` uint32_t width; ` - ` uint32_t height; ` - ` uint32_t parent; ` - ` uint32_t override_redirect; ` - ` }; `|Create a window with given parameters| -|MSG_DESTROY|None|Destroy a window| -|MSG_MAP|` struct msg_map_info { ` - ` uint32_t transient_for; ` - ` uint32_t override_redirect; ` - ` }; `|Map a window with given parameters| -|MSG_UNMAP|None|Unmap a window| -|MSG_CONFIGURE|` struct msg_configure { ` - ` uint32_t x; ` - ` uint32_t y; ` - ` uint32_t width; ` - ` uint32_t height; ` - ` uint32_t override_redirect; ` - ` }; `|Change window position/size/type| -|MSG_MFNDUMP|` struct shm_cmd { ` - ` uint32_t shmid; ` - ` uint32_t width; ` - ` uint32_t height; ` - ` uint32_t bpp; ` - ` uint32_t off; ` - ` uint32_t num_mfn; ` - ` uint32_t domid; ` - ` uint32_t mfns[0]; ` - ` }; `|Retrieve the array of mfns that constitute the composition buffer of a remote window. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Message nameStructure after headerAction
MSG_CLIPBOARD_DATAamorphic blob (length determined by the "window" field)Store the received clipboard content (not parsing in any way)
MSG_CREATE
+struct msg_create {
+  uint32_t x;
+  uint32_t y;
+  uint32_t width;
+  uint32_t height;
+  uint32_t parent;
+  uint32_t override_redirect;
+};
+
+		Create a window with given parameters
MSG_DESTROYNoneDestroy a window
MSG_MAP
+struct msg_map_info { 
+  uint32_t transient_for; 
+  uint32_t override_redirect; 
+};
+
Map a window with given parameters
MSG_UNMAPNoneUnmap a window
MSG_CONFIGURE
+struct msg_configure { 
+  uint32_t x; 
+  uint32_t y; 
+  uint32_t width; 
+  uint32_t height; 
+  uint32_t override_redirect; 
+};
+
Change window position/size/type
MSG_MFNDUMP
+struct shm_cmd { 
+  uint32_t shmid; 
+  uint32_t width; 
+  uint32_t height; 
+  uint32_t bpp; 
+  uint32_t off; 
+  uint32_t num_mfn; 
+  uint32_t domid; 
+  uint32_t mfns[0]; 
+};
+
Retrieve the array of mfns that constitute the composition buffer of a remote window. + The "num_mfn" 32bit integers follow the shm_cmd structure; "off" is the offset of the composite buffer start in the first frame; "shmid" and "domid" parameters are just placeholders (to be filled by *qubes_guid*), so that we can use the same structure when talking to *shmoverride.so*| -|MSG_SHMIMAGE|` struct msg_shmimage { ` - ` uint32_t x; ` - ` uint32_t y;` - ` uint32_t width;` - ` uint32_t height;` - ` }; `|Repaint the given window fragment| -|MSG_WMNAME|` struct msg_wmname { ` - ` char data[128]; ` - ` } ; `|Set the window name; only printable characters are allowed| -|MSG_DOCK|None|Dock the window in the tray| -|MSG_WINDOW_HINTS|` struct msg_window_hints { ` - ` uint32_t flags; ` - ` uint32_t min_width; ` - ` uint32_t min_height; ` - ` uint32_t max_width; ` - ` uint32_t max_height; ` - ` uint32_t width_inc; ` - ` uint32_t height_inc; ` - ` uint32_t base_width; ` - ` uint32_t base_height; ` - ` }; `|Size hints for window manager| -|MSG_WINDOW_FLAGS|` struct msg_window_flags { ` - ` uint32_t flags_set; ` - ` uint32_t flags_unset;` - ` }; `|Change window state request; fields contains bitmask which flags request to be set and which unset| -~~~ +
MSG_SHMIMAGE
+struct msg_shmimage { 
+     uint32_t x; 
+     uint32_t y;
+     uint32_t width;
+     uint32_t height;
+};
+
Repaint the given window fragment
MSG_WMNAME
+struct msg_wmname { 
+  char data[128]; 
+};
+
Set the window name; only printable characters are allowed
MSG_DOCKNoneDock the window in the tray
MSG_WINDOW_HINTS
+struct msg_window_hints { 
+     uint32_t flags; 
+     uint32_t min_width; 
+     uint32_t min_height; 
+     uint32_t max_width; 
+     uint32_t max_height; 
+     uint32_t width_inc; 
+     uint32_t height_inc; 
+     uint32_t base_width; 
+     uint32_t base_height; 
+};
+
Size hints for window manager
MSG_WINDOW_FLAGS
+struct msg_window_flags { 
+      uint32_t flags_set; 
+     uint32_t flags_unset;
+};
+
Change window state request; fields contains bitmask which flags request to be set and which unset
Dom0 -> AppVM messages ----------------------- @@ -197,63 +267,134 @@ struct msghdr { ~~~ The header is followed by message-specific data. - ` KEYPRESS, BUTTON, MOTION, FOCUS ` messages pass information extracted from dom0 XEvent; see appropriate event documentation. + `KEYPRESS`, `BUTTON`, `MOTION`, `FOCUS` messages pass information extracted from dom0 XEvent; see appropriate event documentation. -~~~ -|Message name|Structure after header|Action| -|:-----------|:---------------------|:-----| -|MSG_KEYPRESS|` struct msg_keypress { ` - ` uint32_t type; ` - ` uint32_t x; ` - ` uint32_t y; ` - ` uint32_t state; ` - ` uint32_t keycode; ` - ` }; `|Tell *qubes_drv* driver to generate a keypress| -|MSG_BUTTON|` struct msg_button { ` - ` uint32_t type; ` - ` uint32_t x; ` - ` uint32_t y; ` - ` uint32_t state; ` - ` uint32_t button; ` - ` }; `|Tell *qubes_drv* driver to generate mouseclick| -|MSG_MOTION|` struct msg_motion { ` - ` uint32_t x; ` - ` uint32_t y; ` - ` uint32_t state; ` - ` uint32_t is_hint; ` - ` }; `|Tell *qubes_drv* driver to generate motion event| -|MSG_CONFIGURE|` struct msg_configure { ` - ` uint32_t x; ` - ` uint32_t y; ` - ` uint32_t width; ` - ` uint32_t height; ` - ` uint32_t override_redirect; ` - ` }; `|Change window position/size/type| -|MSG_MAP|` struct msg_map_info { ` - ` uint32_t transient_for; ` - ` uint32_t override_redirect; ` - ` }; `|Map a window with given parameters| -|MSG_CLOSE|None|send wmDeleteMessage to the window| -|MSG_CROSSING|` struct msg_crossing { ` - ` uint32_t type; ` - ` uint32_t x; ` - ` uint32_t y; ` - ` uint32_t state; ` - ` uint32_t mode; ` - ` uint32_t detail; ` - ` uint32_t focus; ` - ` }; `|Notify window about enter/leave event| -|MSG_FOCUS|` struct msg_focus { ` - ` uint32_t type; ` - ` uint32_t mode; ` - ` uint32_t detail; ` - ` }; `|Raise a window, XSetInputFocus| -|MSG_CLIPBOARD_REQ|None|Retrieve the local clipboard, pass contents to gui-daemon| -|MSG_CLIPBOARD_DATA|amorphic blob|Insert the received data into local clipboard| -|MSG_EXECUTE|Obsolete|Obsolete, unused| -|MSG_KEYMAP_NOTIFY|` unsigned char remote_keys[32]; `|Synchronize the keyboard state (key pressed/released) with dom0| -|MSG_WINDOW_FLAGS|` struct msg_window_flags { ` - ` uint32_t flags_set; ` - ` uint32_t flags_unset;` - ` }; `|Window state change confirmation| -~~~ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Message nameStructure after headerAction
MSG_KEYPRESS
+struct msg_keypress {  
+  uint32_t type;  
+  uint32_t x;  
+  uint32_t y;  
+  uint32_t state;  
+  uint32_t keycode;  
+};
+
Tell *qubes_drv* driver to generate a keypress
MSG_BUTTON
+struct msg_button {  
+  uint32_t type;  
+  uint32_t x;  
+  uint32_t y;  
+  uint32_t state;  
+  uint32_t button;  
+};
+
Tell *qubes_drv* driver to generate mouseclick
MSG_MOTION
+struct msg_motion {  
+  uint32_t x;  
+  uint32_t y;  
+  uint32_t state;  
+  uint32_t is_hint;  
+};
+
Tell *qubes_drv* driver to generate motion event
MSG_CONFIGURE
+struct msg_configure { 
+  uint32_t x; 
+  uint32_t y; 
+  uint32_t width; 
+  uint32_t height; 
+  uint32_t override_redirect; 
+};
+
Change window position/size/type
MSG_MAP
+struct msg_map_info { 
+  uint32_t transient_for; 
+  uint32_t override_redirect; 
+};
+
Map a window with given parameters
MSG_CLOSENonesend wmDeleteMessage to the window
MSG_CROSSING
+struct msg_crossing { 
+  uint32_t type; 
+  uint32_t x; 
+  uint32_t y; 
+  uint32_t state; 
+  uint32_t mode; 
+  uint32_t detail; 
+  uint32_t focus; 
+};
+
Notify window about enter/leave event
MSG_FOCUS
+struct msg_focus {  
+  uint32_t type;  
+  uint32_t mode;  
+  uint32_t detail;  
+};
+
Raise a window, XSetInputFocus
MSG_CLIPBOARD_REQNoneRetrieve the local clipboard, pass contents to gui-daemon
MSG_CLIPBOARD_DATAamorphic blobInsert the received data into local clipboard
MSG_EXECUTEObsoleteObsolete, unused
MSG_KEYMAP_NOTIFY unsigned char remote_keys[32]; Synchronize the keyboard state (key pressed/released) with dom0
MSG_WINDOW_FLAGS
+struct msg_window_flags { 
+      uint32_t flags_set; 
+     uint32_t flags_unset;
+};
+
Window state change confirmation