The UMSXWindow object is an Ultimedia Services Version 2 feature and does not apply to Ultimedia Services Version 1.2.1.
This class inherits from the UMSObject class.
UMSXWindow object provides an interface to the X Windowing System. Its purpose is to gather X Windowing System related methods into a single object for other objects to use. The object knows about StaticGray, TrueColor, GrayScale, PseudoColor, and DirectColor visuals. It does not know how to deal with the StaticColor visual. It can only handle specific depths and color orders of the visuals it knows about.
To learn more about the UMSXWindow object, see:
For introductory information, see Image Window and Negotiator Objects.
In general the set_display_ptr() method must be called before other methods do anything besides return an error. Usually the method is called by the superclass.
After the display, image format, and window have been set these methods can be used: put_image().
If the set_screen() method is not called, then the default screen is used.
If the set_colormap_id() method is not called then the colormap ID is found from the window.
If the colormap associated with the window does not match the colormap set with the set_colormap_id() method, then the object changes the window colormap.
The set_colormap_attributes() and set_colormap() methods are only used with the RGB8Dither image format.
If the image format is RGB8Dither and set_colormap_attributes() and set_colormap() are not called to set the colors, then the colormap is used as it is.
If set_colormap_attributes() and set_colormap() are called without calling set_colormap_id(), then the object uses the default colormap returned by DefaultColormap().
The application must manage colormaps itself if the colormap for the window is different from the top level window of the application. The application should participate in installing or uninstalling the colormap at the proper times and/or set the WM_COLORMAP_WINDOWS window manager hint.
Note: Many window managers do not pay attention to WM_COLORMAP_WINDOWS but hopefully other window managers do.
Sharing colormaps means having several XWindow objects use the same colormap.
The non-writable colormaps are easy to share because the values cannot be set to something other than what the object expects. These visual types are StaticGray and TrueColor.
If the application owns a colormap and it needs several objects to use it and the visual type is StaticGray or TrueColor, then all it needs to do is call the set_colormap_id() method for each.
If the application owns a colormap and it needs several objects to use it and the visual type is PseudoColor and the application has already allocated the colors, then all it needs to do is call the set_colormap_id() method for each. As long as the set_colormap_attributes() and set_colormap() methods are not called the objects do not attempt to allocate any color cells.
If the application owns a colormap and it needs several objects to use it and the visual type is PseudoColor and the application has NOT allocated the colors, then it needs to do two things. It needs to call the set_colormap_id() method for each object. In addition it needs to call the set_colormap_attributes() and set_colormap() methods on only one of the objects. The other objects use the same colormap but do not attempt to allocate any color cells.
Not Sharing colormaps means having several XWindow objects each use a different colormap.
For the non-writable colormaps, StaticGray and TrueColor, not sharing is pointless.
For not sharing PseudoColor there is little change from shared. The object uses the colormap set with the set_colormap_id() method. The application can allocate colors as it needs them or call set_colormap_attributes() and set_colormap() to allocate the colors.
To avoid name collision on defines, integer values have been captured as enumerated lists. The detailed method descriptions describe the valid or possible values for the specific use. The enumerated lists that are defined for this object are:
enum ReturnCode {
Success,
Failure,
UnsupportedVisual, /* set_window() */
NullPointer,
InvalidArgument,
ValueChanged
};
This method does not work with DSOM. The display must be set before doing any other operation. Changing the display requires resetting all the other values: image format, window, and colormap.
| in Display *x_display | The argument is of type (Display *). |
This method does not work with DSOM.
| out Display *x_display | The argument is of type (Display *). |
If this method is not called the default screen is used. Changing this value requires resetting all the other values: image format, window, and colormap.
| in unsigned long x_screen | The screen number to use. |
This method returns the current screen number being used by the object.
| out unsigned long x_screen | The screen number being used |
Determines visual class of passed in window, can return UnsupportedVisual.
Attention: If the window has been created recently then flush your display with the XFlush() function before calling this method.
| in unsigned long x_window | (X type Window) The window to be used. |
This method returns the window set with set_window();
| out unsigned long x_window | The value to be returned. |
The argument is of type (Colormap). A colormap is required in order to create a window that has a visual that is different than the parent window. In that case this method can be called so that the colormap is used. If this method is called it should be done before calling set_window().
| in unsigned long x_colormap_id | The colormap ID to use. |
The argument is of type (Colormap).
| out unsigned long x_colormap_id | The colormap ID being used. |
This method is called to indicate which colormap cells should be used. It might use the colormap associated with the window; it might create a new colormap. The actual colormap that is used is returned. Calling this method causes the currently saved colormap to be freed. The caller has to call set_colormap() to fill in the colormap. This method only applies when the image format is RGB8Dither.
This method returns the values set with set_colormap_attributes(). This method only applies when the image format is RGB8Dither.
| out long index | The start index of the colors to be used. This is the index of the first cell in the colormap to be used. |
| out long size | This is the number of cells in the colormap to be used. |
| Success | If no error is found. |
| Failure | If an error is found that is not described by any other return code. |
| NullPointer | If a null pointer is passed instead of &index and &size. |
This method allows the values of the colormap cells to be set. The values should only be the ones specified by the set_colormap_attributes() method. The set_colormap_attributes() method must be called before calling this method. The caller should pass the address of the sequence structure for map_really. The format of the data is one byte of pad, one byte of red, one byte of green, one byte of blue. Each colormap cell is represented by a total of four bytes. If map_really->_maximum, map_really->_length, and map_really->_buffer are all zero (NULL) then this method allocates the buffer using SOMMalloc() for the return value. If they are not zero (NULL) then this method just copies the value into the sequence. This method only applies when the image format is RGB8Dither.
For any application that wants to bind another window to the same colormap. The values returned are only the ones specified by the set_colormap_attributes() method. The caller should pass the address of the sequence structure for map. The format of the data is one byte of pad, one byte of red, one byte of green, one byte of blue. Each colormap cell is represented by a total of four bytes. If map->_maximum, map->_length, and map->_buffer are all zero (NULL) then this method allocates the buffer using SOMMalloc() for the return value. If they are not zero (NULL) then this method just copies the value into the sequence. This method only applies when the image format is RGB8Dither.
| out sequence<octet> map | The sequence inside which to return the values of the current colormap. |
This method returns the X visual ID that works with the format specified. The x_visual_id is of type (VisualID).
| in string format | The image format the caller wants to use. |
| out unsigned long x_visual_id | The X visual ID that the object can use on the current display. |
Changing the image format can require a call to set_window() with a new window that matches the new visual required to handle the new format.
| in string image_format | This is the format of the images the caller wants to send to a window. |
This method allows the caller to get the current image_format.
| out string image_format | The current image format. |
This method does an XPutImage() to the window.
This method determines if the display on a remote machine.
| out unsigned long result | This return value is zero (false) if the display is local. This value is nonzero (true) if the display is remote. |
This method determines if the current display supports the XV extension. If adaptor_name is null, it returns true if the server has the XV extension. If the adaptor_name is not null, it returns true if the server has the XV extension and one of the supported adapters' XvAdaptorInfo.name matches adaptor_name.
This method returns the X GC created inside the object. The caller should not change the GC values. And it cannot be used after the object is freed (because the object frees it). If the caller would like to change the GC values or keep it after the object has been freed then use the X function XCopyGC(). This method does not return success unless the set_window() method has been called.
| out GC x_gc | The graphics context from the object. |
This method allows the values of the colormap cells to be queried. The format of the data is one byte of pad, one byte of red, one byte of green, one byte of blue. Each colormap cell is represented by a total of four bytes. This method allocates the buffer using SOMMalloc() for the return value. This method works independent of the other colormap methods.
For introductory information, see Image Window and Negotiator Objects.