1 #ifndef SIGNAL_DEFINITIONS_HPP 2 #define SIGNAL_DEFINITIONS_HPP 3 4 #include "wayfire/view.hpp" 5 #include "wayfire/output.hpp" 6 7 /** 8 * Documentation of signals emitted from core components. 9 * Each signal documentation follows the following scheme: 10 * 11 * name: The base name of the signal 12 * on: Which components the plugin is emitted on. Prefixes are specified 13 * in (), i.e test(view-) means that the signal is emitted on component 14 * test with prefix 'view-'. 15 * when: Description of when the signal is emitted. 16 * argument: What the signal data represents when there is no dedicated 17 * signal data struct. 18 */ 19 20 namespace wf 21 { 22 /* ----------------------------------------------------------------------------/ 23 * Core signals 24 * -------------------------------------------------------------------------- */ 25 /** 26 * name: startup-finished 27 * on: core 28 * when: Emitted when the Wayfire initialization has been completed and the main 29 * loop is about to start. 30 * argument: unused 31 */ 32 33 /** 34 * name: shutdown 35 * on: core 36 * when: Right before the shutdown sequence starts. 37 * argument: unused 38 */ 39 40 class input_device_t; 41 /** 42 * name: input-device-added, input-device-removed 43 * on: core 44 * when: Whenever a new input device is added or removed. 45 */ 46 struct input_device_signal : public wf::signal_data_t 47 { 48 nonstd::observer_ptr<input_device_t> device; 49 }; 50 51 /** 52 * name: tablet-mode, lid-state 53 * on: core 54 * when: When the corresponding switch device state changes. 55 */ 56 struct switch_signal : public wf::signal_data_t 57 { 58 /** The switch device */ 59 nonstd::observer_ptr<input_device_t> device; 60 /** On or off */ 61 bool state; 62 }; 63 64 /** 65 * Describes the various ways in which core should handle an input event. 66 */ 67 enum class input_event_processing_mode_t 68 { 69 /** 70 * Core should process this event for input grabs, bindings and eventually 71 * forward it to a client surface. 72 */ 73 FULL, 74 /** 75 * Core should process this event for input grabs and bindings, but not send 76 * the event to the client. 77 */ 78 NO_CLIENT, 79 }; 80 81 /** 82 * name: 83 * pointer_motion, pointer_motion_absolute, pointer_button, pointer_axis, 84 * pointer_swipe_begin, pointer_swipe_update, pointer_swipe_end, 85 * pointer_pinch_begin, pointer_pinch_update, pointer_pinch_end, 86 * keyboard_key, 87 * touch_down, touch_up, touch_motion, 88 * tablet_proximity, tablet_axis, tablet_button, tablet_tip 89 * 90 * on: core 91 * when: The input event signals are sent from core whenever a new input from an 92 * input device arrives. The events are sent before any processing is done, 93 * and they are independent of plugin input grabs and other wayfire input 94 * mechanisms. 95 * 96 * The event data can be modified by plugins, and then the modified event 97 * will be used instead. However plugins which modify the event must ensure 98 * that subsequent events are adjusted accordingly as well. 99 * 100 * The same signals are emitted with a _post suffix after the event handling 101 * by core has finished. 102 * 103 * example: The pointer_motion event is emitted with data of type 104 * input_event_signal<wlr_event_pointer_motion> 105 */ 106 template<class wlr_event_t> 107 struct input_event_signal : public wf::signal_data_t 108 { 109 /* The event as it has arrived from wlroots */ 110 wlr_event_t *event; 111 112 /** 113 * Describes how core should handle this event. 114 * 115 * This is currently supported for only a subset of signals, namely: 116 * 117 * pointer_button, keyboard_key, touch_down 118 */ 119 input_event_processing_mode_t mode = input_event_processing_mode_t::FULL; 120 }; 121 122 /** 123 * name: drag-started, drag-stopped 124 * on: core 125 * when: When a DnD action is started/stopped 126 */ 127 struct dnd_signal : public wf::signal_data_t 128 { 129 /** The DnD icon */ 130 wf::surface_interface_t *icon; 131 }; 132 133 /** 134 * name: surface-mapped, surface-unmapped 135 * on: core 136 * when: Whenever a surface map state changes. This must be emitted for all 137 * surfaces regardless of their type (view, subsurface, etc). 138 */ 139 struct surface_map_state_changed_signal : public wf::signal_data_t 140 { 141 wf::surface_interface_t *surface; 142 }; 143 144 /** 145 * name: reload-config 146 * on: core 147 * when: When the config file is reloaded 148 * argument: unused 149 */ 150 151 /** 152 * name: keyboard-focus-changed 153 * on: core 154 * when: Keyboard focus is changed (may change to nullptr). 155 */ 156 struct keyboard_focus_changed_signal : public wf::signal_data_t 157 { 158 wayfire_view view; 159 wlr_surface *surface; 160 }; 161 162 /* ----------------------------------------------------------------------------/ 163 * Output signals 164 * -------------------------------------------------------------------------- */ 165 166 /** Base class for all output signals. */ 167 struct _output_signal : public wf::signal_data_t 168 { 169 wf::output_t *output; 170 }; 171 172 /** @return The output in the signal. Must be an _output_signal. */ 173 output_t *get_signaled_output(signal_data_t *data); 174 175 /** 176 * name: output-added 177 * on: output-layout 178 * when: Each time a new output is added. 179 */ 180 using output_added_signal = _output_signal; 181 182 /** 183 * name: pre-remove 184 * on: output, output-layout(output-) 185 * when: Emitted just before starting the destruction procedure for an output. 186 */ 187 using output_pre_remove_signal = _output_signal; 188 189 /** 190 * name: output-removed 191 * on: output-layout 192 * when: Each time a new output is added. 193 */ 194 using output_removed_signal = _output_signal; 195 196 enum output_config_field_t 197 { 198 /** Output source changed */ 199 OUTPUT_SOURCE_CHANGE = (1 << 0), 200 /** Output mode changed */ 201 OUTPUT_MODE_CHANGE = (1 << 1), 202 /** Output scale changed */ 203 OUTPUT_SCALE_CHANGE = (1 << 2), 204 /** Output transform changed */ 205 OUTPUT_TRANSFORM_CHANGE = (1 << 3), 206 /** Output position changed */ 207 OUTPUT_POSITION_CHANGE = (1 << 4), 208 }; 209 210 struct output_state_t; 211 212 /** 213 * name: configuration-changed 214 * on: output, output-layout(output-) 215 * when: Each time the output's source, mode, scale, transform and/or position 216 * changes. 217 */ 218 struct output_configuration_changed_signal : public _output_signal 219 { output_configuration_changed_signalwf::output_configuration_changed_signal220 output_configuration_changed_signal(const wf::output_state_t& st) : 221 state(st) 222 {} 223 /** 224 * Which output attributes actually changed. 225 * A bitwise OR of output_config_field_t. 226 */ 227 uint32_t changed_fields; 228 229 /** 230 * The new state of the output. 231 */ 232 const wf::output_state_t& state; 233 }; 234 235 /** 236 * name: gain-focus 237 * on: output, core(output-) 238 * when: Immediately after the output becomes focused. 239 */ 240 using output_gain_focus_signal = _output_signal; 241 242 /* ----------------------------------------------------------------------------/ 243 * Output rendering signals (see also wayfire/workspace-stream.hpp) 244 * -------------------------------------------------------------------------- */ 245 /** 246 * name: start-rendering 247 * on: output 248 * when: Whenever the output is ready to start rendering. This can happen 249 * either on output creation or whenever all inhibits in wayfire-shell have 250 * been removed. 251 */ 252 using output_start_rendering_signal = _output_signal; 253 254 /* ----------------------------------------------------------------------------/ 255 * Output workspace signals 256 * -------------------------------------------------------------------------- */ 257 258 /** 259 * name: workspace-changed 260 * on: output 261 * when: Whenever the current workspace on the output has changed. 262 */ 263 struct workspace_changed_signal : public wf::signal_data_t 264 { 265 /** For workspace-change-request, whether the request has already been 266 * handled. */ 267 bool carried_out; 268 269 /** Previously focused workspace */ 270 wf::point_t old_viewport; 271 272 /** Workspace that is to be focused or became focused */ 273 wf::point_t new_viewport; 274 275 /** The output this is happening on */ 276 wf::output_t *output; 277 }; 278 279 /** 280 * name: workspace-change-request 281 * on: output 282 * when: Whenever a workspace change is requested by core or by a plugin. 283 * This can be used by plugins who wish to handle workspace changing 284 * themselves, for ex. if animating the transition. 285 */ 286 struct workspace_change_request_signal : public workspace_changed_signal 287 { 288 /** 289 * A list of views whose geometry should remain stationary. 290 * The caller is responsible for ensuring that this doesn't move the views 291 * outside of the visible area. 292 * 293 * Note that the views might still be moved if a previous workspace change 294 * request is being serviced. 295 */ 296 std::vector<wayfire_view> fixed_views; 297 }; 298 299 /** 300 * name: workarea-changed 301 * on: output 302 * when: Whenever the available workarea changes. 303 */ 304 struct workarea_changed_signal : public wf::signal_data_t 305 { 306 wf::geometry_t old_workarea; 307 wf::geometry_t new_workarea; 308 }; 309 310 /** 311 * name: fullscreen-layer-focused 312 * on: output 313 * when: Whenever a fullscreen view is promoted on top of the other layers. 314 * argument: The event data pointer is null if there are no promoted views, 315 * and not-null otherwise. 316 */ 317 318 /** 319 * name: stack-order-changed 320 * on: output, core(output-) 321 * when: Whenever the stacking order of views on the output changes. Note that 322 * the signal can be a false positive, i.e the stacking order did not really 323 * change. However, there will be no cases where the order changed but the 324 * signal was not fired. 325 */ 326 using stack_order_changed_signal = _output_signal; 327 328 /* ----------------------------------------------------------------------------/ 329 * Surface signals 330 * -------------------------------------------------------------------------- */ 331 struct _subsurface_signal : public wf::signal_data_t 332 { 333 nonstd::observer_ptr<surface_interface_t> main_surface; 334 nonstd::observer_ptr<surface_interface_t> subsurface; 335 }; 336 337 /** 338 * name: subsurface-added 339 * on: surface 340 * when: Emitted when a subsurface is added to the given surface. 341 */ 342 using subsurface_added_signal = _subsurface_signal; 343 344 /** 345 * name: subsurface-removed 346 * on: surface 347 * when: Emitted immediately before removing a subsurface from the surface. 348 */ 349 using subsurface_removed_signal = _subsurface_signal; 350 351 /* ----------------------------------------------------------------------------/ 352 * View signals 353 * -------------------------------------------------------------------------- */ 354 355 /** Base class for all view signals. */ 356 struct _view_signal : public wf::signal_data_t 357 { 358 wayfire_view view; 359 }; 360 361 /** 362 * @return The view contained in the signal data, it must be 363 * a _view_signal. 364 */ 365 wayfire_view get_signaled_view(wf::signal_data_t *data); 366 367 /** 368 * name: mapped 369 * on: view, output(view-) 370 * when: After the view becomes mapped. This signal must also be emitted from 371 * all compositor views. 372 */ 373 struct view_mapped_signal : public _view_signal 374 { 375 /* Indicates whether the position already has its initial position */ 376 bool is_positioned = false; 377 }; 378 379 /** 380 * name: pre-unmapped 381 * on: view, output(view-) 382 * when: Immediately before unmapping a mapped view. The signal may not be 383 * emitted from all views, but it is necessary for unmap animations to work. 384 */ 385 using view_pre_unmap_signal = _view_signal; 386 387 /** 388 * name: unmapped 389 * on: view, output(view-) 390 * when: After a previously mapped view becomes unmapped. This must be emitted 391 * for all views. 392 */ 393 using view_unmapped_signal = _view_signal; 394 395 /** 396 * name: set-output 397 * on: view 398 * when: Immediately after the view's output changes. Note that child views may 399 * still be on the old output. 400 * argument: The old output of the view. 401 */ 402 using view_set_output_signal = _output_signal; 403 404 /* ----------------------------------------------------------------------------/ 405 * View state signals 406 * -------------------------------------------------------------------------- */ 407 408 /** 409 * name: minimized 410 * on: view, output(view-) 411 * when: After the view's minimized state changes. 412 */ 413 struct view_minimized_signal : public _view_signal 414 { 415 /** true is minimized, false is restored */ 416 bool state; 417 }; 418 419 /** 420 * name: view-minimize-request 421 * on: output 422 * when: Emitted whenever some entity requests that the view's minimized state 423 * changes. If no plugin is available to service the request, it is carried 424 * out by core. See view_interface_t::minimize_request() 425 */ 426 struct view_minimize_request_signal : public _view_signal 427 { 428 /** true is minimized, false is restored */ 429 bool state; 430 431 /** 432 * Whether some plugin will service the minimization request, in which 433 * case other plugins and core should ignore the request. 434 */ 435 bool carried_out = false; 436 }; 437 438 /** 439 * name: tiled 440 * on: view, output(view-) 441 * when: After the view's tiled edges change. 442 */ 443 struct view_tiled_signal : public _view_signal 444 { 445 /** Previously tiled edges */ 446 uint32_t old_edges; 447 /** Currently tiled edges */ 448 uint32_t new_edges; 449 }; 450 451 /** 452 * name: view-tile-request 453 * on: output 454 * when: Emitted whenever some entity requests that the view's tiled edges 455 * change. If no plugin is available to service the request, it is carried 456 * out by core. See view_interface_t::tile_request() 457 */ 458 struct view_tile_request_signal : public _view_signal 459 { 460 /** The desired edges */ 461 uint32_t edges; 462 463 /** 464 * The geometry the view should have. This is for example the last geometry 465 * a view had before being tiled. The given geometry is only a hint by core 466 * and plugins may override it. It may also be undefined (0,0 0x0). 467 */ 468 wf::geometry_t desired_size; 469 470 /** 471 * The target workspace of the operation. 472 */ 473 wf::point_t workspace; 474 475 /** 476 * Whether some plugin will service the tile request, in which case other 477 * plugins and core should ignore the request. 478 */ 479 bool carried_out = false; 480 }; 481 482 483 /** 484 * name: fullscreen 485 * on: view, output(view-) 486 * when: After the view's fullscreen state changes. 487 */ 488 struct view_fullscreen_signal : public _view_signal 489 { 490 /** The desired fullscreen state */ 491 bool state; 492 493 /** 494 * For view-fullscreen-request: 495 * 496 * Whether some plugin will service the fullscreen request, in which case 497 * other plugins and core should ignore the request. 498 */ 499 bool carried_out = false; 500 501 /** 502 * For view-fullscreen-request: 503 * 504 * The geometry the view should have. This is for example the last geometry 505 * a view had before being fullscreened. The given geometry is only a hint 506 * by core and plugins may override it. It may also be undefined (0,0 0x0). 507 */ 508 wf::geometry_t desired_size; 509 510 /** 511 * For view-fullscreen-request: 512 * 513 * The target workspace of the operation. 514 */ 515 wf::point_t workspace; 516 }; 517 518 /** 519 * name: view-fullscreen-request 520 * on: output 521 * when: Emitted whenever some entity requests that the view's fullscreen state 522 * change. If no plugin is available to service the request, it is carried 523 * out by core. See view_interface_t::fullscreen_request() 524 */ 525 using view_fullscreen_request_signal = view_fullscreen_signal; 526 527 /** 528 * name: view-focus-request 529 * on: view, core 530 * when: Emitted whenever some entity (typically a panel) wants to focus the view. 531 */ 532 struct view_focus_request_signal : public _view_signal 533 { 534 /** Set to true if core and other plugins should not handle this request. */ 535 bool carried_out = false; 536 537 /** Set to true if the request comes from the view client itself */ 538 bool self_request; 539 }; 540 541 /** 542 * name: set-sticky 543 * on: view, output(view-) 544 * when: Whenever the view's sticky state changes. 545 */ 546 using view_set_sticky_signal = _view_signal; 547 548 /** 549 * name: title-changed 550 * on: view 551 * when: After the view's title has changed. 552 */ 553 using title_changed_signal = _view_signal; 554 555 /** 556 * name: app-id-changed 557 * on: view 558 * when: After the view's app-id has changed. 559 */ 560 using app_id_changed_signal = _view_signal; 561 562 /** 563 * name: view-show-window-menu 564 * on: output, core 565 * when: To show a menu with window related actions. 566 */ 567 struct view_show_window_menu_signal : public _view_signal 568 { 569 /** The position as requested by the client, in surface coordinates */ 570 wf::point_t relative_position; 571 }; 572 573 /** 574 * name: geometry-changed 575 * on: view, output(view-), core(view-) 576 * when: Whenever the view's wm geometry changes. 577 */ 578 struct view_geometry_changed_signal : public _view_signal 579 { 580 /** The old wm geometry */ 581 wf::geometry_t old_geometry; 582 }; 583 584 /** 585 * name: region-damaged 586 * on: view 587 * when: Whenever a region of the view becomes damaged, for ex. when the client 588 * updates its contents. 589 * argument: Unused. 590 */ 591 592 /** 593 * name: decoration-state-updated 594 * on: view, output(view-) 595 * when: Whenever the value of view::should_be_decorated() changes. 596 */ 597 using view_decoration_state_updated_signal = _view_signal; 598 599 /** 600 * name: decoration-changed 601 * on: view 602 * when: Whenever the view's decoration changes. 603 * argument: unused. 604 */ 605 606 /** 607 * name: ping-timeout 608 * on: view 609 * when: Whenever the client fails to respond to a ping request within 610 * the expected time(10 seconds). 611 */ 612 using view_ping_timeout_signal = _view_signal; 613 614 /* ----------------------------------------------------------------------------/ 615 * View <-> output signals 616 * -------------------------------------------------------------------------- */ 617 618 /** 619 * name: view-attached 620 * on: output 621 * when: As soon as the view's output is set to the given output. This is the 622 * first point where the view is considered to be part of that output. 623 */ 624 using view_attached_signal = _view_signal; 625 626 /** 627 * name: view-layer-attached 628 * on: output 629 * when: Emitted when the view is added to a layer in the output's workspace 630 * manager and it was in no layer previously. 631 */ 632 using view_layer_attached_signal = _view_signal; 633 634 /** 635 * name: view-detached 636 * on: output 637 * when: Emitted when the view's output is about to be changed to another one. 638 * This is the last point where the view is considered to be part of the given 639 * output. 640 */ 641 using view_detached_signal = _view_signal; 642 643 /** 644 * name: view-layer-detached 645 * on: output 646 * when: Emitted when the view is removed from a layer but is not added to 647 * another. 648 */ 649 using view_layer_detached_signal = _view_signal; 650 651 /** 652 * name: view-pre-moved-to-output 653 * on: core 654 * when: Immediately before the view is moved to another output. The usual 655 * sequence when moving views to another output is: 656 * 657 * pre-moved-to-output -> layer-detach -> detach -> 658 * attach -> layer-attach -> moved-to-output 659 */ 660 struct view_pre_moved_to_output_signal : public signal_data_t 661 { 662 /* The view being moved */ 663 wayfire_view view; 664 /* The output the view was on, may be NULL. */ 665 wf::output_t *old_output; 666 /* The output the view is being moved to. */ 667 wf::output_t *new_output; 668 }; 669 670 /** 671 * name: view-moved-to-output 672 * on: core 673 * when: After the view has been moved to a new output. 674 */ 675 using view_moved_to_output_signal = view_pre_moved_to_output_signal; 676 677 /** 678 * name: view-disappeared 679 * on: output 680 * when: This is a signal which combines view-unmapped, view-detached and 681 * view-minimized, and is emitted together with each of these three. Semantic 682 * meaning is that the view is no longer available for focus, interaction with 683 * the user, etc. 684 */ 685 using view_disappeared_signal = _view_signal; 686 687 /** 688 * name: view-focused 689 * on: output 690 * when: As soon as the output focus changes. 691 * argument: The newly focused view. 692 */ 693 using focus_view_signal = _view_signal; 694 695 /** 696 * name: view-move-request 697 * on: output 698 * when: Whenever an interactive move is requested on the view. See also 699 * view_interface_t::move_request() 700 */ 701 using view_move_request_signal = _view_signal; 702 703 /** 704 * name: view-resize-request 705 * on: output 706 * when: Whenever an interactive resize is requested on the view. See also 707 * view_interface_t::resize_request() 708 */ 709 struct view_resize_request_signal : public _view_signal 710 { 711 /** The requested resize edges */ 712 uint32_t edges; 713 }; 714 715 /** 716 * name: hints-changed 717 * on: view and core(view-) 718 * when: the client indicates the views hints have changed (example urgency hint). 719 */ 720 struct view_hints_changed_signal : public _view_signal 721 { 722 bool demands_attention = false; 723 }; 724 725 /** 726 * name: view-system-bell 727 * on: core 728 * when: Whenever a client wants to invoke the system bell if such is available. 729 * Note the system bell may or may not be tied to a particular view, so the 730 * signal may be emitted with a nullptr view. 731 */ 732 using view_system_bell_signal = _view_signal; 733 } 734 735 #endif 736