Creating an Interactive User Interface

The following figure shows a GUI similar to the one created by the code that follows the figure. The main program creates a parent form (form) with one button (display). The button callback shows the Label Builder dialog box that is created by the call to the tsol_lbuild_create() routine. See the tsol_lbuild_create(3TSOL) man page.

Figure 7-1 Label Building Interface

The Label Builder dialog box appears when you click the Show button in the parent form. The callouts indicate where the parameters passed to the tsol_lbuild_create() routine appear in the Label Builder dialog box. See the tsol_lbuild_create(3TSOL) man page.

The following code creates a GUI something like that shown by the figure.

#include <X11/Intrinsic.h>
#include <X11/StringDefs.h>
#include <Xm/Xm.h>
#include <Xm/PushB.h>
#include <Xm/Form.h>
#include <Dt/ModLabel.h>

ModLabelData *data;

/* Callback passed to tsol_lbuild_create() */
void callback_function()
{ 
    char *title, *userval;
    char *string = (char *)0;
    char *string1 = (char *)0;
    int mode, view;
    Boolean show;
    m_label_t *sl_label, *work_sl_label;
    Position x, y;

/* Your application-specific implementation goes here */
    printf("OK button called\n"); 

/* Query settings */
    mode = (int)tsol_lbuild_get(data, LBUILD_MODE);
    title = (String)tsol_lbuild_get(data, LBUILD_TITLE);
    sl_label = (m_label_t*) tsol_lbuild_get(data, LBUILD_VALUE_SL);
    work_sl_label = (m_label_t*) tsol_lbuild_get(data, LBUILD_WORK_SL);
    view = (int)tsol_lbuild_get(data, LBUILD_VIEW);
    x = (Position ) tsol_lbuild_get(data, LBUILD_X);
    y = (Position ) tsol_lbuild_get(data, LBUILD_Y);
    userval = (char *)tsol_lbuild_get(data, LBUILD_USERFIELD);
    show = (Boolean )tsol_lbuild_get(data, LBUILD_SHOW);

    label_to_str(sl_label, &string, M_LABEL, LONG_NAMES);
    label_to_str(work_sl_label, &string1, M_LABEL, LONG_NAMES);
    printf("Mode = %d, Title = %s, SL = %s, WorkSL = %s, View = %d, ",
        mode, title, string, string1, view);
    printf("X = %d, Y = %d, Userval = %s, Show = %d\n",
        x, y, userval, show);

}

/* Callback to display dialog box upon button press */
void Show(Widget display, caddr_t client_data, caddr_t call_data)
{
    tsol_lbuild_set(data, LBUILD_SHOW, TRUE, NULL);
}

main(int argc, char **argv)
{
    Widget     form, topLevel, display;
    Arg args[9];
    int i = 0, error, retval;
    char *sl_string = "CNF";
    m_label_t * sl_label;

    topLevel = XtInitialize(argv[0], "XMcmds1", NULL, 0, &argc, argv);
    form = XtCreateManagedWidget("form",
        xmFormWidgetClass, topLevel, NULL, 0);

    retval = str_to_label(sl_string, &sl_label, MAC_LABEL, L_NO_CORRECTION, NULL);
    printf("Retval = %d\n", retval);

    data = tsol_lbuild_create( form, callback_function,
        LBUILD_MODE, LBUILD_MODE_SL,
        LBUILD_TITLE, "Building Sensitivity Label",
        LBUILD_VALUE_SL, sl_label,
        LBUILD_VIEW, LBUILD_VIEW_EXTERNAL,
        LBUILD_X, 200,
        LBUILD_Y, 200,
        LBUILD_USERFIELD, "/export/home/zelda",
        LBUILD_SHOW, FALSE,
        NULL);

    i = 0;
    XtSetArg(args[i], XmNtopAttachment, XmATTACH_FORM); i++;
    XtSetArg(args[i], XmNleftAttachment, XmATTACH_FORM); i++;
    XtSetArg(args[i], XmNrightAttachment, XmATTACH_FORM); i++;
    XtSetArg(args[i], XmNbottomAttachment, XmATTACH_FORM); i++;
    display = XtCreateManagedWidget("Show",
        xmPushButtonWidgetClass, form, args, i);
    XtAddCallback(display, XmNactivateCallback, Show,0);
    XtRealizeWidget(topLevel);

    XtMainLoop();

    tsol_lbuild_destroy(data);

}

When run, the program produces the following output:

OK button called  
Mode = 12, Title = Building Sensitivity label, 
Label = CNF, WorkSL = SECRET, 
View = 1, X = 200, Y = 200, 
Userval = /export/home/zelda, 
Show = 1

The following sections cover these topics:

• Label Builder behavior

• Application-specific functionality for Label Builder

• Privileged operations and Label Builder

• tsol_lbuild_create() routine

• Extended Label Builder operations

• ModLabelData structure

Label Builder Behavior

