Awesome 4.0 changelog

# Awesome window manager framework version 4.0 changes

Awesome 4.0 is the first release of the v4 API level. It is also the first new API level in 4 years. The v3.5 API level has proven itself very reliable and durable, but there is now enough major changes in the pipeline to warrant a new API level. As with every new major versions / APIs since the project was conceived, this includes the need to port existing user configuration and extensions to the new APIs. This document offer an overview of the new features and required changes for existing users.

## New features

### Inputs related

#### Mouse move and resize handlers

The code used to resize and move clients has been refectored to allow plugins to be attached. Such plugin can:

 * display the client geometry in the wibar 
 * implement a resize grid
 * implement delayed resizing (like Windows 3.11 and TWM)
 * touch friendly resize handles (implemented by the Collision extension)
 * allow window snapping (implemented)
 * allow edge tiling (like Windows 7+ (AeroSnap) , KDE and Gnome) (implemented)
 * move to the next tag when dragged to the edge (like KDE3) (disabled by default)

##### Edge tiling (AeroSnap)

Client are now resized when dragged to the screen edge similar to other window managers. The widget of the border can be controlled by the `beautiful.snap_border_width` theme variable. The edge shape by `beautiful.snap_shape` (see `gears.shape`) and can be disabled by setting `awful.mouse.snap.edge_enabled = false`

##### Edge snapping

While this was already supported, this feature has been extensively extended. It can be disabled by setting `awful.mouse.snap.client_enabled = false`.

#### Hotkey popup

It is now possible to display the list of active keyboard shortcuts by pressing `mod4+s`.

### New tag and layout properties

#### Generic useless gap

Add an empty space between clients.

#### Master fill policies

Tell the layout whether or not it should take all the space when there is no "slave" client or use a smaller screen area. 

#### Volatile

Tags can now be `volatile`. A volatile tag will be destroyed when its last client has been untagged. This is useful for temporary layouts or tags dedicated to a single client.

### New client properties
- `focusable` is now read/write (compared to read only in the previous versions)
- `valid` tell if the client still really exist or if the object is waiting to be deleted
- `floating` is now a client property
- `x`/`y`/`width`/`height` are `client.geometry` aliases
- `first_tag` is a convenience wrapper for `c:tags()[1]`

#### Client signaling

There is now an `awesome.unix_signal` signal table with all platform specific signals and their indices. There is also an `awesome.kill()` function to send signals to clients. This can be used, among other thing, to pause and resume clients.

### New client rules (`awful.rules`)

All of the new client properties can be used in rules. In addition, the following ones have been added:
- `placement`: Use `awful.placement` method (or combinasons) to place the client. While older version of Awesome allowed that using callbacks, it didn't support all corner cases such as titlebars offsets and border_width.
- `titlebars_enabled`: Older versions of Awesome had a global variables to enable or disable titlebars. This is now delegated to the rules.
- `new_tag` Allow creating a tag for the client instead of using an existing one.
- The `tag` property has been expanded to also find tags from their name
- The `tags` property now tries to merge the current tags into the array to fix some other properties
- All geometry properties are now execute at once to avoid side effects
- The `focus` is now going through the focus filters instead of being applied as-is (see the focus filter section)

Rules execution has been re-ordered to minimize the race conditions (one rule affecting the output of another). This may create a slightly different behavior for some users, but usually as in improvement.

#### User rules

It is now possible to register new rules by adding them to some `awful.rules` arrays. This can be used by modules to add extra functionalities or to avoid boiler plate code in callbacks.

 * `rules.high_priority_properties`: Before most rules are executed
 * `rules.extra_properties`: With normal rules
 * `rules.delayed_properties`: After most rules, but before `focus`

Those extra rules also have the capability to mutate the rule array.

### New widgets
- pie chart
- arc chart
- radial progressbar
- shaped progressbar
- bar graph
- ratio layout
- stack layout
- placement container
- shaped widget (in the background container)
- checkbox
- slider

Other widgets, such as the `taglist` and `tasklist`, gained many new configuration features such as empty colors and shape.

See http://new.awesomewm.org/apidoc/documentation/03-declarative-layout.md.html

### New APIs

#### The new and streamlined property system

Before, some core objects, such as clients or tags, were static. It wasn't possible to directly set new properties on them. It is now supported

```
c.my_new_property = "bar"
```

Also, all properties previously accessible from the `awful` module are now directly accessible on the object

``` lua
-- Before
awful.client.floating.set(c, true)

-- Now
c.floating = true
```

See the "deprecated" section below for the list of functions that have been replaced by properties or methods.

The widgets API also received a similar overhaul. Both getters/setters and property APIs are now supported.

```lua
-- Before
mytextbox:set_text("Foobar")
myimagebox:set_resize(not myimagebox:get_resize())

-- Now
mytextbox.text = "Foobar"
myimagebox.resize = not myimagebox.resize
```

