vlist.note - VList widget documentation ******************************************************************************* * VToolkit (1995) "If it doesn't use VToolkit, it isn't cool!" * * (c) Steve Klein * * Unpublished rights reserved under the copyright laws of the United States. * ******************************************************************************* This document describes the VList widget. +----------------------+ | Modification History | +----------------------+ 29-Oct-1993 (sjk) Add VListNselectionIsLocked resource. This boolean resource allows the application to set the VList widget into an insensitive state. The user cannot change the set of selected lines, but autoscrolling still works and the application itself is still allows to change the set of selected lines. 22-Oct-1993 (sjk) Add VListNgridStyle and VListNgridPixmap resources. These resources define a color or pattern to be drawn between rows and/or columns of the list. 17-Sep-1993 (sjk) Make closurePP argument to VListGetAllSelectedLines be optional. 06-Jan-1991 (sjk) Add support for text/icon selection per cell/segment. This allows cells to be formatting as icon over text, similar to other desktop managers. 11-Dec-1991 (sjk) Add VListNallowDeadspace resource. This resource enables a mode in which the last line in the list is visible at the top of the window rather than the bottom. It is followed by deadspace. This resource is ignored unless VListNcolumnStyle is VListColumnStyleSingle. 20-Nov-1991 (sjk) Add VListNspaceTiersEqually resource. 19-Nov-1991 (sjk) Add VListChangeCell* routines, allowing application to pass field/row combination rather than requiring line closure to be passed. These new routines are more efficient than the VListChangeLine* routines because the ClosureToLine search is avoided. 15-Nov-1991 (sjk) Add VListNspaceGroupsEqually resource. 14-Nov-1991 (sjk) Add VListAnyButton option and add VListNdrag* resources. Add VListRemoveRow routine description. 29-Oct-1991 (sjk) VListField.width now determines the minimum field width for all types of fields, not just histograms. Relax restriction on all fonts needing to have the same height. Add VListNselectButton resource. Added VListAlignment~ symbols for vertical alignment options. VListNalignment resource now determines alignment of all field types, not just text and icons. Add VListSegmentNewLineMask to support multi-line text cells. Add VListNfieldResizePolicy resource. 28-Oct-1991 (sjk) Add VListNselectButton resource. 25-Oct-1991 (sjk) Add VListNiconMarginWidth and VListNiconMarginHeight resources. Row height now may be optionally computed by the widget even if the list contains icons. 31-Aug-1990 (sjk) Add SimpleTestVList sample program. This program shows how to use a simple VList in a program that lets the user move lines from one list to another by clicking on them. 29-Aug-1990 (sjk) Add per-line-item background color support. Each line item in the list may be assigned a background color by the application. By default, the widget's background color is used. Like other color values, background colors may be passed either as pixel values or as an index into the optional color list. Changes include the definition of the VListList.background field and the corresponding VListLineBackgroundMask constant. Add the VListGetAllLines routine. This routine returns the closure value of all the cells in the list. 24-Jul-1990 (sjk) Add icon support. Specifically, the application can specify icon-type fields. For each line item in that field, an icon pixmap can be supplied. Changes include the definition of the VListFieldTypeIcon constant, the VListLine.icon field and corresponding VListLineIconMask constant, and the VListNrowHeight resource. 28-Mar-1990 (sjk) Add Known Bugs section to documentation. 28-Mar-1990 (sjk) Add VListSelectStyleNone. This makes it easy for an application to create a read-only VList without having to explicitly set each line item's sensitivity to false. 28-Mar-1990 (sjk) Add multi-bar histograms. Applications can specify histogram bars with multiple segments. Each segment can have a color (index) specified and may be stippled. (Future plans include user-specified stipple patterns.) 09-Mar-1990 (sjk) Add histograms. Applications can specify that fields are to be displayed in histogram format. Grid lines and labels can also be defined by the application. Change the default value of the VListNfieldSpacingWidth resource to zero. This improves the default look when rows containing multiple fields are selected. Add a new special routine, VListGetLineCount, that returns the total number of line items in the list. Add two new modules to the sample program, vautorepeat.c and vautorepeat.uil. These modules implement auto-repeating pushbuttons and may be used by any application that would like the same feature. Add the wish list section to this document. 06-Mar-1990 (sjk) Remove VListChangeLinePixel. Applications must use VListChangeLineColoridx instead. Remove ~PixelMask usage that was added on 21-Feb-1990. The widget now uses the existence or non-existence of VListNcolorList resource pixmap to infer whether coloridx is interpreted as a color index or a pixel value. 05-Mar-1990 (sjk) Added the VListNuserData resource (compatible with DwtNuserData and XmNuserData) to allow the application to associate one Opaque longword with the VList widget as a whole. This is in addition to the Opaque closure that can be associated with each line in the list. Added the selectionCount field to the VListSelectCallbackStruct to make it easier for applications to determine how many lines in the list are selected when the callback is made. 21-Feb-1990 (sjk) Added the capability to directly specify a color by its pixel value. Previously, colors could only be specified by an index into a color palette. Added VListLinePixelMask and VListSegmentPixelMask. 26-Jan-1990 (sjk) Added the VListSelectChange structure, a list of which is passed to the VListSelect callback. This allows the application to easily determine what changed during the select operation. 26-Jan-1990 (sjk) Added VListSetAutoScrollPosition routine. This routine allows the application to enable and disable autoscrolling based on its own events. 23-Jan-1990 (sjk) Added stippled text support. String segments can be drawn through a "gray" stipple. 22-Jan-1990 (sjk) Added label padding options. Header labels may be padded with blanks or with a dashed line. Added documentation for the VHeader widget resources. 19-Jan-1990 (sjk) Added MOTIF support. 15-Jan-1990 (sjk) Added segmented string support. Each string segment can have its own color and/or font. 09-Jan-1990 (sjk) Added VListComputePreferredWidth routine. This routine allows the application to set the VList widget to its optimal width. 28-Dec-1989 (sjk) Version X2.0 update. +---------+ | Preface | +---------+ This note documents the VList widget. The VList widget can be used by Xt-toolkit-based applications to display dynamic, interactive lists. It works under both the DECwindows toolkit (XUI) and the MOTIF toolkit. The VList widget is operating-system-portable and works with both VMS and UNIX. [Note that the XUI version of the VList widget was archived in Sep-1993 and is available by special request only.] The VList is part of the VToolkit package which includes, among others, the following related widgets: VList widget - manages the active display region VHeader widget - displays column headers VFrame widget - container widget To build the sample programs on a VMS system: (*) copy the entire VToolkit source directory to your directory (*) @vbuildall (*) run testvlist To use the VList widget in your own application, include vtoolkit.h and vlist.h into any C-language module that calls the VList special routines. To use the VToolkit, link with the object files in VTKLIB.OLB. Look at the sample programs for details. I must emphasize that this is unsupported software. -steve klein- +--------------+ | Introduction | +--------------+ The VList widget can be used by Xt-toolkit-based applications to display dynamic, interactive lists. It works under both the DECwindows toolkit (XUI) and the MOTIF toolkit. The VList widget is operating-system-portable and works under both VMS and UNIX. The VList widget presents an dynamic, interactive list of records to the user. It handles records with multiple fields and aligns the columns automatically. Each record has one or more cells, also called field values. Cells may contain text, icons or histograms. The user can select and manipulate cells using the mouse. The application can change the list dynamically and efficiently. The VList widget also provides application callbacks to support a drag-and-drop user interface mechanism. At one extreme, the VList serves as a flexible, interactive widget that can display real-time numeric and graphic data. At the other extreme, it can present a simple set of options to the user in typical list-box format. Each record consists of one or more cells, one for each defined field. Under program control, each cell can be displayed in a different color or font. Cells can also be drawn in a stippled (grayed-out) mode. Both foreground and background colors for each cell can be controlled. A more advanced feature, "segmented strings", allows you to control colors and fonts of text strings on a character-by-character basis. You can also use segmented strings to put multi-line text in a single cell. By clicking or double-clicking over the window, the user can "select" one or more cells to serve as the objects of some application-specific action. The VList widget supports callbacks to notify the application of a select or double-click event. Options include per-cell and per-record selection, and single-select, multi-select and extend-select drag options. If the list is so large that it cannot be completely displayed in the widget's window, scroll-bars are shown that allow the user to do smooth, live scrolling of the list contents. The application can control the visibility and positioning of the scroll-bars. The VList widget supports autoscrolling. Autoscrolling is activated when the user presses the mouse button in the VList window and drags the mouse outside the window. Autoscrolling speed is governed by the pointer's distance from the window. Autoscrolling can also be controlled by the application. The VList widget can efficiently support large lists with as many as several thousand lines. Screen updates are optimized by the widget. The VList widget has several special routines that let the application add, remove, change and reorder the list. Individual cells can be efficiently changed in-place, allowing the VList widget to be used to display real-time data. The VList widget also has a special routine that helps implement a pop-up menu with different menu entries for each cell in the list. The VList widget documentation is organized into these sections: (*) Terms (*) Resources (*) Shared Data Structure Definition (*) Callbacks (*) Special Routines (*) Creation (*) Wish List (*) Known Bugs +-------+ | Terms | +-------+ cell A cell is the smallest addressible object managed by the widget. Each cell has a number of attributes, or characteristics. The widget interfaces are designed so that new cell attributes can be added in an upward compatible way. In this version of the widget, there are the following per-line-item attributes: all types: closure (opaque ID number) select (the cell is selected) sensitive (the cell is selectable by the user) stippled (the cell is drawn in a grayed-out mode) coloridx (color index or pixel value) background (background color index or pixel value) text type only: text (ASCIZ text string) fontidx (index into the font list) segment list (for character-by-character control) histogram type only: high/low values (for histogram scaling) bar list (describing each histogram bar segment) icon type only: icon pixmap (cell) closure Each cell has a "closure" value that is an opaque, non-zero value (ID number) that identifies the cell. This closure value can be used for any purpose by the application. Often, it contains the address of an application-private, per-line-item data structure. Simple applications may not need to use the cell closure value. The closure value identifies the particular cell, both when the widget communicates with the application (through a callback) and when the application communicates with the widget (through a special routine). This closure value may be supplied by the application, or the application may choose to let the VList widget pick a value. Similarly, if the application supplies a zero, it is replaced by a widget-supplied, non-zero value. Closure values supplied by the application should be unique, but this is not enforced by the widget. Closure values supplied by the widget are unique among themselves. To ensure uniqueness, either all cells in the list must get their closure values from the application or all from the widget. The application can change a cell's closure value at any time by calling VListChangeLine or a similar routine. A record (as opposed to a cell) is identified by the closure value of the first cell in the record. text "Text" used by the VList widget is represented by zero-terminated, 8-bit ASCII strings. Text can be supplied by the application for use in cells, header labels and histogram grid labels. coloridx The application can control the color of an individual object by assigning a "coloridx" value to that object. Many objects have a coloridx attribute, for example: text, histogram bars, and grid lines. The coloridx of a cell is also used as the highlight color when the cell is selected. Depending on whether a color list was supplied (through the VListNcolorList resource), the coloridx value is interpreted either as a color index or as a pixel value. If a color list was supplied, the coloridx is a zero-based index into the color list pixmap. The object will be displayed in the color of the corresponding color list pixel. For example, a coloridx value of 3 corresponds to the fourth pixel (x=3, y=0) in the color list pixmap. A coloridx value greater than or equal to the width (in pixels) of the color list pixmap is reduced in range by a MOD operation. If a color list was not supplied, the coloridx value supplied by the application is directly used as a pixel values rather than as an index into the color list. In this case, the application is responsible for allocating or otherwise obtaining the pixel value. The widget will supply a default color when the application does not supply a specific coloridx value for an object. If a color list was supplied, the default object color is the first color in the list. If a color list was not supplied, the default color is specified by the VListNforeground resource. fontidx The application can control the font of an individual text object by assigning a "fontidx" value to that object. A fontidx is a zero-based index into the font table specified by the VListNfontTable resource. (cell) sensitivity Each cell in the list is potentially selectable by the user. The application can control the selectability of an individual cell by changing its "sensitivity". Sensitivity is represented by a boolean value (1/0) indicating whether the cell is able to be selected by the user. By default, all cells are sensitive. Simply setting a cell insensitive does not change its visual rendition, nor does it prevent the application from selecting the cell through the VListChangeLine (or similar) special routine. (cell) selection state Each cell in the list has a boolean value (1/0) indicating whether the cell is currently selected. When selected, the cell is highlighted in reverse-video. If the option specified by the VListNselectUnit resource is VListSelectUnitLine, the selection state of the first cell in the record controls the highlighting of the entire record. segment list For text-type cells only, this optional array of VListSegment structure entries allows the application to specify colors, fonts and stippling on a character-by-character basis. A segment is defined by an offset into the cell's text string and a length in characters. By using a segment list, the application can also specify a multi-line text string to be drawn within a single cell. stippled Each cell in the list has a boolean value (1/0) indicating whether the cell is to be drawn in a "stippled" (grayed-out) mode. Although many user interfaces use stippling to indicate insensitivity, stippling can be controlled independently and can be used for any purpose by the application designer. (histogram) low/high value For histogram-type cells only, these two integer values specify the scale values corresponding to the two ends of the histogram bar. The widget will quietly swap the low and high values if the low value is greater than the high value, making it easy to display histograms that vary both up and down from some central baseline. Histogram values are scaled by the widget based on the min and max values specified in the corresponding VListField structure. icon For icon-type cells only, the application can supply an icon pixmap (X-windows Pixmap ID) for each cell. If zero (0) is supplied, no icon is drawn for that cell. This pixmap can be loaded from a UID file (see testvlist.c for an example of this) or can be created by any other mechanism that creates an X-windows Pixmap. list The "list" is the virtual, two-dimensional array of cells managed by the widget. The horizontal dimension consists of "fields", and the vertical dimension consists of "rows". The total number of cells in the list equals the product of the number of rows and the number of fields. Each VList widget instance manages exactly one list. Multiple instances of the widget can be used to manage independent lists. The virtual array that is the list is mapped onto the physical, on-screen display in one of two basic layouts: single column and multiple column. Choice of layout can be selected by the application, the user, or dynamically by the widget. field A "field" is the logical collection or description of all the cells in a particular vertical slice of the list. Fields are numbered starting with zero. The application specifies the number of fields, which defaults to 1. Each field has a number of attributes. In this version of the widget, each field has the following attributes associated with it: type, alignment, minimum overall width, margin width and height, resize policy, min/max histogram values and histogram grid list. (field) type Each field has a type attribute that specifies whether the cells in that field contain text, histograms or icons. The default field type is text. All cells in a particular field have the same type. (field) alignment This attribute specifies how the body of a cell should be aligned within the cell's display region. There are nine alignment options corresponding to all combinations of left/center/right and top/center/bottom. (field) minimum width This attribute specifies the minimum width in pixels for the field. The actual width of the field is determined dynamically and automatically by the VList widget based on the list contents. (field) margin width and height These attributes specify the margin width and height in pixels between the body of a cell and the cell's display region. (field) resize policy This attribute determines whether the width of the field should be allowed to shrink when its contents allow. By setting this attribute to grow-only, certain applications may be able to reduce window flicker. (field) min/max histogram values For histogram-type fields only, these integer values specify the low and high limits to be used to scale grid-line and histogram values. If the application is displaying floating-point data, the application must do its own floating-point to integer conversion and scaling. (field) histogram grid list For histogram fields only, this optional array of VListGrid entries specifies grid lines and grid header labels. Each grid entry has a value, coloridx, line dash pattern, and header label. row A row is the logical collection of all the cells in a particular horizontal slice of the list. The rows are numbered starting with zero. The number of rows is determined indirectly by dividing the number of cells by the number of fields. The number of rows changes as records are added to and removed from the list. record A record is also a logical collection of all the cells in a particular horizontal slice of the list, but, unlike rows, records are not numbered. Instead, each record is identified by the closure value of the first cell in the record. A record is the smallest unit that can be added to or removed from the list. A record is also the smallest unit that can be moved (reordered). layout style Visually, cells are organized into a two-dimensional array. The cells in a vertical slice of the visual array are called a column, and the cells in a horizontal slice are called a "tier". Columns and tiers are numbered starting with zero. There are two basic layout styles - single and multiple. In single layout style, each field corresponds to a single column and each row or record corresponds to a single tier. Column and tier numbers are equal to field and row numbers. In multiple layout style, the list is divided into blocks of records which are then placed side-by-side in the display. In this case, there will be more than one "column group", with as many columns in each group as there are fields. If the widget's column style is BestFit, the widget will select single or multiple column layout based on the actual contents and size of the window. +-----------+ | Resources | +-----------+ The VList widget is a subclass of Composite and inherits all the Core and Composite resources. These resources are Xt-toolkit-specific and are not discussed in this document. The VList widget also has these widget-specific resources: VListNalignment (int, default = VListAlignmentLeft) specifies the default alignment for fields and header labels. Allowable values for the VListNalignment resource are: VListAlignmentCenter VListAlignmentTop VListAlignmentBottom VListAlignmentLeft VListAlignmentRight VListAlignmentTopLeft VListAlignmentTopRight VListAlignmentBottomLeft VListAlignmentBottomRight VListAlignmentBeginning VListAlignmentEnd This default can be overridden by the application for individual fields and labels through the VListNfields and VListNlabels resources. In this version of the VList widget, VListAlignmentBeginning and VListAlignmentEnd are identical to VListAlignmentLeft and VListAlignmentRight. These options are defined for future support of right-to-left text. VListNallowDeadspace (boolean, default = false) enables a mode in which the last line in the list is visible at the top of the window rather than the bottom. It is followed by deadspace. This resource is ignored unless VListNcolumnStyle is VListColumnStyleSingle. VListNautoScrollRate (int, default = 15) specifies the relative speed at which the VList widget will scroll its contents when the user drags the pointer outside the window. The larger the value, the faster the window will scroll. Auto-scroll speed is also proportional to the pointer's distance from the edge of the window. VListNcolorList (pixmap, default = 0) specifies an optional palette of colors available to the VList widget. To define this color list using UIL, create a small pixmap containing one pixel of each color. Only the first row of pixels in this pixmap is used. If supplied, the color list is used to map from a coloridx value to a pixel. The coloridx value is used as an index into the color list and the value of the corresponding pixel is used. For example, a coloridx value of 3 corresponds to the pixel at location (x=3, y=0) in the color list pixmap. A coloridx value greater than or equal to the width (in pixels) of the color list pixmap is reduced in range by a MOD operation. If a color list is not supplied, the widget directly uses a coloridx value as a pixel value rather than as an index into the color list. In this case, the application is responsible for allocating or otherwise obtaining a pixel value. XLib routines like XAllocNamedColor are one way to allocate color pixel values. Cells for which the application does not specify an explicit coloridx value are drawn in the default foreground and background colors. If a color list is supplied, the first color in the color list is used as the default foreground color. If no color list is supplied, the default foreground color is specified by the VListNforeground resource. The default background color is determined by the (core) XtNbackground resource whether or not a color list is supplied. Although the color list resource cannot be changed once the widget has been realized, the color of any individual cell can be changed at any time by calling VListChangeLine or a convenience routine (VListChangeLineColoridx or VListChangeLineBackground). Note: The color of the line that separates the VList widget from the VHeader widget is controlled by the (core) XtNborderPixmap or XtNborderColor resources, not by any VList widget-specific resource. VListNcolumnStyle (int, default = VListColumnStyleBestFit) specifies the column arrangement. Cells in the list will be physically organized according to the specified style. Allowable values for this resource are: VListColumnStyleSingle - single vertical column VListColumnStyleMultiple - multiple columns, side-by-side VListColumnStyleBestFit - best use of visible space VListColumnStyleSingle forces the list to be displayed in a single vertical column group. Some display update optimizations can only be done when this column style is selected, therefore this may be the most efficient choice when the list is dynamically updated. A vertical scroll-bar may be needed to allow the user to scroll through the list and a horizontal scroll-bar may also be needed if the contents of the list are too wide to be shown completely. VListColumnStyleMultiple forces the list to be displayed as one or more side-by-side column groups. When this column style is selected, a vertical scroll-bar is never needed, but a horizontal scroll-bar may be needed. VListColumnStyleBestFit specifies that the widget is to select single or multiple column layout based on the size of the window and the list contents. Multiple column layout is selected if the entire list can be shown in the window or if at least two complete column groups would be visible at all times. Otherwise, single column layout is selected. VListNdoubleClickDelay (int, default = 250) specifies the maximum delay (in thousandths of a second) between a ButtonRelease and ButtonPress that will arm the double-click callback (VListNselectConfirmCallback). VListNdragButton (int, default = VListButton2(MOTIF) or VListButton3(XUI)) specifies the mouse button that will be used by the VList widget for drag-and-drop operations. Allowable values for this resource are: VListAnyButton VListButton1 VListButton2 VListButton3 VListButton4 VListButton5 VListNdragWidget (widget, default = 0) specifies the widget ID of the drag widget. This widget (usually a label or a form containing labels) will be managed automatically by the VList widget when a drag-and-drop action is started by the user. If the user attempts to drag an entry that should not be dragged. the application can reject the drag operation by setting the VListNdragWidget resource to zero in the VListNdragArmCallback, VListNfieldCount (int, default = 1) specifies the number of fields (cells) per record. This resource may only be changed when the list is empty. VListNfieldResizePolicy (int, default = VListResizePolicyAny) specifies the default field resize policy. Allowable values for this resource are: VListResizePolicyAny - field may grow or shrink VListResizePolicyGrowOnly - field may grow only This default can be overridden by the application for individual fields through the VListNfields resource. VListNfieldSpacingWidth (int, default = 0) specifies the horizontal distance, in pixels, between adjacent fields in a single column group. This is not to be confused with VListNmarginWidth which specifies the space to either side of a column group. VListNfields (VListField *, default = 0) specifies an array of VListField entries describing the per-field attributes. If the VListNfields resource is supplied, it must contain as many VListField entries as there are fields-per-record. Fields-per-record is specified by the VListNfieldCount resource. If the VListNfields resource is not supplied, a default field definition is supplied by the widget for all fields. The definition of the VListField structure is as follows: typedef struct { int mask; /* mask flags */ int width; /* minimum width in pixels */ int alignment; /* VListAlignment~ option */ int marginWidth; /* margin width in pixels */ int marginHeight; /* margin height in pixels */ int resizePolicy; /* VListResizePolicy~ option */ int type; /* VListFieldType~ option */ /* VListFieldTypeHist only */ int maxValue; /* histogram max value */ int minValue; /* histogram min value */ VListGrid *gridsP; /* address of grid array */ int gridCount; /* number of grid entries */ } VListField; VListField.mask specifies which attribute values are to be taken from the VListField structure and which are to be given default values. Use of a mask supports upward compatible extensions to the VListField structure and a uniform mechanism for defaulting. Defined mask bits and their corresponding fields are: VListFieldWidthMask - width VListFieldAlignmentMask - alignment VListFieldMarginWidthMask - marginWidth VListFieldMarginHeightMask - marginHeight VListFieldResizePolicyMask - resizePolicy VListFieldTypeMask - type /* VListFieldTypeHist only */ VListFieldMaxValueMask - maxValue VListFieldMinValueMask - minValue VListFieldGridsMask - gridsP and gridCount [VListFieldWidthMask] The field's minimum width in pixels is specified by VListField.width. By default, the field's minimum width is dynamically determined by its contents. This only specifies a minimum width. The widget will automatically and dynamically increase the width of the field as needed to display its entire contents. [VListFieldAlignmentMask] The field's alignment is specified by VListField.alignment. By default, the value of the VListNalignment resource is used. Allowable values for VListField.alignment are: VListAlignmentCenter VListAlignmentTop VListAlignmentBottom VListAlignmentLeft VListAlignmentRight VListAlignmentTopLeft VListAlignmentTopRight VListAlignmentBottomLeft VListAlignmentBottomRight VListAlignmentBeginning VListAlignmentEnd The body of each cell is aligned within its display region according to the specified option. [VListFieldMarginWidthMask and VListFieldMarginHeightMask] The field's margin width and margin height are specified by VListField.marginWidth and VListField.marginHeight. The default is determined by resources based on the field type. -- type -- -- resources -- VListFieldTypeIcon : VListNiconMarginWidth VListNiconMarginHeight VListFieldTypeText : VListNtextMarginWidth VListNtextMarginHeight VListFieldTypeHist : VListNhistMarginWidth VListNhistMarginHeight The body of each cell is padded with the specified margin width and height before it is positioned in its display region. [VListFieldResizePolicyMask] The field's resize policy is specified by VListField.resizePolicy. By default, the value of the VListNfieldResizePolicy resource is used. Allowable values for VListField.resizePolicy are: VListResizePolicyAny - field may grow or shrink VListResizePolicyGrowOnly - field may grow only VListResizePolicyAny specifies that the field width may grow or shrink based on the actual contents of its cells. VListResizePolicyGrowOnly specifies that the field width may grow as needed to display the contents of its cells but the field will not shrink except when the entire window contents need to be redisplayed. This option may reduce flicker (window repaint) during certain dynamic update operations. [VListFieldTypeMask] The field's type is specified by VListField.type. The default is VListFieldTypeText. Allowable values for VListField.type are: VListFieldTypeText - field contains ASCII text (the default) VListFieldTypeHist - field contains histograms VListFieldTypeIcon - field contains icon pixmaps [VListFieldMaxValueMask and VListFieldMinValueMask] Applies to histogram fields only. The minimum and maximum values in the histogram's range are specified by VListField.minValue and VListField.maxValue. All grid and bar values will be scaled to this range, and values outside the range will be clipped or hidden. The default minValue is zero (0) and the default maxValue is 100. [VListFieldGridsMask] Applies to histogram fields only. VListField.gridsP points to an array of VListGrid entries which specify grid lines and labels, and VListField.gridCount specifies the number of entries in the array. By default, no grid lines or grid labels will be drawn. The definition of the VListGrid structure is as follows: typedef struct { int mask; /* mask flags */ char *textP; /* ASCIZ label */ int row; /* label's row in the header */ int value; /* value */ int dashOn; /* pixels on (or zero) */ int dashOff; /* pixels off */ int coloridx; /* color index or pixel value */ } VListGrid; VListGrid.mask specifies which attribute values are to be taken from the VListGrid structure and which are to be given default values. Defined mask bits and their corresponding fields are: VListGridTextMask - textP VListGridRowMask - row VListGridValueMask - value VListGridDashMask - dashOf and dashOff VListGridColoridxMask - coloridx [VListGridTextMask] ASCIZ text specified by VListGrid.textP will be displayed in the header, centered over the grid's value. By default, no label will be drawn for this grid value. [VListGridRowMask] The grid's label specified by VListGrid.textP will be drawn on the zero-based row in the header specified by VListGrid.row. By default, the label will be drawn on the top (zeroeth) row in the header. [VListGridValueMask] The grid's value is specified by VListGrid.value. By default, a value of zero is used. If the grid's value is out of range (as determined by VListField.minValue and VListField.maxValue), the grid line will not be visible but the label (if any) will still be drawn in the appropriate location in the header. [VListGridDashMask] The grid line's dash pattern is specified by VListGrid.dashOn and VListGrid.dashOff. If dashOn is zero, no line will be drawn. If dashOff is zero, a solid line will be drawn. By default, the grid line's dash pattern is specified by the VListNgridDashOn and VListNgridDashOff resources. [VListGridColoridxMask] The grid line's coloridx is specified by VListGrid.coloridx. If a color list was supplied through the VListNcolorList resource, then the widget uses the coloridx value to index into the color list to find the color in which the grid line is to be drawn. In this case, the default grid color is the first color in the color list. If no color list was supplied, the coloridx value is directly used as the pixel value of the grid line. In this case, the default grid color is determined by the value of the VListNforeground resource. VListNfontTable (fontList, default = XtFontDefault) specifies a set of fonts to be used by the VList widget to display text. When calling VListAddLine or VListChangeLine, you can assign a fontidx value (font index) to a text-type cell or string segment. The text will be displayed in the corresponding font from this font table. For example, a fontidx of 3 corresponds to the fourth font in the font list (since fontidx is zero-based). A fontidx value greater than or equal to the number of fonts in this table is reduced in range by a MOD operation. By default, all text will be drawn in the default toolkit font. Although the VListNfontTable resource cannot be changed once the widget has been realized, the font of any individual cell or text segment in the list can be changed at any time by calling VListChangeLine. Use the VHeader widget's VHeaderNfontTable to control the font of the text in the header. The VListNfontTable resource only controls the fonts in the body of the VList widget itself. VListNforeground (pixel, default = XtDefaultForeground) specifies the default foreground color for the VList widget. This resource is used only if the VListNcolorList resource is not supplied and is used as the final fallback. Changing this resource does not affect cells that have already been added to the list. VListNgridDashOff (int, default = 2) specifies the number of background pixels in the default dash line pattern for the grid lines. This default may be overridden for individual grid lines through the VListNfields resource. VListNgridDashOn (int, default = 2) specifies the number of foreground pixels in the default dash line pattern for the grid lines. This default may be overridden for individual grid lines through the VListNfields resource. VListNgridPixmap (Pixmap, default = none) specifies the pixmap (pattern) to be shown in the blank space between the cells in the list. This resource is ignored unless the VListNgridStyle resource is equal to VListGridStylePixmap. VListNgridStyle (int, default = VListGridStyleBackground) specifies the background grid style. Not to be confused with the histogram grids, this VListNgridStyle resource gives you control over the VList window color or pattern that will appear in the blank space between the cells in the list. To be most effective, the VListNfieldSpacingWidth and VListNrowSpacingHeight resources can be set to non-zero values to control the apparent width of the background grid. Allowable values for the VListNgridStyle resource are: VListGridStyleBackground - use the background color VListGridStyleForeground - use the foreground color VListGridStylePixmap - use the VListNgridPixmap pattern VListGridStyleBackground, the default, suppresses the background grid. This is the most efficient option. No grid color or pattern will be shown in the blank space between the cells in the list. VListGridStyleForeground specifies that the widget's foreground color as specified by the VListNforeground resource will be used as the solid background grid. This color will be shown in the blank space between the cells in the list. VListGridStylePixmap specifies that the pixmap specified by the VListNgridPixmap resource will be used as the background grid pattern. This pattern will be shown in the blank space between the cells in the list. This option can be used to create a background grid that is a different color than the widget's VListNforeground color. It also can be used to create a background grid that is a pattern. VListNheaderWidget (widget, default = dynamic) specifies the custom VHeader widget to be used for displaying column header labels. This resource may not be changed by XtSetValues once the VList widget has been realized. The application does not directly manipulate the VHeader widget, but uses the VListNlabels and VListNlabelCnt resources to control the column headers. By default, the VList widget locates and uses the VHeader widget that has the same VFrame parent widget. This resource is present for compatibility reasons only and should not be used. VListNhistHeight (int, default = 10) specifies the minimum height in pixels for histogram bars. This height does not include the margin. VListNhistMarginHeight (int, default = 4) specifies the default minimum number of pixels between the body of a histogram bar and the edge of its cell. The application may override this default for individual fields through the VListNfields resource. VListNhistMarginWidth (int, default = 4) specifies the default number of pixels between the body of a histogram bar and the edge of its cell. The application may override this default for individual fields through the VListNfields resource. VListNhistWidth (int, default = 100) specifies the default width in pixels for any histogram-type field. The application may override this default for individual fields through the VListNfields resource. This width does not include the margin. VListNhScrollBarPolicy (int, default = VListScrollBarPolicyAsNeeded) specifies the scroll-bar policy for the horizontal scroll-bar. Presence or absence of scroll-bars does not affect auto-scrolling. Allowable values for this resource are: VListScrollBarPolicyAsNeeded - visible when needed VListScrollBarPolicyNever - never visible VListScrollBarPolicyAlways - always visible VListNhScrollBarWidget (widget, default = dynamic) specifies the horizontal scroll-bar widget to be used. This resource is present for compatibility reasons only and should not be used. By default, the VList widget locates and uses the horizontal scroll-bar widget that has the same VFrame parent widget. If no horizontal scroll-bar is found, autoscrolling is the only way to perform horizontal scrolling. This resource may not be changed by XtSetValues once the VList widget has been realized, however the VListNhScrollBarPolicy resource can be changed by XtSetValues to explicitly control the visibility of the horizontal scroll-bar. VListNiconMarginHeight (int, default = 4) specifies the default minimum number of pixels between the body of an icon pixmap and the edge of its cell. The application may override this default for individual fields through the VListNfields resource. VListNiconMarginWidth (int, default = 4) specifies the default minimum number of pixels between the body of an icon pixmap and the edge of its cell. The application may override this default for individual fields through the VListNfields resource. VListNlabelCnt (int, default = 0) specifies the number of column header labels. When a non-zero value is given to this resource, the VListNlabels resource must also be supplied at the same time. VListNlabelPadOption (int, default = VListLabelPadWithDashes) specifies the default padding option for header labels. The application may override this default for individual labels through the VListNlabels resource. Allowable values for this resource are: VListLabelPadWithDashes - pad with a dashed line VListLabelPadWithBlanks - do not pad the label VListNlabels (VListLabel *, default = 0) specifies an array of VListLabel entries, one for each header label. For each label, a text string, row, alignment, first field, last field and padding option can be specified. The array must have the exact number of entries specified by the VListNlabelCount resource. By default, column headers will not be displayed. Each entry in the VListNlabels resource is described by the following structure: typedef struct { int mask; /* mask flags */ char *textP; /* pointer to ASCIZ text */ int row; /* zero-based row number */ int alignment; /* VListAlignment~ option */ int firstField; /* zero-based first field */ int lastField; /* zero-based last field */ int pad; /* VListLabelPadWith~ option */ } VListLabel; VListLabel.mask indicates which values are to be taken from the VListLabel structure and which are to be given default values. Using a mask allows for upward compatible extensions to the VListLabel structure as well as a uniform mechanism for defaulting. Allowable mask values are: VListLabelTextMask - VListLabel.text is specified VListLabelRowMask - VListLabel.row is specified VListLabelAlignmentMask - VListLabel.alignment is specified VListLabelFirstFieldMask - VListLabel.firstField is specified VListLabelLastFieldMask - VListLabel.lastField is specified VListLabelPadMask - VListLabel.pad is specified [VListLabelTextMask] The ASCIZ text string specified by the VListLabel.textP field is displayed in the column header area. Because this version of the VList widget supports only ASCIZ text in its column headers, all VListLabel entries should have this bit set. [Future versions of the widget may support compound strings and other representations.] [VListLabelRowMask] The label will be displayed in the column header area on the zero-based row number specified in VListLabel.row. By default, the label will be displayed by default on the top (zeroeth) row. [VListLabelAlignmentMask] The label's alignment is determined by the value specified in VListLabel.alignment. By default, the label's alignment is determined by the value of the VListNalignment resource. Allowable values for VListLabel.alignment are: VListAlignmentCenter VListAlignmentTop VListAlignmentBottom VListAlignmentLeft VListAlignmentRight VListAlignmentTopLeft VListAlignmentTopRight VListAlignmentBottomLeft VListAlignmentBottomRight VListAlignmentBeginning VListAlignmentEnd [VListLabelFirstFieldMask} The first (left-most) field covered by the label is determined by the zero-based value specified in VListLabel.firstField. By default, the ordinal position of the VListLabel entry determines the first field. That is, labels are assigned one-to-one to fields. [VListLabelLastFieldMask] The last (right-most) field covered by the label is determined by the zero-based value specified in VListLabel.lastField. By default, the last field is equal to the first field. That is, the label will only cover a single field. [VListLabelPadMask] The text in the label will be padded to the full width of its covered columns according to the option specified in VListLabel.pad. The default padding option is specified by the VListNlabelPadOption resource. Allowable values for the VListLabel.pad field are: VListLabelPadWithDashes - pad with a dashed line VListLabelPadWithBlanks - pad with spaces VListNmarginHeight (int, default = 6) specifies the minimum margin height in pixels above the top cell and below the bottom cell in the list. When the list is displayed in multiple column style, the top and bottom margins are automatically balanced by the VList widget for improved visual appearance. VListNmarginWidth (int, default = 8) specifies the margin width in pixels to either side of each column group. When the list is displayed in muliple column style, the spacing between column groups is twice the value specified by this resource. VListNrowHeight (int, default = 0) specifies the minimum height, in pixels, of each row. The widget computes actual row height dynamically and automatically based on list contents. VListNrowSpacingHeight (int, default = 0) specifies the vertical distance, in pixels, between cells in a column. VListNselectButton (int, default = VListButton1) specifies the mouse button that will be used by the VList widget for select operations. Allowable values for this resource are: VListAnyButton VListButton1 VListButton2 VListButton3 VListButton4 VListButton5 VListNselectStyle (int, default = VListSelectStyleSingle) specifies the select style. Allowable values for this resource are: VListSelectStyleSingle - single select style VListSelectStyleMultiple - multiple select style VListSelectStyleExtend - extend select style VListSelectStyleNone - no selection VListSelectStyleSingle specifies that only one entry can be selected at a time. As soon as the user presses the select button in the VList window, the previously selected entry is deselected and the entry under the pointer is selected. As the pointer is moved, the selection tracks the pointer position. When the user releases the mouse button, the selectCallback is called, at which time there may be zero or one entry selected. VListSelectStyleMultiple specifies that any number of entries can be selected at a time. When the user presses the select button in the VList window, the entry under the pointer is toggled. That is, if it was not selected, it becomes selected, and if it was already selected, it is deselected. This sets the "parity" of the mouse operation. As the pointer is moved, the entries between the down-click position and the current position are selected or deselected according to the parity. This allows the user to select and deselect ranges of entries without affecting entries outside the range. VListSelectStyleExtend is similar to VListSelectStyleMultiple with one exception. When the user presses the select button in the VList window and the shift key is not down, then all selected entries in the list are immediately deselected. If the shift key is down, then the behavior is exactly like VListSelectStyleMultiple. VListSelectStyleNone does not allow any cells to be selected by the user. This is equivalent to setting the sensitivity of all cells to false. Unlike setting the entire widget insensitive using the XtSetSensitive routine, this select style still allows the user to autoscroll the widget. VListNselectUnit (int, default = VListSelectUnitRow) specifies the select unit. Allowable values for this resource are: VListSelectUnitRow - select whole rows of cells VListSelectUnitField - select individual cells If VListNfieldCount is equal to one, then VListNselectUnit is ignored, since each record has only one cell. VListSelectUnitRow specifies that the smallest unit of selection is an entire row (record). In this case, the closure value of the first cell in the record is used to represent the row. VListSelectUnitField specifies that each field (cell) can be individually selected. VListNselectionIsLocked (boolean int, default = false) specifies whether the widget should allow user actions (button events) to change the set of selected entries. If this resource is false (the default), then user actions are enabled and the user can select and deselect entries by using the mouse. If this resource is true, then the set of selected entries is locked and can only be changed by the application through the VList special entrypoints. This resource is similar to the XmNsensitive resource. However, if you want to lock the selected entries but still leave autoscrolling enabled, set the VListNselectionIsLocked resource to true. If you set XmNsensitive to false, not only will user actions that change selection be ignored, but user actions to autoscroll the list will also be ignored. VListNspaceGroupsEqually (boolean int, default = false) specifies whether column groups should be spaced equally within the window if the width of the list is less than the width of the window. VListNspaceTiersEqually (boolean int, default = false) specifies whether tiers should be spaced equally within the window if the height of the list is less than the height of the window. VListNtextMarginHeight (int, default = 0) specifies the default minimum height in pixels between the inner edge of a text cell and the body of text in that cell. VListNtextMarginWidth (int, default = 4) specifies the default minimum width in pixels between the inner edge of a text cell and the body of text in that cell. VListNuserData (int, default = 0) specifies an Opaque value to be associated with the VList widget instance. This is compatible with the DwtNuserData and XmNuserData resources commonly supplied for XUI and MOTIF widgets. VListNvScrollBarPolicy (int, default = VListScrollBarPolicyAsNeeded) specifies the scroll-bar policy for the vertical scroll-bar. Presence or absence of scroll-bars does not affect auto-scrolling. Allowable values for this resource are: VListScrollBarPolicyAsNeeded - visible when needed VListScrollBarPolicyNever - never visible VListScrollBarPolicyAlways - always visible VListNvScrollBarPosition (int, default = VListScrollBarPositionRight) specifies the position of the vertical scroll-bar in the window. Allowable values for this resource are: VListScrollBarPositionLeft - scroll-bar on the left VListScrollBarPositionRight - scroll-bar on the right VListNvScrollBarWidget (widget, default = dynamic) specifies the vertical scroll-bar widget to be used. This resource is present for compatibility reasons only and should not be used. By default, the VList widget locates and uses the vertical scroll-bar widget that has the same VFrame parent widget. If no vertical scroll-bar is found, autoscrolling is the only way to perform vertical scrolling. This resource may not be changed by XtSetValues once the VList widget has been realized, however the VListNvScrollBarPolicy resource can be changed by XtSetValues to explicitly control the visibility of the verticalscroll-bar. The VList widget works together with the VFrame and VHeader widgets to provide its functionality. The VFrame widget is a subclass of Composite. It does not have any widget-specified resources. The VHeader widget is a subclass of Core and inherits all the Core resources. These resources are toolkit-specific and are not discussed in this document. However, the VHeader widget also has these widget-specific resources: VHeaderNbottomMarginHeight (int, default = 1) specifies the number of pixels between the bottom of the last row of labels and the bottom of the VHeader widget's window. VHeaderNdashOff (int, default = 3) specifies, together with VHeaderNdashOn, the dashed line pattern to be used for labels that are padded with dashes. VHeaderNdashOff specifies the number of "off" pixels in the line's dash pattern. VHeaderNdashOn (int, default = 1) specifies, together with VHeaderNdashOff, the dashed line pattern to be used for labels that are padded with dashes. VHeaderNdashOn specifies the number of "on" pixels in the line's dash pattern. VHeaderNfontTable (fontList, default = XtFontDefault) specifies the font to be used to display the column header labels. Only the first font in this table is used. The other fonts are ignored. This version of the VHeader widget does not handle compound strings. VHeaderNforeground (pixel, default = XtDefaultForeground) specifies the foreground color to be used for the text labels and the dashed padding lines (if any). VHeaderNspacingHeight (int, default = 1) specifies the number of pixels between the bottom of each row of labels and the top of the next row. VHeaderNtextMarginWidth (int, default = 4) specifies the number of pixels between the left and right edges of the label text and the end of the dashed padding lines (if any). VHeaderNtopMarginHeight (int, default = 1) specifies the number of pixels between the top of the VHeader window and the top of the first row of labels. +-------------------------------------+ | VListLine Data Structure Definition | +-------------------------------------+ The VListLine data structure is used by the widget's special routines to send and receive information about individual cells. The widget maintains an internal array of VListLine entries, one for each cell in the list. Each record has as many VListLine entries as there are fields in the list. This field count is specified by the VListNfieldCount resource. typedef struct { /* common fields - all field types */ int mask; /* mask flags */ Opaque closure; /* cell's Opaque closure (ID) */ int select; /* cell is selected (1/0) */ int sensitive; /* cell can be selected (1/0) */ int stippled; /* cell is stippled (1/0) */ int coloridx; /* cell's foreground color index */ int background; /* cell's background color index */ int type; /* cell type (VListLineType~) */ /* VListLineTypeText only */ char *textP; /* pointer to cell's ASCIZ text */ int fontidx; /* cell's font index */ VListSegment *segmentsP; /* array of VListSegment structures */ int segmentCount; /* count of VListSegment entries */ /* VListLineTypeHist only */ int highValue; /* histogram high-end value */ int lowValue; /* histogram low-end value */ VListBar *barsP; /* array of VListBar structures */ int barCount; /* count of VListBar entries */ /* VListLineTypeIcon only */ Pixmap icon; /* icon pixmap */ } VListLine; VListLine.mask is used by the VListAddLine and VListChangeLine routines to determine which values are to be taken from the VListLine structure. Each field in the VListLine structure has a corresponding mask bit. When calling VListAddLine to add a record, you must pass an array of VListLine entries, one for each cell in the record. The mask value indicates whether a particular field in the VListLine structure has been supplied by the application. If the corresponding mask bit is set, the value is taken from the VListLine structure, otherwise the widget supplies a default. When calling VListChangeLine to change a cell, the mask value indicates which aspects of the cell should be changed. If the corresponding mask bit is set, the cell is changed to the value specified in the VListLine structure. Otherwise, that aspect of the cell is not changed. This mask supports upward compatible extensions to the VListLine structure and a uniform mechanism for defaulting. Defined mask values and their corresonding fields are: VListLineClosureMask - closure VListLineTextMask - textP VListLineFontidxMask - fontidx VListLineColoridxMask - coloridx VListLineBackgroundMask - background VListLineSelectMask - select VListLineSensitiveMask - sensitive VListLineTypeMask - type VListLineSegmentsMask - segmentsP and segmentCount VListLineStippledMask - stippled VListLineHighValueMask - highValue VListLineLowValueMask - lowValue VListLineBarsMask - barsP and barCount VListLineIconMask - icon [VListLineClosureMask] VListLine.closure specifies the cell's non-zero Opaque closure value (ID number). This value may be assigned by the application, or the application may choose to let the VList widget pick unique closure values. Closure values can be used for any purpose by the application. They are typically used to point to application-private, per-cell data structures. A closure value identifies a particular cell, both when the widget communicates with the application (through a callback) and when the application communicates with the widget (through a special routine). The application can change a cell's closure value at any time by calling VListChangeLine. [VListLineTextMask] Applies to text fields only. VListLine.textP contains the address of an ASCIZ text string. This string will be displayed in the VList widget's window when the cell is visible. The application can change a cell's text at any time. When the application provides a string, the widget always makes a copy of the string. For more complex text, including multi-line strings, see the VListLineSegmentMask options. [VListLineFontidxMask] Applies to text fields only. VListLine.fontidx contains the cell's font index. The widget uses this value to index into the font table to find the font in which the cell's text is to be displayed when the cell is visible. The application can change a cell's font at any time by calling VListChangeLine. Individual string segments can override the cell's default font index. [VListLineColoridxMask] VListLine.coloridx contains the cell's foreground color. If a color list was supplied through the VListNcolorList resource, then the widget uses the coloridx value to index into the color list to find the color in which the cell is to be displayed when it is visible. If no color list was supplied, then the widget uses the coloridx value directly as the pixel value of the line's color. The application can change a cell's color at any time by calling VListChangeLine. Individual string segments can override the cell's default color. By default, the cell contents are drawn using the widget's default foreground color as supplied by the VListNforeground resource. [VListLineBackgroundMask] VListLine.background contains the cell's background color. If a color list was supplied through the VListNcolorList resource, the widget uses the background value to index into the color list to get an actual pixel value. As a special case, if a background value is (-1) is supplied, the color table is not used and the widget's default background color as supplied by the XtNbackground resource is used. If no color list was supplied, then the widget uses the supplied background value directly as a pixel value. The application can change a cell's background color at any time by calling VListChangeLine. If no background value is supplied for a new cell, the default background color as supplied by the XtNbackground resource is used (whether a color list was supplied or not). [VListLineSelectMask] VListLine.select contains the cell's select state. If zero (0), the cell is not selected. If non-zero, the cell is selected. Selected cells are drawn in a highlighted, reverse-video mode. [VListLineSensitiveMask] VListLine.sensitive contains the cell's sensitivity state. If zero (0), the cell cannot be selected by the user. It can, however, be selected by the application. If non-zero, the cell can be selected by the user. [VListLineStippledMask] VListLine.stippled contains the cell's stipple state. If zero (0), the cell will be drawn normally. If non-zero, the cell will be drawn in a stippled mode and will appear grayed-out. The application can override the stippled state of individual string segments through the VListLine segment list. [VListLineTypeMask] VListLine.type contains the cell's type. By default, the type is inherited from the field containing this cell. Possible values are: VListLineTypeText VListLineTypeHist VListLineTypeIcon [VListLineSegmentsMask] Applies to text fields only. VListLine.segmentsP and VListLine.segmentCount describe the optional segment list for the cell. If VListLine.segmentCount is zero, the cell is not segmented and the cell's text is rendered in the font and color specified by the VListLine.coloridx and VListLine.fontidx fields. Each segment represents a text string or an icon, based on the segment type. Segmented strings can also be used to format the cell into multiple lines. If VListLine.segmentCount is non-zero, it specified the number of entries in an array of VListSegment structures pointed to by VListLine.segmentsP. In this case, the cell is segmented and is rendered segment-by-segment according to the entries in the VListSegment array. When the cell is segmented, the segment list controls the drawing of the cell. There is no requirement that all the text in the string (pointed to by VListLine.textP) be included in a string segment, and portions that are omitted will not be drawn. Segmented strings can be used to subset and reorder text as well as to change colors, fonts and stippled modes. Each VListSegment entry has the following definition: typedef struct { int mask; /* mask flags */ int type; /* segment type (VlistSegmentType~) */ int coloridx; /* segment's color index or pixel value */ int stippled; /* segment's stipple state (1/0) */ /* VListSegmentTypeText only */ int textPosition; /* zero-based offset into VListLine.textP */ int textStrlen; /* number of bytes in text segment */ int fontidx; /* segment's font index */ /* VListSegmentTypeIcon only */ Pixmap icon; /* icon pixmap */ } VListSegment; VListSegment.mask indicates which cell attributes are to overridden for this segment. It is not necessary to override any attributes. Attributes that are not overridden in the VListSegment entry inherit the values specified by the VListLine entry or widget default values. Allowable mask values are: VListSegmentColoridxMask - VListSegment.coloridx is specified VListSegmentStippledMask - VListSegment.stippled is specified VListSegmentTypeMask - VListSegment.type is specified VListSegmentFontidxMask - VListSegment.fontidx is specified VListSegmentNewLineMask - next segment starts on a new line VListSegmentIconMask - VListSegment.icon is specified [VListSegmentColoridxMask] VListSegment.coloridx specifies a color index for the segment. [VListSegmentStippledMask] VListSegment.stippled specifies a stipple state for the segment. [VListSegmentTypeMask] VListSegment.type specifies the type of segment. Allowable values are: VListSegmentTypeText (default) - segment is a text string VListSegmentTypeIcon - segment is an icon pixmap If VListSegment.type is VListSegmentTypeText, then: VListSegment.textPosition specifies a zero-based offset from the beginning of the string pointed to by VListLine.textP. This indicates the start of the string segment. VListSegment.textStrlen specifies the length, in bytes, of the string segment. [VListSegmentFontidxMask] (VListSegmentTypeText only) VListSegment.fontidx specifies a font index for the string segment. [VListSegmentIconMask] VListSegment.icon specifies an icon pixmap to be drawn in this segment. By default, the icon pixmap in the VListLine entry is used. [VListSegmentNewLineMask] When set, this mask bit indicates that the segment is the final segment in the line. If there are any more segments following this one in the segment list, a new line will be started when the text is rendered into the cell's display region. [VListIconMask] Applies to icon fields only. VListLine.icon specifies the Pixmap ID of the icon to be displayed in the field. If zero (0) is passed, or if this value is defaulted, no icon is shown in this cell. [VListHighValueMask] Applies to histogram fields only. Ignored if VListBarsMask is set. VListLine.highValue specifies the value corresponding to the high end of the histogram bar. [VListLowValueMask] Applies to histogram fields only. Ignored if VListBarsMask is set. VListLine.lowValue specifies the value corresponding to the low end of the histogram bar. [VListBarsMask] Applies to histogram fields only. VListLine.barsP and VListLine.barCount specify the address and count of an array of VListBar entries, each of which describes a single segment of the histogram bar for this line entry. This array describes a segmented histogram. Segments are drawn in the order they appear in this list. Overlapping segments can be specified. Each VListBar has the following definition: typedef struct { int mask; /* mask flags */ int lowValue; /* bar low-end value */ int highValue; /* bar high-end value */ int coloridx; /* bar color index or pixel value */ int stippled; /* bar is stippled (1/0) */ } VListBar; VListBar.mask indicates which histogram attributes are to overridden for this bar segment. Attributes which are not overridden in the VListBar entry have values specified by the VListLine entry or widget default values. Allowable mask values are: Mask flag values for VListBar.mask and the corresponding fields are: VListBarLowValueMask - lowValue VListBarHighValueMask - highValue VListBarColoridxMask - coloridx VListBarStippledMask - stippled [VListBarLowValueMask] VListBar.lowValue specifies the low value for the histogram bar segment. This value should always be supplied. [VListBarHighValueMask] VListBar.highValue specifies the high value for the histogram bar segment. This value should always be supplied. [VListBarColoridxMask] VListBar.coloridx specifies a color index for the histogram bar segment. See the discussion of the VListField.coloridx field for details. The value of the VListLine.coloridx field (or its default) is used if VListBar.coloridx is not supplied. [VListBarStippledMask] VListBar.stippled specifies a stipple state for the histogram bar segment. The value of the VListLine.stippled field (or its default) is used if VListBar.stippled is not supplied. +-----------+ | Callbacks | +-----------+ The VList widget supports four application callback resources: VListNselectCallback - single-click selection VListNselectConfirmCallback - double-click selection VListNdragArmCallback - starting drag-and-drop VListNdragDropCallback - completing drag-and-drop +---------- | VListNselectCallback (reason VListCRSelect) VListNselectConfirmCallback (reason VListCRSelectConfirm) The VListNselectCallback is called whenever the user completes a select action on the list. The VListNselectConfirmCallback is called whenever the user completes a double-click action on the list. The same callback structure is used for both callbacks. typedef struct { int reason; /* VListCRSelect(Confirm) */ XEvent *event; /* triggering event */ int field; /* upclick logical field num */ int row; /* upclick logical row num */ VListLine vLine; /* upclick cell info */ VListSelectChange *selectChangesP; /* old and new select states */ int lineCount; /* total cell count */ int selectionCount; /* (new) number of selected lines */ } VListSelectCallbackStruct; VListSelectCallbackStruct.reason contains VListCRSelect or VListCRSelectConfirm, depending on which callback was made. VListSelectCallbackStruct.event contains the address of the XEvent that triggered the callback. VListSelectCallbackStruct.field and VListSelectCallbackStruct.row contain the zero-based field and row numbers of the cell over which the mouse button was released. This cell may not actually be selected, depending on the values of VListNselectStyle and the sensitivity of the cell itself. If the mouse button was released where there was no cell, VListSelectCallbackStruct.vLine.closure contains a zero. Otherwise, VListSelectCallbackStruct.vLine contains a copy of the VListLine entry for the cell over which the mouse button was released. VListSelectCallbackStruct.vLine.textP contains a pointer to the actual text used for the string - do not modify or XtFree it. If the select reason is VListCRSelect, then VListSelectCallbackStruct.selectChangesP contains a pointer to an array of VListSelectChange structures, one for each cell in the list. All cells are included in this list regardless of their selection state. typedef struct { Opaque closure; /* cell closure */ int oldSelect; /* cell was previously selected */ int newSelect; /* cell is now selected */ } VListSelectChange; VListSelectCallbackStruct.lineCount contains the total number of cells in the VList widget. This includes all cells, selected or not. VListSelectCallbackStruct.selectionCount contains the number of cells that are selected when the callback is made. This value is provided for the convenience of the application and can also be determined by looping through the VListSelectChange array counting all the newSelect flags that are set. | +---------- +---------- | VListNdragArmCallback (reason VListCRDragArm) The VListNdragArmCallback is called whenever the user attempts to start dragging an object in the list. The VListNdragArmCallback is passed the following callback structure: typedef struct { int reason; /* VListCRDragArm */ XEvent *event; /* triggering XButtonEvent */ int field; /* source field num */ int row; /* source row num */ VListLine vLine; /* source cell info */ } VListDragArmCallbackStruct; VListDragArmCallbackStruct.reason contains VListCRDragArm. VListDragArmCallbackStruct.event contains the address of the XEvent that triggered the callback. This is always an XButtonEvent (ButtonPress). VListDragArmCallbackStruct.field and VListDragArmCallbackStruct.row contain the zero-based field and row numbers of the cell over which the drag mouse button was pressed. If the drag mouse button was pressed where there was no cell, VListDragArmCallbackStruct.vLine.closure contains a zero. Otherwise, VListDragArmCallbackStruct.vLine contains a copy of the VListLine entry for the cell over which the mouse button was pressed. Within the VListNdragArmCallback, the application may: (1) reject the drag operation by setting the VList widget's VListNdragWidget resource to zero, or (2) accept the drag operation. This may involve setting the drag label widget's string or pixmap to show the user which entry was picked up. The application must make sure that the VListNdragWidget resource is set to the widget ID of the drag widget before returning from the callback. | +---------- +---------- | VListNdragDropCallback (reason VListCRDragDrop) The VListNdragDropCallback is called whenever the user completes a drag-and-drop operation. The VListNdragDropCallback is passed the following callback structure: typedef struct { int reason; /* VListCRDragArm */ XEvent *event; /* triggering XButtonEvent */ int field; /* source field num */ int row; /* source row num */ VListLine vLine; /* source cell info */ int dropWindow; /* target window on which entry was dropped */ int dropX, dropY; /* coordinates of drop within target window */ Widget dropWidget; /* target widget on which entry was dropped */ int dropWidgetIsVList; /* target widget is a VList widget (1/0) */ int dropField; /* target VList field */ int dropRow; /* target VList row */ VListLine dropVLine; /* target VList line info (closure may be 0) */ int dropVListFieldCount; /* number of fields in target widget */ int dropVListRowCount; /* number of rows in target widget */ } VListDragDropCallbackStruct; VListDragDropCallbackStruct.reason contains VListCRDragDrop. VListDragDropCallbackStruct.event contains the address of the XEvent that triggered the callback. This is always an XButtonEvent (ButtonRelease). The field, row and vLine fields have the same values as the corresponding fields in the VListDragArmCallbackStruct passed to the VListNdragArmCallback. VListDragDropCallbackStruct.dropWindow contains the window ID of the window over which the user dropped the object. This window may or may not belong to the application. VListDragDropCallbackStruct.dropX and dropY contains the x,y event coordinates within the dropWindow where the user dropped the object. VListDragDropCallbackStruct.dropWidget contains the widget ID of the widget over which the user dropped the object. If the object was dropped outside of the application window boundaries, the widget ID of the parent of the drag widget is returned in this field. VListDragDropCallbackStruct.dropWidgetIsVList contains a 1 or a 0 depending on whether the dropWidget is an instance of a VList widget. VListDragDropCallbackStruct.dropField and dropRow contain the field and row of the object in the TARGET VList widget over which the object was dropped. These fields are meaningless if the dropWidgetIsVList flag is false (0). If the object was dropped there was no VList cell, VListDragDropCallbackStruct.dropVLine.closure contains a zero. Otherwise, VListDragDropCallbackStruct.dropVLine contains a copy of the VListLine entry for the cell over which the object was dropped. This is a cell in the TARGET VList widget. VListDragDropCallbackStruct.dropVListFieldCount and dropVListRowCount contain the number of fields and rows in the TARGET VList widget. | +---------- +------------------+ | Special Routines | +------------------+ The VList widget provides special routines that allow the application to manipulate the list contents. The following special routines change the list contents: VListAddLine - add a single record to the list VListChangeLine - change a single cell in the list VListChangeCell - change a single cell in the list VListMoveLine - move a single record up or down one slot VListRemoveLine - remove a single record from the list VListRemoveRow - remove a single record from the list VListRemoveAllLines - empty the list VListSelectAll - select or deselect all cells in the list The difference between VListChangeLine and VListChangeCell is this: VListChangeLine accepts the closure value of the target cell and does a sequential search through the widget's list to find the target line that has that closure value. VListChangeCell accepts the field and row numbers of the target cell and avoids the search. This call is more efficient and may be used if the application knows the field and row number of the target cell. The following convenience routines call VListChangeLine to change one cell attribute at a time. If more than one attribute is being changed, it is more efficient to make a single call to VListChangeLine. VListChangeLineBars - change a cell's histogram bar segments VListChangeLineClosure - change a cell's closure value VListChangeLineColoridx - change a cell's foreground color index VListChangeLineBackground - change a cell's background color index VListChangeLinePixel - change a cell's pixel color value VListChangeLineFontidx - change a cell's font index VListChangeLineIcon - change a cell's icon pixmap VListChangeLineSegments - change a cell's segment list VListChangeLineSelect - change a cell's selection state VListChangeLineSensitive - change a cell's sensitivity VListChangeLineStippled - change a cell's stipple state VListChangeLineText - change a cell's text VListChangeLineValues - change a cell's low and high values For each VListChangeLine~ convenience routine, there is a similar VListChangeCell~ routine that calls VListChangeCell. The following special routines control VList window updates: VListStartBatchUpdate - start batch update, suppress redraws VListEndBatchUpdate - end batch update, redraw the window The following special routine controls the window scroll position: VListMakeLineVisible - scroll the window under application control VListSetAutoScrollPosition - set autoscroll strength The following routines return a cell's closure value based on its logical or physical position: VListFieldRowToLine - translate logical coordinates to closure VListXYToLine - translate event coordinates to closure The following routines return the closure values for selected cells: VListGetFirstSelectedLine - return closure of first selected cell VListGetAllSelectedLines - return a list of all selected cells The following routines return information about cells in the list: VListGetLineCount - return number of cells in the list VListGetAllLines - return closures of all cells in the list VListGetFieldLines - return closures of all cells in a field VListGetLineInfo - return information about a specified cell The following routine returns the optimal width needed to display the entire contents of the list without a horizontal scroll bar: VListComputePreferredWidth - return optimal width ---------------------------------------------------------------------- To add a new record to the list, call VListAddLine. This routine adds a single record at any row in the list. Records following the new record are shifted towards the end of the list. Unless batch updating is in effect, the widget updates its window (if necessary) to show the change. Opaque VListAddLine(w, vLinesP, row) Widget w; /* VList widget */ VListLine *vLinesP; /* Array of VListLine entries */ int row; /* New record's ordinal position */ The vLinesP argument is the address of an array of VListLine entries describing the new record. There must be as many entries in this array as there are fields in the list. (This value is determined by the VListNfieldCount resource, and defaults to 1.) The row argument is the zero-based position in the list for the new record. If the specified row is less than zero or greater than the number of records already in the list, then the new record is added to the end of the list. Otherwise, the new record is placed in the specified position. For convenience, the following special values for the row argument are defined: VListAddAtTop /* add to beginning of list */ VListAddAtBottom /* add to end of list */ VListAddLine's Opaque return value is the closure value of the first cell in the new record. If the application supplied a closure value in the first VListLine entry, that same value is returned by the routine. Otherwise, the widget uses an incrementing counter to allocate a non-zero closure value to the new cell and returns that value. The widget will not allow the application to assign a zero closure value to a cell. Instead, the widget will use its incrementing counter value. Examples of use: static void AddSimpleRecord(w, textP) Widget w; char *textP; { VListLine vLine; /* only one field */ vLine.mask = VListLineTextMask; /* only specify text */ vLine.textP = textP; /* ... */ VListAddLine (w, &vLine, VListAddAtBottom); } static Opaque AddRecordeWithThreeFields(w, text0P, text1P, text2P) Widget w; /* VList widget */ char *text0P, *text1P, *text2P; /* ASCIZ text for each field */ { VListLine vLineA[3]; /* there are three fields */ /* Use the VListLine array to hold the new record's description. */ vLineA[0].mask = VListLineTextMask; vLineA[0].textP = text0P; vLineA[1].mask = VListLineTextMask; vLineA[1].textP = text1P; vLineA[2].mask = VListLineTextMask; vLineA[2].textP = text2P; /* Add the record to the end of the list and return its closure. */ return (VListAddLine (vListW, vLineA, VListAddAtBottom)); } ---------------------------------------------------------------------- To change the attributes of a single cell, call VListChangeLine or VListChangeCell. These routine can change any or all of the attributes of any one cell. Unless batch updating is in effect, the widget updates its window (if necessary) to show the change. void VListChangeLine(w, closure, vLineP) Widget w; /* VList widget */ Opaque closure; /* closure value (ID) of target cell */ VListLine *vLineP; /* new cell attributes */ void VListChangeCell(w, field, row, vLineP) Widget w; /* VList widget */ int field, row; /* target cell's field and row number */ VListLine *vLineP; /* new cell attributes */ The closure argument identifies the cell to be changed. The first cell in the list that has this closure value is the target of the operation. If no cell is found with this closure value, the call is ignored. The field and row arguments identify the target cell by its position in the list. These values are the zero-based field and row of the target cell. If the field or row is out-of-bounds, the call is ignored. The vLineP argument is the address of a VListLine structure containing new attribute values for the target cell. Attributes whose corresponding mask flag is set are changed to the new values specified in the structure; the other attributes are not changed. Example of use: ChangeTextAndColor(w, closure, textP, coloridx) Widget w; /* VList widget */ Opaque closure; /* cell's closure (ID) value */ char *textP; /* new ASCIZ text string */ int coloridx; /* new color index */ { VListLine vLine; vLine.mask = (VListLineTextMask | VListLineColoridxMask); vLine.textP = textP; vLine.coloridx = coloridx; VListChangeLine (w, closure, &vLine); } ---------------------------------------------------------------------- To make it easier to change a single attribute of a single cell, the following convenience routines are provided. These routines call VListChangeLine or VListChangeCell. When changing more than one attribute, it is more efficient to make a single call to VListChangeLine or VListChangeCell than to call several of these routines since the VList widget can better optimize the screen update. void VListChangeLineBars(w, closure, newBarsP, newBarCount) Widget w; /* VList widget */ Opaque closure; /* closure of cell to be changed */ VListBar *newBarsP; /* address of new VListBar array */ int newBarCount; /* count of new VListBar array */ void VListChangeLineClosure(w, closure, newClosure) Widget w; /* VList widget */ Opaque closure; /* closure of cell to be changed */ Opaque newClosure; /* new closure value for cell */ void VListChangeLineColoridx(w, closure, newColoridx) Widget w; /* VList widget */ Opaque closure; /* closure of cell to be changed */ int newColoridx; /* new foreground color index for cell */ void VListChangeLineBackground(w, closure, newBackground) Widget w; /* VList widget */ Opaque closure; /* closure of cell to be changed */ int newBackground; /* new background color index for cell */ void VListChangeLineFontidx(w, closure, newFontidx) Widget w; /* VList widget */ Opaque closure; /* closure of cell to be changed */ int newFontidx; /* new font index for cell */ void VListChangeLineIcon(w, closure, newIcon) Widget w; /* VList widget */ Opaque closure; /* closure of cell to be changed */ Pixmap icon; /* new icon Pixmap ID for cell (or zero) */ void VListChangeLineSegments(w, closure, newSegmentsP, newSegmentCount) Widget w; /* VList widget */ Opaque closure; /* closure of cell to be changed */ VListSegment *newSegmentsP; /* address of new segment list */ int newSegmentCount; /* count of new segment list (may be zero) */ void VListChangeLineSelect(w, closure, newSelect) Widget w; /* VList widget */ Opaque closure; /* closure of cell to be changed */ int newSelect; /* new selection state for cell (1/0) */ void VListChangeLineSensitive(w, closure, newSensitive) Widget w; /* VList widget */ Opaque closure; /* closure of cell to be changed */ int newSensitive; /* new sensitivity for cell (1/0) */ void VListChangeLineStippled(w, closure, newStippled) Widget w; /* VList widget */ Opaque closure; /* closure of cell to be changed */ int newStippled; /* new stipple state for cell (1/0) */ void VListChangeLineText(w, closure, newTextP) Widget w; /* VList widget */ Opaque closure; /* closure of cell to be changed */ char *newTextP; /* new ASCIZ text for cell */ void VListChangeLineValues(w, closure, newLowValue, newHighValue) Widget w; /* VList widget */ Opaque closure; /* closure of cell to be changed */ int newLowValue; /* new low histogram bar value */ int newHighValue; /* new high histogram bar value */ void VListChangeLineBars(w, field, row, newBarsP, newBarCount) Widget w; /* VList widget */ int field, row; /* field, row of cell to be changed */ VListBar *newBarsP; /* address of new VListBar array */ int newBarCount; /* count of new VListBar array */ void VListChangeLineClosure(w, field, row, newClosure) Widget w; /* VList widget */ int field, row; /* field, row of cell to be changed */ Opaque newClosure; /* new closure value for cell */ void VListChangeLineColoridx(w, field, row, newColoridx) Widget w; /* VList widget */ int field, row; /* field, row of cell to be changed */ int newColoridx; /* new foreground color index for cell */ void VListChangeLineBackground(w, field, row, newBackground) Widget w; /* VList widget */ int field, row; /* field, row of cell to be changed */ int newBackground; /* new background color index for cell */ void VListChangeLineFontidx(w, field, row, newFontidx) Widget w; /* VList widget */ int field, row; /* field, row of cell to be changed */ int newFontidx; /* new font index for cell */ void VListChangeLineIcon(w, field, row, newIcon) Widget w; /* VList widget */ int field, row; /* field, row of cell to be changed */ Pixmap icon; /* new icon Pixmap ID for cell (or zero) */ void VListChangeLineSegments(w, field, row, newSegmentsP, newSegmentCount) Widget w; /* VList widget */ int field, row; /* field, row of cell to be changed */ VListSegment *newSegmentsP; /* address of new segment list */ int newSegmentCount; /* count of new segment list (may be zero) */ void VListChangeLineSelect(w, field, row, newSelect) Widget w; /* VList widget */ int field, row; /* field, row of cell to be changed */ int newSelect; /* new selection state for cell (1/0) */ void VListChangeLineSensitive(w, field, row, newSensitive) Widget w; /* VList widget */ int field, row; /* field, row of cell to be changed */ int newSensitive; /* new sensitivity for cell (1/0) */ void VListChangeLineStippled(w, field, row, newStippled) Widget w; /* VList widget */ int field, row; /* field, row of cell to be changed */ int newStippled; /* new stipple state for cell (1/0) */ void VListChangeLineText(w, field, row, newTextP) Widget w; /* VList widget */ int field, row; /* field, row of cell to be changed */ char *newTextP; /* new ASCIZ text for cell */ void VListChangeLineValues(w, field, row, newLowValue, newHighValue) Widget w; /* VList widget */ int field, row; /* field, row of cell to be changed */ int newLowValue; /* new low histogram bar value */ int newHighValue; /* new high histogram bar value */ ---------------------------------------------------------------------- To change the position of a record in the list, call VListMoveLine. This routine switches the position of the target record with the record above or below it in the list. Unless batch updating is in effect, the widget updates its window (if necessary) to show the change. void VListMoveLine(w, closure, direction) Widget w; /* VList widget */ Opaque closure; /* closure of any cell in target record */ int direction; /* direction in which record should be moved */ The closure argument identifies the record to be moved. The first record in the list containing a cell that has this closure value is the target of the operation. If no cell is found with this closure value, the call is ignored. The direction argument specifies the direction in which the record should be moved. The following values are allowed: VListMoveLineUp - move one row closer to the beginning VListMoveLineDown - move one row closer to the end ---------------------------------------------------------------------- To remove a record from the list, call VListRemoveLine or VListRemoveRow. These routines remove any single record from the list. Unless batch updating is in effect, the widget updates its window (if necessary) to show the change. void VListRemoveLine(w, closure) Widget w; /* VList widget */ Opaque closure; /* closure of any cell in target record */ The closure argument identifies the record to be removed. The first record in the list containing a cell that has this closure value is the target of the operation. If no cell is found with this closure value, the call is ignored. void VListRemoveRow(w, row) Widget w; /* VList widget */ int row; /* zero-based row number of target record */ The row argument specifies the zero-based position in the list of the record to be removed. If no record is found with this row number, the call is ignored. ---------------------------------------------------------------------- To efficiently empty the list, call VListRemoveAllLines. Unless batch updating is in effect, the widget updates its window (if necessary) to show the empty list. void VListRemoveAllLines(w) Widget w; /* VList widget */ ---------------------------------------------------------------------- To select or deselect all the cells in the list, call VListSelectAll. Calling this routine does not cause the selectCallback to be called. (Use VListChangeLineSelect to select or deselect individual cells.) void VListSelectAll(w, select) Widget w; /* VList widget */ int select; /* select (1) or deselect (0) */ The select argument indicates whether the routine should select (1) or deselect (0) all the cells in the list. ---------------------------------------------------------------------- To efficiently make multiple, related changes to the VList widget, call VListStartBatchUpdate and VListEndBatchUpdate. Normally, when a change is made to the widget's list (add, remove, change, move), the widget's window is immediately updated to reflect the change. This can be desirable when individual changes are made, but when the list is completely rebuilt or massively modified, it may be better to wait and then repaint the entire window. While the widget can often detect the beginning of a group of updates and will wait until they are complete before repainting the window, the application can sometimes assist the widget by using these routines. A call to VListStartBatchUpdate puts the widget into a state in which changes to its list will be made internally but the window will not be updated to reflect the changes. When the final VListEndBatchUpdate call is made, the widget repaints its entire window. These calls can be nested, and only when the nesting level reaches zero will the window be repainted. void VListStartBatchUpdate(w) Widget w; /* VList widget */ void VListEndBatchUpdate(w) Widget w; /* VList widget */ ---------------------------------------------------------------------- To ensure that a particular cell is visible in the widget's window, call VListMakeLineVisible. This routine allows the application to scroll the VList window contents to make sure that important information is visible. void VListMakeLineVisible(w, closure, visible) Widget w; /* VList widget */ Opaque closure; /* closure value (ID) of target cell */ int visible; /* visibility option (see below) */ The closure argument identifies the cell to be made visible. The first cell in the list that has this closure value is the target of the operation. If no cell is found with this closure value, the call is ignored. The visible argument specifies how the cell should be made visible. The following values are allowed: VListVisibleInWindow - mimimum scrolling necessary to make visible VListVisibleAtTop - position cell at top of window VListVisibleAtBottom - position cell at bottom of window VListVisibleAtLeft - position cell at left edge of window VListVisibleAtRight - position cell at right edge of window VListVisibleAtTopLeft - position at upper left corner of window VListVisibleAtTopRight - position at upper right corner of window VListVisibleAtBottomLeft - position at bottom left corner of window VListVisibleAtBottomRight - position at bottom right corner of window ---------------------------------------------------------------------- To start and stop auto-scrolling of the VList window from within the application program, call VListSetAutoScrollPosition. This routine takes an x,y position (relative to the VList widget's window) and does auto-scrolling as though the user had grabbed the list with the mouse button. void VListSetAutoScrollPosition(w, x, y) Widget w; /* VList widget */ int x, y; /* event position */ If x and y are both zero, auto-scrolling will be stopped. If the specified position is outside the boundaries of the VList widget's window, continuous auto-scrolling is started and will continue until this routine is called again with different event coordinates. ---------------------------------------------------------------------- To retrieve the closure (ID) value for a cell given that cell's field and row numbers, call VListFieldRowToLine. This routine takes a field and row number and returns the closure value for the cell at that logical position in the list. Opaque VListFieldRowToLine(w, field, row) Widget w; /* VList widget */ int field; /* zero-based field number */ int row; /* zero-based row number */ The field argument specifies the zero-based field number of the target cell. If the field number is negative or is greater than or equal to the number of fields in the list, then this routine returns zero (0). The row argument specifies the zero-based row number of the target cell. If the row number is negative or is greater than or equal to the number of rows in the list, then this routine returns zero (0). If both the field and row arguments are in-range, then the value of the closure attribute of the target cell is returned. Example of use: static void RemoveRowFromList(w, row) Widget w; /* VList widget */ int row; /* row containing record to be removed */ { VListRemoveLine (w, VListFieldRowToLine (w, 0, row)); } ---------------------------------------------------------------------- To retrieve the closure (ID) value for a cell given a physical position in the VList window, call VListXYToLine. This routine takes an pair of (x,y) coordinates and returns the closure value for the cell occupying the physical cell containing those coordinates. Opaque VListXYToLine(w, x, y) Widget w; /* VList widget */ int x, y; /* window coordinates */ The x and y arguments specify a position relative to the VList window. The application will often have received these coordinates in a ButtonPress event and will use them to determine context for a pop-up menu. If there is a cell at the specified coordinates, it is the target of this operation. If there is no target cell, then this routine returns zero (0). If the widget select unit is VListSelectUnitRow, then the closure of the first cell in the row containing the target cell is returned, otherwise the closure of the target cell itself is returned. Example of use: /* Assume that this routine has been enabled as an event handler for * Button2Press events. When MB2 is pressed over a line, that line * should be selected and a popup menu activated. */ static void ButtonPressHandler(w, popupMenuW, eventP) Widget w, popupMenuW; XButtonEvent *eventP; { Opaque lineClosure; /* closure for target line */ ... /* Determine the closure of the cell we are over. If we are not over * any cell, simply return. Otherwise, select it. */ lineClosure = VListXYToLine (vListW, eventP->x, eventP->y); if (!lineClosure) return; VListChangeLineSelect (w, lineClosure, 1); /* Pop up the menu. */ XmMenuPosition (popupMenuW, eventP); XtManageChild (popupMenuW); } ---------------------------------------------------------------------- To get the closure value of the first cell that is selected, call VListGetFirstSelectedLine. Opaque VListGetFirstSelectedLine(w) Widget w; /* VList widget */ This routine returns the closure value of the first cell in the list that is selected. If there are no selected cells, this routine returns zero (0). ---------------------------------------------------------------------- To get the closure values of all the cells that are selected, call VListGetAllSelectedLines. This routine allocates VM for a list of closure values and returns the list and its count. int VListGetAllSelectedLines(w, closurePP) Widget w; /* VList widget */ Opaque **closurePP; /* pointer to receive address of list */ The closurePP argument is the address of an optional pointer variable that will receive the address of the closure list allocated by the widget on this call. The application must free this closure list by calling XtFree. Even if there are no selected cells, an empty closure list is allocated and must be freed. If the closurePP argument is not supplied (is zero), no list is allocated. If the widget's select unit is VListSelectUnitRow, then only the first cell in each record is considered to be selected, even though all the cells in the record are highlighted. If the select unit is VListSelectUnitField, then each cell can be individually selected. The number of selected cells is returned as the value of the routine. Example of use: static void RemoveAllSelectedRecords(w) Widget w; /* VList widget */ { Opaque *lineClosuresP; /* to receive address of list */ int selectionCnt, i; /* Get the count and list of closures for selected cells. */ selectionCnt = VListGetAllSelectedLines (w, &lineClosuresP); /* Loop through the closure list, removing each selected record. */ for (i = 0; i < selectionCnt; i++) VListRemoveLine (w, lineClosuresP[i]); /* Free the closure list, even if it was empty. */ XtFree (lineClosuresP); } ---------------------------------------------------------------------- To determine the number of cells in the list, call VListGetLineCount. This routine returns the number of cells currently in the list. To determine how many rows (or lines) are in the list, the application must divide the cell count by the number of fields in the list as specified by the VListNfieldCount resource. int VListGetLineCount(w) Widget w; /* VList widget */ ---------------------------------------------------------------------- To get the closure values of all the cells in the list, call VListGetAllLines. This routine allocates VM for a list of closure values and returns the list and its count. int VListGetAllLines(w, closurePP) Widget w; /* VList widget */ Opaque **closurePP; /* pointer to receive address of list */ The closurePP argument is the address of a pointer variable that will receive the address of the closure list allocated by the widget on this call. The application must free this closure list by calling XtFree. Even if there are no cells in the list, an empty closure list is allocated and must be freed. The number of cells in the list is returned as the value of the routine. Example of use: static void StippleAllCells(w, stippled) Widget w; /* VList widget */ int stippled; /* new stippled value (1/0) */ { Opaque *lineClosuresP; /* to receive address of list */ int lineCnt, i; /* Get the count and list of closures for all cells. */ lineCnt = VListGetAllLines (w, &lineClosuresP); /* Loop through the closure list, changing each cell's stipple value. */ for (i = 0; i < lineCnt; i++) VListChangeLineStippled (w, lineClosuresP[i], stippled); /* Free the closure list, even if it was empty. */ XtFree (lineClosuresP); } ---------------------------------------------------------------------- To get the closure values of all the cells in a single field of the list, call VListGetFieldLines. This routine allocates VM for a list of closure values and returns the list and its count. int VListGetFieldLines(w, field, closurePP) Widget w; /* VList widget */ int field; /* zero-based field number */ Opaque **closurePP; /* pointer to receive address of list */ This routine is similar to VListGetAllLines except that only those cells that are in the specified field are included. The closurePP argument is the address of a pointer variable that will receive the address of the closure list allocated by the widget on this call. The application must free this closure list by calling XtFree. Even if there are no cells in the list, an empty closure list is allocated and must be freed. Since each record has one cell for each field in the list, this routine returns the number of records. Example of use: static void StippleAllCellsInField(w, stippled, field) Widget w; /* VList widget */ int stippled; /* new stippled value (1/0) */ int field; /* field to be stippled */ { Opaque *lineClosuresP; /* to receive address of list */ int lineCnt, i; /* Get the count and list of closures for all cells in this field. */ lineCnt = VListGetFieldLines (w, field, &lineClosuresP); /* Loop through the closure list, changing each cell's stipple value. */ for (i = 0; i < lineCnt; i++) VListChangeLineStippled (w, lineClosuresP[i], stippled); /* Free the closure list, even if it was empty. */ XtFree (lineClosuresP); } ---------------------------------------------------------------------- To retrieve the attributes of any cell given its closure value, call VListGetLineInfo. int VListGetLineInfo(w, closure, vLineP, fieldP, rowP) Widget w; /* VList widget */ Opaque closure; /* cell's closure (ID) value */ VListLine *vLineP; /* VListLine structure to receive attributes */ int *fieldP; /* integer to receive cell's field number */ int *rowP; /* integer to receive cell's row number */ The closure argument identifies the cell whose information is to be returned. The first cell in the list that has this closure value is the target of the operation. If no cell is found with the specified closure value, the call is ignored and the routine returns zero (0). In this case, none of the other return variables are affected. If there is a target cell then this routine returns (1). The vLineP argument is the address of a VListLine structure allocated by the caller to receive the attribute values for the target cell. If a zero (0) is supplied as this argument's value, the argument is ignored. After calling this routine, the VListLine structure contains a copy of the values of all the attributes for the cell. The textP field in the VListLine structure contains a pointer to the actual text string for the cell. Do not XtFree this string. The fieldP and rowP arguments are the addresses of integer variables allocated by the caller to receive the logical field and row numbers for the target cell. If a zero (0) is supplied as either of the argument values, that argument is ignored. After calling this routine, the field and row variables contain the field and row currently occupied by the target line. Subsequent changes to the list (add, remove, reorder) can change the a cell's row (but will not change the cell's field). Example of use: static void PrintCellInfo(w, closure) Widget w; /* Vlist widget */ Opaque closure; /* cell's closure */ { VListLine vLine; /* to receive cell's attribute values */ int field, row; /* to receive cell's position */ if (VListGetLineInfo (w, closure, &vLine, &field, &row)) { printf ("closure = %d\n", vLine.closure); printf ("text = %s\n", vLine.textP); printf ("color index = %d\n", vLine.coloridx); printf ("font index = %d\n", vLine.fontidx); printf ("field = %d\n", field); printf ("row = %d\n", row); } else printf ("no cell found with closure %d\n", closure); } ---------------------------------------------------------------------- To determine the best width for the VList widget's frame, call VListComputePreferredWidth. int VListComputePreferredWidth(w) Widget w; /* VList widget */ This routine computes the minimum width necessary to display the complete contents of each record in the list without the need for a horizontal scroll bar. ** This routine is only effective when single column style is enabled and ** the horizontal scroll bar is not necessarily always visible: ** ** (VListNcolumnStyle == VListColumnStyleSingle) && ** (VListNhScrollBarPolicy != VListScrollBarPolicyAlways) In this case, the routine returns the preferred width in pixels of the VFrame widget. Be sure that the VFrame is allowed to change its size. If both of its side edges are attached (in an XmForm widget, for example), its size is determined by its parent widget and cannot be changed from within the application. Example of use: /* Change the width of the VList widget's (VFrame) parent to best * display the list contents. */ Arg args[1]; XtSetArg (args[0], XtNwidth, VListComputePreferredWidth (vListW)); XtSetValues (XtParent (vListW), args, XtNumber (args)); +----------+ | Creation | +----------+ The VList widget can be created either through UIL or through program calls to XtCreateWidget. The VList widget must be a member of a widget hierarchy as follows. The widget would typically be a form or dialog box (attached or normal) or a main window. The VFrame widget is parent for the VList, the two scroll-bars, and the column header (VHeader) widgets. ... | | +---+---+--+--+---+---+ | | | | | | siblings... | other siblings... | vFrame | +------+------+--+---------+ | | | | | | | | hScroll vScroll vList vHeader If you use UIL, you must register the VList, VFrame, and VHeader widget classes with DRM. You must put the following lines in your application program before attempting to create any VList widgets: DwtInitializeDRM (); /* register toolkit widgets */ VListInitializeForDRM (); /* register VList widget */ VFrameInitializeForDRM (); /* register VFrame widget */ VHeaderInitializeForDRM (); /* register VHeader widget */ In your UIL file, you must include these lines: include file 'vlist.uil'; /* VList widget definition */ include file 'vframe.uil'; /* VFrame widget definition */ include file 'vheader.uil'; /* VHeader widget definition */ You can then define a VList widget as follows. You may need as many as five objects for each VList or as few as two, depending on your need for vertical and horizontal scroll bars and column headers. You can specify additional resources for the scroll_bar, vHeader and vFrame widgets. The sample program (testvlist.uil) shows how to use some of the more advanced options. A simple UIL example is shown here: module SimpleExample names = case_sensitive include file 'decw$include:dwtappl.uil'; /* DWT definitions */ include file 'vlist.uil'; /* VList widget definition */ include file 'vframe.uil'; /* VFrame widget definition */ include file 'vheader.uil'; /* VHeader widget definition */ object vScrollBar : scroll_bar { arguments {orientation = DwtOrientationVertical; height = 1;};}; object hScrollBar : scroll_bar { arguments {orientation = DwtOrientationHorizontal; width = 1;};}; object vHeader : user_defined procedure VHeaderCreate {}; object vList : user_defined procedure VListCreate { arguments { vlist_header_widget = user_defined vHeader; vlist_h_scroll_bar_widget = scroll_bar hScrollBar; vlist_v_scroll_bar_widget = scroll_bar vScrollBar;};}; object vFrame : user_defined procedure VFrameCreate { controls { scroll_bar hScrollBar; scroll_bar vScrollBar; user_defined vList; user_defined vHeader;};}; object main : main_window {controls {user_defined vFrame;};}; end module; Look at simpletestvlistm.uil and testvlistm.uil for MOTIF examples. +-----------+ | Wish List | +-----------+ The following items are currently on the VList widget wish list. If you have any ideas that you would like to contribute, send mail to WIDGET::KLEIN where it will be happily received. These items are roughly in the order I expect them to be implemented. (*) Vertical and horizontal separator lines (*) Support for font units (in addition to pixel units) for resource values (*) Sensitive header labels (single and double click callbacks on labels) (*) Non-scrollable header labels (single field, single column) (*) MOTIF-style keyboard traversal (*) Compound string text (in addition to ASCII text) (*) Right-to-left text and geometry (in addition to left-to-right) (*) Full-lines-only vertical scrolling option (*) Default pushbutton triggering (*) Indented text (*) Left and right side line header labels (in addition to top field labels) (*) Word-wrapped entries (*) Multiple stipple patterns (*) Better memory reclaimation in XtDestroy widget callback (*) Smooth histogram updates (flicker-free) (*) Improve performance of non-dashed (solid) histogram grid lines (*) Outlined entries (*) Arm and Disarm callbacks to track button press and release (*) Use negative closure values as direct index into the line array (*) Compress internal list format to reduce memory usage +------------+ | Known Bugs | +------------+ (*) When calling VListAddLine and while not in batch update mode, the layout sometimes stays in single-column style when it should automatically switch to multi-column style. [END-OF-DOCUMENT]