# xdm-slackware-theme

Sébastien Ballet
`<slacker6896 at gmail dot com>`
June 26, 2019

## I. Presentation

This is a customizable theme for the `XDM` login manager.

## II. Requirements

This `XDM` theme depends on the following softwares :

- `bash`

- `xdm`

- `imagemagick`

- `numlockx` (optional)

- `compton` (optional)

- `feh` (optional)

- `xonclock` (optional)

- `cairo-clock` (optional)

- `conky` (optional)

- `xscreensaver` (optional)

- To take advantage of this theme, `XDM` must be the current login manager.

- `numlockx` is required to enable num lock at `XDM` startup.

- The image viewer `feh` is required for this `XDM` theme to work with the compositor `compton`.

- the analog clocks `xonclock` and `cairo-clock` are required by the `Xsetup` extension `analog-clock`.

- the system monitor `conky` is required by the `Xsetup` extension `sysmon-conky`.

- `xscreensaver` is required by the `Xsetup` extension `xdm-screensaver`.

## III. Directories and Files

This `XDM` theme includes the resources, scripts, images, and documentation files below :

### 1. In `/etc/X11/xdm/slackware`

- `Xresources`

  The resources of the X clients run by `XDM` outside the user’s sessions.

  This file defines the visual aspect of the login box, and keyboard shortcuts to start a given `WM`/`DE`.

  WM/DE | Keyboard Shortcuts
  --- | ---
  `failsafe` | `F1` or `Ctrl` + `Return`
  `blackbox` | `F2` or `Alt` + `B`
  `fluxbox` | `F3` or `Alt` + `F`
  `fvwm2` | `F4` or `Alt` + `V`
  `kde` | `F5` or `Alt` + `K`
  `twm` | `F6` or `Alt` + `T`
  `window maker` | `F7` or `Alt` + `W`
  `xfce` | `F8` or `Alt` + `X`

- `Xservers`

  File in which are defined the X server(s) running on the local machine.

- `Xsetup`

  The setup script which is run each time the X server is started/reset.

  This script assits `XDM` in setting up the screen the user sees. In the case of this `XDM` theme, this script, draws the `XDM`'s background and starts widgets according to the settings found in Xsetup configuration’s file(s).

- `Xstartup`

  The startup script which is run after user logs in by `XDM`.

  This script :

  - kills the processes and X clients started by `Xsetup` (ex. `compton`, `xclock`, …)

  - registers the `XDM` session with `sessreg`.

  Note that it is required to kills the clients started by `Xsetup`, otherwise they would continue to run inside the `WM`/`DE` the user started.

- `Xreset`

  The program which is run (as root) after the session terminates.

  This script de-register the `XDM` session with `sessreg`.

- `Xsession`

  The program to run as the session after the user has logged in.

  For more about `Xsession`, see sections The configuration file Xsession.conf and How Xsession works.

- `Xbuttons_bar`

  This script is run by `Xsetup`. It displays a buttons bar which allows user to execute actions under `XDM`, like selecting a session, suspending or rebooting the computer,…

  For more about `Xbuttons_bar`, see sections The configuration file Xbuttons_bar.conf and The desktop sessions menu.

- `xdm-config`

  xdm configuration file for this `XDM` theme.

- `Xbuttons_bar.conf`

  `Xbuttons_bar` (default) configuration file. For more, read this.

- `Xsession.conf`

  `Xsession` (default) configuration file. For more, read this.

- `Xsetup.conf`

  `Xsetup` (default) configuration file. For more, read this.

### 2. In `/etc/X11/xdm/slackware/extensions.d`

Directory in which the `Xsetup` extensions are stored.

An `Xsetup` extension is a shell script which adds new feature(s) to `Xsetup`.

- `analog-clock`

  An `Xsetup` extension to display an analog clock on the `XDM` screen.

- `analog-clock.conf`

  `analog-clock` (default) configuration file.

- `sysmon-conky`

  An `Xsetup` extension to integrate the system monitor `conky` on the `XDM` screen.

- `sysmon-conky.conf`

  `sysmon-conky` (default) configuration file.

- `sysmon-conky-rt.conf` and `sysmon-conky-pt.conf`

  conky configuration files used by extension `sysmon-conky`.

- `xdm-screensaver`

  An `Xsetup` extension to run a screensaver on `XDM` screen.

- `xdm-screensaver.conf`

  `xdm-screensaver` (default) configuration file.

### 3. In `/etc/X11/xdm/slackware/pixmaps`

- `s-logo-on-white.xpm`

  The Slackware (S) logo on a white background.

- `s-logo-on-grey.xpm`

  The Slackware (S) logo on a grey background.

- `*.jpg`

  Wallpapers for this `XDM` theme.

### 4. In `/usr/libexec/setxdmbg`

- `setxdmbg.sh`

  Command line tool to set the XDM background image easily. See this page for more about this tool.

### 5. In `/usr/bin`

- `setxdmbg`

  symlink to `/usr/libexec/setxdmbg/setxdmbg.sh`

### 6. In `/usr/share/man/man1`

- `setxdmbg.1.gz` : `setxdmbg` manual page.

### 7. In `/usr/share/man/man5`

