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 where 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. " "). 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 -:- 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