THEME howto for slimski

GENERAL CONCEPT
    A slimski theme consists of:
    ~~ a background image (background.png or background.jpg)
    ~~ a panel image (panel.png or panel.jpg)
    ~~ a file (slimski.theme) specifying placement and properties
          of input box(es) and text messages. (Also, refer to the
          "Localization" section later in this doc.)

    The panel image and background image can be a PNG or JPEG file.
    At runtime, the panel is blended into the background image using alpha transparency.
    note: slimski disregards any transparency of the background image
      ~~ background_color pixels will not "bleed through" the background image.

    The presence of background imagefile within a theme directory is optional.
    Similarly, presence of panel imagefile is optional. Testing has indicated that,
    by omitting the imagefiles and/or choosing "background_style solidcolor",
    you may reduce the runtime memory footprint of slimski.
    -=-
    in the absence of a panel image, the username/login fields are rendered
    atop a generic (opaque white) rectangular overlay.
    -=-
    If both a background.png and background.jpg file are present in a theme directory,
    slimski will load the PNG and ignore the jpeg. (Identical behavior
    applies if both a panel.png and panel.jpg are present)


SUPPORTED FORMATS
    fonts:  use the xft font specs, e.g.: Verdana:size=16:bold
    colors: use html hex format, e.g. #0066CC
    positions: can be specified either as absolute pixel offest values (e.g. 350)
        or relative to the container (e.g. 50% to specify middle of screen).


PREVIEW MODE
    While Xorg is running (in other words, from within a desktop session),
    you can preview a theme with:
        $ slimski -p /usr/share/slimski/themes/<name of theme>
    Note: by design (not a bug), toward accurately simulating the
    runtime behavior, slimski (hides the mouse cursor and) ignores
    all mousebutton click events within the bounds of the preview window.
    -=-
    During preview mode, slimski disregards the 'special usernames' (does not perform any action)
    -=-
    Upon recognizing a successful (pw+username) 'login', slimski will display
    a hardcoded test message for 4 seconds, then exit.
        test: UTF8 chars ¥·£·€·$·¢·₡·₢·₣·₤·₥·₦·₧·₨·₩·₪·₫·₭·₮·₯·₹
    -=-
    The preview is rendered via a window sized/scaled to 1280x1080 (hardcoded).
    If you expect to support systems with lesser displays, bear in mind
    (when specifying exact pixel x/y offsets in your theme) to position the
    input field x/y coordinates less than (1080x720? 800x600?) from
    0,0 (top left corner position). Toward accommodating a range of display sizes,
    the practice of specifying offsets using PERCENTAGE values is recommended.


LOCALIZATION
    slimski expects to find themes under the /usr/share/slimski/themes/  directory.
    To activate a given theme, edit the current_theme line in /etc/slimski.conf
    -=-
    If you do not specify a theme within /etc/slimski.conf, slimski will
    attempt to load the theme file /usr/share/slimski/themes/slimski.theme

    slimski consults the LANG runtime environmental variable, and will
    check for the existence of a matching localized __nn_NN variant of the specified theme.
    For example:
    At runtime, if slimski detects LANG=en_GB.UTF-8
    and the themename specified in /etc/slim.conf is  twilite
    it would load  /usr/share/slimski/themes/twilite__en_GB.theme
    if present. Otherwise it would fallback to loading /usr/share/slimski/themes/twilite.theme

    Currently (Jan 2021), you should expect to find very few localized theme
    variants (or none) included as pre\-installed items within the installation package.
    The onus of creating localized variants rests with distro maintainers and/or
    local sysadmins.

    distro maintainers may elect to distribute theme variants via separate
    package bundles (e.g. 'slimski-themes'). However, consider: any sysadmin
    interested in further customizing the localized content on THEIR system would
    (still) be required to copy/rename/paste any modified theme subdirectories,
    because a file placed during package installation is
    essentially 'owned by' the package (see: man dpkg-divert); any edits to
    its content by a local sysadmin are subject to being overwritten during each
    apt//dpkg upgrade of the 'owned by' package.


FONT SELECTION (WITH ATTENTION TO LOCALIZATION)

    Use the "slimski -p <themename>" preview feature to ensure that your
    specified font (is installed and) provides adequate unicode coverage
    for the locale(s) your theme intends to serve.
    If you do not specify a font face (family) for a given configuration item,
    slimski (via fontconfig, if installed on the system) will render the item
    using the default XftFont per your operating system.
    ref:
    https://tldp.org/HOWTO/Font-HOWTO/fonts.html
    https://en.wikipedia.org/wiki/Open-source_Unicode_typefaces


HOW TO TEST (PREVIEW) NON-NATIVE LOCALIZED THEME VARIANTS
    example:
    My system locale is en_US
    To view (and verify) the current LANG assignment, at a terminal prompt I type:
        env | grep LANG
    and the output is:
        en_US.UTF-8

    To create a "localized en_GB variant for the default slimski theme", I would:
        cp /usr/share/slim/themes/default/slimski.theme  /usr/share/slim/themes/default/slimski__en_GB.theme

    After editing the slimski__en_GB.theme file, in order to preview it I would type:
        bash -c "export LANG=en_GB.UTF-8  && slimski -p /usr/share/slim/themes/default/slimski__en_GB.theme"


TIPS / MISCELLANEOUS:

slimski recognizes 80 or so configurable options; about 50 of these options
are theme-related. slimski does not require theme authors to explicitly
declare a value for each of these options. For unspecified options,
it falls back to using a default value.
-=-
The “msg_x” and “msg_y” options        ---------- (unseen/unused antiX19's default SLiM theme, FWIW) ----------
govern the placement of session labelnames displayed in response to F1 keypress.
Toward accommodating both older 72dpi (with low display dimensions) displays and systems
having multi-monitor displays, slimski’s implicit values for these are
message_x::12% and message_y::12%
-=-
As a tip / suggestion: for any option values which are expressed as a percentage,
choosing a value lower than (72/96=75) 75 percent should accommodate 72dpi displays.
-=-
Nowadays, the default (implicit, unless overridden) xserver dpi default is probably 96.
Additionally (or alternatively) for a machine which permanently uses a lower dpi display,
can avoid offscreen msg placement by editing /etc/slimski.conf
and appending  -dpi 75  to the “xserver_arguments” line.
-=-
Check (search in file) for the presence of any ` ' "  quote-y characters.
A theme file should contain ZERO such characters. Their presence may not
cause the slimski program to crash, but may cause slimski to reject/ignore
any parsed line which contains these characters.
-=-
Applicable to both slimski .conf and .theme files, any line beginning
with a # (aka poundsign, hashmark) will be parsed as a comment, and ignored.
-=-
List of valid characters for use in naming
/usr/share/slimski/themes/ subdirectories (aka "theme names"):
       0123456789_ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz

RECOMMENDATIONS TOWARD BOTH ACCOMMODATING USERS VIEWING ON HiDPI DISPLAYS
AND USERS VIEWING ON "LOW RES" DISPLAYS:

    1) specify low (percentage) or small (x/y coordinates) positioning values
       for panel image and text messages to yield top-left placement
       ~~ suitable for viewing at low display resolution.

    2) specify a large(r) fontsize value for the various text messages
       to facilitate viewing by users of HiDPI displays

    3) (a related consideration) bear in mind that a "centered" layout
       may create a nuisance for users of dual-monitor systems.


THEME CONFIGURATION OPTIONS
    The following is an example slimski.theme file
    (for a comprehensive list of available config options, refer to /usr/share/doc/slimski/OPTIONS_LIST.txt)
    ----------------------------------------------------------------------
    ### Color, font, position for the messages (e.g.: shutting down)
    ### (used to display error or other informative messages)
    msg_color               #FFFFFF
    msg_font                Verdana:size=16:bold
    msg_x                   50%
    msg_y                   30

    ### Color, font, position for the session list
    sessiontype_color           #FFFFFF
    sessiontype_font            Verdana:size=16:bold
    sessiontype_x               50%
    sessiontype_y               70%

    ### style of background: 'stretch', 'tile', 'center', 'solidcolor'
    ###
    ###   IF YOU INTEND TO SPECIFY A background_color,
    ###   THE background_style OPTION MUST BE SET TO 'solidcolor' (noquotes)
    ###
    background_style        stretch
    background_color        #FF0033

    ### Horizonatal and vertical position for the panel
    input_panel_x           50%
    input_panel_y           40%

    ### input controls: horizontal and vertical positions.
    ### IMPORTANT! set input_pass_x and input_pass_y to -1
    ### to use a single input box for username/password (GDM Style).
    ### Note: use only absolute values (NOT percentages) for these fields
    ###
    ###          RESTATED, FOR CLARITY:
    ### If the following are not specified (or are set to -1), the result is a single inputbox.
    ###      ALSO, FOR SINGLE INPUTBOX PRESENTATION,
    ###      input_pass_x value MUST EQUAL input_name_x value
    ###      AND input_pass_y value MUST EQUAL input_name_y value
    input_name_x            40
    input_name_y            100
    input_pass_x            40
    input_pass_y            120
    #    ^----- for these 4 options, only integer values (not percent)

    password_msg    Please enter your password
    password_feedback_capslock_msg      Authentication failed (CapsLock is ON)
    password_feedback_msg               Authentication failed

    ### this msg is only displayed in the event of a miscongifuration
    login_cmd_failed_msg       Failed to execute login command

    ### Hide the input field textcursor (Valid values: true|false)
    input_hidetextcursor       false
    input_cursor_height    20

    ### slimski will hide the mouse cursor while the login screen is displayed
    ### unless TRUE is explicitly declared by a line here.
    ### Consider: Displaying the cursor invites user confusion b/c the login page
    ### contains no clickable elements. On the other hand, in the absence of
    ### a cursor some users may jump to the conclusion "oh no, my mouse isn't working".
    ### (note: while previewing themes, some window managers ignore this directive)
    ### Valid values: true|false
    # mouse_enabled          true


    ### Input controls font and color
    ### (used for textlabels displayed alongside the entry fields)
    input_font              Verdana:size=12
    input_color             #000000

    ### Welcome message position (relative to the panel)
    ### use -1 for both values or comment the options to disable the welcome message
    welcome_x               50%
    welcome_y               38

    ### Font and color for the welcome message
    ### (Often configured to include the hostname, via %host variable, in the msgtext)
    welcome_font            Verdana:size=16:bold:slant=italic
    welcome_color           #d7dde8

    ### 'Enter username' font and foreground/background color
    ### (used for user-typed input strings)
    username_font           Verdana:size=12
    username_color          #d7dde8

    ### 'Enter username' and 'Enter password' position (relative to the panel)
    ###  use -1 for both values to disable the message
    ### note that in case of single inputbox the password values are ignored.
    username_x              50%
    username_y              146
    password_x              50%
    password_y              146

    ### The message to be displayed. Leave blank if no message
    ### is needed (i.e. when already present in the panel image)
    username_msg            Please enter your username
    password_msg            Please enter your password
    ----------------------------------------------------------------------

>>>END