- `Xsetup.conf.5.gz` : `Xsetup.conf` manual page.

- `Xbuttons_bar.conf.5.gz` : `Xbuttons_bar.conf` manual page.

- `Xsession.conf.5.gz` : `Xsession.conf` manual page.

- `analog-clock.conf.5.gz` : `analog-clock.conf` manual page.

- `sysmon-conky.conf.5.gz` : `sysmon-conky.conf` manual page.

- `xdm-screensaver.conf.5.gz` : `xdm-screensaver.conf` manual page.

### 8. In `/usr/doc/xdm-slackware-theme-<VERSION>/`

- `README`

  Text version of this html page.

- `readme.html`

  This html page.

- `setxdmbg.html`

  setxdmbg manual page in html format.

- `slackware-s-logo.xcf`

  Gimp file used to generate `s-logo-on-white.xpm` and `s-logo-on-grey.xpm` pixmaps. Might be useful to create Slackware (S) logo images on other colors than white and grey.

- `adoc/readme.txt`

  Source file (to asciidoc format) of readme.html

- `adoc/setxdmbg.txt`

  Source file (to asciidoc format) of setxdmbg.html

## IV. The configuration file Xsetup.conf

This is the (default) `Xsetup` configuration file.

Below the properties (aka variables) that can be (re)defined in `Xsetup` configuration file(s) :

- `DISABLE_LOG` `(default to off)`

  Defines whether or not logging of Xsetup activity must be disabled.

  The activity is logged in `/var/log/xdm-xsetup.${XDISP}.log`

  `XDISP` is the X server display name, without field screennumber, and to `XDM` resource name format, that is, with underscores in place of dots and colons. For instance, in case of X server display name :1, `XDISP` is `_1`.

- `XDM_LOCALE` `(default to en_US.UTF-8)`

  Defines the locale used while running `XDM`.

- `WITH_COMPTON` `(default to on)`

  Defines whether or not `Xsetup` must start the compositor `compton` if installed.

  Attention, `WITH_COMPTON` is turned off when the image viewer `feh` is not installed.

- `COMPTON_ARGS` `(see Xsetup.conf for default value)`

  The compton arguments.

- `WITH_BUTTONS_BAR` `(default to on)`

  Defines if `Xsetup` must start the buttons-bar (i.e. `Xbuttons_bar`).

- `BUTTONS_BAR_POSITION` `(default to TOP_LEFT)`

  The position of the buttons-bar which can be one of the following :

  `TOP_LEFT` | `TOP_RIGHT`
  `BOTTOM_LEFT` | `BOTTOM_RIGHT`

- `WITH_XCLOCK` `(default to on)`

  Defines if `Xsetup` must start `xclock` if installed.

- `XCLOCK_POSITION` `(default to TOP_RIGHT)`

  Defines the position of `xclock` which can be one of the following :

  `TOP_LEFT` | `TOP_RIGHT`
  `BOTTOM_LEFT` | `BOTTOM_RIGHT`

- `XCLOCK_FONT` `(see Xsetup.conf for default value)`

  Defines the font of the `xclock` widget.

- `XCLOCK_FG_COLOR` `(default grey90)`

  Defines the foreground color of the `xclock` widget.

- `XCLOCK_STRFTIME` `(default to %T)`

  Defines the `strftime` format of the date/time displayed by the `xclock` widget.

- `WITH_NUMLOCK_ON` `(default to on)`

  Defines if the num lock must be activated (requires `numlockx`) when starting `XDM`.

- `PRIMARY_ONLY` `(default to on)`

  Defines whether or not the `XDM` background and widgets (xclock, buttons-bar, …) must be displayed on the primary screen only when `XDM` is running on a multi-screen configuration.

  Note that `Xsetup` has no control over the display on which the `XDM` greeting and login prompt are displayed.

- `PRIMARY_ID` `(default to auto)`

  Defines the identifier of primary display.

  - Can be any existing output supported by xrandr (ex. `VGA-1`, `HDMI-0`, `DVI-D-0`,…), or the keyword `auto`, to auto-detect the primary display.

  - This property is ignored when `PRIMARY_ONLY` is set to `off`.

  - `PRIMARY_ONLY` is turned `off` when the given identifier is invalid, or when this property is set to `auto` and none of the displays listed by `xrandr` is defined as primary.

- `XDMBGIMG` `(default to ${SCRIPTDIR}/pixmaps/default-wallpaper.pixmap)`

  Full path to the image that `Xsetup` must pass to setxdmbg to generate the `XDM` background image.

  When this property is not set, XDM background is black, unless if compton is enabled, in which case the background is greyed. To prevent this, `WITH_COMPTON` must be turned off.

  By default, this property points the symlink default-wallpaper.pixmap in directory `${SCRIPTDIR}/pixmaps`, so that, user can change the `XDM` background image source without to have to edit this configuration file.

  `SCRIPTDIR` is the absolute path to Xsetup’s directory.

