Property grid — version history

u_pbt_propertygrid · Introduced in 5.0

An inspector of named values, like the property window of an IDE: categories that fold, each value with the editor of its type, two views, a search and a help pane. Introduced in 5.0.

5.0 #

New #

• Named values sorted into categories that fold (of_add_category), or placed at the top without a category; a property is named by its address, "layout/width" under a category, "name" at the top (of_add_property).
• An editor for each type: text (TYPE_STRING), number (TYPE_NUMBER, typed in the display language: its decimal separator or a dot, its thousands grouping when well formed — 1,000 is a thousand in English, 1.500 fifteen hundred in German, 1 234,5 in French —, anything ambiguous or not a number refused and the old value back), check box (TYPE_BOOLEAN), list of choices (TYPE_ENUM, options added one by one with of_add_option), colour with its swatch and the themed colour picker (TYPE_COLOR), date with the themed calendar (TYPE_DATE), masked password (TYPE_PASSWORD).
• Values are given, read and handed by the events as text, written the same way whatever the language of the workstation: of_property(address).is_value for one value; of_values for every value at once, as a typed JSON object read with n_pbt_json along the same addresses.
• ue_value_changed(as_keys, as_value) reports each change of the user; a value written by the code raises nothing, like SetItem. With ib_veto_changes, ue_value_changing is asked first and can refuse the value: the cell shows the old one again.
• Two views, by category or alphabetical (is_sort), and a search (is_filter) on the label, the key and the shown value, both in a toolbar (ib_toolbar) and from the code.
• A help pane (ib_help) shows the label and the description (is_description, rich text markup) of the selected property.
• A … button at the end of a row (ib_ellipsis) raises ue_ellipsis_clicked, to open a dialog of your own and write its result back.
• Read-only properties (ib_readonly), hidden properties and categories (ib_visible), category titles and labels with rich text markup, a tooltip and five colours on every category and property.
• Selection by click, keyboard or code (of_select_property, of_clear_selection, of_selected_key, ue_selection_changed); categories fold by click, keyboard or code (ib_collapsed, of_expand_all, of_collapse_all, ue_category_toggled).
• Keyboard: arrows, Home, End and pages to move, Left and Right to fold, Enter or F2 to edit, Space to check, Escape to give the old value back; a double click on a label flips a boolean or takes the next choice of a list.
• Expandable properties (TYPE_GROUP), like the Font of a property window: a group holds the properties added at its address ("appearance/font/size" in a category, "margin/left" at the top), groups can be nested inside groups, and the closed row shows a summary of the values it holds, which is_value reads.
• A group opens and closes by its chevron, a double click on its label, the keyboard (Right opens, Left closes or goes up from a sub-property to its group, Space and Enter toggle) or the code (ib_expanded); ue_property_toggled(as_keys, ab_expanded) reports each change, and of_expand_all, of_collapse_all and of_select_property open or close groups too.
• The summary of a group is written your way with is_summary, a template: "{name}, {size} pt{?bold}, bold{/bold}" shows "Segoe UI, 10 pt, bold" ({x} a shown value, {x:raw} the stored one, {?x}…{/x} and {!x}…{/x} a piece kept only while x is on, or off).
• A search opens the groups that hold a match; the alphabetical view keeps the content of a group under it; a read-only group makes what it holds read-only; of_values gives each group as an object, read along the same address; of_remove_property removes a group with everything it holds; a group handle walks its sub-properties (of_count, of_keys_at, of_has).
• The line between labels and values is dragged by the user (ii_label_width, from 15 to 85 percent of the width).
• of_remove_property, of_remove_category, of_clear and of_reset remove what was added; a handle walks a category or the options of a list (of_count, of_keys_at, of_has), and of_type gives the type of a property.
• Numbers are kept digit for digit: "1.50" stays "1.50", and a decimal of 21 digits stays exact in of_values. A value its type cannot hold is refused: of_add_property returns -5, and is_value keeps the old value while of_get_last_error says why.
• A list of choices can be changed without removing its property: of_remove_option removes one option, of_clear_options empties the list to load another one; the value of the property stays.
• PowerBuilder system colours (above 16777215: Button Face, Transparent, Window Background…) are shown by their name with a neutral swatch, and the colour picker opens without a current colour.
• The grid is one stop of the Tab key, whatever its size: only the editors of the selected row take Tab. Ctrl+Enter presses the … button of the selected row, which also stays available on a read-only property; Enter and Escape with nothing to do are left to the window and its default and Cancel buttons. Screen readers are told the selected row, the level and the open state of each row.
• Large grids load fast: thousands of properties are added and walked by the keyboard without delay.
• Right-to-left applications are followed, arrows included.
• Numeric input masks in the PowerBuilder syntax on a TYPE_NUMBER property (is_mask: "#,##0.00", "$#,##0;($#,##0)", "0.0%"): the value is shown through the mask, the thousands grouping appears as the user types, the decimals are limited to the mask, letters are refused, and leaving the field completes it (12 becomes 12.00). The separators are those of the display language, and the value keeps the number as the code writes it.
• A display format next to the input mask (is_format): a TYPE_NUMBER property shows its number with its literals in its cell, its group summary and the search (#,##0 "px" shows 575 px), and its field turns into the input text when it takes the keyboard (575). Without an input mask, the field types the display format stripped of its literals. The swap never changes the value and raises no event.