Awesome 4.0 restore a feature found in older versions of Awesome. All widgets now have properties again. While all `:set_foo(bar)` type accessors are still fully (and forever) supported, it is now possible to do `.foo = bar` and `obj.foo = not obj.foo` . This is supported for all official widgets, containers and layouts.

#### Declarative widget syntax is supported again

Awesome 4.0 re-introduce the declarative widget syntax. This feature was lost when Awesome 3.5 introduced the new (and much, much better) widget system. It is possible to do it again.

http://new.awesomewm.org/apidoc/documentation/03-declarative-layout.md.html

Most documentation examples have been adapted to use this syntax instead of the imperative one. Both syntax are fully supported.

For example:

```lua

-- Imperative
local l = wibox.layout.fized.horizontal()
local i = wibox.widget.imagebox()
local t = wibox.widget.textbox()

i:set_image("/path/to/awesomeness.png")
t:set_text("is awesome")

l:add(i)
l:add(t)

-- Declarative
local l = wibox.layout {
     {
         image  = "/path/to/awesomeness.png",
         widget = wibox.widget.imagebox
     }.
     {
         text   = "is awesome",
         widget = wibox.widget.textbox
     }.
     layout = wibox.layout.fized.horizontal
}

```

#### The request API

Previously, Awesome blindly allowed request from clients to steal focus or move around. There is now handlers to block such request. The `request::` API is also used in Awesome itself to make previously hard-coded behavior more flexible.

* `request::activate`: When a client requests focus and/or being raised
* `request::geometry`:  When a client requests a position
* `request::screen`:  When a client needs a screen
* `request::select`:  When a tag wants to be selected
* `request::tag`:  When a client needs a tag
* `request::titlebars`: When a client needs a titlebar
* `request::urgent`: When a client requests attention

The defaults handlers are mostly located in the `awful.ewmh` module and comply with what the specification defines.

#### The placement API

While Awesome already had some basic placement function, the new API made possible to remove most hard-coded geometry handling code. From the user point of view, this API allow rich floating window management using `awful.rules`

http://new.awesomewm.org/apidoc/libraries/awful.placement.html

It provides generic placement functions that work with:
- clients
- wibox
- the mouse
- anything with a `:geometry()` method

#### The shape API

This new API allows nicer visuals and more complex themes.

http://new.awesomewm.org/apidoc/libraries/gears.shape.html

Also note that client shape was broken in 3.5 and has been fixed.

#### The hierarchy API

The widget framework now produce a persistent model of its content rather than a volatile one during the wibox drawing. This allows better introspection into the widget tree. This model is now exposed in the `mouse::enter`, `mouse::press`, `mouse.current_widget` and other APIs. This tree model also include various matrices to convert positions from the screen coordinates to the widget ones (think of scaling and rotations).

This allows interactive widgets such as the slider to be implemented.

### New themes

A new `xresources` has been added. It uses native X11 assets such as colors.

### Spawn and launcher improvements

#### Spawn

The newly renamed `awful.spawn` (previously `awful.util.spawn`) has been extended into a whole API. It is now possible to define rules directly into the spawn function. Note that this only work if the client properly support the freedesktop startup notification protocol. For example, to open a new `urxvt` in a new tag from the command line, use:

```
awesome-client  "require('awful.spawn')('urxvt', {new_tag=true})"
```

For example, to launch a centered floating terminal in the currently selected tag of screen number 2:

 ```
awful.spawn("urxvt", {
    tag       = screen[2].selected_tag,
    placement = awful.placement.centered,
    floating  = true
})
```

All rules properties can be used, including the newly introduced placement ones.

#### Launcher

`awful.prompt` gained many new features. One of them is the ability to add custom keyboard shortcuts and mutate the command. Paired with the new spawn features, it can be used to create `mod4+r` shortcuts to spawn the clients with arguments and callbacks.

### Focus stealing filters.

It is now possible to add and manage filters able to restrict the what kind of focus stealing is allowed. It can be used to mute noisy applications or implement tag level policies. Every way a client could claim focus, including those from within Awesome itself, now must go through the request filters.

### Notification actions

Awesome now support XDG notification (aka, naughty) actions.

### Custom xproperties support

Awesome can now save some data in the X11 server itself. This allows to communicate with external applications or so save state across restarts.

There is also support for persistent client properties.

### Better XKB keyboard layout support

Awesome now has native support for keyboard layout detection and setting. Using `setxkbmap` is no longer necessary. This also include a widget to view the current layout.

See:
- `awesome.xkb_set_layout_group`
- `awesome.xkb_get_layout_group`
- `awesome.xkb_get_group_names`
- `wibox.widget.keyboardlayout`

