Module: `awful.titlebar`

Titlebars for awful.

Create a titlebar:

This example reproduces what the default rc.lua does. It shows how to handle the titlebars on a lower level.

Usage example

-- Create a titlebar for the client.
-- By default, ruled.client will create one, but all it does is to call this
-- function.
local top_titlebar = awful.titlebar(c, {
    size      = 20,
    bg_normal = "#ff0000",
})
-- buttons for the titlebar
local buttons = gears.table.join(
    awful.button({ }, 1, function()
        client.focus = c
        c:raise()
        awful.mouse.client.move(c)
    end),
    awful.button({ }, 3, function()
        client.focus = c
        c:raise()
        awful.mouse.client.resize(c)
    end)
)
top_titlebar : setup {
    { -- Left
        awful.titlebar.widget.iconwidget(c),
        buttons = buttons,
        layout  = wibox.layout.fixed.horizontal
    },
    { -- Middle
        { -- Title
            align  = "center",
            widget = awful.titlebar.widget.titlewidget(c)
        },
        buttons = buttons,
        layout  = wibox.layout.flex.horizontal
    },
    { -- Right
        awful.titlebar.widget.floatingbutton (c),
        awful.titlebar.widget.maximizedbutton(c),
        awful.titlebar.widget.stickybutton   (c),
        awful.titlebar.widget.ontopbutton    (c),
        awful.titlebar.widget.closebutton    (c),
        layout = wibox.layout.fixed.horizontal()
    },
    layout = wibox.layout.align.horizontal
}

Info:

Copyright: 2012 Uli Schlachter
Originally authored by: Uli Schlachter
(Full contributors list available on our github project)

Constructors

awful.titlebar (c[, args={}])	Create a new titlebar for the given client.
awful.titlebar.widget.titlewidget (c)	Create a new title widget.
awful.titlebar.widget.iconwidget (c)	Create a new icon widget.
awful.titlebar.widget.button (c, name, selector, action)	Create a new button widget.
awful.titlebar.widget.floatingbutton (c)	Create a new float button for a client.
awful.titlebar.widget.maximizedbutton (c)	Create a new maximize button for a client.
awful.titlebar.widget.minimizebutton (c)	Create a new minimize button for a client.
awful.titlebar.widget.closebutton (c)	Create a new closing button for a client.
awful.titlebar.widget.ontopbutton (c)	Create a new ontop button for a client.
awful.titlebar.widget.stickybutton (c)	Create a new sticky button for a client.

Static module functions

awful.titlebar.show (c[, position="top"])	Show the client’s titlebar.
awful.titlebar.hide (c[, position="top"])	Hide the client’s titlebar.
awful.titlebar.toggle (c[, position="top"])	Toggle the client’s titlebar, hiding it if it is visible, otherwise showing it.

Object methods

:setup {[args]}

Set a declarative widget hierarchy description.

Theme variables