- `BORDER_TOP` `(default to 40:black)`

  The height and color of the border at top of the `XDM` background image when the buttons-bar and/or `xclock` widget is/are enabled and placed on top.

  The value of this property must be to the format `<height>:<color>`.

  `color` can be an X11 color name or an hex triplet to the format `#rrggbb`.

  Important:

  The border is drawn with imagemagick which does not use the same color names as xclock/xmessage widgets.

  For instance, imagemagick associates the color `c(0,80,0)` to the name `green`, while X11 associates this name to the color `c(0,255,0)`.

- `BORDER_BTM` `(default to 40:black)`

  The height and color of the border at bottom of the `XDM` background image when the buttons-bar and/or `xclock` widget is/are enabled and placed on bottom.

  The same format and informations as for `BORDER_TOP` apply to this property.

- `EXTRAIMGOPS` `(empty by default)`

  The imagemagick extra image operators that `Xsetup` must pass to setxdmbg to generate the `XDM` background image.

  Attention, extra image operators can be time consuming the first time the XDM background image is generated.

- `EXTENSIONS` `(empty by default)`

  Defines the `Xsetup` extension(s) to load (and execute).

  For more, see section Extension mechanism.

## V. The configuration file Xbuttons_bar.conf

This is the (default) `Xbuttons_bar` configuration file.

Below the properties (aka variables) that can be (re)defined in `Xbuttons_bar` configuration file(s) :

- `DISABLE_LOG` `(default to off)`

  Defines whether or not logging of `Xbuttons_bar` activity must be disabled.

  The activity is logged in `/var/log/xdm-xbuttons_bar.${XDISP}.log`

  `XDISP` is the X server display name, without field screennumber, and to `XDM` resource name format, that is, with underscores in place of dots and colons. For instance, in case of X server display name :1, `XDISP` is `_1`.

- `BUTTONS_ORDER` `(default to "SESSIONS SYSTEM")`

  Defines the buttons present in the buttons-bar and their order.

  Below the supported identifiers :

    `SESSIONS` | Identifier of button to access the sessions menu.
    `SYSTEM` | Identifier of button to access the system menu.
    `SCREENSHOT` | Identifier of button to take a screenshot of XDM screen.

- `SYSMENU_BUTTONS_ORDER` `(default to "SUSPEND HIBERNATE REBOOT HALT")`

  Defines the buttons present in the system menu and their order.

  Below the supported identifiers :

    `SUSPEND` | Identifer of button to suspend the system.
    `HIBERNATE` | Identifer of button to hibernate the system.
    `REBOOT` | Identifer of button to reboot the system.
    `HALT` | Identifer of button to halt the system.

- `SESMENU_BTLABEL` `(default to "Session[@SESSION_NAME@]")`

  Defines the label of the button to access the sessions menu.

  When the tag `@SESSION_NAME@` is present, it is replaced by the name of the current selected session, if any, by the string specified by property `NOSESSION_STR` otherwise.

- `NOSESSION_STR` `(default to "default")`

  The string by which the tag `@SESSION_NAME@`, if present in property `SESMENU_BTLABEL`, must be replaced when there is no selected session.

- `SYSMENU_BTLABEL` `(default to "System")`

  Defines the label of the button to access the system menu.

- `SCREENSHOT_BTLABEL` `(default to "Screenshot")`

  Defines the label of the button to take a screenshot of XDM screen.

  To make this button invisible on the screenshots, simply set this property to " ".

- `SUSPEND_BTLABEL` `(default to "Suspend")`

  Defines the label of the button to suspend the system.

- `HIBERNATE_BTLABEL` `(default to "Hibernate")`

  Defines the label of the button to hibernate the system.

- `REBOOT_BTLABEL` `(default to "Reboot")`

  Defines the label of the button to reboot the system.

- `HALT_BTLABEL` `(default to "Halt")`

  Defines the label of the button to halt the system.

- `EXITMENU_BTLABEL` `(default to "Exit")`

  Defines the label of the button to exit from system/sessions menu.

- `RESET_BTLABEL` `(default to "Reset")`

  Defines the reset button label of sessions menu selection.

- `FONT` `(see Xbuttons_bar.conf)`

  Defines the buttons-bar font.

- `FG_COLOR` `(default to grey90)`

  Defines the buttons-bar foreground color.

- `SYSMENU_FONT` `(see Xbuttons_bar.conf)`

  Defines the system menu font.

- `SESMENU_FONT` `(see Xbuttons_bar.conf)`

  Defines the sessions menu font.

- `SYSMENU_FG_COLOR` `(default to grey90)`

  Defines the system menu foreground color.

- `SESMENU_FG_COLOR` `(default to grey90)`

  Defines the sessions menu foreground color.

- `XINITRC_FILES_DIR` `(default to /etc/X11/xinit)`

  Defines the location of `xinitrc.*` session files used to populate the sessions menu.

- `SESSIONS_BLACKLIST` `(empty by default)`

  Defines the sessions to exclude from the sessions menu.

- `SESMENU_VIEWPORT_SIZE` `(default to 10)`

  Defines the maximum number of items visible at a time in the sessions menu.

  When there is more items than that in the sessions menu, scroll buttons are added accordingly.

- `SESMENU_LSCROLL_BTLABEL` `(default to " < ")`

  Defines the label of the sessions menu left-scroll button.

- `SESMENU_RSCROLL_BTLABEL` `(default to " > ")`

  Defines the label of the sessions menu right-scroll button.

