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	floatingbuttonnormal.
beautiful.titlebar_maximized_button_normal	gears.surface or string	maximizedbuttonnormal.
beautiful.titlebar_minimize_button_normal	gears.surface or string	minimizebuttonnormal.
beautiful.titlebar_minimize_button_normal_hover	gears.surface or string	minimizebuttonnormal_hover.
beautiful.titlebar_minimize_button_normal_press	gears.surface or string	minimizebuttonnormal_press.
beautiful.titlebar_close_button_normal	gears.surface or string	closebuttonnormal.
beautiful.titlebar_close_button_normal_hover	gears.surface or string	closebuttonnormal_hover.
beautiful.titlebar_close_button_normal_press	gears.surface or string	closebuttonnormal_press.
beautiful.titlebar_ontop_button_normal	gears.surface or string	ontopbuttonnormal.
beautiful.titlebar_sticky_button_normal	gears.surface or string	stickybuttonnormal.
beautiful.titlebar_floating_button_focus	gears.surface or string	floatingbuttonfocus.
beautiful.titlebar_maximized_button_focus	gears.surface or string	maximizedbuttonfocus.
beautiful.titlebar_minimize_button_focus	gears.surface or string	minimizebuttonfocus.
beautiful.titlebar_minimize_button_focus_hover	gears.surface or string	minimizebuttonfocus_hover.
beautiful.titlebar_minimize_button_focus_press	gears.surface or string	minimizebuttonfocus_press.
beautiful.titlebar_close_button_focus	gears.surface or string	closebuttonfocus.
beautiful.titlebar_close_button_focus_hover	gears.surface or string	closebuttonfocus_hover.
beautiful.titlebar_close_button_focus_press	gears.surface or string	closebuttonfocus_press.
beautiful.titlebar_ontop_button_focus	gears.surface or string	ontopbuttonfocus.
beautiful.titlebar_sticky_button_focus	gears.surface or string	stickybuttonfocus.
beautiful.titlebar_floating_button_normal_active	gears.surface or string	floatingbuttonnormal_active.
beautiful.titlebar_floating_button_normal_active_hover	gears.surface or string	floatingbuttonnormalactivehover.
beautiful.titlebar_floating_button_normal_active_press	gears.surface or string	floatingbuttonnormalactivepress.
beautiful.titlebar_maximized_button_normal_active	gears.surface or string	maximizedbuttonnormal_active.
beautiful.titlebar_maximized_button_normal_active_hover	gears.surface or string	maximizedbuttonnormalactivehover.
beautiful.titlebar_maximized_button_normal_active_press	gears.surface or string	maximizedbuttonnormalactivepress.
beautiful.titlebar_ontop_button_normal_active	gears.surface or string	ontopbuttonnormal_active.
beautiful.titlebar_ontop_button_normal_active_hover	gears.surface or string	ontopbuttonnormalactivehover.
beautiful.titlebar_ontop_button_normal_active_press	gears.surface or string	ontopbuttonnormalactivepress.
beautiful.titlebar_sticky_button_normal_active	gears.surface or string	stickybuttonnormal_active.
beautiful.titlebar_sticky_button_normal_active_hover	gears.surface or string	stickybuttonnormalactivehover.
beautiful.titlebar_sticky_button_normal_active_press	gears.surface or string	stickybuttonnormalactivepress.
beautiful.titlebar_floating_button_focus_active	gears.surface or string	floatingbuttonfocus_active.
beautiful.titlebar_floating_button_focus_active_hover	gears.surface or string	floatingbuttonfocusactivehover.
beautiful.titlebar_floating_button_focus_active_press	gears.surface or string	floatingbuttonfocusactivepress.
beautiful.titlebar_maximized_button_focus_active	gears.surface or string	maximizedbuttonfocus_active.
beautiful.titlebar_maximized_button_focus_active_hover	gears.surface or string	maximizedbuttonfocusactivehover.
beautiful.titlebar_maximized_button_focus_active_press	gears.surface or string	maximizedbuttonfocusactivepress.
beautiful.titlebar_ontop_button_focus_active	gears.surface or string	ontopbuttonfocus_active.
beautiful.titlebar_ontop_button_focus_active_hover	gears.surface or string	ontopbuttonfocusactivehover.
beautiful.titlebar_ontop_button_focus_active_press	gears.surface or string	ontopbuttonfocusactivepress.
beautiful.titlebar_sticky_button_focus_active	gears.surface or string	stickybuttonfocus_active.
beautiful.titlebar_sticky_button_focus_active_hover	gears.surface or string	stickybuttonfocusactivehover.
beautiful.titlebar_sticky_button_focus_active_press	gears.surface or string	stickybuttonfocusactivepress.
beautiful.titlebar_floating_button_normal_inactive	gears.surface or string	floatingbuttonnormal_inactive.
beautiful.titlebar_floating_button_normal_inactive_hover	gears.surface or string	floatingbuttonnormalinactivehover.
beautiful.titlebar_floating_button_normal_inactive_press	gears.surface or string	floatingbuttonnormalinactivepress.
beautiful.titlebar_maximized_button_normal_inactive	gears.surface or string	maximizedbuttonnormal_inactive.
beautiful.titlebar_maximized_button_normal_inactive_hover	gears.surface or string	maximizedbuttonnormalinactivehover.
beautiful.titlebar_maximized_button_normal_inactive_press	gears.surface or string	maximizedbuttonnormalinactivepress.
beautiful.titlebar_ontop_button_normal_inactive	gears.surface or string	ontopbuttonnormal_inactive.
beautiful.titlebar_ontop_button_normal_inactive_hover	gears.surface or string	ontopbuttonnormalinactivehover.
beautiful.titlebar_ontop_button_normal_inactive_press	gears.surface or string	ontopbuttonnormalinactivepress.
beautiful.titlebar_sticky_button_normal_inactive	gears.surface or string	stickybuttonnormal_inactive.
beautiful.titlebar_sticky_button_normal_inactive_hover	gears.surface or string	stickybuttonnormalinactivehover.
beautiful.titlebar_sticky_button_normal_inactive_press	gears.surface or string	stickybuttonnormalinactivepress.
beautiful.titlebar_floating_button_focus_inactive	gears.surface or string	floatingbuttonfocus_inactive.
beautiful.titlebar_floating_button_focus_inactive_hover	gears.surface or string	floatingbuttonfocusinactivehover.
beautiful.titlebar_floating_button_focus_inactive_press	gears.surface or string	floatingbuttonfocusinactivepress.
beautiful.titlebar_maximized_button_focus_inactive	gears.surface or string	maximizedbuttonfocus_inactive.
beautiful.titlebar_maximized_button_focus_inactive_hover	gears.surface or string	maximizedbuttonfocusinactivehover.
beautiful.titlebar_maximized_button_focus_inactive_press	gears.surface or string	maximizedbuttonfocusinactivepress.
beautiful.titlebar_ontop_button_focus_inactive	gears.surface or string	ontopbuttonfocus_inactive.
beautiful.titlebar_ontop_button_focus_inactive_hover	gears.surface or string	ontopbuttonfocusinactivehover.
beautiful.titlebar_ontop_button_focus_inactive_press	gears.surface or string	ontopbuttonfocusinactivepress.
beautiful.titlebar_sticky_button_focus_inactive	gears.surface or string	stickybuttonfocus_inactive.
beautiful.titlebar_sticky_button_focus_inactive_hover	gears.surface or string	stickybuttonfocusinactivehover.
beautiful.titlebar_sticky_button_focus_inactive_press	gears.surface or string	stickybuttonfocusinactivepress.

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

Client tiling

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:

Module: `awful.titlebar`