### Create and Setup Top Wibar

Source: https://github.com/awesomewm/apidoc/blob/gh-pages/popups_and_bars/awful.wibar.html

Example of creating a top-aligned wibar and setting its layout with various widgets like taglist, tasklist, and clock. Requires prior setup of mytaglist, mytasklist, mykeyboardlayout, and mytextclock.

```lua
local wb = awful.wibar { position = "top" }
wb:setup {
    layout = wibox.layout.align.horizontal,
    {
        mytaglist,
        layout = wibox.layout.fixed.horizontal,
    },
    mytasklist,
    {
        layout = wibox.layout.fixed.horizontal,
        mykeyboardlayout,
        mytextclock,
    },
}
```

--------------------------------

### Build and Install AwesomeWM on Debian-based Systems

Source: https://github.com/awesomewm/apidoc/blob/gh-pages/documentation/01-readme.md.html

Install build dependencies, clone the AwesomeWM repository, and build a .deb package. Install the package using apt.

```bash
sudo apt build-dep awesome
sudo apt install libxcb-xfixes0-dev
git clone https://github.com/awesomewm/awesome
cd awesome
make package
cd build
sudo apt install ./*.deb
```

--------------------------------

### Create and Setup Left Wibar

Source: https://github.com/awesomewm/apidoc/blob/gh-pages/popups_and_bars/awful.wibar.html

Demonstrates creating a left-aligned vertical wibar. The example shows how to set up a vertical layout and includes a comment about rotating widgets within the container.

```lua
local wb = awful.wibar { position = "left" }
wb:setup {
    layout = wibox.layout.align.vertical,
    {
        -- Rotate the widgets with the container
        {
            mytaglist,

```

--------------------------------

### Install AwesomeWM from Arch Linux AUR

Source: https://github.com/awesomewm/apidoc/blob/gh-pages/documentation/01-readme.md.html

Clone the AUR repository, navigate into the directory, and use makepkg to build and install the package. Ensure base-devel and git are installed.

```bash
sudo pacman -S --needed base-devel git
git clone https://aur.archlinux.org/awesome-git.git
cd awesome-git
makepkg -fsri
```

--------------------------------

### Wallpaper Configuration Example

Source: https://github.com/awesomewm/apidoc/blob/gh-pages/popups_and_bars/awful.wallpaper.html

Example demonstrating how to set wallpaper properties like screens, background color, and a custom widget.

```APIDOC
## Wallpaper Configuration

### Description
This section details the configuration of wallpaper in AwesomeWM, including setting background and foreground colors, and options for honoring the workarea.

### Parameters
#### Request Body
- **screens** (table) - Optional - A list of screen objects to apply the wallpaper to. Defaults to all screens.
- **bg** (string | table | cairo.pattern) - Required - The background color. Can be a hex code, color name, gradient table, or Cairo pattern.
- **fg** (string | table | cairo.pattern) - Optional - The foreground color, used by the widget if provided.
- **widget** (widget) - Optional - A custom widget to display as the wallpaper.
- **honor_workarea** (boolean) - Optional - If true, the wallpaper will only fill the workarea, not the entire screen. Defaults to false.

### Request Example
```lua
local awful = require("awful")
local wibox = require("wibox")
local gears = require("gears")

awful.wallpaper {
    screens = { screen[2], screen[3] },
    bg = "#222222",
    widget = wibox.widget {
        { -- Inner widget definition
            fit = function(_, width, height)
                return width, height
            end,
            draw = function(_, _, cr, width, height)
                cr:set_source(gears.color("#0000ff"))
                cr:line_to(width, height)
                cr:line_to(width, 0)
                cr:line_to(0, 0)
                cr:close_path()
                cr:fill()
                cr:set_source(gears.color("#ff00ff"))
                cr:move_to(0, 0)
                cr:line_to(0, height)
                cr:line_to(width, height)
                cr:close_path()
                cr:fill()
            end,
            widget = wibox.widget.base.make_widget()
        },
        { -- Text widget definition
            text = "Center",
            valign = "center",
            halign = "center",
            widget = wibox.widget.textbox
        },
        widget = wibox.layout.stack
    }
}
```

### Response
This function does not return a value. Configuration is applied directly.
```

--------------------------------

### Build and Install AwesomeWM

Source: https://github.com/awesomewm/apidoc/blob/gh-pages/documentation/10-building-and-testing.md.html

Run these commands in the repository root to build and install AwesomeWM after all dependencies are met.

```bash
make
sudo make install
```

--------------------------------

### Example Usage

Source: https://github.com/awesomewm/apidoc/blob/gh-pages/popups_and_bars/awful.widget.calendar_popup.html

Example of how to create and attach a month calendar popup.

```APIDOC
## Example

```lua
local month_calendar = awful.widget.calendar_popup.month()
month_calendar:attach( mytextclock, "tr" )
month_calendar:toggle()
```
```

--------------------------------

### Theme Configuration File Example

Source: https://github.com/awesomewm/apidoc/blob/gh-pages/theme_related_libraries/beautiful.html

An example of a theme configuration file for AwesomeWM. This file should return a table containing theme properties.

```lua
theme = {}
    theme.font = 'Monospace Bold 10'
return theme
```

--------------------------------

### Connect Signal Example

Source: https://github.com/awesomewm/apidoc/blob/gh-pages/widget_containers/wibox.container.scroll.html

