WALLCHANGE.CMD
(C) 2021,2023 Alex Taylor

  WALLCHANGE is a REXX script which changes the WPS desktop background to a
  random image selected from a list of candidates.

  This is most useful when run automatically at a fixed interval or at
  scheduled times, which effectively creates a 'slideshow' of changing desktop
  wallpapers.  WALLCHANGE itself does not include a schedule function - you
  can instead use the scheduler of your choice. The DTProgram class included
  with Rich Walsh's DragText provides one example; Unix-type 'cron' schedulers
  are another.

  WALLCHANGE requires WPTOOLS.DLL from Henk Kelder's WPTools package.  You
  are also recommended to have the 'file' utility from the GNU coreutils
  package installed, although WALLCHANGE will function without it.


USING WALLCHANGE

  Whether you run WALLCHANGE through a scheduler or directly, the syntax is:
    wallchange <arguments>
  where <arguments> is one or more of the following (separated by spaces):
   - the name of a single file containing a valid image
   - a directory name (other than the desktop directory)
   - the name (ending in '.lst') of a special list file as defined below

  These arguments are used to build the list of candidate images.  They may be
  either relative or fully-qualified filenames.  If the file or directory
  doesn't exist or is otherwise unreadable, it will be skipped.

  Arguments containing spaces must be wrapped in double quotes (").

  Supported image formats are JPEG, PNG, GIT and BMP.  Each valid image that
  is specified will be added to the list of available backgrounds.

  For directory names, WALLCHANGE will read the directory recursively,
  including any subdirectories, and attempt to interpret each file found as
  an image or a list file.


LIST FILE FORMAT

  A list file is an ASCII text file containing one formatted entry per line.
  Blank lines, or lines starting with a semicolon (;), are ignored.

  Each entry consists of up to four tab-separated fields:
   - filespec (required)
   - display-mode (optional)
   - text-colour (optional)
   - active-time (optional)

  The meaning of each field is as follows:

  filespec
     Name of an image file, a directory, or another list file, which will
     be handled accordingly.

  display-mode
    How the background image is to be scaled to the screen; one of:
     N         Show image at its native size (the default if not specified)
     T         Tile image at its native size
     S[,#]     Tile image, scaled to show # instances in each direction; # is
                a number from 1 to 20, defaulting to 1 if not specified

  text-colour
    The desktop icon text colour to apply along with the image, specified as
    three RGB decimal values separated by spaces (i.e. "<red> <green> <blue>").
    If not specified, whatever is set for the current directory or list (see
    below) will be used.  If none, the default is white ("255 255 255").

  active-time
    Defines time periods (based on hour and weekday) when an image is eligible
    for use as the background.  See Time Periods, below, for an explanation.
    If not specified, the image is assumed to always be eligible.

  For individual image entries, the display-mode, text-colour and active-time
  specifiers are applied as-is to that image.  For a directory or list entry,
  they are interpreted as defaults to be applied to every image within that
  directory or list, unless overidden by an individual list entry inside it.


  Time Periods

  The active-time field is a string consisting of any number of comma-separated
  intervals, each of which takes the form
    <hour1>-<hour2>:<weekday1>-<weekday2>
  where:
   - hour1 is the interval's starting hour (0-23, inclusive)
   - hour2 is the period's ending hour (1-24, exclusive)
   - weekday1 is the starting weekday number (1=Mon, 7=Sun)
   - weekday2 is the ending weekday number
  Each of these variables is optional.  The hyphens are required unless the
  interval specifier consists of nothing but the hour1 variable.  If neither
  weekday variable is present, the colon may be omitted.  To specify a single
  day of the week, use e.g. '1-1' for Monday.

  Examples:

  12
    Indicates that the image is only a valid background candidate after noon
    on any day of the week.

  -12:7-7
    Indicates that the image is only a valid background candidate before noon
    on Sundays.

  9-18:1-5
    Indicates that the image is only a valid background candidate on weekdays
    from 9am until 6pm.

  0-9:1-5,18-24:1-5,0-24:6-7
    Indicates that the image is a valid background candidate
     - before 9am on Monday-Friday,
     - after 6pm on Monday-Friday, and
     - at any time on Saturday or Sunday
  Note that the above could also be written as
  -9:1-5,18-:1-5,-:6-7


NOTICES

  WALLCHANGE is (C) 2021-2023 Alex Taylor.

  Redistribution and use in source and binary forms, with or without
  modification, are permitted provided that the following conditions are met:

     1. Redistributions of source code must retain the above copyright notice,
        this list of conditions and the following disclaimer.
     2. Redistributions in binary form must reproduce the above copyright
        notice, this list of conditions and the following disclaimer in the
        documentation and/or other materials provided with the distribution.
     3. The name of the author may not be used to endorse or promote products
        derived from this software without specific prior written permission.

  THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR IMPLIED
  WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
  MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO
  EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
  PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
  BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER
  IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  POSSIBILITY OF SUCH DAMAGE.


Program web site: http://altsan.org/programming/rexx/#wallchange

Alex Taylor
December 2023
