Notes and tips for ActiveX Toolkit lists
The following is a list of issues you should keep in mind when using the ActiveX implementation of a Toolkit list. For additional notes, see Using lists in Toolkit applications. For information on setting options that cause lists to be ActiveX lists, see Specifying and determining the list type.
- To retrieve the ActiveX control ID for an ActiveX Toolkit list, use L_STATUS.
- Prompts and fields create columns in an ActiveX Toolkit list. (Other text residing in the window does not.) When using multi-line list entries, the widest entry in a column determines the width of the column. For selection fields, the width of the column is set to the width of the widest selection list entry, regardless of the size of the field, unless the selection field is enumerated, in which case the enumerated display length is used instead.
- Prompts and fields are aligned within their corresponding columns without changing their content. Although this preserves leading spaces within a prompt, it does not preserve leading spaces before a prompt.
- To create an empty cell for alignment purposes, create a field that is not part of the input set.
- If the input window used for an ActiveX list contains fields that have display or view lengths that are different than their field lengths, don’t use windowing display routines (e.g., W_DISP) to populate these fields. The data won’t display correctly. Use I_DISPLAY, I_DSPFLD, or I_PUTFLD.
- Unlike Toolkit lists, ActiveX Toolkit lists enable users to scroll the current item out of view without causing focus to move to another item. This is mostly for performance, but it is also a common behavior for Windows applications.
There are times, however, when the internal list control snaps the currently focused item into view when L_INPUT or L_INPFLD is being used (as opposed to L_SELECT). This usually occurs when the user expects it (when focus moves to a new cell that is also not currently in view, for example), but it can occur at unexpected times. For example, this can happen when the initial and/or last item parameters passed to L_CREATE (or the default estimates if these parameters are not passed) prove incorrect by the responses from the load method. At that point, the internal list must be reorganized for the new list dimensions, which often causes the focused cell to snap back into the viewable area.
For instance, if you have a list that’s longer than twice the viewable area, and you don’t pass the last argument to L_CREATE, and the user uses the scroll bar to scroll all the way down, the list may suddenly snap back to the focused item when the item loaded exceeds the initially estimated last item. Note that this only occurs in L_INPUT and L_INPFLD, and does not occur if a correct estimate of the dimensions of the list is given to L_CREATE.
- When entering input into the list, the first field in the list will be selected even if it is not in the current input set.
- Dragging the scroll bar doesn’t update the list until the mouse button is released.
- Dragging the scroll bar all the way down may or may not go to the bottom of the list. For the scroll bar to work properly, you need to provide an accurate number (or overestimate the number) of list items for L_CREATE.
- If the width of a column is narrower than its header or footer text, that text will be truncated unless vertical bars (|) are used within the text to designate the initial width of the column. See L_SECT for more information.
- The order of items loaded is different when two-way loading is enabled. The specific order we have chosen to implement achieves the best performance for each type of list: Toolkit lists load as needed for display, and ActiveX Toolkit lists load ahead further in each direction to minimize self-correction when the initial estimates are incorrect. (See L_CREATE for information on loading methods for lists.)
- There may be repainting issues if users input directly into an ActiveX Toolkit list. As an alternative, you can set up the list as a selection list (using L_SELECT) and then create a separate input window for adding and updating list items. To see an example of this method, open S/DE Repository and select Modify > Structures. This opens the Structures Definitions list (which isn’t an ActiveX Toolkit list, but illustrates the method). In this list, you can highlight list entries, but you can’t make any changes in this window. To make a change, you must highlight a list entry and press Enter. This opens a separate input window, which enables you to add and update list items.
- By default, the size of a list container is based on the display area of the associated input window. However, if you don’t specify this display area for the input window, the runtime calculates the size by adding the columns using the larger of the input or display format to determine the size of each column. If any column has a header or footer that’s larger than the column’s input or display format, however, the container won’t be large enough to show all the columns. To correct this, set the display area for the input window by doing the following:
1. | For each column, find the largest of the following: the header, the footer, the display format, or the input format. |
2. | Add the numbers from step 1. (There should be a number for each column.) Then add an additional one or two characters for each column. |
3. | Test the window by compiling the window and looking at the list. If the column header, footer, or data is truncated, increase the display area until everything displays properly. |
For example, if your list has two columns (one whose largest element is the header, which has 13 characters, and a second whose largest element is the footer, which has 15 characters), add these two numbers. The sum is 28. Then add four to the total, which makes 32. (In this case, we’re adding two characters for each column in the list.) The display_area line of the list definition is
display_area 1, 1, 1, 32
Set the window width larger than the sum calculated in step 2 above. For example, if you calculate that the display area needs to be 32 characters, set the window size to at least 33:
.input table_list, 1, 33