- `PERSISTENT_SESSION` `(default to off)`

  Defines whether or not the (last) selected session in the sessions menu must persist (across `XDM` resets and system reboots).

- `SCREENSHOT_DELAY` `(default to 5)`

  Defines the delay (in seconds) before taking a screenshot.

- `SCREENSHOT_DIR` `(default to /tmp)`

  Defines the screenshot folder.

  Screenshot names are to the format :

        xdm.${XDISP}.$(date +%Y%m%d_%H%M%S).png

- `SCREENSHOT_NTFY_MSG` `(see Xbuttons_bar.conf)`

  Defines the message displayed before taking a screenshot.

  The tag `@SCREENSHOT_DELAY@` is replaced at runtime by the value of property `SCREENSHOT_DELAY`.

- `SCREENSHOT_NOW_BTLABEL` `(default to Now)`

  Defines the label of button to dismiss the timeout and take a screenshot immediately.

- `SCREENSHOT_CANCEL_BTLABEL` `(default to Cancel)`

  Defines the label of button to cancel taking a screenshot.

- `SCREENSHOT_TAKEN_MSG` `(see Xbuttons_bar.conf)`

  Defines the message displayed after taking a screenshot.

  The tag `@SCREENSHOT_FILENAME@` is replaced at runtime by the full path to the screenshot file.

- `SCREENSHOT_FAIL_MSG` `(see Xbuttons_bar.conf)`

  Defines the message displayed when taking a screenshot failed.

- `SCREENSHOT_DLG_FONT` `(see Xbuttons_bar.conf)`

  Defines the font of the message displayed before/after taking a screenshot, and in case of error.

- `SCREENSHOT_ALWAYS_FULL` `(default to off)`

  Defines whether or not to always take full screenshots, even when XDM is configured for primary display only (`Xsetup.PRIMARY_ONLY=on`).

## VI. The configuration file Xsession.conf

This is the (default) `Xsession` configuration file.

Below the properties (aka variables) that can be (re)defined in `Xsession` configuration file(s) :

- `DISABLE_LOG` `(default to off)`

  Defines whether or not logging of `Xsession` activity must be disabled.

  The activity is logged in `~/xdm-xsession.${XDISP}.log`

  `XDISP` is the X server display name, without field screennumber, and to `XDM` resource name format, that is, with underscores in place of dots and colons. For instance, in case of X server display name :1, `XDISP` is `_1`.

- `USR_XSESSION` `(default to ${HOME}/.xsession)`

  Full path to the user’s X session.

- `SYS_XSESSION` `(default to /etc/X11/xinit/xinitrc)`

  Full path to the system’s X session.

- `XINITRC_FILES_DIR` `(default to /etc/X11/xinit)`

  The location of `xinitrc.*` session files.

- `SYS_XRESOURCES` `(default to /etc/X11/xinit/.Xresources)`

  Full path to the system’s X resources.

- `USR_XRESOURCES` `(default to ${HOME}/.Xresources)`

  Full path to the user’s X resources.

- `SYS_XMODMAP` `(default to /etc/X11/xinit/.Xmodmap)`

  Full path to the system’s X modmap.

- `USR_XMODMAP` `(default to ${HOME}/.Xmodmap)`

  Full path to the user’s X modmap.

- `LOAD_XRESOURCES_ON` `(default to ( "failsafe" ) )`

  The name of the sessions for which `Xsession` must load the X resources (specified by `SYS_RESOURCES` and `USR_XRESOURCES`) when available.

  Most of the `xinitrc` scripts usually load the X resources automatically. Thus, this variable should only be used for those who don’t.

  `failsafe` is a pseudo-session for which there is no xinitrc script.

- `LOAD_XMODMAP_ON` `(default to ( "failsafe" ) )`

  The name of the sessions for which `Xsession` must load the X modmap (specified by `SYS_XMODMAP` and `USR_XMODMAP`) when available.

  Most of the `xinitrc` scripts usually load the X modmap automatically. Thus, this variable should only be used for those who don’t.

  `failsafe` is a pseudo-session for which there is no xinitrc script.

- `XSESSION_ERRFILE` `(see Xsession.conf for default value)`

  Defines the files in which (session) errors can be redirected.

  Errors are only redirected to one of the specified files, the 1st that met the following condition :

        umask 077 && cp /dev/null XSESSION_ERRFILE[i] 2>/dev/null

  Errors are not redirected when this variable is not set, nor when the condition above is not met by any of the specified files.

- `SOURCE_SYS_PROFILE` `(default to on)`

  Defines whether or not the system profile script `/etc/profile` must be sourced by `Xsession`, when present.

- `SOURCE_USR_PROFILE` `(default to on)`

  Defines whether or not the user profile script `~/.profile` must be sourced by `Xsession`, when present.

- `SOURCE_SYS_XPROFILE` `(default to on)`

  Defines whether or not the system x-profile script `/etc/xprofile` must be sourced by `Xsession`, when present.

- `SOURCE_USR_XPROFILE` `(default to on)`

  Defines whether or not the user x-profile script `~/.xprofile` must be sourced by `Xsession`, when present.