### Other minor features
- `awesome.composite_manager_running` allows to detect if a compositor is running
- a new `--replace` option is available (similar to other window managers) 
- clients now have an unified `maximized` property additionally to only _horizontal and _vertical
- `awful.layout.layouts` is now where the client layout array is stored
- The `systray` elements order can be reversed and spacing added
- It is now possible to get the layout of unselected tags (use with caution)
- tags can be swapped, former XMonad users with multiple screens can rejoice
- whole screens can now be swapped
- virtual screens can be created, moved and resized
- paths can be added to Lua's search path via the `--search` argument
- RandR 1.5 MONITOR support
- access to the X resource management database
- Titlebars are now controlled using `awful.rules` and enabled by default
- `awesome-client` now support lua code as its first argument (instead of reading from stdin)
- It is now possible to select the preferred client icon size (see `awesome.set_preferred_icon_size`)
- There is now an `awesome.startup_errors` string with the startup error (if any)
- Initial support for HiDPI monitors
- Early support for stateful client layouts
- `--version` now provides more details and system information

## Breaking changes

Awesome 4.0 is a major release, as with all other major release, we broke the API to accommodate the new capabilities. It isn't as different as 3.5 was from 3.4. Many changes now cause a deprecation warning instead of breaking your window manager. However, it is important to take note of these changes in order to avoid new bugs.

### There can be off-screen clients unless rc.lua is adapted

```
# To fix from bash/zsh without a config change
echo 'for _,c in ipairs(client.get()) do require("awful.placement").no_offscreen(c) end' | awesome-client
```

And add to the global rc.lua `awful.rule` section

```
 placement = awful.placement.no_overlap+awful.placement.no_offscreen
```

Also note that this is the new official syntax for placement functions in rules. It is recommended to remove existing ones that are used as callbacks and move them to the `placement` rule property.

### Screens are no longer static

Replace rc.lua `for s=1, screen.count() do` by `awful.screen.connect_for_each_screen(function(s)` and add a `)` after the section `end`. All global widget tables should be adapted to avoid memory leaks. Static code should not use `screen.count()` anymore. It should also always use the screen object, as the integer representation is mostly deprecated.

### Screen are now objects

Before `type(s) == "number"`, now `type(s) == "screen"`. Doing `screen[1].geometry` is now partially deprecated and will probably print a warning in future versions. Any code comparing number and screen objects is now broken. Use screen objects instead of number everywhere.

### Awesome no longer restart when a new screen is added

By default, `rc.lua` now handle screen changes without restart. It allows to preserve the tag and layout state across changes. Old `rc.lua` can either be ported to handle this by taking clues from the new `rc.lua` or restore the old behavior adding:

```
screen.connect("list", awesome.restart)
```

At the end of the config.

### Widgets `:fit()` and `:draw()` methods signature changed and `:layout()` is mandatory for layouts and containers

All custom widgets need to change their function signature.

### The "align" layout default behavior changes

There is a new "strategy" property to define how the space is distributed.

### Many APIs are deprecated, fix them before they turns into errors

For example, instead of `awful.tag.viewonly(t)`, the recommended API is now `t:view_only()`. The whole API has been standardized around this object oriented notation. The warnings will print on stderr.

### Most widgets private APIs have changed.

Users should not use undocumented APIs. Those can change at any time, and this is no exception. All widgets private API have been broken.

### Spawn changes
- It has been moved into its own module (`awful.spawn`)
- Some methods have been deprecated. It is not recommended to use blocking methods in Awesome. We made sure to make your life harder if you wish to ignore this warning. Really, using blocking calls in rc.lua have very nasty side effects.

### Prompt changes

Most arguments have been deprecated, they are now taken from the `args` argument-by-name table. This was done because the number of optional arguments was getting out of control.

### Timers are no longer part of the C API

Use `gears.timer`.

### Deprecated functions