Demonstrates how to connect a callback function to a signal. The example shows output for nil and string/number arguments.

```lua
In slot [obj]   nil nil nil
In slot [obj]   foo bar 42

```

--------------------------------

### Install AwesomeWM v4 Locally

Source: https://github.com/awesomewm/apidoc/blob/gh-pages/documentation/17-porting-tips.md.html

Install AwesomeWM v4 in a separate prefix to avoid conflicts with existing installations. This assumes dependencies are already met.

```bash
cd path/to/awesome/code
mkdir -p $HOME/.config/awesome4
mkdir build -p
cd build
cmake -DCMAKE_INSTALL_PREFIX=$HOME/awesome4_test ..
make -j4
cp awesomerc.lua $HOME/.config/awesome4/rc.lua
make install
```

--------------------------------

### Start Clients as Slave Windows

Source: https://github.com/awesomewm/apidoc/blob/gh-pages/documentation/90-FAQ.md.html

Configure AwesomeWM to start new windows as slave windows by adding a rule to the ruled.client.rules table that matches all clients and sets them as slave.

```lua
-- Start windows as slave
{ rule = { }, properties = { }, callback = awful.client.setslave }
```

--------------------------------

### Signal Connection Example

Source: https://github.com/awesomewm/apidoc/blob/gh-pages/widget_layouts/wibox.layout.flex.html

Example demonstrating how signals are received in a callback function.

```lua
In slot [obj]   nil nil nil
In slot [obj]   foo bar 42
```

--------------------------------

### wibox.widget.imagebox Usage Example

Source: https://github.com/awesomewm/apidoc/blob/gh-pages/widgets/awful.widget.launcher.html

Example demonstrating the usage of wibox.widget.imagebox with stylesheet.

```APIDOC
## Usage Example: wibox.widget.imagebox with Stylesheet

### Request Example
```lua
local image = '<?xml version="1.0" encoding="UTF-8" standalone="no"?>'..\n    '<svg width="190" height="60">'..\n        '<rect x="10"  y="10" width="50" height="50" />'..\n        '<rect x="70"  y="10" width="50" height="50" class="my_class" />'..\n        '<rect x="130" y="10" width="50" height="50" id="my_id" />'..\n    '</svg>'

local stylesheet = "" ..\n     "rect { fill: #ffff00; } "..\n     ".my_class { fill: #00ff00; } "..\n     "#my_id { fill: #0000ff; }"

local w = wibox.widget {
    stylesheet = stylesheet,
    image      = image,
    widget     = wibox.widget.imagebox
}
```
```

--------------------------------

### Install Debian Package

Source: https://github.com/awesomewm/apidoc/blob/gh-pages/documentation/10-building-and-testing.md.html

Use dpkg to install the generated .deb package.

```bash
sudo dpkg -i awesome-x.y.z.deb
```

--------------------------------

### AwesomeWM Prompt Key Listener Example

Source: https://github.com/awesomewm/apidoc/blob/gh-pages/libraries/awful.prompt.html

This example demonstrates how to listen for key press and release events within the AwesomeWM prompt. It uses `naughty.notification` to show feedback when 'Shift' is pressed and cleans up the notification on release.

```lua
local atextbox = wibox.widget.textbox()
local notif = nil
awful.prompt.run {
    prompt               = "<b>Run: </b>",
    keypressed_callback  = function(mod, key, cmd) --luacheck: no unused args
        if key == "Shift_L" then
            notif = naughty.notification { message = "Shift pressed" }
        end
    end,
    keyreleased_callback = function(mod, key, cmd) --luacheck: no unused args
        if notif then
            naughty.destroy(notif)
            notif = nil
        end
    end,
    textbox              = atextbox,
    history_path         = gfs.get_cache_dir() .. "/history",
}
```

--------------------------------

### Generate .deb or .rpm Package

Source: https://github.com/awesomewm/apidoc/blob/gh-pages/documentation/01-readme.md.html

Use 'make package' to create installation packages. Install them using dpkg or rpm.

```bash
make package
```

```bash
sudo dpkg -i awesome-x.y.z.deb
# or
sudo rpm -Uvh awesome-x.y.z.rpm
```

--------------------------------

### awesome.version

Source: https://github.com/awesomewm/apidoc/blob/gh-pages/core_components/awesome.html

Provides the version string of the AwesomeWM installation.

```APIDOC
## awesome.version

### Description
The AwesomeWM version.
```

--------------------------------

### wibox.container.background Widget Usage Examples

Source: https://github.com/awesomewm/apidoc/blob/gh-pages/widget_containers/wibox.container.background.html

Illustrative examples of how to use the wibox.container.background widget with different border colors and strategies.

```APIDOC
## Usage Examples for wibox.container.background

### Example 1: Setting Border Color

This example demonstrates setting the `border_color` property with various valid types.

```lua
local colors = {
    beautiful.bg_normal,
    "#00ff00",
    gears.color {
        type  = "linear",
        from  = { 0 , 20 },
        to    = { 20, 0  },
        stops = {
            { 0, "#0000ff" },
            { 1, "#ff0000" }
        },
    },
}

for _, color in ipairs(colors) do
    local w = wibox.widget {
        {
            {
                text          = "  Content  ",
                valign        = "center",
                align         = "center",
                widget        = wibox.widget.textbox
            },
            margins = 10,
            widget  = wibox.container.margin
        },
        border_color         = color,
        border_width         = 3,
        stretch_vertically   = true,
        stretch_horizontally = true,
        shape                = gears.shape.rounded_rect,
        widget               = wibox.container.background
    }
