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 background patterns presented in this panel are derived from 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>
         default        <default command>


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


     The default line specifies the command that will be passed to 4Dwm, which
     handles the management of backgrounds. The following options may be used
     in the default line:

         -xpm      <filename>     XPM image with changeable colors
         -image    <filename>     Hicolor image of any supported format
         -bitmap   <filename>     Bitmap to use
         -solid    <color>        Specify a solid color, may be
         -colors   <list>         List of formatting characters - see
         -fg       <color>        Foreground color for use with bitmap
         -bg       <color>        Background color for use with bitmap
         -mod      <x> <y>        Grid parameters, see xsetroot(1)


     The -image option supports any image format which is known to
     imgformats(1). You are not able to use the -image option with any other
     option (you may not have any changeable colors for images specified with
     the -image option).

     The -bitmap option supports any X Bitmap file, with colors specified with
     the -fg and -bg options.

     The -colors option typically has a number of colors after it which
     represent the default colors for that background, as well as how many the
     user may edit, up to a maximum of five. This option may only be used in
     combination with the -xpm option.

     The -fg and -bg options specify the foreground and background colors to
     be used with X Bitmap images. Typically formatting characters will be
     used with these options. They may only be used in combination with the
     -bitmap option.

     Additionally a -execute option allows execution of any background setting
     command.  However, use of this option is not recommended as it can
     seriously degrade performance.  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.)

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

     background "Scatter"
        default "-bitmap /usr/include/X11/bitmaps/granite -bg lightsteelblue3 -fg honeydew1"



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.

     IRIX 6.5.14 introduced some new non-GL background patterns: Citrus
     Citrus, Camouflage, Sand, Sky (HDTV), Sprinkle, Reef, Reef (HDTV),
     Midnight, and Iron.  Except for Sprinkle, these new patterns are
     unusually large pixmaps; their sizes are 1280x1024 pixels except the
     "HDTV" backgrounds which are intended for 1920x1200-pixel screens.  The
     large backgrounds can be used on monitors at any resolution, but they
     look best when the screen matches their size.

     Using the new 1280x1024 and 1920x1200 backgrounds will cause Xsgi, the
     background panel and 4Dwm to consume several megabytes more memory than
     usual, hence it is recommended that these large desktop patterns be
     applied prudently.  It will take longer for the background panel to
     display the previews for these large patterns than for the small ones,
     and login may take several more seconds, but desk switching should not
     suffer performance degradation.  The user can free the consumed memory by
     clicking the background panel's Close button, by applying a smaller
     pattern then restarting 4Dwm (System > Utilities > Restart Window Manager
     on the toolchest), and/or by logging out.  To avoid consuming much memory
     on low-memory IRIX workstations, do not apply any of the new large
     pixmaps to any desk's background and remember to close the background
     panel when done previewing patterns.

     Here is an example $HOME/.backgrounds entry for an RGB background:

     background "Genesis"
        default "-image /usr/tmp/genesis.rgb"



     4Dwm records the user's chosen backgrounds (including any color
     customizations) for every desk in the user's $HOME/.Sgiresources file.


     Previous to IRIX 6.5.22, extra lines were required in the backgrounds
     file (to check that a file was readable, or for a general command).  In
     IRIX 6.5.22, the background panel was improved (so that it is able to
     decide which files are required by looking at the default line). Any
     extra lines, if present, are now ignored.

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.