VkVisual(3x)VkVisual(3x)NAMEVkVisual - convenience class for dealing with X11 visuals
HEADER FILE
#include <Vk/VkVisual.h>
PUBLIC PROTOCOL SUMMARY
Constructors, Destructor
VkVisual (Widget w = NULL, Boolean forceNewCmap=FALSE)
VkVisual (const VkComponent *component,
Boolean forceNewCmap=FALSE)
VkVisual (int visualClass, int level=NORMAL_LEVEL,
int colors=MAX_AVAILABLE_COLORS,
CARD32 xparentRequested=TRANSPARENT_DONT_CARE,
Boolean forceNewCmap=FALSE)
VkVisual (const VkVisual&)
VkVisual &operator =(const VkVisual&)
virtual ~VkVisual()
Constructors - ViewKit 2.1 only
VkVisual (VkScreen *screen,
int visualClass, int level=NORMAL_LEVEL,
int colors=MAX_AVAILABLE_COLORS,
CARD32 xparentRequested=TRANSPARENT_DONT_CARE,
Boolean forceNewCmap=FALSE)
Setting the Class' Visual Information
virtual Colormap setColormap(Colormap cmap=NULL,
Boolean setDefault=FALSE)
virtual void setVisual (Widget w = NULL,
Boolean forceNewCmap=FALSE)
virtual void setVisual (const VkComponent *component,
Boolean forceNewCmap=FALSE)
virtual VkVisual::status setVisual
(int visualClass, int level,
int colors, CARD32 transparent,
Boolean forceNewCmap=FALSE)
Page 1
VkVisual(3x)VkVisual(3x)
Data Access Functions
virtual int argCnt() const
virtual ArgList argList() const
virtual void argList(Arg *args,
Cardinal *offset) const
inline void argList(Arg *args, int *offset) const
const char *className( void ) const
virtual Colormap colormap() const
virtual Boolean colormapCreated() const
virtual int depth() const
virtual int maxLevel() const
virtual int minLevel() const
virtual int numColors() const
virtual Visual *visual() const
virtual VisualID visualID() const
virtual const VkVisualInfo *vkVisualInfo
( VisualID vis) const
virtual const VkVisualInfo *vkVisualInfo
( Visual *vis=NULL) const
virtual const VkVisualInfo *vkVisualInfo
( const Widget w) const
virtual const VkVisualInfo *vkVisualInfo
( int index) const
virtual Window window() const
Debugging Functions
virtual const char *indexString(index) const
virtual const char *planesString(planes) const
virtual void printAll() const
virtual void print( ) const
virtual void print( VisualID vid) const
virtual void print( const Visual *vis) const
virtual void print( const Widget w) const
Page 2
VkVisual(3x)VkVisual(3x)
virtual void print( int index) const
virtual void print( const VkVisualInfo *vis) const
virtual const char *statusString(status) const
virtual const char *transparencyString(transparency) const
virtual const char *visualClassString(int) const
Static Functions
static Widget visualParent( Widget w, Visual ** )
static void visualParentArgs(Widget parent,
Arg *args, int *cnt)
Enums
enum colors {MAX_AVAILABLE_COLORS}
enum index {RESET, FIRST, NEXT, LAST}
enum planes {NORMAL_LEVEL,
OVERLAY_LEVEL, UNDERLAY_LEVEL,
MAX_OVERLAY_LEVEL, MIN_OVERLAY_LEVEL,
MAX_UNDERLAY_LEVEL, MIN_UNDERLAY_LEVEL,
ANY_LEVEL}
enum status {FAILURE, SUCCESS, ALMOST}
enum transparency
{TRANSPARENT_NONE, TRANSPARENT_PIXEL,
TRANSPARENT_MASK, TRANSPARENT_DONT_CARE}
CLASS DESCRIPTION
Dealing with the interaction between widgets and X11 visuals can get
complicated. Some applications either get it wrong, or else stick with
the default visual when another would be more appropriate. Code, even
library code, that assumes default visual attributes is commonplace.
Such an assumption is especially bad in a library, because libraries must
work with applications that use non-default visuals.
VkVisual() makes it easy for an application to set up the X11 visual
information it needs. Using VkVisual, it is easy to do such things as:
o get an existing widget's full visual information.
o to pick the best visual for a Shell or for an entire application by
describing its semantic characteristics. This includes such things
as getting the "deepest overlay visual".
Page 3
VkVisual(3x)VkVisual(3x)
o get information about the default visual.
o deal with actual visuals, default or non-default, in a consistent
and robust way that works across different kinds of hardware.
o Get a suitable window for use when creating a GC or a pixmap.
On an SGI workstation, Widget access to the popup or overlay bitplanes is
by means of non-default X11 visuals. There are a few things that one
needs to be careful of when using Xt widgets with non-default visuals.
(For further information about X11 and Xt handling of visual information,
see below.)
The VkVisual class simplifies this task. Because it simplifies the
model, VkVisual cannot do all possible things. Applications that have
more complex needs than those addressed by VkVisual will still need to
use direct Xlib and/or OpenGL calls instead.
The VkVisual class itself deals with global things, such as:
o Associating a single colormap with a single visual
o Coordinating X11 visual information with that provided by the root
window's SERVER_OVERLAY_VISUALS property.
Each VkVisual instance deals with all of the information pertinent to a
single visual. The visual can be set to be:
o a caller-defined visual
o the same visual a specific widget is using
o the same visual a specific ViewKit component is using
o the default visual
The visual information can also be reset to a new visual (using
setVisual()), but all old visual information is then lost. If an
application will continue to need to refer to both sets of visual
information, it should create a second VkVisual object, not just reset
the first one.
Information such as the colormap or the read-only ArgList are created as
needed. Any such information is cached, and reused as appropriate.
Page 4
VkVisual(3x)VkVisual(3x)FUNCTION DESCRIPTIONSVkVisual()
VkVisual(VkComponent *comp, Boolean forceNewCmap=FALSE);
Create a VkVisual object whose visual attributes match those of
comp->baseWidget().
VkVisual()
VkVisual(Widget w=NULL, Boolean forceNewCmap=FALSE);
Create a VkVisual object whose visual attributes match the widget's.
If w is NULL, default visual information is set up.
VkVisual()VkVisual (int visualClass, int level=NORMAL_LEVEL,
int colors=MAX_AVAILABLE_COLORS,
CARD32 transparency=TRANSPARENT_DONT_CARE,
Boolean forceNewCmap=FALSE)
Create a VkVisual object as close to the specified calling
parameters as possible. For how "close" is determined, see the
description of setVisual(), below.
VkVisual() - ViewKit 2.1 only
VkVisual (VkScreen *screen,
int visualClass, int level=NORMAL_LEVEL,
int colors=MAX_AVAILABLE_COLORS,
CARD32 transparency=TRANSPARENT_DONT_CARE,
Boolean forceNewCmap=FALSE)
Create a VkVisual object as close to the specified calling
parameters as possible on the specified VkScreen. For how "close"
is determined, see the description of setVisual(), below.
VkVisual()VkVisual (const VkVisual&)
This is the copy constructor.
VkVisual()
Page 5
VkVisual(3x)VkVisual(3x)VkVisual &operator =(const VkVisual&)
This is the "operator =" constructor.
~VkVisual()
virtual ~VkVisual();
The destructor deletes the instance. Global information, such as a
visual/colormap pairing, is undisturbed.
enum colors
enum colors {MAX_AVAILABLE_COLORS}
Using this for the number of colors in the constructor, or in a
setVisual() call, means that the deepest visual that otherwise
satisfies the request criteria is considered a match.
enum index
enum index {RESET, FIRST, NEXT, LAST}
This is passed to vkVisualInfo(int) or print(int) when using it to
iterate over the visuals list.
enum planes
enum planes {NORMAL_LEVEL,
OVERLAY_LEVEL, UNDERLAY_LEVEL,
MAX_OVERLAY_LEVEL, MIN_OVERLAY_LEVEL,
MAX_UNDERLAY_LEVEL, MIN_UNDERLAY_LEVEL,
ANY_LEVEL}
This specifies which level bit planes are being requested. These
constants do not conflict with any legitimate specific level. Calls
to the constructor, or to setVisual(), can specify either the
explicit level required or one of these enum values.
NORMAL_LEVEL - request for the normal planes
OVERLAY_LEVEL - request for any overlay planes
UNDERLAY_LEVEL - any underlay planes
MAX_OVERLAY_LEVEL - highest available overlay level
MIN_OVERLAY_LEVEL - lowest available overlay level
Page 6
VkVisual(3x)VkVisual(3x)
MAX_UNDERLAY_LEVEL - underlay level that is the closest to zero
MIN_UNDERLAY_LEVEL - underlay level that is the furthest from zero
ANY_LEVEL - don't care which level
enum status
enum status {FAILURE, SUCCESS, ALMOST}
These are the values that setVisual() can return. It is up to an
application to notice that it did not get SUCCESS, and make
appropriate adjustments if it needs to.
SUCCESS - the visual found is exactly what was requested.
ALMOST - the visual found is likely to be close enough. It is up to
the application to query any attributes it cares about to see
whether the attribute is acceptable.
FAILURE - there was a serious problem, such as could not get the
right visual class. This generally means that the default visual
had to be assigned, rather than what was requested.
The lowest status found in processing any of the parameters is returned.
I.e. if anything failed, FAILURE. Else if anything was ALMOST, then that
is returned. SUCCESS is returned only if everything succeeded.
enum transparency
enum transparency {TRANSPARENT_NONE, TRANSPARENT_PIXEL,
TRANSPARENT_MASK, TRANSPARENT_DONT_CARE}
This is the kind of transparency that is requested.
argCnt()
virtual int argCnt() const
Returns the number of visual arguments that a call to argList() will
supply. The number this returns could change in a future release.
argList()
virtual ArgList argList() const
Returns pointer to a read-only ArgList, suitable for using in an Xt
call such as:
VkVisual vis (parent);
XtSetValues( w, vis.argList(), vis.argCnt() );
Page 7
VkVisual(3x)VkVisual(3x)argList()
virtual void argList(Arg *args, Cardinal *offset) const
Appends the visual arguments to the ArgList args, beginning at
position offset, and then increments the offset by the number of
arguments it appended.
argList()
inline void argList(Arg *args, int *offset) const
An overloaded version of the previous call. This one takes an int*
instead of a Cardinal*
className()
const char *className( void ) const
The class name of VkVisual is "VkVisual".
colormap()
virtual Colormap colormap() const
Returns the colormap associated with this instance of VkVisual. If
there is no colormap, an empty sharable one will be created.
colormapCreated()
virtual Boolean colormapCreated() const
Returns TRUE iff the current colormap was created by VkVisual. This
can be used by the application to tell whether or not the colormap
should be destroyed when no longer needed.
Failure to destroy colormaps that VkVisual creates causes colormap
leakage in the X server. Fortunately, from a practical point of
view, most applications do not need to be concerned with this:
o All created colormaps are deleted when the application terminates.
Unless a lot of colormaps are being created, this is adequate.
o VkVisual reuses colormaps. Unless the application sets
forceNewColormap or uses setColormap(), there will be at most one
colormap for each visual used. This is normally few enough that
they can be ignored until they are destroyed when the application
terminates.
o Any VkVisual that is constructed by passing it a widget uses the
colormap from that widget. Such a colormap should not be explicitly
destroyed.
Page 8
VkVisual(3x)VkVisual(3x)depth()
virtual int depth() const
Returns the depth associated with this instance's visual.
indexString()
const char *indexString(planes) const
Debug function: print (on stderr) the string equivalent to the
passed enum value.
maxLevel()
virtual int maxLevel() const
Returns the maximum framebuffer level for the current screen.
minLevel()
virtual int minLevel() const
Returns the minimum framebuffer level for the current screen.
numColors()
virtual int numColors() const
Returns the number of colors in the colormap associated with this
instance's visual.
planesString()
const char *planesString(planes) const
Debug function: print (on stderr) the string equivalent to the
passed enum value
print()
void print() const
Debug function: print (on stderr) the visual information from the
VkVisual instance.
print()
void print(VisualID vid) const
Debug function: print (on stderr) the visual information matching
the Visual ID.
Page 9
VkVisual(3x)VkVisual(3x)print()
void print(Visual *vis) const
Debug function: print (on stderr) the visual information matching
the X visual.
print()
void print(Widget w) const
Debug function: print (on stderr) the visual information matching
the Widget.
print()
void print(int index) const
Debug function: print (on stderr) the visual information matching
the VkVisual whose index is given.
print()
void print(const VkVisualInfo *vis) const
Debug function: print (on stderr) the visual information from vis.
printAll()
void printAll() const
Debug function: print (on stderr) a variety of details about the
visuals of the current display.
setColormap()
virtual Colormap setColormap(Colormap cmap=NULL,
Boolean setDefault=FALSE)
If there is a passed-in colormap, makes it current. If there is no
colormap, create a new empty one that matches the current visual.
If setDefault is True, make the new colormap be the default one for
the visual associated with this VkVisual instance. Return the now-
current colormap.
setVisual()
virtual void setVisual (Widget w = NULL,
Boolean forceNewCmap=FALSE)
Page 10
VkVisual(3x)VkVisual(3x)
Resets the VkVisual to the visual of the widget or gadget, or if
NULL then the default visual.
If forceNewCmap is true, you are guaranteed a new, empty, colormap.
Otherwise, VkVisual will reuse an existing colormap for this visual
if one is available. Unless you know you need a new colormap, you
should leave this FALSE.
setVisual()
virtual void setVisual (const VkComponent *component,
Boolean forceNewCmap=FALSE)
Resets the VkVisual to the visual used by component->baseWidget().
If forceNewCmap is true, you are guaranteed a new, empty, colormap.
Otherwise, VkVisual will reuse an existing colormap for this visual
if one is available. Unless you know you need a new colormap, you
should leave this FALSE.
setVisual()
virtual VkVisual::status setVisual
(int visualClass, int level,
int colors, CARD32 transparent,
Boolean forceNewCmap=FALSE)
Resets the visual to be as close to the specified calling parameters
as possible. This function always sets some visual. It will set
the default visual, if there is no better match.
o visualClass - must be one of the constants from <X11/X.h>
(StaticGray, GrayScale, StaticColor, PseudoColor, TrueColor, or
DirectColor).
If the application asks for a class that is not supported by the
current screen, setVisual() returns FAILURE and provides the default
visual.
o level - setVisual() always tries to give you the type of planes you
asked for (i.e. a specific level, overlay planes, underlay planes,
or normal planes).
If the value is one of the enum constants, that is used. Else if
the value is greater than the maximum level, then the maximum level
is used. Else if the value is less than the minimum level, then the
minimum level is used. Else the value is a legal explicit level and
it is used directly.
Page 11
VkVisual(3x)VkVisual(3x)
If the requested plane(s) exist for the specified visual class, the
status is SUCCESS.
If the requested plane(s) have no visual of the requested class, but
there is a normal planes visual of the requested class, then that is
the visual and the status is ALMOST.
Otherwise, setVisual() sets the default visual, and returns FAILURE.
o colors - is either MAX_AVAILABLE_COLORS or else the actual number of
colors needed, not counting any transparent pixel. For example,
most 2-bit overlays only have 3 colors (and one transparent pixel).
8-bit visuals have 256 colors, unless there is a transparent pixel.
setVisual() tries to get a visual that supports at least the
requested number of colors. If it can do that, the status is
SUCCESS. Otherwise, it does the best it can and the status is
ALMOST.
o transparency - one of TRANSPARENT_NONE, TRANSPARENT_PIXEL,
TRANSPARENT_MASK, or TRANSPARENT_DONT_CARE.
o forceNewCmap - If forceNewCmap is true, you are guaranteed a new,
empty, colormap. Otherwise, VkVisual will reuse an existing
colormap for this visual if one is available. Unless you know you
need a new colormap, you should leave this FALSE.
setVisual() tries to get a visual that supports the requested type
of transparency. If it can, the status is success. Otherwise, it
does the best it can and the status is ALMOST.
statusString()
const char *statusString(status) const
Debug function: print (on stderr) the string equivalent to the
passed enum value.
transparencyString()
const char *transparencyString(transparency) const
Debug function: print (on stderr) the string equivalent to the
passed enum value.
visual()
virtual Visual *visual() const
Page 12
VkVisual(3x)VkVisual(3x)
Returns this instance's visual.
visualClassString()
const char *visualClassString(int) const
Debug function: print (on stderr) the string equivalent to the
passed enum value ("Pseudocolor", etc).
visualID()
virtual VisualID visualID() const
Returns the visual ID of this instance's visual.
visualParent()
static Widget visualParent( Widget w, Visual ** )
Returns the first widget, higher in the widget tree, that has a
visual attribute. Normally, this widget will be a subclass of
Shell, but it could be an SgVisualDrawingArea or any other widget
that has an XmNvisual resource.
visualParentArgs()
static void visualParentArgs(Widget parent, Arg *args, int *cnt)
This gets a set of visual resources, appropriate to the parent
widget. The resources are copied into args, and cnt is updated.
All resources except the visual are copied from the parent. Visual
is copied from the visualParent(parent).
vkVisualInfo()
virtual const VkVisualInfo *vkVisualInfo( VisualID vid) const
Returns a pointer to the VkVisualInfo structure associated with the
visual whose ID is vid.
vkVisualInfo()
virtual const VkVisualInfo *vkVisualInfo( Visual *vis=NULL) const
Returns a pointer to the VkVisualInfo structure associated with the
specified visual. If vis is NULL, the current visual is used.
vkVisualInfo()
virtual const VkVisualInfo *vkVisualInfo( Widget w) const
Page 13
VkVisual(3x)VkVisual(3x)
Returns a pointer to the VkVisualInfo structure associated with the
widget's visual.
vkVisualInfo()
virtual const VkVisualInfo *vkVisualInfo( int index ) const
Returns a pointer to one of the VkVisualInfo structures from the
global list maintained by VkVisual. Possible arguments are:
<number> - an integer from 0 to the number of available visuals
retrieve a pointer to that VkVisualInfo structure.
RESET - resets the global record so that a call to
vkVisualInfo(NEXT) will return a pointer to the first structure.
Returns NULL.
FIRST - returns a pointer to the first structure.
NEXT - returns a pointer to the first structure beyond the
previously retrieved one, regardless of how it was retrieved. If
the previously retrieved structure was the last structure, a RESET
is done and a NULL pointer is returned. The next vkVisualInfo(NEXT)
call will retrieve (a pointer to) the first structure.
LAST - returns a pointer to the last structure.
window()
virtual Window window() const
Returns a window associated with this instance's visual.
VkApp's window is used for that visual. The root window is used for
its visual. For any other X11 visual, a matching new InputOutput
unmapped window will be created the first time a window is needed
for that particular visual. Windows will reused later as necessary.
Separate VkVisual instances will return the same window if the
instances are for the same X11 visual.
Note that there is no guarantee as to which window you will get
back, even if you used the VkVisual(widget) constructor. Typical
use of this window is as a parameter to create a GC or to call the
Xpm pixmaps routines (which derive visual information from the
window they are passed).
Because a window may be re-used, it is important that the
application not delete it.
Page 14
VkVisual(3x)VkVisual(3x)Examples of Putting A Widget In A Non-Default Visual
1) Using VkVisual, putting a single widget in a non-default visual is
very straight-forward.
Widget p; // Parent widget
char *c="Questions"; // Widget's name
...
VkVisualvis(p); // Get the visual info
XmCreateQuestionDialog
(p, c, vis.argList(), vis.argCnt());
...
2) Putting your entire application into a non-default visual is only a
little more complicated. See VkApp(3X).
3) Creating a GC of the right depth:
Display *dpy;
VkVisualvis(widget);
...
XCreateGC ( dpy, vis.window(), .... )
REVIEW OF X11 VISUAL INFORMATION
Many developers do not quite understand how X and Xt deal with
information that is related to X11 visuals. This information is
important if one is going to put part or all of an application's GUI in a
non-default visual. Following is a summary of some of the more important
points.
X11 Visual Attributes
X11 does not attach any semantic meaning to a visual. For example, there
is no concept of an "overlay visual". There is, however, a semi-standard
convention that has been adopted by SGI and by some other workstation
vendors:
o A visual's level is the framebuffer level the visual is associated
with. This is a hardware-related term. It has nothing to do with X
window stacking order.
o Levels less than zero are underlays. As of this writing (8/96), SGI
has no hardware that has underlay planes that are supported by the X
server.
o Level zero is the normal planes. The default visual is generally
(but not necessarily) in the normal planes.
Page 15
VkVisual(3x)VkVisual(3x)
o Levels greater than zero are overlay planes.
o Each X11 visual is associated with exactly one level.
o SERVER_OVERLAY_VISUALS is a property on the root window, relating
each X11 visual to its level.
An X11 window has several attributes that need to be consistent when the
window is created. If an application sets these values inconsistently,
or if it allows an inconsistent value to be inherited, the X server will
return a fatal BadMatch error.
o XCreateWindow(3X) must be passed a consistent visual and depth.
o Certain fields in the XSetWindowAttributes structure that is passed
to XCreateWindow(3X) must be consistent with the visual and depth.
The significant fields are:
background pixmap - must be NULL or of the stated depth.
background pixel - is used if the background pixmap is NULL. The
pixel value must not exceed the colormap size.
border pixmap - must be NULL or of the stated depth.
border pixel - is used if the border pixmap is NULL. The pixel
value must not exceed the colormap size.
colormap - must match the visual.
The depth and visual cannot be changed after the window is created. The
XSetWindowAttributes values can be changed later.
Xt Visual Handling
Xt does not make it easy to achieve the required consistency when dealing
with widgets in non-default visuals. Under the Xt widget model:
o A gadget does not have any visual resources of its own, because it
draws into its parent's window.
o Each widget class, because it is derived from the Core class, has
borderPixmap, borderColor, colormap, and depth attributes. Each
widget instance inherits the values of these attributes from its
parent widget.
Page 16
VkVisual(3x)VkVisual(3x)
o If a widget does not have an XmNvisual resource, its visual cannot
be explicitly set at creation time. Most widgets do not have a
visual resource, so they must inherit their visual. The only way
these widgets can be put into a non-default visual is for their
widget parent to be in that visual.
o The only standard widgets that have an XmNvisual resource (and hence
an X11 visual) directly associated with them are Shell and its
subclasses. (Note: there can also be special widgets, such as the
SgVisualDrawingArea widget ( <Sgm/VisualDrawingA.h> ), that have an
associated X11 visual. Such special widgets are not common.)
o Any widget that does not have a visual resource explicitly set at
creation time inherits its visual from its parent window. For all
widgets other than Shell widgets, the parent window is the parent
widget's window. This results in inheriting a consistent set of
values, and there is no problem.
However, the situation is different for a Shell widget. Its parent
window is the root window. Thus, if the parent widget is using a
different visual than the root window's visual, you must explicitly
set at least some of the Shell's visual resources. If you do not,
you will get an X server BadMatch fatal error.
To avoid mismatches, ViewKit explicitly sets the visual information for
all new Shell widgets it creates. This includes all menus and dialogs.
Shell visual attributes are set to, in priority order:
o If visual information is passed in by the application, it is used.
o If the widget is a menu, and useOverlayMenus is set, an appropriate
visual is chosen.
o If the widget is a dialog, and useOverlayDialogs is set, an
appropriate visual is chosen.
o Otherwise ViewKit sets the Shell (i.e. menu or dialog) to the widget
parent's visual.
The net effect is that most ViewKit applications do not need to worry
about this.
It is possible to place the top shell (VkApp's unrealized shell) in a
non-default visual. Because of the inheritance described above, That
effectively resets the visual for the rest of the application. (See
VkApp(3X), topics useOverlayApps() and preRealizeFunction().
Page 17
VkVisual(3x)VkVisual(3x)
Visual consistency issues are important when creating Shell widgets.
They are also important at other times. For example, you cannot use a
pixmap or a GC at a depth other than the one it was created for.
Colormaps
Pixel values need to be kept consistent. In general, the same pixel will
not be the same color in the various colormaps. Be sure you use the
correct pixel value for the current colormap.
The BlackPixel and WhitePixel macros should be avoided. They do as X11
documents and return pixel values suitable for use with the default
colormap. BlackPixel returns a pixel which is black in the normal planes
colormaps, but is generally transparent in overlay colormaps.
Another common way to get inconsistent pixel values is for an application
to determine a pixel value using the default colormap, and then to use it
in a different colormap. If the pixel exists, you are likely to get the
wrong color. If the pixel does not exist (such as when you try to apply
a pixel greater than 3 to a 2-bit overlay colormap), you will get an X
protocol error.
If you do decide to put widgets in one of the overlay visuals, remember
that the colormap may well be smaller than the default one. And don't
forget that pixel 0 is apt to be transparent.
Some hardware has a 2-bit level 1 visual, a 2-bit level 2 visual, and a
4-bit level 1 visual that are not entirely independent. The two-bit
colormaps will be independent, but they may overlap with the 4-bit
colormap. The framebuffer pixels of the 4-bit visual may overlap with
those of the 2-bit visuals. On such hardware, using the 4-bit visual is
discouraged.
Colormap Coordination
There is no such thing as a system default colormap for any visual other
than the default visual. If a VkVisual instance refers to the default
visual, it automatically uses the default colormap. The first VkVisual
instance that refers to each non-default visual creates a suitable
colormap for that visual. Subsequent VkVisual instances that refer to
the same visual re-use the colormap the first instance created. This
effectively establishes default colormaps for a single application.
There is no supported way for multiple independent applications to
cooperate on using a common colormap. If we get to where there is a
default colormap for the various visuals, VkVisual will provide it.
An application is only guaranteed to have its colormaps installed when it
has colormap focus. Consequently, there may be colormap flashing. When
an application gets colormap focus, all of the colormaps the application
has declared get installed (whether or not it actually needs them).
These colormaps remain until another application needs to have one of
Page 18
VkVisual(3x)VkVisual(3x)
them replaced. Any of your application's windows that need a conflicting
colormap will not return to correct colors until your application next
gets colormap focus.
o Override widgets (e.g. pull-down and popup menus) are responsible
for installing their own colormaps. They will not get their
colormaps installed - ever - unless the application does something
about it.
o Likewise, overlay dialogs will not get their color maps installed
until the dialog gets colormap focus.
o ViewKit arranges automatic installation of colormaps for the menu
and dialog widgets it creates. Otherwise you must call
XSetWMColormapWindows() yourself.
KNOWN CLASSES THAT USE THIS CLASS
Any ViewKit class that puts up any kind of a Shell widget uses this
class. That includes VkApp, VkSimpleWindow, VkFileSet, VkGraph,
VkIconButton, VkMeter, VkOutline, VkHelpAPI, the VkIcon* and VkPixmap*
classes, the dialog classes, and the menu classes.
SEE ALSOVkApp(3), VkDialogManager(3), VkMenu (3), VkSimpleWindow(3), VkSubMenu
(3)
ViewKit Programmer's Guide
The X Window System, DEC Press, Bob Scheifler and Jim Gettys
The X Window System Toolkit, DEC Press, Paul Asente and Ralph Swick
Page 19
