NAME

App::MathImage::X11::Protocol::XSetRoot -- set root window background

SYNOPSIS

 use App::MathImage::X11::Protocol::XSetRoot;
 App::MathImage::X11::Protocol::XSetRoot->set_background
                             (color_name => 'green');

 # or given $X, which then can't be used any more
 App::MathImage::X11::Protocol::XSetRoot->set_background
                             (X       => $X,
                              pixmap  => $pixmap_xid,
                              pixmap_allocated_colors => 1);

DESCRIPTION

This module uses an X11::Protocol connection object to set the root window background in the style of the xsetroot program.

The simplest is a named colour, interpreted by the server generally per its /etc/X11/rgb.txt file, or a 2 or 4 digit hex string "#RRGGBB" or "#RRRRGGGGBBBB".

    App::MathImage::X11::Protocol::XSetRoot->set_background
                               (color_name => 'green');

    App::MathImage::X11::Protocol::XSetRoot->set_background
                               (color_name => '#FF0000'); # red

Or a black and white pattern in a little pixmap,

    # draw $pixmap with black_pixel and white_pixel ...
    App::MathImage::X11::Protocol::XSetRoot->set_background
                               (X      => $X,
                                pixmap => $pixmap);

set_background considers that it owns the given $pixmap and will free it with FreePixmap once put into the window background.

Allocated Pixels

If the background pixmap has pixels allocated with AllocColor etc then those colours are preserved in the root colormap using "RetainPermanent" and a client ID recorded in an _XSETROOT_ID property on the root window.

When this happens any subsequent xsetroot or similar will free the colours by killing the client in that _XSETROOT_ID. This could happen immediately after setting the background, which means that after setting a background with allocated colours the $X connection cannot be used for anything more.

    # draw $pixmap with AllocColor colours
    App::MathImage::X11::Protocol::XSetRoot->set_background
                               (X      => $X,
                                pixmap => $pixmap,
                                pixmap_allocated_colors => 1);
    # don't use $X any more

pixmap_allocated_colors indicates whether colours were allocated in $pixmap, as opposed to using just the pre-defined black and white pixels.

If the root visual is static such as TrueColor then AllocColor is just a lookup, not an actual allocation. On a static visual set_background skips the RetainPermanent and _XSETROOT_ID.

Currently there's nothing returned to say whether RetainPermanent was or wasn't done and an application should assume any given $X cannot be used after a pixmap_allocated_colors or an allocated pixel.

FUNCTIONS

App::MathImage::X11::Protocol::XSetRoot->set_background (key=>value, ...)

Set the root window background to a pixmap or a pixel. The key/value parameters are

    X        => X11::Protocol object
    display  => string ":0:0" etc

    screen   => integer, eg. 0
    root     => XID of root window

    color_name => string
    pixel      => integer pixel value
    pixmap     => XID of pixmap to display
    pixmap_allocated_colors => boolean, default false

The server is given by an X connection, or display name to connect to, or otherwise the default DISPLAY environment variable.

The root window to set is given by root or screen, or otherwise the $X "chosen" screen or the display default.

What to display is given by a colour name, pixel, or pixmap. color_name can be anything understood by the server AllocNamedColor, plus 2 or 4 digit hex "#RRGGBB" or "#RRRRGGGGBBBB".

pixel is an integer pixel value in the root window colormap. It's taken to be an "allocated" pixel if it's the screen pre-defined black or white pixels.

pixmap is the XID integer. set_background considers it owns this pixmap and will FreePixmap at the right time. Pixmap 0 means no pixmap, which gives the server's default root background.

pixmap_allocated_colors should be true if any of the pixels in pixmap were allocated with AllocColor etc, as opposed to just the screen pre-defined black and white pixels.

When an allocated pixel or a pixmap with allocated pixels is set as the background the _XSETROOT_ID mechanism described above means the $X could be killed by another xsetroot at any time, so the $X connection should not be used any more. The easiest thing is to make set_background the last thing done on $X.

Setting a pixel or pixmap can only be done on a given X connection, not from a newly opened connection with the display option. This is because "retaining" with _XSETROOT_ID can only be done from the client connection which created them, not a new connection.

SEE ALSO

math-image

HOME PAGE

http://user42.tuxfamily.org/math-image/index.html

LICENSE

Copyright 2010, 2011 Kevin Ryde

Math-Image is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3, or (at your option) any later version.

Math-Image is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with Math-Image. If not, see <http://www.gnu.org/licenses/>.