EditColormap Widget Class

Overview

The EditColormap widget displays two panels that offer alternative methods for changing one or more colors in the application's colormap. The colors can be edited individually or in groups using an interpolation algorithm. An individual color is edited by using an EditColor widget instantiated by the EditColormap widget or by graphically defining a new value for the red, green and/or blue components of a color. In addition, provided functions can store a colormap file on disk, retrieve a colormap file from disk and generate a colormap to be used during editing.

Inherited Behavior and Resources

The EditColormap widget inherits behavior and resources from Core, Composite, Constraint, Manager, and BulletinBoard classes.

The class pointer is xintEditColormapWidgetClass.
The class name is XintEditColormap.
The header file is included as <Xint/EditColormap.h>.

The following resources are defined by the EditColormap widget class:
Name	Type	Default	Access
XmNannotationFontList	XmFontList	"fixed"	CSG
XmNbias	int	0	CSG
XmNcancelCallback	XtCallbackList	NULL	C
XmNcolormapFile	char *	NULL	CSG
XmNcolorNumberFontList	XmFontList	"fixed"	CSG
XmNcontrast	int	0	CSG
XmNdoubleClickInterval	int	250	CSG
XmNhelpCallback	XtCallbackList	NULL	C
XmNnumberOfColors	int	0	CSG
XmNokCallback	XtCallbackList	NULL	C
XmNpixelArray	Pixel *	NULL	C
XmNshowHelpButton	Boolean	False	CSG
XmNshowBiasScale	Boolean	True	CSG
XmNshowContrastScale	Boolean	True	CSG
XmNshowRotateScale	Boolean	True	CSG
XmNtitleFontList	XmFontList	"helvetica-bold-r--180-*"	CSG
XmNtitleString	XmString	NULL	CSG

When a colormap file is used by the EditColormap widget to generate the colors to be edited, this resource should not be specified by you because the widget will set it to the number of colors defined in the colormap file.

XmNokCallback

Specifies the list of callback procedures called when the user clicks on the OK pushbutton on the EditColormap panel.

XmNpixelArray

Specifies the array of pixels to be edited. This array must be at least as large as the value specified by the resource, XmNnumberOfColors.

XmNshowHelpButton

Specifies whether or not a Help pushbutton will appear on the Color Square Panel. The default is False, indicating that the Help pushbutton will not be visible.

XmNshowBiasScale

Specifies whether or not a bias scale will appear on the Color Square Panel. The default is True, indicating that the bias scale will be visible.

XmNshowContrastScale

Specifies whether or not a contrast scale will appear on the Color Square Panel. The default is True, indicating that the contrast scale will be visible.

XmNshowRotateScale

Specifies whether or not a colormap rotate scale will appear on the Color Square Panel. The default is True, indicating that the colormap rotate scale will be visible.

XmNtitleFontList

Specifies the font used for the title at the top of the Color Square Panel and Color Diagram Panel.

XmNtitleString

Specifies the compound string containing the title to be placed at the top of the Color Square Panel and Color Diagram Panel. If this resource value is NULL (the default), then no title will appear.

Internal Widgets

The following table lists the named widgets contained within an EditColormap widget that are accessible to the application programmer. The appearance of the internal widgets can be specified in a resource file using the listed widget names.

Name Class Description
title_label XmLabelGadget Contains the optional title.
frame XmFrame The frame widget surrounding the colormap drawing area.
cmap_display XmDrawingArea Drawing area where the continuous spectrum of colors in the colormap is drawn.
cmap_square XmDrawingArea Where the color squares in the colormap are drawn.
interpo_radio_box XmRowColumn The radio box containing the interpolation radio buttons.
linear_toggle XmToggleButtonGadget The linear interpolation radio button.
tanh_toggle XmToggleButtonGadget The tanh interpolation radio button.
spline_toggle XmToggleButtonGadget The spline interpolation radio button.
rotate_scale XmScale The scale for rotating the colormap.
bias_scale XmScale The scale for the bias.
contrast_scale XmScale The scale for the contrast.
color_number_toggle XmToggleButtonGadget The check box controlling the display of the color numbers.
diagram XmDrawingArea Drawing area where the color intensity diagram is drawn.
toggle_box XmRowColumn The box containing the color component check boxes on the Color Diagram Panel.
red XmToggleButtonGadget The red component check box.
green XmToggleButtonGadget The green component check box.
blue XmToggleButtonGadget The blue component check box.