end
```

### Example 2: Using `border_strategy`

This example shows how to apply different `border_strategy` values with varying `border_width`.

```lua
for k, strategy in ipairs { "none", "inner" } do
    for idx, width in ipairs {0, 1, 3, 10 } do
        local w = wibox.widget {
            {
                {
                    text          = "border_width = "..width,
                    valign        = "center",
                    align         = "center",
                    widget        = wibox.widget.textbox
                },
                border_color    = beautiful.bg_normal,
                border_width    = width,
                border_strategy = strategy,
                shape           = gears.shape.rounded_rect,
                widget          = wibox.container.background
            },
            widget = wibox.container.place
        }
    end
end
```
```

--------------------------------

### awesome.spawn

Source: https://github.com/awesomewm/apidoc/blob/gh-pages/core_components/awesome.html

Spawns a program to be started on the default screen.

```APIDOC
## awesome.spawn

### Description
Spawn a program. The program will be started on the default screen.

### Parameters
#### Path Parameters
- **cmd** (string) - Required - The command to spawn.
- **use_sn** - Optional - Use sn.
- **stdin** - Optional - Standard input.
- **stdout** - Optional - Standard output.
- **stderr** - Optional - Standard error.
- **exit_callback** - Optional - Callback function when the process exits.
- **cmd** (string) - Required - The command to spawn (repeated parameter, likely a typo in source).

### Returns
- **(integer, string, integer, integer, integer) or string** - The result of spawning the program.

### Method
Not applicable (function call)
```

--------------------------------

### Relative Client Movement and Resizing

Source: https://github.com/awesomewm/apidoc/blob/gh-pages/core_components/client.html

Demonstrates relative movement and resizing of a client. The first example moves the client by 100 units in both x and y directions. The second example resizes the client by adding 100 units to its width and height.

```lua
awful.spawn("")

client.get()[1].floating = true

geo = client.get()[1]:geometry()
print("Client geometry:", geo.x, geo.y, geo.width, geo.height)

client.get()[1]:relative_move(100, 100)

geo = client.get()[1]:geometry()
print("Client geometry:", geo.x, geo.y, geo.width, geo.height)

client.get()[1]:relative_move(nil, nil, 100, 100)

geo = client.get()[1]:geometry()
print("Client geometry:", geo.x, geo.y, geo.width, geo.height)
```

--------------------------------

### Start AwesomeWM with startx or Display Manager

Source: https://github.com/awesomewm/apidoc/blob/gh-pages/documentation/01-readme.md.html

Add 'exec awesome' to your .xinitrc for startx or .xsession for display managers to launch AwesomeWM.

```bash
exec awesome
```

--------------------------------

### Get Themes Directory

Source: https://github.com/awesomewm/apidoc/blob/gh-pages/utility_libraries/gears.filesystem.html

Retrieves the path to the directory where themes are installed. The returned path includes a trailing slash.

```lua
gears.filesystem.get_themes_dir()
```

--------------------------------

### Get Awesome Icon Directory

Source: https://github.com/awesomewm/apidoc/blob/gh-pages/utility_libraries/gears.filesystem.html

Retrieves the path to the directory where AwesomeWM icons are installed. The returned path includes a trailing slash.

```lua
gears.filesystem.get_awesome_icon_dir()
```

--------------------------------

### client:setup

Source: https://github.com/awesomewm/apidoc/blob/gh-pages/popups_and_bars/awful.titlebar.html

Sets a declarative widget hierarchy description for a client. This utilizes AwesomeWM's declarative layout system.

```APIDOC
## client:setup

### Description
Set a declarative widget hierarchy description.
See [The declarative layout system](../documentation/03-declarative-layout.md.html)

### Parameters:

- **args** (table) - Required - An array containing the widgets disposition
```

--------------------------------

### Configure Wibox Layout

Source: https://github.com/awesomewm/apidoc/blob/gh-pages/widgets/awful.widget.launcher.html

Set up the layout for a wibox, arranging widgets horizontally and vertically. This example demonstrates a common setup for a status bar.

```lua
wb:setup {
    layout = wibox.layout.align.horizontal,
    { 
        mylauncher,
        mytaglist,
        layout = wibox.layout.fixed.horizontal,
    },
    mytasklist, 
    {
        layout = wibox.layout.fixed.horizontal,
        mykeyboardlayout,
        mytextclock,
        mylayoutbox,
    },
}
```

--------------------------------

### Create a table iterator

Source: https://github.com/awesomewm/apidoc/blob/gh-pages/utility_libraries/gears.table.html

Use gears.table.iterate to get an iterator function for a table. An optional filter function can be provided to match specific elements, and iteration can start from a given index.

```lua
local t = { 10, 20, 30, 40 }
local iterator = gears.table.iterate(t, function(value) return value > 15 end)
for value in iterator do
  print(value)
end
```

--------------------------------

### Set Client Sticky

Source: https://github.com/awesomewm/apidoc/blob/gh-pages/core_components/client.html

This example demonstrates how to make a client window sticky, meaning it will appear on all tags (workspaces). AwesomeWM implements sticky clients per screen.

```lua
awful.spawn("xterm")

-- Set sticky = true
screen[1].clients[1].sticky = true
```

--------------------------------

### Install RPM Package

