2. Simple Widgets

Label

• the label widget places a label string on the screen

Command

• the command widget places a label string on the screen and can also be selected by the user, when selected the callback procedures are called

Toggle

• a toggle is a command widget that has state, it can be either in the on or off state
• toggle widgets can also be used to build radio groups
• when a toggle widget is selected its callbacks are called
• that application can also determine the current state of the toggle widget by examining the state resource
• the resources in a widget can be retrieved by using the XtGetValues procedure, this procedure is similar to the XtSetValues procedures that is used to set the resource values
• the declaration of this procedure is:

      XtGetValues(w, args, num_args)
      Widget    w;
      ArgList   args;
      int       num_args;
  

• the args parameter to this function has essentially the same format as the args parameter to the XtSetValues procedure, the XtSetArg macro can be used to set up the args parameter
• the only difference is that the value parameter to the macro must be a pointer, the location where the resource value will be stored
• to retrieve the value of the state resource of a toggle widget we could use the following code:

      int state;
      Arg wargs[10];
      Widget tog;
  
      tog = XtCreateManagedWidget("toggle", toggleWidgetClass, ...);
  
  
      XtSetArg(wargs[0], XtNstate, &state);
      XtGetValues(tog, wargs, 1);
  

• on return from the XtGetValues call the integer variable state will contain the state of the toggle widget
• toggle widgets can be grouped together to form radio buttons, this is called a radio group in Athena, in a radio group only one button can be in the "on" state
• there are two toggle resources that are used to form radio groups: radioGroup and radioData
• the radioGroup resource is used to identify all the toggles that are in the group, the value of this resource is the widget identifier of another toggle in the radio group
• the easiest way to handle this is to use one of the toggles as the name of the radio group, and use this widget as the value of the radioGroup resource for all the toggles in the group
• the easiest way to set up a radio group is to use the XawToggleChangeRadioGroup procedure, the declaration of this procedure is: XawToggleChangeRadioGroup(w, radio group) - Widget w; Widget radio group; -
• the first parameter is the widget to be added to the radio group and the second parameter is the widget that identifies the radio group
• we will see how this procedure is used in the example
• the radioData resource is used to identify the individual toggles in the radio group, this resource is rarely used, but it is a bit tricky
• the radioData resource is a pointer, the toggle widget uses pointer comparisons to find a toggle widget given a radioData value
• Warning: the default value of this resource is useless, do not use it
• the best way to handle this resource is to allocate a block of memory and use it as the radioData value
• to see how the toggle widget can be used to create radio buttons we will look at a procedure that creates radio boxes for us
• this procedure creates a radio box that can be used to change the value of a single variable, this variable is an integer and it is assumed that it can take a small fixed set of values
• the values of this variable could be the size of a text font
• the input to this procedure is a list of names to be used on the radio buttons, the values corresponding to these names, a pointer to the variable and the initial value of the variable
• the radio box procedure first creates a box widget to contain the radio buttons, then it creates one toggle widget for each name, the toggle widgets are grouped into a radio group, the toggle corresponding to the initial value is found, and made the currently selected button
• the radio box procedure returns the widget id of the box widget
• the radio box procedure has a private callback procedure that sets the variable to its new value, this callback procedure has as client data a pointer to a structure that contains the new value for the variable and a pointer to the variable
• the test program creates a radio box with 5 buttons, it has a print command that prints the current value of the variable to test whether it is set correctly

  /**************************************************************
   *
   *                      rbox.c
   *
   *  Simple radio button utility.  The radio_box procedure creates
   *  a widget hierarchy that contains a box widget plus an
   *  arbitrary number of toggle widgets that are organized as
   *  a radio group.  The radio box hierarchy is used to maintain
   *  the value of a variable, this variable can have one of
   *  a small set of values, with each value represented by one
   *  of the radio buttons.  When a radio button is pressed the
   *  value of the variable changes.  The parameters passed to
   *  the radio_box procedure is a list of names for the buttons,
   *  the variable value corresponding to each button, and a
   *  pointer to the variable to be changed.  The value returned
   *  is the widget id of the box widget
   *
   *****************************************************************/

  #include  < X11/StringDefs.h > 
  #include  < X11/Intrinsic.h > 
  #include  < X11/Xaw/Box.h > 
  #include  < X11/Xaw/Toggle.h > 

  struct radio_struct {
       int  *variable;
       int  value;
  };


  static void rgback(w,rs,call)
  Widget w;
  struct radio_struct *rs;
	      
  XtPointer call; {

       *(rs->variable) = rs->value;

  }


  Widget radio_box(parent,names,values,variable,initial)
  Widget    parent;   /* parent of the radio box */
  char *names[];
  int  *values;
  int  *variable;
  int  initial; {
       struct    radio_struct *rs;
       Widget    togs[100];
       int  ntogs;
       char *init_name;
       Widget    box;
       Widget  group;
       int  len;
       Arg  wargs[10];



       int  index;
       int  i;

       box = XtCreateManagedWidget("box",boxWidgetClass,parent,
		 NULL, 0);

       ntogs = 0;
       while(names[ntogs] != 0) {
	    togs[ntogs] = XtCreateWidget(names[ntogs],
		      toggleWidgetClass,box,NULL,0);

	    if(ntogs == 0)
		 group = togs[0];

	    XawToggleChangeRadioGroup(togs[ntogs],group);

	    rs = (struct radio_struct *) malloc(sizeof *rs);
	    rs->variable = variable;
	    rs->value = values[ntogs];

	    XtAddCallback(togs[ntogs],XtNcallback,rgback,rs);

	    ntogs++;
       }

       XtManageChildren(togs,ntogs);

       index = -1;
       for(i=0; i < ntogs; i++)
	    if(values[i] == initial)
		 index = i;

       if(index  <  0)
	    index = 0;

       *variable = values[index];

       len = strlen(names[index]) + 1;
       init_name = (char *)malloc(len);
       strcpy(init_name,names[index]);

       XtSetArg(wargs[0],XtNradioData,init_name);
       XtSetValues(togs[index],wargs,1);

       XawToggleSetCurrent(group,init_name);
				     

       return(box);
  }









  /**********************************************************
   *
   *                     rtest.c
   *
   *  Test program for the radio box
   *
   *********************************************************/

  #include  < X11//StringDefs.h > 
  #include  < X11/Intrinsic.h > 
  #include  < X11/Xaw/Box.h > 
  #include  < X11/Xaw/Command.h > 
  #include "lib.h"

  char *names[] = {
       "value1",
       "value2",
       "value3",
       "value4",
       "value5",
       0
  };

  int values[] = {
       1,
       2,
       3,
       4,
       5
  };

  int var;

  void var_print(w,client,call)
  Widget         w;
  XtPointer client;
  XtPointer call; {

       printf("var: %d\n",var);

  }

  main(argc, argv)
  int argc;
  char **argv; {
       Widget toplevel;
       Widget box;
       Widget buttons;
       Widget quit;
       Widget print;

       toplevel = XtInitialize(argv[0],"rtest",NULL, 0,
		      &argc,argv);

       box = XtCreateManagedWidget("main",boxWidgetClass,
		 toplevel, NULL, 0);

       print = XtCreateManagedWidget("print", commandWidgetClass,
		 box, NULL, 0);

       XtAddCallback(print, XtNcallback, var_print, NULL);
					    

       quit = quit_button(box);
		  

       buttons = radio_box(box,names,values,&var,1);
		      

       XtRealizeWidget(toplevel);

       XtMainLoop();

  }

