1# NEWS 2 3<a name="v43"></a> 4# Awesome window manager framework version 4.3 changes 5 6<center> <img src="../images/AUTOGEN_wibox_logo_logo_and_name.svg" /> </center> 7 8Awesome v4.3 is the third release of the 4.x API. It comes after one and a half 9years of little fixes and improvements. Awesome v4.2 was very stable thanks to 10everybody's effort to unit test everything. Given no major bug warranted a new 11release, this one adds a few large features while preserving full compatibility 12with existing user configurations. 13 14## New features 15 16 * `gears.string` now has a `endswith` and `startswith` functions 17 * `luarocks` modules are now automatically available in Awesome 18 * A generic way to create or use widgets has been added 19 (`wibox.widget.base.make_widget_from_value`) 20 * It is now possible to connect to signals from all instances of a widget at once 21 * The calendar widget now supports margins 22 * The documentation has a new theme 23 * Wiboxes now have `to_widget()` and `save_to_svg()` methods. 24 * The client objects now have a `immobilized_horizontal` and 25 `immobilized_vertical` property to know if they can currently be moved or 26 resized (for example, it is set to false when maximized) 27 * `gears.timer` objects now have a `call_now` method. 28 * The hotkey popup now supports `termite` keybindings 29 * The menubar loads faster 30 * Wiboxes have an `input_passthrough` property to send mouse clicks 31 to the object below. 32 * The `taglist` and `tasklist` now support the declarative constructor syntax 33 * There is now an `awesome.pixbuf_to_surface` to convert a `GdkPixbuf` to 34 a cairo surface. 35 * The notifications icon can now be resized and limited with 36 `notification\_icon_\size` 37 * A `gears.sort` module has been added with graph resolution 38 * `awesome-client` now runs code in a protected context 39 * The <a href="./03-declarative-layout.md.html">widget documentation</a> has 40 been extended to be more friendly to new users. 41 * There is a new `beautiful.maximized_hide_border` theme option to hide the 42 border for maximized clients. 43 * The `client` `startup_id` field is now writable. This is useful when the 44 client native implementation is not present or too buggy to be used. 45 * The `awful.widget.prompt` now has a `with_shell` option to allow Bash/ZSH 46 aliases, function and environment variables to be used in commands. 47 * The `awful.titlebar`s now have a `fallback_name` when a client has no `name` 48 property. 49 * Clients now have a `motif_wm_hints` property to reflect some hints using the 50 Motif X11 property extension. This is used by some modern toolkits including 51 GTK. 52 * Clients now have a `requests_no_titlebar` property to expose when a client 53 has client side titlebars (also known as decorations and CSD) 54 * The hotkey popup now has a `show_awesome_keys` option. 55 * The `awful.widget.prompt` now has more of the `awful.prompt` constructor 56 arguments. 57 * It is now possible to set a list of layouts per tag instead of a single 58 global one. 59 * There is now a `awful.layout.get_tag_layout_index()` function to get the 60 index of the current layout in the global layout list 61 (`awful.layout..layouts`) 62 * The `wibox.layout.manual` layout now has an `:insert()` method. 63 64### Better DPI handling 65 66The screen now has a read/write `dpi` property and `awful.screen.set_auto_dpi_enabled(true)` 67can be used to automatically set the DPI for many Awesome elements. Please 68note that it is not backward compatible and breaks many widget. As AwesomeWM 69always used pixels as the de-facto metric for sizes, enabling `auto_dpi` will 70break most existing configs. However, for people who use such setup, it might be 71worth speding some time to fix their config. 72 73### Extendable `awful.rules` providers and better `awful.spawn` functions 74 75There is two new functions called `awful.rules.add_rule_source` and 76`awful.rules.remove_rule_source`. They allow to create a dependency graph 77for where a rule comes from and which provider has the priority when setting it. 78 79Previously, there were the normal properties, 80`awful.rules.high_priority_properties` and `awful.rules.delayed_properties`. 81This didn't scale and could not represent all corner cases. Those table still 82exist and are still honored, but there is now a system that can handle the full 83complexity of the property priority graph. 84 85This is used by default in `awful.spawn`. The reliability of attaching 86properties to `spawn` calls has been improved. On top of this, three new 87functions were added 88 89 * `awful.spawn.once` 90 * `awful.spawn.single_instance` 91 * `awful.spawn.raise_or_spawn` 92 93They allow to specify that a command should only have one running instance. 94This works across restart too, so all hacks to handle restarting Awesome are 95no longer required. 96 97Note that the `client.startup_id` isn't supported by all applications and a 98Linux-specific workaround is recommended to improve the reliability of the 99`awful.spawn` functions. 100 101### A brand new keygrabber API 102 103The `keygrabber` module API was rebuilt from scratch to make it more usable. 104The previous API was very low level, very close to how it actually work, but 105was disconnected from how keygrabbers are used in a window manager. Getting 106anything done with the previous API required a lot of boilerplate code and had 107many corner cases to handle. The new API has built-in support for the most 108common use cases and is fully declarative. 109 110### A new GTK color palette based theme 111 112A new theme has been added. It reads the GTK theme colors and use them in the 113`wibar`, `menu` and `titlebar`. It helps create an uniform look and feel 114between the window manager and client applications with minimal efforts. 115 116### Widgets improvements 117 118The following widgets have been added: 119 120<table class='widget_list' border=1> 121 <tr style='font-weight: bold;'> 122 <th align='center'>Name</th> 123 <th align='center'>Example</th> 124 </tr> 125<tr> 126 <td> 127 <a href='../classes/wibox.widget.checkbox.html'>wibox.widget.separator</a> 128 </td> 129 <td><img src='../images/AUTOGEN_wibox_widget_defaults_separator.svg' /></td> 130</tr> 131</table> 132 133It is now possible to set `spacing` widgets for all layouts: 134 135[](../classes/wibox.layout.flex.html#wibox.layout.flex.spacing_widget) 136 137The `awful.widget.taglist` and `awful.widget.tasklist` now support creating 138custom widgets for each elements: 139 140[](../classes/wibox.layout.flex.html#wibox.layout.flex.spacing_widget) 141 142[](../classes/wibox.layout.flex.html#wibox.layout.flex.spacing_widget) 143 144[](../classes/wibox.layout.flex.html#wibox.layout.flex.spacing_widget) 145 146A new `popup` widget allows to bypass most of the boilerplate code and easily 147display widgets on the screen: 148 149[](../classes/awful.popup.html) 150 151 152The `awful.widget.layoutlist` allows to easily display and select the client 153layout from a widget: 154 155[](../classes/awful.widget.layoutlist.html) 156 157 158## Noteworthy fixes 159 160 * There is no longer an error when a tag defined by name in `awful.rules` is 161 not found. 162 * The menubar is now generally more robust thanks to a variety of improvements 163 * Many dead links in the documentation have been fixed 164 * The `textclock` is now generally more robust with formatting issues, 165 timezones and declarative constructors. 166 * The last screen is never removed. Previously, some laptops removed all screens 167 during suspend, causing all clients to go to the first tag or getting lost 168 completely. 169 * The new default `rc.lua` uses `request::activate` to set the focus. This 170 fixes many corner case such as unfocusable clients getting the focus. 171 * Calling `awful.spawn` with a set of properties is now more reliable. 172 * `awful.key.execute` is now much more reliable. 173 174## Behavior changes 175 176* Previously, when accessing a screen by RandR output name caused a Lua error 177 when no output with the given name exists. This was changed to now return 178 `nil` instead. This could break code that uses `pcall` to check if a screen 179 exists. This code now needs to be changed to check for a `nil` return instead. 180 In practice it is unlikely anyone will notice the difference. 181* In the previous release, unfocusable clients might also not be raised. 182 It was decided that this is a bug and the default behavior was changed. 183 184<a name="v42"></a> 185# Awesome window manager framework version 4.2 changes 186 187Awesome v4.2 is the second release of the 4.x API. It mostly fixes the bugs 188reported over the last 3 months and adds a couple widgets. Almost 150 issues 189have been resolved or decided to be obsolete. 190 191## Noteworthy fixes 192 193 * The annoying maximization regression from v4.1 has been fixed 194 * Fixes broken drag&drop with some applications like FlowBlade 195 * Changing the keyboard layout using `xmodmap` is now much faster 196 * Fixes a regression that prevents Awesome to start when the wallpaper is invalid 197 * The client history is now more reliable 198 * Another instance where clients ended up in the wrong screen has been fixed 199 * Awesome will no longer generate zombie processes when restarted 200 * All official themes now support HiDPI screens 201 * The `magnifier` layout has been fixed 202 * The menubar has been fixed for Lua 5.1 users 203 204## New features 205 206 * The hotkey popup has been extended to support Firefox, Qutebrowser and TMUX 207 * Naughty (the notification system) has a new `ignore_suspend` flag 208 * The `textclock` widget now supports timezones 209 * New utility functions have been added: 210 * `gears.string.split` 211 * `gears.table.map` 212 * `gears.filesystem.make_parent_directories` 213 * New widget functions (moved out of the `gears` module): 214 * `wibox.widget.draw_to_cairo_context` 215 * `wibox.widget.draw_to_svg_file` 216 * `wibox.widget.draw_to_image_surface` 217 * Maximization requests from clients can now be intercepted using a 218 `request::geometry` signal handler. 219 * A new `wibox.layout.manual` layout has been added (see below) 220 * Two new `calendar` widgets have been added, a widget and a popup (see below) 221 * The `ratio` layout now supports various strategies to redistribute space 222 * The `stack` layout now supports offsets 223 * The notifications now have a `naughty.destroy_all_notifications()` function 224 * The `xresources` theme now supports the titlebar `hover` and `press` states 225 226The stack layout offsets: 227 228[](../classes/wibox.layout.stack.html) 229 230The ratio layout new full strategies: 231 232[](../classes/wibox.layout.ratio.html) 233 234The `manual` layout fixes a capability gap where hierarchical elements need to be 235placed manually. It has multiple modes including an `awful.placement` integration. 236 237[](../classes/wibox.layout.manual.html) 238 239The new calendar widgets are very flexible and can be themed down to the very small details: 240 241[](../classes/wibox.widget.calendar.html) 242[](../classes/wibox.widget.calendar.html) 243 244 245## Behavior changes 246 247 * The client `property::floating` is now also emitted when the floating 248 state changes implicitly, e.g. because the client gets maximized or 249 fullscreened. 250 * Building Awesome from its root source directory is no longer supported and 251 will print an error. 252 253<hr /> 254 255<a name="v41"></a> 256# Awesome window manager framework version 4.1 changes 257 258Awesome v4.1 is the first stable release for the Awesome 4.0 API. It adds 259non-breaking new features and fixes bugs. The main purpose of the release is to 260provide stability while also adding features submitted by our contributors. 261This release contains about 350 commits by 35 contributors, including many new 262developers. Thanks a lot. 263 264## New features 265 266The shape API has been extended to both client, notifications and wibox. 267 268[](../libraries/awful.prompt.html) 269 270The prompt now supports syntax highlight and more advanced key hooks. 271 272[](../libraries/awful.prompt.html) 273 274The prompt widget gained many new themes variables. 275 276[](../classes/wibox.layout.grid.html) 277 278There is a new 2D grid layout with rowspan and colspan support. 279 280[](../classes/awful.widget.only_on_screen.html) 281 282There is a new `awful.widget.only_on_screen` container to make it easier to 283share wiboxes across multiple screens. 284 285Various documentation improvements. Thanks for the feedbacks. 286 287The `awful.widget.taglist` now has `volatile` theme variables. 288 289There is now extra environment variables such as `AWESOME_ICON_PATH` and 290`AWESOME_THEMES_PATH` for those who prefer not installing Awesome. 291 292Dynamic "C" Lua libraries are now detected like pure Lua ones. 293 294`gears.timer` gained many new constructor arguments to make it easier to use. 295 296[Input shape](https://awesomewm.org/apidoc/classes/wibox.html#wibox.shape_input) 297mask are now supported. It is possible to create a wibox with passthough inputs. 298 299There is a new `awful.widget.clienticon` widget capable of fetching icons of 300different sizes. 301 302## New theme variables 303 304This release adds a ton of new theme variables to make Awesome prettier. We also 305thank all users who [submitted screenshot](https://github.com/awesomeWM/awesome/issues/1395). 306 307 theme.arcchart_thickness 308 theme.enable_spawn_cursor 309 theme.fullscreen_hide_border 310 theme.hotkeys_bg 311 theme.hotkeys_border_colo 312 theme.hotkeys_border_width 313 theme.hotkeys_description_font 314 theme.hotkeys_fg 315 theme.hotkeys_font 316 theme.hotkeys_group_margin 317 theme.hotkeys_label_bg 318 theme.hotkeys_label_fg 319 theme.hotkeys_modifiers_fg 320 theme.hotkeys_shape 321 theme.maximized_honor_padding 322 theme.notification_bg 323 theme.notification_border_color 324 theme.notification_border_width 325 theme.notification_fg 326 theme.notification_font 327 theme.notification_height 328 theme.notification_margin 329 theme.notification_opacity 330 theme.notification_shape 331 theme.notification_width 332 theme.prompt_bg_cursor 333 theme.prompt_bg 334 theme.prompt_fg_cursor 335 theme.prompt_fg 336 theme.prompt_font 337 theme.taglist_bg_volatile 338 theme.taglist_fg_volatile 339 theme.taglist_shape_border_color_volatile 340 theme.taglist_shape_border_width_volatile 341 theme.taglist_shape_volatile 342 theme.taglist_spacing 343 theme.tasklist_disable_icon 344 theme.tasklist_disable_task_name 345 theme.titlebar_close_button_focus_hover 346 theme.titlebar_close_button_focus_press 347 theme.titlebar_close_button_normal_hover 348 theme.titlebar_close_button_normal_press 349 theme.titlebar_floating_button_focus_active_hover 350 theme.titlebar_floating_button_focus_active_press 351 theme.titlebar_floating_button_focus_inactive_hover 352 theme.titlebar_floating_button_focus_inactive_press 353 theme.titlebar_floating_button_normal_active_hover 354 theme.titlebar_floating_button_normal_active_press 355 theme.titlebar_floating_button_normal_inactive_hover 356 theme.titlebar_floating_button_normal_inactive_press 357 theme.titlebar_maximized_button_focus_active_hover 358 theme.titlebar_maximized_button_focus_active_press 359 theme.titlebar_maximized_button_focus_inactive_hover 360 theme.titlebar_maximized_button_focus_inactive_press 361 theme.titlebar_maximized_button_normal_active_hover 362 theme.titlebar_maximized_button_normal_active_press 363 theme.titlebar_maximized_button_normal_inactive_hover 364 theme.titlebar_maximized_button_normal_inactive_press 365 theme.titlebar_minimize_button_focus_hover 366 theme.titlebar_minimize_button_focus_press 367 theme.titlebar_minimize_button_normal_hover 368 theme.titlebar_minimize_button_normal_press 369 theme.titlebar_ontop_button_focus_active_hover 370 theme.titlebar_ontop_button_focus_active_press 371 theme.titlebar_ontop_button_focus_inactive_hover 372 theme.titlebar_ontop_button_focus_inactive_press 373 theme.titlebar_ontop_button_normal_active_hover 374 theme.titlebar_ontop_button_normal_active_press 375 theme.titlebar_ontop_button_normal_inactive_hover 376 theme.titlebar_ontop_button_normal_inactive_press 377 theme.titlebar_sticky_button_focus_active_hover 378 theme.titlebar_sticky_button_focus_active_press 379 theme.titlebar_sticky_button_focus_inactive_hover 380 theme.titlebar_sticky_button_focus_inactive_press 381 theme.titlebar_sticky_button_normal_active_hover 382 theme.titlebar_sticky_button_normal_active_press 383 theme.titlebar_sticky_button_normal_inactive_hover 384 theme.titlebar_sticky_button_normal_inactive_press 385 theme.wibar_bgimage 386 theme.wibar_bg 387 theme.wibar_border_color 388 theme.wibar_border_width 389 theme.wibar_cursor 390 theme.wibar_fg 391 theme.wibar_height 392 theme.wibar_ontop 393 theme.wibar_opacity 394 theme.wibar_shape 395 theme.wibar_stretch 396 theme.wibar_type 397 theme.wibar_width 398 399## Noteworthy fixes 400 401 * Some applications such as VLC and Terminator had large unpainted areas 402 * The magnifier layout has been fixed 403 * Un-maximization misbehaved 404 * Docking area is now per-tag again 405 * CMake missing dependencies detection is fixed 406 * Support for FreeBSD and OpenBSD have been restored. 407 * Dialog and transient window can be moved to other screens again 408 * The fallback mode (when Awesome fails to load `rc.lua`) is now more robust 409 410## Behavior changes 411 412This is a stable release and we tried to minimize any upgrade impact. However 413various bugfixes induced minor, not noticeable, changes: 414 415 * HiDPI support fix changed the default theme "taglist square". This is only 416 true if the original theme file is used (not a copy). 417 * Maximization now honor the screen padding. There is an option to restore the 418 previous behavior. 419 * Un-maximized clients are now restored to their current screen instead of the 420 screen where they were maximized. 421 * Hotkey popup no longer enable the Vim module by default due to user 422 complaints 423 424`awful.util` has been split into multiple modules in the `gears` library to 425reduce the dependency graph. This allows for better unit testing. `awful.util` 426will be deprecated in Awesome v5. For now, it is still safe to use it. However, 427new code should use the functions from `gears` instead of `awful.util`. 428 429## Other 430 431 * The minimal LGI version is now 0.8.0. It was found that Awesome 4.0 also had 432 an issue in the menubar module when used with 0.7.3. 433 * GTK+3 is now required to run the integration tests. 434 435<hr /> 436 437<a name="v4"></a> 438# Awesome window manager framework version 4.0 changes 439 440 441Awesome 4.0 is the first release of the v4 API level, breaking the proven 442v3.5 API level after 4 years. This requires to port the existing user 443configuration and extensions to the new API. 444 445This document offers an overview of the new features and required changes for 446existing users. 447 448## New features 449 450### Input 451 452#### Mouse move and resize handlers 453 454The code used to resize and move clients has been refactored to allow plugins 455to be attached. This includes: 456 457* display the client geometry in the wibar 458* implement a resize grid 459* implement delayed resizing (like Windows 3.11 and TWM) 460* have touch-friendly resize handles (implemented by the Collision extension) 461* allow window snapping (implemented) 462* allow edge tiling (like Windows 7+ (AeroSnap) , KDE and Gnome) (implemented) 463* move to the next tag when dragged to the edge (like KDE3) (disabled by default) 464 465**See:** 466 467* `mouse` 468* `client` `request::geometry` 469 470. 471 472##### Edge tiling (AeroSnap) 473 474Clients are now resized when dragged to the screen edge similar to other window 475managers. The width of the border can be controlled by the 476`beautiful.snap_border_width` theme variable. The edge shape with 477`beautiful.snap_shape` (see `gears.shape`) and can be disabled by setting 478 479 awful.mouse.snap.edge_enabled = false 480 481##### Edge snapping 482 483While this was already supported, this feature has been extensively extended. 484It can be disabled by setting 485 486 awful.mouse.snap.client_enabled = false 487 488#### Hotkey popup 489 490It is now possible to display the list of active keyboard shortcuts by pressing 491`mod4 + s` (`hotkeys_popup.show_help`). 492 493 494**See:** 495 496* `awful.hotkeys_popup` 497* `awful.hotkeys_popup.keys` 498* `awful.hotkeys_popup.keys.vim` 499* `awful.hotkeys_popup.widget` 500 501### New tag and layout properties 502 503[](../classes/tag.html) 504 505#### Generic useless gap 506 507Adds an empty space between clients. 508 509**See:** 510 511* `tag` 512* `tag.gap` 513* `tag.gap_single_client` 514 515#### Master fill policies 516 517Allows the layout to optionally take all the space when there is no "slave" 518client or to use a smaller screen area. For example, if only one terminal is 519present in a `awful.layout.suit.tile.left` layout, then instead of filling the 520whole screen, it wont be larger than it would otherwise be if there were more 521clients. 522 523**See:** 524 525* `tag` 526* `tag.master_fill_policy` 527 528#### Volatile 529 530Tags can now be `volatile`. A volatile tag will be destroyed when its last 531client has been untagged. This is useful for temporary layouts or tags 532dedicated to a single client. 533 534**See:** 535 536* `tag.volatile` 537 538#### The corner layout 539 540A new client layout with a larger master client and both a vertical and an 541horizontal row of slave clients. 542 543### New client properties 544 545* `client.focusable` is now read/write (compared to read only in the previous 546 versions) 547* `client.valid` tells if the client still really exist or if the object is waiting to 548 be deleted 549* `client.floating` is now a client property 550* `client.x` / `client.y` / `client.width` / `client.height` are 551 `client.geometry` aliases 552* `client.first_tag` is a convenience wrapper for `c:tags()[1]` 553 554#### Client signaling 555 556There is now an `awesome.unix_signal` signal table with all platform specific 557signals and their indices. There is also an `awesome.kill()` function to send 558signals to clients. This can be used, among other thing, to pause and resume 559clients. 560 561### New client rules (`awful.rules`) 562 563All of the new client properties can be used in rules. In addition, the 564following ones have been added: 565 566* `placement`: use the `awful.placement` method (or combinations) to place the 567 client. While older version of Awesome allowed to use callbacks here, it 568 didn't support all corner cases such as titlebar offsets and border_width. 569* `titlebars_enabled`: older versions of Awesome had a global variable to 570 enable or disable titlebars. This is now delegated to the rules. 571* `new_tag`: allows to create a tag for the client instead of using an existing 572 one. 573* The `tag` property has been expanded to also find tags from their name. 574* The `tags` property now tries to merge the current tags into the array to fix 575 some other properties. 576* All geometry properties are now executed at once to avoid side effects. 577* The `focus` is now going through the focus filters instead of being applied 578 as-is (see the focus filter section). 579 580#### User rules 581 582It is now possible to register new rules by adding them to some `awful.rules` 583arrays. This can be used by modules to add extra functionalities or to avoid 584boilerplate code in callbacks. 585 586* `awful.rules.high_priority_properties`: before most other rules are executed. 587* `awful.rules.extra_properties`: together with normal rules. 588* `awful.rules.delayed_properties`: after most other rules, but before `focus`. 589 590Those extra rules also have the capability to mutate the current rule array. 591 592### New widgets 593 594#### Widgets 595 596<table class='widget_list' border=1> 597 <tr style='font-weight: bold;'> 598 <th align='center'>Name</th> 599 <th align='center'>Example</th> 600 </tr> 601<tr> 602 <td> 603 <a href='../classes/wibox.widget.checkbox.html'>wibox.widget.checkbox</a> 604 </td> 605 <td><img src='../images/AUTOGEN_wibox_widget_defaults_checkbox.svg' /></td> 606</tr> 607<tr> 608 <td> 609 <a href='../classes/wibox.widget.piechart.html'>wibox.widget.piechart</a> 610 </td> 611 <td><img src='../images/AUTOGEN_wibox_widget_defaults_piechart.svg' /></td> 612</tr> 613<tr> 614 <td> 615 <a href='../classes/wibox.widget.progressbar.html'>wibox.widget.progressbar</a> 616 </td> 617 <td><img src='../images/AUTOGEN_wibox_widget_defaults_progressbar.svg' /></td> 618</tr> 619<tr> 620 <td> 621 <a href='../classes/wibox.widget.slider.html'>wibox.widget.slider</a> 622 </td> 623 <td><img src='../images/AUTOGEN_wibox_widget_defaults_slider.svg' /></td> 624</tr> 625</table> 626 627#### Containers 628 629<table class='widget_list' border=1> 630 <tr style='font-weight: bold;'> 631 <th align='center'>Name</th> 632 <th align='center'>Example</th> 633 </tr> 634<tr> 635 <td> 636 <a href='../classes/wibox.container.arcchart.html'>wibox.container.arcchart</a> 637 </td> 638 <td><img src='../images/AUTOGEN_wibox_container_defaults_arcchart.svg' /></td> 639</tr> 640<tr> 641 <td> 642 <a href='../classes/wibox.container.radialprogressbar.html'>wibox.container.radialprogressbar</a> 643 </td> 644 <td><img src='../images/AUTOGEN_wibox_container_defaults_radialprogressbar.svg' /></td> 645</tr> 646 647</table> 648 649#### Layouts 650 651<table class='widget_list' border=1> 652 <tr style='font-weight: bold;'> 653 <th align='center'>Name</th> 654 <th align='center'>Example</th> 655 </tr> 656<tr> 657 <td> 658 <a href='../classes/wibox.layout.ratio.html'>wibox.layout.ratio</a> 659 </td> 660 <td><img src='../images/AUTOGEN_wibox_layout_defaults_ratio.svg' /></td> 661</tr> 662<tr> 663 <td> 664 <a href='../classes/wibox.layout.stack.html'>wibox.layout.stack</a> 665 </td> 666 <td><img src='../images/AUTOGEN_wibox_layout_defaults_stack.svg' /></td> 667</tr> 668</table> 669 670Other widgets, like the `taglist` and `tasklist`, gained many new 671configuration features such as empty colors and shape. 672 673**See:** 674 675* <a href="./03-declarative-layout.md.html">The declarative layout system</a> 676* `awful.widget.tasklist` 677* `awful.widget.taglist` 678 679### New APIs 680 681#### The new and streamlined property system 682 683Previously some core objects, such as clients or tags, were static. It wasn't 684possible to directly set new properties on them. This is now supported: 685 686 c.my_new_property = "bar" 687 688Also all properties previously accessible from the `awful` module are now 689directly accessible on the object: 690 691 -- Before 692 awful.client.floating.set(c, true) 693 694 -- Now 695 c.floating = true 696 697See the "deprecated" section below for the list of functions that have been 698replaced by properties or methods. 699 700The widgets API also received a similar overhaul. Both getters/setters and 701the property APIs are now supported. 702 703 -- Before 704 mytextbox:set_text("Foobar") 705 myimagebox:set_resize(not myimagebox:get_resize()) 706 707 -- Now 708 mytextbox.text = "Foobar" 709 myimagebox.resize = not myimagebox.resize 710 711 712Awesome 4.0 restores a feature found in older versions of Awesome. 713All widgets now have properties again. While all `:set_foo(bar)` type accessors 714are still fully (and forever) supported, it is now possible to do `.foo = bar` 715and `obj.foo = not obj.foo` . This is supported for all official widgets, 716containers and layouts. 717 718#### Declarative widget syntax is supported again 719 720Awesome 4.0 re-introduces the declarative widget syntax. This feature was lost 721when Awesome 3.5 introduced the new (and much, much better) widget system. It 722is possible to do it again. 723 724**See:** 725 726* <a href="./03-declarative-layout.md.html">The declarative layout system</a> 727 728Most documentation examples have been adapted to use this syntax instead of the 729imperative one. Both syntaxes are fully supported. 730 731For example: 732 733 -- Imperative 734 local l = wibox.layout.fized.horizontal() 735 local i = wibox.widget.imagebox() 736 local t = wibox.widget.textbox() 737 738 i:set_image("/path/to/awesomeness.png") 739 t:set_text("is awesome") 740 741 l:add(i) 742 l:add(t) 743 744 -- Declarative 745 local l = wibox.layout { 746 { 747 image = "/path/to/awesomeness.png", 748 widget = wibox.widget.imagebox 749 }. 750 { 751 text = "is awesome", 752 widget = wibox.widget.textbox 753 }. 754 layout = wibox.layout.fized.horizontal 755 } 756 757 758#### The request API 759 760Awesome used to blindly allow requests from clients to steal focus or move 761them around. There are now handlers to block such requests. 762The `request::` API is also used internally in Awesome itself to make 763previously hard-coded behavior more flexible. 764 765* `request::activate`: When a client requests focus and/or being raised. 766* `request::geometry`: When a client requests a position. 767* `request::screen`: When a client needs a screen. 768* `request::select`: When a tag wants to be selected. 769* `request::tag`: When a client needs a tag. 770* `request::titlebars`: When a client needs a titlebar. 771* `request::urgent`: When a client requests attention. 772 773**See:** 774 775* `awful.ewmh.tag` 776* `awful.ewmh.geometry` 777* `awful.ewmh.activate` 778* `awful.ewmh.urgent` 779* awful.`mouse.resize_handler` 780 781The defaults handlers are mostly located in the `awful.ewmh` module and comply 782with what the specification defines. 783 784#### The placement API 785 786[](../libraries/awful.placement.html) 787 788While Awesome already had some basic placement function, the new API makes it 789possible to remove most hard-coded geometry handling code. From a user's point 790of view this API allows for rich floating window management using 791`awful.rules`. 792 793It provides generic placement functions that work with: 794 795* `client`s 796* `wibox`es 797* the `mouse` 798* anything with a `:geometry()` method 799 800**See:** 801 802* `awful.placement` 803 804#### The shape API 805 806[](../libraries/gears.shape.html) 807 808This new API allows nicer visuals and more complex themes. 809 810 811Also note that the client shape functionality was broken in 3.5 and has been 812fixed. 813**See:** 814 815* `gears.shape` 816 817#### The hierarchy API 818 819The widget framework now produces a persistent model of its content rather than 820a volatile one during the wibox drawing. This allows for better introspection 821into the widget tree. 822This model is now exposed through the `mouse::enter`, `mouse::press`, 823`mouse.current_widget` and other APIs. This tree model also includes various 824matrices to convert positions from the screen coordinates to the one of the 825widgets (think of scaling and rotations). 826 827This allows for interactive widgets such as a slider. 828 829**See:** 830 831* `wibox.hierarchy` 832* <a href="./04-new-widgets.md.html">Creating new widget</a> 833 834### New themes 835 836A new `xresources` theme has been added. It uses native X11 assets such as 837colors. 838 839The default theme was improved with a more modern looking icon set. 840 841### Spawn and launcher improvements 842 843#### Spawn 844 845The newly renamed `awful.spawn` (previously `awful.util.spawn`) has been 846extended into a whole API. It is now possible to define rules directly through 847the spawn function. 848Note that this only works if the client properly supports the freedesktop.org 849startup notifications protocol. For example, to open a new `urxvt` in a new tag 850from the command line, use: 851 852 853 awesome-client "require('awful.spawn')('urxvt', {new_tag=true})" 854 855 856As another example, to launch a centered floating terminal in the currently 857selected tag of screen number 2: 858 859 860 awful.spawn("urxvt", { 861 tag = screen[2].selected_tag, 862 placement = awful.placement.centered, 863 floating = true 864 }) 865 866**See:** 867 868* `awful.spawn` 869* `awful.rules` 870 871All rule properties can be used, including the newly introduced placement ones 872(like above). 873 874#### Launcher 875 876`awful.prompt` gained many new features. One of them is the ability to add 877custom keyboard shortcuts and mutate the command. 878Paired with the new spawn features, it can be used to create `mod4 + r` 879shortcuts to spawn the clients with arguments and callbacks. 880 881**See:** 882 883* `awful.prompt` 884 885### Focus stealing filters. 886 887It is now possible to add and manage filters to restrict what kind of focus 888stealing is allowed. It can be used to mute noisy applications or to implement 889tag level policies. 890Every way a client could claim focus, including those from within Awesome 891itself, now goes through the request filters. 892 893**See:** 894 895* `awful.ewmh.add_activate_filter` 896* `awful.ewmh.remove_activate_filter` 897* `awful.ewmh.activate` 898 899### Notification actions 900 901Awesome now supports XDG notification (aka, naughty) actions. 902 903**See:** 904 905* `naughty` 906 907### Custom xproperties support 908 909Awesome can now save some data in the X11 server itself. This allows to 910communicate with external applications or so save state across restarts. 911 912There is also supported/used for persistent client properties. 913 914### Better XKB keyboard layout support 915 916Awesome now has native support for keyboard layout detection and setting. Using 917`setxkbmap` to track the current layout is no longer necessary. This also 918includes a widget to view the current layout. 919 920**See:** 921 922* `awesome.xkb_set_layout_group` 923* `awesome.xkb_get_layout_group` 924* `awesome.xkb_get_group_names` 925* `wibox.widget.keyboardlayout` 926 927### Other minor features 928 929* `awesome.composite_manager_running` allows to detect if a compositor is 930 running 931* a new `--replace` command line option is available (similar to other window 932 managers) 933* clients now have an unified `maximized` property additionally to only 934 _horizontal and _vertical 935* `awful.layout.layouts` is now where the client layout array is stored 936* the `systray` elements order can be reversed and spacing can be added 937* it is now possible to get the layout of unselected tags (use with caution) 938* tags can be swapped, former XMonad users with multiple screens can rejoice 939* whole screens can now be swapped 940* virtual screens can be created, moved and resized 941* paths can be added to Lua's search path via the `--search` argument 942* RandR 1.5 MONITOR support 943* access to the X resource management database 944* titlebars are now controlled using `awful.rules` and enabled by default 945* `awesome-client` now supports Lua code as its first argument (instead of 946 reading from stdin) 947* preferred client icon size can now be configured (see 948 `awesome.set_preferred_icon_size`) 949* there is now an `awesome.startup_errors` string with the startup error (if 950 any) 951* Initial support for HiDPI monitors / different DPI per screen 952* early support for stateful client layouts 953* the `--version` command line option now provides more details and system 954 information 955 956## Breaking changes 957 958Awesome 4.0 is a major release. 959As with all other major release, the API was broken to accommodate for new 960capabilities. It isn't as different as 3.5 was from 3.4 however. 961Many changes now cause a deprecation warning instead of breaking hard. 962However, it is important to take note of these changes in order to avoid new 963bugs. 964 965Also see the <a href="17-porting-tips.md.html#v4">tips for porting your 966configuration</a>. 967 968### There can be off-screen clients unless rc.lua is adapted 969 970 971**To fix from bash/zsh without a config change:** 972 973 echo 'for _,c in ipairs(client.get()) do require("awful.placement").no_offscreen(c) end' | awesome-client 974 975And add the following to the global rc.lua `awful.rule` section: 976 977 placement = awful.placement.no_overlap+awful.placement.no_offscreen 978 979Also note that this is the new official syntax for placement functions in 980rules. It is recommended to remove existing ones that are used as callbacks and 981move them to the `placement` rule property. 982 983**See:** 984 985* `awful.placement` 986* `awful.placement.no_overlap` 987* `awful.placement.no_offscreen` 988* `awful.rules` 989 990### Screens are no longer static 991 992Replace rc.lua `for s=1, screen.count() do` with 993`awful.screen.connect_for_each_screen(function(s)` and add a `)` after the 994section `end`. 995All global widget tables should be adapted to avoid memory leaks. 996Static code should not use `screen.count()` anymore. It should also always use 997the screen object, as the integer representation is mostly deprecated. 998 999**See:** 1000 1001* `screen` 1002* `screen.connect_for_each_screen` 1003* `screen.disconnect_for_each_screen` 1004 1005### Screens are now objects 1006 1007Previously: `type(s) == "number"`, now: `type(s) == "screen"`. 1008Doing `screen[1].geometry` is now partially deprecated and will probably print 1009a warning in future versions. Any code comparing number and screen objects is 1010now broken. Use screen objects instead of numbers. 1011 1012**See:** 1013 1014* `screen` 1015 1016### Awesome no longer restarts when a new screen is added 1017 1018By default, `rc.lua` now handles screen changes without restarting. 1019It allows to preserve the tag and layout state across changes. Old `rc.lua` can 1020either be ported to handle this by taking clues from the new `rc.lua` or 1021restore the old behavior by adding the following at the end: 1022 1023 screen.connect_signal("list", awesome.restart) 1024 1025**See:** 1026 1027* `screen` 1028* `screen.list` 1029 1030 1031### Widgets' `:fit()` and `:draw()` methods signature changed and `:layout()` is mandatory for layouts and containers 1032 1033All custom widgets need to change their function signature. 1034 1035### The "align" layout default behavior changes 1036 1037There is a new "strategy" property to define how the space is distributed. 1038 1039### Many APIs are deprecated, fix them before they turn into errors 1040 1041For example, instead of `awful.tag.viewonly(t)`, the recommended API is now 1042`t:view_only()`. The whole API has been standardized around this object 1043oriented notation. The warnings will be printed on stderr. 1044 1045### Most widgets' private APIs have changed 1046 1047You should not use undocumented APIs. Those can change at any time, and this 1048is no exception. The private API of all widgets has been broken. 1049 1050### Spawn changes 1051 1052* It has been moved into its own module (`awful.spawn`). 1053* Some methods have been deprecated. It is not recommended to use blocking 1054 methods in Awesome. We made sure to make your life harder if you wish to 1055 ignore this warning. 1056 Really, using blocking calls in rc.lua has very nasty side effects. 1057 1058 1059**See:** 1060 1061* `awful.spawn` 1062 1063### Prompt changes 1064 1065Most arguments have been deprecated, they are now taken from the `args` 1066argument-by-name table. This was done because the number of optional arguments 1067was getting out of control. 1068 1069 1070**See:** 1071 1072* `awful.prompt.run` 1073 1074### Timers are no longer part of the C API 1075 1076Use `gears.timer`. 1077 1078### Deprecated functions 1079 1080The previous Awesome API mixed different conventions. There was a major 1081undertaking in 4.0 to make the API coherent and well documented. 1082 1083Those functions have been renamed or converted to methods: 1084 1085* awful.`client.jumpto` 1086* awful.`client.visible` 1087* awful.`client.tiled` 1088* awful.`client.moveresize` 1089* awful.`client.movetotag` 1090* awful.`client.toggletag` 1091* awful.`client.movetoscreen` 1092* awful.`client.mark` 1093* awful.`client.unmark` 1094* awful.`client.ismarked` 1095* awful.`client.togglemarked` 1096* awful.`client.floating.set` 1097* awful.`client.isfixed` 1098* awful.`client.floating.get` 1099* awful.`client.floating.toggle` 1100* awful.`client.dockable.get` 1101* awful.`client.dockable.set` 1102* awful.`client.property.get` 1103* awful.`client.property.set` 1104* awful.`client.get_transient_for_matching` 1105* awful.`client.is_transient_for` 1106* awful.`mouse.client_under_pointer` 1107* awful.`mouse.client.dragtotag.border` 1108* awful.`mouse.client.corner` 1109* awful.`screen.getdistance_sq` 1110* awful.`screen.padding` 1111* awful.`tag.move` 1112* awful.`tag.swap` 1113* awful.`tag.delete` 1114* awful.`tag.gettags` 1115* awful.`tag.setscreen` 1116* awful.`tag.getscreen` 1117* awful.`tag.selectedlist` 1118* awful.`tag.selected` 1119* awful.`tag.setmwfact` 1120* awful.`tag.getmwfact` 1121* awful.`tag.setlayout` 1122* awful.`tag.setvolatile` 1123* awful.`tag.getvolatile` 1124* awful.`tag.setgap` 1125* awful.`tag.getgap` 1126* awful.`tag.setmfpol` 1127* awful.`tag.getmfpol` 1128* awful.`tag.setnmaster` 1129* awful.`tag.getnmaster` 1130* awful.`tag.seticon` 1131* awful.`tag.geticon` 1132* awful.`tag.setncol` 1133* awful.`tag.getncol` 1134* awful.`tag.getidx` 1135* awful.`tag.viewonly` 1136* awful.`tag.getdata` 1137* awful.`tag.getproperty` 1138* awful.`tag.setproperty` 1139* awful.`tag.withcurrent` 1140* `awful.util.get_rectangle_in_direction` 1141* `awful.wibox.get_position` 1142* `awful.wibox.set_position` 1143* `awful.wibox.attach` 1144* `awful.wibox.align` 1145* `awful.wibox.stretch` 1146* `awful.widget.progressbar.set_vertical` 1147* `awful.widget.progressbar.set_height` 1148* `awful.widget.progressbar.set_width` 1149 1150Note that for 4.0, only a warning will be printed if these functions are used. 1151They will eventually be removed. 1152 1153### Increased use of asynchronous programming 1154 1155Many operations, such as re-draw, re-layout, geometry changes and various C API 1156calls are now delayed to the end of the event loop iteration to avoid multiple 1157changes per iteration (to not waste CPU time). 1158The downside of this is that it is no longer reliable to assume the result of 1159the previous line of code being applied in the next already. 1160 1161### Startup handling 1162 1163There is no longer a "startup" argument to the client "manage" signal. If 1164Awesome is currently starting up, then `awesome.startup` is set to `true`. 1165 1166### Renamed modules 1167 1168Just as the functions above, many modules have been moved to follow a naming 1169convention. 1170Using the old name will print a warning and will alias into the new module. 1171Note that theses aliases are temporary and will be removed. 1172 1173* `awful.wibox` 1174* `awful.widget.graph` 1175* `awful.widget.progressbar` 1176* `awful.widget.textclock` 1177* `wibox.layout.constraint` 1178* `wibox.layout.margin` 1179* `wibox.layout.mirror` 1180* `wibox.layout.rotate` 1181* `wibox.layout.scroll` 1182* `wibox.widget.background` 1183 1184### The mouse finder module is gone 1185 1186It has been broken for ages, so we concluded nobody cared. 1187 1188### Menubar changes 1189 1190`menubar.menu_gen.generate` is now asynchronous and needs a callback as an 1191argument. 1192 1193### Rules execution order changes 1194 1195The order in which rules are executed changed. 1196It has been manually curated to avoid known race conditions between the rules 1197execution. For example, adding a titlebar after setting the position resulted 1198in an unwanted shift proportional to the titlebar size. 1199 1200This is regarded as a breaking changes since it impacts the behavior of 1201existing code, hopefully for the better. 1202 1203## Other 1204 1205### New dependencies 1206 1207Awesome now depends on Gio and a few other new packages since 3.5. 1208See the README for an extensive list. 1209 1210### A new documentation 1211 1212Awesome 4.0 now uses LDoc and MarkDown based documentation. We also introduced 1213official guides into our documentation: 1214 1215* <a href="./90-FAQ.md.html">FAQ</a> 1216* <a href="./02-contributing.md.html">Contributing</a> 1217* <a href="./03-declarative-layout.md.html">The declarative layout system</a> 1218* <a href="./04-new-widgets.md.html">Creating new widget</a> 1219* <a href="./05-awesomerc.md.html">Default configuration file documentation</a> 1220* <a href="./06-appearance.md.html">Change Awesome appearance</a> 1221* <a href="./16-using-cairo.md.html">Using Cairo and LGI</a> 1222 1223The new documentation is vastly superior to the previous one and includes 1224previously missing elements such as: 1225 1226* a hundred images (from zero) 1227* more than a hundred new code examples, most of them unit tested (from very, 1228 very few) 1229* all signals (previously partially documented in the wiki) 1230* all theme variables 1231* the object properties 1232* references throughout the documentation 1233* variable types (previously mostly undocumented) 1234* many auto-generated pages instead of manually curated (and out of date) ones 1235 1236### The old wiki is closing down 1237 1238We are moving to a 2 tier solution based on official (and curated) 1239documentation, and a Git based wiki solution. 1240The old wiki has been partially closed down for years due to spam issues and 1241given the API breakage in the past, a non-negligible percentage of the content 1242and tips were no longer working properly. 1243 1244### New website address 1245 1246The official website is now `https://awesomewm.org/` and is now hosted by 1247GitHub. This will allow to retire the former server. 1248 1249### Awesome is now developed on GitHub 1250 1251This isn't technically part of the release and has been true for years, but as 1252the first major releases since the move, it is a good time to point out that we 1253retired the old infrastructure. This includes the bug tracker, download, wiki, 1254website, repository and continuous integration system. 1255 1256This move increased our development velocity, number of contributor, 1257visibility count and reduced our infrastructure maintenance cost. 1258 1259### Test-driven development 1260 1261Awesome went from 0% to 75% unit test coverage. We now have 4 testing systems: 1262 1263* Linting (checks the code quality and consistency) 1264* Unit testing 1265* Documentation examples, documentation images and user interface appearance 1266 tests 1267* Integration tests 1268 1269We also have a test matrix for: 1270 1271* Different Lua versions 1272* Different screen resolutions 1273* Installation paths 1274* Dependencies versions 1275 1276### Packaging support 1277 1278Apart from the existing packages in distributions, Awesome users can now use 1279"make package" to generate .deb or .rpm instead of using `make install`. 1280