Older Awesome API mixed different conventions. There was a major undertaking in 4.0 to make the API coherent and well documented. Those functions have been renamed or converted to methods:
- `awful.client.jumpto`
- `awful.client.visible`
- `awful.client.tiled`
- `awful.client.moveresize`
- `awful.client.movetotag`
- `awful.client.toggletag`
- `awful.client.movetoscreen`
- `awful.client.mark`
- `awful.client.unmark`
- `awful.client.ismarked`
- `awful.client.togglemarked`
- `awful.client.floating.set`
- `awful.client.isfixed`
- `awful.client.floating.get`
- `awful.client.floating.toggle`
- `awful.client.dockable.get`
- `awful.client.dockable.set`
- `awful.client.property.get`
- `awful.client.property.set`
- `awful.client.get_transient_for_matching`
- `awful.client.is_transient_for`
- `awful.mouse.client_under_pointer`
- `awful.mouse.client.dragtotag.border`
- `awful.mouse.client.corner`
- `awful.screen.getdistance_sq`
- `awful.screen.padding`
- `awful.tag.move`
- `awful.tag.swap`
- `awful.tag.delete`
- `awful.tag.gettags`
- `awful.tag.setscreen`
- `awful.tag.getscreen`
- `awful.tag.selectedlist`
- `awful.tag.selected`
- `awful.tag.setmwfact`
- `awful.tag.getmwfact`
- `awful.tag.setlayout`
- `awful.tag.setvolatile`
- `awful.tag.getvolatile`
- `awful.tag.setgap`
- `awful.tag.getgap`
- `awful.tag.setmfpol`
- `awful.tag.getmfpol`
- `awful.tag.setnmaster`
- `awful.tag.getnmaster`
- `awful.tag.seticon`
- `awful.tag.geticon`
- `awful.tag.setncol`
- `awful.tag.getncol`
- `awful.tag.getidx`
- `awful.tag.viewonly`
- `awful.tag.getdata`
- `awful.tag.getproperty`
- `awful.tag.setproperty`
- `awful.tag.withcurrent`
- `awful.util.get_rectangle_in_direction`
- `awful.wibox.get_position`
- `awful.wibox.set_position`
- `awful.wibox.attach`
- `awful.wibox.align`
- `awful.wibox.stretch`
- `awful.widget.progressbar.set_vertical`
- `awful.widget.progressbar.set_height`
- `awful.widget.progressbar.set_width`

Note that for 4.0, only a warning will be printed if these functions are used. They will eventually be removed.

### Increased use of asynchronous programming

Many operations, such as re-draw, re-layout, geometry changes and various C API calls are now delayed to end of the event loop iteration to avoid multiple changes per iteration (totally wasted CPU time). The downside of this is that it is no longer reliable to assume the result of the previous line of code is applied in the next.

### Startup handling

There is no longer a "startup" argument to the client "manage" signal. If Awesome is currently starting up, then `awesome.startup` is set to true.

### Renamed modules

Just as the functions above, many modules have been moved to follow a naming convention. Using the old name will print a warning and will alias into the new module. Note that theses aliases are temporary and will be removed.
- `awful.wibox`
- `awful.widget.graph`
- `awful.widget.progressbar`
- `awful.widget.textclock`
- `wibox.layout.constraint`
- `wibox.layout.margin`
- `wibox.layout.mirror`
- `wibox.layout.rotate`
- `wibox.layout.scroll`
- `wibox.widget.background`

### The mouse finder module is gone

It has been broken for ages, so we concluded nobody cared.

### Menubar changes

`menubar.menu_gen.generate` is now asynchronous and needs a callback as an argument.

### Rules execution order changes

The order in which rules are executed changed. It has been manually curated to avoid known race conditions between the rules execution. For example, adding a titlebar after setting the position resulted in an unwanted shift proportional to the titlebar size.

This is regarded as a breaking changes has it impacts the behavior of existing code, hopefully for the better.

## Other

### New dependencies

Awesome now depend on Gio and a few other new packages since 3.5 see the README for an extensive list.

### A new documentation

Awesome 4.0 now use LDoc and MarkDown based documentation. We also introduced official guides into our documentation such as

http://new.awesomewm.org/apidoc/documentation/03-declarative-layout.md.html

The new documentation is vastly superior to the previous one and include previously missing elements such as:
- A hundred images (from zero)
- More than a hundred new code examples, most of them unit tested (from very, very few)
- All signals (previously partially documented in the wiki)
- All theme variables
- The object properties
-  500+ references between parts of the documentation
- Variable types (previously mostly undocumented)
- Many auto-generated pages instead of manually curated (and out of date) ones

### The old wiki is closing down

We are moving to a 2 tier solution based on official (and curated) documented and git based wiki solution. The old wiki has been partially closed down for years due to spam issues and given Awesome API is broken in every major releases, a non-negligible percentage of the content and tips were no longer working.

### New website address

The official website is now `http://awesomewm.org/` and is now hosted by github. This will allow to retire the former server.

### Awesome is now developed on GitHub

This isn't technically part of the release and has been true for years, but as the first major releases since the move, it is a good time to point out that we retired the old infrastructure. This include the bug tracker, download, wiki, website, repository and continuous integration system.

This move increased our development velocity, contributor, visibility count and reduced our infrastructure maintenance cost.

### Test driven development

Awesome went from 0% to 75% unit test coverage. We now have 4 testing systems
- Linting (check the code quality and consistency)
- Unit testing
- Documentation examples, documentation images and user interface appearance tests
- Integration tests

We also have a test matrix for:
- Different lua versions
- Different resolution
- Installation paths
- Dependencies versions

### Packaging support

Awesome users can now use "make package" to generate .deb or .rpm instead of using make install.

TODO: Get rid of links to new.awesomewm.org