Class awful.titlebar - awesome API documentation

# Class `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.

    -- Create a titlebar for the client.
    -- By default, awful.rules will create one, but all it does is to call this
    -- function.
    local top_titlebar = awful.titlebar(c, {
        height    = 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

## Functions

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

## Theme variables

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

## Fields

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

## Methods

awful.titlebar:setup (args) | Set a declarative widget hierarchy description.
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.

## Functions

Methods

awful.titlebar (c[, args={}])
  Get a client's titlebar.
  - 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)
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.
  - c The client for which a titlewidget should be created.

  ### Returns:

  The title widget.
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.
  - c The client for which an icon widget should be created.

  ### Returns:

  The icon widget.
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.
  - 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
titlebar.widget.floatingbutton (c)
  Create a new float button for a client.
  - c The client for which the button is wanted.
titlebar.widget.maximizedbutton (c)
  Create a new maximize button for a client.
  - c The client for which the button is wanted.
titlebar.widget.minimizebutton (c)
  Create a new minimize button for a client.
  - c The client for which the button is wanted.
titlebar.widget.closebutton (c)
  Create a new closing button for a client.
  - c The client for which the button is wanted.
titlebar.widget.ontopbutton (c)
  Create a new ontop button for a client.
  - c The client for which the button is wanted.
titlebar.widget.stickybutton (c)
  Create a new sticky button for a client.
  - c The client for which the button is wanted.

## Theme variables

beautiful.titlebar_fg_normal
  The titlebar foreground (text) color.

  ### Type:

  - color

  ### See also:

  gears.color
beautiful.titlebar_bg_normal
  The titlebar background color.

  ### Type:

  - color

  ### See also:

  gears.color
beautiful.titlebar_bgimage_normal
  The titlebar background image image.

  ### Type:

  - surface

  ### See also:

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

  ### Type:

  - color

  ### See also:

  gears.color
beautiful.titlebar_bg
  The titlebar background color.

  ### Type:

  - color

  ### See also:

  gears.color
beautiful.titlebar_bgimage
  The titlebar background image image.

  ### Type:

  - surface

  ### See also:

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

  ### Type:

  - color

  ### See also:

  gears.color
beautiful.titlebar_bg_focus
  The focused titlebar background color.

  ### Type:

  - color

  ### See also:

  gears.color
beautiful.titlebar_bgimage_focus
  The focused titlebar background image image.

  ### Type:

  - surface

  ### See also:

  gears.surface
beautiful.titlebar_floating_button_normal
  floatingbuttonnormal.

  ### Type:

  - surface

  ### See also:

  gears.surface
beautiful.titlebar_maximized_button_normal
  maximizedbuttonnormal.

  ### Type:

  - surface

  ### See also:

  gears.surface
beautiful.titlebar_minimize_button_normal
  minimizebuttonnormal.

  ### Type:

  - surface

  ### See also:

  gears.surface
beautiful.titlebar_minimize_button_normal_hover
  minimizebuttonnormal_hover.

  ### Type:

  - surface

  ### See also:

  gears.surface
beautiful.titlebar_minimize_button_normal_press
  minimizebuttonnormal_press.

  ### Type:

  - surface

  ### See also:

  gears.surface
beautiful.titlebar_close_button_normal
  closebuttonnormal.

  ### Type:

  - surface

  ### See also:

  gears.surface
beautiful.titlebar_close_button_normal_hover
  closebuttonnormal_hover.

  ### Type:

  - surface

  ### See also:

  gears.surface
beautiful.titlebar_close_button_normal_press
  closebuttonnormal_press.

  ### Type:

  - surface

  ### See also:

  gears.surface
beautiful.titlebar_ontop_button_normal
  ontopbuttonnormal.

  ### Type:

  - surface

  ### See also:

  gears.surface
beautiful.titlebar_sticky_button_normal
  stickybuttonnormal.

  ### Type:

  - surface

  ### See also:

  gears.surface
beautiful.titlebar_floating_button_focus
  floatingbuttonfocus.

  ### Type:

  - surface

  ### See also:

  gears.surface
beautiful.titlebar_maximized_button_focus
  maximizedbuttonfocus.

  ### Type:

  - surface

  ### See also:

  gears.surface
beautiful.titlebar_minimize_button_focus
  minimizebuttonfocus.

  ### Type:

  - surface

  ### See also:

  gears.surface
beautiful.titlebar_minimize_button_focus_hover
  minimizebuttonfocus_hover.

  ### Type:

  - surface

  ### See also:

  gears.surface
beautiful.titlebar_minimize_button_focus_press
  minimizebuttonfocus_press.

  ### Type:

  - surface

  ### See also:

  gears.surface
beautiful.titlebar_close_button_focus
  closebuttonfocus.

  ### Type:

  - surface

  ### See also:

  gears.surface
beautiful.titlebar_close_button_focus_hover
  closebuttonfocus_hover.

  ### Type:

  - surface

  ### See also:

  gears.surface
beautiful.titlebar_close_button_focus_press
  closebuttonfocus_press.

  ### Type:

  - surface

  ### See also:

  gears.surface
beautiful.titlebar_ontop_button_focus
  ontopbuttonfocus.

  ### Type:

  - surface

  ### See also:

  gears.surface
beautiful.titlebar_sticky_button_focus
  stickybuttonfocus.

  ### Type:

  - surface

  ### See also:

  gears.surface
beautiful.titlebar_floating_button_normal_active
  floatingbuttonnormal_active.

  ### Type:

  - surface

  ### See also:

  gears.surface
beautiful.titlebar_floating_button_normal_active_hover
  floatingbuttonnormalactivehover.

  ### Type:

  - surface

  ### See also:

  gears.surface
beautiful.titlebar_floating_button_normal_active_press
  floatingbuttonnormalactivepress.

  ### Type:

  - surface

  ### See also:

  gears.surface
beautiful.titlebar_maximized_button_normal_active
  maximizedbuttonnormal_active.

  ### Type:

  - surface

  ### See also:

  gears.surface
beautiful.titlebar_maximized_button_normal_active_hover
  maximizedbuttonnormalactivehover.

  ### Type:

  - surface

  ### See also:

  gears.surface
beautiful.titlebar_maximized_button_normal_active_press
  maximizedbuttonnormalactivepress.

  ### Type:

  - surface

  ### See also:

  gears.surface
beautiful.titlebar_ontop_button_normal_active
  ontopbuttonnormal_active.

  ### Type:

  - surface

  ### See also:

  gears.surface
beautiful.titlebar_ontop_button_normal_active_hover
  ontopbuttonnormalactivehover.

  ### Type:

  - surface

  ### See also:

  gears.surface
beautiful.titlebar_ontop_button_normal_active_press
  ontopbuttonnormalactivepress.

  ### Type:

  - surface

  ### See also:

  gears.surface
beautiful.titlebar_sticky_button_normal_active
  stickybuttonnormal_active.

  ### Type:

  - surface

  ### See also:

  gears.surface
beautiful.titlebar_sticky_button_normal_active_hover
  stickybuttonnormalactivehover.

  ### Type:

  - surface

  ### See also:

  gears.surface
beautiful.titlebar_sticky_button_normal_active_press
  stickybuttonnormalactivepress.

  ### Type:

  - surface

  ### See also:

  gears.surface
beautiful.titlebar_floating_button_focus_active
  floatingbuttonfocus_active.

  ### Type:

  - surface

  ### See also:

  gears.surface
beautiful.titlebar_floating_button_focus_active_hover
  floatingbuttonfocusactivehover.

  ### Type:

  - surface

  ### See also:

  gears.surface
beautiful.titlebar_floating_button_focus_active_press
  floatingbuttonfocusactivepress.

  ### Type:

  - surface

  ### See also:

  gears.surface
beautiful.titlebar_maximized_button_focus_active
  maximizedbuttonfocus_active.

  ### Type:

  - surface

  ### See also:

  gears.surface
beautiful.titlebar_maximized_button_focus_active_hover
  maximizedbuttonfocusactivehover.

  ### Type:

  - surface

  ### See also:

  gears.surface
beautiful.titlebar_maximized_button_focus_active_press
  maximizedbuttonfocusactivepress.

  ### Type:

  - surface

  ### See also:

  gears.surface
beautiful.titlebar_ontop_button_focus_active
  ontopbuttonfocus_active.

  ### Type:

  - surface

  ### See also:

  gears.surface
beautiful.titlebar_ontop_button_focus_active_hover
  ontopbuttonfocusactivehover.

  ### Type:

  - surface

  ### See also:

  gears.surface
beautiful.titlebar_ontop_button_focus_active_press
  ontopbuttonfocusactivepress.

  ### Type:

  - surface

  ### See also:

  gears.surface
beautiful.titlebar_sticky_button_focus_active
  stickybuttonfocus_active.

  ### Type:

  - surface

  ### See also:

  gears.surface
beautiful.titlebar_sticky_button_focus_active_hover
  stickybuttonfocusactivehover.

  ### Type:

  - surface

  ### See also:

  gears.surface
beautiful.titlebar_sticky_button_focus_active_press
  stickybuttonfocusactivepress.

  ### Type:

  - surface

  ### See also:

  gears.surface
beautiful.titlebar_floating_button_normal_inactive
  floatingbuttonnormal_inactive.

  ### Type:

  - surface

  ### See also:

  gears.surface
beautiful.titlebar_floating_button_normal_inactive_hover
  floatingbuttonnormalinactivehover.

  ### Type:

  - surface

  ### See also:

  gears.surface
beautiful.titlebar_floating_button_normal_inactive_press
  floatingbuttonnormalinactivepress.

  ### Type:

  - surface

  ### See also:

  gears.surface
beautiful.titlebar_maximized_button_normal_inactive
  maximizedbuttonnormal_inactive.

  ### Type:

  - surface

  ### See also:

  gears.surface
beautiful.titlebar_maximized_button_normal_inactive_hover
  maximizedbuttonnormalinactivehover.

  ### Type:

  - surface

  ### See also:

  gears.surface
beautiful.titlebar_maximized_button_normal_inactive_press
  maximizedbuttonnormalinactivepress.

  ### Type:

  - surface

  ### See also:

  gears.surface
beautiful.titlebar_ontop_button_normal_inactive
  ontopbuttonnormal_inactive.

  ### Type:

  - surface

  ### See also:

  gears.surface
beautiful.titlebar_ontop_button_normal_inactive_hover
  ontopbuttonnormalinactivehover.

  ### Type:

  - surface

  ### See also:

  gears.surface
beautiful.titlebar_ontop_button_normal_inactive_press
  ontopbuttonnormalinactivepress.

  ### Type:

  - surface

  ### See also:

  gears.surface
beautiful.titlebar_sticky_button_normal_inactive
  stickybuttonnormal_inactive.

  ### Type:

  - surface

  ### See also:

  gears.surface
beautiful.titlebar_sticky_button_normal_inactive_hover
  stickybuttonnormalinactivehover.

  ### Type:

  - surface

  ### See also:

  gears.surface
beautiful.titlebar_sticky_button_normal_inactive_press
  stickybuttonnormalinactivepress.

  ### Type:

  - surface

  ### See also:

  gears.surface
beautiful.titlebar_floating_button_focus_inactive
  floatingbuttonfocus_inactive.

  ### Type:

  - surface

  ### See also:

  gears.surface
beautiful.titlebar_floating_button_focus_inactive_hover
  floatingbuttonfocusinactivehover.

  ### Type:

  - surface

  ### See also:

  gears.surface
beautiful.titlebar_floating_button_focus_inactive_press
  floatingbuttonfocusinactivepress.

  ### Type:

  - surface

  ### See also:

  gears.surface
beautiful.titlebar_maximized_button_focus_inactive
  maximizedbuttonfocus_inactive.

  ### Type:

  - surface

  ### See also:

  gears.surface
beautiful.titlebar_maximized_button_focus_inactive_hover
  maximizedbuttonfocusinactivehover.

  ### Type:

  - surface

  ### See also:

  gears.surface
beautiful.titlebar_maximized_button_focus_inactive_press
  maximizedbuttonfocusinactivepress.

  ### Type:

  - surface

  ### See also:

  gears.surface
beautiful.titlebar_ontop_button_focus_inactive
  ontopbuttonfocus_inactive.

  ### Type:

  - surface

  ### See also:

  gears.surface
beautiful.titlebar_ontop_button_focus_inactive_hover
  ontopbuttonfocusinactivehover.

  ### Type:

  - surface

  ### See also:

  gears.surface
beautiful.titlebar_ontop_button_focus_inactive_press
  ontopbuttonfocusinactivepress.

  ### Type:

  - surface

  ### See also:

  gears.surface
beautiful.titlebar_sticky_button_focus_inactive
  stickybuttonfocus_inactive.

  ### Type:

  - surface

  ### See also:

  gears.surface
beautiful.titlebar_sticky_button_focus_inactive_hover
  stickybuttonfocusinactivehover.

  ### Type:

  - surface

  ### See also:

  gears.surface
beautiful.titlebar_sticky_button_focus_inactive_press
  stickybuttonfocusinactivepress.

  ### Type:

  - surface

  ### See also:

  gears.surface

## Fields

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

## Methods

awful.titlebar:setup (args)
  Set a declarative widget hierarchy description. See The declarative layout system
  - args An array containing the widgets disposition
awful.titlebar:show (c[, position])
  Show a client's titlebar.
  - 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:hide (c[, position])
  Hide a client's titlebar.
  - 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])
  Toggle a client's titlebar, hiding it if it is visible, otherwise showing it.
  - 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)

generated by LDoc 1.5.0 Last updated 2024-12-21 21:41:42