List

• the list widget is used to display a list of items on the screen, these items are character strings
• the user can select one of the items from the list, when this occurs the previously selected item is unhighlighted, the new item is highlighted, and the callback for the list widget is called
• the list resource contains the strings that are displayed in the widget, this value can be set through XtSetValues, or the XawListChange procedure can be used, the declaration of this procedure is:

      void XawListChange(w, list, nitems, longest, resize)
      Widget    w;
      String    *list;
      int       nitems;
      int       longest;
      Boolean   resize;
  

• list should be a NULL terminated array of character strings, in this case the list widget will compute the value of nitems, the value of longest will also be computed by the list widget if its value is less than 1
• if resize is True the widget will attempt to change its size to fit the current list of strings
• the callback data for this widget is a pointer to a struct that contains the character string selected along with the index of the string in the list

Scrollbar

• the scrollbar widget can be used on its own to enter an an integer or real value, or it can be used as part of a composite widget to scroll through text or any other type of data
• the scrollbar has fairly complicated behavior, when button 2 is pressed the thumb can be dragged to any position on the scrollbar, this causes continuous scrolling and the jumpProc callback list is used for this action
• buttons 1 and 3 are not directly tied to the scrollbar thumb, each time they are clicked the callbacks on the scrollProc list are called with the absolute position of the mouse
• the main difficulty with the scrollbar is knowing which callbacks will be called, unfortuntaly the data passed to the two sets of callback is different, so they can't share code
• in the case of the jumpProc callback, the callback has the following declaration:

      void JumpProc(w, client, percent)
      Widget         w;
      XtPointer      client;
      XtPointer      percent;
  

• the percent paramter is a pointer to a float value that lies in the range 0.0 - > 1.0 and gives the relative position of the thumb
• for the scrollProc callback the callback has the following declaration: void ScrollProc(w, client, position) Widget w; XtPointer client; XtPointer position;
• the position parameter is a signed integer, and should be cast to one
• if button 1 was clicked position will be positive and if button 3 was clicked position will be negative
• the absolute value of position is the distance, in pixels, of the mouse pointer from the top or left of the scrollbar

  Go to Xt and the Athena Widgets        Go to Index        Go to Composite Widgets