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
  • Author: Uli Schlachter

Constructors

awful.titlebar (c[, args={}]) Get a client's titlebar.
awful.titlebar.widget.titlewidget (c) Create a new titlewidget.
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]) Show a client's titlebar.
awful.titlebar.hide (c[, position]) Hide a client's titlebar.
awful.titlebar.toggle (c[, position]) Toggle a 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_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={}])
Get a client's titlebar.

Parameters:

  • c client The client for which a titlebar is wanted.
  • args A table with extra arguments for the titlebar.
    • size number The height of the titlebar. (default font.height*1.5)
    • position string " values are top, left, right and bottom. (default top)
    • bg_normal string (default top)
    • bg_focus string (default top)
    • bgimage_normal string (default top)
    • bgimage_focus string (default top)
    • fg_normal string (default top)
    • fg_focus string (default top)
    • font string (default top)
awful.titlebar.widget.titlewidget (c)
Create a new titlewidget. 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() function. 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]) · 1 permission
Show a client's titlebar.

Parameters:

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

Click to display more

Requested actions or permissions:

Class Permission Context Default Description
clienttitlebarsshowgrantedCalled when awful.titlebar.show is called.
awful.titlebar.hide (c[, position])
Hide a client's titlebar.

Parameters:

  • c The client whose titlebar is modified
  • position The position of the titlebar. Must be one of "left", "right", "top", "bottom". Default is "top". (optional)
awful.titlebar.toggle (c[, position]) · 1 permission
Toggle a client's titlebar, hiding it if it is visible, otherwise showing it.

Parameters:

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

Click to display more

Requested actions or permissions:

Class Permission Context Default Description
clienttitlebarstogglegrantedCalled 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.

See also:

beautiful.titlebar_bg_normal color
The titlebar background color.

See also:

beautiful.titlebar_bgimage_normal gears.surface or string
The titlebar background image image.

See also:

beautiful.titlebar_fg color
The titlebar foreground (text) color.

See also:

beautiful.titlebar_bg color
The titlebar background color.

See also:

beautiful.titlebar_bgimage gears.surface or string
The titlebar background image image.

See also:

beautiful.titlebar_fg_focus color
The focused titlebar foreground (text) color.

See also:

beautiful.titlebar_bg_focus color
The focused titlebar background color.

See also:

beautiful.titlebar_bgimage_focus gears.surface or string
The focused titlebar background image image.

See also:

beautiful.titlebar_floating_button_normal gears.surface or string
floatingbuttonnormal.

See also:

beautiful.titlebar_maximized_button_normal gears.surface or string
maximizedbuttonnormal.

See also:

beautiful.titlebar_minimize_button_normal gears.surface or string
minimizebuttonnormal.

See also:

beautiful.titlebar_minimize_button_normal_hover gears.surface or string
minimizebuttonnormal_hover.

See also:

beautiful.titlebar_minimize_button_normal_press gears.surface or string
minimizebuttonnormal_press.

See also:

beautiful.titlebar_close_button_normal gears.surface or string
closebuttonnormal.

See also:

beautiful.titlebar_close_button_normal_hover gears.surface or string
closebuttonnormal_hover.

See also:

beautiful.titlebar_close_button_normal_press gears.surface or string
closebuttonnormal_press.

See also:

beautiful.titlebar_ontop_button_normal gears.surface or string
ontopbuttonnormal.

See also:

beautiful.titlebar_sticky_button_normal gears.surface or string
stickybuttonnormal.

See also:

beautiful.titlebar_floating_button_focus gears.surface or string
floatingbuttonfocus.

See also:

beautiful.titlebar_maximized_button_focus gears.surface or string
maximizedbuttonfocus.

See also:

beautiful.titlebar_minimize_button_focus gears.surface or string
minimizebuttonfocus.

See also:

beautiful.titlebar_minimize_button_focus_hover gears.surface or string
minimizebuttonfocus_hover.

See also:

beautiful.titlebar_minimize_button_focus_press gears.surface or string
minimizebuttonfocus_press.

See also:

beautiful.titlebar_close_button_focus gears.surface or string
closebuttonfocus.

See also:

beautiful.titlebar_close_button_focus_hover gears.surface or string
closebuttonfocus_hover.

See also:

beautiful.titlebar_close_button_focus_press gears.surface or string
closebuttonfocus_press.

See also:

beautiful.titlebar_ontop_button_focus gears.surface or string
ontopbuttonfocus.

See also:

beautiful.titlebar_sticky_button_focus gears.surface or string
stickybuttonfocus.

See also:

beautiful.titlebar_floating_button_normal_active gears.surface or string
floatingbuttonnormal_active.

See also:

beautiful.titlebar_floating_button_normal_active_hover gears.surface or string
floatingbuttonnormalactivehover.

See also:

beautiful.titlebar_floating_button_normal_active_press gears.surface or string
floatingbuttonnormalactivepress.

See also:

beautiful.titlebar_maximized_button_normal_active gears.surface or string
maximizedbuttonnormal_active.

See also:

beautiful.titlebar_maximized_button_normal_active_hover gears.surface or string
maximizedbuttonnormalactivehover.

See also:

beautiful.titlebar_maximized_button_normal_active_press gears.surface or string
maximizedbuttonnormalactivepress.

See also:

beautiful.titlebar_ontop_button_normal_active gears.surface or string
ontopbuttonnormal_active.