beautiful.titlebar_fg_normal	color	The titlebar foreground (text) color.
beautiful.titlebar_bg_normal	color	The titlebar background color.
beautiful.titlebar_bgimage_normal	gears.surface or string	The titlebar background image image.
beautiful.titlebar_fg	color	The titlebar foreground (text) color.
beautiful.titlebar_bg	color	The titlebar background color.
beautiful.titlebar_bgimage	gears.surface or string	The titlebar background image image.
beautiful.titlebar_fg_focus	color	The focused titlebar foreground (text) color.
beautiful.titlebar_bg_focus	color	The focused titlebar background color.
beautiful.titlebar_bgimage_focus	gears.surface or string	The focused titlebar background image image.
beautiful.titlebar_fg_urgent	color	The urgent titlebar foreground (text) color.
beautiful.titlebar_bg_urgent	color	The urgent titlebar background color.
beautiful.titlebar_bgimage_urgent	gears.surface or string	The urgent titlebar background image image.
beautiful.titlebar_floating_button_normal	gears.surface or string	floating_button_normal.
beautiful.titlebar_maximized_button_normal	gears.surface or string	maximized_button_normal.
beautiful.titlebar_minimize_button_normal	gears.surface or string	minimize_button_normal.
beautiful.titlebar_minimize_button_normal_hover	gears.surface or string	minimize_button_normal_hover.
beautiful.titlebar_minimize_button_normal_press	gears.surface or string	minimize_button_normal_press.
beautiful.titlebar_close_button_normal	gears.surface or string	close_button_normal.
beautiful.titlebar_close_button_normal_hover	gears.surface or string	close_button_normal_hover.
beautiful.titlebar_close_button_normal_press	gears.surface or string	close_button_normal_press.
beautiful.titlebar_ontop_button_normal	gears.surface or string	ontop_button_normal.
beautiful.titlebar_sticky_button_normal	gears.surface or string	sticky_button_normal.
beautiful.titlebar_floating_button_focus	gears.surface or string	floating_button_focus.
beautiful.titlebar_maximized_button_focus	gears.surface or string	maximized_button_focus.
beautiful.titlebar_minimize_button_focus	gears.surface or string	minimize_button_focus.
beautiful.titlebar_minimize_button_focus_hover	gears.surface or string	minimize_button_focus_hover.
beautiful.titlebar_minimize_button_focus_press	gears.surface or string	minimize_button_focus_press.
beautiful.titlebar_close_button_focus	gears.surface or string	close_button_focus.
beautiful.titlebar_close_button_focus_hover	gears.surface or string	close_button_focus_hover.
beautiful.titlebar_close_button_focus_press	gears.surface or string	close_button_focus_press.
beautiful.titlebar_ontop_button_focus	gears.surface or string	ontop_button_focus.
beautiful.titlebar_sticky_button_focus	gears.surface or string	sticky_button_focus.
beautiful.titlebar_floating_button_normal_active	gears.surface or string	floating_button_normal_active.
beautiful.titlebar_floating_button_normal_active_hover	gears.surface or string	floating_button_normal_active_hover.
beautiful.titlebar_floating_button_normal_active_press	gears.surface or string	floating_button_normal_active_press.
beautiful.titlebar_maximized_button_normal_active	gears.surface or string	maximized_button_normal_active.
beautiful.titlebar_maximized_button_normal_active_hover	gears.surface or string	maximized_button_normal_active_hover.
beautiful.titlebar_maximized_button_normal_active_press	gears.surface or string	maximized_button_normal_active_press.
beautiful.titlebar_ontop_button_normal_active	gears.surface or string	ontop_button_normal_active.
beautiful.titlebar_ontop_button_normal_active_hover	gears.surface or string	ontop_button_normal_active_hover.
beautiful.titlebar_ontop_button_normal_active_press	gears.surface or string	ontop_button_normal_active_press.
beautiful.titlebar_sticky_button_normal_active	gears.surface or string	sticky_button_normal_active.
beautiful.titlebar_sticky_button_normal_active_hover	gears.surface or string	sticky_button_normal_active_hover.
beautiful.titlebar_sticky_button_normal_active_press	gears.surface or string	sticky_button_normal_active_press.
beautiful.titlebar_floating_button_focus_active	gears.surface or string	floating_button_focus_active.
beautiful.titlebar_floating_button_focus_active_hover	gears.surface or string	floating_button_focus_active_hover.
beautiful.titlebar_floating_button_focus_active_press	gears.surface or string	floating_button_focus_active_press.
beautiful.titlebar_maximized_button_focus_active	gears.surface or string	maximized_button_focus_active.
beautiful.titlebar_maximized_button_focus_active_hover	gears.surface or string	maximized_button_focus_active_hover.
beautiful.titlebar_maximized_button_focus_active_press	gears.surface or string	maximized_button_focus_active_press.
beautiful.titlebar_ontop_button_focus_active	gears.surface or string	ontop_button_focus_active.
beautiful.titlebar_ontop_button_focus_active_hover	gears.surface or string	ontop_button_focus_active_hover.
beautiful.titlebar_ontop_button_focus_active_press	gears.surface or string	ontop_button_focus_active_press.
beautiful.titlebar_sticky_button_focus_active	gears.surface or string	sticky_button_focus_active.
beautiful.titlebar_sticky_button_focus_active_hover	gears.surface or string	sticky_button_focus_active_hover.
beautiful.titlebar_sticky_button_focus_active_press	gears.surface or string	sticky_button_focus_active_press.
beautiful.titlebar_floating_button_normal_inactive	gears.surface or string	floating_button_normal_inactive.
beautiful.titlebar_floating_button_normal_inactive_hover	gears.surface or string	floating_button_normal_inactive_hover.
beautiful.titlebar_floating_button_normal_inactive_press	gears.surface or string	floating_button_normal_inactive_press.
beautiful.titlebar_maximized_button_normal_inactive	gears.surface or string	maximized_button_normal_inactive.
beautiful.titlebar_maximized_button_normal_inactive_hover	gears.surface or string	maximized_button_normal_inactive_hover.
beautiful.titlebar_maximized_button_normal_inactive_press	gears.surface or string	maximized_button_normal_inactive_press.
beautiful.titlebar_ontop_button_normal_inactive	gears.surface or string	ontop_button_normal_inactive.
beautiful.titlebar_ontop_button_normal_inactive_hover	gears.surface or string	ontop_button_normal_inactive_hover.
beautiful.titlebar_ontop_button_normal_inactive_press	gears.surface or string	ontop_button_normal_inactive_press.
beautiful.titlebar_sticky_button_normal_inactive	gears.surface or string	sticky_button_normal_inactive.
beautiful.titlebar_sticky_button_normal_inactive_hover	gears.surface or string	sticky_button_normal_inactive_hover.
beautiful.titlebar_sticky_button_normal_inactive_press	gears.surface or string	sticky_button_normal_inactive_press.
beautiful.titlebar_floating_button_focus_inactive	gears.surface or string	floating_button_focus_inactive.
beautiful.titlebar_floating_button_focus_inactive_hover	gears.surface or string	floating_button_focus_inactive_hover.
beautiful.titlebar_floating_button_focus_inactive_press	gears.surface or string	floating_button_focus_inactive_press.
beautiful.titlebar_maximized_button_focus_inactive	gears.surface or string	maximized_button_focus_inactive.
beautiful.titlebar_maximized_button_focus_inactive_hover	gears.surface or string	maximized_button_focus_inactive_hover.
beautiful.titlebar_maximized_button_focus_inactive_press	gears.surface or string	maximized_button_focus_inactive_press.
beautiful.titlebar_ontop_button_focus_inactive	gears.surface or string	ontop_button_focus_inactive.
beautiful.titlebar_ontop_button_focus_inactive_hover	gears.surface or string	ontop_button_focus_inactive_hover.
beautiful.titlebar_ontop_button_focus_inactive_press	gears.surface or string	ontop_button_focus_inactive_press.
beautiful.titlebar_sticky_button_focus_inactive	gears.surface or string	sticky_button_focus_inactive.
beautiful.titlebar_sticky_button_focus_inactive_hover	gears.surface or string	sticky_button_focus_inactive_hover.
beautiful.titlebar_sticky_button_focus_inactive_press	gears.surface or string	sticky_button_focus_inactive_press.

