EditColor Widget Class

Overview

The EditColor widget displays a panel that lets the end-user change a color. The end-user can edit the color using sliders to select values for the RGB, CMY or HLS components of the color. Alternatively, the end-user can select a new color from a list of named colors. The programmer uses the EditColor widget's resources and children's widget IDs to control the layout and contents of the Editcolor panel. For instance, the programmer can specify that the end-user can use only the RGB color model or can select only from a list of named colors that are defined by the application.

Inherited Behavior and Resources

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

The class pointer is xintEditColorWidgetClass.
The class name is XintEditColor.
The header file is included as <Xint/EditColor.h>.

The following resources are defined by the EditColor widget class:
Name	Type	Default	Access
XmNapplyCallback	XtCallbackList	NULL	C
XmNcancelCallback	XtCallbackList	NULL	C
XmNcolorFilename	char *	/usr/lib/X11/rgb.txt	CSG
XmNcolorModel	int	XintRGB	CSG
XmNcolorSelectionMode	int	XintCOLOR_SLIDER	CG
XmNeditPixel	Pixel	white	CSG
XmNhelpCallback	XtCallbackList	NULL	C
XmNokCallback	XtCallbackList	NULL	C
XmNshowApplyButton	Boolean	False	CG
XmNshowHelpButton	Boolean	False	CG
XmNshowHexValue	Boolean	True	CG
XmNsynchronizeScale	Boolean	True	CSG
XmNtitleFontList	XmFontList	"helvetica-bold-r--180-*"	CSG
XmNtitleString	XmString	NULL	CSG

Resource Value Description
XintRGB (default) The RGB slider bars will be displayed initially.
XintCMY The CMY slider bars will be displayed initially.
XintHLS The HLS slider bars will be displayed initially.

Resource Value	Description
XintRGB (default)	The RGB slider bars will be displayed initially.
XintCMY	The CMY slider bars will be displayed initially.
XintHLS	The HLS slider bars will be displayed initially.

XmNcolorSelectionMode

Specifies the methods available to the end-user for editing a color. You can specify one of the following values:

Resource Value Description
XintCOLOR_LIST Only the named color list is available.
XintCOLOR_LIST_AND_SLIDER Both the named color list and the color sliders are available.
XintCOLOR_SLIDER (default) Only the color sliders are available.

Resource Value	Description
XintCOLOR_LIST	Only the named color list is available.
XintCOLOR_LIST_AND_SLIDER	Both the named color list and the color sliders are available.
XintCOLOR_SLIDER (default)	Only the color sliders are available.

XmNeditPixel

Specifies the pixel ID of the color to be edited. If the specified pixel is associated with a read-only cell then the widget will try to allocate a read/write color cell for editing. The pixel value for this new cell can be obtained using function XintEditColorGetColor.

XmNhelpCallback

Specifies a list of callback procedures to be called each time the end-user clicks on the Help pushbutton on the EditColor panel.

XmNokCallback

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

XmNshowApplyButton

Specifies whether or not an Apply pushbutton will appear on the EditColor panel. The default is False, indicating that the Apply pushbutton will not be visible.

XmNshowHelpButton

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

XmNshowHexValue

Specifies whether or not a text widget will appear on the EditColor panel containing the current color value in hexadecimal format. The default is True, indicating that hex value will be visible.

XmNsynchronizeScale

Indicates whether or not the color displayed on the EditColor panel is updated while the user moves a slider bar. The default is True, indicating that the color displayed is updated as the slider is moved. In some hardware environments, it may be more efficient to set this resource to False, indicating that the color displayed on the EditColor panel is to be updated after the end-user stops moving a slider.

XmNtitleFontList

Specifies the font used for the title at the top of the EditColor panel.

XmNtitleString

Specifies the compound string containing the title to be placed at the top of the EditColor panel.

Internal Widgets

The following table lists the named widgets contained within an EditColor widget that are accessible to the application programmer. You can unmanage the internal widgets or change their appearance. The appearance and behavior of the internal widgets can also be specified in a resource file using the listed widget names.

Name Class Description
apply_button XmPushButtonGadget The Apply pushbutton.
cancel_button XmPushButtonGadget The Cancel pushbutton.
color_display XmDrawingArea Displays the current color.
color_list XmList List box containing named colors.
cmy_toggle XmToggleButtonGadget Selects the CMY color model.
hls_toggle XmToggleButtonGadget Selects the HLS color model.
help_button XmPushButtonGadget The Help pushbutton.
hex_text XmText Displays the hexadecimal value of the current color.
ok_button XmPushButtonGadget The OK pushbutton
radio_box XmRowColumn Contains the RGB, HLS, and CMY radio buttons.
rgb_toggle XmToggleButtonGadget Selects the RGB color model.
scale1 XmScale Top slider bar.
scale2 XmScale Middle slider bar.
scale3 XmScale Bottom slider bar.
separator1 XmSeparatorGadget Separator above the color selection mode radio box.
separator2 XmSeparatorGadget Separator above the OK, Apply, Cancel, and Help pushbuttons.
title_label XmLabelGadget Contains the optional title.