- `FAILSAFE_TERM` `(default to /usr/bin/uxterm)`

  Defines the terminal emulator to execute when running `failsafe` mode.

  The failsafe mode is run when all possible sessions (ie. session passed in argument (if any), session selected through the sessions menu (if any), user’s session, system’s default session) failed to start.

- `FAILSAFE_TERM_GEOMETRY` `(default to 80x24`+0+0)

  Defines the geometry of the terminal emulator specified by variable `FAILSAFE_TERM`.

  When this variable is not set, no geometry is passed to the terminal emulator.

## VII. Multiple XDM logins

The file `Xservers` that comes with this theme includes sections to run up to 3 X servers on a single machine, and thus 3 XDM logins. By default, only the X server on local display :0 (paired with VT7) is enabled.

To enable the X server on local display `:1` (paired with VT8), it is required to uncomment the line :

      #:1 local /usr/bin/X :1 vt8

To enable the X server on local display `:2` (paired with VT9), it is required to uncomment the line :

      #:2 local /usr/bin/X :2 vt9

Once done, restart `XDM`, or reboot the system. To access `XDM` on local display `:1`, hit CTRL+ALT+F8, to access XDM on local display `:0`, hit CTRL+ALT+F7.

By default, all XDM logins share the same configuration which is specified by the (default) configuration files :

- `Xsetup.conf`

- `Xbuttons_bar.conf`

- `Xsession.conf`

The `Xsetup`/`Xbuttons_bar`/`Xsession` configuration of each XDM login can be (re)defined in specific configuration files named :

- `Xsetup.<XDISP>.conf`

- `Xbuttons_bar.<XDISP>.conf`

- `Xsession.<XDISP>.conf`

`XDISP` is the X server display name, without field screennumber, and to `XDM` resource name format, that is, with underscores in place of dots and colons.

For instance, the `Xsetup` configuration for `XDM` login on `:1` is named `Xsetup._1.conf`, the `Xbuttons_bar` configuration for the `XDM` login `:2` is named `Xbuttons_bar._2.conf`.

When only a few properties need to be redefined for a given `XDM` login, the default configuration can be loaded by the dedicated configuration. For instance, to only redefine the property `XDMBGIMG` for the `XDM` login on `:1` and `:2`, the configuration files `Xsetup._1.conf` and `Xsetup._2.conf` could look like that :

  Xsetup._1.conf

      # Load default
      source ${SCRIPTDIR}/Xsetup.conf

      # defines background image for XDM on :1
      XDMBGIMG=${SCRIPTDIR}/pixmaps/default-wallpaper._1.pixmap

  Xsetup._2.conf

      # Load default
      source ${SCRIPTDIR}/Xsetup.conf

      # defines background image for XDM on :2
      XDMBGIMG=${SCRIPTDIR}/pixmaps/default-wallpaper._2.pixmap

When an `XDM` login has no dedicated Xsetup/Xbuttons_bar/Xsession configuration, the default configuration is used.

## VIII. Extension mechanism

The extension mechanism allows to improve `XDM` user experience with external shell scripts which are dynamically loaded and executed by `Xsetup`.

The extensions must be in the folder `extensions.d` of `Xsetup`'s directory.

The extension(s) that `Xsetup` must load/execute have to be specified by the property `EXTENSIONS`, declared in `Xsetup`'s configuration file(s).

### 1. Included extensions

This `XDM` theme comes with the extensions described below.

#### A. analog-clock

Extension to display an analog-clock on XDM screen.

When `Xsetup` is configured with `compton` support, `analog-clock` starts an instance of `cairo-clock`, otherwise, an instance of `xonclock` is started.

if neither `cairo-clock` nor `xonclock` is installed, `analog-clock` does nothing.

By default, `analog-clock`'s settings are loaded from configuration file `analog-clock.conf`.

On system with multiple XDM logins, there might be a configuration file per X server: `analog-clock._0.conf` for X server `:0`, `analog-clock._1.conf` for X server `:1`, …

Below the properties (aka variables) that can be (re)defined in `analog-clock` configuration file(s) :

- `XOC_SKIN` `(default to /usr/share/xonclock/skins/chrome-128-bs.png)`

  Defines `xonclock`'s skin.

- `XOC_POSITION` `(default to TOP_RIGHT)`

  Defines `xonclock`'s position on XDM screen. Can be one of the following :

  `TOP_LEFT` | `TOP_RIGHT`
  `BOTTOM_LEFT` | `BOTTOM_RIGHT`

- `XOC_SIZE` `(default to 128)`

  Defines the `xonclock`'s size.

  Attention, xonclock has no option to set the clock size which is defined by the skin (see `XOC_SKIN`). The size specified by property `XOC_SIZE` is only used when computing the position of the clock.

- `XOC_MARGIN` `(default to 16)`

  Defines the `xonclock`'s margin.

- `XOC_USE_BACKGROUND` `(default to on)`

  Defines whether or not `xonclock` must merge the skin with desktop root window background image.

- `XOC_SHOW_SECONDS` `(default to on)`

  Defines whether or not `xonclock` must render second hand.

- `XOC_SHOW_DATE` `(default to on)`

  Defines whether or not `xonclock` must display the date.

