New Grid Widget Features

Cell Text Wrapping (38994), Vertical Centering (38993), and Checklists (38995) are new features for Panther 5.54 for Windows.  These features are not available for Unix and Linux editions of Panther.

Cell Text Wrapping

Cell text wrapping comes into play when the heights of cells within a column are made taller due to a larger font being used in some other column of the Grid Frame widget.  Cell text wrapping works automatically for left-justified Single Line Text Widgets, Dynamic Labels, and Listboxes that are contained within a Grid Frame.  It is not available for right-justified widgets. 

In the case of a left-justified Single Line Text widget within a Grid Frame, text is not wrapped while typing into the cell.  The text scrolls horizontally off-screen (shifts) to the left while typing.  However, when the cursor (caret) leaves the cell, as much text as will fit neatly onto multiple lines within the cell will wrap within the cell.  If there is still more text, it will not be displayed.  If column widths are dynamically adjusted using the mouse, text will rewrap as needed.  It will vertically center itself on a single line if it all fits within the cell width on one line, or it may rewrap onto additional lines if the column width is decreased.  Regardless of wrapping, each cell is accessible to Panther application code as a single occurrence of an array, the same as before.

Vertical Centering

Cell text is now automatically centered vertically within each cell of the Grid Frame.  This works whether text appears on a single line within a cell or on multiple lines that are wrapped.   Note that this change may be apparent even for single lines of text where no cell height change was made due to a larger font in another column of the Grid Frame.  Previous versions of Panther displayed text slightly upward from center for some fonts.

Checklists

Listbox widgets can now display checkboxes when contained within a column of a Grid Frame widget.  Listboxes have a new property, 'checklist', or PR_CHECKLIST, which is available only for 'Select Any' Listbox widget types.  The new property has a default value of 'no', or PV_NO.  When set to 'yes', or PV_YES, a 'Select Any' Listbox widget will display a checkbox to the left of its display text, but only when contained within a Grid Frame, and only in Windows versions of Panther.  The property is settable and retrievable for non-Windows versions of Panther, but will otherwise have no effect for those other platforms.

Note that in Edit Mode of the Panther IDE, the 'Checklist' property appears in the Properties Window as a sub-property of 'Listbox Type', when the value for 'Listbox Type' is 'Select Any'.

PR_COLUMN_CLICK_ACTION / PV_SELECT_ALL

A new value for the PR_COLUMN_CLICK_ACTION property is supported for a Listbox.  It is PV_SELECT_ALL, or 'Select All', as shown in the Properties Window.  This new value is available for only "Select Any" Listbox types and for only those that allow more than one selection. The Checklist property is not required.  (Note that Selection Group properties can limit the number of selections to only one, making the Select Any property unavailable.) The Select All value is available regardless of whether the Listbox is contained within a Grid Fame, but is otherwise non-functional, just like the Sort value.

When Select Any is used for a Checklist-style Listbox within a Grid Frame, it causes the Listbox to show a checkbox on the left side of the column title when Column Titles is enabled for the Grid Frame widget.  At runtime, this checkbox is used to select all occurrences of the Checklist at once.  If all occurrences of the Checklist are already selected, the checkbox within the column title will show a checkmark, whereupon deselecting it will deselect all occurrences in the column. (Note that the box itself does not need to be clicked.  It is sufficient to click anywhere within the column title area. Thus, this new functionality may be used even for non-Checklist Select Any Listboxes within a Grid Frame.) 

The built-in function that is used to perform automatic selection or deselection of all occurrences in a column is named sm_select_all.  It is available as a prototyped function for application code to call explicitly.  This function conforms to the standard prototype for a custom Column Click Action function.  See Appendix A at the bottom of this document for additional documentation for sm_select_all().

F2ASC

Panther’s F2ASC utility has been enhanced to support the new PR_CHECKLIST property.  The generated ASCII text will show "WIDGET-TYPE=LISTBOX(SELECT-ANY CHECKLIST)" for a Listbox whose Checklist property is set to Yes.

Additional Notes for Checklists

1. The new checklist-style Listbox will behave the same as a normal selection-style Listbox within a Grid Frame, except that it does not support 'Extended Selection'.  That is, even if you have the setup variable LISTBOX_SELECTION assigned the value EXTENDED_SELECTION, which is the default, the Checklist will behave as if were in SINGLE_SELECTION mode.  In other words, you don't need to hold down the Ctrl key when clicking to make multiple selections.  However, nor can you make multiple selections with a mouse drag operation.

2. The group property PR_NUM_OF_SELECTIONS will affect the Checklist behavior in the same way that it does for a normal 'Select Any' Listbox.

3. The PR_CHECKLIST property is a widget property for a Listbox.  It cannot be assigned to individual Listbox elements or occurrences. 

4. All occurrences of the Panther array that is in the form of a Checklist will show a checkbox when within a Grid Frame column in Windows, including empty occurrences or elements.  Empty occurrences may be selected and deselected, the same as for a non-Checklist Listbox within a column of a Grid Frame.

5. The checkboxes used for the Checklist are square, with sides that are approximately equal in length to the font height used in the column in which they appear.  They are custom drawn by Panther.  Therefore, they will not look exactly like the Check Box that is a separate Panther widget which is implemented as a Windows Common Control.

6. The Checklist checkboxes are always displayed on the left side of a Grid Frame column, even when the Listbox text is right-justified.

7. The width of a column is made wider to account for the extra width occupied by the checkboxes for a given field Length.  Thus, a column whose width is dynamically changed by means of changing the Length property of a checklist-style Listbox within that column, will acquire a new width that takes account of the extra width required for its checkboxes and the extra margin to their right.

Appendix A: Function Reference Addendum

The following new function is available in C, JPL, and Java (CFunctions, and CFunctionsInterface).

NAME

            sm_select_all - select or deselect all occurrences of a selection widget

SYNOPSIS

ret = sm_select_all (objid);

int  ret;

int  objid;

DESCRIPTION

This function selects or deselects all occurrences of objid, where objid is the Object Id of an array that is a checkbox array, a toggle button array, a rel-5 array, or a select-any listbox.  It is used for the PV_SELECT_ALL setting of the PR_COLUMN_CLICK_ACTION property of a select-any listbox.

If all occurrences in the array are already selected, all are deselected.  Otherwise, all are selected.  The widget is not required to be in a grid or selection group, but if it is in a selection group, the group must allow any number of selections, or else an error code is returned.

Note that this function does not select/deselect all members of a selection group containing the selection widget, unless that selection group consists only of that one widget.

RETURNS

0          success;

else    a Property API error code