XmeGetDesktopColorCells(3XUNIX System XmeGetDesktopColorCells(3X)
NAME
XmeGetDesktopColorCells - return desktop pixel data in
XColor[] format
SYNOPSIS
#include <Xm/ColorObjP.h>
Boolean XmeGetDesktopColorCells(
Screen *screen,
Colormap colormap,
XColor *colors,
int ncolors,
int *ncolorsret);
VERSION
This page documents Motif 2.1.
DESCRIPTION
The Motif library creates and maintains a ColorObject at
application initialization time (first VendorShell creation)
which holds color information coming from a Color Server
running on the desktop (see Color Server protocol). An
application that needs to use a private colormap should
include in its colormap the desktop pixels returned by the
Color Server protocol, plus the pixels used for the desktop
icons, so that the rest of the desktop doesn't go
"technicolor" when the application colormap is installed
(and the desktop default colormap is de-installed). This
function calls XmeGetColorObjData(screen...), in order to
get the raw pixel information and fill out the XColor[]
color array for as many pixels as specified by the colorUse
attributes, and then determine the RGB components for these
pixel in the desktop colormap.
After it has retrieved the pixels of this screen's color
object using XmeGetColorObjData, and added the pixels to the
Color calculation cache in Motif (so that widgets created
with a colormap set to share pixels get the right pixels for
derived colors like shadows) this function calls
XQueryColorson the default colormap to get the RGB intensity
values for the desktop pixels in the XColor elements. It
also sets all the flags to (DoRed|DoGreen|DoBlue)in the
XColor array.
For the icon pixels, the function use XParseColorand
XAllocColor on the default colormap using the 16 standard
desktop icon color names ( "black", "white", "red", "green",
"blue", "yellow", "cyan", "magenta", "#dededededede",
"#bdbdbdbdbdbd", "#adadadadadad", "#949494949494",
"#737373737373", "#636363636363", "#424242424242",
"#212121212121") to find out the pixel ids that need to be
shared.
Page 1 (printed 1/22/99)
XmeGetDesktopColorCells(3XUNIX System XmeGetDesktopColorCells(3X)
XmeGetDesktopColorCells returns most-interesting-pixels
first, and guarantees no duplicate pixel entries (which is
not the same as duplicate RGB entries)
The order in the XColor array on return is:
⊕ Foreground and background for all 8 palettes (primary,
secondary, text, active, inactive, front-panel, ws
buttons, in that order)
⊕ Select color for primary, secondary
⊕ The icon pixels (2 for LOW_COLOR and BW, 16 for HIGH
and MEDIUM_COLOR)
⊕ Topshadow color for all 8 palettes
⊕ Bottomshadow color for all 8 palettes (same order as
above)
⊕ Rest of select colors
The idea is that if an application has only, say, 12 pixels
to spare in its colormap for the desktop, it should get
shared pixels that allow most of the desktop visual to be
usable: foreground and background colors first, mainly.
screen X screen passed in.
colormap Colormap for which the pixel are fetched
colors X color structures returned (allocated by called).
n_colors Size available in colors array.
n_colors_ret
Number of X colors elements filled by the function
RETURN VALUE
False if XmeGetColorObjData returns False, or if colorUse is
XmCO_BLACK_WHITE.
STRUCTURES
XColor is defined in Xlib.
ENVIRONMENT
The information returned by this function depends on the
presence of an active Color Server.
RESOURCES
This function is affected by the resources set on the Color
Server and useColorObj on XmScreen.
Page 2 (printed 1/22/99)
XmeGetDesktopColorCells(3XUNIX System XmeGetDesktopColorCells(3X)
ACTIONS/MESSAGES
None.
ERRORS/WARNINGS
None.
EXAMPLES
After calling this function, the application can then add
more entries to the XColor[] array (it can do that before in
fact) and call XStoreColors with this XColor[] on the new
colormap (note that if a program wants to use a private
colormap and share the desktop pixels, a ReadWrite colormap
must be used, since pixel have to be allocated at specific
location, which is not possible with read-only cells.)
static void
SetColormap(Widget widget,
int pixel_for_desktop)
{
Colormap my_colormap;
int ncolors_ret, i, p;
XColor colors[256];
if (!XtIsRealized(widget)) return;
/* create a readwrite colormap */
my_colormap = XCreateColormap(XtDisplay(widget),
XtWindow(widget),
XDefaultVisual(XtDisplay(widget), 0),
AllocAll);
/* we need to keep track of which pixel are used, mark
them all free before calling XmeGet... */
for(i=0; i<256; i++) colors[i].pixel = -1;
/* get the desktop pixels in the array */
XmeGetDesktopColorCells (XtScreen(widget), my_colormap,
colors, pixel_for_desktop,
&ncolors_ret);
/* then fill in the rest of our private colormap */
for(i=ncolors_ret, p = 0; i<256; i++) {
/* get a free pixel id */
while (p <= 255 && colors[p].pixel != -1) p ++;
colors[i].pixel = p;
color[i].flags = DoRed|DoGreen|DoBlue;
color[i].red = color[i].green = color[i].blue = i * 256;
}
XStoreColors(XtDisplay(widget), my_colormap, colors, 256);
XtVaSetValues(widget, XmNcolormap, my_colormap, NULL);
}
Page 3 (printed 1/22/99)
XmeGetDesktopColorCells(3XUNIX System XmeGetDesktopColorCells(3X)
main () {
toplevel = XtAppInitialize(...);
XtRealizeWidget(toplevel);
SetColormap (toplevel, 40);
...
}
SEE ALSO
, , XmeGetColorObjData(3)
Page 4 (printed 1/22/99)