Class `tag`

awesome tag API

Furthermore to the classes described here, one can also use signals as described in signals.

Client geometry

Creating tags:

The default config initializes tags like this:

awful.tag(
  { "1", "2", "3", "4", "5", "6", "7", "8", "9" },
  s,
  awful.layout.layouts[1]
)

If you wish to have tags with different properties, then awful.tag.add is a better choice:

awful.tag.add("First tag", {
    icon               = "/path/to/icon1.png",
    layout             = awful.layout.suit.tile,
    master_fill_policy = "master_width_factor",
    gap_single_client  = true,
    gap                = 15,
    screen             = s,
    selected           = true,
})

awful.tag.add("Second tag", {
    icon = "/path/to/icon2.png",
    layout = awful.layout.suit.max,
    screen = s,
})

Note: the example above sets “First tag” to be selected explicitly, because otherwise you will find yourself without any selected tag.

Accessing tags:

To access the “current tags”, use

local tags = awful.screen.focused().selected_tags

See: awful.screen.focused

See: screen.selected_tags

To ignore the corner case where multiple tags are selected:

local t = awful.screen.focused().selected_tag

See: screen.selected_tag

To get all tags for the focused screen:

local tags = awful.screen.focused().tags

See: screen.tags

To get all tags:

local tags = root.tags()

To get the current tag of the focused client:

local t = client.focus and client.focus.first_tag or nil

See: client.focus See: client.first_tag

To get a tag from its name:

local t = awful.tag.find_by_name(awful.screen.focused(), "name")

Common shortcuts:

Here is a few useful shortcuts not part of the default rc.lua. Add these functions above – {{{ Key bindings:

Delete the current tag

local function delete_tag()
    local t = awful.screen.focused().selected_tag
    if not t then return end
    t:delete()
end

Create a new tag at the end of the list

local function add_tag()
    awful.tag.add("NewTag", {
        screen = awful.screen.focused(),
        layout = awful.layout.suit.floating }):view_only()
end

Rename the current tag

local function rename_tag()
    awful.prompt.run {
        prompt       = "New tag name: ",
        textbox      = awful.screen.focused().mypromptbox.widget,
        exe_callback = function(new_name)
            if not new_name or #new_name == 0 then return end

            local t = awful.screen.focused().selected_tag
            if t then
                t.name = new_name
            end
        end
    }
end

Move the focused client to a new tag

local function move_to_new_tag()
    local c = client.focus
    if not c then return end

    local t = awful.tag.add(c.class,{screen= c.screen })
    c:tags({t})
    t:view_only()
end

Copy the current tag at the end of the list

local function copy_tag()
    local t = awful.screen.focused().selected_tag
    if not t then return end

    local clients = t:clients()
    local t2 = awful.tag.add(t.name, awful.tag.getdata(t))
    t2:clients(clients)
    t2:view_only()
end

And, in the globalkeys table:

awful.key({ modkey,           }, "a", add_tag,
          {description = "add a tag", group = "tag"}),
awful.key({ modkey, "Shift"   }, "a", delete_tag,
          {description = "delete the current tag", group = "tag"}),
awful.key({ modkey, "Control"   }, "a", move_to_new_tag,
          {description = "add a tag with the focused client", group = "tag"}),
awful.key({ modkey, "Mod1"   }, "a", copy_tag,
          {description = "create a copy of the current tag", group = "tag"}),
awful.key({ modkey, "Shift"   }, "r", rename_tag,
          {description = "rename the current tag", group = "tag"}),

See the global keybindings for more information about the keybindings.

Some signal names are starting with a dot. These dots are artefacts from the documentation generation, you get the real signal name by removing the starting dot.

Info:

Copyright: 2008-2009 Julien Danjou
Author: Julien Danjou <[email protected]>

Functions

awful.tag.add (name, props)	Add a tag.
awful.tag.new (names, screen, layout)	Create a set of tags and attach it to a screen.
awful.tag.find_fallback (screen, invalids)	Find a suitable fallback tag.
awful.tag.history.update (obj)	Update the tag history.
awful.tag.history.restore (screen, idx)	Revert tag history.
awful.tag.incmwfact (add, t)	Increase master width factor.
awful.tag.incgap (add, t)	Increase the spacing between clients
awful.tag.togglemfpol (t)	Toggle size fill policy for the master client(s) between “expand” and “master_width_factor”.
awful.tag.incnmaster (add[, t[, sensible=false]])	Increase the number of master windows.
awful.tag.incncol (add[, t[, sensible=false]])	Increase number of column windows.
awful.tag.viewnone ([screen])	View no tag.
awful.tag.viewidx (i[, screen])	View a tag by its taglist index.
awful.tag.viewnext (screen)	View next tag.
awful.tag.viewprev (screen)	View previous tag.
awful.tag.viewmore (tags[, screen[, maximum=#tags]])	View only a set of tags.
awful.tag.viewtoggle (t)	Toggle selection of a tag
awful.tag.attached_connect_signal (screen[, signal[, Callback]])	Add a signal to all attached tags and all tags that will be attached in the future.

Object properties

name	Tag name.
selected	True if the tag is selected to be viewed.
activated	True if the tag is active and can be used.
index	The tag index.
screen	The tag screen.
master_width_factor	The tag master width factor.
layout	The tag client layout.
layouts	The (proposed) list of available layouts for this tag.
volatile	Define if the tag must be deleted when the last client is untagged.
gap	The gap (spacing, also called useless_gap) between clients.
gap_single_client	Enable gaps for a single client.
master_fill_policy	Set size fill policy for the master client(s).
master_count	Set the number of master windows.
icon	Set the tag icon.
column_count	Set the number of columns.

Signals

request::select
tagged	When a client gets tagged with this tag.
untagged	When a client gets untagged with this tag.
property::urgent	True when a tagged client is urgent
property::urgent_count	The number of urgent tagged clients
request::screen	Emitted when a screen is removed.
removal-pending	Emitted after request::screen if no new screen has been set.

Theme variables

beautiful.master_width_factor	The default master width factor
beautiful.useless_gap	The default gap.
beautiful.gap_single_client	Enable gaps for a single client.
beautiful.master_fill_policy	The default fill policy.
beautiful.master_count	The default number of master windows.
beautiful.column_count	The default number of columns.

Deprecated functions

awful.tag.move [deprecated]	Move a tag to an absolute position in the screen[]:tags() table.
awful.tag.swap [deprecated]	Swap 2 tags
awful.tag.delete [deprecated]	Delete a tag.
awful.tag.gettags [deprecated]	Get a list of all tags on a screen
awful.tag.setscreen [deprecated]	Set a tag’s screen
awful.tag.getscreen [deprecated]	Get a tag’s screen
awful.tag.selectedlist [deprecated]	Return a table with all visible tags
awful.tag.selected [deprecated]	Return only the first visible tag.
awful.tag.setmwfact [deprecated]	Set master width factor.
awful.tag.getmwfact [deprecated]	Get master width factor.
awful.tag.setlayout [deprecated]	Set layout.
awful.tag.setvolatile [deprecated]	Set if the tag must be deleted when the last client is untagged
awful.tag.getvolatile [deprecated]	Get if the tag must be deleted when the last client closes
awful.tag.setgap [deprecated]	Set the spacing between clients
awful.tag.getgap [deprecated]	Get the spacing between clients.
awful.tag.setmfpol [deprecated]	Set size fill policy for the master client(s)
awful.tag.getmfpol [deprecated]	Get size fill policy for the master client(s)
awful.tag.setnmaster [deprecated]
awful.tag.getnmaster [deprecated]	Get the number of master windows.
awful.tag.seticon [deprecated]	Set the tag icon
awful.tag.geticon [deprecated]	Get the tag icon
awful.tag.setncol [deprecated]	Set number of column windows.
awful.tag.getncol [deprecated]	Get number of column windows.
awful.tag.getidx [deprecated]	Get a tag’s index in the gettags() table.
awful.tag.viewonly [deprecated]	View only a tag.
awful.tag.getdata [deprecated]	Get tag data table.
awful.tag.getproperty [deprecated]	Get a tag property.
awful.tag.setproperty [deprecated]	Set a tag property.
awful.tag.withcurrent [deprecated]	Tag a client with the set of current tags.

Fields

awful.tag.history.limit	The number of elements kept in the history.
awful.tag.layouts	An ordered list of layouts.

Methods

tag:instances ()	Get the number of instances.
tag:clients (clients_table)	Get or set the clients attached to this tag.
tag:disconnect_signal (name, func)	Disconnect from a signal.
tag:emit_signal (name, ...)	Emit a signal.
tag:connect_signal (name, func)	Connect to a signal.
tag:swap (tag2)	Swap 2 tags
tag:delete ([fallback_tag=awful.tag.find_fallback()[, force=false]])	Delete a tag.
tag:find_by_name (s, name)	Find a tag by name.
tag:view_only ()	View only a tag.

Functions

Methods

awful.tag.add (name, props)

Add a tag.

This function allow to create tags from a set of properties:

local t = awful.tag.add("my new tag", {
    screen = screen.primary,
    layout = awful.layout.suit.max,
})

name The tag name, a string
props The tags inital properties, a table

Returns:

The created tag

Returns:

A table with all created tags.

awful.tag.find_fallback (screen, invalids)

Find a suitable fallback tag.

screen The screen to look for a tag on. [awful.screen.focused()]
invalids A table of tags we consider unacceptable. [selectedlist(scr)]

awful.tag.history.update (obj)

Update the tag history.

obj Screen object.

awful.tag.history.restore (screen, idx)

Revert tag history.

screen The screen.
idx Index in history. Defaults to “previous” which is a special index toggling between last two selected sets of tags. Number (eg 1) will go back to the given index in history.

awful.tag.incmwfact (add, t)

Increase master width factor.

add Value to add to master width factor.
t The tag to modify, if null tag.selected() is used.

Object properties

name

Tag name.

Signal:

property::name

Type:

string

selected

True if the tag is selected to be viewed.

Signal:

property::selected

Type:

boolean

activated

True if the tag is active and can be used.

Signal:

property::activated

Type:

boolean

index

The tag index.

The index is the position as shown in the awful.widget.taglist.

Signal:

property::index

Type:

integer

screen

The tag screen.

Signal:

property::screen

Type:

screen

Type:

number Between 0 and 1

Type:

layout layout or function A layout table or a constructor function

Type:

table

Type:

boolean

gap

The gap (spacing, also called useless_gap) between clients.

This property allow to waste space on the screen in the name of style, unicorns and readability.

Signal:

property::useless_gap

Type:

number The value has to be greater than zero.

Type:

boolean Enable gaps for a single client

master_fill_policy

Set size fill policy for the master client(s).

Possible values:

expand: Take all the space
master_width_factor: Only take the ratio defined by the master_width_factor

Signal:

property::master_fill_policy

Type:

string “expand” or “master_width_factor”

master_count

Set the number of master windows.

Signal:

property::nmaster (deprecated)
property::master_count

Type:

integer nmaster Only positive values are accepted

icon

Set the tag icon.

Signal:

property::icon

Type:

icon path or surface The icon

column_count

Set the number of columns.

Signal:

property::ncol (deprecated)
property::column_count

Type:

ncol integer Has to be greater than 1

Signals

request::select

tagged

When a client gets tagged with this tag.

Arguments:

c client.object The tagged client.

untagged

When a client gets untagged with this tag.

Arguments:

c client.object The untagged client.

property::urgent

True when a tagged client is urgent

Theme variables

beautiful.master_width_factor

The default master width factor

Type:

number (default: 0.5)

Type:

number (default: 0)

Type:

boolean (default: true)

Type:

string (default: “expand”)

Type:

integer (default: 1)

Type:

integer (default: 1)

Deprecated functions

awful.tag.move [deprecated]

Move a tag to an absolute position in the screen[]:tags() table.

param:

new_index Integer absolute position in the table to insert.
target_tag The tag that should be moved. If null, the currently selected tag is used.

param:

tag1 The first tag
tag2 The second tag

param:

target_tag Optional tag object to delete. [selected()]
fallback_tag Tag to assign stickied tags to. [~selected()]

param:

s screen Screen

param:

s Screen
t tag object

param:

t tag object (optional)

param:

s Screen.

param:

s Screen.

param:

mwfact Master width factor.
t The tag to modify, if null tag.selected() is used.

param:

t The tag. (optional)

param:

layout a layout table or a constructor function
t The tag to modify

param:

volatile boolean If the tag must be deleted when the last client is untagged
t The tag to modify, if null tag.selected() is used.

param:

t The tag to modify, if null tag.selected() is used.

param:

useless_gap The spacing between clients
t The tag to modify, if null tag.selected() is used.

param:

t tag The tag. (default tag.selected())
numclients int Number of (tiled) clients. Passing this will return 0 for a single client. You can override this function to change this behavior. (optional)

param:

policy string Can be set to “expand” (fill all the available workarea) or “master_width_factor” (fill only an area inside the master width factor)
t tag The tag to modify (default tag.selected())

param:

t tag The tag (default tag.selected())

param:

nmaster The number of master windows.
t The tag. (optional)

param:

t The tag. (optional)

param:

icon the icon to set, either path or image object
_tag the tag

param:

_tag the tag

param:

ncol The number of column.
t The tag to modify, if null tag.selected() is used.

param:

t The tag. (optional)

param:

query_tag The tag object to find. [selected()]

param:

t The tag object.

param:

_tag tag The tag.

awful.tag.getproperty [deprecated]

Get a tag property.

Use _tag.prop directly.

param:

_tag tag The tag.
prop string The property name.

awful.tag.setproperty [deprecated]

Set a tag property. This properties are internal to awful. Some are used to draw taglist, or to handle layout, etc.

Use _tag.prop = value

param:

_tag The tag.
prop The property name.
value The value.

awful.tag.withcurrent [deprecated]

Tag a client with the set of current tags.

param:

c The client to tag.

Fields

awful.tag.history.limit

The number of elements kept in the history.

limit integer (default 20)

awful.tag.layouts

An ordered list of layouts. awful.tag.layout Is usually defined in rc.lua. It store the list of layouts used when selecting the previous and next layouts. This is the default:

 -- Table of layouts to cover with awful.layout.inc, order matters.
 awful.layout.layouts = {
     awful.layout.suit.floating,
     awful.layout.suit.tile,
     awful.layout.suit.tile.left,
     awful.layout.suit.tile.bottom,
     awful.layout.suit.tile.top,
     awful.layout.suit.fair,
     awful.layout.suit.fair.horizontal,
     awful.layout.suit.spiral,
     awful.layout.suit.spiral.dwindle,
     awful.layout.suit.max,
     awful.layout.suit.max.fullscreen,
     awful.layout.suit.magnifier,
     awful.layout.suit.corner.nw,
     -- awful.layout.suit.corner.ne,
     -- awful.layout.suit.corner.sw,
     -- awful.layout.suit.corner.se,
 }

Methods

tag:instances ()

Get the number of instances.

Returns:

The number of tag objects alive.

tag:clients (clients_table)

Get or set the clients attached to this tag.

clients_table None or a table of clients to set as being tagged with this tag.

Returns:

A table with the clients attached to this tags.

tag:disconnect_signal (name, func)

Disconnect from a signal.

name string The name of the signal.
func function The callback that should be disconnected.

tag:emit_signal (name, ...)

Emit a signal.

name string The name of the signal.
... Extra arguments for the callback functions. Each connected function receives the object as first argument and then any extra arguments that are given to emit_signal().

tag:connect_signal (name, func)

Connect to a signal.

name string The name of the signal.
func function The callback to call when the signal is emitted.

tag:swap (tag2)

Swap 2 tags

tag2 The second tag

Returns:

Returns true if the tag is successfully deleted. If there are no clients exclusively on this tag then delete it. Any stickied clients are assigned to the optional ‘fallback_tag’. If after deleting the tag there is no selected tag, try and restore from history or select the first tag on the screen.

Returns:

nil

Usage:

-- For the current screen
local t = awful.tag.find_by_name(awful.screen.focused(), "name")

-- For a screen index
local t = awful.tag.find_by_name(screen[1], "name")

-- For all screens
local t = awful.tag.find_by_name(nil, "name")

tag:view_only ()

View only a tag.

awesome

Contents

Classes

Libraries

Sample files

Documentation

Class tag

Info:

Functions

Object properties

Signals

Theme variables

Deprecated functions

Fields

Methods

Functions

Returns:

See also:

Returns:

See also:

See also:

See also:

See also:

See also:

See also:

Object properties

Type:

Type:

Type:

Type:

Type:

See also:

Type:

See also:

Type:

See also:

Type:

See also:

Type:

Type:

See also:

Type:

Type:

Type:

Type:

Type:

Signals

Arguments:

Arguments:

See also:

See also:

Theme variables

Type:

See also:

Type:

See also:

Type:

See also:

Type:

See also:

Type:

See also:

Type:

See also:

Deprecated functions

param:

See also:

param:

See also:

param:

See also:

param:

See also:

param:

See also:

param:

See also:

param:

See also:

param:

Class `tag`