Source: https://github.com/awesomewm/apidoc/blob/gh-pages/documentation/10-building-and-testing.md.html

Use rpm to install the generated .rpm package.

```bash
sudo rpm -Uvh awesome-x.y.z.rpm
```

--------------------------------

### Configure Tasklist Screen and Buttons

Source: https://github.com/awesomewm/apidoc/blob/gh-pages/widgets/awful.widget.tasklist.html

This example shows how to initialize a tasklist widget for a specific screen and define custom buttons for client interaction. It also demonstrates how to change the tasklist's screen after initialization.

```lua
local tasklist = awful.widget.tasklist {
    screen      = screen[1],
    filter      = awful.widget.tasklist.filter.currenttags,
    buttons     = {
        awful.button({ }, 1, function (c) 
            c:activate {
                context = "tasklist",
                action  = "toggle_minimization"
            }
        end),
        awful.button({ }, 3, function() awful.menu.client_list { theme = { width = 250 } } end),
        awful.button({ }, 4, function() awful.client.focus.byidx(-1) end),
        awful.button({ }, 5, function() awful.client.focus.byidx( 1) end),
    },
}

-- Spawn 5 clients on screen 1.
for i= 1, 5 do
    awful.spawn("Client #"..i, {screen = screen[1]})
end

-- Spawn 3 clients on screen 2.
for i=1, 3 do
    awful.spawn("Client #"..(5+i), {screen = screen[2]})
end

-- Change the tastlist screen.
tasklist.screen = screen[2]

```

--------------------------------

### Set Up Screen Configuration

Source: https://github.com/awesomewm/apidoc/blob/gh-pages/documentation/17-porting-tips.md.html

Connects functions for each screen to set up wallpapers, tags, promptboxes, layoutboxes, taglists, tasklists, and wiboxes. This is crucial for multi-monitor setups.

```lua
awful.screen.connect_for_each_screen(function(s)
    -- Wallpaper
    set_wallpaper(s)

    -- Each screen has its own tag table.
    awful.tag({ "1", "2", "3", "4", "5", "6", "7", "8", "9" }, s, awful.layout.layouts[1])

    -- Create a promptbox for each screen
    s.mypromptbox = awful.widget.prompt()
    -- Create an imagebox widget which will contains an icon indicating which layout we're using.
    -- We need one layoutbox per screen.
    s.mylayoutbox = awful.widget.layoutbox(s)
    s.mylayoutbox:buttons(awful.util.table.join(
                            awful.button({ }, 1, function () awful.layout.inc( 1) end),
                            awful.button({ }, 3, function () awful.layout.inc(-1) end),
                            awful.button({ }, 4, function () awful.layout.inc( 1) end),
                            awful.button({ }, 5, function () awful.layout.inc(-1) end)))
    -- Create a taglist widget
    s.mytaglist = awful.widget.taglist(s, awful.widget.taglist.filter.all, taglist_buttons)

    -- Create a tasklist widget
    s.mytasklist = awful.widget.tasklist(s, awful.widget.tasklist.filter.currenttags, tasklist_buttons)

    -- Create the wibox
    s.mywibox = awful.wibar({ position = "top", screen = s })

    -- Widgets that are aligned to the left
    local left_layout = wibox.layout.fixed.horizontal()
    left_layout:add(s.mytaglist)
    left_layout:add(s.mypromptbox)

   -- Widgets that are aligned to the right
    local right_layout = wibox.layout.fixed.horizontal()
    right_layout:add(wibox.widget.systray())
    right_layout:add(mytextclock)
    right_layout:add(s.mylayoutbox)

    -- Add the widgets to the wibox
    s.mywibox:setup { layout = wibox.layout.align.horizontal, 
        { no_margins = true, widget = left_layout }, 
        { no_margins = true, widget = mytooltip }, 
        { no_margins = true, widget = right_layout } 
    }
end)
```

--------------------------------

### Global Keybindings Example

Source: https://github.com/awesomewm/apidoc/blob/gh-pages/popups_and_bars/awful.hotkeys_popup.widget.html

Example of adding global keybindings using awful.key.

```APIDOC
## Global Keybindings

### Description
Example of how to add global keybindings, including showing help popups with different options.

### Method
Function Call

### Endpoint
N/A (Function Call)

### Parameters
None explicitly defined in this snippet, relies on `modkey`, `altkey` variables.

### Request Example
```lua
awful.keyboard.append_global_keybindings({
    awful.key({modkey}, "/", function()
      hotkeys_popup.show_help()
    end, nil, {
      description = "show help (all)", group="HELP"
    }),
    awful.key({"Shift", modkey}, "/", function()
      hotkeys_popup.show_help(nil, nil, {show_awesome_keys=false})
    end, nil, {
      description = "show help for current app", group="HELP"
    }),
    awful.key({altkey, modkey}, "/", function()
      hotkeys_popup.show_help({}, nil, {show_awesome_keys=true})
    end, nil, {
      description = "show help for awesome only", group="HELP"
    })
})
```

### Response
#### Success Response (200)
Global keybindings are registered.

#### Response Example
```lua
-- Keybindings registered
```
```

--------------------------------

### Separator Widget Usage Example

Source: https://github.com/awesomewm/apidoc/blob/gh-pages/widgets/wibox.widget.separator.html

An example demonstrating how to use the wibox.widget.separator with custom properties.