See also:

beautiful.titlebar_ontop_button_normal_active_hover gears.surface or string
ontopbuttonnormalactivehover.

See also:

beautiful.titlebar_ontop_button_normal_active_press gears.surface or string
ontopbuttonnormalactivepress.

See also:

beautiful.titlebar_sticky_button_normal_active gears.surface or string
stickybuttonnormal_active.

See also:

beautiful.titlebar_sticky_button_normal_active_hover gears.surface or string
stickybuttonnormalactivehover.

See also:

beautiful.titlebar_sticky_button_normal_active_press gears.surface or string
stickybuttonnormalactivepress.

See also:

beautiful.titlebar_floating_button_focus_active gears.surface or string
floatingbuttonfocus_active.

See also:

beautiful.titlebar_floating_button_focus_active_hover gears.surface or string
floatingbuttonfocusactivehover.

See also:

beautiful.titlebar_floating_button_focus_active_press gears.surface or string
floatingbuttonfocusactivepress.

See also:

beautiful.titlebar_maximized_button_focus_active gears.surface or string
maximizedbuttonfocus_active.

See also:

beautiful.titlebar_maximized_button_focus_active_hover gears.surface or string
maximizedbuttonfocusactivehover.

See also:

beautiful.titlebar_maximized_button_focus_active_press gears.surface or string
maximizedbuttonfocusactivepress.

See also:

beautiful.titlebar_ontop_button_focus_active gears.surface or string
ontopbuttonfocus_active.

See also:

beautiful.titlebar_ontop_button_focus_active_hover gears.surface or string
ontopbuttonfocusactivehover.

See also:

beautiful.titlebar_ontop_button_focus_active_press gears.surface or string
ontopbuttonfocusactivepress.

See also:

beautiful.titlebar_sticky_button_focus_active gears.surface or string
stickybuttonfocus_active.

See also:

beautiful.titlebar_sticky_button_focus_active_hover gears.surface or string
stickybuttonfocusactivehover.

See also:

beautiful.titlebar_sticky_button_focus_active_press gears.surface or string
stickybuttonfocusactivepress.

See also:

beautiful.titlebar_floating_button_normal_inactive gears.surface or string
floatingbuttonnormal_inactive.

See also:

beautiful.titlebar_floating_button_normal_inactive_hover gears.surface or string
floatingbuttonnormalinactivehover.

See also:

beautiful.titlebar_floating_button_normal_inactive_press gears.surface or string
floatingbuttonnormalinactivepress.

See also:

beautiful.titlebar_maximized_button_normal_inactive gears.surface or string
maximizedbuttonnormal_inactive.

See also:

beautiful.titlebar_maximized_button_normal_inactive_hover gears.surface or string
maximizedbuttonnormalinactivehover.

See also:

beautiful.titlebar_maximized_button_normal_inactive_press gears.surface or string
maximizedbuttonnormalinactivepress.

See also:

beautiful.titlebar_ontop_button_normal_inactive gears.surface or string
ontopbuttonnormal_inactive.

See also:

beautiful.titlebar_ontop_button_normal_inactive_hover gears.surface or string
ontopbuttonnormalinactivehover.

See also:

beautiful.titlebar_ontop_button_normal_inactive_press gears.surface or string
ontopbuttonnormalinactivepress.

See also:

beautiful.titlebar_sticky_button_normal_inactive gears.surface or string
stickybuttonnormal_inactive.

See also:

beautiful.titlebar_sticky_button_normal_inactive_hover gears.surface or string
stickybuttonnormalinactivehover.

See also:

beautiful.titlebar_sticky_button_normal_inactive_press gears.surface or string
stickybuttonnormalinactivepress.

See also:

beautiful.titlebar_floating_button_focus_inactive gears.surface or string
floatingbuttonfocus_inactive.

See also:

beautiful.titlebar_floating_button_focus_inactive_hover gears.surface or string
floatingbuttonfocusinactivehover.

See also:

beautiful.titlebar_floating_button_focus_inactive_press gears.surface or string
floatingbuttonfocusinactivepress.

See also:

beautiful.titlebar_maximized_button_focus_inactive gears.surface or string
maximizedbuttonfocus_inactive.

See also:

beautiful.titlebar_maximized_button_focus_inactive_hover gears.surface or string
maximizedbuttonfocusinactivehover.

See also:

beautiful.titlebar_maximized_button_focus_inactive_press gears.surface or string
maximizedbuttonfocusinactivepress.

See also:

beautiful.titlebar_ontop_button_focus_inactive gears.surface or string
ontopbuttonfocus_inactive.

See also:

beautiful.titlebar_ontop_button_focus_inactive_hover gears.surface or string
ontopbuttonfocusinactivehover.

See also:

beautiful.titlebar_ontop_button_focus_inactive_press gears.surface or string
ontopbuttonfocusinactivepress.

See also:

beautiful.titlebar_sticky_button_focus_inactive gears.surface or string
stickybuttonfocus_inactive.

See also:

beautiful.titlebar_sticky_button_focus_inactive_hover gears.surface or string
stickybuttonfocusinactivehover.

See also:

beautiful.titlebar_sticky_button_focus_inactive_press gears.surface or string
stickybuttonfocusinactivepress.

See also:

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.
generated by LDoc 1.4.6 Build with 💜 By F0xedb Last updated 2021-05-21 03:30:15