Image Widget Class

Overview

The Image widget class displays an image inside a grid along with an optional color scale. An instance of the Image widget class or of a widget class derived from the Image widget class can be used to display and manipulate images. The Image widget class inherits all of the capabilities of its superclasses (CompBase, EditObject and Grid widget classes). Therefore, grid lines, multiple axes, zooming, hardcopy output and graphic object creation and editing can be performed with an Image widget.

Inherited Behavior and Resources

The Image widget inherits behavior and resources from the Core, Composite, Constraint, Motif Manager, INT CompBase, EditObject and Grid classes.
The following resources are defined by the Image widget class:
NameTypeDefaultAccess
XmNbuildPixmapBooleanTrueCSG
XmNcolormapFilechar *NULLCSG
XmNcolorRecordXintColorRec *NULLCSG
XmNcolorScaleintXintCOLOR_SCALE_NONECSG
XmNcolorScaleAnnotationListchar **NULLCSG
XmNcolorScaleSizeint350CSG
XmNimageXImage *NULLCSG
XmNimageBackgroundPixelwhiteCSG
XmNimageForegroundPixelblackCSG
XmNinterpolatePixmapBooleanTrueCSG
XmNpixmapPixmapXmUNSPECIFIED_PIXMAPCSG

XmNbuildPixmap

Specifies how the image display is updated. The default is True, indicating that the widget will use an XImage to build a pixmap for updating the image display. This method of updating the image display is preferable when running over a network (because the pixmap is located on the server system). When this resource is set to False, updating is done using an XImage that resides on the client system. This method of updating is recommended when the memory on the server system is limited or when the server system limits the size of the pixmap.

XmNcolormapFile

Specifies a colormap file for allocating a colormap for the image display.

XmNcolorRecord

Specifies a pointer to an opaque structure of type XintColorRec that describes the colormap to be used by the XintImage widget when displaying the image. If a pointer to an XintColorRec structure is not specified as the value of this resource and a colormap file has been specified, then the widget creates a XintColorRec structure based on the colormap file. If both resources, XmNcolormapFile and XmNcolorRec are NULL, then the widget allocates an XintColorRec structure based upon a 64 gray scale colormap.

XmNcolorScale

Specifies whether a color scale will be displayed to the left or to the right of the image display. Specify XintCOLOR_SCALE_NONE, XintCOLOR_SCALE_LEFT or XintCOLOR_SCALE_RIGHT. The color scale will be displayed only if a colormap has been allocated.

XmNcolorScaleAnnotationList

Specifies an array of character strings to be used to annotate the color scale. The last element in the array must be a NULL character string. The character strings are equally spaced from top to bottom of the color scale. If the value of this resource is NULL, the Image widget will automatically annotate the color scale.

XmNcolorScaleSize

Specifies the height in pixels of the color scale. Specify XintFULL_SIZE to have the color scale extend to the full size of the window.

XmNimage

Specifies an XImage to be used as the image displayed.

XmNimageBackground

Specifies a color (as a Pixel value) to be used as the background color of the image. Only used with images of depth 1.

XmNimageForeground

Specifies a color (as a Pixel value) to be used as the foreground color of the image. Only used with images of depth 1.

XmNinterpolatePixmap

Specifies whether the image displayed is scaled using pixel replication when the window containing the image is resized. The default is False, indicating that the image will not be scaled using pixel replication.

XmNpixmap

Specifies the ID of a pixmap to be used to display the image.

Using the XintColorRec Structure

The XintColorRec structure is an opaque data structure that contains a description of the color pixels to be used by the widget. This structure can be created by the application or by the Image widget. Several Image widgets can use the same XintColorRec structure and thus share the same colors. You can create an XintColorRec structure by calling the XintImageCreateColorRecord with a pixel array that you have previously allocated. Otherwise, if the XmNcolorRecord resource is NULL when the widget is created, the widget will allocate an XintColorRec structure and set the XmNcolorRecord accordingly. If the XmNcolormapFile resource is specified, then the widget will use the colors defined in the colormap file to allocate the colors. If neither XmNcolorRecord nor XmNcolormapFile is specified, then the widget will create an XintColorRec structure based upon a 64 gray scale colormap. If the XintColorRec structure has been created by the widget, it will be freed automatically by the widget when the structure is no longer needed.

