├── .github └── workflows │ └── pylint.yml ├── .gitignore ├── .pylintrc ├── LICENSE ├── README.md ├── pyproject.toml ├── requirements.txt ├── riverwm_utils ├── __init__.py ├── river-control-unstable-v1.xml ├── river-status-unstable-v1.xml ├── riverwm_utils.py └── wayland.xml ├── setup.cfg └── setup.py /.github/workflows/pylint.yml: -------------------------------------------------------------------------------- 1 | name: Pylint 2 | 3 | on: [push] 4 | 5 | jobs: 6 | build: 7 | runs-on: ubuntu-latest 8 | strategy: 9 | matrix: 10 | python-version: ["3.11"] 11 | steps: 12 | - uses: actions/checkout@v4 13 | - name: Set up Python ${{ matrix.python-version }} 14 | uses: actions/setup-python@v5 15 | with: 16 | python-version: ${{ matrix.python-version }} 17 | - name: Install dependencies 18 | run: | 19 | python -m pip install --upgrade pip 20 | pip install pylint 21 | - name: Analysing the code with pylint 22 | run: | 23 | pylint $(git ls-files '*.py') 24 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | 2 | # Created by https://www.toptal.com/developers/gitignore/api/python 3 | # Edit at https://www.toptal.com/developers/gitignore?templates=python 4 | 5 | ### Python ### 6 | # Byte-compiled / optimized / DLL files 7 | __pycache__/ 8 | *.py[cod] 9 | *$py.class 10 | 11 | # C extensions 12 | *.so 13 | 14 | # Distribution / packaging 15 | .Python 16 | build/ 17 | develop-eggs/ 18 | dist/ 19 | downloads/ 20 | eggs/ 21 | .eggs/ 22 | lib/ 23 | lib64/ 24 | parts/ 25 | sdist/ 26 | var/ 27 | wheels/ 28 | share/python-wheels/ 29 | *.egg-info/ 30 | .installed.cfg 31 | *.egg 32 | MANIFEST 33 | 34 | # PyInstaller 35 | # Usually these files are written by a python script from a template 36 | # before PyInstaller builds the exe, so as to inject date/other infos into it. 37 | *.manifest 38 | *.spec 39 | 40 | # Installer logs 41 | pip-log.txt 42 | pip-delete-this-directory.txt 43 | 44 | # Unit test / coverage reports 45 | htmlcov/ 46 | .tox/ 47 | .nox/ 48 | .coverage 49 | .coverage.* 50 | .cache 51 | nosetests.xml 52 | coverage.xml 53 | *.cover 54 | *.py,cover 55 | .hypothesis/ 56 | .pytest_cache/ 57 | cover/ 58 | 59 | # Translations 60 | *.mo 61 | *.pot 62 | 63 | # Django stuff: 64 | *.log 65 | local_settings.py 66 | db.sqlite3 67 | db.sqlite3-journal 68 | 69 | # Flask stuff: 70 | instance/ 71 | .webassets-cache 72 | 73 | # Scrapy stuff: 74 | .scrapy 75 | 76 | # Sphinx documentation 77 | docs/_build/ 78 | 79 | # PyBuilder 80 | .pybuilder/ 81 | target/ 82 | 83 | # Jupyter Notebook 84 | .ipynb_checkpoints 85 | 86 | # IPython 87 | profile_default/ 88 | ipython_config.py 89 | 90 | # pyenv 91 | # For a library or package, you might want to ignore these files since the code is 92 | # intended to run in multiple environments; otherwise, check them in: 93 | # .python-version 94 | 95 | # pipenv 96 | # According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control. 97 | # However, in case of collaboration, if having platform-specific dependencies or dependencies 98 | # having no cross-platform support, pipenv may install dependencies that don't work, or not 99 | # install all needed dependencies. 100 | #Pipfile.lock 101 | 102 | # poetry 103 | # Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control. 104 | # This is especially recommended for binary packages to ensure reproducibility, and is more 105 | # commonly ignored for libraries. 106 | # https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control 107 | #poetry.lock 108 | 109 | # PEP 582; used by e.g. github.com/David-OConnor/pyflow 110 | __pypackages__/ 111 | 112 | # Celery stuff 113 | celerybeat-schedule 114 | celerybeat.pid 115 | 116 | # SageMath parsed files 117 | *.sage.py 118 | 119 | # Environments 120 | .env 121 | .venv 122 | env/ 123 | venv/ 124 | ENV/ 125 | env.bak/ 126 | venv.bak/ 127 | 128 | # Spyder project settings 129 | .spyderproject 130 | .spyproject 131 | 132 | # Rope project settings 133 | .ropeproject 134 | 135 | # mkdocs documentation 136 | /site 137 | 138 | # mypy 139 | .mypy_cache/ 140 | .dmypy.json 141 | dmypy.json 142 | 143 | # Pyre type checker 144 | .pyre/ 145 | 146 | # pytype static type analyzer 147 | .pytype/ 148 | 149 | # Cython debug symbols 150 | cython_debug/ 151 | 152 | # PyCharm 153 | # JetBrains specific template is maintainted in a separate JetBrains.gitignore that can 154 | # be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore 155 | # and can be added to the global gitignore or merged into this file. For a more nuclear 156 | # option (not recommended) you can uncomment the following to ignore the entire idea folder. 157 | #.idea/ 158 | 159 | # End of https://www.toptal.com/developers/gitignore/api/python 160 | -------------------------------------------------------------------------------- /.pylintrc: -------------------------------------------------------------------------------- 1 | [main] 2 | max-branches=12 3 | max-statements=50 4 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | GNU GENERAL PUBLIC LICENSE 2 | Version 3, 29 June 2007 3 | 4 | Copyright (C) 2007 Free Software Foundation, Inc. 5 | Everyone is permitted to copy and distribute verbatim copies 6 | of this license document, but changing it is not allowed. 7 | 8 | Preamble 9 | 10 | The GNU General Public License is a free, copyleft license for 11 | software and other kinds of works. 12 | 13 | The licenses for most software and other practical works are designed 14 | to take away your freedom to share and change the works. By contrast, 15 | the GNU General Public License is intended to guarantee your freedom to 16 | share and change all versions of a program--to make sure it remains free 17 | software for all its users. We, the Free Software Foundation, use the 18 | GNU General Public License for most of our software; it applies also to 19 | any other work released this way by its authors. You can apply it to 20 | your programs, too. 21 | 22 | When we speak of free software, we are referring to freedom, not 23 | price. Our General Public Licenses are designed to make sure that you 24 | have the freedom to distribute copies of free software (and charge for 25 | them if you wish), that you receive source code or can get it if you 26 | want it, that you can change the software or use pieces of it in new 27 | free programs, and that you know you can do these things. 28 | 29 | To protect your rights, we need to prevent others from denying you 30 | these rights or asking you to surrender the rights. Therefore, you have 31 | certain responsibilities if you distribute copies of the software, or if 32 | you modify it: responsibilities to respect the freedom of others. 33 | 34 | For example, if you distribute copies of such a program, whether 35 | gratis or for a fee, you must pass on to the recipients the same 36 | freedoms that you received. You must make sure that they, too, receive 37 | or can get the source code. And you must show them these terms so they 38 | know their rights. 39 | 40 | Developers that use the GNU GPL protect your rights with two steps: 41 | (1) assert copyright on the software, and (2) offer you this License 42 | giving you legal permission to copy, distribute and/or modify it. 43 | 44 | For the developers' and authors' protection, the GPL clearly explains 45 | that there is no warranty for this free software. For both users' and 46 | authors' sake, the GPL requires that modified versions be marked as 47 | changed, so that their problems will not be attributed erroneously to 48 | authors of previous versions. 49 | 50 | Some devices are designed to deny users access to install or run 51 | modified versions of the software inside them, although the manufacturer 52 | can do so. This is fundamentally incompatible with the aim of 53 | protecting users' freedom to change the software. The systematic 54 | pattern of such abuse occurs in the area of products for individuals to 55 | use, which is precisely where it is most unacceptable. Therefore, we 56 | have designed this version of the GPL to prohibit the practice for those 57 | products. If such problems arise substantially in other domains, we 58 | stand ready to extend this provision to those domains in future versions 59 | of the GPL, as needed to protect the freedom of users. 60 | 61 | Finally, every program is threatened constantly by software patents. 62 | States should not allow patents to restrict development and use of 63 | software on general-purpose computers, but in those that do, we wish to 64 | avoid the special danger that patents applied to a free program could 65 | make it effectively proprietary. To prevent this, the GPL assures that 66 | patents cannot be used to render the program non-free. 67 | 68 | The precise terms and conditions for copying, distribution and 69 | modification follow. 70 | 71 | TERMS AND CONDITIONS 72 | 73 | 0. Definitions. 74 | 75 | "This License" refers to version 3 of the GNU General Public License. 76 | 77 | "Copyright" also means copyright-like laws that apply to other kinds of 78 | works, such as semiconductor masks. 79 | 80 | "The Program" refers to any copyrightable work licensed under this 81 | License. Each licensee is addressed as "you". "Licensees" and 82 | "recipients" may be individuals or organizations. 83 | 84 | To "modify" a work means to copy from or adapt all or part of the work 85 | in a fashion requiring copyright permission, other than the making of an 86 | exact copy. The resulting work is called a "modified version" of the 87 | earlier work or a work "based on" the earlier work. 88 | 89 | A "covered work" means either the unmodified Program or a work based 90 | on the Program. 91 | 92 | To "propagate" a work means to do anything with it that, without 93 | permission, would make you directly or secondarily liable for 94 | infringement under applicable copyright law, except executing it on a 95 | computer or modifying a private copy. Propagation includes copying, 96 | distribution (with or without modification), making available to the 97 | public, and in some countries other activities as well. 98 | 99 | To "convey" a work means any kind of propagation that enables other 100 | parties to make or receive copies. Mere interaction with a user through 101 | a computer network, with no transfer of a copy, is not conveying. 102 | 103 | An interactive user interface displays "Appropriate Legal Notices" 104 | to the extent that it includes a convenient and prominently visible 105 | feature that (1) displays an appropriate copyright notice, and (2) 106 | tells the user that there is no warranty for the work (except to the 107 | extent that warranties are provided), that licensees may convey the 108 | work under this License, and how to view a copy of this License. If 109 | the interface presents a list of user commands or options, such as a 110 | menu, a prominent item in the list meets this criterion. 111 | 112 | 1. Source Code. 113 | 114 | The "source code" for a work means the preferred form of the work 115 | for making modifications to it. "Object code" means any non-source 116 | form of a work. 117 | 118 | A "Standard Interface" means an interface that either is an official 119 | standard defined by a recognized standards body, or, in the case of 120 | interfaces specified for a particular programming language, one that 121 | is widely used among developers working in that language. 122 | 123 | The "System Libraries" of an executable work include anything, other 124 | than the work as a whole, that (a) is included in the normal form of 125 | packaging a Major Component, but which is not part of that Major 126 | Component, and (b) serves only to enable use of the work with that 127 | Major Component, or to implement a Standard Interface for which an 128 | implementation is available to the public in source code form. A 129 | "Major Component", in this context, means a major essential component 130 | (kernel, window system, and so on) of the specific operating system 131 | (if any) on which the executable work runs, or a compiler used to 132 | produce the work, or an object code interpreter used to run it. 133 | 134 | The "Corresponding Source" for a work in object code form means all 135 | the source code needed to generate, install, and (for an executable 136 | work) run the object code and to modify the work, including scripts to 137 | control those activities. However, it does not include the work's 138 | System Libraries, or general-purpose tools or generally available free 139 | programs which are used unmodified in performing those activities but 140 | which are not part of the work. For example, Corresponding Source 141 | includes interface definition files associated with source files for 142 | the work, and the source code for shared libraries and dynamically 143 | linked subprograms that the work is specifically designed to require, 144 | such as by intimate data communication or control flow between those 145 | subprograms and other parts of the work. 146 | 147 | The Corresponding Source need not include anything that users 148 | can regenerate automatically from other parts of the Corresponding 149 | Source. 150 | 151 | The Corresponding Source for a work in source code form is that 152 | same work. 153 | 154 | 2. Basic Permissions. 155 | 156 | All rights granted under this License are granted for the term of 157 | copyright on the Program, and are irrevocable provided the stated 158 | conditions are met. This License explicitly affirms your unlimited 159 | permission to run the unmodified Program. The output from running a 160 | covered work is covered by this License only if the output, given its 161 | content, constitutes a covered work. This License acknowledges your 162 | rights of fair use or other equivalent, as provided by copyright law. 163 | 164 | You may make, run and propagate covered works that you do not 165 | convey, without conditions so long as your license otherwise remains 166 | in force. You may convey covered works to others for the sole purpose 167 | of having them make modifications exclusively for you, or provide you 168 | with facilities for running those works, provided that you comply with 169 | the terms of this License in conveying all material for which you do 170 | not control copyright. Those thus making or running the covered works 171 | for you must do so exclusively on your behalf, under your direction 172 | and control, on terms that prohibit them from making any copies of 173 | your copyrighted material outside their relationship with you. 174 | 175 | Conveying under any other circumstances is permitted solely under 176 | the conditions stated below. Sublicensing is not allowed; section 10 177 | makes it unnecessary. 178 | 179 | 3. Protecting Users' Legal Rights From Anti-Circumvention Law. 180 | 181 | No covered work shall be deemed part of an effective technological 182 | measure under any applicable law fulfilling obligations under article 183 | 11 of the WIPO copyright treaty adopted on 20 December 1996, or 184 | similar laws prohibiting or restricting circumvention of such 185 | measures. 186 | 187 | When you convey a covered work, you waive any legal power to forbid 188 | circumvention of technological measures to the extent such circumvention 189 | is effected by exercising rights under this License with respect to 190 | the covered work, and you disclaim any intention to limit operation or 191 | modification of the work as a means of enforcing, against the work's 192 | users, your or third parties' legal rights to forbid circumvention of 193 | technological measures. 194 | 195 | 4. Conveying Verbatim Copies. 196 | 197 | You may convey verbatim copies of the Program's source code as you 198 | receive it, in any medium, provided that you conspicuously and 199 | appropriately publish on each copy an appropriate copyright notice; 200 | keep intact all notices stating that this License and any 201 | non-permissive terms added in accord with section 7 apply to the code; 202 | keep intact all notices of the absence of any warranty; and give all 203 | recipients a copy of this License along with the Program. 204 | 205 | You may charge any price or no price for each copy that you convey, 206 | and you may offer support or warranty protection for a fee. 207 | 208 | 5. Conveying Modified Source Versions. 209 | 210 | You may convey a work based on the Program, or the modifications to 211 | produce it from the Program, in the form of source code under the 212 | terms of section 4, provided that you also meet all of these conditions: 213 | 214 | a) The work must carry prominent notices stating that you modified 215 | it, and giving a relevant date. 216 | 217 | b) The work must carry prominent notices stating that it is 218 | released under this License and any conditions added under section 219 | 7. This requirement modifies the requirement in section 4 to 220 | "keep intact all notices". 221 | 222 | c) You must license the entire work, as a whole, under this 223 | License to anyone who comes into possession of a copy. This 224 | License will therefore apply, along with any applicable section 7 225 | additional terms, to the whole of the work, and all its parts, 226 | regardless of how they are packaged. This License gives no 227 | permission to license the work in any other way, but it does not 228 | invalidate such permission if you have separately received it. 229 | 230 | d) If the work has interactive user interfaces, each must display 231 | Appropriate Legal Notices; however, if the Program has interactive 232 | interfaces that do not display Appropriate Legal Notices, your 233 | work need not make them do so. 234 | 235 | A compilation of a covered work with other separate and independent 236 | works, which are not by their nature extensions of the covered work, 237 | and which are not combined with it such as to form a larger program, 238 | in or on a volume of a storage or distribution medium, is called an 239 | "aggregate" if the compilation and its resulting copyright are not 240 | used to limit the access or legal rights of the compilation's users 241 | beyond what the individual works permit. Inclusion of a covered work 242 | in an aggregate does not cause this License to apply to the other 243 | parts of the aggregate. 244 | 245 | 6. Conveying Non-Source Forms. 246 | 247 | You may convey a covered work in object code form under the terms 248 | of sections 4 and 5, provided that you also convey the 249 | machine-readable Corresponding Source under the terms of this License, 250 | in one of these ways: 251 | 252 | a) Convey the object code in, or embodied in, a physical product 253 | (including a physical distribution medium), accompanied by the 254 | Corresponding Source fixed on a durable physical medium 255 | customarily used for software interchange. 256 | 257 | b) Convey the object code in, or embodied in, a physical product 258 | (including a physical distribution medium), accompanied by a 259 | written offer, valid for at least three years and valid for as 260 | long as you offer spare parts or customer support for that product 261 | model, to give anyone who possesses the object code either (1) a 262 | copy of the Corresponding Source for all the software in the 263 | product that is covered by this License, on a durable physical 264 | medium customarily used for software interchange, for a price no 265 | more than your reasonable cost of physically performing this 266 | conveying of source, or (2) access to copy the 267 | Corresponding Source from a network server at no charge. 268 | 269 | c) Convey individual copies of the object code with a copy of the 270 | written offer to provide the Corresponding Source. This 271 | alternative is allowed only occasionally and noncommercially, and 272 | only if you received the object code with such an offer, in accord 273 | with subsection 6b. 274 | 275 | d) Convey the object code by offering access from a designated 276 | place (gratis or for a charge), and offer equivalent access to the 277 | Corresponding Source in the same way through the same place at no 278 | further charge. You need not require recipients to copy the 279 | Corresponding Source along with the object code. If the place to 280 | copy the object code is a network server, the Corresponding Source 281 | may be on a different server (operated by you or a third party) 282 | that supports equivalent copying facilities, provided you maintain 283 | clear directions next to the object code saying where to find the 284 | Corresponding Source. Regardless of what server hosts the 285 | Corresponding Source, you remain obligated to ensure that it is 286 | available for as long as needed to satisfy these requirements. 287 | 288 | e) Convey the object code using peer-to-peer transmission, provided 289 | you inform other peers where the object code and Corresponding 290 | Source of the work are being offered to the general public at no 291 | charge under subsection 6d. 292 | 293 | A separable portion of the object code, whose source code is excluded 294 | from the Corresponding Source as a System Library, need not be 295 | included in conveying the object code work. 296 | 297 | A "User Product" is either (1) a "consumer product", which means any 298 | tangible personal property which is normally used for personal, family, 299 | or household purposes, or (2) anything designed or sold for incorporation 300 | into a dwelling. In determining whether a product is a consumer product, 301 | doubtful cases shall be resolved in favor of coverage. For a particular 302 | product received by a particular user, "normally used" refers to a 303 | typical or common use of that class of product, regardless of the status 304 | of the particular user or of the way in which the particular user 305 | actually uses, or expects or is expected to use, the product. A product 306 | is a consumer product regardless of whether the product has substantial 307 | commercial, industrial or non-consumer uses, unless such uses represent 308 | the only significant mode of use of the product. 309 | 310 | "Installation Information" for a User Product means any methods, 311 | procedures, authorization keys, or other information required to install 312 | and execute modified versions of a covered work in that User Product from 313 | a modified version of its Corresponding Source. The information must 314 | suffice to ensure that the continued functioning of the modified object 315 | code is in no case prevented or interfered with solely because 316 | modification has been made. 317 | 318 | If you convey an object code work under this section in, or with, or 319 | specifically for use in, a User Product, and the conveying occurs as 320 | part of a transaction in which the right of possession and use of the 321 | User Product is transferred to the recipient in perpetuity or for a 322 | fixed term (regardless of how the transaction is characterized), the 323 | Corresponding Source conveyed under this section must be accompanied 324 | by the Installation Information. But this requirement does not apply 325 | if neither you nor any third party retains the ability to install 326 | modified object code on the User Product (for example, the work has 327 | been installed in ROM). 328 | 329 | The requirement to provide Installation Information does not include a 330 | requirement to continue to provide support service, warranty, or updates 331 | for a work that has been modified or installed by the recipient, or for 332 | the User Product in which it has been modified or installed. Access to a 333 | network may be denied when the modification itself materially and 334 | adversely affects the operation of the network or violates the rules and 335 | protocols for communication across the network. 336 | 337 | Corresponding Source conveyed, and Installation Information provided, 338 | in accord with this section must be in a format that is publicly 339 | documented (and with an implementation available to the public in 340 | source code form), and must require no special password or key for 341 | unpacking, reading or copying. 342 | 343 | 7. Additional Terms. 344 | 345 | "Additional permissions" are terms that supplement the terms of this 346 | License by making exceptions from one or more of its conditions. 347 | Additional permissions that are applicable to the entire Program shall 348 | be treated as though they were included in this License, to the extent 349 | that they are valid under applicable law. If additional permissions 350 | apply only to part of the Program, that part may be used separately 351 | under those permissions, but the entire Program remains governed by 352 | this License without regard to the additional permissions. 353 | 354 | When you convey a copy of a covered work, you may at your option 355 | remove any additional permissions from that copy, or from any part of 356 | it. (Additional permissions may be written to require their own 357 | removal in certain cases when you modify the work.) You may place 358 | additional permissions on material, added by you to a covered work, 359 | for which you have or can give appropriate copyright permission. 360 | 361 | Notwithstanding any other provision of this License, for material you 362 | add to a covered work, you may (if authorized by the copyright holders of 363 | that material) supplement the terms of this License with terms: 364 | 365 | a) Disclaiming warranty or limiting liability differently from the 366 | terms of sections 15 and 16 of this License; or 367 | 368 | b) Requiring preservation of specified reasonable legal notices or 369 | author attributions in that material or in the Appropriate Legal 370 | Notices displayed by works containing it; or 371 | 372 | c) Prohibiting misrepresentation of the origin of that material, or 373 | requiring that modified versions of such material be marked in 374 | reasonable ways as different from the original version; or 375 | 376 | d) Limiting the use for publicity purposes of names of licensors or 377 | authors of the material; or 378 | 379 | e) Declining to grant rights under trademark law for use of some 380 | trade names, trademarks, or service marks; or 381 | 382 | f) Requiring indemnification of licensors and authors of that 383 | material by anyone who conveys the material (or modified versions of 384 | it) with contractual assumptions of liability to the recipient, for 385 | any liability that these contractual assumptions directly impose on 386 | those licensors and authors. 387 | 388 | All other non-permissive additional terms are considered "further 389 | restrictions" within the meaning of section 10. If the Program as you 390 | received it, or any part of it, contains a notice stating that it is 391 | governed by this License along with a term that is a further 392 | restriction, you may remove that term. If a license document contains 393 | a further restriction but permits relicensing or conveying under this 394 | License, you may add to a covered work material governed by the terms 395 | of that license document, provided that the further restriction does 396 | not survive such relicensing or conveying. 397 | 398 | If you add terms to a covered work in accord with this section, you 399 | must place, in the relevant source files, a statement of the 400 | additional terms that apply to those files, or a notice indicating 401 | where to find the applicable terms. 402 | 403 | Additional terms, permissive or non-permissive, may be stated in the 404 | form of a separately written license, or stated as exceptions; 405 | the above requirements apply either way. 406 | 407 | 8. Termination. 408 | 409 | You may not propagate or modify a covered work except as expressly 410 | provided under this License. Any attempt otherwise to propagate or 411 | modify it is void, and will automatically terminate your rights under 412 | this License (including any patent licenses granted under the third 413 | paragraph of section 11). 414 | 415 | However, if you cease all violation of this License, then your 416 | license from a particular copyright holder is reinstated (a) 417 | provisionally, unless and until the copyright holder explicitly and 418 | finally terminates your license, and (b) permanently, if the copyright 419 | holder fails to notify you of the violation by some reasonable means 420 | prior to 60 days after the cessation. 421 | 422 | Moreover, your license from a particular copyright holder is 423 | reinstated permanently if the copyright holder notifies you of the 424 | violation by some reasonable means, this is the first time you have 425 | received notice of violation of this License (for any work) from that 426 | copyright holder, and you cure the violation prior to 30 days after 427 | your receipt of the notice. 428 | 429 | Termination of your rights under this section does not terminate the 430 | licenses of parties who have received copies or rights from you under 431 | this License. If your rights have been terminated and not permanently 432 | reinstated, you do not qualify to receive new licenses for the same 433 | material under section 10. 434 | 435 | 9. Acceptance Not Required for Having Copies. 436 | 437 | You are not required to accept this License in order to receive or 438 | run a copy of the Program. Ancillary propagation of a covered work 439 | occurring solely as a consequence of using peer-to-peer transmission 440 | to receive a copy likewise does not require acceptance. However, 441 | nothing other than this License grants you permission to propagate or 442 | modify any covered work. These actions infringe copyright if you do 443 | not accept this License. Therefore, by modifying or propagating a 444 | covered work, you indicate your acceptance of this License to do so. 445 | 446 | 10. Automatic Licensing of Downstream Recipients. 447 | 448 | Each time you convey a covered work, the recipient automatically 449 | receives a license from the original licensors, to run, modify and 450 | propagate that work, subject to this License. You are not responsible 451 | for enforcing compliance by third parties with this License. 452 | 453 | An "entity transaction" is a transaction transferring control of an 454 | organization, or substantially all assets of one, or subdividing an 455 | organization, or merging organizations. If propagation of a covered 456 | work results from an entity transaction, each party to that 457 | transaction who receives a copy of the work also receives whatever 458 | licenses to the work the party's predecessor in interest had or could 459 | give under the previous paragraph, plus a right to possession of the 460 | Corresponding Source of the work from the predecessor in interest, if 461 | the predecessor has it or can get it with reasonable efforts. 462 | 463 | You may not impose any further restrictions on the exercise of the 464 | rights granted or affirmed under this License. For example, you may 465 | not impose a license fee, royalty, or other charge for exercise of 466 | rights granted under this License, and you may not initiate litigation 467 | (including a cross-claim or counterclaim in a lawsuit) alleging that 468 | any patent claim is infringed by making, using, selling, offering for 469 | sale, or importing the Program or any portion of it. 470 | 471 | 11. Patents. 472 | 473 | A "contributor" is a copyright holder who authorizes use under this 474 | License of the Program or a work on which the Program is based. The 475 | work thus licensed is called the contributor's "contributor version". 476 | 477 | A contributor's "essential patent claims" are all patent claims 478 | owned or controlled by the contributor, whether already acquired or 479 | hereafter acquired, that would be infringed by some manner, permitted 480 | by this License, of making, using, or selling its contributor version, 481 | but do not include claims that would be infringed only as a 482 | consequence of further modification of the contributor version. For 483 | purposes of this definition, "control" includes the right to grant 484 | patent sublicenses in a manner consistent with the requirements of 485 | this License. 486 | 487 | Each contributor grants you a non-exclusive, worldwide, royalty-free 488 | patent license under the contributor's essential patent claims, to 489 | make, use, sell, offer for sale, import and otherwise run, modify and 490 | propagate the contents of its contributor version. 491 | 492 | In the following three paragraphs, a "patent license" is any express 493 | agreement or commitment, however denominated, not to enforce a patent 494 | (such as an express permission to practice a patent or covenant not to 495 | sue for patent infringement). To "grant" such a patent license to a 496 | party means to make such an agreement or commitment not to enforce a 497 | patent against the party. 498 | 499 | If you convey a covered work, knowingly relying on a patent license, 500 | and the Corresponding Source of the work is not available for anyone 501 | to copy, free of charge and under the terms of this License, through a 502 | publicly available network server or other readily accessible means, 503 | then you must either (1) cause the Corresponding Source to be so 504 | available, or (2) arrange to deprive yourself of the benefit of the 505 | patent license for this particular work, or (3) arrange, in a manner 506 | consistent with the requirements of this License, to extend the patent 507 | license to downstream recipients. "Knowingly relying" means you have 508 | actual knowledge that, but for the patent license, your conveying the 509 | covered work in a country, or your recipient's use of the covered work 510 | in a country, would infringe one or more identifiable patents in that 511 | country that you have reason to believe are valid. 512 | 513 | If, pursuant to or in connection with a single transaction or 514 | arrangement, you convey, or propagate by procuring conveyance of, a 515 | covered work, and grant a patent license to some of the parties 516 | receiving the covered work authorizing them to use, propagate, modify 517 | or convey a specific copy of the covered work, then the patent license 518 | you grant is automatically extended to all recipients of the covered 519 | work and works based on it. 520 | 521 | A patent license is "discriminatory" if it does not include within 522 | the scope of its coverage, prohibits the exercise of, or is 523 | conditioned on the non-exercise of one or more of the rights that are 524 | specifically granted under this License. You may not convey a covered 525 | work if you are a party to an arrangement with a third party that is 526 | in the business of distributing software, under which you make payment 527 | to the third party based on the extent of your activity of conveying 528 | the work, and under which the third party grants, to any of the 529 | parties who would receive the covered work from you, a discriminatory 530 | patent license (a) in connection with copies of the covered work 531 | conveyed by you (or copies made from those copies), or (b) primarily 532 | for and in connection with specific products or compilations that 533 | contain the covered work, unless you entered into that arrangement, 534 | or that patent license was granted, prior to 28 March 2007. 535 | 536 | Nothing in this License shall be construed as excluding or limiting 537 | any implied license or other defenses to infringement that may 538 | otherwise be available to you under applicable patent law. 539 | 540 | 12. No Surrender of Others' Freedom. 541 | 542 | If conditions are imposed on you (whether by court order, agreement or 543 | otherwise) that contradict the conditions of this License, they do not 544 | excuse you from the conditions of this License. If you cannot convey a 545 | covered work so as to satisfy simultaneously your obligations under this 546 | License and any other pertinent obligations, then as a consequence you may 547 | not convey it at all. For example, if you agree to terms that obligate you 548 | to collect a royalty for further conveying from those to whom you convey 549 | the Program, the only way you could satisfy both those terms and this 550 | License would be to refrain entirely from conveying the Program. 551 | 552 | 13. Use with the GNU Affero General Public License. 553 | 554 | Notwithstanding any other provision of this License, you have 555 | permission to link or combine any covered work with a work licensed 556 | under version 3 of the GNU Affero General Public License into a single 557 | combined work, and to convey the resulting work. The terms of this 558 | License will continue to apply to the part which is the covered work, 559 | but the special requirements of the GNU Affero General Public License, 560 | section 13, concerning interaction through a network will apply to the 561 | combination as such. 562 | 563 | 14. Revised Versions of this License. 564 | 565 | The Free Software Foundation may publish revised and/or new versions of 566 | the GNU General Public License from time to time. Such new versions will 567 | be similar in spirit to the present version, but may differ in detail to 568 | address new problems or concerns. 569 | 570 | Each version is given a distinguishing version number. If the 571 | Program specifies that a certain numbered version of the GNU General 572 | Public License "or any later version" applies to it, you have the 573 | option of following the terms and conditions either of that numbered 574 | version or of any later version published by the Free Software 575 | Foundation. If the Program does not specify a version number of the 576 | GNU General Public License, you may choose any version ever published 577 | by the Free Software Foundation. 578 | 579 | If the Program specifies that a proxy can decide which future 580 | versions of the GNU General Public License can be used, that proxy's 581 | public statement of acceptance of a version permanently authorizes you 582 | to choose that version for the Program. 583 | 584 | Later license versions may give you additional or different 585 | permissions. However, no additional obligations are imposed on any 586 | author or copyright holder as a result of your choosing to follow a 587 | later version. 588 | 589 | 15. Disclaimer of Warranty. 590 | 591 | THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY 592 | APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT 593 | HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY 594 | OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, 595 | THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 596 | PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM 597 | IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF 598 | ALL NECESSARY SERVICING, REPAIR OR CORRECTION. 599 | 600 | 16. Limitation of Liability. 601 | 602 | IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING 603 | WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS 604 | THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY 605 | GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE 606 | USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF 607 | DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD 608 | PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), 609 | EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF 610 | SUCH DAMAGES. 611 | 612 | 17. Interpretation of Sections 15 and 16. 613 | 614 | If the disclaimer of warranty and limitation of liability provided 615 | above cannot be given local legal effect according to their terms, 616 | reviewing courts shall apply local law that most closely approximates 617 | an absolute waiver of all civil liability in connection with the 618 | Program, unless a warranty or assumption of liability accompanies a 619 | copy of the Program in return for a fee. 620 | 621 | END OF TERMS AND CONDITIONS 622 | 623 | How to Apply These Terms to Your New Programs 624 | 625 | If you develop a new program, and you want it to be of the greatest 626 | possible use to the public, the best way to achieve this is to make it 627 | free software which everyone can redistribute and change under these terms. 628 | 629 | To do so, attach the following notices to the program. It is safest 630 | to attach them to the start of each source file to most effectively 631 | state the exclusion of warranty; and each file should have at least 632 | the "copyright" line and a pointer to where the full notice is found. 633 | 634 | 635 | Copyright (C) 636 | 637 | This program is free software: you can redistribute it and/or modify 638 | it under the terms of the GNU General Public License as published by 639 | the Free Software Foundation, either version 3 of the License, or 640 | (at your option) any later version. 641 | 642 | This program is distributed in the hope that it will be useful, 643 | but WITHOUT ANY WARRANTY; without even the implied warranty of 644 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 645 | GNU General Public License for more details. 646 | 647 | You should have received a copy of the GNU General Public License 648 | along with this program. If not, see . 649 | 650 | Also add information on how to contact you by electronic and paper mail. 651 | 652 | If the program does terminal interaction, make it output a short 653 | notice like this when it starts in an interactive mode: 654 | 655 | Copyright (C) 656 | This program comes with ABSOLUTELY NO WARRANTY; for details type `show w'. 657 | This is free software, and you are welcome to redistribute it 658 | under certain conditions; type `show c' for details. 659 | 660 | The hypothetical commands `show w' and `show c' should show the appropriate 661 | parts of the General Public License. Of course, your program's commands 662 | might be different; for a GUI interface, you would use an "about box". 663 | 664 | You should also get your employer (if you work as a programmer) or school, 665 | if any, to sign a "copyright disclaimer" for the program, if necessary. 666 | For more information on this, and how to apply and follow the GNU GPL, see 667 | . 668 | 669 | The GNU General Public License does not permit incorporating your program 670 | into proprietary programs. If your program is a subroutine library, you 671 | may consider it more useful to permit linking proprietary applications with 672 | the library. If this is what you want to do, use the GNU Lesser General 673 | Public License instead of this License. But first, please read 674 | . 675 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # riverwm-utils 2 | Utilities for the River Wayland compositor. Currently just one utility is included. 3 | 4 | ## Usage 5 | 6 | ### cycle-focused-tags 7 | 8 | Change to either the next or previous focused tags. 9 | 10 | As can be seen in a [pull 11 | request](https://github.com/riverwm/river/pull/506), this 12 | functionality can easily be built directly into river. However, [as 13 | explained by Leon 14 | Plickat](https://github.com/riverwm/river/pull/506#issuecomment-1008021752) 15 | there is a plan to separate the window management to a separate 16 | client, and as such new additions are not being accepted. The 17 | approach implemented here was suggested and sample code was 18 | provided. That sample code forms the basis of this script. 19 | 20 | The script takes two arguments: the first is being the direction 21 | next|previous, the second being the maximum number of tags at which 22 | the cycling should wrap back to the first tag (or to the last tag from 23 | the first tag). 24 | 25 | If the second argument is omitted the maximum number of tags is 26 | assumed to be 32. If both arguments are omitted the direction, 27 | next, will be used. 28 | 29 | The script can be called using spawn in the users init file. For example: 30 | ``` 31 | riverctl map normal Mod4 Up spawn "cycle-focused-tags +1 9" 32 | riverctl map normal Mod4 Down spawn "cycle-focused-tags -1 9" 33 | ``` 34 | 35 | 36 | ## Install 37 | 38 | ### Development version 39 | Clone the repository: 40 | ``` 41 | git clone https://github.com/NickHastings/riverwm-utils.git 42 | ``` 43 | Install locally with pip 44 | ``` 45 | python3 -m pip install ./riverwm-utils 46 | ``` 47 | ### Stable realeases 48 | ``` 49 | python3 -m pip install riverwm-utils 50 | ``` 51 | 52 | ### Wayland protocols and pywayland 53 | 54 | For `cycle-focused-tags` to work the relevant wayland protocol xml 55 | files will need to be scanned by pywayland. If this has not already 56 | been done `cycle-focused-tags` will attempt to do so. 57 | 58 | ## Licensing 59 | 60 | riverwm-utils is released under the GNU General Public License v3.0 only. 61 | 62 | The protocols in the `*.xml` files are released under various licenses by 63 | various parties. You should refer to the copyright block of each protocol for 64 | the licensing information. 65 | -------------------------------------------------------------------------------- /pyproject.toml: -------------------------------------------------------------------------------- 1 | [build-system] 2 | requires = [ 3 | "setuptools>=42" 4 | ] 5 | build-backend = "setuptools.build_meta" 6 | -------------------------------------------------------------------------------- /requirements.txt: -------------------------------------------------------------------------------- 1 | pywayland==0.4.7 2 | -------------------------------------------------------------------------------- /riverwm_utils/__init__.py: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/NickHastings/riverwm-utils/bed817bc61e1ab0530352c019ab2b1f6dec7de99/riverwm_utils/__init__.py -------------------------------------------------------------------------------- /riverwm_utils/river-control-unstable-v1.xml: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | Copyright 2020 The River Developers 5 | 6 | Permission to use, copy, modify, and/or distribute this software for any 7 | purpose with or without fee is hereby granted, provided that the above 8 | copyright notice and this permission notice appear in all copies. 9 | 10 | THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 11 | WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 12 | MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 13 | ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 14 | WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 15 | ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 16 | OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 17 | 18 | 19 | 20 | 21 | This interface allows clients to run compositor commands and receive a 22 | success/failure response with output or a failure message respectively. 23 | 24 | Each command is built up in a series of add_argument requests and 25 | executed with a run_command request. The first argument is the command 26 | to be run. 27 | 28 | A complete list of commands should be made available in the man page of 29 | the compositor. 30 | 31 | 32 | 33 | 34 | This request indicates that the client will not use the 35 | river_control object any more. Objects that have been created 36 | through this instance are not affected. 37 | 38 | 39 | 40 | 41 | 42 | Arguments are stored by the server in the order they were sent until 43 | the run_command request is made. 44 | 45 | 46 | 47 | 48 | 49 | 50 | Execute the command built up using the add_argument request for the 51 | given seat. 52 | 53 | 54 | 56 | 57 | 58 | 59 | 60 | 61 | This object is created by the run_command request. Exactly one of the 62 | success or failure events will be sent. This object will be destroyed 63 | by the compositor after one of the events is sent. 64 | 65 | 66 | 67 | 68 | Sent when the command has been successfully received and executed by 69 | the compositor. Some commands may produce output, in which case the 70 | output argument will be a non-empty string. 71 | 72 | 73 | 74 | 75 | 76 | 77 | Sent when the command could not be carried out. This could be due to 78 | sending a non-existent command, no command, not enough arguments, too 79 | many arguments, invalid arguments, etc. 80 | 81 | 83 | 84 | 85 | 86 | -------------------------------------------------------------------------------- /riverwm_utils/river-status-unstable-v1.xml: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | Copyright 2020 The River Developers 5 | 6 | Permission to use, copy, modify, and/or distribute this software for any 7 | purpose with or without fee is hereby granted, provided that the above 8 | copyright notice and this permission notice appear in all copies. 9 | 10 | THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 11 | WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 12 | MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 13 | ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 14 | WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 15 | ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 16 | OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 17 | 18 | 19 | 20 | 21 | A global factory for objects that receive status information specific 22 | to river. It could be used to implement, for example, a status bar. 23 | 24 | 25 | 26 | 27 | This request indicates that the client will not use the 28 | river_status_manager object any more. Objects that have been created 29 | through this instance are not affected. 30 | 31 | 32 | 33 | 34 | 35 | This creates a new river_output_status object for the given wl_output. 36 | 37 | 38 | 39 | 40 | 41 | 42 | 43 | This creates a new river_seat_status object for the given wl_seat. 44 | 45 | 46 | 47 | 48 | 49 | 50 | 51 | 52 | This interface allows clients to receive information about the current 53 | windowing state of an output. 54 | 55 | 56 | 57 | 58 | This request indicates that the client will not use the 59 | river_output_status object any more. 60 | 61 | 62 | 63 | 64 | 65 | Sent once binding the interface and again whenever the tag focus of 66 | the output changes. 67 | 68 | 69 | 70 | 71 | 72 | 73 | Sent once on binding the interface and again whenever the tag state 74 | of the output changes. 75 | 76 | 77 | 78 | 79 | 80 | 81 | Sent once on binding the interface and again whenever the set of 82 | tags with at least one urgent view changes. 83 | 84 | 85 | 86 | 87 | 88 | 89 | Sent once on binding the interface should a layout name exist and again 90 | whenever the name changes. 91 | 92 | 93 | 94 | 95 | 96 | 97 | Sent when the current layout name has been removed without a new one 98 | being set, for example when the active layout generator disconnects. 99 | 100 | 101 | 102 | 103 | 104 | 105 | This interface allows clients to receive information about the current 106 | focus of a seat. Note that (un)focused_output events will only be sent 107 | if the client has bound the relevant wl_output globals. 108 | 109 | 110 | 111 | 112 | This request indicates that the client will not use the 113 | river_seat_status object any more. 114 | 115 | 116 | 117 | 118 | 119 | Sent on binding the interface and again whenever an output gains focus. 120 | 121 | 122 | 123 | 124 | 125 | 126 | Sent whenever an output loses focus. 127 | 128 | 129 | 130 | 131 | 132 | 133 | Sent once on binding the interface and again whenever the focused 134 | view or a property thereof changes. The title may be an empty string 135 | if no view is focused or the focused view did not set a title. 136 | 137 | 138 | 139 | 140 | 141 | 142 | Sent once on binding the interface and again whenever a new mode 143 | is entered (e.g. with riverctl enter-mode foobar). 144 | 145 | 146 | 147 | 148 | 149 | -------------------------------------------------------------------------------- /riverwm_utils/riverwm_utils.py: -------------------------------------------------------------------------------- 1 | '''Utilities for river wayland compositor''' 2 | import sys 3 | import os 4 | import argparse 5 | import struct 6 | # pylint: disable=global-statement 7 | try: 8 | from pywayland.protocol.wayland import WlOutput 9 | from pywayland.protocol.wayland import WlSeat 10 | from pywayland.protocol.wayland import WlRegistry 11 | from pywayland.protocol.river_control_unstable_v1 import ZriverControlV1 12 | from pywayland.protocol.river_status_unstable_v1 import ZriverStatusManagerV1 # noqa: E501 13 | except ModuleNotFoundError: 14 | try: 15 | from pywayland.scanner.protocol import Protocol 16 | import pywayland 17 | this_dir = os.path.split(__file__)[0] 18 | protocol_dir = os.path.join(this_dir) 19 | input_files = ['wayland.xml', 20 | 'river-control-unstable-v1.xml', 21 | 'river-status-unstable-v1.xml'] 22 | 23 | protocols = [Protocol.parse_file(os.path.join( 24 | protocol_dir, input_file)) for input_file in input_files] 25 | protocol_imports = { 26 | interface.name: protocol.name 27 | for protocol in protocols 28 | for interface in protocol.interface 29 | } 30 | 31 | pywayland_dir = os.path.split(pywayland.__file__)[0] 32 | output_dir = os.path.join(pywayland_dir, 'protocol') 33 | for protocol in protocols: 34 | protocol.output(output_dir, protocol_imports) 35 | print('Generated river bindings.') 36 | print('Please try running cycle-focused-tags again.') 37 | 38 | except ImportError: 39 | THIS_DIR = os.path.split(__file__)[0] 40 | PROTOCOL_DIR = os.path.normpath( 41 | os.path.join(THIS_DIR, '..', 'protocol')) 42 | ERROR_TEXT = (f''' 43 | Your pywayland package does not have bindings for 44 | river-control-unstable-v1 and/or river-status-unstable-v1. 45 | 46 | An attempt was made to generate them but it failed. You may be able to 47 | generate the manually with the following command: 48 | 49 | python3 -m pywayland.scanner -i {PROTOCOL_DIR}/wayland.xml ''' 50 | f'{PROTOCOL_DIR}/river-control-unstable-v1.xml ' 51 | f'{PROTOCOL_DIR}/river-status-unstable-v1.xml') 52 | 53 | print(ERROR_TEXT) 54 | 55 | sys.exit() 56 | 57 | from pywayland.client import Display # pylint: disable=import-error 58 | 59 | 60 | STATUS_MANAGER = None 61 | CONTROL = None 62 | 63 | OUTPUTS = [] 64 | SEAT = None 65 | 66 | 67 | class Output: 68 | '''Represents a wayland output a.k.a. a display''' 69 | def __init__(self): 70 | self.wl_output = None 71 | self.focused_tags = None 72 | self.view_tags = None 73 | self.tags = None 74 | self.status = None 75 | 76 | def destroy(self) -> None: 77 | '''Cleanup''' 78 | if self.wl_output is not None: 79 | self.wl_output.destroy() 80 | if self.status is not None: 81 | self.status.destroy() 82 | 83 | def configure(self) -> None: 84 | '''Setup''' 85 | self.status = STATUS_MANAGER.get_river_output_status(self.wl_output) 86 | self.status.user_data = self 87 | self.status.dispatcher["focused_tags"] = self.handle_focused_tags 88 | self.status.dispatcher["view_tags"] = self.handle_view_tags 89 | 90 | def handle_focused_tags(self, _, tags: int) -> None: 91 | '''Handle Event''' 92 | self.focused_tags = tags 93 | 94 | def handle_view_tags(self, _, tags: int) -> None: 95 | '''Handle Event''' 96 | self.view_tags = tags 97 | 98 | 99 | class Seat: 100 | '''Represents a wayland seat''' 101 | def __init__(self): 102 | self.wl_seat = None 103 | self.status = None 104 | self.focused_output = None 105 | 106 | def destroy(self) -> None: 107 | '''Cleanup''' 108 | if self.wl_seat is not None: 109 | self.wl_seat.destroy() 110 | 111 | if self.status is not None: 112 | self.status.destroy() 113 | 114 | def configure(self) -> None: 115 | '''Setup''' 116 | self.status = STATUS_MANAGER.get_river_seat_status(self.wl_seat) 117 | self.status.user_data = self 118 | self.status.dispatcher["focused_output"] = self.handle_focused_output 119 | 120 | def handle_focused_output(self, _, wl_output: WlOutput) -> None: 121 | '''Handle Event''' 122 | for output in OUTPUTS: 123 | if output.wl_output == wl_output: 124 | self.focused_output = output 125 | 126 | 127 | def registry_handle_global(registry: WlRegistry, wid: int, interface: str, 128 | version: int) -> None: 129 | '''Main Event Handler''' 130 | global STATUS_MANAGER 131 | global CONTROL 132 | global SEAT 133 | 134 | if interface == 'zriver_status_manager_v1': 135 | STATUS_MANAGER = registry.bind(wid, ZriverStatusManagerV1, version) 136 | elif interface == 'zriver_control_v1': 137 | CONTROL = registry.bind(wid, ZriverControlV1, version) 138 | elif interface == 'wl_output': 139 | output = Output() 140 | output.wl_output = registry.bind(wid, WlOutput, version) 141 | OUTPUTS.append(output) 142 | elif interface == 'wl_seat': 143 | # We only care about the first seat 144 | if SEAT is None: 145 | SEAT = Seat() 146 | SEAT.wl_seat = registry.bind(wid, WlSeat, version) 147 | 148 | 149 | def prepare_display(display: Display) -> None: 150 | '''Prepare display global objects''' 151 | display.connect() 152 | 153 | registry = display.get_registry() 154 | registry.dispatcher["global"] = registry_handle_global 155 | 156 | display.dispatch(block=True) 157 | display.roundtrip() 158 | 159 | if STATUS_MANAGER is None: 160 | print("Failed to bind river status manager") 161 | sys.exit() 162 | 163 | if CONTROL is None: 164 | print("Failed to bind river control") 165 | sys.exit() 166 | 167 | # Configuring all outputs, even the ones we do not care about, 168 | # should be faster than first waiting for river to advertise the 169 | # focused output of the SEAT. 170 | for output in OUTPUTS: 171 | output.configure() 172 | 173 | SEAT.configure() 174 | 175 | display.dispatch(block=True) 176 | display.roundtrip() 177 | 178 | 179 | def close_display(display: Display) -> None: 180 | '''Clean up objects''' 181 | SEAT.destroy() 182 | for output in OUTPUTS: 183 | output.destroy() 184 | 185 | if STATUS_MANAGER is not None: 186 | STATUS_MANAGER.destroy() 187 | 188 | if CONTROL is not None: 189 | CONTROL.destroy() 190 | 191 | display.disconnect() 192 | 193 | 194 | def check_n_tags(n_tags: int) -> int: 195 | '''Check max tag number argument''' 196 | error_string = f'Invalid max number of tags: {n_tags}' 197 | try: 198 | i_n_tags = int(n_tags) 199 | except Exception as exc: 200 | raise argparse.ArgumentTypeError(error_string) from exc 201 | 202 | if i_n_tags < 1 or 32 < i_n_tags: 203 | raise argparse.ArgumentTypeError(error_string) 204 | 205 | return i_n_tags 206 | 207 | 208 | def parse_command_line() -> argparse.Namespace: 209 | '''Read commandline arguments''' 210 | parser = argparse.ArgumentParser( 211 | description='Change to either the next or previous tags.', 212 | formatter_class=argparse.ArgumentDefaultsHelpFormatter 213 | ) 214 | parser.add_argument( 215 | 'n_cycle', default=1, nargs='?', type=int, 216 | help=('Number of tags to cycle through. Signed integer.') 217 | ) 218 | parser.add_argument( 219 | 'n_tags', default=32, nargs='?', type=check_n_tags, 220 | help=('The tag number the cycling should loop back to the first tag ' 221 | 'or to the last tag from the first tag. Integer between 1 and ' 222 | '32 inclusive.') 223 | ) 224 | parser.add_argument( 225 | '--all-outputs', '-a', dest='all_outputs', action='store_true', 226 | help='Cycle the tags for all outputs (following the active output).' 227 | ) 228 | parser.add_argument( 229 | '--follow', '-f', dest='follow', action='store_true', 230 | help='Move the active window when cycling.' 231 | ) 232 | parser.add_argument( 233 | '--skip-occupied', '-o', action='store_true', 234 | help='Skip occupied tags.' 235 | ) 236 | parser.add_argument( 237 | '--skip-empty', '-s', action='store_true', 238 | help='Skip empty tags.' 239 | ) 240 | parser.add_argument( 241 | '--debug', '-d', action='store_true', 242 | help='Enable debugging output.' 243 | ) 244 | return parser.parse_args() 245 | 246 | 247 | def get_occupied_tags(cli_args: argparse.Namespace) -> int: 248 | '''Return bitmap of occupied tags as int''' 249 | used_tags = (1 << cli_args.n_tags) - 1 250 | 251 | if not cli_args.all_outputs or len(OUTPUTS) == 1: 252 | return get_occupied_from_view_tags( 253 | SEAT.focused_output.view_tags) & used_tags 254 | 255 | occupied_tags = 0 256 | for output in OUTPUTS: 257 | occupied_tags |= get_occupied_from_view_tags(output.view_tags) 258 | 259 | return occupied_tags & used_tags 260 | 261 | 262 | def get_occupied_from_view_tags(view_tags: int) -> int: 263 | '''Return bitmap of view_tags occupied tags as int''' 264 | occupied_tags = 0 265 | nviews = int(len(view_tags) / 4) 266 | for view in struct.unpack(f'{nviews}I', view_tags): 267 | occupied_tags |= view 268 | 269 | return occupied_tags 270 | 271 | 272 | def get_new_tags(cli_args: argparse.Namespace, 273 | occupied_tags: int) -> int: 274 | '''Return the new tag set''' 275 | used_tags = (1 << cli_args.n_tags) - 1 276 | tags = SEAT.focused_output.focused_tags & used_tags 277 | 278 | if (cli_args.n_cycle == 0 # noqa: W504 279 | or cli_args.skip_empty and occupied_tags == 0 280 | # All tags empty & we want to skip empty tags 281 | or cli_args.skip_occupied and used_tags == (used_tags ^ occupied_tags) 282 | # All tags occupied & we want to skip occupied tags 283 | ): 284 | return tags 285 | 286 | i = 0 287 | initial_tags = tags 288 | last_tag = 1 << (cli_args.n_tags - 1) 289 | for _ in range(cli_args.n_tags): 290 | new_tags = 0 291 | if cli_args.n_cycle > 0: 292 | # If last tag is set => unset it and set first bit on new_tags 293 | if (tags & last_tag) != 0: 294 | tags ^= last_tag 295 | new_tags = 1 296 | 297 | new_tags |= (tags << 1) 298 | 299 | else: 300 | # If lowest bit is set (first tag) => unset it and set 301 | # last_tag bit on new tags 302 | if (tags & 1) != 0: 303 | tags ^= 1 304 | new_tags = last_tag 305 | 306 | new_tags |= (tags >> 1) 307 | 308 | tags = new_tags 309 | 310 | if cli_args.skip_empty and not bool(tags & occupied_tags): 311 | continue 312 | 313 | if cli_args.skip_occupied and bool(tags & occupied_tags): 314 | continue 315 | 316 | i += 1 317 | 318 | if i == abs(cli_args.n_cycle) % cli_args.n_tags: 319 | return tags 320 | 321 | # Looped over all tags without returning, either skip options caused 322 | # none of the potential tags to be viable or something went wrong. 323 | if cli_args.skip_empty: 324 | print('Cycle failed: all tags empty') 325 | elif cli_args.skip_occupied: 326 | print('Cycle failed: all tags occupied') 327 | else: 328 | # Something is wrong, bail out. 329 | print('Cycle failed: looped over all tags') 330 | 331 | return initial_tags 332 | 333 | 334 | 335 | def set_new_tags(cli_args: argparse.Namespace, new_tags: int) -> None: 336 | '''Set the focused tags''' 337 | if cli_args.follow: 338 | CONTROL.add_argument("set-view-tags") 339 | CONTROL.add_argument(str(new_tags)) 340 | CONTROL.run_command(SEAT.wl_seat) 341 | 342 | CONTROL.add_argument("set-focused-tags") 343 | CONTROL.add_argument(str(new_tags)) 344 | CONTROL.run_command(SEAT.wl_seat) 345 | 346 | if len(OUTPUTS) == 1 or not cli_args.all_outputs: 347 | return 348 | 349 | # The active output has been switched, walk over all other outputs and 350 | # set their tags too, wrapping back to the start (where setting can be 351 | # skipped). 352 | for i in range(len(OUTPUTS)): 353 | CONTROL.add_argument("focus-output") 354 | CONTROL.add_argument("next") 355 | CONTROL.run_command(SEAT.wl_seat) 356 | 357 | if i + 1 == len(OUTPUTS): 358 | # Back to the start which has already had it's tags set. 359 | # Breaking here isn't needed but the next assignment is 360 | # redundant. 361 | break 362 | 363 | CONTROL.add_argument("set-focused-tags") 364 | CONTROL.add_argument(str(new_tags)) 365 | CONTROL.run_command(SEAT.wl_seat) 366 | 367 | return 368 | 369 | 370 | def cycle_focused_tags() -> None: 371 | '''Shift to next or previous tags''' 372 | args = parse_command_line() 373 | display = Display() 374 | prepare_display(display) 375 | 376 | occupied_tags = get_occupied_tags(args) 377 | new_tags = get_new_tags(args, occupied_tags) 378 | 379 | if args.debug: 380 | print(f'cur 0b{SEAT.focused_output.focused_tags:032b}') 381 | print(f'occ 0b{occupied_tags:032b}') 382 | print(f'new 0b{new_tags:032b}') 383 | 384 | set_new_tags(args, new_tags) 385 | 386 | display.dispatch(block=True) 387 | display.roundtrip() 388 | 389 | close_display(display) 390 | -------------------------------------------------------------------------------- /riverwm_utils/wayland.xml: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | Copyright © 2008-2011 Kristian Høgsberg 6 | Copyright © 2010-2011 Intel Corporation 7 | Copyright © 2012-2013 Collabora, Ltd. 8 | 9 | Permission is hereby granted, free of charge, to any person 10 | obtaining a copy of this software and associated documentation files 11 | (the "Software"), to deal in the Software without restriction, 12 | including without limitation the rights to use, copy, modify, merge, 13 | publish, distribute, sublicense, and/or sell copies of the Software, 14 | and to permit persons to whom the Software is furnished to do so, 15 | subject to the following conditions: 16 | 17 | The above copyright notice and this permission notice (including the 18 | next paragraph) shall be included in all copies or substantial 19 | portions of the Software. 20 | 21 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, 22 | EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF 23 | MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND 24 | NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS 25 | BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN 26 | ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN 27 | CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 28 | SOFTWARE. 29 | 30 | 31 | 32 | 33 | The core global object. This is a special singleton object. It 34 | is used for internal Wayland protocol features. 35 | 36 | 37 | 38 | 39 | The sync request asks the server to emit the 'done' event 40 | on the returned wl_callback object. Since requests are 41 | handled in-order and events are delivered in-order, this can 42 | be used as a barrier to ensure all previous requests and the 43 | resulting events have been handled. 44 | 45 | The object returned by this request will be destroyed by the 46 | compositor after the callback is fired and as such the client must not 47 | attempt to use it after that point. 48 | 49 | The callback_data passed in the callback is the event serial. 50 | 51 | 53 | 54 | 55 | 56 | 57 | This request creates a registry object that allows the client 58 | to list and bind the global objects available from the 59 | compositor. 60 | 61 | It should be noted that the server side resources consumed in 62 | response to a get_registry request can only be released when the 63 | client disconnects, not when the client side proxy is destroyed. 64 | Therefore, clients should invoke get_registry as infrequently as 65 | possible to avoid wasting memory. 66 | 67 | 69 | 70 | 71 | 72 | 73 | The error event is sent out when a fatal (non-recoverable) 74 | error has occurred. The object_id argument is the object 75 | where the error occurred, most often in response to a request 76 | to that object. The code identifies the error and is defined 77 | by the object interface. As such, each interface defines its 78 | own set of error codes. The message is a brief description 79 | of the error, for (debugging) convenience. 80 | 81 | 82 | 83 | 84 | 85 | 86 | 87 | 88 | These errors are global and can be emitted in response to any 89 | server request. 90 | 91 | 93 | 95 | 97 | 99 | 100 | 101 | 102 | 103 | This event is used internally by the object ID management 104 | logic. When a client deletes an object that it had created, 105 | the server will send this event to acknowledge that it has 106 | seen the delete request. When the client receives this event, 107 | it will know that it can safely reuse the object ID. 108 | 109 | 110 | 111 | 112 | 113 | 114 | 115 | The singleton global registry object. The server has a number of 116 | global objects that are available to all clients. These objects 117 | typically represent an actual object in the server (for example, 118 | an input device) or they are singleton objects that provide 119 | extension functionality. 120 | 121 | When a client creates a registry object, the registry object 122 | will emit a global event for each global currently in the 123 | registry. Globals come and go as a result of device or 124 | monitor hotplugs, reconfiguration or other events, and the 125 | registry will send out global and global_remove events to 126 | keep the client up to date with the changes. To mark the end 127 | of the initial burst of events, the client can use the 128 | wl_display.sync request immediately after calling 129 | wl_display.get_registry. 130 | 131 | A client can bind to a global object by using the bind 132 | request. This creates a client-side handle that lets the object 133 | emit events to the client and lets the client invoke requests on 134 | the object. 135 | 136 | 137 | 138 | 139 | Binds a new, client-created object to the server using the 140 | specified name as the identifier. 141 | 142 | 143 | 144 | 145 | 146 | 147 | 148 | Notify the client of global objects. 149 | 150 | The event notifies the client that a global object with 151 | the given name is now available, and it implements the 152 | given version of the given interface. 153 | 154 | 155 | 156 | 157 | 158 | 159 | 160 | 161 | Notify the client of removed global objects. 162 | 163 | This event notifies the client that the global identified 164 | by name is no longer available. If the client bound to 165 | the global using the bind request, the client should now 166 | destroy that object. 167 | 168 | The object remains valid and requests to the object will be 169 | ignored until the client destroys it, to avoid races between 170 | the global going away and a client sending a request to it. 171 | 172 | 173 | 174 | 175 | 176 | 177 | 178 | Clients can handle the 'done' event to get notified when 179 | the related request is done. 180 | 181 | 182 | 183 | 184 | Notify the client when the related request is done. 185 | 186 | 187 | 188 | 189 | 190 | 191 | 192 | A compositor. This object is a singleton global. The 193 | compositor is in charge of combining the contents of multiple 194 | surfaces into one displayable output. 195 | 196 | 197 | 198 | 199 | Ask the compositor to create a new surface. 200 | 201 | 202 | 203 | 204 | 205 | 206 | Ask the compositor to create a new region. 207 | 208 | 209 | 210 | 211 | 212 | 213 | 214 | The wl_shm_pool object encapsulates a piece of memory shared 215 | between the compositor and client. Through the wl_shm_pool 216 | object, the client can allocate shared memory wl_buffer objects. 217 | All objects created through the same pool share the same 218 | underlying mapped memory. Reusing the mapped memory avoids the 219 | setup/teardown overhead and is useful when interactively resizing 220 | a surface or for many small buffers. 221 | 222 | 223 | 224 | 225 | Create a wl_buffer object from the pool. 226 | 227 | The buffer is created offset bytes into the pool and has 228 | width and height as specified. The stride argument specifies 229 | the number of bytes from the beginning of one row to the beginning 230 | of the next. The format is the pixel format of the buffer and 231 | must be one of those advertised through the wl_shm.format event. 232 | 233 | A buffer will keep a reference to the pool it was created from 234 | so it is valid to destroy the pool immediately after creating 235 | a buffer from it. 236 | 237 | 238 | 239 | 240 | 241 | 242 | 243 | 244 | 245 | 246 | 247 | Destroy the shared memory pool. 248 | 249 | The mmapped memory will be released when all 250 | buffers that have been created from this pool 251 | are gone. 252 | 253 | 254 | 255 | 256 | 257 | This request will cause the server to remap the backing memory 258 | for the pool from the file descriptor passed when the pool was 259 | created, but using the new size. This request can only be 260 | used to make the pool bigger. 261 | 262 | This request only changes the amount of bytes that are mmapped 263 | by the server and does not touch the file corresponding to the 264 | file descriptor passed at creation time. It is the client's 265 | responsibility to ensure that the file is at least as big as 266 | the new pool size. 267 | 268 | 269 | 270 | 271 | 272 | 273 | 274 | A singleton global object that provides support for shared 275 | memory. 276 | 277 | Clients can create wl_shm_pool objects using the create_pool 278 | request. 279 | 280 | On binding the wl_shm object one or more format events 281 | are emitted to inform clients about the valid pixel formats 282 | that can be used for buffers. 283 | 284 | 285 | 286 | 287 | These errors can be emitted in response to wl_shm requests. 288 | 289 | 290 | 291 | 292 | 293 | 294 | 295 | 296 | This describes the memory layout of an individual pixel. 297 | 298 | All renderers should support argb8888 and xrgb8888 but any other 299 | formats are optional and may not be supported by the particular 300 | renderer in use. 301 | 302 | The drm format codes match the macros defined in drm_fourcc.h, except 303 | argb8888 and xrgb8888. The formats actually supported by the compositor 304 | will be reported by the format event. 305 | 306 | For all wl_shm formats and unless specified in another protocol 307 | extension, pre-multiplied alpha is used for pixel values. 308 | 309 | 311 | 312 | 313 | 314 | 315 | 316 | 317 | 318 | 319 | 320 | 321 | 322 | 323 | 324 | 325 | 326 | 327 | 328 | 329 | 330 | 331 | 332 | 333 | 334 | 335 | 336 | 337 | 338 | 339 | 340 | 341 | 342 | 343 | 344 | 345 | 346 | 347 | 348 | 349 | 350 | 351 | 352 | 353 | 354 | 355 | 356 | 357 | 358 | 359 | 360 | 361 | 362 | 363 | 364 | 365 | 366 | 367 | 368 | 369 | 370 | 371 | 372 | 373 | 374 | 375 | 376 | 377 | 378 | 379 | 380 | 381 | 382 | 383 | 384 | 385 | 386 | 387 | 388 | 389 | 390 | 391 | 392 | 393 | 394 | 395 | 396 | 397 | 398 | 399 | 400 | 401 | 402 | 403 | 404 | 405 | 406 | 407 | 408 | 409 | 410 | 411 | 412 | 413 | 414 | 415 | 416 | 417 | 418 | 419 | 420 | 421 | 422 | 423 | Create a new wl_shm_pool object. 424 | 425 | The pool can be used to create shared memory based buffer 426 | objects. The server will mmap size bytes of the passed file 427 | descriptor, to use as backing memory for the pool. 428 | 429 | 430 | 431 | 432 | 433 | 434 | 435 | 436 | Informs the client about a valid pixel format that 437 | can be used for buffers. Known formats include 438 | argb8888 and xrgb8888. 439 | 440 | 441 | 442 | 443 | 444 | 445 | 446 | A buffer provides the content for a wl_surface. Buffers are 447 | created through factory interfaces such as wl_shm, wp_linux_buffer_params 448 | (from the linux-dmabuf protocol extension) or similar. It has a width and 449 | a height and can be attached to a wl_surface, but the mechanism by which a 450 | client provides and updates the contents is defined by the buffer factory 451 | interface. 452 | 453 | If the buffer uses a format that has an alpha channel, the alpha channel 454 | is assumed to be premultiplied in the color channels unless otherwise 455 | specified. 456 | 457 | 458 | 459 | 460 | Destroy a buffer. If and how you need to release the backing 461 | storage is defined by the buffer factory interface. 462 | 463 | For possible side-effects to a surface, see wl_surface.attach. 464 | 465 | 466 | 467 | 468 | 469 | Sent when this wl_buffer is no longer used by the compositor. 470 | The client is now free to reuse or destroy this buffer and its 471 | backing storage. 472 | 473 | If a client receives a release event before the frame callback 474 | requested in the same wl_surface.commit that attaches this 475 | wl_buffer to a surface, then the client is immediately free to 476 | reuse the buffer and its backing storage, and does not need a 477 | second buffer for the next surface content update. Typically 478 | this is possible, when the compositor maintains a copy of the 479 | wl_surface contents, e.g. as a GL texture. This is an important 480 | optimization for GL(ES) compositors with wl_shm clients. 481 | 482 | 483 | 484 | 485 | 486 | 487 | A wl_data_offer represents a piece of data offered for transfer 488 | by another client (the source client). It is used by the 489 | copy-and-paste and drag-and-drop mechanisms. The offer 490 | describes the different mime types that the data can be 491 | converted to and provides the mechanism for transferring the 492 | data directly from the source client. 493 | 494 | 495 | 496 | 498 | 500 | 502 | 504 | 505 | 506 | 507 | 508 | Indicate that the client can accept the given mime type, or 509 | NULL for not accepted. 510 | 511 | For objects of version 2 or older, this request is used by the 512 | client to give feedback whether the client can receive the given 513 | mime type, or NULL if none is accepted; the feedback does not 514 | determine whether the drag-and-drop operation succeeds or not. 515 | 516 | For objects of version 3 or newer, this request determines the 517 | final result of the drag-and-drop operation. If the end result 518 | is that no mime types were accepted, the drag-and-drop operation 519 | will be cancelled and the corresponding drag source will receive 520 | wl_data_source.cancelled. Clients may still use this event in 521 | conjunction with wl_data_source.action for feedback. 522 | 523 | 524 | 525 | 526 | 527 | 528 | 529 | To transfer the offered data, the client issues this request 530 | and indicates the mime type it wants to receive. The transfer 531 | happens through the passed file descriptor (typically created 532 | with the pipe system call). The source client writes the data 533 | in the mime type representation requested and then closes the 534 | file descriptor. 535 | 536 | The receiving client reads from the read end of the pipe until 537 | EOF and then closes its end, at which point the transfer is 538 | complete. 539 | 540 | This request may happen multiple times for different mime types, 541 | both before and after wl_data_device.drop. Drag-and-drop destination 542 | clients may preemptively fetch data or examine it more closely to 543 | determine acceptance. 544 | 545 | 546 | 547 | 548 | 549 | 550 | 551 | Destroy the data offer. 552 | 553 | 554 | 555 | 556 | 557 | Sent immediately after creating the wl_data_offer object. One 558 | event per offered mime type. 559 | 560 | 561 | 562 | 563 | 564 | 565 | 566 | 567 | Notifies the compositor that the drag destination successfully 568 | finished the drag-and-drop operation. 569 | 570 | Upon receiving this request, the compositor will emit 571 | wl_data_source.dnd_finished on the drag source client. 572 | 573 | It is a client error to perform other requests than 574 | wl_data_offer.destroy after this one. It is also an error to perform 575 | this request after a NULL mime type has been set in 576 | wl_data_offer.accept or no action was received through 577 | wl_data_offer.action. 578 | 579 | If wl_data_offer.finish request is received for a non drag and drop 580 | operation, the invalid_finish protocol error is raised. 581 | 582 | 583 | 584 | 585 | 586 | Sets the actions that the destination side client supports for 587 | this operation. This request may trigger the emission of 588 | wl_data_source.action and wl_data_offer.action events if the compositor 589 | needs to change the selected action. 590 | 591 | This request can be called multiple times throughout the 592 | drag-and-drop operation, typically in response to wl_data_device.enter 593 | or wl_data_device.motion events. 594 | 595 | This request determines the final result of the drag-and-drop 596 | operation. If the end result is that no action is accepted, 597 | the drag source will receive wl_data_source.cancelled. 598 | 599 | The dnd_actions argument must contain only values expressed in the 600 | wl_data_device_manager.dnd_actions enum, and the preferred_action 601 | argument must only contain one of those values set, otherwise it 602 | will result in a protocol error. 603 | 604 | While managing an "ask" action, the destination drag-and-drop client 605 | may perform further wl_data_offer.receive requests, and is expected 606 | to perform one last wl_data_offer.set_actions request with a preferred 607 | action other than "ask" (and optionally wl_data_offer.accept) before 608 | requesting wl_data_offer.finish, in order to convey the action selected 609 | by the user. If the preferred action is not in the 610 | wl_data_offer.source_actions mask, an error will be raised. 611 | 612 | If the "ask" action is dismissed (e.g. user cancellation), the client 613 | is expected to perform wl_data_offer.destroy right away. 614 | 615 | This request can only be made on drag-and-drop offers, a protocol error 616 | will be raised otherwise. 617 | 618 | 620 | 622 | 623 | 624 | 625 | 626 | This event indicates the actions offered by the data source. It 627 | will be sent right after wl_data_device.enter, or anytime the source 628 | side changes its offered actions through wl_data_source.set_actions. 629 | 630 | 632 | 633 | 634 | 635 | 636 | This event indicates the action selected by the compositor after 637 | matching the source/destination side actions. Only one action (or 638 | none) will be offered here. 639 | 640 | This event can be emitted multiple times during the drag-and-drop 641 | operation in response to destination side action changes through 642 | wl_data_offer.set_actions. 643 | 644 | This event will no longer be emitted after wl_data_device.drop 645 | happened on the drag-and-drop destination, the client must 646 | honor the last action received, or the last preferred one set 647 | through wl_data_offer.set_actions when handling an "ask" action. 648 | 649 | Compositors may also change the selected action on the fly, mainly 650 | in response to keyboard modifier changes during the drag-and-drop 651 | operation. 652 | 653 | The most recent action received is always the valid one. Prior to 654 | receiving wl_data_device.drop, the chosen action may change (e.g. 655 | due to keyboard modifiers being pressed). At the time of receiving 656 | wl_data_device.drop the drag-and-drop destination must honor the 657 | last action received. 658 | 659 | Action changes may still happen after wl_data_device.drop, 660 | especially on "ask" actions, where the drag-and-drop destination 661 | may choose another action afterwards. Action changes happening 662 | at this stage are always the result of inter-client negotiation, the 663 | compositor shall no longer be able to induce a different action. 664 | 665 | Upon "ask" actions, it is expected that the drag-and-drop destination 666 | may potentially choose a different action and/or mime type, 667 | based on wl_data_offer.source_actions and finally chosen by the 668 | user (e.g. popping up a menu with the available options). The 669 | final wl_data_offer.set_actions and wl_data_offer.accept requests 670 | must happen before the call to wl_data_offer.finish. 671 | 672 | 674 | 675 | 676 | 677 | 678 | 679 | The wl_data_source object is the source side of a wl_data_offer. 680 | It is created by the source client in a data transfer and 681 | provides a way to describe the offered data and a way to respond 682 | to requests to transfer the data. 683 | 684 | 685 | 686 | 688 | 690 | 691 | 692 | 693 | 694 | This request adds a mime type to the set of mime types 695 | advertised to targets. Can be called several times to offer 696 | multiple types. 697 | 698 | 699 | 700 | 701 | 702 | 703 | Destroy the data source. 704 | 705 | 706 | 707 | 708 | 709 | Sent when a target accepts pointer_focus or motion events. If 710 | a target does not accept any of the offered types, type is NULL. 711 | 712 | Used for feedback during drag-and-drop. 713 | 714 | 715 | 716 | 717 | 718 | 719 | Request for data from the client. Send the data as the 720 | specified mime type over the passed file descriptor, then 721 | close it. 722 | 723 | 724 | 725 | 726 | 727 | 728 | 729 | This data source is no longer valid. There are several reasons why 730 | this could happen: 731 | 732 | - The data source has been replaced by another data source. 733 | - The drag-and-drop operation was performed, but the drop destination 734 | did not accept any of the mime types offered through 735 | wl_data_source.target. 736 | - The drag-and-drop operation was performed, but the drop destination 737 | did not select any of the actions present in the mask offered through 738 | wl_data_source.action. 739 | - The drag-and-drop operation was performed but didn't happen over a 740 | surface. 741 | - The compositor cancelled the drag-and-drop operation (e.g. compositor 742 | dependent timeouts to avoid stale drag-and-drop transfers). 743 | 744 | The client should clean up and destroy this data source. 745 | 746 | For objects of version 2 or older, wl_data_source.cancelled will 747 | only be emitted if the data source was replaced by another data 748 | source. 749 | 750 | 751 | 752 | 753 | 754 | 755 | 756 | Sets the actions that the source side client supports for this 757 | operation. This request may trigger wl_data_source.action and 758 | wl_data_offer.action events if the compositor needs to change the 759 | selected action. 760 | 761 | The dnd_actions argument must contain only values expressed in the 762 | wl_data_device_manager.dnd_actions enum, otherwise it will result 763 | in a protocol error. 764 | 765 | This request must be made once only, and can only be made on sources 766 | used in drag-and-drop, so it must be performed before 767 | wl_data_device.start_drag. Attempting to use the source other than 768 | for drag-and-drop will raise a protocol error. 769 | 770 | 772 | 773 | 774 | 775 | 776 | The user performed the drop action. This event does not indicate 777 | acceptance, wl_data_source.cancelled may still be emitted afterwards 778 | if the drop destination does not accept any mime type. 779 | 780 | However, this event might however not be received if the compositor 781 | cancelled the drag-and-drop operation before this event could happen. 782 | 783 | Note that the data_source may still be used in the future and should 784 | not be destroyed here. 785 | 786 | 787 | 788 | 789 | 790 | The drop destination finished interoperating with this data 791 | source, so the client is now free to destroy this data source and 792 | free all associated data. 793 | 794 | If the action used to perform the operation was "move", the 795 | source can now delete the transferred data. 796 | 797 | 798 | 799 | 800 | 801 | This event indicates the action selected by the compositor after 802 | matching the source/destination side actions. Only one action (or 803 | none) will be offered here. 804 | 805 | This event can be emitted multiple times during the drag-and-drop 806 | operation, mainly in response to destination side changes through 807 | wl_data_offer.set_actions, and as the data device enters/leaves 808 | surfaces. 809 | 810 | It is only possible to receive this event after 811 | wl_data_source.dnd_drop_performed if the drag-and-drop operation 812 | ended in an "ask" action, in which case the final wl_data_source.action 813 | event will happen immediately before wl_data_source.dnd_finished. 814 | 815 | Compositors may also change the selected action on the fly, mainly 816 | in response to keyboard modifier changes during the drag-and-drop 817 | operation. 818 | 819 | The most recent action received is always the valid one. The chosen 820 | action may change alongside negotiation (e.g. an "ask" action can turn 821 | into a "move" operation), so the effects of the final action must 822 | always be applied in wl_data_offer.dnd_finished. 823 | 824 | Clients can trigger cursor surface changes from this point, so 825 | they reflect the current action. 826 | 827 | 829 | 830 | 831 | 832 | 833 | 834 | There is one wl_data_device per seat which can be obtained 835 | from the global wl_data_device_manager singleton. 836 | 837 | A wl_data_device provides access to inter-client data transfer 838 | mechanisms such as copy-and-paste and drag-and-drop. 839 | 840 | 841 | 842 | 843 | 844 | 845 | 846 | 847 | This request asks the compositor to start a drag-and-drop 848 | operation on behalf of the client. 849 | 850 | The source argument is the data source that provides the data 851 | for the eventual data transfer. If source is NULL, enter, leave 852 | and motion events are sent only to the client that initiated the 853 | drag and the client is expected to handle the data passing 854 | internally. If source is destroyed, the drag-and-drop session will be 855 | cancelled. 856 | 857 | The origin surface is the surface where the drag originates and 858 | the client must have an active implicit grab that matches the 859 | serial. 860 | 861 | The icon surface is an optional (can be NULL) surface that 862 | provides an icon to be moved around with the cursor. Initially, 863 | the top-left corner of the icon surface is placed at the cursor 864 | hotspot, but subsequent wl_surface.attach request can move the 865 | relative position. Attach requests must be confirmed with 866 | wl_surface.commit as usual. The icon surface is given the role of 867 | a drag-and-drop icon. If the icon surface already has another role, 868 | it raises a protocol error. 869 | 870 | The current and pending input regions of the icon wl_surface are 871 | cleared, and wl_surface.set_input_region is ignored until the 872 | wl_surface is no longer used as the icon surface. When the use 873 | as an icon ends, the current and pending input regions become 874 | undefined, and the wl_surface is unmapped. 875 | 876 | 877 | 878 | 879 | 880 | 881 | 882 | 883 | 884 | This request asks the compositor to set the selection 885 | to the data from the source on behalf of the client. 886 | 887 | To unset the selection, set the source to NULL. 888 | 889 | 890 | 891 | 892 | 893 | 894 | 895 | The data_offer event introduces a new wl_data_offer object, 896 | which will subsequently be used in either the 897 | data_device.enter event (for drag-and-drop) or the 898 | data_device.selection event (for selections). Immediately 899 | following the data_device.data_offer event, the new data_offer 900 | object will send out data_offer.offer events to describe the 901 | mime types it offers. 902 | 903 | 904 | 905 | 906 | 907 | 908 | This event is sent when an active drag-and-drop pointer enters 909 | a surface owned by the client. The position of the pointer at 910 | enter time is provided by the x and y arguments, in surface-local 911 | coordinates. 912 | 913 | 914 | 915 | 916 | 917 | 919 | 920 | 921 | 922 | 923 | This event is sent when the drag-and-drop pointer leaves the 924 | surface and the session ends. The client must destroy the 925 | wl_data_offer introduced at enter time at this point. 926 | 927 | 928 | 929 | 930 | 931 | This event is sent when the drag-and-drop pointer moves within 932 | the currently focused surface. The new position of the pointer 933 | is provided by the x and y arguments, in surface-local 934 | coordinates. 935 | 936 | 937 | 938 | 939 | 940 | 941 | 942 | 943 | The event is sent when a drag-and-drop operation is ended 944 | because the implicit grab is removed. 945 | 946 | The drag-and-drop destination is expected to honor the last action 947 | received through wl_data_offer.action, if the resulting action is 948 | "copy" or "move", the destination can still perform 949 | wl_data_offer.receive requests, and is expected to end all 950 | transfers with a wl_data_offer.finish request. 951 | 952 | If the resulting action is "ask", the action will not be considered 953 | final. The drag-and-drop destination is expected to perform one last 954 | wl_data_offer.set_actions request, or wl_data_offer.destroy in order 955 | to cancel the operation. 956 | 957 | 958 | 959 | 960 | 961 | The selection event is sent out to notify the client of a new 962 | wl_data_offer for the selection for this device. The 963 | data_device.data_offer and the data_offer.offer events are 964 | sent out immediately before this event to introduce the data 965 | offer object. The selection event is sent to a client 966 | immediately before receiving keyboard focus and when a new 967 | selection is set while the client has keyboard focus. The 968 | data_offer is valid until a new data_offer or NULL is received 969 | or until the client loses keyboard focus. Switching surface with 970 | keyboard focus within the same client doesn't mean a new selection 971 | will be sent. The client must destroy the previous selection 972 | data_offer, if any, upon receiving this event. 973 | 974 | 976 | 977 | 978 | 979 | 980 | 981 | 982 | This request destroys the data device. 983 | 984 | 985 | 986 | 987 | 988 | 989 | The wl_data_device_manager is a singleton global object that 990 | provides access to inter-client data transfer mechanisms such as 991 | copy-and-paste and drag-and-drop. These mechanisms are tied to 992 | a wl_seat and this interface lets a client get a wl_data_device 993 | corresponding to a wl_seat. 994 | 995 | Depending on the version bound, the objects created from the bound 996 | wl_data_device_manager object will have different requirements for 997 | functioning properly. See wl_data_source.set_actions, 998 | wl_data_offer.accept and wl_data_offer.finish for details. 999 | 1000 | 1001 | 1002 | 1003 | Create a new data source. 1004 | 1005 | 1006 | 1007 | 1008 | 1009 | 1010 | Create a new data device for a given seat. 1011 | 1012 | 1013 | 1014 | 1015 | 1016 | 1017 | 1018 | 1019 | 1020 | This is a bitmask of the available/preferred actions in a 1021 | drag-and-drop operation. 1022 | 1023 | In the compositor, the selected action is a result of matching the 1024 | actions offered by the source and destination sides. "action" events 1025 | with a "none" action will be sent to both source and destination if 1026 | there is no match. All further checks will effectively happen on 1027 | (source actions ∩ destination actions). 1028 | 1029 | In addition, compositors may also pick different actions in 1030 | reaction to key modifiers being pressed. One common design that 1031 | is used in major toolkits (and the behavior recommended for 1032 | compositors) is: 1033 | 1034 | - If no modifiers are pressed, the first match (in bit order) 1035 | will be used. 1036 | - Pressing Shift selects "move", if enabled in the mask. 1037 | - Pressing Control selects "copy", if enabled in the mask. 1038 | 1039 | Behavior beyond that is considered implementation-dependent. 1040 | Compositors may for example bind other modifiers (like Alt/Meta) 1041 | or drags initiated with other buttons than BTN_LEFT to specific 1042 | actions (e.g. "ask"). 1043 | 1044 | 1045 | 1046 | 1047 | 1048 | 1049 | 1050 | 1051 | 1052 | 1053 | This interface is implemented by servers that provide 1054 | desktop-style user interfaces. 1055 | 1056 | It allows clients to associate a wl_shell_surface with 1057 | a basic surface. 1058 | 1059 | Note! This protocol is deprecated and not intended for production use. 1060 | For desktop-style user interfaces, use xdg_shell. Compositors and clients 1061 | should not implement this interface. 1062 | 1063 | 1064 | 1065 | 1066 | 1067 | 1068 | 1069 | 1070 | Create a shell surface for an existing surface. This gives 1071 | the wl_surface the role of a shell surface. If the wl_surface 1072 | already has another role, it raises a protocol error. 1073 | 1074 | Only one shell surface can be associated with a given surface. 1075 | 1076 | 1077 | 1078 | 1079 | 1080 | 1081 | 1082 | 1083 | An interface that may be implemented by a wl_surface, for 1084 | implementations that provide a desktop-style user interface. 1085 | 1086 | It provides requests to treat surfaces like toplevel, fullscreen 1087 | or popup windows, move, resize or maximize them, associate 1088 | metadata like title and class, etc. 1089 | 1090 | On the server side the object is automatically destroyed when 1091 | the related wl_surface is destroyed. On the client side, 1092 | wl_shell_surface_destroy() must be called before destroying 1093 | the wl_surface object. 1094 | 1095 | 1096 | 1097 | 1098 | A client must respond to a ping event with a pong request or 1099 | the client may be deemed unresponsive. 1100 | 1101 | 1102 | 1103 | 1104 | 1105 | 1106 | Start a pointer-driven move of the surface. 1107 | 1108 | This request must be used in response to a button press event. 1109 | The server may ignore move requests depending on the state of 1110 | the surface (e.g. fullscreen or maximized). 1111 | 1112 | 1113 | 1114 | 1115 | 1116 | 1117 | 1118 | These values are used to indicate which edge of a surface 1119 | is being dragged in a resize operation. The server may 1120 | use this information to adapt its behavior, e.g. choose 1121 | an appropriate cursor image. 1122 | 1123 | 1124 | 1125 | 1126 | 1127 | 1128 | 1129 | 1130 | 1131 | 1132 | 1133 | 1134 | 1135 | 1136 | Start a pointer-driven resizing of the surface. 1137 | 1138 | This request must be used in response to a button press event. 1139 | The server may ignore resize requests depending on the state of 1140 | the surface (e.g. fullscreen or maximized). 1141 | 1142 | 1143 | 1144 | 1145 | 1146 | 1147 | 1148 | 1149 | Map the surface as a toplevel surface. 1150 | 1151 | A toplevel surface is not fullscreen, maximized or transient. 1152 | 1153 | 1154 | 1155 | 1156 | 1157 | These flags specify details of the expected behaviour 1158 | of transient surfaces. Used in the set_transient request. 1159 | 1160 | 1161 | 1162 | 1163 | 1164 | 1165 | Map the surface relative to an existing surface. 1166 | 1167 | The x and y arguments specify the location of the upper left 1168 | corner of the surface relative to the upper left corner of the 1169 | parent surface, in surface-local coordinates. 1170 | 1171 | The flags argument controls details of the transient behaviour. 1172 | 1173 | 1174 | 1175 | 1176 | 1177 | 1178 | 1179 | 1180 | 1181 | Hints to indicate to the compositor how to deal with a conflict 1182 | between the dimensions of the surface and the dimensions of the 1183 | output. The compositor is free to ignore this parameter. 1184 | 1185 | 1186 | 1187 | 1188 | 1189 | 1190 | 1191 | 1192 | 1193 | Map the surface as a fullscreen surface. 1194 | 1195 | If an output parameter is given then the surface will be made 1196 | fullscreen on that output. If the client does not specify the 1197 | output then the compositor will apply its policy - usually 1198 | choosing the output on which the surface has the biggest surface 1199 | area. 1200 | 1201 | The client may specify a method to resolve a size conflict 1202 | between the output size and the surface size - this is provided 1203 | through the method parameter. 1204 | 1205 | The framerate parameter is used only when the method is set 1206 | to "driver", to indicate the preferred framerate. A value of 0 1207 | indicates that the client does not care about framerate. The 1208 | framerate is specified in mHz, that is framerate of 60000 is 60Hz. 1209 | 1210 | A method of "scale" or "driver" implies a scaling operation of 1211 | the surface, either via a direct scaling operation or a change of 1212 | the output mode. This will override any kind of output scaling, so 1213 | that mapping a surface with a buffer size equal to the mode can 1214 | fill the screen independent of buffer_scale. 1215 | 1216 | A method of "fill" means we don't scale up the buffer, however 1217 | any output scale is applied. This means that you may run into 1218 | an edge case where the application maps a buffer with the same 1219 | size of the output mode but buffer_scale 1 (thus making a 1220 | surface larger than the output). In this case it is allowed to 1221 | downscale the results to fit the screen. 1222 | 1223 | The compositor must reply to this request with a configure event 1224 | with the dimensions for the output on which the surface will 1225 | be made fullscreen. 1226 | 1227 | 1228 | 1229 | 1231 | 1232 | 1233 | 1234 | 1235 | Map the surface as a popup. 1236 | 1237 | A popup surface is a transient surface with an added pointer 1238 | grab. 1239 | 1240 | An existing implicit grab will be changed to owner-events mode, 1241 | and the popup grab will continue after the implicit grab ends 1242 | (i.e. releasing the mouse button does not cause the popup to 1243 | be unmapped). 1244 | 1245 | The popup grab continues until the window is destroyed or a 1246 | mouse button is pressed in any other client's window. A click 1247 | in any of the client's surfaces is reported as normal, however, 1248 | clicks in other clients' surfaces will be discarded and trigger 1249 | the callback. 1250 | 1251 | The x and y arguments specify the location of the upper left 1252 | corner of the surface relative to the upper left corner of the 1253 | parent surface, in surface-local coordinates. 1254 | 1255 | 1256 | 1257 | 1258 | 1259 | 1260 | 1261 | 1262 | 1263 | 1264 | 1265 | Map the surface as a maximized surface. 1266 | 1267 | If an output parameter is given then the surface will be 1268 | maximized on that output. If the client does not specify the 1269 | output then the compositor will apply its policy - usually 1270 | choosing the output on which the surface has the biggest surface 1271 | area. 1272 | 1273 | The compositor will reply with a configure event telling 1274 | the expected new surface size. The operation is completed 1275 | on the next buffer attach to this surface. 1276 | 1277 | A maximized surface typically fills the entire output it is 1278 | bound to, except for desktop elements such as panels. This is 1279 | the main difference between a maximized shell surface and a 1280 | fullscreen shell surface. 1281 | 1282 | The details depend on the compositor implementation. 1283 | 1284 | 1286 | 1287 | 1288 | 1289 | 1290 | Set a short title for the surface. 1291 | 1292 | This string may be used to identify the surface in a task bar, 1293 | window list, or other user interface elements provided by the 1294 | compositor. 1295 | 1296 | The string must be encoded in UTF-8. 1297 | 1298 | 1299 | 1300 | 1301 | 1302 | 1303 | Set a class for the surface. 1304 | 1305 | The surface class identifies the general class of applications 1306 | to which the surface belongs. A common convention is to use the 1307 | file name (or the full path if it is a non-standard location) of 1308 | the application's .desktop file as the class. 1309 | 1310 | 1311 | 1312 | 1313 | 1314 | 1315 | Ping a client to check if it is receiving events and sending 1316 | requests. A client is expected to reply with a pong request. 1317 | 1318 | 1319 | 1320 | 1321 | 1322 | 1323 | The configure event asks the client to resize its surface. 1324 | 1325 | The size is a hint, in the sense that the client is free to 1326 | ignore it if it doesn't resize, pick a smaller size (to 1327 | satisfy aspect ratio or resize in steps of NxM pixels). 1328 | 1329 | The edges parameter provides a hint about how the surface 1330 | was resized. The client may use this information to decide 1331 | how to adjust its content to the new size (e.g. a scrolling 1332 | area might adjust its content position to leave the viewable 1333 | content unmoved). 1334 | 1335 | The client is free to dismiss all but the last configure 1336 | event it received. 1337 | 1338 | The width and height arguments specify the size of the window 1339 | in surface-local coordinates. 1340 | 1341 | 1342 | 1343 | 1344 | 1345 | 1346 | 1347 | 1348 | The popup_done event is sent out when a popup grab is broken, 1349 | that is, when the user clicks a surface that doesn't belong 1350 | to the client owning the popup surface. 1351 | 1352 | 1353 | 1354 | 1355 | 1356 | 1357 | A surface is a rectangular area that may be displayed on zero 1358 | or more outputs, and shown any number of times at the compositor's 1359 | discretion. They can present wl_buffers, receive user input, and 1360 | define a local coordinate system. 1361 | 1362 | The size of a surface (and relative positions on it) is described 1363 | in surface-local coordinates, which may differ from the buffer 1364 | coordinates of the pixel content, in case a buffer_transform 1365 | or a buffer_scale is used. 1366 | 1367 | A surface without a "role" is fairly useless: a compositor does 1368 | not know where, when or how to present it. The role is the 1369 | purpose of a wl_surface. Examples of roles are a cursor for a 1370 | pointer (as set by wl_pointer.set_cursor), a drag icon 1371 | (wl_data_device.start_drag), a sub-surface 1372 | (wl_subcompositor.get_subsurface), and a window as defined by a 1373 | shell protocol (e.g. wl_shell.get_shell_surface). 1374 | 1375 | A surface can have only one role at a time. Initially a 1376 | wl_surface does not have a role. Once a wl_surface is given a 1377 | role, it is set permanently for the whole lifetime of the 1378 | wl_surface object. Giving the current role again is allowed, 1379 | unless explicitly forbidden by the relevant interface 1380 | specification. 1381 | 1382 | Surface roles are given by requests in other interfaces such as 1383 | wl_pointer.set_cursor. The request should explicitly mention 1384 | that this request gives a role to a wl_surface. Often, this 1385 | request also creates a new protocol object that represents the 1386 | role and adds additional functionality to wl_surface. When a 1387 | client wants to destroy a wl_surface, they must destroy this 'role 1388 | object' before the wl_surface. 1389 | 1390 | Destroying the role object does not remove the role from the 1391 | wl_surface, but it may stop the wl_surface from "playing the role". 1392 | For instance, if a wl_subsurface object is destroyed, the wl_surface 1393 | it was created for will be unmapped and forget its position and 1394 | z-order. It is allowed to create a wl_subsurface for the same 1395 | wl_surface again, but it is not allowed to use the wl_surface as 1396 | a cursor (cursor is a different role than sub-surface, and role 1397 | switching is not allowed). 1398 | 1399 | 1400 | 1401 | 1402 | These errors can be emitted in response to wl_surface requests. 1403 | 1404 | 1405 | 1406 | 1407 | 1408 | 1409 | 1410 | 1411 | 1412 | Deletes the surface and invalidates its object ID. 1413 | 1414 | 1415 | 1416 | 1417 | 1418 | Set a buffer as the content of this surface. 1419 | 1420 | The new size of the surface is calculated based on the buffer 1421 | size transformed by the inverse buffer_transform and the 1422 | inverse buffer_scale. This means that at commit time the supplied 1423 | buffer size must be an integer multiple of the buffer_scale. If 1424 | that's not the case, an invalid_size error is sent. 1425 | 1426 | The x and y arguments specify the location of the new pending 1427 | buffer's upper left corner, relative to the current buffer's upper 1428 | left corner, in surface-local coordinates. In other words, the 1429 | x and y, combined with the new surface size define in which 1430 | directions the surface's size changes. Setting anything other than 0 1431 | as x and y arguments is discouraged, and should instead be replaced 1432 | with using the separate wl_surface.offset request. 1433 | 1434 | When the bound wl_surface version is 5 or higher, passing any 1435 | non-zero x or y is a protocol violation, and will result in an 1436 | 'invalid_offset' error being raised. To achieve equivalent semantics, 1437 | use wl_surface.offset. 1438 | 1439 | Surface contents are double-buffered state, see wl_surface.commit. 1440 | 1441 | The initial surface contents are void; there is no content. 1442 | wl_surface.attach assigns the given wl_buffer as the pending 1443 | wl_buffer. wl_surface.commit makes the pending wl_buffer the new 1444 | surface contents, and the size of the surface becomes the size 1445 | calculated from the wl_buffer, as described above. After commit, 1446 | there is no pending buffer until the next attach. 1447 | 1448 | Committing a pending wl_buffer allows the compositor to read the 1449 | pixels in the wl_buffer. The compositor may access the pixels at 1450 | any time after the wl_surface.commit request. When the compositor 1451 | will not access the pixels anymore, it will send the 1452 | wl_buffer.release event. Only after receiving wl_buffer.release, 1453 | the client may reuse the wl_buffer. A wl_buffer that has been 1454 | attached and then replaced by another attach instead of committed 1455 | will not receive a release event, and is not used by the 1456 | compositor. 1457 | 1458 | If a pending wl_buffer has been committed to more than one wl_surface, 1459 | the delivery of wl_buffer.release events becomes undefined. A well 1460 | behaved client should not rely on wl_buffer.release events in this 1461 | case. Alternatively, a client could create multiple wl_buffer objects 1462 | from the same backing storage or use wp_linux_buffer_release. 1463 | 1464 | Destroying the wl_buffer after wl_buffer.release does not change 1465 | the surface contents. Destroying the wl_buffer before wl_buffer.release 1466 | is allowed as long as the underlying buffer storage isn't re-used (this 1467 | can happen e.g. on client process termination). However, if the client 1468 | destroys the wl_buffer before receiving the wl_buffer.release event and 1469 | mutates the underlying buffer storage, the surface contents become 1470 | undefined immediately. 1471 | 1472 | If wl_surface.attach is sent with a NULL wl_buffer, the 1473 | following wl_surface.commit will remove the surface content. 1474 | 1475 | 1477 | 1478 | 1479 | 1480 | 1481 | 1482 | 1483 | This request is used to describe the regions where the pending 1484 | buffer is different from the current surface contents, and where 1485 | the surface therefore needs to be repainted. The compositor 1486 | ignores the parts of the damage that fall outside of the surface. 1487 | 1488 | Damage is double-buffered state, see wl_surface.commit. 1489 | 1490 | The damage rectangle is specified in surface-local coordinates, 1491 | where x and y specify the upper left corner of the damage rectangle. 1492 | 1493 | The initial value for pending damage is empty: no damage. 1494 | wl_surface.damage adds pending damage: the new pending damage 1495 | is the union of old pending damage and the given rectangle. 1496 | 1497 | wl_surface.commit assigns pending damage as the current damage, 1498 | and clears pending damage. The server will clear the current 1499 | damage as it repaints the surface. 1500 | 1501 | Note! New clients should not use this request. Instead damage can be 1502 | posted with wl_surface.damage_buffer which uses buffer coordinates 1503 | instead of surface coordinates. 1504 | 1505 | 1506 | 1507 | 1508 | 1509 | 1510 | 1511 | 1512 | 1513 | Request a notification when it is a good time to start drawing a new 1514 | frame, by creating a frame callback. This is useful for throttling 1515 | redrawing operations, and driving animations. 1516 | 1517 | When a client is animating on a wl_surface, it can use the 'frame' 1518 | request to get notified when it is a good time to draw and commit the 1519 | next frame of animation. If the client commits an update earlier than 1520 | that, it is likely that some updates will not make it to the display, 1521 | and the client is wasting resources by drawing too often. 1522 | 1523 | The frame request will take effect on the next wl_surface.commit. 1524 | The notification will only be posted for one frame unless 1525 | requested again. For a wl_surface, the notifications are posted in 1526 | the order the frame requests were committed. 1527 | 1528 | The server must send the notifications so that a client 1529 | will not send excessive updates, while still allowing 1530 | the highest possible update rate for clients that wait for the reply 1531 | before drawing again. The server should give some time for the client 1532 | to draw and commit after sending the frame callback events to let it 1533 | hit the next output refresh. 1534 | 1535 | A server should avoid signaling the frame callbacks if the 1536 | surface is not visible in any way, e.g. the surface is off-screen, 1537 | or completely obscured by other opaque surfaces. 1538 | 1539 | The object returned by this request will be destroyed by the 1540 | compositor after the callback is fired and as such the client must not 1541 | attempt to use it after that point. 1542 | 1543 | The callback_data passed in the callback is the current time, in 1544 | milliseconds, with an undefined base. 1545 | 1546 | 1547 | 1548 | 1549 | 1550 | 1551 | This request sets the region of the surface that contains 1552 | opaque content. 1553 | 1554 | The opaque region is an optimization hint for the compositor 1555 | that lets it optimize the redrawing of content behind opaque 1556 | regions. Setting an opaque region is not required for correct 1557 | behaviour, but marking transparent content as opaque will result 1558 | in repaint artifacts. 1559 | 1560 | The opaque region is specified in surface-local coordinates. 1561 | 1562 | The compositor ignores the parts of the opaque region that fall 1563 | outside of the surface. 1564 | 1565 | Opaque region is double-buffered state, see wl_surface.commit. 1566 | 1567 | wl_surface.set_opaque_region changes the pending opaque region. 1568 | wl_surface.commit copies the pending region to the current region. 1569 | Otherwise, the pending and current regions are never changed. 1570 | 1571 | The initial value for an opaque region is empty. Setting the pending 1572 | opaque region has copy semantics, and the wl_region object can be 1573 | destroyed immediately. A NULL wl_region causes the pending opaque 1574 | region to be set to empty. 1575 | 1576 | 1578 | 1579 | 1580 | 1581 | 1582 | This request sets the region of the surface that can receive 1583 | pointer and touch events. 1584 | 1585 | Input events happening outside of this region will try the next 1586 | surface in the server surface stack. The compositor ignores the 1587 | parts of the input region that fall outside of the surface. 1588 | 1589 | The input region is specified in surface-local coordinates. 1590 | 1591 | Input region is double-buffered state, see wl_surface.commit. 1592 | 1593 | wl_surface.set_input_region changes the pending input region. 1594 | wl_surface.commit copies the pending region to the current region. 1595 | Otherwise the pending and current regions are never changed, 1596 | except cursor and icon surfaces are special cases, see 1597 | wl_pointer.set_cursor and wl_data_device.start_drag. 1598 | 1599 | The initial value for an input region is infinite. That means the 1600 | whole surface will accept input. Setting the pending input region 1601 | has copy semantics, and the wl_region object can be destroyed 1602 | immediately. A NULL wl_region causes the input region to be set 1603 | to infinite. 1604 | 1605 | 1607 | 1608 | 1609 | 1610 | 1611 | Surface state (input, opaque, and damage regions, attached buffers, 1612 | etc.) is double-buffered. Protocol requests modify the pending state, 1613 | as opposed to the current state in use by the compositor. A commit 1614 | request atomically applies all pending state, replacing the current 1615 | state. After commit, the new pending state is as documented for each 1616 | related request. 1617 | 1618 | On commit, a pending wl_buffer is applied first, and all other state 1619 | second. This means that all coordinates in double-buffered state are 1620 | relative to the new wl_buffer coming into use, except for 1621 | wl_surface.attach itself. If there is no pending wl_buffer, the 1622 | coordinates are relative to the current surface contents. 1623 | 1624 | All requests that need a commit to become effective are documented 1625 | to affect double-buffered state. 1626 | 1627 | Other interfaces may add further double-buffered surface state. 1628 | 1629 | 1630 | 1631 | 1632 | 1633 | This is emitted whenever a surface's creation, movement, or resizing 1634 | results in some part of it being within the scanout region of an 1635 | output. 1636 | 1637 | Note that a surface may be overlapping with zero or more outputs. 1638 | 1639 | 1640 | 1641 | 1642 | 1643 | 1644 | This is emitted whenever a surface's creation, movement, or resizing 1645 | results in it no longer having any part of it within the scanout region 1646 | of an output. 1647 | 1648 | Clients should not use the number of outputs the surface is on for frame 1649 | throttling purposes. The surface might be hidden even if no leave event 1650 | has been sent, and the compositor might expect new surface content 1651 | updates even if no enter event has been sent. The frame event should be 1652 | used instead. 1653 | 1654 | 1655 | 1656 | 1657 | 1658 | 1659 | 1660 | 1661 | This request sets an optional transformation on how the compositor 1662 | interprets the contents of the buffer attached to the surface. The 1663 | accepted values for the transform parameter are the values for 1664 | wl_output.transform. 1665 | 1666 | Buffer transform is double-buffered state, see wl_surface.commit. 1667 | 1668 | A newly created surface has its buffer transformation set to normal. 1669 | 1670 | wl_surface.set_buffer_transform changes the pending buffer 1671 | transformation. wl_surface.commit copies the pending buffer 1672 | transformation to the current one. Otherwise, the pending and current 1673 | values are never changed. 1674 | 1675 | The purpose of this request is to allow clients to render content 1676 | according to the output transform, thus permitting the compositor to 1677 | use certain optimizations even if the display is rotated. Using 1678 | hardware overlays and scanning out a client buffer for fullscreen 1679 | surfaces are examples of such optimizations. Those optimizations are 1680 | highly dependent on the compositor implementation, so the use of this 1681 | request should be considered on a case-by-case basis. 1682 | 1683 | Note that if the transform value includes 90 or 270 degree rotation, 1684 | the width of the buffer will become the surface height and the height 1685 | of the buffer will become the surface width. 1686 | 1687 | If transform is not one of the values from the 1688 | wl_output.transform enum the invalid_transform protocol error 1689 | is raised. 1690 | 1691 | 1693 | 1694 | 1695 | 1696 | 1697 | 1698 | 1699 | This request sets an optional scaling factor on how the compositor 1700 | interprets the contents of the buffer attached to the window. 1701 | 1702 | Buffer scale is double-buffered state, see wl_surface.commit. 1703 | 1704 | A newly created surface has its buffer scale set to 1. 1705 | 1706 | wl_surface.set_buffer_scale changes the pending buffer scale. 1707 | wl_surface.commit copies the pending buffer scale to the current one. 1708 | Otherwise, the pending and current values are never changed. 1709 | 1710 | The purpose of this request is to allow clients to supply higher 1711 | resolution buffer data for use on high resolution outputs. It is 1712 | intended that you pick the same buffer scale as the scale of the 1713 | output that the surface is displayed on. This means the compositor 1714 | can avoid scaling when rendering the surface on that output. 1715 | 1716 | Note that if the scale is larger than 1, then you have to attach 1717 | a buffer that is larger (by a factor of scale in each dimension) 1718 | than the desired surface size. 1719 | 1720 | If scale is not positive the invalid_scale protocol error is 1721 | raised. 1722 | 1723 | 1725 | 1726 | 1727 | 1728 | 1729 | 1730 | This request is used to describe the regions where the pending 1731 | buffer is different from the current surface contents, and where 1732 | the surface therefore needs to be repainted. The compositor 1733 | ignores the parts of the damage that fall outside of the surface. 1734 | 1735 | Damage is double-buffered state, see wl_surface.commit. 1736 | 1737 | The damage rectangle is specified in buffer coordinates, 1738 | where x and y specify the upper left corner of the damage rectangle. 1739 | 1740 | The initial value for pending damage is empty: no damage. 1741 | wl_surface.damage_buffer adds pending damage: the new pending 1742 | damage is the union of old pending damage and the given rectangle. 1743 | 1744 | wl_surface.commit assigns pending damage as the current damage, 1745 | and clears pending damage. The server will clear the current 1746 | damage as it repaints the surface. 1747 | 1748 | This request differs from wl_surface.damage in only one way - it 1749 | takes damage in buffer coordinates instead of surface-local 1750 | coordinates. While this generally is more intuitive than surface 1751 | coordinates, it is especially desirable when using wp_viewport 1752 | or when a drawing library (like EGL) is unaware of buffer scale 1753 | and buffer transform. 1754 | 1755 | Note: Because buffer transformation changes and damage requests may 1756 | be interleaved in the protocol stream, it is impossible to determine 1757 | the actual mapping between surface and buffer damage until 1758 | wl_surface.commit time. Therefore, compositors wishing to take both 1759 | kinds of damage into account will have to accumulate damage from the 1760 | two requests separately and only transform from one to the other 1761 | after receiving the wl_surface.commit. 1762 | 1763 | 1764 | 1765 | 1766 | 1767 | 1768 | 1769 | 1770 | 1771 | 1772 | 1773 | The x and y arguments specify the location of the new pending 1774 | buffer's upper left corner, relative to the current buffer's upper 1775 | left corner, in surface-local coordinates. In other words, the 1776 | x and y, combined with the new surface size define in which 1777 | directions the surface's size changes. 1778 | 1779 | Surface location offset is double-buffered state, see 1780 | wl_surface.commit. 1781 | 1782 | This request is semantically equivalent to and the replaces the x and y 1783 | arguments in the wl_surface.attach request in wl_surface versions prior 1784 | to 5. See wl_surface.attach for details. 1785 | 1786 | 1787 | 1788 | 1789 | 1790 | 1791 | 1792 | 1793 | A seat is a group of keyboards, pointer and touch devices. This 1794 | object is published as a global during start up, or when such a 1795 | device is hot plugged. A seat typically has a pointer and 1796 | maintains a keyboard focus and a pointer focus. 1797 | 1798 | 1799 | 1800 | 1801 | This is a bitmask of capabilities this seat has; if a member is 1802 | set, then it is present on the seat. 1803 | 1804 | 1805 | 1806 | 1807 | 1808 | 1809 | 1810 | 1811 | These errors can be emitted in response to wl_seat requests. 1812 | 1813 | 1815 | 1816 | 1817 | 1818 | 1819 | This is emitted whenever a seat gains or loses the pointer, 1820 | keyboard or touch capabilities. The argument is a capability 1821 | enum containing the complete set of capabilities this seat has. 1822 | 1823 | When the pointer capability is added, a client may create a 1824 | wl_pointer object using the wl_seat.get_pointer request. This object 1825 | will receive pointer events until the capability is removed in the 1826 | future. 1827 | 1828 | When the pointer capability is removed, a client should destroy the 1829 | wl_pointer objects associated with the seat where the capability was 1830 | removed, using the wl_pointer.release request. No further pointer 1831 | events will be received on these objects. 1832 | 1833 | In some compositors, if a seat regains the pointer capability and a 1834 | client has a previously obtained wl_pointer object of version 4 or 1835 | less, that object may start sending pointer events again. This 1836 | behavior is considered a misinterpretation of the intended behavior 1837 | and must not be relied upon by the client. wl_pointer objects of 1838 | version 5 or later must not send events if created before the most 1839 | recent event notifying the client of an added pointer capability. 1840 | 1841 | The above behavior also applies to wl_keyboard and wl_touch with the 1842 | keyboard and touch capabilities, respectively. 1843 | 1844 | 1845 | 1846 | 1847 | 1848 | 1849 | The ID provided will be initialized to the wl_pointer interface 1850 | for this seat. 1851 | 1852 | This request only takes effect if the seat has the pointer 1853 | capability, or has had the pointer capability in the past. 1854 | It is a protocol violation to issue this request on a seat that has 1855 | never had the pointer capability. The missing_capability error will 1856 | be sent in this case. 1857 | 1858 | 1859 | 1860 | 1861 | 1862 | 1863 | The ID provided will be initialized to the wl_keyboard interface 1864 | for this seat. 1865 | 1866 | This request only takes effect if the seat has the keyboard 1867 | capability, or has had the keyboard capability in the past. 1868 | It is a protocol violation to issue this request on a seat that has 1869 | never had the keyboard capability. The missing_capability error will 1870 | be sent in this case. 1871 | 1872 | 1873 | 1874 | 1875 | 1876 | 1877 | The ID provided will be initialized to the wl_touch interface 1878 | for this seat. 1879 | 1880 | This request only takes effect if the seat has the touch 1881 | capability, or has had the touch capability in the past. 1882 | It is a protocol violation to issue this request on a seat that has 1883 | never had the touch capability. The missing_capability error will 1884 | be sent in this case. 1885 | 1886 | 1887 | 1888 | 1889 | 1890 | 1891 | 1892 | 1893 | In a multi-seat configuration the seat name can be used by clients to 1894 | help identify which physical devices the seat represents. 1895 | 1896 | The seat name is a UTF-8 string with no convention defined for its 1897 | contents. Each name is unique among all wl_seat globals. The name is 1898 | only guaranteed to be unique for the current compositor instance. 1899 | 1900 | The same seat names are used for all clients. Thus, the name can be 1901 | shared across processes to refer to a specific wl_seat global. 1902 | 1903 | The name event is sent after binding to the seat global. This event is 1904 | only sent once per seat object, and the name does not change over the 1905 | lifetime of the wl_seat global. 1906 | 1907 | Compositors may re-use the same seat name if the wl_seat global is 1908 | destroyed and re-created later. 1909 | 1910 | 1911 | 1912 | 1913 | 1914 | 1915 | 1916 | 1917 | Using this request a client can tell the server that it is not going to 1918 | use the seat object anymore. 1919 | 1920 | 1921 | 1922 | 1923 | 1924 | 1925 | 1926 | The wl_pointer interface represents one or more input devices, 1927 | such as mice, which control the pointer location and pointer_focus 1928 | of a seat. 1929 | 1930 | The wl_pointer interface generates motion, enter and leave 1931 | events for the surfaces that the pointer is located over, 1932 | and button and axis events for button presses, button releases 1933 | and scrolling. 1934 | 1935 | 1936 | 1937 | 1938 | 1939 | 1940 | 1941 | 1942 | Set the pointer surface, i.e., the surface that contains the 1943 | pointer image (cursor). This request gives the surface the role 1944 | of a cursor. If the surface already has another role, it raises 1945 | a protocol error. 1946 | 1947 | The cursor actually changes only if the pointer 1948 | focus for this device is one of the requesting client's surfaces 1949 | or the surface parameter is the current pointer surface. If 1950 | there was a previous surface set with this request it is 1951 | replaced. If surface is NULL, the pointer image is hidden. 1952 | 1953 | The parameters hotspot_x and hotspot_y define the position of 1954 | the pointer surface relative to the pointer location. Its 1955 | top-left corner is always at (x, y) - (hotspot_x, hotspot_y), 1956 | where (x, y) are the coordinates of the pointer location, in 1957 | surface-local coordinates. 1958 | 1959 | On surface.attach requests to the pointer surface, hotspot_x 1960 | and hotspot_y are decremented by the x and y parameters 1961 | passed to the request. Attach must be confirmed by 1962 | wl_surface.commit as usual. 1963 | 1964 | The hotspot can also be updated by passing the currently set 1965 | pointer surface to this request with new values for hotspot_x 1966 | and hotspot_y. 1967 | 1968 | The current and pending input regions of the wl_surface are 1969 | cleared, and wl_surface.set_input_region is ignored until the 1970 | wl_surface is no longer used as the cursor. When the use as a 1971 | cursor ends, the current and pending input regions become 1972 | undefined, and the wl_surface is unmapped. 1973 | 1974 | The serial parameter must match the latest wl_pointer.enter 1975 | serial number sent to the client. Otherwise the request will be 1976 | ignored. 1977 | 1978 | 1979 | 1981 | 1982 | 1983 | 1984 | 1985 | 1986 | 1987 | Notification that this seat's pointer is focused on a certain 1988 | surface. 1989 | 1990 | When a seat's focus enters a surface, the pointer image 1991 | is undefined and a client should respond to this event by setting 1992 | an appropriate pointer image with the set_cursor request. 1993 | 1994 | 1995 | 1996 | 1997 | 1998 | 1999 | 2000 | 2001 | 2002 | Notification that this seat's pointer is no longer focused on 2003 | a certain surface. 2004 | 2005 | The leave notification is sent before the enter notification 2006 | for the new focus. 2007 | 2008 | 2009 | 2010 | 2011 | 2012 | 2013 | 2014 | Notification of pointer location change. The arguments 2015 | surface_x and surface_y are the location relative to the 2016 | focused surface. 2017 | 2018 | 2019 | 2020 | 2021 | 2022 | 2023 | 2024 | 2025 | Describes the physical state of a button that produced the button 2026 | event. 2027 | 2028 | 2029 | 2030 | 2031 | 2032 | 2033 | 2034 | Mouse button click and release notifications. 2035 | 2036 | The location of the click is given by the last motion or 2037 | enter event. 2038 | The time argument is a timestamp with millisecond 2039 | granularity, with an undefined base. 2040 | 2041 | The button is a button code as defined in the Linux kernel's 2042 | linux/input-event-codes.h header file, e.g. BTN_LEFT. 2043 | 2044 | Any 16-bit button code value is reserved for future additions to the 2045 | kernel's event code list. All other button codes above 0xFFFF are 2046 | currently undefined but may be used in future versions of this 2047 | protocol. 2048 | 2049 | 2050 | 2051 | 2052 | 2053 | 2054 | 2055 | 2056 | 2057 | Describes the axis types of scroll events. 2058 | 2059 | 2060 | 2061 | 2062 | 2063 | 2064 | 2065 | Scroll and other axis notifications. 2066 | 2067 | For scroll events (vertical and horizontal scroll axes), the 2068 | value parameter is the length of a vector along the specified 2069 | axis in a coordinate space identical to those of motion events, 2070 | representing a relative movement along the specified axis. 2071 | 2072 | For devices that support movements non-parallel to axes multiple 2073 | axis events will be emitted. 2074 | 2075 | When applicable, for example for touch pads, the server can 2076 | choose to emit scroll events where the motion vector is 2077 | equivalent to a motion event vector. 2078 | 2079 | When applicable, a client can transform its content relative to the 2080 | scroll distance. 2081 | 2082 | 2083 | 2084 | 2085 | 2086 | 2087 | 2088 | 2089 | 2090 | 2091 | Using this request a client can tell the server that it is not going to 2092 | use the pointer object anymore. 2093 | 2094 | This request destroys the pointer proxy object, so clients must not call 2095 | wl_pointer_destroy() after using this request. 2096 | 2097 | 2098 | 2099 | 2100 | 2101 | 2102 | 2103 | Indicates the end of a set of events that logically belong together. 2104 | A client is expected to accumulate the data in all events within the 2105 | frame before proceeding. 2106 | 2107 | All wl_pointer events before a wl_pointer.frame event belong 2108 | logically together. For example, in a diagonal scroll motion the 2109 | compositor will send an optional wl_pointer.axis_source event, two 2110 | wl_pointer.axis events (horizontal and vertical) and finally a 2111 | wl_pointer.frame event. The client may use this information to 2112 | calculate a diagonal vector for scrolling. 2113 | 2114 | When multiple wl_pointer.axis events occur within the same frame, 2115 | the motion vector is the combined motion of all events. 2116 | When a wl_pointer.axis and a wl_pointer.axis_stop event occur within 2117 | the same frame, this indicates that axis movement in one axis has 2118 | stopped but continues in the other axis. 2119 | When multiple wl_pointer.axis_stop events occur within the same 2120 | frame, this indicates that these axes stopped in the same instance. 2121 | 2122 | A wl_pointer.frame event is sent for every logical event group, 2123 | even if the group only contains a single wl_pointer event. 2124 | Specifically, a client may get a sequence: motion, frame, button, 2125 | frame, axis, frame, axis_stop, frame. 2126 | 2127 | The wl_pointer.enter and wl_pointer.leave events are logical events 2128 | generated by the compositor and not the hardware. These events are 2129 | also grouped by a wl_pointer.frame. When a pointer moves from one 2130 | surface to another, a compositor should group the 2131 | wl_pointer.leave event within the same wl_pointer.frame. 2132 | However, a client must not rely on wl_pointer.leave and 2133 | wl_pointer.enter being in the same wl_pointer.frame. 2134 | Compositor-specific policies may require the wl_pointer.leave and 2135 | wl_pointer.enter event being split across multiple wl_pointer.frame 2136 | groups. 2137 | 2138 | 2139 | 2140 | 2141 | 2142 | Describes the source types for axis events. This indicates to the 2143 | client how an axis event was physically generated; a client may 2144 | adjust the user interface accordingly. For example, scroll events 2145 | from a "finger" source may be in a smooth coordinate space with 2146 | kinetic scrolling whereas a "wheel" source may be in discrete steps 2147 | of a number of lines. 2148 | 2149 | The "continuous" axis source is a device generating events in a 2150 | continuous coordinate space, but using something other than a 2151 | finger. One example for this source is button-based scrolling where 2152 | the vertical motion of a device is converted to scroll events while 2153 | a button is held down. 2154 | 2155 | The "wheel tilt" axis source indicates that the actual device is a 2156 | wheel but the scroll event is not caused by a rotation but a 2157 | (usually sideways) tilt of the wheel. 2158 | 2159 | 2160 | 2161 | 2162 | 2163 | 2164 | 2165 | 2166 | 2167 | Source information for scroll and other axes. 2168 | 2169 | This event does not occur on its own. It is sent before a 2170 | wl_pointer.frame event and carries the source information for 2171 | all events within that frame. 2172 | 2173 | The source specifies how this event was generated. If the source is 2174 | wl_pointer.axis_source.finger, a wl_pointer.axis_stop event will be 2175 | sent when the user lifts the finger off the device. 2176 | 2177 | If the source is wl_pointer.axis_source.wheel, 2178 | wl_pointer.axis_source.wheel_tilt or 2179 | wl_pointer.axis_source.continuous, a wl_pointer.axis_stop event may 2180 | or may not be sent. Whether a compositor sends an axis_stop event 2181 | for these sources is hardware-specific and implementation-dependent; 2182 | clients must not rely on receiving an axis_stop event for these 2183 | scroll sources and should treat scroll sequences from these scroll 2184 | sources as unterminated by default. 2185 | 2186 | This event is optional. If the source is unknown for a particular 2187 | axis event sequence, no event is sent. 2188 | Only one wl_pointer.axis_source event is permitted per frame. 2189 | 2190 | The order of wl_pointer.axis_discrete and wl_pointer.axis_source is 2191 | not guaranteed. 2192 | 2193 | 2194 | 2195 | 2196 | 2197 | 2198 | Stop notification for scroll and other axes. 2199 | 2200 | For some wl_pointer.axis_source types, a wl_pointer.axis_stop event 2201 | is sent to notify a client that the axis sequence has terminated. 2202 | This enables the client to implement kinetic scrolling. 2203 | See the wl_pointer.axis_source documentation for information on when 2204 | this event may be generated. 2205 | 2206 | Any wl_pointer.axis events with the same axis_source after this 2207 | event should be considered as the start of a new axis motion. 2208 | 2209 | The timestamp is to be interpreted identical to the timestamp in the 2210 | wl_pointer.axis event. The timestamp value may be the same as a 2211 | preceding wl_pointer.axis event. 2212 | 2213 | 2214 | 2215 | 2216 | 2217 | 2218 | 2219 | Discrete step information for scroll and other axes. 2220 | 2221 | This event carries the axis value of the wl_pointer.axis event in 2222 | discrete steps (e.g. mouse wheel clicks). 2223 | 2224 | This event is deprecated with wl_pointer version 8 - this event is not 2225 | sent to clients supporting version 8 or later. 2226 | 2227 | This event does not occur on its own, it is coupled with a 2228 | wl_pointer.axis event that represents this axis value on a 2229 | continuous scale. The protocol guarantees that each axis_discrete 2230 | event is always followed by exactly one axis event with the same 2231 | axis number within the same wl_pointer.frame. Note that the protocol 2232 | allows for other events to occur between the axis_discrete and 2233 | its coupled axis event, including other axis_discrete or axis 2234 | events. A wl_pointer.frame must not contain more than one axis_discrete 2235 | event per axis type. 2236 | 2237 | This event is optional; continuous scrolling devices 2238 | like two-finger scrolling on touchpads do not have discrete 2239 | steps and do not generate this event. 2240 | 2241 | The discrete value carries the directional information. e.g. a value 2242 | of -2 is two steps towards the negative direction of this axis. 2243 | 2244 | The axis number is identical to the axis number in the associated 2245 | axis event. 2246 | 2247 | The order of wl_pointer.axis_discrete and wl_pointer.axis_source is 2248 | not guaranteed. 2249 | 2250 | 2251 | 2252 | 2253 | 2254 | 2255 | 2256 | Discrete high-resolution scroll information. 2257 | 2258 | This event carries high-resolution wheel scroll information, 2259 | with each multiple of 120 representing one logical scroll step 2260 | (a wheel detent). For example, an axis_value120 of 30 is one quarter of 2261 | a logical scroll step in the positive direction, a value120 of 2262 | -240 are two logical scroll steps in the negative direction within the 2263 | same hardware event. 2264 | Clients that rely on discrete scrolling should accumulate the 2265 | value120 to multiples of 120 before processing the event. 2266 | 2267 | The value120 must not be zero. 2268 | 2269 | This event replaces the wl_pointer.axis_discrete event in clients 2270 | supporting wl_pointer version 8 or later. 2271 | 2272 | Where a wl_pointer.axis_source event occurs in the same 2273 | wl_pointer.frame, the axis source applies to this event. 2274 | 2275 | The order of wl_pointer.axis_value120 and wl_pointer.axis_source is 2276 | not guaranteed. 2277 | 2278 | 2279 | 2280 | 2281 | 2282 | 2283 | 2284 | 2285 | The wl_keyboard interface represents one or more keyboards 2286 | associated with a seat. 2287 | 2288 | 2289 | 2290 | 2291 | This specifies the format of the keymap provided to the 2292 | client with the wl_keyboard.keymap event. 2293 | 2294 | 2296 | 2298 | 2299 | 2300 | 2301 | 2302 | This event provides a file descriptor to the client which can be 2303 | memory-mapped in read-only mode to provide a keyboard mapping 2304 | description. 2305 | 2306 | From version 7 onwards, the fd must be mapped with MAP_PRIVATE by 2307 | the recipient, as MAP_SHARED may fail. 2308 | 2309 | 2310 | 2311 | 2312 | 2313 | 2314 | 2315 | 2316 | Notification that this seat's keyboard focus is on a certain 2317 | surface. 2318 | 2319 | The compositor must send the wl_keyboard.modifiers event after this 2320 | event. 2321 | 2322 | 2323 | 2324 | 2325 | 2326 | 2327 | 2328 | 2329 | Notification that this seat's keyboard focus is no longer on 2330 | a certain surface. 2331 | 2332 | The leave notification is sent before the enter notification 2333 | for the new focus. 2334 | 2335 | After this event client must assume that all keys, including modifiers, 2336 | are lifted and also it must stop key repeating if there's some going on. 2337 | 2338 | 2339 | 2340 | 2341 | 2342 | 2343 | 2344 | Describes the physical state of a key that produced the key event. 2345 | 2346 | 2347 | 2348 | 2349 | 2350 | 2351 | 2352 | A key was pressed or released. 2353 | The time argument is a timestamp with millisecond 2354 | granularity, with an undefined base. 2355 | 2356 | The key is a platform-specific key code that can be interpreted 2357 | by feeding it to the keyboard mapping (see the keymap event). 2358 | 2359 | If this event produces a change in modifiers, then the resulting 2360 | wl_keyboard.modifiers event must be sent after this event. 2361 | 2362 | 2363 | 2364 | 2365 | 2366 | 2367 | 2368 | 2369 | 2370 | Notifies clients that the modifier and/or group state has 2371 | changed, and it should update its local state. 2372 | 2373 | 2374 | 2375 | 2376 | 2377 | 2378 | 2379 | 2380 | 2381 | 2382 | 2383 | 2384 | 2385 | 2386 | 2387 | 2388 | 2389 | 2390 | Informs the client about the keyboard's repeat rate and delay. 2391 | 2392 | This event is sent as soon as the wl_keyboard object has been created, 2393 | and is guaranteed to be received by the client before any key press 2394 | event. 2395 | 2396 | Negative values for either rate or delay are illegal. A rate of zero 2397 | will disable any repeating (regardless of the value of delay). 2398 | 2399 | This event can be sent later on as well with a new value if necessary, 2400 | so clients should continue listening for the event past the creation 2401 | of wl_keyboard. 2402 | 2403 | 2405 | 2407 | 2408 | 2409 | 2410 | 2411 | 2412 | The wl_touch interface represents a touchscreen 2413 | associated with a seat. 2414 | 2415 | Touch interactions can consist of one or more contacts. 2416 | For each contact, a series of events is generated, starting 2417 | with a down event, followed by zero or more motion events, 2418 | and ending with an up event. Events relating to the same 2419 | contact point can be identified by the ID of the sequence. 2420 | 2421 | 2422 | 2423 | 2424 | A new touch point has appeared on the surface. This touch point is 2425 | assigned a unique ID. Future events from this touch point reference 2426 | this ID. The ID ceases to be valid after a touch up event and may be 2427 | reused in the future. 2428 | 2429 | 2430 | 2431 | 2432 | 2433 | 2434 | 2435 | 2436 | 2437 | 2438 | 2439 | The touch point has disappeared. No further events will be sent for 2440 | this touch point and the touch point's ID is released and may be 2441 | reused in a future touch down event. 2442 | 2443 | 2444 | 2445 | 2446 | 2447 | 2448 | 2449 | 2450 | A touch point has changed coordinates. 2451 | 2452 | 2453 | 2454 | 2455 | 2456 | 2457 | 2458 | 2459 | 2460 | Indicates the end of a set of events that logically belong together. 2461 | A client is expected to accumulate the data in all events within the 2462 | frame before proceeding. 2463 | 2464 | A wl_touch.frame terminates at least one event but otherwise no 2465 | guarantee is provided about the set of events within a frame. A client 2466 | must assume that any state not updated in a frame is unchanged from the 2467 | previously known state. 2468 | 2469 | 2470 | 2471 | 2472 | 2473 | Sent if the compositor decides the touch stream is a global 2474 | gesture. No further events are sent to the clients from that 2475 | particular gesture. Touch cancellation applies to all touch points 2476 | currently active on this client's surface. The client is 2477 | responsible for finalizing the touch points, future touch points on 2478 | this surface may reuse the touch point ID. 2479 | 2480 | 2481 | 2482 | 2483 | 2484 | 2485 | 2486 | 2487 | 2488 | 2489 | 2490 | 2491 | 2492 | Sent when a touchpoint has changed its shape. 2493 | 2494 | This event does not occur on its own. It is sent before a 2495 | wl_touch.frame event and carries the new shape information for 2496 | any previously reported, or new touch points of that frame. 2497 | 2498 | Other events describing the touch point such as wl_touch.down, 2499 | wl_touch.motion or wl_touch.orientation may be sent within the 2500 | same wl_touch.frame. A client should treat these events as a single 2501 | logical touch point update. The order of wl_touch.shape, 2502 | wl_touch.orientation and wl_touch.motion is not guaranteed. 2503 | A wl_touch.down event is guaranteed to occur before the first 2504 | wl_touch.shape event for this touch ID but both events may occur within 2505 | the same wl_touch.frame. 2506 | 2507 | A touchpoint shape is approximated by an ellipse through the major and 2508 | minor axis length. The major axis length describes the longer diameter 2509 | of the ellipse, while the minor axis length describes the shorter 2510 | diameter. Major and minor are orthogonal and both are specified in 2511 | surface-local coordinates. The center of the ellipse is always at the 2512 | touchpoint location as reported by wl_touch.down or wl_touch.move. 2513 | 2514 | This event is only sent by the compositor if the touch device supports 2515 | shape reports. The client has to make reasonable assumptions about the 2516 | shape if it did not receive this event. 2517 | 2518 | 2519 | 2520 | 2521 | 2522 | 2523 | 2524 | 2525 | Sent when a touchpoint has changed its orientation. 2526 | 2527 | This event does not occur on its own. It is sent before a 2528 | wl_touch.frame event and carries the new shape information for 2529 | any previously reported, or new touch points of that frame. 2530 | 2531 | Other events describing the touch point such as wl_touch.down, 2532 | wl_touch.motion or wl_touch.shape may be sent within the 2533 | same wl_touch.frame. A client should treat these events as a single 2534 | logical touch point update. The order of wl_touch.shape, 2535 | wl_touch.orientation and wl_touch.motion is not guaranteed. 2536 | A wl_touch.down event is guaranteed to occur before the first 2537 | wl_touch.orientation event for this touch ID but both events may occur 2538 | within the same wl_touch.frame. 2539 | 2540 | The orientation describes the clockwise angle of a touchpoint's major 2541 | axis to the positive surface y-axis and is normalized to the -180 to 2542 | +180 degree range. The granularity of orientation depends on the touch 2543 | device, some devices only support binary rotation values between 0 and 2544 | 90 degrees. 2545 | 2546 | This event is only sent by the compositor if the touch device supports 2547 | orientation reports. 2548 | 2549 | 2550 | 2551 | 2552 | 2553 | 2554 | 2555 | 2556 | An output describes part of the compositor geometry. The 2557 | compositor works in the 'compositor coordinate system' and an 2558 | output corresponds to a rectangular area in that space that is 2559 | actually visible. This typically corresponds to a monitor that 2560 | displays part of the compositor space. This object is published 2561 | as global during start up, or when a monitor is hotplugged. 2562 | 2563 | 2564 | 2565 | 2566 | This enumeration describes how the physical 2567 | pixels on an output are laid out. 2568 | 2569 | 2570 | 2571 | 2572 | 2573 | 2574 | 2575 | 2576 | 2577 | 2578 | 2579 | This describes the transform that a compositor will apply to a 2580 | surface to compensate for the rotation or mirroring of an 2581 | output device. 2582 | 2583 | The flipped values correspond to an initial flip around a 2584 | vertical axis followed by rotation. 2585 | 2586 | The purpose is mainly to allow clients to render accordingly and 2587 | tell the compositor, so that for fullscreen surfaces, the 2588 | compositor will still be able to scan out directly from client 2589 | surfaces. 2590 | 2591 | 2592 | 2593 | 2594 | 2595 | 2596 | 2597 | 2598 | 2599 | 2600 | 2601 | 2602 | 2603 | The geometry event describes geometric properties of the output. 2604 | The event is sent when binding to the output object and whenever 2605 | any of the properties change. 2606 | 2607 | The physical size can be set to zero if it doesn't make sense for this 2608 | output (e.g. for projectors or virtual outputs). 2609 | 2610 | The geometry event will be followed by a done event (starting from 2611 | version 2). 2612 | 2613 | Note: wl_output only advertises partial information about the output 2614 | position and identification. Some compositors, for instance those not 2615 | implementing a desktop-style output layout or those exposing virtual 2616 | outputs, might fake this information. Instead of using x and y, clients 2617 | should use xdg_output.logical_position. Instead of using make and model, 2618 | clients should use name and description. 2619 | 2620 | 2622 | 2624 | 2626 | 2628 | 2630 | 2632 | 2634 | 2636 | 2637 | 2638 | 2639 | 2640 | These flags describe properties of an output mode. 2641 | They are used in the flags bitfield of the mode event. 2642 | 2643 | 2645 | 2647 | 2648 | 2649 | 2650 | 2651 | The mode event describes an available mode for the output. 2652 | 2653 | The event is sent when binding to the output object and there 2654 | will always be one mode, the current mode. The event is sent 2655 | again if an output changes mode, for the mode that is now 2656 | current. In other words, the current mode is always the last 2657 | mode that was received with the current flag set. 2658 | 2659 | Non-current modes are deprecated. A compositor can decide to only 2660 | advertise the current mode and never send other modes. Clients 2661 | should not rely on non-current modes. 2662 | 2663 | The size of a mode is given in physical hardware units of 2664 | the output device. This is not necessarily the same as 2665 | the output size in the global compositor space. For instance, 2666 | the output may be scaled, as described in wl_output.scale, 2667 | or transformed, as described in wl_output.transform. Clients 2668 | willing to retrieve the output size in the global compositor 2669 | space should use xdg_output.logical_size instead. 2670 | 2671 | The vertical refresh rate can be set to zero if it doesn't make 2672 | sense for this output (e.g. for virtual outputs). 2673 | 2674 | The mode event will be followed by a done event (starting from 2675 | version 2). 2676 | 2677 | Clients should not use the refresh rate to schedule frames. Instead, 2678 | they should use the wl_surface.frame event or the presentation-time 2679 | protocol. 2680 | 2681 | Note: this information is not always meaningful for all outputs. Some 2682 | compositors, such as those exposing virtual outputs, might fake the 2683 | refresh rate or the size. 2684 | 2685 | 2686 | 2687 | 2688 | 2689 | 2690 | 2691 | 2692 | 2693 | 2694 | 2695 | This event is sent after all other properties have been 2696 | sent after binding to the output object and after any 2697 | other property changes done after that. This allows 2698 | changes to the output properties to be seen as 2699 | atomic, even if they happen via multiple events. 2700 | 2701 | 2702 | 2703 | 2704 | 2705 | This event contains scaling geometry information 2706 | that is not in the geometry event. It may be sent after 2707 | binding the output object or if the output scale changes 2708 | later. If it is not sent, the client should assume a 2709 | scale of 1. 2710 | 2711 | A scale larger than 1 means that the compositor will 2712 | automatically scale surface buffers by this amount 2713 | when rendering. This is used for very high resolution 2714 | displays where applications rendering at the native 2715 | resolution would be too small to be legible. 2716 | 2717 | It is intended that scaling aware clients track the 2718 | current output of a surface, and if it is on a scaled 2719 | output it should use wl_surface.set_buffer_scale with 2720 | the scale of the output. That way the compositor can 2721 | avoid scaling the surface, and the client can supply 2722 | a higher detail image. 2723 | 2724 | The scale event will be followed by a done event. 2725 | 2726 | 2727 | 2728 | 2729 | 2730 | 2731 | 2732 | 2733 | Using this request a client can tell the server that it is not going to 2734 | use the output object anymore. 2735 | 2736 | 2737 | 2738 | 2739 | 2740 | 2741 | 2742 | Many compositors will assign user-friendly names to their outputs, show 2743 | them to the user, allow the user to refer to an output, etc. The client 2744 | may wish to know this name as well to offer the user similar behaviors. 2745 | 2746 | The name is a UTF-8 string with no convention defined for its contents. 2747 | Each name is unique among all wl_output globals. The name is only 2748 | guaranteed to be unique for the compositor instance. 2749 | 2750 | The same output name is used for all clients for a given wl_output 2751 | global. Thus, the name can be shared across processes to refer to a 2752 | specific wl_output global. 2753 | 2754 | The name is not guaranteed to be persistent across sessions, thus cannot 2755 | be used to reliably identify an output in e.g. configuration files. 2756 | 2757 | Examples of names include 'HDMI-A-1', 'WL-1', 'X11-1', etc. However, do 2758 | not assume that the name is a reflection of an underlying DRM connector, 2759 | X11 connection, etc. 2760 | 2761 | The name event is sent after binding the output object. This event is 2762 | only sent once per output object, and the name does not change over the 2763 | lifetime of the wl_output global. 2764 | 2765 | Compositors may re-use the same output name if the wl_output global is 2766 | destroyed and re-created later. Compositors should avoid re-using the 2767 | same name if possible. 2768 | 2769 | The name event will be followed by a done event. 2770 | 2771 | 2772 | 2773 | 2774 | 2775 | 2776 | Many compositors can produce human-readable descriptions of their 2777 | outputs. The client may wish to know this description as well, e.g. for 2778 | output selection purposes. 2779 | 2780 | The description is a UTF-8 string with no convention defined for its 2781 | contents. The description is not guaranteed to be unique among all 2782 | wl_output globals. Examples might include 'Foocorp 11" Display' or 2783 | 'Virtual X11 output via :1'. 2784 | 2785 | The description event is sent after binding the output object and 2786 | whenever the description changes. The description is optional, and may 2787 | not be sent at all. 2788 | 2789 | The description event will be followed by a done event. 2790 | 2791 | 2792 | 2793 | 2794 | 2795 | 2796 | 2797 | A region object describes an area. 2798 | 2799 | Region objects are used to describe the opaque and input 2800 | regions of a surface. 2801 | 2802 | 2803 | 2804 | 2805 | Destroy the region. This will invalidate the object ID. 2806 | 2807 | 2808 | 2809 | 2810 | 2811 | Add the specified rectangle to the region. 2812 | 2813 | 2814 | 2815 | 2816 | 2817 | 2818 | 2819 | 2820 | 2821 | Subtract the specified rectangle from the region. 2822 | 2823 | 2824 | 2825 | 2826 | 2827 | 2828 | 2829 | 2830 | 2831 | 2832 | The global interface exposing sub-surface compositing capabilities. 2833 | A wl_surface, that has sub-surfaces associated, is called the 2834 | parent surface. Sub-surfaces can be arbitrarily nested and create 2835 | a tree of sub-surfaces. 2836 | 2837 | The root surface in a tree of sub-surfaces is the main 2838 | surface. The main surface cannot be a sub-surface, because 2839 | sub-surfaces must always have a parent. 2840 | 2841 | A main surface with its sub-surfaces forms a (compound) window. 2842 | For window management purposes, this set of wl_surface objects is 2843 | to be considered as a single window, and it should also behave as 2844 | such. 2845 | 2846 | The aim of sub-surfaces is to offload some of the compositing work 2847 | within a window from clients to the compositor. A prime example is 2848 | a video player with decorations and video in separate wl_surface 2849 | objects. This should allow the compositor to pass YUV video buffer 2850 | processing to dedicated overlay hardware when possible. 2851 | 2852 | 2853 | 2854 | 2855 | Informs the server that the client will not be using this 2856 | protocol object anymore. This does not affect any other 2857 | objects, wl_subsurface objects included. 2858 | 2859 | 2860 | 2861 | 2862 | 2864 | 2865 | 2866 | 2867 | 2868 | Create a sub-surface interface for the given surface, and 2869 | associate it with the given parent surface. This turns a 2870 | plain wl_surface into a sub-surface. 2871 | 2872 | The to-be sub-surface must not already have another role, and it 2873 | must not have an existing wl_subsurface object. Otherwise a protocol 2874 | error is raised. 2875 | 2876 | Adding sub-surfaces to a parent is a double-buffered operation on the 2877 | parent (see wl_surface.commit). The effect of adding a sub-surface 2878 | becomes visible on the next time the state of the parent surface is 2879 | applied. 2880 | 2881 | This request modifies the behaviour of wl_surface.commit request on 2882 | the sub-surface, see the documentation on wl_subsurface interface. 2883 | 2884 | 2886 | 2888 | 2890 | 2891 | 2892 | 2893 | 2894 | 2895 | An additional interface to a wl_surface object, which has been 2896 | made a sub-surface. A sub-surface has one parent surface. A 2897 | sub-surface's size and position are not limited to that of the parent. 2898 | Particularly, a sub-surface is not automatically clipped to its 2899 | parent's area. 2900 | 2901 | A sub-surface becomes mapped, when a non-NULL wl_buffer is applied 2902 | and the parent surface is mapped. The order of which one happens 2903 | first is irrelevant. A sub-surface is hidden if the parent becomes 2904 | hidden, or if a NULL wl_buffer is applied. These rules apply 2905 | recursively through the tree of surfaces. 2906 | 2907 | The behaviour of a wl_surface.commit request on a sub-surface 2908 | depends on the sub-surface's mode. The possible modes are 2909 | synchronized and desynchronized, see methods 2910 | wl_subsurface.set_sync and wl_subsurface.set_desync. Synchronized 2911 | mode caches the wl_surface state to be applied when the parent's 2912 | state gets applied, and desynchronized mode applies the pending 2913 | wl_surface state directly. A sub-surface is initially in the 2914 | synchronized mode. 2915 | 2916 | Sub-surfaces also have another kind of state, which is managed by 2917 | wl_subsurface requests, as opposed to wl_surface requests. This 2918 | state includes the sub-surface position relative to the parent 2919 | surface (wl_subsurface.set_position), and the stacking order of 2920 | the parent and its sub-surfaces (wl_subsurface.place_above and 2921 | .place_below). This state is applied when the parent surface's 2922 | wl_surface state is applied, regardless of the sub-surface's mode. 2923 | As the exception, set_sync and set_desync are effective immediately. 2924 | 2925 | The main surface can be thought to be always in desynchronized mode, 2926 | since it does not have a parent in the sub-surfaces sense. 2927 | 2928 | Even if a sub-surface is in desynchronized mode, it will behave as 2929 | in synchronized mode, if its parent surface behaves as in 2930 | synchronized mode. This rule is applied recursively throughout the 2931 | tree of surfaces. This means, that one can set a sub-surface into 2932 | synchronized mode, and then assume that all its child and grand-child 2933 | sub-surfaces are synchronized, too, without explicitly setting them. 2934 | 2935 | If the wl_surface associated with the wl_subsurface is destroyed, the 2936 | wl_subsurface object becomes inert. Note, that destroying either object 2937 | takes effect immediately. If you need to synchronize the removal 2938 | of a sub-surface to the parent surface update, unmap the sub-surface 2939 | first by attaching a NULL wl_buffer, update parent, and then destroy 2940 | the sub-surface. 2941 | 2942 | If the parent wl_surface object is destroyed, the sub-surface is 2943 | unmapped. 2944 | 2945 | 2946 | 2947 | 2948 | The sub-surface interface is removed from the wl_surface object 2949 | that was turned into a sub-surface with a 2950 | wl_subcompositor.get_subsurface request. The wl_surface's association 2951 | to the parent is deleted, and the wl_surface loses its role as 2952 | a sub-surface. The wl_surface is unmapped immediately. 2953 | 2954 | 2955 | 2956 | 2957 | 2959 | 2960 | 2961 | 2962 | 2963 | This schedules a sub-surface position change. 2964 | The sub-surface will be moved so that its origin (top left 2965 | corner pixel) will be at the location x, y of the parent surface 2966 | coordinate system. The coordinates are not restricted to the parent 2967 | surface area. Negative values are allowed. 2968 | 2969 | The scheduled coordinates will take effect whenever the state of the 2970 | parent surface is applied. When this happens depends on whether the 2971 | parent surface is in synchronized mode or not. See 2972 | wl_subsurface.set_sync and wl_subsurface.set_desync for details. 2973 | 2974 | If more than one set_position request is invoked by the client before 2975 | the commit of the parent surface, the position of a new request always 2976 | replaces the scheduled position from any previous request. 2977 | 2978 | The initial position is 0, 0. 2979 | 2980 | 2981 | 2982 | 2983 | 2984 | 2985 | 2986 | This sub-surface is taken from the stack, and put back just 2987 | above the reference surface, changing the z-order of the sub-surfaces. 2988 | The reference surface must be one of the sibling surfaces, or the 2989 | parent surface. Using any other surface, including this sub-surface, 2990 | will cause a protocol error. 2991 | 2992 | The z-order is double-buffered. Requests are handled in order and 2993 | applied immediately to a pending state. The final pending state is 2994 | copied to the active state the next time the state of the parent 2995 | surface is applied. When this happens depends on whether the parent 2996 | surface is in synchronized mode or not. See wl_subsurface.set_sync and 2997 | wl_subsurface.set_desync for details. 2998 | 2999 | A new sub-surface is initially added as the top-most in the stack 3000 | of its siblings and parent. 3001 | 3002 | 3004 | 3005 | 3006 | 3007 | 3008 | The sub-surface is placed just below the reference surface. 3009 | See wl_subsurface.place_above. 3010 | 3011 | 3013 | 3014 | 3015 | 3016 | 3017 | Change the commit behaviour of the sub-surface to synchronized 3018 | mode, also described as the parent dependent mode. 3019 | 3020 | In synchronized mode, wl_surface.commit on a sub-surface will 3021 | accumulate the committed state in a cache, but the state will 3022 | not be applied and hence will not change the compositor output. 3023 | The cached state is applied to the sub-surface immediately after 3024 | the parent surface's state is applied. This ensures atomic 3025 | updates of the parent and all its synchronized sub-surfaces. 3026 | Applying the cached state will invalidate the cache, so further 3027 | parent surface commits do not (re-)apply old state. 3028 | 3029 | See wl_subsurface for the recursive effect of this mode. 3030 | 3031 | 3032 | 3033 | 3034 | 3035 | Change the commit behaviour of the sub-surface to desynchronized 3036 | mode, also described as independent or freely running mode. 3037 | 3038 | In desynchronized mode, wl_surface.commit on a sub-surface will 3039 | apply the pending state directly, without caching, as happens 3040 | normally with a wl_surface. Calling wl_surface.commit on the 3041 | parent surface has no effect on the sub-surface's wl_surface 3042 | state. This mode allows a sub-surface to be updated on its own. 3043 | 3044 | If cached state exists when wl_surface.commit is called in 3045 | desynchronized mode, the pending state is added to the cached 3046 | state, and applied as a whole. This invalidates the cache. 3047 | 3048 | Note: even if a sub-surface is set to desynchronized, a parent 3049 | sub-surface may override it to behave as synchronized. For details, 3050 | see wl_subsurface. 3051 | 3052 | If a surface's parent surface behaves as desynchronized, then 3053 | the cached state is applied on set_desync. 3054 | 3055 | 3056 | 3057 | 3058 | 3059 | -------------------------------------------------------------------------------- /setup.cfg: -------------------------------------------------------------------------------- 1 | [metadata] 2 | name = riverwm-utils 3 | version = 0.0.10 4 | author = Nick Hastings 5 | author_email = nicholaschastings@gmail.com 6 | description = Utilities for the River Wayland compositor 7 | long_description = file: README.md 8 | long_description_content_type = text/markdown 9 | license = GPLv3 10 | license_file = LICENSE 11 | url = https://github.com/NickHastings/riverwm-utils 12 | classifiers = 13 | Programming Language :: Python :: 3.7 14 | License :: OSI Approved :: GNU General Public License v3 (GPLv3) 15 | Operating System :: POSIX :: Linux 16 | 17 | [options] 18 | packages = find: 19 | python_requires = >=3.7 20 | install_requires = 21 | pywayland >=0.4.7 22 | 23 | [options.entry_points] 24 | console_scripts = 25 | cycle-focused-tags = riverwm_utils.riverwm_utils:cycle_focused_tags 26 | 27 | [options.package_data] 28 | riverwm_utils = 29 | *.xml 30 | -------------------------------------------------------------------------------- /setup.py: -------------------------------------------------------------------------------- 1 | '''Packaging Boilerplate''' 2 | from setuptools import setup 3 | setup() 4 | --------------------------------------------------------------------------------