- `XOC_DATE_FORMAT` `(default to "%b %d")`

  Defines the `strftime` format of the date string used by `xonclock` to render the date.

- `XOC_EXTRA_ARGS` `(default to ())`

  Defines the extra arguments to pass to `xonclock`.

  Note that `XOC_EXTRA_ARGS` can also be used to override arguments that `analog-clock` passes to `xonclock`.

  Example :

        XOC_EXTRA_ARGS=( "--date-position=BOTTOM-RIGHT" "--date-offset-v=32" )

- `CC_THEME` `(default to radium)`

  Defines the `cairo-clock`'s theme.

- `CC_POSITION` `(default to TOP_RIGHT)`

  Defines `cairo-clock`'s position on XDM screen. Can be set to one of the following :

  `TOP_LEFT` | `TOP_RIGHT`
  `BOTTOM_LEFT` | `BOTTOM_RIGHT`

- `CC_SIZE` `(default to 200)`

  Defines the `cairo-clock`'s size to format `WIDTH[:HEIGHT]`. When `HEIGHT` is not set, defaults to `WIDTH`.

- `CC_MARGIN` `(default to 16)`

  Defines the `cairo-clock`'s margin.

- `CC_SHOW_SECONDS` `(default to on)`

  Defines whether or not `cairo-clock` must render second hand.

- `CC_SHOW_DATE` `(default to on)`

  Defines whether or not `cairo-clock` must render the date string.

- `CC_EXTRA_ARGS` `(default to ())`

  Defines the extra arguments to pass to `cairo-clock`.

  Note that `CC_EXTRA_ARGS` can also be used to override arguments that `analog-clock` passes to `cairo-clock`.

  Example :

          CC_EXTRA_ARGSfx=( "--twentyfour" )

#### B. sysmon-conky

Extension to integrate the system monitor `conky` on the `XDM` screen.

if `conky` is not installed, `sysmon-conky` does nothing.

By default, `sysmon-conky`'s settings are loaded from configuration file `sysmon-conky.conf`.

On system with multiple XDM logins, there might be a configuration file per X server: `sysmon-conky._0.conf` for X server `:0`, `symon-conky._1.conf` for X server `:1`, …

Below the properties (aka variables) that can be (re)defined in `sysmon-conky` configuration file(s) :

- `CONKY_REAL_TRANSPARENT_CFG` `(default to ${EXTDIR}/conky-real-transparent.conf)`

  Defines the `conky` configuration with real transparency.

  This configuration is used when `Xsetup` is configured with compton, i.e. `WITH_COMPTON=on` (see `Xsetup`).

- `CONKY_PSEUDO_TRANSPARENT_CFG` `(default to ${EXTDIR}/conky-pseudo-transparent.conf)`

  Defines the `conky` configuration with pseudo transparency.

  This configuration is used when `Xsetup` is configured without compton, i.e. `WITH_COMPTON=off` (see `Xsetup`).

- `CONKY_EXTRA_ARGS` `(default to ())`

  Defines the extra arguments to pass to conky.

  Example :

        CONKY_EXTRA_ARGS=( "--alignment=bottom_middle" "--interval=2" )

#### C. xdm-screensaver

Extension to run a screensaver on `XDM` screen.

By default, `xdm-screensaver`'s settings are loaded from configuration file `xdm-screensaver.conf`.

On system with multiple `XDM` logins, there might be a configuration file per X server: `xdm-screensaver._0.conf` for X server `:0`, `xdm-screensaver._1.conf` for X server `:1`, …

Below the properties (aka variables) that can be (re)defined in `xdm-screensaver` configuration file(s) :

- `SCREENSAVER_MODE` `(default to windowed)`

  Defines the operating mode of xdm-screensaver extension. Can be set to one of the following.

  - `fullscreen`

    The screensaver is draw on the root window.

    Attention, when this mode is selected :

    - The screensaver is not visible when compton is enabled (i.e. the `Xsetup` property `WITH_COMPTON` is set to on).

    - The background image specified by `Xsetup` property `XDMBGIMG` is erased by the screensaver.

    - Parts of the top/bottom border on which is placed the buttons-bar and/or the xclock widget might be erased by the screensaver.

  - `windowed`

    The screensaver is draw on a newly-created window on the physical display specified by property `SCREENSAVER_DISPLAY`.

    Attention, when this mode is selected, the screensaver’s window might overlap any other window on the same physical display (ex. the `XDM` login window).

- `SCREENSAVER_DISPLAY` `(default to 1)`

  Defines the physical display on which to draw the screensaver when `SCREENSAVER_MODE` is set to `windowed`. This can be one of the following:

  - The name of any output supported by xrandr (ex. `VGA-0`, `HDMI-0`, …)

  - The number of the corresponding display in the list returned by command `xrandr --listmonitors` (ex. 0, 1, 2, ..)

  - the keyword `primary` to select the primary display.

