background(1)

NAME
     background - customization panel for setting background pattern


SYNOPSIS
     /usr/sbin/background


DESCRIPTION
     The background customization panel is used to edit the background for a
     particular desk.  The user is presented with a list of different
     backgrounds.  All backgrounds except those using the graphics library
     (GL) can be previewed.  The user can select a background, modify its
     colors if it is a non-GL pattern, then apply the background pattern to
     the current desk.


     The background panel can be run from a Unix shell command line or from
     the toolchest (Desktop > Customize > Background).  Like most other
     customization panels, the background panel has the ``runonce'' feature,
     meaning only one instance of the application will at one time.
     Attempting to launch the application a second time will have the effect
     of deiconifying the application window or popping it to the top on the
     current desk.


     For more information about the entire IRIX Interactive Desktop
     environment and about the XUSERFILESEARCHPATH environment variable, see
     the IID(1) man page.


FILES
     The backgrounds presented in this panel can be stored in one of two
     files:

     /usr/lib/X11/system.backgrounds (system default)
     $HOME/.backgrounds              (user)


     Either the user's backgrounds or the system default backgrounds will be
     presented in the background panel.  If a $HOME/.backgrounds file exists,
     then the backgrounds on that list will be presented in the panel.
     Otherwise the backgrounds in the system default file will be presented.
     If the user desires to append some backgrounds to the system default
     list, the user must first copy the system default file to the
     $HOME/.backgrounds file in their home directory, then use a text editor
     to append new background entries to that file.


     Each background entry has the following format:

         background     <name>
         command        <4Dwm command>
         default        <default command>
         readok         <file1>, <file2>, ...


     The background line defines the name of the background that the user will
     see from the customization panel.


     The command line specifies the command that will be passed to 4Dwm, which
     handles the management of backgrounds.  This command can have formatting
     characters (%1 %2 %3 ...) representing how many colors the background
     requires as well as how many the user may edit, up to a maximum of five
     colors.

     Currently all command formats acceptable to the xsetroot(1) command may
     be used, as well as a -xpm option for files in X pixmap (xpm) format.

     Additionally a -execute option allows execution of any background setting
     command (for example, twilight(6D)).  However, use of arbitrary
     backgrounds set via the -execute command may degrade performance,
     especially if file manager icons are on the background.  Also note that
     to integrate with the IRIX Interactive Desktop environment, any X program
     introduced as a new background (for example, xearth) needs to set the
     _SGI_ROOTPAINTER_ID property on its window and on the root window.  (This
     property needs to be of type WINDOW and have a value of the window on
     which the property is set.)  If the background-setting program does not
     set this property, then the window manager, 4Dwm(1X), will not know on
     which window to perform an XKillClient operation when the user switches
     desks or selects a new background.  Without the property set, the
     background-setting program can run multiple times, which can load the
     system unnecessarily.  In short, users can have any X program running as
     their background, but if that program does not set the
     _SGI_ROOTPAINTER_ID property, then they need to kill that program
     manually every time they switch desks or switch backgrounds.

     The default line designates the image the user will originally see in the
     viewer as well as its default colors.


     The readok command checks that the files listed can actually be read.  If
     they can not, the background will not be presented to the user in the
     background panel.


     For example, the following is the entry for the two-color Scatter
     background pattern:

     background "Scatter"
        command "-bitmap /usr/include/X11/bitmaps/granite -bg %1 -fg %2"
        default "-bitmap /usr/include/X11/bitmaps/granite -bg lightsteelblue3 -fg honeydew1"
        readok "/usr/include/X11/bitmaps/granite"
NOTES
     4Dwm caches backgrounds for all desks.  If a user has many desks, each
     using many colors, the colors can fill up the colormap.  Similarly, if
     many desks each have large background pixmaps, much server memory can be
     used.

     Setting a background via the -execute flag in the background panel
     differs from setting the same background from the command line in that
     those backgrounds set via the background panel will be remembered across
     desk switches and restarted automatically when returning to the desk.
     Backgrounds started from the command line will be forgotten after a desk
     switch.  (However, backgrounds set using the xsetroot(1) command will be
     remembered across desk switches.)


SEE ALSO
     4Dwm(1X), xsetroot(1), ov(1), IID(1)


BUGS
     The maximum number of editable colors in the customization panel is five.
     If a pixmap contains more than that many, only the first five will be
     available in the palette beneath the image viewing area.