Name	Class	Description
apply_button	XmPushButtonGadget	The Apply pushbutton.
cancel_button	XmPushButtonGadget	The Cancel pushbutton.
color_display	XmDrawingArea	Displays the current color.
color_list	XmList	List box containing named colors.
cmy_toggle	XmToggleButtonGadget	Selects the CMY color model.
hls_toggle	XmToggleButtonGadget	Selects the HLS color model.
help_button	XmPushButtonGadget	The Help pushbutton.
hex_text	XmText	Displays the hexadecimal value of the current color.
ok_button	XmPushButtonGadget	The OK pushbutton
radio_box	XmRowColumn	Contains the RGB, HLS, and CMY radio buttons.
rgb_toggle	XmToggleButtonGadget	Selects the RGB color model.
scale1	XmScale	Top slider bar.
scale2	XmScale	Middle slider bar.
scale3	XmScale	Bottom slider bar.
separator1	XmSeparatorGadget	Separator above the color selection mode radio box.
separator2	XmSeparatorGadget	Separator above the OK, Apply, Cancel, and Help pushbuttons.
title_label	XmLabelGadget	Contains the optional title.

Defined Callbacks

The following callbacks are defined by an EditColor widget.

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

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

XmAnyCallbackStruct

The following ordered table lists the members of the callback structure, XmAnyCallbackStruct, used by the EditColor 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 manipulating the EditColor widget.

Function Name Description
XintCreateEditColor Creates an EditColor widget.
XintCreateEditColorDialog Creates a dialog shell containing an EditColor widget.
XintEditColorGetColor Returns the original color and the new color.
XintEditColorGetChild Returns the widget ID of a named child of an EditColor widget.
XintEditColorGetScale Returns the widget IDs of the three scale widgets.

Function Name	Description
XintCreateEditColor	Creates an EditColor widget.
XintCreateEditColorDialog	Creates a dialog shell containing an EditColor widget.
XintEditColorGetColor	Returns the original color and the new color.
XintEditColorGetChild	Returns the widget ID of a named child of an EditColor widget.
XintEditColorGetScale	Returns the widget IDs of the three scale widgets.

XintCreateEditColor

XintCreateEditColor creates an unmanaged EditColor widget.

     Widget XintCreateEditColor (...)

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

XintCreateEditColorDialog

XintCreateEditColorDialog creates an unmanaged dialog shell containing an EditColor widget.

     Widget XintCreateEditColorDialog (...)

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.

XintEditColorGetColor

Call this function to get the new color selected by the end-user.

     void XintEditColorGetColor (...)

Widget widget EditColor widget ID.
XColor * initial_color Address of an XColor structure where information about the original color will be returned.
XColor * current_color Address of an XColor structure where information about the edited color will be returned.

XintEditColorGetChild

This function returns the widget ID of a named widget internal to the EditColor widget.

     Widget XintEditColorGetChild (...)

Widget widget EditColor widget ID.
int child Code specifying the child of interest.

The following defined constants can be used to specify the value for child:

Constant Name Description
XintEDIT_COLOR_COLOR_SQUARE Current color drawing area.
XintEDIT_COLOR_HEX_TEXT Current color hex value text.
XintEDIT_COLOR_SEPARATOR Pushbutton separator.
XintEDIT_COLOR_APPLY Apply pushbutton.
XintEDIT_COLOR_CANCEL Cancel pushbutton.
XintEDIT_COLOR_HELP Help pushbutton.
XintEDIT_COLOR_OK OK pushbutton.
XintEDIT_COLOR_LIST Named color list box.
XintEDIT_COLOR_FRAME Frame containing color square.

Constant Name	Description
XintEDIT_COLOR_COLOR_SQUARE	Current color drawing area.
XintEDIT_COLOR_HEX_TEXT	Current color hex value text.
XintEDIT_COLOR_SEPARATOR	Pushbutton separator.
XintEDIT_COLOR_APPLY	Apply pushbutton.
XintEDIT_COLOR_CANCEL	Cancel pushbutton.
XintEDIT_COLOR_HELP	Help pushbutton.
XintEDIT_COLOR_OK	OK pushbutton.
XintEDIT_COLOR_LIST	Named color list box.
XintEDIT_COLOR_FRAME	Frame containing color square.

XintEditColorGetScale

Call this function to get the widget IDs of the three sliders on the EditColor panel.

     void XintEditColorGetScale (...)

Widget widget EditColor widget ID.
Widget * scale1 Widget ID returned for top slider.
Widget * scale2 Widget ID returned for middle slider.
Widget * scale3 Widget ID returned for bottom slider.

Widget	parent	Parent of new EditColor widget.
char *	name	Name of new EditColor 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	EditColor widget ID.
XColor *	initial_color	Address of an XColor structure where information about the original color will be returned.
XColor *	current_color	Address of an XColor structure where information about the edited color will be returned.