VkVisual(3x)
VkVisual - convenience class for dealing with X11 visuals
As shipped in IRIX 6.5.7. Last changed in IRIX 6.5.5.
NAME VkVisual - 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) 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 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". 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. FUNCTION DESCRIPTIONS VkVisual() 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() 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 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() ); 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. 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. 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) 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. 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 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 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. 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 ... VkVisual vis(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; VkVisual vis(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. 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. 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(). 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 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 ALSO VkApp(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