By default, the ColorChooser widget uses GL's Gouraud shading to display the colors in the hexagon and sliders. You can force the ColorChooser widget not to use GL by setting the value of the SgNuseGl resource to FALSE. When SgNuseGl is FALSE, the ColorChooser widget uses only X function calls. In this case, it does not draw a color hexagon and it uses XmScale widgets instead of the special color sliders.

When using GL, the ColorChooser normally shades the color hexagon and color sliders so that each point is a true representation of the color that would be selected if the user were to move the hexagon pointer or color slider to that point. However, if the value of the SgNwysiwyg resource is FALSE then the ColorChooser always displays the hexagon colors with a Value (intensity) of 1 (maximum intensity), and the RGB sliders with a color range of black to the maximum RGB color component value.

For example, if the current selected color RGB value is (100, 200, 50), then the Red color slider displays the colors (0, 200, 50) through (255, 200, 50) if SgNwysiwyg is TRUE, and (0, 0, 0) through (233, 0, 0) if SgNwysiwyg is FALSE. (Note that the user can also toggle the value of SgNwysiwyg by selecting the “WYSIWYG” option from the ColorChooser's Options menu.)

The SgNshowSliders resource determines which of the color sliders are visible. Possible values are:

The default labels (in the C locale) for the ColorChooser buttons are “OK,” “Apply,” “Cancel,” and “Help.” You can change these by setting the values of SgNokLabelString, SgNapplyLabelString, SgNcancelLabelString, and SgNhelpLabelString respectively.

You can add additional children to the ColorChooser after creation—they're laid out in the following manner:

In ColorChooser callback functions, the RGB color values are provided as the r, g, and b parameters of the SgColorChooserCallbackStruct structure passed to the functions. “Handling User Interaction With the Color Chooser” describes the ColorChooser callbacks.

ColorChooser also provides several convenience routines for getting and setting both the current color values and setting the stored color value.

SgColorChooserSetColor() sets both the current and the stored color values to the same color:

void SgColorChooserSetColor(Widget w, short r, short g,
                            short b);

SgColorChooserGetColor() retrieves the current color values:

void SgColorChooserGetColor(Widget w, short *r, short *g,
                            short *b);

SgColorChooserSetCurrentColor() sets the current color but not the stored color:

void SgColorChooserSetCurrentColor(Widget w, short r,
                                   short g, short b);

SgColorChooserSetStoredColor() sets the stored color but not the current color:

void SgColorChooserSetStoredColor(Widget w, short r,
                                  short g, short b);

For each function, w is the ColorChooser widget and r, g, and b are the red, green, and blue values, respectively.

The ColorChooser widget defines the following callback resources:

A pointer to a SgColorChooserCallbackStruct structure is passed to each ColorChooser callback function:

typedef struct {
    int reason;
    XEvent *event;
    short r, g, b;
} SgColorChooserCallbackStruct;

You control the display characteristics of a Dial through widget resources.

The SgNdialVisual resource determines whether the Dial uses a knob or a pointer. The default value, SgKNOB, specifies a knob and SgPOINTER specifies a pointer. If you use a pointer, you can also specify the color of the small “indicator” at the center of the pointer using the SgNindicatorColor resource; the default color is red.

You specify the position of the lowest value on the Dial with the SgNstartAngle resource. The value, which must be between 0 and 360 inclusive, specifies the number of degrees clockwise from the top of the Dial. The default value of 0 corresponds to the top of the Dial.

The SgNangleRange resource determines the range of the Dial in degrees. The value, which must be between 0 and 360 inclusive, specifies the number of degrees clockwise from the start angle of the Dial. The default value of 360 allows the Dial to rotate completely.

The Dial widget displays evenly spaced “tick marks” along the perimeter of the Dial's angle range. You control the number of tick marks with the SgNdialMarkers resource; the default number is 16. The length of the tick marks in pixels is determined by the SgNmarkerLength resource; the default length is 8 pixels. The SgNdialForeground resource determines the color of the tick marks; the default is red.

The resources XmNminimum and XmNmaximum determine the minimum and maximum values of the Dial. The Dial takes on the minimum value at the position specified by SgNstartAngle and takes on the maximum value at the position SgNangleRange degrees clockwise from SgNstartAngle. The value of XmNmaximum must be greater than or equal to the value of XmNminimum. The default value of XmNminimum is 0 and the default value of XmNmaximum is 360.

The XmNvalue resource, which must be a value between XmNminimum and XmNmaximum inclusive, contains the current position of the Dial. You can set or get the value of a Dial widget at any time by respectively setting or getting its XmNvalue resource.

In Dial callback functions, the Dial value is provided as the position parameter of the SgDialCallbackStruct structure passed to the functions. “Detecting Changes in the Dial's Value” describes the Dial callbacks.

Dial also provides a convenience routine, SgDialSetValue(), for setting the value of XmNvalue:

void SgDialSetValue(Widget w, int value);

w is the Dial widget whose value you want to set and value is the new value.

You can get the current value of a Dial widget at any time by retrieving the value of its XmNvalue resource. Dial also provides a convenience routine, SgDialGetValue(), for getting the value of XmNvalue:

void SgDialGetValue(Widget w, int *value);

w is the Dial widget whose value you want to get. Upon returning, value contains the Dial's value.

The Dial widget defines two callback list resources, XmNvalueChangedCallback and XmNdragCallback. A Dial widget invokes XmNvalueChangedCallback whenever its value changes either programmatically (for example, by calling SgDialSetValue()) or through user interaction. A Dial widget invokes XmNdragCallback whenever the user clicks and drags, or “spins,” the Dial's knob or pointer.

A pointer to a SgDialCallbackStruct structure is passed to each Dial callback function:

typedef struct {
    int reason;
    XEvent *event;
    int position;
} SgDialCallbackStruct;

The SgDialCallbackStruct parameters are:

You control the display characteristics of a ThumbWheel through widget resources.

The resources XmNminimum and XmNmaximum determine the minimum and maximum values of the ThumbWheel. Setting XmNmaximum equal to XmNminimum indicates an infinite range. The default value of XmNminimum is 0 and the default value of XmNmaximum is 100.

The SgNangleRange resource specifies the angular range, in degrees, through which the ThumbWheel is allowed to rotate. The default of 150 represents roughly the visible amount of the wheel. Thus clicking at one end of the wheel and dragging the mouse to the other end would give roughly the entire range from XmNminimum to XmNmaximum.

In conjunction with XmNmaximum and XmNminimum, the SgNangleRange resource controls the fineness or coarseness of the wheel control when it is not infinite. If this value is 0, the ThumbWheel has an infinite range. If the range of the ThumbWheel is infinite, you can use the SgNunitsPerRotation resource to specify the change in the ThumbWheel's value for each full rotation of the wheel.

If the value of SgNshowHomeButton is TRUE, the default, the ThumbWheel displays a home button by the slider. The user can click on the home button to set the value of the ThumbWheel to a known value, which is specified by the SgNhomePosition resource. The default value of SgNhomePosition is 50.

The XmNorientation resource determines whether the orientation of the ThumbWheel is vertical, indicated by a value of XmVERTICAL, or horizontal, indicated by a value of XmHORIZONTAL. The default value is XmVERTICAL.

The XmNvalue resource contains the current position of the ThumbWheel. XmNvalue must be a value between XmNminimum and XmNmaximum if the ThumbWheel is not “infinite.” You can set or get the value of a ThumbWheel widget at any time by respectively setting or getting its XmNvalue resource.

In ThumbWheel callback functions, the ThumbWheel value is provided as the value parameter of the SgThumbWheelCallbackStruct structure passed to the functions. “Detecting Changes in the ThumbWheel's Value” describes the ThumbWheel callbacks.

The ThumbWheel widget defines two callback list resources, XmNvalueChangedCallback and XmNdragCallback. A ThumbWheel widget invokes XmNvalueChangedCallback whenever its value changes either programmatically (that is, by setting the value of XmNvalue) or through user interaction. A ThumbWheel widget invokes XmNdragCallback whenever the user clicks and drags, or “spins,” the ThumbWheel's wheel.

A pointer to a SgThumbWheelCallbackStruct structure is passed to each ThumbWheel callback function:

typedef struct { int reason;
                 XEvent * event;
                 int value;
               } SgThumbWheelCallbackStruct;

The SgThumbWheelCallbackStruct parameters are:

If you don't need the drop pocket feature of the Finder widget, you can set the value of the resource SgNuseDropPocket to FALSE when you create the widget. This bypasses the costs of setting up drag and drop and loading the file icon libraries. Note that you can't set this resource using XtSetValues(); if you don't originally create a Finder widget with a drop pocket, you can't add one afterwards.

Similarly, if you don't need the Recycle button, you can set the value of the resource SgNuseHistoryMenu to FALSE. Note that you can't set this resource using XtSetValues(); if you don't originally create a Finder widget with a Recycle button, you can't add one afterwards.

You can customize the appearance of the Recycle button by setting the value of the SgNhistoryPixmap resource to the pixmap you want to display.

By default, the Finder widget determines where to place the buttons on the path navigation bar by the location of the forward slash (/) character in the text field. You can specify a different separator character by providing it as the value of the SgNseparator resource. This feature is useful if you want to use the Finder widget to display something other than filenames.

You can retrieve the current value of the Finder's text field with SgFinderGetTextString():

char *SgFinderGetTextString(Widget w);

You can set the value of the text field with SgFinderSetTextString():

void SgFinderSetTextString(Widget w, char *value);

You can add an item to the “history list” of the Recycle button with SgFinderAddHistoryItem():

void SgFinderAddHistoryItem(Widget w, char *str);

You can clear the Recycle button's history list with SgFinderClearHistory():

void SgFinderClearHistory(Widget w);

You can access a widget component within a finder using SgFinderGetChild():

Widget SgFinderGetChild(Widget w, int child);

child specifies the component and can take any of the following values:

When the user clicks a button in the path navigation bar, the default action of the Finder is to set the current directory to the directory listed underneath that button. You can change this behavior by setting the SgNsetTextSectionFunc resource to the handler you want to use. The handler function must be of type SgSetTextFunc, which is defined in <Sg/Finder.h>:

typedef void (*SgSetTextFunc)(Widget finder, int section);

The first argument is the Finder widget and the second is an integer corresponding to the button pressed. Buttons are numbered sequentially from the left, starting with 0. You can perform whatever operations you want in this function, but typically you include a call to SgFinderSetTextString() to set the value of the text field after the user clicks a button.

Additionally, the Finder widget defines two callback list resources:

You specify the number of rows and columns in a Grid by setting the values of its XmNnumRows and XmNnumColumns resources, respectively. The default value for each is 1. Note that you can set the size of a Grid only when you create it; you can't use XtSetValues() to change the number of rows or columns in a Grid.

The XmNautoLayout resource determines the layout policy for a Grid. If its value is TRUE (the default), all rows and columns that have a non-zero resizability factor (described below) are sized according to the desired natural size of the widgets in that row or column.

If XmNautoLayout is FALSE, all widgets in resizable rows or columns are sized according to the resizability factor for that row or column. By default, the resizability factor is “1” for all rows and columns, which results in each cell in the grid having an equal size. You can change the resizability factor for a row or column by calling SgGridSetRowMargin() or SgGridSetColumnMargin() respectively:

SgGridSetRowResizability(Widget widget, int row, int factor);

SgGridSetColumnResizability(Widget widget, int column,
                            int factor);

widget is the Grid widget. The second argument specifies the row or column. Rows are numbered sequentially from the top starting at 0; columns are numbered sequentially from the left starting with 0. factor is the resizability factor for the row or column. Setting this value to 0 establishes the specified row or column as not resizable, regardless of the setting of XmNautoLayout. Other values are taken relative to all other rows. For example, if a Grid has three rows whose resizability factors are set to 100, 100, and 200, the first and second rows will occupy one quarter of the space (100/(100+100+200)), while the third row will occupy one half of the available space.

The XmNdefaultSpacing resource default spacing between rows and columns. The default value is 4 pixels. You can override the value on a per row/column basis using SgGridSetColumnMargin() or SgGridSetRowMargin() respectively:

SgGridSetRowMargin(Widget widget, int row, Dimension margin);

SgGridSetColumnMargin(Widget widget, int column,
                      Dimension margin);

widget is the Grid widget. The second argument specifies the row or column. margin specifies the margin in pixels between the row or column's edges and the widgets it contains. The margin is added to both sides of each row or column, so adding a 1 pixel margin increases the relevant dimension of the affected row or column by 2 pixels.

You can display the boundaries of a Grid by setting the value of its XmNshowGrid resource to TRUE. You might find this useful for debugging resize specifications. The default value is FALSE.

The XmNrow and XmNcolumn resources of a Grid's child widget specify the row and column in which the Grid places the child. If you don't specify these values, the Grid widget places the child in a randomly selected unoccupied cell.

The XmNresizeVertical and XmNresizeHorizontal resources determine whether the Grid can resize the child to fill the cell in the vertical and horizontal directions. The default value of TRUE allows the Grid to resize the child.

If a child is a fixed size, and smaller than the cell that contains it, the child's position within the cell is determined by an XmNgravity resource. Gravity may be any of the gravity values defined by Xlib except StaticGravity and ForgetGravity. The default is NorthWestGravity. Note that gravity has no effect if both XmNresizeVertical and XmNresizeHorizontal are TRUE.

Example 4-1 creates a grid of four buttons that all size (and resize) equally to fill one quarter of their parent.

createGrid(Widget parent)
{
    int n;
    Arg args[10];
    Widget grid, child1, child2, child3, child4;

    n = 0;
    XtSetArg(args[n], XmNnumRows, 2); n++;
    XtSetArg(args[n], XmNnumColumns, 2); n++;
    grid = SgCreateGrid(parent, "grid", args, n);

    child1 = XtVaCreateManagedWidget("child1",
                                     xmPushButtonWidgetClass,
                                     grid,
                                     XmNrow, 0,
                                     XmNcolumn, 0,
                                     NULL);
    child2 = XtVaCreateManagedWidget("child2",
                                     xmPushButtonWidgetClass,
                                     grid,
                                     XmNrow, 0,
                                     XmNcolumn, 1,
                                     NULL);
    child3 = XtVaCreateManagedWidget("child3",
                                     xmPushButtonWidgetClass
                                     grid,
                                     XmNrow, 1,
                                     XmNcolumn, 0,
                                     NULL);
    child4 = XtVaCreateManagedWidget("child4",
                                     xmPushButtonWidgetClass
                                     grid,
                                     XmNrow, 1,
                                     XmNcolumn, 1,
                                     NULL);
    XtManageChild(grid);
}

Example 4-2 creates four buttons. The top row has a fixed vertical size, while the bottom row is resizable. The left column has a fixed size, but the right column can be resized. The button in the lower right can be resized, but the others cannot. The button in the lower left cell, which can be resized vertically, floats in the middle of its cell. The button in the upper right stays to the left of its cell.

createGrid(Widget parent) {
    int n;
    Arg args[10];
    Widget grid, chidl1, child2, child3, child4;

    n = 0;
    XtSetArg(args[n], XmNnumRows, 2); n++;
    XtSetArg(args[n], XmNnumColumns, 2); n++;
    grid = SgCreateGrid( parent, "grid", args, n );

    SgGridSetColumnResizability(grid, 0, 0);
    SgGridSetRowResizability(grid, 0, 0);

    child1 = XtVaCreateManagedWidget("child1",
                                 xmPushButtonWidgetClass,
                                 grid,
                                 XmNrow, 0,
                                 XmNcolumn, 0,
                                 NULL);
    child2 = XtVaCreateManagedWidget("child2",
                                 xmPushButtonWidgetClass,
                                 grid,
                                 XmNrow, 0,
                                 XmNcolumn, 1,
                                 XmNresizeHorizontal, FALSE,
                                 XmNgravity, WestGravity,
                                 NULL);
    child3 = XtVaCreateManagedWidget("child3",
                                 xmPushButtonWidgetClass,
                                 grid,
                                 XmNrow, 1,
                                 XmNcolumn, 0,
                                 XmNresizeVertical, FALSE,
                                 XmNgravity, CenterGravity,
                                 NULL);
    child4 = XtVaCreateManagedWidget("child4",
                                 xmPushButtonWidgetClass,
                                 grid,
                                 XmNrow, 1,
                                 XmNcolumn, 1,
                                 NULL);
    XtManageChild(grid);
}