Dogcows Code - chaz/openbox/blob - doc/bsetbg.1

   1 .TH bsetbg 1 "February 2002" "bsetbg" "v2.0"
   2 .SH NAME
   3 bsetbg \- utility to manipulate the appearance of the X11 desktop's root window.
   4 .SH SYNOPSIS
   5 \fBbsetbg\fR [options] \fIimage\fR
   6 .SH DESCRIPTION
   7 \fBbsetbg\fR is intended to provide a standard method for the \fIBlackbox\fR
   8 window manager to alter the background of the root window
   9 (although it will work with any other window manager as well). \fBbsetbg\fR
  10 acts as a wrapper both to \fIbsetroot\fR
  11 and to a flexible variety of third-party applications that it uses when handling images files.
  12
  13 .SH OPTIONS
  14 .TP
  15 \fB\-f\fR, \fB\-full\fR \fIimage\fR
  16 \fIimage\fR is stretched to fill the entire desktop.
  17 .TP
  18 \fB\-t\fR, \fB\-tile\fR \fIimage\fR
  19 \fIimage\fR is tiled on the desktop.
  20 .TP
  21 \fB\-c\fR, \fB\-center\fR \fIimage\fR
  22 \fIimage\fR is centered on the desktop.
  23 .TP
  24 \fB\-e\fR, \fB\-exec\fR \fIprogram\fR \fIoptions\fR \fIfallback\-\fIarg\fR \fIimage\fR
  25 This option tells \fBbsetbg\fR to run a seperate command by executing \fIprogram\fR with
  26 \fIoptions\fR, where \fIoptions\fR are arguments to \fIprogram\fR.
  27
  28 If a \fIfallback\-arg\fR is supplied (\fB\-full\fR, \fB\-tile\fR, or \fB\-center\fR
  29 as described above),
  30 \fBbsetbg\fR will assume that the last argument is a filename. In the case that
  31 \fIprogram\fR exits non-zero or isn't available on the target system, \fBbsetbg\fR
  32 will try to handle the file with the fallback argument.
  33
  34 See the \fBEXAMPLES\fR section for more information on \fB\-exec\fR.
  35 .TP
  36 \fB\-p\fR, \fB\-post\fR \fIlist\fR
  37 Specifies a list of arguments to pass to the $POST_COMMAND.
  38 .TP
  39 \fB\-d\fR, \fB\-debug\fR
  40 Debugging mode. \fBbsetbg\fR will print commands without executing them.
  41 .TP
  42 \fB\-g\fR, \fB\-generate\fR \fIlist\fR
  43 Output a list of default configuration values, suitable for redirecting into
  44 \fI~/.bsetbgrc\fR. Any arguments that are supplied will be considered applications
  45 to search for in the system path, overriding \fBbsetbg\fR's internal defaults.
  46 .TP
  47 \fB\-v\fR, \fB\-version\fR
  48 Output version number.
  49 .TP
  50 \fB\-h\fR, \fB\-help\fR
  51 Output a brief usage message.
  52
  53 .SH OTHER OPTIONS
  54 \fBbsetbg\fR will also accept all of the arguments for \fIbsetroot\fR.
  55 Consult the \fIbsetroot\fR(1) man page for further information.
  56
  57 .SH CONFIGURATION
  58 \fBbsetbg\fR will read its configuration values from the file \fI~/.bsetbgrc\fR
  59 if it exists. Otherwise, it will scan the
  60 system path for a pre-defined list of image applications to use
  61 (currently this list consists of qiv, xli, xv, wmsetbg, Esetroot,
  62 display, and xsetbg).
  63 \fP
  64 \fI~/.bsetbgrc\fR should contain the following variables:
  65 .TP
  66 \fB    CENTER=\fR\fI"string"\fR
  67 Application and arguments to be used to center an image on the root window
  68 when the \fB-center\fR argument is specified.
  69
  70 .TP
  71 \fB    FULL=\fR\fI"string"\fR
  72 Application and arguments to be used to stretch an image to fill the root window
  73 when the \fB-full\fR argument is specified.
  74
  75 .TP
  76 \fB    TILE=\fR\fI"string"\fR
  77 Application and arguments to be used to tile an image on the root window
  78 when the \fB-tile\fR argument is specified.
  79
  80 .TP
  81 \fB    DEFAULT=\fR\fI"string"\fR
  82 Action to take place by default if none of the above have been specified.
  83
  84 .TP
  85 The following variables are optional:
  86
  87 .TP
  88 \fB    NO_EXEC=\fR\fI"boolean"\fR
  89 If this variable is set, bsetbg will never modify the root window.
  90
  91 .TP
  92 \fB    POST_COMMAND=\fR\fI"string"\fR
  93 This variable specifies a command that \fBbsetbg\fR will run after every
  94 successful modification of the root window.
  95
  96 .TP
  97 \fB    LOG_LAST_CMD=\fR\fI"boolean"\fR
  98 If this variable is set, \fBbsetbg\fR will keep a logfile of the last two
  99 successful commands.
 100
 101 .TP
 102 \fB    LOGFILE=\fR\fI"string"\fR
 103 This variable can specify the logfile to be used when $LOG_LAST_CMD is defined.
 104 The default is ~/.bsetbg_last_cmd .
 105
 106 .TP
 107 As mentioned above, \fBbsetbg\fR will function perfectly for the majority of users without having a configuration file. Power users who want more control over \fBbsetbg\fR's behavior should run \fBbsetbg -g\fR and use the output to create a \fI~/.bsetbgrc\fR which may then be tweaked by hand.
 108
 109 .SH EXAMPLES
 110 In this example, bsetbg will set the image in centered mode:
 111
 112     bsetbg -center foo.png
 113
 114 An example of the \fB-exec\fR argument:
 115
 116     bsetbg -exec xv -root -quit -rmode 5 -rbg rgb:2/2/2 \\
 117         -center foo.png
 118
 119 An example in which bsetbg creates a configuration file using xv and qiv:
 120
 121         bsetbg -g xv qiv > ~/.bsetbgrc
 122
 123 .SH AUTHOR
 124 The author of
 125 .B bsetbg
 126 may be reached at \fItmk@lordzork.com\fR.
 127
 128 .SH SEE ALSO
 129 \fIblackbox\fR(1), \fIbsetroot\fR(1), \fIqiv\fR(1), \fIxli\fR(1), \fIxv\fR(1), \fIdisplay\fR(1),
 130 \fIwmsetbg\fR(1)