1 /* This entire file is licensed under MIT 2 * 3 * Copyright 2020 William Wold 4 * 5 * Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: 6 * 7 * The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. 8 * 9 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. 10 */ 11 12 #ifndef GTK_LAYER_SHELL_H 13 #define GTK_LAYER_SHELL_H 14 15 #include <gtk/gtk.h> 16 17 /** 18 * SECTION:gtk-layer-shell 19 * @title: Gtk Layer Shell 20 * @short_description: A library to write GTK Applications using Layer Shell 21 * 22 * insert more general verbiage here 23 * 24 * # Forcing Window Size 25 * If you wish to force your layer surface window to be a different size than it 26 * is by default: 27 * |[<!-- language="C" --> 28 * gtk_widget_set_size_request (GTK_WIDGET (layer_gtk_window), width, height); 29 * // force the window to resize to the new request 30 * gtk_window_resize (layer_gtk_window, 1, 1); 31 * ]| 32 * If width or height is -1, the default is used for that axis. If the window is 33 * anchored to opposite edges of the output (see gtk_layer_set_anchor ()), the 34 * size request is ignored. If you later wish to use the default window size, 35 * simply repeat the two calls but with both width and height as -1. 36 */ 37 38 G_BEGIN_DECLS 39 40 /** 41 * GtkLayerShellLayer: 42 * @GTK_LAYER_SHELL_LAYER_BACKGROUND: The background layer. 43 * @GTK_LAYER_SHELL_LAYER_BOTTOM: The bottom layer. 44 * @GTK_LAYER_SHELL_LAYER_TOP: The top layer. 45 * @GTK_LAYER_SHELL_LAYER_OVERLAY: The overlay layer. 46 * @GTK_LAYER_SHELL_LAYER_ENTRY_NUMBER: Should not be used except to get the number of entries. (NOTE: may change in 47 * future releases as more entries are added) 48 */ 49 typedef enum { 50 GTK_LAYER_SHELL_LAYER_BACKGROUND, 51 GTK_LAYER_SHELL_LAYER_BOTTOM, 52 GTK_LAYER_SHELL_LAYER_TOP, 53 GTK_LAYER_SHELL_LAYER_OVERLAY, 54 GTK_LAYER_SHELL_LAYER_ENTRY_NUMBER, // Should not be used except to get the number of entries 55 } GtkLayerShellLayer; 56 57 /** 58 * GtkLayerShellEdge: 59 * @GTK_LAYER_SHELL_EDGE_LEFT: The left edge of the screen. 60 * @GTK_LAYER_SHELL_EDGE_RIGHT: The right edge of the screen. 61 * @GTK_LAYER_SHELL_EDGE_TOP: The top edge of the screen. 62 * @GTK_LAYER_SHELL_EDGE_BOTTOM: The bottom edge of the screen. 63 * @GTK_LAYER_SHELL_EDGE_ENTRY_NUMBER: Should not be used except to get the number of entries. (NOTE: may change in 64 * future releases as more entries are added) 65 */ 66 typedef enum { 67 GTK_LAYER_SHELL_EDGE_LEFT = 0, 68 GTK_LAYER_SHELL_EDGE_RIGHT, 69 GTK_LAYER_SHELL_EDGE_TOP, 70 GTK_LAYER_SHELL_EDGE_BOTTOM, 71 GTK_LAYER_SHELL_EDGE_ENTRY_NUMBER, // Should not be used except to get the number of entries 72 } GtkLayerShellEdge; 73 74 /** 75 * GtkLayerShellKeyboardMode: 76 * GTK_LAYER_SHELL_KEYBOARD_MODE_NONE: This window should not receive keyboard events. 77 * GTK_LAYER_SHELL_KEYBOARD_MODE_EXCLUSIVE: This window should have exclusive focus if it is on the top or overlay layer. 78 * GTK_LAYER_SHELL_KEYBOARD_MODE_ON_DEMAND: The user should be able to focus and unfocues this window in an implementation 79 * defined way. Not supported for protocol version < 4. 80 * GTK_LAYER_SHELL_KEYBOARD_MODE_ENTRY_NUMBER: Should not be used except to get the number of entries. (NOTE: may change in 81 * future releases as more entries are added) 82 */ 83 typedef enum { 84 GTK_LAYER_SHELL_KEYBOARD_MODE_NONE = 0, 85 GTK_LAYER_SHELL_KEYBOARD_MODE_EXCLUSIVE = 1, 86 GTK_LAYER_SHELL_KEYBOARD_MODE_ON_DEMAND = 2, 87 GTK_LAYER_SHELL_KEYBOARD_MODE_ENTRY_NUMBER = 3, // Should not be used except to get the number of entries 88 } GtkLayerShellKeyboardMode; 89 90 /** 91 * gtk_layer_get_major_version: 92 * 93 * Returns: the major version number of the GTK Layer Shell library 94 * 95 * Since: 0.4 96 */ 97 guint gtk_layer_get_major_version (); 98 99 /** 100 * gtk_layer_get_minor_version: 101 * 102 * Returns: the minor version number of the GTK Layer Shell library 103 * 104 * Since: 0.4 105 */ 106 guint gtk_layer_get_minor_version (); 107 108 /** 109 * gtk_layer_get_micro_version: 110 * 111 * Returns: the micro/patch version number of the GTK Layer Shell library 112 * 113 * Since: 0.4 114 */ 115 guint gtk_layer_get_micro_version (); 116 117 /** 118 * gtk_layer_is_supported: 119 * 120 * May block for a Wayland roundtrip the first time it's called. 121 * 122 * Returns: %TRUE if the platform is Wayland and Wayland compositor supports the 123 * zwlr_layer_shell_v1 protocol. 124 * 125 * Since: 0.5 126 */ 127 gboolean gtk_layer_is_supported (); 128 129 /** 130 * gtk_layer_get_protocol_version: 131 * 132 * May block for a Wayland roundtrip the first time it's called. 133 * 134 * Returns: version of the zwlr_layer_shell_v1 protocol supported by the 135 * compositor or 0 if the protocol is not supported. 136 * 137 * Since: 0.6 138 */ 139 guint gtk_layer_get_protocol_version (); 140 141 /** 142 * gtk_layer_init_for_window: 143 * @window: A #GtkWindow to be turned into a layer surface. 144 * 145 * Set the @window up to be a layer surface once it is mapped. this must be called before 146 * the @window is realized. 147 */ 148 void gtk_layer_init_for_window (GtkWindow *window); 149 150 /** 151 * gtk_layer_is_layer_window: 152 * @window: A #GtkWindow that may or may not have a layer surface. 153 * 154 * Returns: if @window has been initialized as a layer surface. 155 * 156 * Since: 0.5 157 */ 158 gboolean gtk_layer_is_layer_window (GtkWindow *window); 159 160 /** 161 * gtk_layer_get_zwlr_layer_surface_v1: 162 * @window: A layer surface. 163 * 164 * Returns: The underlying layer surface Wayland object 165 * 166 * Since: 0.4 167 */ 168 struct zwlr_layer_surface_v1 *gtk_layer_get_zwlr_layer_surface_v1 (GtkWindow *window); 169 170 /** 171 * gtk_layer_set_namespace: 172 * @window: A layer surface. 173 * @name_space: The namespace of this layer surface. 174 * 175 * Set the "namespace" of the surface. 176 * 177 * No one is quite sure what this is for, but it probably should be something generic 178 * ("panel", "osk", etc). The @name_space string is copied, and caller maintians 179 * ownership of original. If the window is currently mapped, it will get remapped so 180 * the change can take effect. 181 * 182 * Default is "gtk-layer-shell" (which will be used if set to %NULL) 183 */ 184 void gtk_layer_set_namespace (GtkWindow *window, char const* name_space); 185 186 /** 187 * gtk_layer_get_namespace: 188 * @window: A layer surface. 189 * 190 * NOTE: this function does not return ownership of the string. Do not free the returned string. 191 * Future calls into the library may invalidate the returned string. 192 * 193 * Returns: a reference to the namespace property. If namespace is unset, returns the 194 * default namespace ("gtk-layer-shell"). Never returns %NULL. 195 * 196 * Since: 0.5 197 */ 198 const char *gtk_layer_get_namespace (GtkWindow *window); 199 200 /** 201 * gtk_layer_set_layer: 202 * @window: A layer surface. 203 * @layer: The layer on which this surface appears. 204 * 205 * Set the "layer" on which the surface appears (controls if it is over top of or below other surfaces). The layer may 206 * be changed on-the-fly in the current version of the layer shell protocol, but on compositors that only support an 207 * older version the @window is remapped so the change can take effect. 208 * 209 * Default is #GTK_LAYER_SHELL_LAYER_TOP 210 */ 211 void gtk_layer_set_layer (GtkWindow *window, GtkLayerShellLayer layer); 212 213 /** 214 * gtk_layer_get_layer: 215 * @window: A layer surface. 216 * 217 * Returns: the current layer. 218 * 219 * Since: 0.5 220 */ 221 GtkLayerShellLayer gtk_layer_get_layer (GtkWindow *window); 222 223 /** 224 * gtk_layer_set_monitor: 225 * @window: A layer surface. 226 * @monitor: The output this layer surface will be placed on (%NULL to let the compositor decide). 227 * 228 * Set the output for the window to be placed on, or %NULL to let the compositor choose. 229 * If the window is currently mapped, it will get remapped so the change can take effect. 230 * 231 * Default is %NULL 232 */ 233 void gtk_layer_set_monitor (GtkWindow *window, GdkMonitor *monitor); 234 235 /** 236 * gtk_layer_get_monitor: 237 * @window: A layer surface. 238 * 239 * NOTE: To get which monitor the surface is actually on, use 240 * gdk_display_get_monitor_at_window(). 241 * 242 * Returns: the monitor this surface will/has requested to be on, can be %NULL. 243 * 244 * Since: 0.5 245 */ 246 GdkMonitor *gtk_layer_get_monitor (GtkWindow *window); 247 248 /** 249 * gtk_layer_set_anchor: 250 * @window: A layer surface. 251 * @edge: A #GtkLayerShellEdge this layer suface may be anchored to. 252 * @anchor_to_edge: Whether or not to anchor this layer surface to @edge. 253 * 254 * Set whether @window should be anchored to @edge. 255 * - If two perpendicular edges are anchored, the surface with be anchored to that corner 256 * - If two opposite edges are anchored, the window will be stretched across the screen in that direction 257 * 258 * Default is %FALSE for each #GtkLayerShellEdge 259 */ 260 void gtk_layer_set_anchor (GtkWindow *window, GtkLayerShellEdge edge, gboolean anchor_to_edge); 261 262 /** 263 * gtk_layer_get_anchor: 264 * @window: A layer surface. 265 * 266 * Returns: if this surface is anchored to the given edge. 267 * 268 * Since: 0.5 269 */ 270 gboolean gtk_layer_get_anchor (GtkWindow *window, GtkLayerShellEdge edge); 271 272 /** 273 * gtk_layer_set_margin: 274 * @window: A layer surface. 275 * @edge: The #GtkLayerShellEdge for which to set the margin. 276 * @margin_size: The margin for @edge to be set. 277 * 278 * Set the margin for a specific @edge of a @window. Effects both surface's distance from 279 * the edge and its exclusive zone size (if auto exclusive zone enabled). 280 * 281 * Default is 0 for each #GtkLayerShellEdge 282 */ 283 void gtk_layer_set_margin (GtkWindow *window, GtkLayerShellEdge edge, int margin_size); 284 285 /** 286 * gtk_layer_get_margin: 287 * @window: A layer surface. 288 * 289 * Returns: the size of the margin for the given edge. 290 * 291 * Since: 0.5 292 */ 293 int gtk_layer_get_margin (GtkWindow *window, GtkLayerShellEdge edge); 294 295 /** 296 * gtk_layer_set_exclusive_zone: 297 * @window: A layer surface. 298 * @exclusive_zone: The size of the exclusive zone. 299 * 300 * Has no effect unless the surface is anchored to an edge. Requests that the compositor 301 * does not place other surfaces within the given exclusive zone of the anchored edge. 302 * For example, a panel can request to not be covered by maximized windows. See 303 * wlr-layer-shell-unstable-v1.xml for details. 304 * 305 * Default is 0 306 */ 307 void gtk_layer_set_exclusive_zone (GtkWindow *window, int exclusive_zone); 308 309 /** 310 * gtk_layer_get_exclusive_zone: 311 * @window: A layer surface. 312 * 313 * Returns: the window's exclusive zone (which may have been set manually or automatically) 314 * 315 * Since: 0.5 316 */ 317 int gtk_layer_get_exclusive_zone (GtkWindow *window); 318 319 /** 320 * gtk_layer_auto_exclusive_zone_enable: 321 * @window: A layer surface. 322 * 323 * When auto exclusive zone is enabled, exclusive zone is automatically set to the 324 * size of the @window + relevant margin. To disable auto exclusive zone, just set the 325 * exclusive zone to 0 or any other fixed value. 326 * 327 * NOTE: you can control the auto exclusive zone by changing the margin on the non-anchored 328 * edge. This behavior is specific to gtk-layer-shell and not part of the underlying protocol 329 */ 330 void gtk_layer_auto_exclusive_zone_enable (GtkWindow *window); 331 332 /** 333 * gtk_layer_auto_exclusive_zone_is_enabled: 334 * @window: A layer surface. 335 * 336 * Returns: if the surface's exclusive zone is set to change based on the window's size 337 * 338 * Since: 0.5 339 */ 340 gboolean gtk_layer_auto_exclusive_zone_is_enabled (GtkWindow *window); 341 342 /** 343 * gtk_layer_set_keyboard_mode: 344 * @window: A layer surface. 345 * @mode: The type of keyboard interactivity requested. 346 * 347 * Sets if/when @window should receive keyboard events from the compositor, see 348 * GtkLayerShellKeyboardMode for details. 349 * 350 * Default is #GTK_LAYER_SHELL_KEYBOARD_MODE_NONE 351 * 352 * Since: 0.6 353 */ 354 void gtk_layer_set_keyboard_mode (GtkWindow *window, GtkLayerShellKeyboardMode mode); 355 356 /** 357 * gtk_layer_get_keyboard_mode: 358 * @window: A layer surface. 359 * 360 * Returns: current keyboard interactivity mode for @window. 361 * 362 * Since: 0.6 363 */ 364 GtkLayerShellKeyboardMode gtk_layer_get_keyboard_mode (GtkWindow *window); 365 366 /** 367 * gtk_layer_set_keyboard_interactivity: 368 * @window: A layer surface. 369 * @interacitvity: Whether the layer surface should receive keyboard events. 370 * 371 * Whether the @window should receive keyboard events from the compositor. 372 * 373 * Default is %FALSE 374 * 375 * Deprecated: 0.6: Use gtk_layer_set_keyboard_mode () instead. 376 */ 377 void gtk_layer_set_keyboard_interactivity (GtkWindow *window, gboolean interactivity); 378 379 /** 380 * gtk_layer_get_keyboard_interactivity: 381 * @window: A layer surface. 382 * 383 * Returns: if keybaord interacitvity is enabled 384 * 385 * Since: 0.5 386 * Deprecated: 0.6: Use gtk_layer_get_keyboard_mode () instead. 387 */ 388 gboolean gtk_layer_get_keyboard_interactivity (GtkWindow *window); 389 390 G_END_DECLS 391 392 #endif // GTK_LAYER_SHELL_H 393