Colormap Files

Image widgets (or widgets derived from the Image widget class) can read a file that defines a colormap and use it to create a color record. You specify a colormap file for use by the widget via the resource, XmNcolormapFile. The colormap file is formatted as an ASCII file containing a line giving the number of colors defined in the colormap file, followed by lines specifying the red, green and blue intensities of a color as integers between 0 and 65535. The following is an example of a colormap file where the first color is black and the last color is white. 

    ncolors = 7
    bias = 7      # optional field
    contrast = 0  # optional field
    0       0      0
    10000   1870   5482
    30942   20056  59035
    1004    46003  900
    10023   4938   5933
    58332   800    35
    65535   65535  65535

Defined Functions

The following functions are defined for creating and manipulating an Image widget.

Function NameDescription
XintImageColorRecordFreeFrees a color record structure that was allocated with function XintImageCreateColorRecord.
XintCreateImageCreates an unmanaged Image widget.
XintImageCreateColorRecordCreates a color record based upon a specified array of pixels.
XintImageCropPixmapReturns the Pixmap ID of the portion of an image displayed by an Image widget.
XintImageEditColormapCauses an EditColormap dialog to be created so that the end-user can edit the image's colormap.
XintImageGetColorRecordReturns the color record used by the image widget.
XintImageInstallColormapFileCauses a specified colormap file to be used to define a new color record for the image displayed.

XintImageColorRecordFree

Frees a color record structure that was allocated with function XintImageCreateColorRecord. The function also frees the color pixels if the visual class is PseudoColor. If the color record is still used by a widget or an object, the function will not free the structure but simply decrement a link count, so that the color record will be freed only when it is no longer used. 

     Boolean XintImageColorRecordFree(...)

WidgetwidgetWidget ID of the Image widget containing the color record to be freed .
XintColorRec *color_recordPoint s to the color record structure to be freed.

This function returns False if the specified color record structure cannot be freed. Otherwise, it returns True.

XintCreateImage

XintCreateImage creates an unmanaged Image widget. 

     Widget XintCreateImage (...)

WidgetparentParent of the new Image widget.
char *nameName of the new Image widget.
ArgListarglistList of resource/value items.
CardinalargcountNumber of items in arglist.

XintImageCreateColorRecord

Creates an XintColorRec structure based upon colors specified as an array of pixels. Use the resource XmNcolorRecord to specify that a color record created by this function is to be used by the Image widget when displaying an image. 

     XintColorRec * XintImageCreateColorRecord (...)

Pixel *pixel_array Points to an array of colors indicated by pixel value.
intnum_colorsNumber of elements in the pixel array.

XintImageCropPixmap

Returns the Pixmap ID of the specified portion of an image displayed by an Image widget. 

     Pixmap XintImageCropPixmap (...)

WidgetwidgetThe Image widget of interest.
int *xX pixel coordinate of upper left hand vertex of the cropped image.
int *yY pixel coordinate of upper left hand vertex of the cropped image.
int *widthThe width of the cropped image in pixels.
int *heightThe height of the cropped image in pixels.

If there is no image currently displayed by the specified Image widget or if the specified area is invalid, then this function returns NULL.

XintImageEditColormap

Causes an EditColormap widget to be created and displayed so that the end-user can change the colormap used for the image display. 

     Boolean XintImageEditColormap (Widget widget)

where widget is the widget ID of the widget containing the image whose colormap is to be edited.

If the color record of the Image widget is NULL, then this function will display an error message to the end-user and will return False to the application program.

XintImageGetColorRecord

Returns a pointer to the color record being used by the specified Image widget. You can specify this color record to other Image widgets (via the XmNcolorRecord resource) so that they share a common colormap. 

     XintColorRec *XintImageGetColorRecord (Widget widget)

where widget is the widget ID of the Image widget whose color record you wish to reference.

XintImageInstallColormapFile

Causes an Image widget to modify its color record based upon the colors specified in a colormap file. The display of the image displayed by the Image widget will be updated automatically. 

     Boolean XintImageInstallColormapFile(...)

Widgetwidget Widget ID of the Image widget containing the color record to be modified.
char *filenameSpecifies the name of a colormap file to be read.

This function returns False if the specified colormap file cannot be read. Otherwise, it returns True.