Name	Class	Description
title_label	XmLabelGadget	Contains the optional title.
frame	XmFrame	The frame widget surrounding the colormap drawing area.
cmap_display	XmDrawingArea	Drawing area where the continuous spectrum of colors in the colormap is drawn.
cmap_square	XmDrawingArea	Where the color squares in the colormap are drawn.
interpo_radio_box	XmRowColumn	The radio box containing the interpolation radio buttons.
linear_toggle	XmToggleButtonGadget	The linear interpolation radio button.
tanh_toggle	XmToggleButtonGadget	The tanh interpolation radio button.
spline_toggle	XmToggleButtonGadget	The spline interpolation radio button.
rotate_scale	XmScale	The scale for rotating the colormap.
bias_scale	XmScale	The scale for the bias.
contrast_scale	XmScale	The scale for the contrast.
color_number_toggle	XmToggleButtonGadget	The check box controlling the display of the color numbers.
diagram	XmDrawingArea	Drawing area where the color intensity diagram is drawn.
toggle_box	XmRowColumn	The box containing the color component check boxes on the Color Diagram Panel.
red	XmToggleButtonGadget	The red component check box.
green	XmToggleButtonGadget	The green component check box.
blue	XmToggleButtonGadget	The blue component check box.

Defined Callbacks

The following callbacks are defined by an EditColormap widget.

Name Structure Reason
XmNcancelCallback XmAnyCallbackStruct XmCR_CANCEL
XmNhelpCallback XmAnyCallbackStruct XmCR_HELP
XmNokCallback XmAnyCallbackStruct XmCR_OK

Name	Structure	Reason
XmNcancelCallback	XmAnyCallbackStruct	XmCR_CANCEL
XmNhelpCallback	XmAnyCallbackStruct	XmCR_HELP
XmNokCallback	XmAnyCallbackStruct	XmCR_OK

The following ordered table lists the members of the callback structure, XmAnyCallbackStruct, used by the EditColormap widget for all of its callbacks.

Data Type Member Description
int reason Indicates why the callback was invoked.
XEvent *event Points to the XEvent that triggered the callback.

Data Type	Member	Description
int	reason	Indicates why the callback was invoked.
XEvent	*event	Points to the XEvent that triggered the callback.

Defined Functions

The following functions are defined for creating and using an EditColormap widget.

Function Name Description
XintCreateEditColormap Creates an unmanaged EditColormap widget.
XintCreateEditColormapDialog Creates a dialog shell containing an unmanaged EditColormap widget.
XintGenerateColormap Generates a colormap containing gray scale colors.
XintGetColormapBiasContrast Returns the bias and contrast values from a colormap file.
XintIsColormapFile Determines whether a specified file is a colormap file.
XintReadColormap Generates a colormap containing the colors defined in a colormap file.
XintParseColormapFile Creates an array of XColor structures based upon the colors defined in a colormap file.
XintEditColormapFreeColors Frees the pixels in the pixel array allocated by the XintReadColormap and XintGenerateColormap functions.
XintEditColormapUpdate To update the colormap display if the user has changed the mapping of the pixel values to RGB externally.

Function Name	Description
XintCreateEditColormap	Creates an unmanaged EditColormap widget.
XintCreateEditColormapDialog	Creates a dialog shell containing an unmanaged EditColormap widget.
XintGenerateColormap	Generates a colormap containing gray scale colors.
XintGetColormapBiasContrast	Returns the bias and contrast values from a colormap file.
XintIsColormapFile	Determines whether a specified file is a colormap file.
XintReadColormap	Generates a colormap containing the colors defined in a colormap file.
XintParseColormapFile	Creates an array of XColor structures based upon the colors defined in a colormap file.
XintEditColormapFreeColors	Frees the pixels in the pixel array allocated by the XintReadColormap and XintGenerateColormap functions.
XintEditColormapUpdate	To update the colormap display if the user has changed the mapping of the pixel values to RGB externally.

XintCreateEditColormap

XintCreateEditColormap creates an unmanaged EditColormap widget.

     Widget XintCreateEditColormap (...)

Widget parent Parent of new EditColormap widget.
char * name Name of new EditColormap widget.
ArgList arglist List of resource/value items.
Cardinal argcount Number of items in arglist.

XintCreateEditColormapDialog

XintCreateEditColormapDialog creates an unmanaged dialog shell containing an EditColormap widget.

     Widget XintCreateEditColormapDialog (...)

Widget parent Parent of new dialog shell.
char * name Name of new dialog shell.
ArgList arglist List of resource/value items.
Cardinal argcount Number of items in arglist.

XintGenerateColormap

This function allocates a gray scale colormap for use with a specified EditColormap widget.

     Pixel *XintGenerateColormap(...)

Widget widget A widget ID (It does not need to be and EditColormap Widget).
int num_colors Specifies the number of colors to allocate in the new colormap.
int * err_code Error code returned in case of error.

