From 14af07f5dcbb22533e5bd1898ae04d9ac9d25283 Mon Sep 17 00:00:00 2001 From: Chris Guillott Date: Tue, 30 May 2017 16:46:43 -0400 Subject: [PATCH] update docs --- README.md | 18 +++---- i3lock.1 | 142 +++++++++++++++++++++++++++++++++++++++++++++++++++++- i3lock.c | 9 ++-- 3 files changed, 154 insertions(+), 15 deletions(-) diff --git a/README.md b/README.md index 985a54b..8e3d96d 100644 --- a/README.md +++ b/README.md @@ -30,25 +30,28 @@ Many little improvements have been made to i3lock over time: - `--bshlcolor=rrggbbaa` -- Backspace highlight segments - `--line-uses-ring`, `-r` -- the line between the inside and outer ring uses the ring color for its color - `--line-uses-inside`, `-s` -- the line between the inside and outer ring uses the inside color for its color + - The following additional options have been added: - `-S, --screen` -- specifies which display to draw the unlock indicator on - `-k, --clock` -- enables the clock display. - - `-B, --blur` -- enables Gaussian blur + - `--indicator` -- forces the indicator to always show, even if there's no activity. + - `-B=sigma, --blur` -- enables Gaussian blur. Sigma is the blur radius. + - Note: You can still composite images over the blur (but still under the indicator) with -i. + - Eventually there might be an `imagepos` arg, similar to `time` and `datepos`. - `--timestr="%H:%M:%S"` -- allows custom overriding of the time format string. Accepts `strftime` formatting. Default is `"%H:%M:%S"`. - - `--timepos="ix:iy-20"` -- position of the time. Expressions using the variables w (screen width), h (screen height), ix (indicator x position) and iy (indicator y position) can be used. + - `--timepos="ix:iy-20"` -- position of the time. Expressions using the variables x (current screen's x value), y (current screen's y value), w (screen width), h (screen height), ix (indicator x position), iy (indicator y position) cw (clock width), and ch (clock height) can be used.. - `--timecolor=rrggbbaa` -- color of the time string - `--timefont="sans-serif"` -- font used for the time display - `--timesize=32` -- font size for the time display - `--datestr="%A, %m %Y"` -- allows custom overriding of the date format string. Accepts `strftime` formatting. Default is `"%A, %m %Y"`. - - `--datepos="ix:iy-20"` -- position of the date. Expressions using the variables w (screen width), h (screen height), ix (indicator x position), iy (indicator y position), tx (time x) and ty (time y) can be used. + - `--datepos="ix:iy-20"` -- position of the date. All the variables in `timepos` can be used here, as well as the additional values tx (time x) and ty (time y). - `--datecolor=rrggbbaa` -- color of the date string - `--datefont="sans-serif"` -- font used for the date display - `--datesize=14` -- font size for the date display - - All the colors have an alpha channel now. Please keep in mind that this was not intended when the program was originally written, so making things transparent that weren't before can make it look strange. - You can specify whether i3lock should bell upon a wrong password. - i3lock uses PAM and therefore is compatible with LDAP etc. - On OpenBSD i3lock uses the bsd_auth(3) framework. + On OpenBSD i3lock uses the bsd\_auth(3) framework. Requirements ------------ @@ -81,11 +84,6 @@ press enter. On OpenBSD the `i3lock` binary needs to be setgid `auth` to call the authentication helpers, e.g. `/usr/libexec/auth/login_passwd`. -Example usage for colors: - -i3lock-color --insidevercolor=0000a0bf --insidewrongcolor=ff8000bf --insidecolor=ffffffbf --ringvercolor=0020ffff --ringwrongcolor=4040ffff --ringcolor=404090ff --textcolor=ffffffff --separatorcolor=aaaaaaff --keyhlcolor=30ccccff --bshlcolor=ff8000ff -r - - Upstream -------- Please submit pull requests for i3lock things to https://github.com/i3/i3lock and pull requests for color things to me at https://github.com/chrjguill/i3lock-color. diff --git a/i3lock.1 b/i3lock.1 index 1506e2f..653b790 100644 --- a/i3lock.1 +++ b/i3lock.1 @@ -14,7 +14,7 @@ i3lock-color \- improved screen locker .SH SYNOPSIS -.B i3lock-color +.B i3lock .RB [\|\-v\|] .RB [\|\-n\|] .RB [\|\-b\|] @@ -110,6 +110,146 @@ Show the number of failed attempts, if any. Enables debug logging. Note, that this will log the password used for authentication to stdout. +.SH i3lock-color options +.TP +.B \-S=number, \-\-screen=number +Specifies which display to draw the unlock indicator and clock on. By default, they'll be placed on every screen. +Note that this number is zero indexed. The ordering is dependent on libxinerama. + +.TP +.B \-B=sigma, \-\-blur=sigma +Captures the screen and blurs it using the given sigma (radius). +Images may still be overlaid over the blurred screenshot. + +.TP +.B \-\-indicator +Forces the indicator to always be visible, instead of only showing on activity. + +.TP +.B \-\-insidevercolor=rrggbbaa +Sets the interior circle color while the password is being verified. + +.TP +.B \-\-insidewrongcolor=rrggbbaa +Sets the interior circle color for during flash for an incorrect password. + +.TP +.B \-\-insidecolor=rrggbbaa +Sets the default "resting" color for the interior circle. + +.TP +.B \-\-ringvercolor=rrggbbaa +Sets the ring color while the password is being verified. + +.TP +.B \-\-ringwrongcolor=rrggbbaa +Sets the ring color during the flash for an incorrect password. + +.TP +.B \-\-ringcolor=rrggbbaa +Sets the default ring color. + +.TP +.B \-\-linecolor=rrggbbaa +Sets the color for the line separating the inside circle, and the outer ring. + +.TP +.B \-\-line\-uses\-ring +Conflicts with \-\-line\-uses\-inside. Overrides \-\-linecolor. The line will match the ring color. + +.TP +.B \-\-line\-uses\-inside +Conflicts with \-\-line\-uses\-ring. Overrides \-\-linecolor; the line will match the inside color. + +.TP +.B \-\-keyhlcolor=rrggbbaa +Sets the color of the ring 'highlight' strokes that appear upon keypress. + +.TP +.B \-\-bshlcolor=rrggbbaa +Sets the color of the ring 'highlight' strokes that appear upon backspace. + +.TP +.B \-\-separatorcolor=rrggbbaa +Sets the color of the 'separtor', which is at both ends of the ring highlights. + +.TP +.B \-\-textcolor=rrggbbaa +Sets the color of the status text ("verifying...", "wrong!", etc). + +.TP +.B \-\-timecolor=rrggbbaa +Sets the color of the time in the clock. + +.TP +.B \-\-timestr="%H:%M:%S" +Sets the format used for generating the time string. See strftime(3) for a full list of format specifiers. + +.TP +.B \-\-timefont=sans-serif +Sets the font used to render the time string. + +.TP +.B \-\-timesize=32 +Sets the font size for rendering the time string. + +.TP +.B \-\-timepos="x position:y position" +Sets the position for the time string. Valid variables include: + +.RS +.RS +x - x position of the current display. Corresponds to the leftmost row of pixels on that display. + +y - y position of the current display. Corresponds to the topmost row of pixels on that display. + +w - width of the current display. + +h - height of the current display. + +ix - the x value of the indicator on the current display. + +iy - the y value of the indicator on the current display. + +cw - the clock width. + +ch - the clock height. + +.RE +.RE + +.TP +.B \-\-datecolor=rrggbbaa +Sets the color of the date in the clock. + +.TP +.B \-\-datestr="%A, %m %Y +Sets the format used for generating the date string. See strftime(3) for a full list of format specifiers. +.TP +.B \-\-datefont=sans-serif +Sets the font used to render the date string. + +.TP +.B \-\-datesize=14 +Sets the font size for rendering the date string. + +.TP +.B \-\-datepos="x position:y position" +Sets the position for the date string. All the variables from \-\-timepos may be used, in addition to: + +.RS +.RS +tx - the computed x value of the timestring, for the current display. + +ty - the computed y value of the timestring, for the current display. + +.RE +.RE + +.TP +.B \-\-refresh\-rate=seconds +The refresh rate of the indicator, given in seconds. This should automatically align itself, but is somewhat buggy currently. + .SH DPMS The \-d (\-\-dpms) option was removed from i3lock in version 2.8. There were diff --git a/i3lock.c b/i3lock.c index f9e15c4..6e05332 100644 --- a/i3lock.c +++ b/i3lock.c @@ -908,7 +908,8 @@ int main(int argc, char *argv[]) { {"separatorcolor", required_argument, NULL, 0}, {"line-uses-ring", no_argument, NULL, 'r'}, {"line-uses-inside", no_argument, NULL, 's'}, - /* s for in_s_ide; ideally I'd use -I but that's used for timeout, which should use -T, but compatibility argh */ + /* s for in_s_ide; ideally I'd use -I but that's used for timeout, which should use -T, but compatibility argh + * note: `I` has been deprecated for a while, so I might just remove that and reshuffle that? */ {"screen", required_argument, NULL, 'S'}, {"clock", no_argument, NULL, 'k'}, @@ -1227,9 +1228,9 @@ int main(int argc, char *argv[]) { break; default: // TODO: clean this up, use newlines - errx(EXIT_FAILURE, "Syntax: i3lock-color [-v] [-n] [-b] [-d] [-c color] [-u] [-p win|default]" - " [-i image.png] [-t] [-e] [-I timeout] [-f] [-r|s] [-S screen_number] [-k]" - " [-B blur_strength] [--indicator] [--refresh-rate rate] [--variety-of-color-args=rrggbbaa] [--[time|date][pos|color|font|size]=[arg]]\n"); + errx(EXIT_FAILURE, "Syntax: i3lock [-v] [-n] [-b] [-d] [-c color] [-u] [-p win|default]" + " [-i image.png] [-t] [-e] [-f]\n" + "Please see the manpage for a full list of arguments."); } }