The Label Builder dialog box prompts the end user for information and generates a valid sensitivity label from the input. Label Builder ensures that a valid label or clearance is built. The labels and clearances are defined in the label_encodings file for the system.

Label Builder provides default behavior for the OK, Reset, Cancel, and Update buttons. The callback passed to the tsol_lbuild_create() routine is mapped to the OK button to provide application-specific behavior.

Keyboard Entry and Update Button

The Update button takes the text the user types in the Update With field and checks that the string is a valid label or clearance as defined in the label_encodings file.

• If the input is not valid, Label Builder generates an error for the user.

• If the input is valid, Label Builder updates the text in the Label field and stores the value in the appropriate working label field of the ModLabelData variable that is returned by the tsol_lbuild_create() routine. See ModLabelData Structure.

When the user clicks OK, the user-built value is handled according to the OK button callback implementation.

Radio Button Options

The Label Settings radio button options enable you to build a sensitivity label or clearance from classifications and compartments. These options also enable you to build an information label from classifications, compartments, and markings. Depending on the mode, one of these buttons might be grayed out. This approach is independent of the keyboard entry and Update button method described in the previous section.

The information about the classifications, compartments, and markings is specified in the label_encodings file for the system. The combinations and constraints that are specified in the label_encodings file are enforced by graying out invalid combinations. The Label field is updated and the value is stored in the appropriate working label field of the ModLabelData variable that is returned by the tsol_lbuild_create() routine when the user chooses options. The user can build a sensitivity label or a clearance by selecting radio buttons in the classification (CLASS) and compartment (COMPS) lists.

When the user clicks OK, the user-built value is handled according to the OK button callback implementation.

Reset Button

The Reset button sets the text in the Label field to what its value was when the application started.

Cancel Button

The Cancel button exits the application without saving any changes.

Application-Specific Functionality for Label Builder

The Label Builder GUI generates a valid label or clearance. You must also add application-specific callbacks, error handling, and other functionality that is associated with that label or clearance.

Privileged Operations and Label Builder

Label Builder shows the user only those classifications and related compartments that are dominated by the workspace sensitivity label. If the executable has the sys_trans_label privilege in its effective set, more classifications and compartments might be shown.

Your application-specific implementation for the OK button callback might require privileges.

If the user does not have the authorization to upgrade or downgrade labels, the OK and Reset buttons are grayed out. The same is true if the user-built label is out of the user's range. The grayed-out buttons prevent the user from completing the task. No privileges can override these restrictions.

tsol_lbuild_create() Routine

The tsol_lbuild_create() routine accepts any widget, a callback function, and a null-terminated series of name and value pairs. The name represents an operation. The routine returns a variable of type ModLabelData.

The following describes the information accepted by the tsol_lbuild_create() routine:

• Widget – Label Builder can build the dialog box from any widget.

• Callback function – The callback function activates when the OK button is clicked. This callback function provides application-specific behavior.

• Name and value pairs – The name (left) side of the pair specifies an extended operation (see Extended Label Builder Operations) and the value (right) side specifies the value. In some cases, the value is an enumerated constant. In other cases, you provide a value. The pairs can be specified in any order, but every operation you specify requires a valid value.

  The return value is a data structure that contains information about the dialog box that was just created. The information comes from the tsol_lbuild_create() input parameters and user activities during execution. Label Builder provides default values for some fields where no values have been specified.

  Use the tsol_lbuild_get() routine and the tsol_lbuild_set() routine to programmatically access and change the information in these name and value pairs. The data structure is described in ModLabelData Structure.

  The following shows a sample call to the tsol_lbuild_create() routine:

  data= tsol_lbuild_create(form, callback_function,
      LBUILD_MODE, LBUILD_MODE_SL,
      LBUILD_TITLE, "Building a Label",
      LBUILD_VALUE_SL, sl_label,
      LBUILD_VIEW, LBUILD_VIEW_EXTERNAL,
      LBUILD_X, 200,
      LBUILD_Y, 200,
      LBUILD_USERFIELD “/export/home/zelda”,
      LBUILD_SHOW, FALSE,
      NULL);

Extended Label Builder Operations

This section describes the extended operations and valid values that you can pass to the tsol_lbuild_create(), tsol_lbuild_get(), and tsol_lbuild_set() routines. The values that are passed to tsol_lbuild_create() are stored in its return value. The return value is of type ModLabelData. The values returned in the parameters can be accessed by calls to tsol_lbuild_get() and tsol_lbuild_set(). The ModLabelData structure is described in ModLabelData Structure. See the tsol_lbuild_create(3TSOL), tsol_lbuild_get(3TSOL), and tsol_lbuild_set(3TSOL) man pages.

All extended operations are valid to pass to tsol_lbuild_get(). However, the LBUILD_WORK_SL and LBUILD_WORK_CLR operations are not valid to pass to tsol_lbuild_set() or tsol_lbuild_create() because these values are set by Label Builder based on user input. These exceptions are noted in the following operation descriptions:

• LBUILD_MODE – You can instruct tsol_lbuild_create() to create a user interface to build sensitivity labels or clearances. The default value is LBUILD_MODE_SL.

  • LBUILD_MODE_SL – Builds a sensitivity label.

  • LBUILD_MODE_CLR – Builds a clearance.

• LBUILD_VALUE_SL – The starting sensitivity label that is shown in the Label field when the mode is LBUILD_MODE_SL. The default value is ADMIN_LOW.

• LBUILD_VALUE_CLR – The starting clearance that is shown in the Label field when the mode is LBUILD_MODE_CLR. The default value is ADMIN_LOW.

• LBUILD_USERFIELD – A character string prompt that appears at the top of the Label Builder dialog box. The default value is NULL.

• LBUILD_SHOW – Shows or hides the Label Builder dialog box. The default value is FALSE.

  • TRUE – Shows the Label Builder dialog box.

  • FALSE – Hides the Label Builder dialog box.

• LBUILD_TITLE – A character string title that appears at the top of the Label Builder dialog box. The default value is NULL.

• LBUILD_WORK_SL – The sensitivity label that the user is building. This value is updated based on the user's input when the user selects the Update button or interactively chooses an option. The default value is ADMIN_LOW and is not a valid extended operation for tsol_lbuild_set() or tsol_lbuild_create().

• LBUILD_WORK_CLR – The clearance that the user is building. This value is updated based on the user's input when the user selects the Update button or interactively chooses an option. The default value is ADMIN_LOW and is not a valid extended operation for tsol_lbuild_set() or tsol_lbuild_create().

• LBUILD_X – The X offset in pixels from the upper left corner of the Label Builder dialog box in relation to the upper left corner of the screen. By default, the Label Builder dialog box is positioned in the middle of the screen.

• LBUILD_Y – The Y offset in pixels from the upper left corner of the Label Builder dialog box in relation to the upper left corner of the screen. By default, the Label Builder dialog box is positioned in the middle of the screen.

• LBUILD_UPPER_BOUND – The highest classification, and related compartments and markings, that are available to the user as radio buttons. These buttons are used to interactively build a label or a clearance. A value you supply must be within the user's range. If no value is supplied, this value is the user's workspace sensitivity label. Or, if the executable has the sys_trans_label privilege, this value is the user's clearance.

• LBUILD_LOWER_BOUND – The lowest classification, and related compartments and markings, that are available to the user as radio buttons. These buttons are used to interactively build a label or a clearance. This value is the user's minimum label. If no value is specified, the value is based on the default specified by the user's attributes.

• LBUILD_CHECK_AR – Checks whether the user-built label is within the user's range. A value of 1 means “check,” and a value of 0 means “do not check.” If the label is out of range, an error message is displayed to the user. The default value is 1.

• LBUILD_VIEW – Determines whether to use the internal or the external label representation. The default value is LBUILD_VIEW_EXTERNAL.

  • LBUILD_VIEW_INTERNAL – Uses the internal names for the highest and lowest labels in the system, ADMIN_HIGH and ADMIN_LOW.

  • LBUILD_VIEW_EXTERNAL – Promotes an ADMIN_LOW label to the next lowest label and demotes an ADMIN_HIGH label to the next highest label.

ModLabelData Structure

The ModLabelData structure contains information about the state of the Label Builder interface that is created by the call to the tsol_lbuild_create() routine. The following table describes the ModLabelData fields. All fields, except for the widgets and the callbacks, are accessible by specifying the associated extended operation and a valid value in a call to tsol_lbuild_set() or tsol_lbuild_get(). For descriptions of the extended operations, see Extended Label Builder Operations.

Table 7-1 ModLabelData Structure

Extended Operation or Description	Data Type	Field	Comments
LBUILD_CHECK_AR	int	check_ar
LBUILD_MODE	int	mode
LBUILD_SHOW	Bool	show
LBUILD_TITLE	char	*lbuild_title
LBUILD_UPPER_BOUND, LBUILD_LOWER_BOUND	brange_t	range
LBUILD_USERFIELD	char	*userfield
LBUILD_VALUE_CLR	bclear_t	*clr
LBUILD_VALUE_SL	m_label_t	*sl
LBUILD_VIEW	int	view
LBUILD_WORK_CLR	bclear_t	*clr_work	Not valid for tsol_lbuild_set() or tsol_lbuild_create()
LBUILD_WORK_SL	m_label_t	*sl_work	Not valid for tsol_lbuild_set() or tsol_lbuild_create()
LBUILD_X	Position	x
LBUILD_Y	Position	y
Callback passed to tsol_lbuild_create()	void	(*event_handler)()
Cancel button	Widget	cancel
Help button	Widget	help
Label Builder dialog box	Widget	lbuild_dialog
OK button	Widget	ok
Reset button	Widget	reset
Update button	Widget	update