In case of error, the function returns NULL and the argument err_code contains a pointer to an error code. Possible error codes include

Error Code Description
XintBAD_ALLOC_COLOR Indicates that the colormap could not be generated.

Error Code	Description
XintBAD_ALLOC_COLOR	Indicates that the colormap could not be generated.

XintGetColormapBiasContrast

This function returns the bias and contrast values saved into a colormap file. If the bias or contrast values are not specified in the colormap file, they are set to 0.

     void XintGetColormapBiasContrast (...)

Widget widget A widget ID (It does not need to be and EditColormap Widget).
char * filename Specifies the colormap file to be read.
int * bias Returns the bias value.
int * contrast Returns the contrast value.
int * err_code Returns an error code in case of error.

If the specified filename cannot be open, err_code is set to XintOPEN_ERROR, otherwise it is set to 0.

XintIsColormapFile

This function returns True if a specified file contains an EditColormap colormap definition; otherwise, it returns False.

     Boolean XintIsColormapFile (char *filename)

where filename is the name of the file to be checked.

XintReadColormap

This function reads a specified colormap file and allocates read-write color cells based upon the colormap file. A pointer to the array of Pixels in the colormap is returned if the file was read successfully and if the colormap was allocated successfully.

     Pixel *XintReadColormap (...)

Widget widget A widget ID (It does not need to be and EditColormap Widget).
char * filename Specifies the colormap file to be read.
int * num_colors Returns the number of colors in colormap.
int * err_code Returns an error code in case of error.

In case of error, the function returns NULL and the argument err_code contains a pointer to an error code. Possible error codes include:

Error Code Description
XintBAD_ALLOC_COLOR Indicates that the colormap could not be generated.
XintBAD_COLORMAP Indicates that an error occurred while reading the colormap file.
XintOPEN_ERROR Indicates that an error occurred while opening the colormap file.

Error Code	Description
XintBAD_ALLOC_COLOR	Indicates that the colormap could not be generated.
XintBAD_COLORMAP	Indicates that an error occurred while reading the colormap file.
XintOPEN_ERROR	Indicates that an error occurred while opening the colormap file.

XintParseColormapFile

This function reads a specified colormap file and allocates an array of XColor structures based upon the colormap file. A pointer to the XColor structures is returned, if the colormap file was read successfully. No color cells are allocated by this function.

     XColor *XintParseColormapFile (...)

char * filename Specifies the colormap file to be read.
int * num_colors Returns the number of colors in the colormap.
int * err_code Returns an error code in case of error.

In case of error, the function returns NULL and the argument err_code contains a pointer to an error code. Possible error codes include:

Error Code Description
XintBAD_COLORMAP Indicates that an error occurred while reading the colormap file.
XintOPEN_ERROR Indicates that an error occurred while opening the colormap file.

Error Code	Description
XintBAD_COLORMAP	Indicates that an error occurred while reading the colormap file.
XintOPEN_ERROR	Indicates that an error occurred while opening the colormap file.

XintEditColormapFreeColors

This function frees the colormap allocated by the functions XintReadColormap or XintGenerateColormap. Call this function after the application has finished with the colormap generated by XintReadColormap or XintGenerateColormap to free the colormap cells allocated by those functions.

     void XintEditColormapFreeColors (...)

Widget widget Specifies a widget ID that is using the same colormap as the one that was used when allocating the pixels to be freed.
Pixel * pixels Specifies the colormap used by the EditColormap widget.
int num_colors Specifies number of pixels in the pixels array to be freed.

XintEditColormapUpdate

This function is used to update the display of the EditColormap when the application has changed the mapping of the pixels to RGB externally.

     void XintEditColormapUpdate (Widget widget)

where widget specifies the ID of the EditColormap widget.

Widget	parent	Parent of new EditColormap widget.
char *	name	Name of new EditColormap widget.
ArgList	arglist	List of resource/value items.
Cardinal	argcount	Number of items in arglist.

Widget	parent	Parent of new dialog shell.
char *	name	Name of new dialog shell.
ArgList	arglist	List of resource/value items.
Cardinal	argcount	Number of items in arglist.

Widget	widget	A widget ID (It does not need to be and EditColormap Widget).
int	num_colors	Specifies the number of colors to allocate in the new colormap.
int *	err_code	Error code returned in case of error.

char *	filename	Specifies the colormap file to be read.
int *	num_colors	Returns the number of colors in the colormap.
int *	err_code	Returns an error code in case of error.

Widget	widget	Specifies a widget ID that is using the same colormap as the one that was used when allocating the pixels to be freed.
Pixel *	pixels	Specifies the colormap used by the EditColormap widget.
int	num_colors	Specifies number of pixels in the pixels array to be freed.