```APIDOC
### Usage Example

```lua
wibox.widget {
    shape        = gears.shape.circle,
    color        = "#00000000",
    border_width = 1,
    border_color = beautiful.bg_normal,
    widget       = wibox.widget.separator,
}
```
```

--------------------------------

### startup

Source: https://github.com/awesomewm/apidoc/blob/gh-pages/core_components/awesome.html

Emitted when AwesomeWM is about to enter the event loop, indicating that all initialization is complete.

```APIDOC
## startup

### Description

AwesomeWM is about to enter the event loop.

### Usage

This means all initialization has been done.
```

--------------------------------

### spawn::timeout

Source: https://github.com/awesomewm/apidoc/blob/gh-pages/core_components/awesome.html

Emitted when an application starts a spawn event but does not start within the allotted time.

```APIDOC
## spawn::timeout

### Description

An application started a spawn event but didn't start in time.
```

--------------------------------

### spawn::timeout

Source: https://github.com/awesomewm/apidoc/blob/gh-pages/core_components/awesome.html

Signal emitted when an application starts a spawn event but doesn't start in time.

```APIDOC
## spawn::timeout

### Description
An application started a spawn event but didn't start in time.
```

--------------------------------

### awesome.startup

Source: https://github.com/awesomewm/apidoc/blob/gh-pages/core_components/awesome.html

A boolean indicating whether AwesomeWM is currently in its startup phase.

```APIDOC
## awesome.startup

### Description
True if we are still in startup, false otherwise.
```

--------------------------------

### Get Widget Index

Source: https://github.com/awesomewm/apidoc/blob/gh-pages/widget_layouts/wibox.layout.ratio.html

Gets the index of a widget within its parent, optionally searching recursively.

```APIDOC
## :index (widget, recursive, ...)

### Description
Get the index of a widget. Returns the widget index, the parent widget, and the hierarchy path.

### Method
N/A (Method signature provided)

### Endpoint
N/A

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
N/A

### Response
#### Success Response (200)
- **number**: The widget index.
- **widget**: The parent widget.
- **table**: The hierarchy path between "self" and "widget".

#### Response Example
N/A

### Parameters:
Name | Type(s) | Description
--- | --- | ---
widget | widget | The widget to look for.
recursive | Optional boolean | Recursively check accross the sub-widgets hierarchy.
... | Optional widget | Additional widgets to add at the end of the sub-widgets hierarchy "path".
```

--------------------------------

### AwesomeWM Widget Usage

Source: https://github.com/awesomewm/apidoc/blob/gh-pages/widget_layouts/wibox.layout.stack.html

Examples demonstrating how to use AwesomeWM widgets, including separators and custom configurations.

```APIDOC
## Widget Usage Examples

### Direct Separator Widget

```lua
local w1 = wibox.widget {
    spacing        = 10,
    spacing_widget = wibox.widget.separator,
    layout         = wibox.layout.fixed.horizontal
}
```

### Declarative Separator Widget

```lua
local w2 = wibox.widget {
    spacing = 10,
    spacing_widget = {
        color  = "#00ff00",
        shape  = gears.shape.circle,
        widget = wibox.widget.separator,
    },
    layout = wibox.layout.fixed.horizontal
}
```

### Composed Widgets

```lua
local w3 = wibox.widget {
    spacing = 10,
    spacing_widget = {
        {
            text   = "F",
            widget = wibox.widget.textbox,
        },
        bg     = "#ff0000",
        widget = wibox.container.background,
    },
    layout = wibox.layout.fixed.horizontal
}
```

### Powerline Effect with Negative Spacing

```lua
local w4 = wibox.widget {
    spacing = -12,
    spacing_widget = {
        color  = "#ff0000",
        shape  = gears.shape.powerline,
        widget = wibox.widget.separator,
    },
    layout = wibox.layout.fixed.horizontal
}
```
```

--------------------------------

### Get Widget Index

Source: https://github.com/awesomewm/apidoc/blob/gh-pages/widget_layouts/wibox.layout.manual.html

Gets the index of a widget within its layout. Can search recursively. Inherited from `wibox.widget.base`.

```APIDOC
## :index

### Description
Get the index of a widget.

### Method
Inherited method

### Endpoint
N/A (Internal method)

### Parameters
#### Path Parameters
- **widget** (widget) - Required - The widget to look for.
- **recursive** (boolean) - Optional - Recursively check across the sub-widgets hierarchy. Default: `false`
- **...** - Optional - Additional widgets to add at the end of the sub-widgets hierarchy "path".
```

--------------------------------

### Initialize Beautiful Theme

Source: https://github.com/awesomewm/apidoc/blob/gh-pages/sample files/rc.lua.html

Initializes the AwesomeWM theme using a specified theme file. Ensure the theme file exists in the default themes directory.

```lua
beautiful.init(gears.filesystem.get_themes_dir() .. "default/theme.lua")
```

--------------------------------

### Get Widget Index and Hierarchy

Source: https://github.com/awesomewm/apidoc/blob/gh-pages/widget_containers/wibox.container.border.html

Get the index of a widget, its parent, and the hierarchy path. Can optionally search recursively.

```lua
o:index (widget, recursive, ...)
```

--------------------------------

### Move Mouse and Spawn Client on Screen 3

Source: https://github.com/awesomewm/apidoc/blob/gh-pages/core_components/client.html

Demonstrates how to move the mouse cursor to a specific screen and spawn a new client on that screen. Ensure screen 3 is available and configured.

