Skip to content

Commit 0cbaee7

Browse files
committed
Update readme
1 parent 1be37e5 commit 0cbaee7

File tree

1 file changed

+28
-14
lines changed

1 file changed

+28
-14
lines changed

README.md

Lines changed: 28 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -12,13 +12,15 @@ A Python tool for controlling the brightness of your monitor. Supports Windows a
1212

1313
#### Note:
1414
For running on Linux you will need to install one of these programs: [light](https://github.com/haikarainen/light), `xrandr` or `xbacklight`
15+
1516
* Arch: `sudo pacman -S light-git` or `sudo pacman -S xorg-xrandr` or `sudo pacman -S xorg-xbacklight`
1617
* Debian/Ubuntu: [Light install instructions](https://github.com/haikarainen/light) or `sudo apt install x11-server-utils` or `sudo apt install xbacklight`
1718
* Fedora: `sudo dnf install light` or `sudo dnf install libXrandr` or `sudo dnf install xbacklight`
1819

1920

2021
# Usage
2122
You can call this module from your command line or use it as a python library (see the documentation section below).
23+
2224
```
2325
python -m screen_brightness_control --help
2426
> usage: __main__.py [-h] [-d DISPLAY] [-s SET] [-g] [-f FADE] [-v]
@@ -41,10 +43,11 @@ python -m screen_brightness_control -s 50
4143
```
4244

4345
# Documentation
44-
### ScreenBrightnessError(`Exception`)
45-
**Summary:**
46-
Raised by `set_brightness` and `get_brightness` when the brightness cannot be set or retrieved
47-
Used as a unifying class for the multiple error types to make it easier to handle exceptions
46+
47+
There is full documentation for this project hosted [here](https://crozzers.github.io/screen_brightness_control) but here are the basics
48+
49+
### ScreenBrightnessError(`Exception`)
50+
A generic error class designed to make catching errors under one umbrella easy. Raised when the brightness cannot be set/retrieved.
4851

4952
**Usage:**
5053
```python
@@ -61,7 +64,8 @@ except sbc.ScreenBrightnessError as error:
6164
Returns the current screen brightness as a percentage by default. If you're on Windows it may return a list of values if you have multiple, brightness adjustable monitors.
6265
Raises `ScreenBrightnessError` upon failure
6366

64-
**Arguments:**
67+
**Arguments:**
68+
6569
* `verbose_error` - a boolean value to control how much detail any error messages should contain
6670
* `kwargs` - passed to the OS relevant brightness method
6771

@@ -83,7 +87,8 @@ secondary_display_brightness = sbc.get_brightness(display=1)
8387
Sets the brightness to `value`. If `value` is a string and contains "+" or "-" then that value is added to/subtracted from the current brightness.
8488
Raises `ScreenBrightnessError` upon failure
8589

86-
**Arguments:**
90+
**Arguments:**
91+
8792
* `value` - the level to set the brightness to. Can either be an integer or a string.
8893
* `force` (Linux only) - if set to `False` then the brightness is never set to less than 1 because on Linux this often turns the screen off. If set to `True` then it will bypass this check
8994
* `verbose_error` - a boolean value to control how much detail any error messages should contain
@@ -115,7 +120,8 @@ sbc.set_brightness(50, display=0)
115120
Fades the brightness from `start` to `finish` in steps of `increment`, pausing for `interval` seconds between each step.
116121
If it runs in the main thread it will return the final brightness upon success, `ScreenBrightnessError` upon failure. Otherwise it returns the list of thread objects that the process is running in
117122

118-
**Arguments:**
123+
**Arguments:**
124+
119125
* `finish` - The brightness value to fade to
120126
* `start` - The value to start from. If not specified it defaults to the current brightness
121127
* `interval` - The time interval between each step in brightness
@@ -157,34 +163,42 @@ If you have any suggestions feel free to raise an [issue](https://github.com/Cro
157163
[pull request](https://github.com/Crozzers/screen_brightness_control/pulls) or to [ping me an email](mailto:[email protected])
158164

159165
### Why do I always get `ScreenBrightnessError` on Linux?
160-
**Why this happens:**
166+
**Why this happens:**
161167
The way brightness is adjusted on Linux is the program tries to run shell commands to adjust the brightness.
162168
The programs it attempts to call are "light", "xrandr" and "xbacklight".
163169
If none of these programs can be called a `ScreenBrightnessError` is raised
164-
**How to fix it:**
170+
171+
**How to fix it:**
165172
Install light (recommended), xrandr or xbacklight using your system package manager:
173+
166174
* Arch: `sudo pacman -S light-git` or `sudo pacman -S xorg-xrandr` or `sudo pacman -S xorg-xbacklight`
167175
* Debian/Ubuntu: [Light install instructions](https://github.com/haikarainen/light) or `sudo apt install x11-server-utils` or `sudo apt install xbacklight`
168176
* Fedora: `sudo dnf install light` or `sudo dnf install libXrandr` or `sudo dnf install xbacklight`
169177

178+
170179
### I call `set_brightness()` and nothing happens on Linux
171-
**Why this happens:**
180+
**Why this happens:**
172181
Light requires root access to run, which is usually provided when you manually install it using you package manager.
173182
If you installed xbacklight or xrandr, it only supports Intel (and sometimes NVidia) graphics, not AMD.
174-
**How to fix it:**
183+
184+
**How to fix it:**
175185
Install Light by following [these steps](https://github.com/haikarainen/light#installation). Make sure to run the install as sudo
176186

187+
177188
### Using the `display` kwarg does nothing/creates exceptions on Linux
178-
**Why this happens:**
189+
**Why this happens:**
179190
The `display` kwarg is only supported by the `Light` and `XRandr` classes, not by `XBacklight`. So if you only have `xbacklight` installed on your system this kwarg will not work
180-
**How to fix it:**
191+
192+
**How to fix it:**
181193
Install light (recommended) or xrandr using your system package manager:
194+
182195
* Arch: `sudo pacman -S light-git` or `sudo pacman -S xorg-xrandr`
183196
* Debian/Ubuntu: [Light install instructions](https://github.com/haikarainen/light) or `sudo apt install x11-server-utils`
184197
* Fedora: `sudo dnf install light` or `sudo dnf install libXrandr`
185198

199+
186200
### The model of my monitor/display is not what the program says it is (Windows)
187-
**Why this happens:**
201+
**Why this happens:**
188202
If your display is a laptop screen and can be adjusted via a Windows brightness slider then there is no easy way to get the monitor model that I am aware of.
189203
If your display is a desktop monitor with a Virtual Control Panel (VCP) then there is a way to get the actual model, but the function call takes
190204
anywhere between 1 and 2 seconds to run, which is why it doesn't automatically.

0 commit comments

Comments
 (0)