| Previous | Contents | Index |
The color model option menu subwidget lets users of your application choose the color model supported by the color mixer subwidget. (See Section 6.4.4 for information about the color mixer subwidget.) The color models appear as items in the option menu. Users can switch among color models at any time.
When the color model is changed, the color mixing widget preserves the current color definition, translating the values that define the color in the current color model into values appropriate to the new-color model.
The color model option menu subwidget appears in the color mixing
widget only when the default color mixer subwidget is used.
6.4.4 Color Mixer Subwidget
The color mixer subwidget provides graphic tools that users can use to define colors. When a user changes a value in the color mixer subwidget, the color mixing widget immediately updates the color displayed in the new-color window of the color display subwidget.
The default color mixer subwidget supports the Color Picker, HLS, RGB, Browser, and Greyscale mixer color models. You can specify which color model the color mixer subwidget initially supports by assigning a value to the DXmNcolorModel resource. If you do not specify a color model, the color mixer subwidget default is determined by the system type of the display device.
Use the constants listed in Table 6-1 to specify the color model in the DXmNcolorModel resource. Table 6-1 also describes when the various color models are used as the default.
| Color Model | Constant | When Default |
|---|---|---|
| Color Picker | DXmColorModelPicker | Color systems |
| HLS | DXmColorModelHLS | Not used as a default |
| RGB | DXmColorModelRGB | Monochrome systems |
| Browser | DXmColorModelBrowser | Not used as a default |
| Greyscale | DXmColorModelGreyscale | Grayscale systems |
The Color Picker model does not display on noncolor systems. If you specify the Color Picker color model in the DXmNcolorModel resource and the application is displayed on a noncolor system, the color mixer subwidget uses the default color model for that system.
The HLS, RGB, and Browser color models and the Greyscale mixer display on color, grayscale, and monochrome systems. However, the color display subwidget is not visible on static gray and monochrome devices.
For information about replacing the default color mixer subwidget with
a widget of your own design, see Section 6.5.2.
6.4.5 Push-Button Subwidgets
By default, the color mixing widget contains five push-button subwidgets labeled OK, Apply, Reset, Cancel, and Help. When activated, the OK, Apply, and Cancel push buttons cause the color mixing widget to perform a callback to your application.
The Reset and Help push buttons do not trigger a callback to your application because they have built-in functions that are internal to the color mixing widget. |
When activated, the Reset button changes the values in the color mixer subwidget and the color displayed in the new-color window of the color display subwidget back to their initial values. The Help button displays help on using the color mixing widget.
You implement the functions associated with the color mixing widget push buttons. The OSF/Motif Style Guide contains specific recommendations about what functions should be associated with push buttons containing labels such as OK, Apply, and Cancel. The following list restates these recommendations as they might be implemented with the color mixing widget:
Use callback routines to implement the functions you want associated with these push buttons. You associate these callback routines with the callback resources of the color mixing widget. For example, to associate a function with the OK push button, use the XmNactivateCallback resource. (For more information about associating callback routines with the color mixing widget, see Section 6.6.)
Note that you can change the text displayed in the push-button
subwidgets. (See Section 6.4.6 for details.) You can also remove any of
the push-button subwidgets by specifying a null value for the text
label.
6.4.6 Label Subwidgets
The color mixing widget contains more than a dozen labels you can use
to provide descriptive text for the components of the color mixing
widget. Section 6.4.6 describes how to specify text for these labels.
6.4.7 Work Area Subwidget
The color mixing widget can contain a work area subwidget, if your application supplies one. The color mixing widget manages this subwidget and positions it below the color mixer subwidget and above the push-button subwidgets.
The work area subwidget can be any other Toolkit widget, such as a label, push button, or dialog box widget. If you use a dialog box widget, use only the work area style of this widget.
For example, your application can use this additional subwidget to
include additional push-button widgets to extend the functions of the
color mixing widget.
6.4.8 Setting and Retrieving New Color Values
If your application does not use the default color display subwidget, you might need to set or retrieve the RGB values of the new color displayed in the color display subwidget. You can use the XtSetValues and XtgetValues intrinsic routines for this purpose. However, the DECwindows Motif Toolkit provides support routines that let you perform these tasks much faster.
To set the values of the DXmNnewRedValue, DXmNnewGreenValue, and DXmNnewBlueValue resources, use the DXmColorMixSetNewColor support routine. You specify the values of these resources as arguments to the routine. The default color display subwidget updates the new-color window to represent the newly defined color.
To retrieve the value of the new-color resources, use the DXmColorMixGetNewColor support routine. This support routine writes the current values of the DXmNnewRedValue, DXmNnewGreenValue, and DXmNnewBlueValue resources into variables that you pass as arguments to the routine.
Table 6-2 summarizes the support routines for the color mixing widget.
| Routine | Description |
|---|---|
| DXmColorMixGetNewColor | Retrieves the current values of the new-color resources. |
| DXmColorMixSetNewColor | Assigns values to the new-color resources. |
You can customize the following aspects of the appearance and function of the color mixing widget:
The color mixing widget sizes itself to fit the subwidgets that it contains. For example, if you specify long compound strings as values for the label subwidgets, the color mixing widget increases its size to accommodate the labels. (You do not need to set the common widget resources XmNwidth and XmNheight to 0 [zero] to get the default size.)
In the default color display subwidget, you can specify the size of the windows in which the original and new colors are displayed. By default, each of these windows is 80 pixels square. Use the DXmNdisplayColWinWidth resource and the DXmNdisplayColWinHeight resource to specify the dimensions of these windows. Specify these dimensions in pixels. These resources affect only the default color display subwidget.
DXmNpickerTileHeight---Specifies the height of each individual Color Picker spectrum tile in pixels. The default is 30 pixels.
DXmNpickerTileWidth---Specifies the width of each individual Color Picker spectrum tile in pixels. The default is 30 pixels.
DXmNinterpTileHeight---Specifies the height of each individual Color Picker interpolator tile in pixels. The default is 30 pixels.
DXmNinterpTileWidth---Specifies the width of each
individual Color Picker interpolator tile in pixels. The default is 30
pixels.
6.4.9.2 Specifying Margins
You can specify the amount of space surrounding the subwidgets contained in the color mixing widget. Use the common widget resource XmNmarginWidth to specify the amount of space between the left and right edges of the subwidgets. (The default is 10 pixels.) Use the common widget resource XmNmarginHeight to specify the amount of space between the top and bottom edges of the subwidgets. (The default is 10 pixels.) Specify these margins in pixels.
In addition, you can specify the amount of space surrounding the two
window widgets in the default display subwidget. Use the
DXmNdispWinMargin resource to specify the size for all
the margins in the display subwidget. (The default is 20 pixels.) The
DXmNdispWinMargin resource affects only the default
color display subwidget.
6.4.9.3 Labeling the Color Mixing Widget
You can specify the text in each of the labels contained in the color mixing widget by assigning values to the color mixing widget label resources, described in DECwindows Extensions to Motif. You must specify these labels as compound strings.
For example, the DXmNmainLabel resource specifies the text that appears at the top of the color mixing widget, centered between the left and right borders. The following UIL code fragment sets the value of the DXmNmainLabel resource to "Colormix Example":
object main_color : DXmColorMixDialog
{
arguments
{
XmNdialogTitle = "DECburger: Background Color";
DXmNmainLabel = compound_string("Colormix Example");
};
callbacks
{
XmNhelpCallback = procedure sens_help_proc(k_options_help);
XmNcancelCallback = procedure cancel_color_proc();
XmNokCallback = procedure ok_color_proc();
XmNapplyCallback = procedure apply_color_proc();
};
};
|
If you do not specify values for the DXmNmainLabel, DXmNdisplayLabel, or DXmNmixerLabel resources, the color mixing widget does not include these label subwidgets. If you specify a null value for the XmNokLabelString, XmNapplyLabelString, DXmNresetLabelString, or XmNcancelLabelString resources, the color mixing widget deletes the push-button subwidget.
Note that the resources that specify the text labels in the color mixer
subwidget work only with the default color mixer subwidget.
6.4.9.4 Defining the Background Color of the Color Display Subwidget
Use the DXmNbackRedValue,
DXmNbackGreenValue, and
DXmNbackBlueValue resources to define the background
color of the display subwidget. These resources work only with the
default color display subwidget.
6.4.9.5 Adding a Work Area to the Color Mixing Widget
To specify that the color mixing widget contain a work area subwidget, create the widget that you want to be the subwidget and assign the widget identifier as the value of the XmNworkWindow resource.
You do not have to manage the work area subwidget.
6.4.9.6 Customizing the Color Picker Color Model
You can use the resources described in Table 6-3 to customize the Color Picker color model.
| Resource Name | Description |
|---|---|
| DXmNpickerColors |
A palette of 10 colors available through the user palette menu option.
If not specified, the user palette does not appear in the menu. If a
user palette is specified, it is the default palette accessible to the
user through this menu. (The other palettes remain available.)
DXmNpickerColors is an array of 10 colors in the following order: white, red, orange, yellow, green, blue, blue-violet, violet, brown, black. The first item in the array is the red value of the first spectrum tile, the second item is its green value, the third item is its blue value, the fourth item is the second tile's red value, and so forth. Because there are 10 colors by default and each color has red, green, and blue values, DXmNpickerColors has a default value of 30. DXmNpickerColors can be set only at creation time. |
| DXmNinterpTileCount | The number of interpolator tiles used. The default is 10. DXmNinterpTileCount can be set only at creation time. |
| DXmNwarmthIncrement | The amount of red or blue added to the color of each interpolator tile when the warmer or cooler buttons are pressed. The default is 5000. |
| DXmNlightnessIncrement | The percentage by which to increase or decrease the lightness of the color of each interpolator tile when the lighter or darker buttons are pressed. The default is 5 percent. |
You can extend the color mixing widget to support other color models by replacing the default color mixer subwidget and the color display subwidget with widgets of your own design. Section 6.5.1 and Section 6.5.2 describe how to replace these subwidgets.
Whatever color system you choose to support, remember that X11 defines
colors by their RGB values. Your custom subwidget must convert whatever
values it accepts into RGB values and provide these values to the color
mixing widget, which returns the values to the application as callback
data. (On OpenVMS systems, you can find more information about
obtaining color resources as well as an example of converting color
values from another color model to RGB by looking at the color example
program in the VMS DECwindows Xlib Programming Volume.)
6.5.1 Replacing the Color Display Subwidget
To replace the default color display subwidget, specify the identifier of the new-color display subwidget as the value of the DXmNdisplayWindow resource. (If you do not specify a value for this resource, the color mixing widget uses the default color display subwidget.)
Note that you cannot specify a replacement for the default color display subwidget when you create the color mixing widget; you must first create (but not manage) the color mixing widget and then use XtSetArg and XtSetValues to specify a value for the DXmNdisplayWindow resource.
Thus, to replace the default color display subwidget, you must do the following:
You can switch back to the default color display subwidget at any time by setting the DXmNdisplayWindow resource to null.
If you replace the default color display subwidget, you must provide a procedure to update the new-color window when a user changes the color mixer widget. The color mixing widget calls this routine whenever a user changes a value in the color mixer subwidget. Pass the address of this routine as the value of the DXmNsetNewColorProc resource.
The default value for the DXmNsetNewColorProc resource is the routine
that updates the new-color window. If your application supplies a
DXmNsetNewColorProc routine, your routine is used even if your
application does not replace the default color display subwidget.
6.5.2 Replacing the Color Mixer Subwidget
To replace the default color mixer subwidget with one of your own design, assign the widget identifier of the new subwidget as the value of the DXmNmixerWindow resource. (If you do not specify a value for this resource, the color mixing widget uses the default color mixer subwidget.)
Note that you cannot specify a replacement for the default color mixer subwidget when you create the color mixing widget; you must first create (but not manage) the color mixing widget and then use XtSetArg and XtSetValues to specify a value for the DXmNmixerWindow resource.
Thus, to replace the default color mixing subwidget, you must do the following:
You can switch back to the default color mixer subwidget at any time by setting the DXmNmixerWindow resource to null.
The DXmNsetMixerColorProc resource specifies a procedure that is called
whenever the new color is updated by some means other than direct
manipulation of the mixing model (such as pressing the Reset button).
The procedure makes any necessary changes to the current mixing model,
such as setting the sliders in the RGB or HLS models to match the
new-color value. DXmNsetMixerColorProc is generally used when your
application supplies its own color mixing model rather than using the
default mixers.
6.6 Associating Callbacks with a Color Mixing Widget
When a user presses the OK, Apply, or Cancel push button, the color mixing widget performs a callback to your application. (Activating the Reset or Help buttons does not trigger a callback.)
When the color mixing widget performs a callback, it returns data to your application, including the RGB values that define the original color (specified in the DXmNorigRedValue, DXmNorigGreenValue, and DXmNorigBlueValue resources) and the RGB values that define the new color (specified in the DXmNnewRedValue, DXmNnewGreenValue, and DXmNnewBlueValue resources).
For complete information about the data returned in the callback by the color mixing widget, see DECwindows Extensions to Motif.
The color mixing callback also supports passing named colors to your application if the user has selected the Browser color model. If the user selects a named color from the Browser and then triggers a callback to the application without modifying the new color, the newname field of the callback data structure is filled in with a pointer to an ASCII, null-terminated string that contains the color's X11 name. This string is read only and should not be freed or modified.
If a color is generated in one of the other color models or generated in the Browser and subsequently modified, the newname field in the callback structure is set to NULL.
The format of the DXmColorMixCallbackStruct data structure is shown in Example 6-1.
| Example 6-1 The DXmColorMixCallbackStruct Data Structure |
|---|
typedef struct
{
int reason;
XEvent *event;
unsigned short newred;
unsigned short newgrn;
unsigned short newblu;
char *newname;
unsigned short origred;
unsigned short origgrn;
unsigned short origblu;
} DXmColorMixCallbackStruct;
|
To associate a callback routine with a color mixing widget callback, pass a callback routine list to one of the color mixing widget callback resources. Table 6-4 lists the callback resources and describes the conditions that trigger these callbacks.
| Callback Resource | Conditions for Callback |
|---|---|
| XmNokCallback | The user clicked the OK push-button widget in the color mixing widget. |
| XmNapplyCallback | The user clicked the Apply push-button widget in the color mixing widget. |
| XmNcancelCallback | The user clicked the Cancel push-button widget in the color mixing widget. |
To create a color mixing widget, do the following:
After you have completed these steps, if the parent of the color mixing widget has been realized, the color mixing widget appears on the display.
| Mechanism | Routine Name or Object Type |
|---|---|
| Toolkit routine | Use the DXmCreateColorMixDialog routine to create a color mixing widget in a pop-up dialog box. |
| Toolkit routine |
Use the DXmCreateColorMix routine to create a color mixing widget in a
dialog box. You might want to use this routine to add a color mixing
widget inside one of your existing widgets. There are two side effects
of using this version of the color mixing widget:
|
| UIL object type | Use the UIL object type DXmColorDialog to define a color mixing widget in a pop-up dialog box. At run time, the MrmFetchWidget routine creates the widget according to this definition. |
| UIL object type | Use the UIL object type DXmColor to define a dialog box color mixing widget. At run time, the MrmFetchWidget routine creates the widget according to this definition. The side effects described for the DXmCreateColorMix routine also apply to DXmColor. |
| Previous | Next | Contents | Index |