- `SCREENSAVER_WINDOW_POS` `(default to TOP_LEFT)`

  Defines the position of the window on which to draw the screensaver when `SCREENSAVER_MODE` is set to `windowed`.

  The position is relative to the physical display specified by property `SCREENSAVER_DISPLAY`. Can be one of the following :

  `TOP_LEFT` | `TOP_MIDDLE` | `TOP_RIGHT`
  `MIDDLE_LEFT` | `MIDDLE_MIDDLE` | `MIDDLE_RIGHT`
  `BOTTOM_LEFT` | `BOTTOM_MIDDLE` | `BOTTOM_RIGHT`

- `SCREENSAVER_WINDOW_SIZE` `( default to (100% 100%) )`

  Defines the dimensions (`width` x `height`) of the window on which to draw the screensaver when `SCREENSAVER_MODE` is set to `windowed`. The dimensions can be expressed in pixel, or in percent of the width/height of the physical display specified by property `SCREENSAVER_DISPLAY`.

- `SCREENSAVER_WINDOW_MARGINS` `( default to ( 8 8 ) )`

  Defines the margins around the window on which to draw the screensaver when `SCREENSAVER_MODE` is set to `windowed`.

- `SCREENSAVER_DIR` `(default to /usr/libexec/xscreensaver)`

  Defines the location of screensavers.

- `SCREENSAVER` `(default to gltext)`

  Defines the screensaver to run.

- `SCREENSAVER_EXTRA_ARGS` `( see below )`

  Defines the extra-arguments to pass to the screensaver specified by property `SCREENSAVER`.

  default to `( "-text" "$(head -n 1 /etc/slackware-version)" )`

### 2. Integrate extensions

To integrate `conky` in XDM screen, open `Xsetup.conf`, and set property `EXTENSIONS` as below :

      EXTENSIONS=( "sysmon-conky" )

To integrate an analog-clock in `XDM` screen, open `Xsetup.conf`, and set property `EXTENSIONS` as below :

      EXTENSIONS=( "analog-clock" )

To integrate `conky` and an analog clock on the `XDM` screen, simply set property `EXTENSIONS` as below :

      EXTENSIONS=( "sysmon-conky" "analog-clock" )

On a system with multiple `XDM` logins, it is possible to have different extension(s) on each `XDM` login.

For instance, to attach conky to `XDM` on `:0`, and an analog-clock to `XDM` on `:1`, the Xsetup configuration files for these `XDM` logins could look like as below :

  Xsetup._0.conf

      # Load default
      #
      source ${SCRIPTDIR}/Xsetup.conf

      # integrate conky on XDM screen of X server :0
      EXTENSIONS=( "sysmon-conky" )

  Xsetup._1.conf

      # Load default
      #
      source ${SCRIPTDIR}/Xsetup.conf

      # integrate an analog-clock on XDM screen of X server :1
      #
      EXTENSIONS=( "analog-clock" )

### 3. Implementing extensions

It is required to follow the rules below when implementing an `Xsetup` extension:

- The extension must be non blocking, otherwise the XDM display manager will be unusable.

- Any program started in the background by the extension must be referenced in the Xsetup processes registry by calling the function `register_process()`.

  This is required to ensure that any process started by the extension will be stopped (by `Xstartup`) before user’s X session start.

  Before calling `register_process()`, remember that `$!` is the PID of the last executed background command, which might not the PID of the process to track :

        /usr/bin/foo -bar $(head -n 1 /foo/bar) &
        register_process $! FOO-0

  In the example above, the PID of command `$(head -n 1 /foo/bar)` is passed to `register_process()` instead of PID of `/usr/bin/foo`. To avoid this, instead of passing commands to the process to track, use variables :

        ARG=$(head -n 1 /foo/bar)
        /usr/bin/foo -bar ${ARG} &
        register_process $! FOO-0

Below the list of `Xsetup` variables and functions that can be useful when implementing extensions :

`SCRIPTDIR` | `EXTDIR`
`XDISP` | `XSCREEN_NFO`
`PRIMARY_NFO` |
`is_disabled()` | `is_in_list()`
`is_process_registered()` | `get_xscreen_infos()`
`get_display_infos()` | `get_display_geometry()`
`get_xoff()` | `get_xpos()`
`get_yoff()` | `get_ypos()`
`log_infos()` | `register_process()`
`deregister_process()` |

## IX. The desktop sessions menu

This menu :

- is available only if `Xbuttons_bar` is configured to includes it, i.e when property `BUTTONS_ORDER` (defined in `Xbuttons_bar` configuration file) includes the keyword `SESSIONS`.

- allows to select a `WM`/`DE` that will be started on user login.

- includes an entry for each `WM`/`DE` :

  - for which there is a corresponding `xinitrc` (executable) in directory specified by property `XINITRC_FILES_DIR` defined in `Xbuttons_bar` configuration file.

  - which is not on the blacklist specified by variable `SESSION_BLACKLIST` defined in `Xbuttons_bar` configuration file.

The selection made through the desktop sessions menu is volatile by default (i.e. reset on logout), but can be defined as persistent (across `XDM` resets and system reboots) by turning `Xbuttons_bar`'s property `PERSISTENT_SESSION` on.

`Xbuttons_bar` communicates the selected session to `Xsession` script through the file `/var/lib/xdm/xdm.<XDISP>.xsession` (`XDISP` is the target X server display name to `XDM` resource name format) which is reset each time `Xbuttons_bar` starts unless `PERSISTENT_SESSION` is turned on.

