HP OpenVMS Systems Documentation

Generally, your application does not have to be concerned with positioning entries because the SVN widget does this automatically. However, if you specify a tree style of DXmSvnKuserDefinedTree, the SVN widget uses the x- and y-coordinates you specify to position entries.

Your application can call the DXmSvnSetEntryPosition and DXmSvnGetEntryPosition Toolkit routines to set and get the x- and y-coordinates for an entry.

The following example gets the x- and y-coordinates of the parent entries and adds a hard-coded value of 30 for both the x- and y-coordinates of all children. FALSE is a Boolean value that indicates that the position information should be interpreted internally by the SVN widget.

/*
**  For each child, call SetEntry if the child has children.  Also set the
**  positions in case we are in UserDefined Tree Style.
*/
    DXmSvnGetEntryPosition(Svn, node_number, FALSE, &x, &y);
    for (i = 1;  i <= node->number;  i++)
        {
          if (child_node->children != 0)
             DXmSvnSetEntry (Svn, node_number+i, 0, 0, 2, 1, 0, FALSE);
          child_node = child_node->sibling;
          x += 30;
          y += 30;
          DXmSvnSetEntryPosition(Svn, node_number+i, FALSE, x, y);

The DXmSvnPositionDisplay routine lets you position a specified entry at the top, middle, or bottom of the display without concern for the number of entries being displayed. You provide the DXmSvnPositionDisplay routine with the ID of the SVN widget, the entry number of the entry you want to position, and one of the following constants to specify position:

• DXmSvnKpositionTop
• DXmSvnKpositionMiddle
• DXmSvnKpositionBottom
• DXmSvnKpositionPreviousPage
• DXmSvnKpositionNextPage

In the following code example, note that the tag argument specifies one of the position constants:

void MenuPosition (unused_w, tag)

  Widget unused_w;
  int tag;

{
/*
**  Local variables
*/
    int selections [1];


/*
**  Can position only one entry at a time, so just get it
*/
    DXmSvnDisableDisplay(Svn);

    if ((tag != DXmSvnKpositionNextPage) &&
        (tag != DXmSvnKpositionPreviousPage))
        DXmSvnGetSelections (Svn, selections, NULL, NULL, 1);
    DXmSvnPositionDisplay(Svn, selections[0], tag);
    DXmSvnEnableDisplay(Svn);

Because the call to this routine is not the result of a callback, disable the SVN widget. If the position is not equal to DXmSvnKpositionNextPage and DXmSvnKpositionPreviousPage, find out which entries are currently selected. Then, position the first of those entries according to the specified position constant. Enable the SVN widget.

9.2.9 Selecting Entries

The SVN widget selection routines allow your application to:

• Get the number of selections
• Get the entry number of selected entries
• Clear the current selection or selections
• Select all of the entries
• Select a particular component of an entry
• Select a particular entry
• Hide the selections (no reverse video)
• Show the selections if they are hidden

For example, the following code fragment gets the current selections:

void SvnExtended (w)

  Widget w;

{
/*
**  Local data declarations
*/
    int number_selected;
    int selections [50];
    int Entry_tags [50];
    int i;



/*
**  Ask how many were selected.
*/
    number_selected = DXmSvnGetNumSelections (w);


/*
**  Get those that are selected
*/
    DXmSvnGetSelections (w, selections, NULL, Entry_tags, number_selected);

This example gets the entry numbers of the current selections in the selections argument. The number of current selections (number_selected) is returned by the DXmSvnGetNumSelections routine.

If you want your SVN widget to support multiple selections, you must set the DXmSvnNmultipleSelections resource to TRUE.

9.2.10 Manipulating Entries

The SVN widget manipulation routines allow your application to:

• Add and delete entries
• Invalidate an entry, as described in Section 9.2.4
• Get and set the sensitivity of an entry
• Get and set new entry-level information
• Get and set the tag associated with an entry
• Get the entry number associated with an entry tag
• Set the number of components associated with an entry
• Set the entry in or out of the scroll index window (if activated) when the user drags the slider
• Flush an entry to the screen in outline mode

The following example shows how to add an entry:

entry_tags[0] = (unsigned int) &B;
DXmSvnAddEntries (svnw, 0, 1, 0, entry_tags, TRUE);

When a user double clicks on an entry in the SVN demo application, the DXmSvnNselectAndConfirm callback routine opens the entry if it is not already opened and calls the DXmSvnAddEntry routine to add any children that the element might have.

This call adds one entry (starting after zero) with a level of zero. The address of the first entry in the data hierarchy, _Node, is passed as a tag, and the entry appears in the scroll index window (if activated) when the user drags the slider.

The following example shows how to delete an entry:

DXmSvnDeleteEntries (Svn, node_number, node->number);

The after argument, in this case node_number, is the entry number after which to delete entries. The count argument, in this case node->number, is the number of entries to delete. Assume that node_number had a value of 1 and node->number had a value of 3. The example would delete entries 2, 3, and 4.

If you want to delete the children of an entry, pass the parent's entry number in the after argument and the number of its children in the count argument.

In the following example, entries are set sensitive or insensitive depending on the value of the application-specified tag argument. Because the call to this code is not the result of a callback, the example disables and enables the SVN widget.

   .
   .
   .
/*
**  Disable Svn while making changes
*/
    DXmSvnDisableDisplay(Svn);


    if (tag == 0)
        while (DXmSvnGetNumSelections(Svn) > 0)
            {
            DXmSvnGetSelections (Svn, selections, NULL, NULL, 1);
            DXmSvnSetEntrySensitivity(Svn, selections[0], FALSE);
            DXmSvnClearSelection(Svn, selections[0]);
            }


    if (tag == 1)
       for (i = 1; i <= SourceNumEntries; i++)
            DXmSvnSetEntrySensitivity(Svn, i, TRUE);
   .
   .
   .
/*
**  Changes done so reenable
*/
    DXmSvnEnableDisplay(Svn);
}

Column mode allows your application to split the SVN widget display into two columns, which are comprised of primary and secondary work windows. The DXmSvnNstartColumnComponent resource specifies the number of the last component in the primary work window; that is, the number of the component after which components are to be located in the secondary work window.

For example, the following code fragment specifies that components numbered 4 and greater are to be located in the secondary work window.

   .
   .
   .
XtSetArg (arguments[0], DXmSvnNstartColumnComponent, 3);
XtSetArg (arguments[1], DXmSvnNcolumnLines, TRUE);
XtSetValues (Svn, arguments, 2);

You can select only the complete entry from the primary work window; the secondary work window lets you select individual components within an entry. You can call the DXmSvnInsertComponent and DXmSvnRemoveComponent routines to add or remove components from an entry.

9.2.12 Flushing an Entry

Your application can call the DXmSvnFlushEntry routine to display an entry on the screen while in outline mode. If the entry number you pass to DXmSvnFlushEntry is one greater than the entry number of the last displayed entry and there is enough space for the entry to fit, the entry is appended to the set of visible entries. If there is not enough blank space for the entry to fit, DXmSvnFlushEntry scrolls to the entry.

9.2.13 Manipulating Components

As described in Section 9.1.1, each entry in your hierarchy can display as many as 30 components of information, depending upon the amount of information users need. Components can be of three data types: text, pixmaps (icons), and widgets.

Components you might want to use include:

• Icon
• Entry number
• Description
• Child summary

The SVN widget manipulation routines allow your application to:

• Set a pixmap to be used for the icon
• Set a compound string to be used for the description
• Set a widget as a component
• Set a component hidden from the user
• Insert and remove components
• Set and get a component's width
• Set and get a tag to be used as the description component
• Get a component's number (1 to 30)

The following is an example of how to create and set a pixmap to be used as an icon:

   .
   .
   .

/*
**  Create the pixmap.
*/
    parent_pixmap = XCreatePixmapFromBitmapData (
        display,                                /* (IN) display */
        XDefaultRootWindow(display),            /* (IN) drawable */
        parent_pixmap_bits,                     /* (IN) bitmap data */
        pixmap_width,                           /* (IN) width */
        pixmap_height,                          /* (IN) height */
        foreground_pixel,                       /* (IN) foreground pixel */
        background_pixel,                       /* (IN) background pixel */
        DefaultDepthOfScreen (screen));         /* (IN) pixmap depth */

    child_pixmap = XCreatePixmapFromBitmapData (
        display,                                /* (IN) display */
        XDefaultRootWindow(display),            /* (IN) drawable */
        child_pixmap_bits,                      /* (IN) bitmap data */
        pixmap_width,                           /* (IN) width */
        pixmap_height,                          /* (IN) height */
        foreground_pixel,                       /* (IN) foreground pixel */
        background_pixel,                       /* (IN) background pixel */
        DefaultDepthOfScreen (screen));         /* (IN) pixmap depth */

   .
   .
   .
    DXmSvnDisableDisplay(Svn);

    if (node->number == 0)
        DXmSvnSetComponentPixmap (svnw, data->entry_number, 1, 0, 0,
                               child_pixmap,  pixmap_width, pixmap_height);

    else DXmSvnSetComponentPixmap (svnw, data->entry_number, 1, 0, 0,
                               parent_pixmap, pixmap_width, pixmap_height);
   .
   .
   .
    DXmSvnEnableDisplay(Svn);

This example creates two separate pixmaps: one for parent entries and one for entries without children. The example then uses the node->number field to determine if the selected entry has children and sets the icon component accordingly. Because the call to this code is not the result of a callback, the example disables and enables the SVN widget.

9.2.14 Highlighting an Entry

Application users might want to highlight entries to make them stand out in a long list of entries. Another possible use of highlighting is to highlight the user's selection so that the user can confirm the selection. For example, when a user requests a pop-up menu by clicking MB3 on an entry, DECwindows Mail highlights the entry.

The SVN widget allows your application to highlight one or more entries by framing them in dashed rectangular boxes. Your application decides how to treat the highlighted entries; the SVN widget does not assign any special significance to highlighted entries.

The SVN widget includes routines that allow your application to:

• Set and clear highlighting for an entry
• Set and clear highlighting for all entries
• Show highlighted entries
• Hide the highlighting for one or more entries
• Get the number of highlighted entries
• Get the entry numbers of highlighted entries

/*
**  This routine is the callback for the Highlight All button
*/
void MenuHighlightAll()
{
    DXmSvnDisableDisplay(Svn);
    DXmSvnHighlightAll(Svn);
    DXmSvnEnableDisplay(Svn);
}

Because the call to this code is not the result of a callback, the example disables and enables the SVN widget.

If your application is to use highlighting, you should set the DXmSvnNexpectHighlighting resource to TRUE to leave room for the highlight rectangle.

9.2.15 Getting the Displayed Entries

The SVN widget includes routines that allow your application to get the number of entries currently being displayed in the SVN window and then get the entry numbers, tag values, and y-coordinates associated with those entries.

In the following example, DXmSvnGetDisplayed returns the entry numbers of the displayed entries to the array of integers specified by the disp_nums argument, does not use the tag argument value, and returns the y-coordinates to the disp_ys argument. The disp_count argument is the number returned by the DXmSvnGetNumDisplayed routine.

   .
   .
   .
/*
**  Local data declarations
*/
    int disp_count;
    int disp_nums [75];
    int disp_ys   [75];
    int i;


/*
**  Ask how many are being displayed.  If none are being displayed, then
**  leave.
*/
    disp_count = DXmSvnGetNumDisplayed (w);
    if (disp_count == 0)
        return;

/*
**  Max out at 75 hardcoded
*/
    if (disp_count > 75) disp_count = 75;


/*
**  Get those that are displayed.  The null field is for a tag array.
*/
    DXmSvnGetDisplayed (w, disp_nums, NULL, disp_ys, disp_count);

The SVN widget includes an entry-dragging mechanism that lets a user click MB2 on an entry, drag that entry to a new location, and release MB2 to move the entry.

The SVN widget also allows an application to implement an application-specific dragging mechanism. Your application can call the DXmSvnSetApplDragging routine to toggle between the SVN and application-specific dragging modes.

If the DXmSvnNselectionsDraggedCallback callback routine is not null, and application-specific dragging is not set, a callback is generated when entries are being dragged with MB2. The SVN widget implements the dragging function; your application can use this callback to perform some dragging-related function.

If your application calls the DXmSvnSetApplDragging routine to set the application-specific dragging mode, the DXmSvnNdraggingCallback is generated when the user clicks on MB2. When the application dragging is complete, the DXmSvnNdraggingEndCallback is generated. If your application uses application-specific dragging, you must provide the callback routines.

9.2.17 Ghosting

As described in Section 9.2.16, the SVN widget allows applications to implement their own application-specific entry dragging mechanism. As part of this dragging mechanism, your application can define the shape, size, and relative x and y origins of a "ghost" image that follows the entries as they are moved.

The ghost resources are as follows:

• DXmSvnNghostHeight---Height of ghost pixmap.
• DXmSvnNghostPixmap---Pixmap of ghosting image.
• DXmSvnNghostWidth---Width of ghost pixmap.
• DXmSvnNghostX---Relative x offset of the ghost image from the actual entry. This field is provided because the ghost image can be larger or smaller than the size of the entry.
• DXmSvnNghostY---Relative y offset of the ghost image from the actual entry. This field is provided because the ghost image can be larger or smaller than the size of the entry.

The following example gets the x and y offsets of the ghost image. Then, it gets the current selections---that is, the entries being moved---and sets their new entry positions. The data->x and data->y fields of the callback indicate the origin of the ghost; that is, the data->x and data->y fields give the location of the ghost and not of the entry itself.

/*
 **  If not user defined tree, then return
 */
  XtSetArg    (arguments[0], DXmSvnNghostX, &offset_x);
  XtSetArg    (arguments[1], DXmSvnNghostY, &offset_y);
  XtSetArg    (arguments[2], DXmSvnNtreeStyle, &tree_style);
  XtGetValues (Svn, arguments, 3);


  if (tree_style == DXmSvnKuserDefinedTree)
      {
      /*
       **  Move the entry to the new position
       */
      DXmSvnGetSelections (Svn, selection, NULL, entry_tags, num_selections);
      DXmSvnSetEntryPosition (Svn, selection[0], TRUE,
         data->x-offset_x, data->y-offset_y);
      return;
      }

The SVN widget lets your application set default font lists for each entry level or to use one font list as the default for all entry levels. The font list resources are as follows:

• DXmSvnNfontList---Default font list when no level font lists are specified
• DXmSvnNfontListLevel0---Default level 0 font list
• DXmSvnNfontListLevel1---Default level 1 font list
• DXmSvnNfontListLevel2---Default level 2 font list
• DXmSvnNfontListLevel3---Default level 3 font list
• DXmSvnNfontListLevel4---Default level 4 font list

The SVN demo application assigns a child level number (the first field in the data structure) to each entry in the hierarchy, as follows:

static _Node B  = { 1, 7};
static _Node P1 = { 2, 7};
static _Node P2 = { 2, 3};
static _Node P3 = { 2, 3};
static _Node P4 = { 2, 4};
   .
   .
   .

Therefore, if you set the DXmSvnNfontListLevel2 resource, all level 2 entries (children of P1, P2, P3, and P4) use the specified font list.

The following example sets the DXmSvnNfontListLevel2 and DXmSvnNfontListLevel3 resources:

XmFontList fontlist;
Arg        arglist[10];
int        ac;

   .
   .
   .

fontlist = XmFontListCreate (XLoadQueryFont (XtDisplay(toplevel),
           "-ADOBE-ITC Avant Garde Gothic-Book-R-Normal--14-100-*-*-P-80-*"),
            XmSTRING_DEFAULT_CHARSET);

ac = 0;
XtSetArg    (arglist[ac], DXmSvnNfontListLevel2, fontlist);ac++;
XtSetArg    (arglist[ac], DXmSvnNfontListLevel3, fontlist);ac++;
XtSetValues (svn_widget, arglist, ac);
   .
   .
   .

Note that you can set the font list for a component independently of the font list for the entire entry. For example, if you use the DXmSvnSetComponentText routine to specify a compound string, you can use the fontlist argument to specify a font list for a component.

9.3 Setting Tree-Mode Attributes

This section describes the resources that are specific to tree mode.

9.3.1 Manipulating Tree Position

The SVN widget includes routines that allow your application to get and reinstate the tree position when the display mode is DXmSvnDisplayTree. The routines provide a way to determine the exact positioning of the display, based on x- and y-coordinates known internally by the SVN widget, and to store that position for later use. When your application restores the saved position, the SVN widget must be in the same state (same size and number of entries) as when the position was saved.

9.3.2 Setting the Tree-Mode Arc Width

Tree display mode entries are surrounded by an outline that makes the boundaries between entries clearer. You can use the DXmSvnNtreeArcWidth resource to specify an arc width for this outline.

For example, the SVN demo application sets the DXmSvnNtreeArcWidth resource to allow users to toggle between oval (arc_width = 15) and rectangular (arc_width = 0) entries.

(1)if (arc_width == 0)
     {
        arc_width = 15;
        XtSetArg    (arguments[0], DXmSvnNtreeArcWidth, arc_width);
        XtSetValues (Svn, arguments, 1);
        cs = XmStringCreate("Rectangular Entries", XmSTRING_DEFAULT_CHARSET);
     }
(2)else {
        arc_width = 0;
        XtSetArg    (arguments[0], DXmSvnNtreeArcWidth, arc_width);
        XtSetValues (Svn, arguments, 1);
        cs = XmStringCreate("Oval Entries", XmSTRING_DEFAULT_CHARSET);
     };

1. If arc_width is zero, rectangular outlines are displayed. Set arc_width to 15 to display oval entries and switch the toggle-to label to "Rectangular Entries".
2. If arc_width is not zero, oval outlines are displayed. Set arc_width to zero to display rectangular entries and switch the toggle-to label to "Oval Entries".

The DXmSvnNtreeCenteredComponents resource lets you vertically center all of the components within an entry. The SVN widget automatically alters the size of the entries to fit the centered components.

For example, the SVN demo application sets the DXmSvnNtreeCenteredComponents resource to let users toggle between centered and "normal" components.

(1) if (centered_components)
        {
           centered_components = FALSE;
           XtSetArg (arguments[0], DXmSvnNtreeCenteredComponents, centered_components);
           XtSetValues (Svn, arguments, 1);
           cs = XmStringCreate("Components Centered", XmSTRING_DEFAULT_CHARSET);
        }
(2) else {
           centered_components = TRUE;
           XtSetArg (arguments[0], DXmSvnNtreeCenteredComponents, centered_components);
           XtSetValues (Svn, arguments, 1);
           cs = XmStringCreate("Normal Components", XmSTRING_DEFAULT_CHARSET);
        };