```lua
-- Move the mouse to screen 3
mouse.coords {x = 1800, y = 100 }
-- Spawn a client on screen #3
awful.spawn("firefox")
```

--------------------------------

### Configure Root Window Mouse Buttons

Source: https://github.com/awesomewm/apidoc/blob/gh-pages/input_handling/mouse.html

Set up mouse button callbacks for the root window. This example configures button 3 to toggle a main menu, button 4 to view the next tag, and button 5 to view the previous tag.

```lua
root.buttons(awful.util.table.join(
    awful.button({ }, 3, function () mymainmenu:toggle() end),
    awful.button({ }, 4, awful.tag.viewnext),
    awful.button({ }, 5, awful.tag.viewprev)
))
```

--------------------------------

### Run Full Test Suite

Source: https://github.com/awesomewm/apidoc/blob/gh-pages/documentation/10-building-and-testing.md.html

Execute the complete suite of tests for AwesomeWM after building.

```bash
make check
```

--------------------------------

### Basic Prompt Usage with Custom Callback

Source: https://github.com/awesomewm/apidoc/blob/gh-pages/libraries/awful.prompt.html

Demonstrates how to use awful.prompt.run with a custom textbox and an exe_callback to display user input in a notification. Ensure a textbox widget is available and configured.

```lua
local atextbox = wibox.widget.textbox()
-- Create a shortcut function
local function echo_test()
    awful.prompt.run {
        prompt       = "<b>Echo: </b>",
        text         = "default command",
        bg_cursor    = "#ff0000",
        -- To use the default [rc.lua](../sample files/rc.lua.html#) prompt:
        --textbox      = mouse.screen.mypromptbox.widget,
        textbox      = atextbox,
        exe_callback = function(input)
            if not input or #input == 0 then return end
            naughty.notification { message = "The input was: "..input }
        end
    }
end

-- Then **IN THE globalkeys TABLE** add a new shortcut
awful.key({ modkey }, "e", echo_test,
    {description = "Echo a string", group = "custom"}),
```

--------------------------------

### Set Up Screen Desktop Decorations

Source: https://github.com/awesomewm/apidoc/blob/gh-pages/sample files/rc.lua.html

Configures desktop elements for each screen, including creating tag lists, prompt boxes, and layout boxes. Includes custom buttons for tag navigation and manipulation.

```lua
screen.connect_signal("request::desktop_decoration", function(s)
    -- Each screen has its own tag table.
    awful.tag({ "1", "2", "3", "4", "5", "6", "7", "8", "9" }, s, awful.layout.layouts[1])

    -- Create a promptbox for each screen
    s.mypromptbox = awful.widget.prompt()

    -- Create an imagebox widget which will contain an icon indicating which layout we're using.
    -- We need one layoutbox per screen.
    s.mylayoutbox = awful.widget.layoutbox {
        screen  = s,
        buttons = {
            awful.button({ }, 1, function () awful.layout.inc( 1) end),
            awful.button({ }, 3, function () awful.layout.inc(-1) end),
            awful.button({ }, 4, function () awful.layout.inc(-1) end),
            awful.button({ }, 5, function () awful.layout.inc( 1) end),
        }
    }

    -- Create a taglist widget
    s.mytaglist = awful.widget.taglist {
        screen  = s,
        filter  = awful.widget.taglist.filter.all,
        buttons = {
            awful.button({ }, 1, function(t) t:view_only() end),
            awful.button({ modkey }, 1, function(t) 
                                            if client.focus then
                                                client.focus:move_to_tag(t)
                                            end
                                        end),
            awful.button({ }, 3, awful.tag.viewtoggle),
            awful.button({ modkey }, 3, function(t) 
                                            if client.focus then

```

--------------------------------

### Prevent Clients from Starting Maximized

Source: https://github.com/awesomewm/apidoc/blob/gh-pages/documentation/90-FAQ.md.html

Configuration to ensure no application starts maximized by setting `maximized_vertical` and `maximized_horizontal` to false in `ruled.client.rules`.

```lua
-- Search for this rule,
keys = clientkeys,

-- add the following two:
maximized_vertical   = false,
maximized_horizontal = false,
```

--------------------------------

### Example Keygrabber Stop Callback

Source: https://github.com/awesomewm/apidoc/blob/gh-pages/core_components/awful.keygrabber.html

An example of a callback function that can be used when a keygrabber stops. This function receives details about the stop event.

```lua
local function my_done_cb(self, stop_key, stop_mods, sequence)
   -- do something
end
```

--------------------------------

### Sample Theme File Structure

Source: https://github.com/awesomewm/apidoc/blob/gh-pages/documentation/06-appearance.md.html

This is a sample Lua theme file demonstrating default variables for Awesomewm. Uncomment and set variables to customize appearance.

