diff --git a/documentation/content/en/books/accessibility/colors/_index.adoc b/documentation/content/en/books/accessibility/colors/_index.adoc index 6de26c0398..f3cda2106c 100644 --- a/documentation/content/en/books/accessibility/colors/_index.adoc +++ b/documentation/content/en/books/accessibility/colors/_index.adoc @@ -1,490 +1,608 @@ --- title: Chapter 3. Colors part: Part II. Vision prev: books/accessibility/virtual-terminal next: books/accessibility/lowvision description: Features to set up colors tags: ["Accessibility", "High contrast", "Color blindness", "Theming"] showBookMenu: true weight: 6 params: path: "/books/accessibility/colors/" --- [[colors]] = High Contrast :doctype: book :toc: macro :toclevels: 1 :icons: font :sectnums: :sectnumlevels: 6 :sectnumoffset: 3 :partnums: :source-highlighter: rouge :experimental: :images-path: books/accessibility/colors/ ifdef::env-beastie[] ifdef::backend-html5[] :imagesdir: ../../../../images/{images-path} endif::[] ifndef::book[] include::shared/authors.adoc[] include::shared/mirrors.adoc[] include::shared/releases.adoc[] include::shared/attributes/attributes-{{% lang %}}.adoc[] include::shared/{{% lang %}}/teams.adoc[] include::shared/{{% lang %}}/mailing-lists.adoc[] include::shared/{{% lang %}}/urls.adoc[] toc::[] endif::[] ifdef::backend-pdf,backend-epub3[] include::../../../../../shared/asciidoctor.adoc[] endif::[] endif::[] ifndef::env-beastie[] toc::[] include::../../../../../shared/asciidoctor.adoc[] endif::[] [[colors-intro]] == Introduction This chapter explains how to configure colors for on-screen elements, including: - Setting high-contrast color schemes in graphical environments. - Adapting screen color temperature for optimal viewing in daylight and nighttime conditions. - Selecting colors for configuration ports menus. [[high-contrast-theme]] == High Contrast Theme Graphical Environments allow you to easily install and set up graphical themes. This paragraph describes how to configure high contrast themes for windows. [[xfce-high-contrast]] === XFCE Download from https://www.xfce-look.org/p/2289345[High Contrast Windows 11 Themes]: - _Adwaita-Dusk.tar.bz2_ - _Adwaita-Desert.tar.bz2_ - _Adwaita-Aquatic.tar.bz2_ - _Adwaita-NightSky.tar.bz2_ The example is for _NightSky_, but of course you can choose whichever theme you prefer. [source,shell] .... % tar xzvf Adwaita-NightSky.tar.bz2 <1> % mkdir ~/.themes <2> % cp -a Adwaita-NightSky ~/.themes/ <3> % rm Adwaita-NightSky.tar.bz2 <4> % xfconf-query -c xfwm4 -p /general/theme -s 'Adwaita-NightSky' <5> % xfconf-query -c xsettings -p /Net/ThemeName -s 'Adwaita-NightSky' <6> .... <.> Extract the downloaded theme archive. <.> Create the [.filename]#~/.themes# directory if it does not already exist. <.> Copy the extracted themes into [.filename]#~/.themes#. <.> Optionally, delete the original compressed file to save space. <.> Apply the Adwaita-NightSky theme for the XFCE desktop environment. <.> Apply the Adwaita-NightSky theme for GTK applications. The theme selection steps (5 and 6) can also be performed using the graphical configuration dialogs in XFCE: [source,shell] .... % xfwm4-settings % xfce4-appearance-settings .... [[high-contrast-icon]] == High Contrast Icons Graphical Environments allow you to easily install and set up icon themes. This paragraph describes how to configure high contrast icons. [[xfce-icon-high-contrast]] === XFCE Run the following commands to use the _Treepata - High Contrast_ icons theme with XFCE. Download _Treepata.zip_ from https://www.xfce-look.org/p/1015854[Treepata - High contrast]. Then execute: [source,shell] .... # pkg search zip <1> % unzip Treepata.zip <2> % mkdir ~/.icons <3> % cp -a Treepata ~/.icons/ <4> % rm Treepata.zip <5> % xfconf-query -c xsettings -p /Net/IconThemeName -s Treepata <6> .... <.> Install the package package:archivers/zip[]: <.> Extract the downloaded archive file. <.> Create the [.filename]#~/.icons# directory if it does not already exist. <.> Copy the extracted theme into [.filename]#~/.icons#. <.> Optionally, delete the downloaded archive file to free up space. <.> Set the _Treepata_ icon theme. The icon theme (step 6 above) can also be set graphically via the `_Appearance_` dialog under the `_Icons_` tab. To do so, open the dialog and select your preferred icon theme: [source,shell] .... % xfce4-appearance-settings .... [NOTE] ==== If you have icon theme problems, install package:misc/hicolor-icon-theme[] and package:graphics/gtk-update-icon-cache[]: [source,shell] .... # pkg install hicolor-icon-theme gtk-update-icon-cache .... Run man:gtk-update-icon-cache[1] to create or update the icon cache: [source,shell] .... % gtk-update-icon-cache -f -t ~/.icons/treepata .... ==== [[colors-temperature]] == Color temperature This paragraph explains various utilities that adjust screen colors based on temperature, day/night cycles, and gamma settings. These utilities enable both interactive color adjustments and automatic changes based on the local time and geographical location. Some utilities are compatible with the extref:{handbook}x11[X Window System], others support extref:{handbook}wayland[Wayland], and some work on both display servers. .Color Temperature Utilities [options="header", cols="1,1,1,1"] |=== | Name | Auto Update | Environment | Package | darkman | Yes | X11 | package:accessibility/darkman[] | gammastep | Yes | X11 | package:accessibility/gammastep[] | redshift | Yes | X11, Wayland | package:accessibility/redshift[] | sct | No | X11 | package:accessibility/sct[] | sctd | Yes | X11 | package:accessibility/sctd[] | wlsunset | Yes | Wayland | package:accessibility/wlsunset[] |=== The rest of this section details the steps to install, configure, and launch the utilities. [[colors-darkman]] === darkman man:darkman[1] is a daemon that automatically manages transitions between dark mode and light mode. It operates primarily in the background, switching the screen's color scheme based on the local time of the current location. To install, run: [source,shell] .... # pkg install darkman .... Create the file [.filename]#~/.config/darkman/config.yaml# and write your latitude and longitude. Example: [.programlisting] .... lat: 37.52 lng: 122.16 .... The utility does not directly change the screen colors; instead, it calls external utilities to perform the color transitions. Add scripts to be executed at sundown by placing them in [.filename]#$XDG_DATA_DIRS/dark-mode.d/# and scripts to be executed at sunrise by placing them in [.filename]#XDG_DATA_DIRS/light-mode.d/#. Several https://gitlab.com/WhyNotHugo/darkman/-/tree/main/examples[example scripts] are available in the project repository. To start darkman manually, run: [source,shell] .... % darkman run & .... The utility also offers some interactive options; for more details refer to the man:darkman[1] manual page. [[gammastep]] === gammastep The man:gammastep[1] utility adjusts your screen’s color temperature automatically based on your location. To install, run: [source,shell] .... # pkg install gammastep .... The utility works out of the box without any configuration. Simply start it by running: [source,shell] .... % gammastep & .... [NOTE] ==== If you encounter any issues, customize the configuration by adapting the link:https://gitlab.com/chinstrap/gammastep/-/blob/master/gammastep.conf.sample[gammastep.conf.sample] file and save it as [.filename]#~/.config/gammastep/conf.ini#. Refer to the link:https://gitlab.com/chinstrap/gammastep/-/blob/master/README.md[README] for troubleshooting. ==== [[redshift]] === redshift The man:redshift[1] utility find your position and sets the color temperature accordingly. To install, execute: [source,shell] .... # pkg install redshift .... The redshift utility runs without any configuration. To start it, simply execute: [source,shell] .... % redshift & .... The utility might hang while trying to determine the location or the correct method to set the color. In this case, specify them explicitly using `-l _latitude:longitude_` and `-m _method_`. The available methods can be listed by running: `% redshift -m list`. Example of running redshift with an explicit location and method: [source,shell] .... % redshift -l 37.86:-122.27 -m randr & .... To make this setting permanent, add the following lines to [.filename]#~/.config/redshift/redshift.conf# file: [.programlisting] .... [redshift] adjustment-method=randr location-provider=manual [manual] lat=37.86 lon=-122.27 .... [NOTE] ==== The project provides a default https://github.com/jonls/redshift/blob/master/redshift.conf.sample[redshift.conf.sample] configuration file. For troubleshooting and additional information, please refer to the https://github.com/jonls/redshift/blob/master/README.md[README]. ==== [[sct]] === sct The man:sct[1] utility is a simple command-line tool for controlling screen color temperature. It does not update automatically and must be run repeatedly to adjust the temperature over time. To install, execute: [source,shell] .... # pkg install sct .... The utility takes temperature values between 1000 and 10000, 6500 is the default. To run sct, type: `sct _value_`: [source,shell] .... % sct 8000 .... [TIP] ==== The utility suggests 3 styles: 1) Campfire style [source,shell] .... % sct 4500 .... 2) Dust storm on Mars style [source,shell] .... % sct 2000 .... 3) Coffee free all nighter style [source,shell] .... % sct 8000 .... ==== [[sctd]] === sctd The sctd utility calculates sunrise and sunset times based on latitude and longitude, and adjusts the screen's color temperature accordingly. To install, run: [source,shell] .... # pkg install sctd .... To run sctd, specify your location using the `--latitude` and `--longitude` options: [source,shell] .... % sctd --latitude 40.55 --longitude 14.34 & .... To reset the screen color to default, run: [source,shell] .... % sctd --reset .... [[wlsunset]] === wlsunset The man:wlsunset[1] utility is a Day/Night gamma adjustments for Wayland compositors. To install, execute: [source,shell] .... # pkg install wlsunset .... To start the utility type `wlsunset -l _latitude_ -L _longitude_`. Example: [source,shell] .... % wlsunset -l 14.34 -L 40.55 & .... [[colors-ports]] == Ports Collection FreeBSD provides the extref:{handbook}ports[Ports Collection], which offers a simple way to install applications. Some ports allow you to configure options before building and installation. By default, configuration is handled through a TUI menu built by the package:ports-mgmt/portconfig[]. The colors can be customized in several ways: . Terminal color capabilities. . The $NO_COLOR environment variable. . The $PORTCONFIG_THEMEFILE environment variable. . The global [.filename]#/usr/local/etc/portconfig/theme.conf# file. [NOTE] ==== These methods are listed in order of decreasing priority and are mutually exclusive, meaning only one can be active at a time. ==== *1. Terminal Colors* man:portconfig[1] automatically detects whether the terminal supports colors. If not, it defaults to a black-and-white theme. *2. NO_COLOR* If the `$NO_COLOR` environment variable is set and not empty, portconfig forces the black-and-white theme .Example persistent setting `$NO_COLOR` [example] ==== [.filename]#/etc/make.conf# [.programlisting] .... export NO_COLOR=YES .... ==== *3. PORTCONFIG_THEMEFILE* If the `$PORTCONFIG_THEMEFILE` environment variable is set and points to a valid theme file, it will be used. Otherwise, the default theme is applied. ..Example persistent setting `$PORTCONFIG_THEMEFILE` [example] ==== [.filename]#/etc/make.conf# [.programlisting] .... export PORTCONFIG_THEMEFILE=/home/foo/mytheme.conf .... ==== [TIP] ==== To create a new theme file, run: [source,shell] .... % /usr/local/bin/bsddialog --save-theme mytheme.conf --infobox "Saving theme..." 0 0 .... ==== *4. Global theme.conf* If the file [.filename]#/usr/local/etc/portconfig/theme.conf# exists and is valid, it will be used. If not, the default theme is applied. [TIP] ==== Sample themes are included in [.filename]#/usr/local/etc/portconfig/#: - blackwhite.conf - default.conf - red-green.conf - yellow-blue.conf To use the yellow-blue.conf theme: [source,shell] .... # ln -s /usr/local/etc/portconfig/yellow-blue.conf /usr/local/etc/portconfig/theme.conf .... ==== + +[[brightness]] +== Brightness + +Screen brightness can be adjusted in various ways. +The available methods depend heavily on the hardware, so it's recommended to try the features described in the following sections. + +[[backlight]] +=== backlight + +The man:backlight[8] utility is included with the operating system. +It is used to set the brightness of devices located under [.filename]#/dev/backlight/#. + +The command `backlight -f _device_ _value_` sets the brightness of _device_ to _value_, where _value_ is an integer between 0 (dim) and 100 (bright). +If no device is specified, the default device [.filename]#/dev/backlight/backlight0# is considered. + +Example for setting the brightness of the default device to 50%: + +[source,shell] +.... +% backlight 50 +.... + +[NOTE] +==== +Unless the user belongs to the "video" group, the command needs to run as root. +==== + +[[acpi_video]] +=== acpi_video + +The man:acpi_video[4] driver, included with the operating system, uses the ACPI Video Extensions to control display switching and backlight brightness. +To load the kernel module, run: + +[source,shell] +.... +# kldload acpi_video +.... + +Brightness settings can be configured using extref:{handbook}config/#configtuning-sysctl[sysctl(8)]. +The following parameters are available: + +- hw.acpi.video._device_.levels: List of supported brightness levels. +- hw.acpi.video._device_.brightness: Current brightness level of the device. + +_device_ is a possible display device. +Example to set the brightness to 50% for the lcd0 device: + +[source,shell] +.... +% sysctl hw.acpi.video.lcd0.brightness <1> +hw.acpi.video.lcd0.brightness: 90 +% sysctl hw.acpi.video.lcd0.levels <2> +hw.acpi.video.lcd0.levels: 90 60 2 4 6 8 10 12 14 16 +18 20 22 24 26 28 30 32 34 36 38 40 42 44 46 48 50 52 +54 56 58 60 62 64 66 68 70 72 74 76 78 80 82 84 86 88 +90 92 94 96 98 100 +# sysctl hw.acpi.video.lcd0.brightness=50 <3> +hw.acpi.video.lcd0.brightness: 90 -> 50 +.... + +<.> `sysctl hw.acpi.video._device_.brightness` to view the current brightness level. +<.> `sysctl hw.acpi.video._device_.levels` to view the available levels. +<.> `sysctl hw.acpi.video._device_.brightness=50` to set the brightness to 50. + +[NOTE] +==== +man:acpi_video[4] should be loaded after any of the extref:{handbook}x11/#x-graphic-card-drivers[DRM] kernel modules. +==== + +[[xbrightness]] +=== xbrightness + +The package:x11/xbrightness[] utility can change the brightness via the extref:{handbook}x11[X Window System]. + +[source,shell] +.... +# pkg install xbrightness +.... + +The man:xbrightness[1] utility allows to set a value between 0 (darkness) and 65535 (full brightness). +Example for setting brightness to 50%: + +[source,shell] +.... +% xbrightness 32767 +.... + +[[xrandr]] +=== xrandr + +The package:x11/xrandr[] package is an extension of the X11 server that provides the man:xrandr[1] utility. +It allows you to configure various display properties, including brightness. +To install execute: + +[source,shell] +.... +# pkg install xrandr +.... + +The command `xrandr --output _monitor_ --brightness _brightness_` allows you to set the brightness for monitor to a value between 0 and 1.0. +To list the available monitors, run: + +[source,shell] +.... +% xrandr --listmonitors +Monitors: 2 + 0: +HDMI-1 1920/598x1080/337+0+0 HDMI-1 + 1: +eDP-1 1920/344x1080/194+1920+0 eDP-1 + +.... + +Example for setting brightness to 50% for HDMI-1: + +[source,shell] +.... +% xrandr --output HDMI-1 --brightness 0.5 +....