:thumbsup:nice

If you would like to show your appreciation for this project,
please consider a donation :)

N.B. This branch is for Awesome v4.3 git. You can find the branch for Awesome v4.3 stable here

nice is an easy to use, highly configurable extension for Awesome WM that adds beautiful window decorations (and extra functionality!) to clients. It...

• ...adds a subtle 3D look, and soft, rounded anti-aliased, corners to windows
• ...picks the window decoration color based on the client content for a seamless look , and adjusts the window title text color accordingly
• ...auto-generates titlebar buttons (and their states) for you based on the colors your pick or you can let it pick the colors for you!
• ...allows you to customize which titlebar buttons to include, their order, and their layout
• ...adds the ability to maximize/unmaximize floating windows by double clicking the titlebar, and of course, moving them by clicking and holding
• ...adds the ability to "roll up" and "roll down" the client window like a window shade! Scroll up over the titlebar to instantly hide the window contents but keep the title bar right where it is. And then either scroll down or click the titlebar to make the window contents visible again!

Getting Started

Prerequisites

• You need Awesome WM with a working basic configuration. This branch is for Awesome v4.3 git. You can find the branch for Awesome v4.3 stable here

• You also need picom. Make sure you have

  shadow-ignore-shaped = false

  in your configuration otherwise picom will not draw shadows. My recommended shadow settings are given below:

  shadow = true;
  shadow-radius = 40;
  shadow-opacity = .55;
  shadow-offset-x = -40;
  shadow-offset-y = -20;
  shadow-exclude = [
    "_NET_WM_WINDOW_TYPE:a = '_NET_WM_WINDOW_TYPE_NOTIFICATION'",
    "[email protected]:32a *= '_NET_WM_STATE_HIDDEN'",
    "[email protected]:c"
  ];
  shadow-ignore-shaped = false

• For GTK applications add the following line to ~/.config/gtk-3.0/settings.ini under the [Settings] section to hide client-side window control buttons:

  gtk-decoration-layout=menu:

• Within you Awesome configuration, make sure that you do not already have code in place that request default titlebars for clients. Something like this:

client.connect_signal("request::titlebars", function(c) ... end) -- Remove this

• Additionally, nice only adds window decorations to clients that have the

  titlebars_enabled

  property set to true. So configure your client rules accordingly.

Installation

The easiest and quickest way to get started is by cloning this repository to your awesome configuration directory

$ cd ~/.config/awesome
$ git clone https://github.com/mut-ex/awesome-wm-nice.git nice

Usage

To use nice, you first need to load the module. To do that, put the following line right after

beautiful.init(...)

local nice = require("nice")
nice()

If you are fine using the default configuration, you are all done!

nice will automatically detect and change the window decoration color to match the client. However...

• To pick the window decoration color yourself, right-click the titlebar and select 'Manually Pick Color'
• To update the window decoration colors, right-click on the titlebar and select 'Redo Window Decorations'
• Scroll-up with your mouse over the titlebar to "roll up" the window shade. Scroll-down over the titlebar, or left-click to "roll down" the window shade
• nice saves its color rules in the color_rules file within the module directory. If you wish you can manually edit it, or delete the file if you want to start again.

Configuration

You can override the defaults by passing your own configuration. For example

local nice = require("nice")
nice {
    titlebar_color = "#00ff00",

-- You only need to pass the parameter you are changing
context_menu_theme = {
    width = 300, 
},

-- Swap the designated buttons for resizing, and opening the context menu
mb_resize = nice.MB_MIDDLE,
mb_contextmenu = nice.MB_RIGHT,
}

Below you will find further details explaining the configuration parameters for nice.

| Parameter | Type | Description | Default | | --------------------- | :--: | ----------- | ------------------- | |

titlebar_height

38

titlebar_radius

>= 3

<= titlebar_height

9

titlebar_color

"#1e1e24"

titlebar_padding_left

0

titlebar_padding_right

0

titlebar_font

"Sans 11"

win_shade_enabled

true

no_titlebar_maximized

false

mb_move

nice.MB_LEFT

mb_contextmenu

nice.MB_MIDDLE

mb_resize

nice.MB_RIGHT