```lua
local theme = {}

-- Default variables
-- theme.useless_gap = nil
-- theme.font = nil
-- theme.bg_normal = nil
-- theme.bg_focus = nil
-- theme.bg_urgent = nil
-- theme.bg_minimize = nil
-- theme.fg_normal = nil
-- theme.fg_focus = nil
-- theme.fg_urgent = nil
-- theme.fg_minimize = nil
-- theme.wallpaper = nil
-- theme.bg_systray = nil
-- theme.border_color_marked = nil
-- theme.border_color_floating = nil
-- theme.border_color_maximized = nil
-- theme.border_color_fullscreen = nil
-- theme.border_color_active = nil
-- theme.border_color_normal = nil
-- theme.border_color_urgent = nil
-- theme.border_color_new = nil
-- theme.border_color_floating_active = nil
-- theme.border_color_floating_normal = nil
-- theme.border_color_floating_urgent = nil
-- theme.border_color_floating_new = nil
-- theme.border_color_maximized_active = nil
-- theme.border_color_maximized_normal = nil
-- theme.border_color_maximized_urgent = nil
-- theme.border_color_maximized_new = nil
-- theme.border_color_fullscreen_active = nil
-- theme.border_color_fullscreen_normal = nil
-- theme.border_color_fullscreen_urgent = nil
-- theme.border_color_fullscreen_new = nil
-- theme.border_width = nil
-- theme.border_width_floating = nil
-- theme.border_width_maximized = nil
-- theme.border_width_normal = nil
-- theme.border_width_active = nil
-- theme.border_width_urgent = nil
-- theme.border_width_new = nil
-- theme.border_width_floating_normal = nil
-- theme.border_width_floating_active = nil
-- theme.border_width_floating_urgent = nil
-- theme.border_width_floating_new = nil
-- theme.border_width_maximized_normal = nil
-- theme.border_width_maximized_active = nil
-- theme.border_width_maximized_urgent = nil
-- theme.border_width_maximized_new = nil
-- theme.border_width_fullscreen_normal = nil
-- theme.border_width_fullscreen_active = nil
-- theme.border_width_fullscreen_urgent = nil
-- theme.border_width_fullscreen_new = nil
-- theme.border_width_fullscreen = nil
```

--------------------------------

### Start Awesome in a Specific Window

Source: https://github.com/awesomewm/apidoc/blob/gh-pages/documentation/17-porting-tips.md.html

Launches AwesomeWM within a Xephyr window of a specified size. Ensure AwesomeWM and its configuration path are correctly set.

```bash
Xephyr :1 -screen 1280x800 &
DISPLAY=:1 $HOME/awesome4_test/bin/awesome \
    -c $HOME/.config/awesome4/rc.lua \
    --search $HOME/awesome4_test/share/awesome/lib
```

```bash
Xephyr :1 -screen 1280x800 &
DISPLAY=:1 awesome
```

--------------------------------

### Start the timer

Source: https://github.com/awesomewm/apidoc/blob/gh-pages/core_components/gears.timer.html

This method initiates the countdown for a timer object. Once started, the timer will begin measuring time until its timeout is reached or it is stopped.

```lua
:start()
```

--------------------------------

### Configure Screen Desktop Decorations

Source: https://github.com/awesomewm/apidoc/blob/gh-pages/documentation/05-awesomerc.md.html

Sets up tags, prompt boxes, layout boxes, and tag lists for each screen. Includes custom button bindings for tag navigation and client movement.

```lua
screen.connect_signal("request::desktop_decoration", function(s)
    -- Each screen has its own tag table.
    awful.tag({ "1", "2", "3", "4", "5", "6", "7", "8", "9" }, s, awful.layout.layouts[1])

    -- Create a promptbox for each screen
    s.mypromptbox = awful.widget.prompt()

    -- Create an imagebox widget which will contain an icon indicating which layout we're using.
    -- We need one layoutbox per screen.
    s.mylayoutbox = awful.widget.layoutbox {
        screen  = s,
        buttons = {
            awful.button({ }, 1, function () awful.layout.inc( 1) end),
            awful.button({ }, 3, function () awful.layout.inc(-1) end),
            awful.button({ }, 4, function () awful.layout.inc(-1) end),
            awful.button({ }, 5, function () awful.layout.inc( 1) end),
        }
    }

    -- Create a taglist widget
    s.mytaglist = awful.widget.taglist {
        screen  = s,
        filter  = awful.widget.taglist.filter.all,
        buttons = {
            awful.button({ }, 1, function(t) t:view_only() end),
            awful.button({ modkey }, 1, function(t)
                                            if client.focus then
                                                client.focus:move_to_tag(t)
                                            end
                                        end),
            awful.button({ }, 3, awful.tag.viewtoggle),
            awful.button({ modkey }, 3, function(t)
                                            if client.focus then
                                                client.focus:toggle_tag(t)
                                            end
                                        end),
        }
    }
```

--------------------------------

### Get or set wibox geometry

Source: https://github.com/awesomewm/apidoc/blob/gh-pages/popups_and_bars/awful.popup.html

Gets or sets the geometry (x, y, width, height) of a wibox. If no geometry is provided, it returns the current geometry.

```lua
:geometry (geo) -> table · Inherited from wibox · 1 signal
Get or set wibox geometry. That's the same as accessing or setting the x, y, width or height properties of a wibox.

### Parameters:

Name
Type(s)
Description
Default value

geo
Optional
[table](https://www.lua.org/manual/5.3/manual.html#6.6) or nil
A table with coordinates to modify. If nothing is specified, it only returns the current geometry.
`nil`
```

--------------------------------

### Example Keygrabber KeyReleased Callback

Source: https://github.com/awesomewm/apidoc/blob/gh-pages/core_components/awful.keygrabber.html

An example of a callback function to be invoked when a key is released while a keygrabber is active. It receives modifier, key, and event information.

```lua
local function my_keyreleased_cb(self, mod, key, command)
   -- do something
end
```