Fields

awful.titlebar.enable_tooltip	boolean	Show tooltips when hover on titlebar buttons.
awful.titlebar.fallback_name	string	Title to display if client name is not set.

Constructors

awful.titlebar (c[, args={}])

Create a new titlebar for the given client.

Every client can hold up to four titlebars, one for each side (i.e. each value of args.position).

If this constructor is called again with the same values for the client (c) and the titlebar position (args.position), the previous titlebar will be removed and replaced by the new one.

Usage example

 -- Create default titlebar
 awful.titlebar(c)
 -- Create titlebar on the client's bottom edge
 awful.titlebar(c, { position = "bottom" })
 -- Create titlebar with inverted colors
 awful.titlebar(c, { bg_normal = beautiful.fg_normal, fg_normal = beautiful.bg_normal })

Parameters:

c client The client the titlebar will be attached to.
args A table with extra arguments for the titlebar.
- size number The size of the titlebar. Will be interpreted as height for horizontal titlebars or as width for vertical titlebars. (default font.height*1.5)
- position string Possible values are "top", "left", "right" and "bottom". (default "top")
- bg_normal string (optional)
- bg_focus string (optional)
- bg_urgent string (optional)
- bgimage_normal string (optional)
- bgimage_focus string (optional)
- fg_normal string (optional)
- fg_focus string (optional)
- fg_urgent string (optional)
- font string (optional)

Returns:

wibox.drawable

awful.titlebar.widget.titlewidget (c)

Create a new title widget.

A title widget displays the name of a client. Please note that this returns a textbox and all of textbox' API is available. This way, you can e.g. modify the font that is used.

Parameters:

c The client for which a titlewidget should be created.

Returns:

The title widget.

awful.titlebar.widget.iconwidget (c)

Create a new icon widget.

An icon widget displays the icon of a client. Please note that this returns an imagebox and all of the imagebox' API is available. This way, you can e.g. disallow resizes.

Parameters:

c The client for which an icon widget should be created.

Returns:

The icon widget.

awful.titlebar.widget.button (c, name, selector, action)

Create a new button widget.

A button widget displays an image and reacts to mouse clicks. Please note that the caller has to make sure that this widget gets redrawn when needed by calling the returned widget’s :update() method. The selector function should return a value describing a state. If the value is a boolean, either "active" or "inactive" are used. The actual image is then found in the theme as titlebar_[name]_button_[normal/focus]_[state]. If that value does not exist, the focused state is ignored for the next try.

Parameters:

c The client for which a button is created.
name string Name of the button, used for accessing the theme and in the tooltip.
selector A function that selects the image that should be displayed.
action Function that is called when the button is clicked.

Returns:

The widget

awful.titlebar.widget.floatingbutton (c)

Create a new float button for a client.

Parameters:

c The client for which the button is wanted.

awful.titlebar.widget.maximizedbutton (c)

Create a new maximize button for a client.

Parameters:

c The client for which the button is wanted.

awful.titlebar.widget.minimizebutton (c)

Create a new minimize button for a client.

Parameters:

c The client for which the button is wanted.

awful.titlebar.widget.closebutton (c)

Create a new closing button for a client.

Parameters:

c The client for which the button is wanted.

awful.titlebar.widget.ontopbutton (c)

Create a new ontop button for a client.

Parameters:

c The client for which the button is wanted.

awful.titlebar.widget.stickybutton (c)

Create a new sticky button for a client.

Parameters:

c The client for which the button is wanted.

Static module functions

awful.titlebar.show (c[, position="top"]) · 1 permission

Show the client’s titlebar.

Parameters:

c The client whose titlebar is modified
position string The position of the titlebar. Must be one of "left", "right", "top", "bottom". (default "top")

Click to display more

Requested actions or permissions:

Class	Permission	Context	Default	Description
client	titlebars	show	granted	Called when awful.titlebar.show is called.

awful.titlebar.hide (c[, position="top"])

Hide the client’s titlebar.

Parameters:

c The client whose titlebar is modified
position string The position of the titlebar. Must be one of "left", "right", "top", "bottom". (default "top")

awful.titlebar.toggle (c[, position="top"]) · 1 permission

Toggle the client’s titlebar, hiding it if it is visible, otherwise showing it.

Parameters:

c The client whose titlebar is modified
position string The position of the titlebar. Must be one of "left", "right", "top", "bottom". (default "top")

Click to display more

Requested actions or permissions:

Class	Permission	Context	Default	Description
client	titlebars	toggle	granted	Called when awful.titlebar.toggle is called.

Object methods

:setup {[args]}

Set a declarative widget hierarchy description. See The declarative layout system

Parameters:

args An array containing the widgets disposition

Theme variables

beautiful.titlebar_fg_normal color

The titlebar foreground (text) color.

Fields

awful.titlebar.enable_tooltip boolean: Show tooltips when hover on titlebar buttons.
awful.titlebar.fallback_name string: Title to display if client name is not set.

awesome

Contents

Popups and bars

Core components

Input handling

Declarative rules

Widgets

Widget containers

Widget layouts

Utility libraries

Theme related libraries

Libraries

Sample files

Classes

Documentation

Module: awful.titlebar

Info:

Constructors

Static module functions

Object methods

Theme variables

Fields

Constructors

Parameters:

Returns:

Parameters:

Returns:

Parameters:

Returns:

Parameters:

Returns:

Parameters:

Parameters:

Parameters:

Parameters:

Parameters:

Parameters:

Static module functions

Parameters:

Requested actions or permissions:

Parameters:

Parameters:

Requested actions or permissions:

Object methods

Parameters:

Theme variables

See also:

See also:

See also:

See also:

See also:

See also:

See also:

See also:

See also:

See also:

See also:

See also:

See also:

See also:

See also:

See also:

See also:

See also:

See also:

See also:

See also:

See also:

See also:

See also:

See also:

See also:

See also:

See also:

See also:

See also:

See also:

See also:

See also:

See also:

Module: `awful.titlebar`