mb_win_shade_rollup

nice.MB_SCROLL_UP

mb_win_shade_rolldown

nice.MB_SCROLL_DOWN

button_size

button_margin_horizontal

button_margin_left

button_margin_right

button_margin_vertical

button_margin_top

button_margin_bottom

button_margin_top

button_margin_bottom

button_margin_left

button_margin_right

tooltips_enabled

close_color

minimize_color

maximize_color

floating_color

ontop_color

sticky_color

In addition to the above mentioned parameters, there some more parameters that require a little more explanation:

titlebar_items

titlebar_items

• It should be a table with the following keys:

  • left

    — Specifies the item(s) to place on the left side of the titlebar

  • middle

    — Specifies the item(s) to place in the middle of the titlebar

  • right

    — Specifies the items(s) to place on the right side of the titlebar
• Multiple items should be passed as an array of identifiers. For a single item simply passing the identifier is sufficient
• Valid titlebar item identifiers are:

  • "close"

  • "minimize"

  • "maximize"

  • "floating"

  • "ontop"

  • "sticky"

  • "title"

• Default value for

  titlebar_items

  is:

titlebar_items = {
    left = {"close", "minimize", "maximize"},
    middle = "title",
    right = {"sticky", "ontop", "floating"},
}

contextmenutheme

context_menu_theme

• It should be a table with the following keys:

  • ​bg_focus

    — Background color of focused menu item

  • bg_normal

    — Background color of not-focused menu items

  • ​border_color

    — Color of the border around the entire menu

  • ​border_width

    — Width of the border around the entire menu

  • ​fg_focus

    — Foreground color of focused menu item

  • ​fg_normal

    — Foreground color of not-focused menu items

  • ​font

    — Font used for menu text

  • ​height

    — Height of each menu list item

  • ​width

    — Width of the menu
• Default value for

  context_menu_theme

  is:

context_menu_theme = {
    bg_focus = "#aed9e0",
    bg_normal = "#5e6472",
    border_color = "#00000000",
    border_width = 0,
    fg_focus = "#242424",
    fg_normal = "#fefefa",
    font = "Sans 11",
    height = 27.5,
    width = 250,
}

tooltip_messages

tooltip_messages

• It should be a table with the following keys:

  • close

    — Text shown when hovering over the close button

  • minimize

    — Text shown when hovering over the minimize button

  • maximize_active

    — Text shown when hovering over the maximize button when the window is maximized

  • maximize_inactive

    — Text shown when hovering over the maximize button when the window is not maximized

  • floating_active

    — Text shown when hovering over the floating button when the window is floating

  • floating_inactive

    — Text shown when hovering over the floating button when the window is tiled

  • ontop_active

    — Text shown when hovering over the ontop button when the window is set to be above other windows

  • ontop_inactive

    — Text shown when hovering over the ontop button when the window is not set to be above other windows

  • sticky_active

    — Text shown when hovering over the sticky button when the window is set to be available on all tags

  • sticky_inactive

    — Text shown when hovering over the sticky button when the window is not to be available on all tags

The default value for

tooltip_messages

tooltip_messages = {
    close = "close",
    minimize = "minimize",
    maximize_active = "unmaximize",
    maximize_inactive = "maximize",
    floating_active = "enable tiling mode",
    floating_inactive = "enable floating mode",
    ontop_active = "don't keep above other windows",
    ontop_inactive = "keep above other windows",
    sticky_active = "disable sticky mode",
    sticky_inactive = "enable sticky mode",
}

Using

nice will automatically detect and change the window decoration color to match the client. However...

• If nice doesn't pick the right color or you want to specify it yourself, right-click the titlebar and select 'Manually Pick Color'
• If the client theme changes (for example if you change your terminal emulator colors), to update the window decoration colors, right-click on the titlebar and select 'Redo Window Decorations'
• Scroll-up with your mouse over the titlebar to "roll-up" the window shade. Scroll-down over the titlebar, or left-click to "roll-down" the window shade
• nice saves its color rules in the color_rules file within the module directory. If you wish you can manually edit it, or delete the file if you want to start again.

Issues

If you face any bugs or issues (or have a feature request), please feel free to open an issue on here

License