--------------------------------

### Create AwesomeWM Package

Source: https://github.com/awesomewm/apidoc/blob/gh-pages/documentation/10-building-and-testing.md.html

Execute this command to build a .deb or .rpm package for your system's package manager.

```bash
make package
```

--------------------------------

### Example Keygrabber KeyPressed Callback

Source: https://github.com/awesomewm/apidoc/blob/gh-pages/core_components/awful.keygrabber.html

An example of a callback function to be invoked when a key is pressed while a keygrabber is active. It receives modifier, key, and event information.

```lua
local function my_keypressed_cb(self, mod, key, command)
   -- do something
end
```

--------------------------------

### startup

Source: https://github.com/awesomewm/apidoc/blob/gh-pages/core_components/awesome.html

Signal emitted when AwesomeWM is about to enter the event loop, indicating the startup phase.

```APIDOC
## startup

### Description
AwesomeWM is about to enter the event loop.
```

--------------------------------

### Textbox Line Spacing Example

Source: https://github.com/awesomewm/apidoc/blob/gh-pages/widgets/naughty.widget.title.html

Demonstrates the usage of the line_spacing_factor property to control the spacing between lines in a textbox widget. This example shows various spacing values.

```lua
for 
_, spacing in ipairs {0.0, 0.1, 0.5, 0.9, 1, 1.5, 2.0, 2.5} do
    local text = "This text has a line\nspacing of "..tostring(spacing).. "\nunits."

    widget{
        text                = text,
        font                = "sans 10",
        line_spacing_factor = spacing,
        widget              = wibox.widget.textbox,
    }
end

```

--------------------------------

### Install AwesomeWM Desktop Entry

Source: https://github.com/awesomewm/apidoc/blob/gh-pages/documentation/90-FAQ.md.html

Use this command to copy the awesome.desktop file to the correct location for display managers. This ensures AwesomeWM appears on the login screen.

```bash
curl https://raw.githubusercontent.com/awesomeWM/awesome/master/awesome.desktop | sudo tee /usr/share/xsessions/awesome.desktop
```

--------------------------------

### Configure Calendar to Start on Sunday

Source: https://github.com/awesomewm/apidoc/blob/gh-pages/widgets/wibox.widget.calendar.html

Sets up a calendar widget to display week numbers and start the week on Sunday. This configuration is applied via a properties table.

```lua
local cal = wibox.widget {
    date         = os.date("*t"),
    font         = "Monospace 10",
    start_sunday = true,
    widget       = wibox.widget.calendar.month
}
```

--------------------------------

### Get Widget Index

Source: https://github.com/awesomewm/apidoc/blob/gh-pages/widget_containers/wibox.container.place.html

Get the index of a widget within its parent, optionally searching recursively through sub-widgets. Returns the index, parent widget, and hierarchy path.

```lua
:index(widget, recursive, ...)
```

--------------------------------

### Set Wallpaper with Custom DPI and Widget

Source: https://github.com/awesomewm/apidoc/blob/gh-pages/popups_and_bars/awful.wallpaper.html

This example demonstrates setting a wallpaper with a specific screen, custom DPI, and a textbox widget displaying the DPI value. It iterates through available screens to apply the wallpaper.

```lua
for s in screen do
    local dpi = s.index * 100

    awful.wallpaper {
        screen = s,
        dpi    = dpi,
        widget = wibox.widget {
            text   = "DPI: " .. dpi,
            valign = "center",
            halign = "center",
            widget = wibox.widget.textbox,
     }
end
```

--------------------------------

### Example: Stacking Popups with Offset

Source: https://github.com/awesomewm/apidoc/blob/gh-pages/popups_and_bars/awful.popup.html

This example demonstrates how to create multiple popups stacked vertically with a specified y-axis offset between them. It utilizes the `awful.popup` constructor and the `move_next_to` method.

```lua
local previous = nil
    for i=1, 5 do
        local p2 = awful.popup {
            widget = wibox.widget {
                text   = "Hello world!  "..i.."  aaaa.",
                widget = wibox.widget.textbox
            },
            border_color        = beautiful.border_color,
            preferred_positions = "bottom",
            border_width        = 2,
            preferred_anchors   = "back",
            placement           = (not previous) and awful.placement.top or nil,
            offset = {
                 y = 10,
            },
        }
        p2:move_next_to(previous)
        previous = p2
    end
```

--------------------------------

### Wibox Setup

Source: https://github.com/awesomewm/apidoc/blob/gh-pages/popups_and_bars/awful.popup.html

Configures a wibox using a declarative widget hierarchy description.

```APIDOC
## POST /wibox/setup

### Description
Sets a declarative widget hierarchy for the wibox.

### Method
POST

### Endpoint
/wibox/setup

### Parameters
#### Request Body
- **args** (array) - Required - An array containing the widgets disposition.

### Request Example
```json
{
  "args": [
    {
      "widget": "text",
      "text": "Hello World"
    }
  ]
}
```
```

--------------------------------

### Get the next value in a table with cycling

Source: https://github.com/awesomewm/apidoc/blob/gh-pages/utility_libraries/gears.table.html

Use gears.table.cycle_value to get the next or previous value in a table, with optional cycling and filtering. Specify `start_at` for precise control.

```lua
local t = { "a", "b", "c" }
local next_val, next_idx = gears.table.cycle_value(t, "a", 1)
-- next_val will be "b", next_idx will be 2
```