list_box

related attributes

• These attributes are predefined for a list_box only:
• • bcad_label
  • This attribute specifies the column labels of a multi-column list_box. Column labels are to be separated by tab "\t". Within a column label, newlines "\n" may appear to specify a multi-line column label.
    The bricscad dcl engine can also detect column labels from the label attribute. It is more complex to split the label attribute in column labels since that method has to "degrade gracefully" on other dcl engines, which do not support column labels. If both the label and bcad_label attribute are specified, bcad_label will be used instead of label. When using the bcad_label attribute, the plain label attribute can be specified as an alternative on other dcl engines.
    When a complex alternative to multiline column labels is used outside the list_box, for instance two rows of text_part components, the attribute bcad_skip_next_child can be used to suppress the complex alternative on bricscad. Instead, in bricscad, the superior bcad_label can be used for actual multiline column labels.
    To make a list_box multi-column, see the tabs and tab_truncate attributes.
  • bcad_font
  • This attribute controls the monospaced font used when fixed_width_font attribute is enabled.
  • multiple_select
  • This attribute controls whether the list_box is multiple select or single select. The default value is single select.
• These attributes are predefined for a list_box or popup_list only:
• • list
  • With this attribute, the initial contents of the list_box can be specified. To separate between rows, use the newline symbol "\n". To separate between columns use the tab symbol "\t". To change the contents of the list_box at runtime, use the functions start_list, add_list, end_list.
  • tabs
  • This attribute can be used to control the width of columns. The value of this attribute has to be a string containing a space separated list of integers. For historic reasons these integers are cumulative, it is a list of increasing integers. Every integer adds the width of the next column to the previous cumulative width. So to specify four columns of width 5, use "5 10 15 20". Mind that there will be a fifth column of remaining width, so perhaps the last integer is not wanted. When DCL was first created, an actual multi-column control was not available. Tab-stops were used rather than real columns. Tab-stops are indeed typically defined as cumulative values.
  • tab_truncate
  • Normally text that is too wide to fit in a column, will be spread across multiple columns and push further any text that appears further in the same row. If this attribute is set to true, text will be restricted to its own column only and grid lines will be displayed between the columns and rows. Truncated text can be revealed by dragging the grid lines between the columns. (Dragging the columns grid lines is a BricsCAD only feature.)
• This attribute is predefined only for an image_button, edit_box or list_box:
• • allow_accept
  • When a list_box has the attribute allow_accept with value true, hitting enter when the list_box has focus or double clicking the list_box will trigger the default button of the dcl dialog.
• This attribute is predefined only for a text, text_part, edit_box, list_box or popup_list:
• • fixed_width_font
  • If a different monospaced font is desired when fixed_width_font attribute is enabled, use bcad_font attribute.
• These attributes are predefined for every child tile and consequently for a list_box as well:
• • mnemonic
  • is_tab_stop
• These attributes are predefined for every tile and consequently for a list_box as well:
• • key
  • value
  • The value of a list_box represents its current selection. For a single-selection list_box, the value will be the index of the currently selected row or an empty string if no row is selected. For a multiple-selection list_box, the value is a space separated list of row indices.
  • tooltip
  • label
  • In DCL, for historic reasons, the label attribute is typically used to fake column labels. By inserting additional spaces, words are aligned with the columns. For instance, say the tabs attribute has value "10 20 30", with the intention of specifying 3 columns of width 10. A typical label specifying column headers is of the form "header 1     header 2     header 3". Alternatively the same value for the tabs attribute could be to specify 4 columns, 3 of width 10, one of the remaining width. In that case a typical label attribute would be of the form "header 1     header 2     header 3     header 4".
    In BricsCAD it is possible to have actual column labels. When the column labels are aligned with the columns using spaces, BricsCAD attempts to parse the column headers as follows: For each column width n, take the next n characters of the label attribute including any trailing spaces. For the preceeding example, the first 10 characters of the label are "header 1  ". Including the trailing spaces gives "header 1     ". Repeating this process properly divides the label attribute in sub-labels. If the number of sub-labels matches the number of width in the tabs attribute (same amount or one additional column allowed), then actual column labels will be displayed. If actual column labels are displayed, grid lines will be displayed, like when tab_truncate is on.
    The division in sub labels by means of the label attribute is rather elaborate. It is more easy to use the bricscad-only attribute bcad_label, with separation in sub labels by means of the tab "\t" symbol. However, the detection of sub labels in the label attribute yields a good chance to "automagically" have real column labels in bricscad when using legacy dcl code.
  • fixed_height
  • fixed_width
  • alignment
  • width
  • bcad_width
  • height
  • bcad_height
  • is_enabled

callbacks

• When changing the list_box selection by use of the cursor keys or mouse or when hitting enter, a callback with reason CBR_SELECT will be triggered.
• When double clicking a list_box, a callback with reason CBR_DOUBLE_CLICK will be triggered.
• When a list_box has the allow_accept attribute, a callback will be triggered with the ok button as sender by hitting enter when the image_button has focus or by double clicking the image_button. If no ok button has been defined, done_dialog will be called. The ok button callback happens in addition to the normal CBR_SELECT or CBR_DOUBLE_CLICK callback of the list_box.