Attention, when `PERSISTENT_SESSION` is turned on, the selected session become the session of any user that can login on to current X server. There is no (known) way to implements a per-user configuration.

## X. How Xsession works

When `Xsession` is run (after the user has logged in), it executes the following :

1. If a session name is passed in argument (when user hit one of the session keyboard shortcuts defined in `Xresources`), `Xsession` try to start it. On failure, it continues (see 2).

2. If a session has been selected from the sessions menu (i.e. the file `/var/lib/xdm/xdm.<XDISP>.xsession` is not empty), `Xsession` try to start it. On failure, it continues (see 3).

3. `Xsession` try to start the user’s session specified by variable `USR_XSESSION`. On failure, it continues (see 4).

4. `Xsession` try to start the system’s session specified by variable `SYS_XSESSION`. On failure, it continues (see 5).

5. At this point, `Xsession` runs the failsafe mode by starting the terminal emulator specified by variable `FAILSAFE_TERM`. On failure, `Xsession` exits.

## XI. Tips and tricks

### 1. Howto take a screenshot of XDM

The buttons-bar includes a screenshot tool which is disabled by default. To enable it :

- Open `Xbuttons_bar` configuration file.

- Add the keyword `SCREENSHOT` to the property `BUTTONS_ORDER`.

- Restart `XDM`.

The screenshot tool settings are defined by the following properties (in Xbuttons_bar configuration file) :

- `SCREENSHOT_BTLABEL`

- `SCREENSHOT_DELAY`

- `SCREENSHOT_DIR`

- `SCREENSHOT_NTFY_MSG`

- `SCREENSHOT_NOW_BTLABEL`

- `SCREENSHOT_CANCEL_BTLABEL`

- `SCREENSHOT_TAKEN_MSG`

- `SCREENSHOT_FAIL_MSG`

- `SCREENSHOT_DLG_FONT`

- `SCREENSHOT_ALWAYS_FULL`

### 2. Howto change the login box background color

To change the login box background color to something like, grey, proceed as below :

- Open the file `/etc/X11/xdm/slackware/Xresources`

- Replace :

        xlogin.Login.background: white

        xlogin.Login.shdColor: #dedede
        xlogin.Login.hiColor: #dedede

  By :

        xlogin.Login.background: grey

        xlogin.Login.shdColor: grey30
        xlogin.Login.hiColor: grey90

- Replace :

        xlogin.Login.logoFileName: /etc/X11/xdm/slackware/pixmaps/s-logo-on-white.xpm

  By :

        xlogin.Login.logoFileName: /etc/X11/xdm/slackware/pixmaps/s-logo-on-grey.xpm

Note that to change the background color by something else than grey, it is first required to create a Slackware (S) logo image (to .xpm format) with the desired background color, which can easily be done starting with the gimp image `/usr/doc/xdm-slackware-theme-<VERSION>/slackware-s-logo.xcf`.

### 3. My X server(s) tend to grow without bound over time

In this case, it might be useful to set `DisplayManager.<DISPLAY>.terminateServer` to `true` in `/etc/X11/xdm/slackware/Xresources`.

`DISPLAY` is the X server display name to XDM resource name format.

## XII. Known issues

### 1. Multiple XDM logins, multi-screen, and nVidia

In case of Multiple `XDM` logins on a system using an nvidia videocard with 2 monitors and the proprietary nvidia driver, at startup, the 1st `XDM` login is correctly placed at the center of 1st physical display, but, the 2nd `XDM` login is placed at the center of the abstract X screen.

This issue is automatically resolved following a login/logout on the 2nd `XDM` login. It is also possible to fix that by reseting the 2nd `XDM` login (`CTRL+ALT+BACKSPACE`).

This issue comes from the nvidia proprietary driver. It has neither been observed with driver nouveau , nor on systems with an videocard using a non nvidia GPU.

## XIII. Credits

- This xdm theme has been designed using informations found on archwiki (here) and scripts from:

  - archlinux package `xdm-archlinux` (at archlinux.org/packages)

  - slackware package `slackware-xdm-theme` (at slackbuilds.org)

  - The following wallpapers (in `/etc/X11/xdm/slackware/pixmaps`) are resized version of image found at ravefinity.com

    `C1-Nights-Haze-Blue-2.jpg` | `C2-Green-Moutain-Side-2.jpg`
    `C1-Nights-Haze-Grey-2.jpg` | `C2-Morning-View-2.jpg`
    `C1-Nights-Haze-Purple-2.jpg` | `C2-Ocean-Side-Sunset-2.jpg`
    `C1-Shuttleworth-Galaxy-2.jpg` | `C2-Precipice.jpg`
    `C1-Steele-Star-2.jpg` | `C2-Sunset-Shore-2.jpg`
    | `C2-The-Rivers-Of-Cuomo-2.jpg`

    All of these wallpapers are under creative commons license.

  - The following wallpapers (in `/etc/X11/xdm/slackware/pixmaps`) are from unknown source :

    `Geminid-Meteor-Shower.jpg` | `Green-Hills.jpg`
    `Mars-Olympus-Mons.jpg` | `Space-Outer-Nature.jpg`