Form — version history

u_pbt_form · Introduced in 5.0

A whole data-entry screen in one control: typed fields in columns and in sections that fold, checked together, with the changes since the load and one row of a DataWindow read and written. Introduced in 5.0.

5.0 #

New #

• Fields placed at the top of the form or in sections that fold (of_add_section); a field is named by its address, "order/qty" in a section, "name" at the top (of_add_field).
• A control for each type: text (TYPE_STRING), long text (TYPE_TEXTAREA), 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), switch or check box (TYPE_BOOLEAN), list of choices in the themed list (TYPE_ENUM), radio buttons (TYPE_RADIO), date with the themed calendar (TYPE_DATE), time typed h:mm (TYPE_TIME), colour with its swatch and the themed colour picker (TYPE_COLOR), masked password (TYPE_PASSWORD), e-mail (TYPE_EMAIL) and pictures (TYPE_IMAGE). Options of a list or of radio buttons are added one by one (of_add_option), removed one by one or all at once (of_remove_option, of_clear_options).
• Outlined fields with a label that floats up into their border, a placeholder, a line of help, a prefix and a suffix inside the field, an input mask (is_mask), a character counter.
• Values are given, read and handed by the events as text, written the same way whatever the language of the workstation: of_field(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. Numbers are kept digit for digit. A value its type cannot hold is refused: of_add_field returns -5, and is_value keeps the old value while of_get_last_error says why.
• 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 field shows the old one again.
• Validation: required fields (a required check box must be ticked), bounds of a number, a date or a time (is_min, is_max), a longest text (ii_max_length), a pattern the whole value must follow (is_pattern, is_pattern_message), a complete mask, a field equal to another one (is_match), the shape of an e-mail. Nothing shows in red before the user leaves a field; of_is_valid and of_invalid_keys answer without showing anything, of_validate shows every error at once and puts the keyboard on the first one.
• Business errors of your application (is_error) shown under a field until the user edits it, or cleared by of_clear_errors.
• The changes since the load: of_is_dirty, of_dirty_keys and of_is_dirty of a field; of_load loads a record and makes it the reference, of_reset_update takes the values on screen as the new reference, of_revert puts the reference back.
• One row of a DataWindow, a DataStore or a DataWindowChild: of_load_row fills every field named like a column, typed; of_save_row writes the values back into the row by SetItem, typed for each column.
• Layout in columns (ii_columns), a field spanning several columns (ii_colspan, -1 for the whole width) or several rows (ii_rowspan), pinned in a column (ii_col); the other fields fill the free cells.
• The whole form read-only (ib_readonly), or one field read-only, disabled or hidden (ib_readonly, ib_enabled, ib_visible); a section folds or hides (ib_collapsed, ib_visible, ue_section_toggled).
• The keyboard: of_focus_field and of_current_key, ue_focus_changed when the field that has the keyboard changes. Enter in a field commits it and goes on to the default button of the window, Escape puts back what was typed or goes on to its Cancel button; a list, a date or a colour opens with Enter, Space, F4 or Alt+Down, Up and Down step a list, Delete empties it.
• Labels, help lines and section titles with rich text markup, a tooltip and five colours on every section and field.
• Right-to-left applications are followed.
• Numeric input masks in the PowerBuilder syntax on a TYPE_NUMBER field (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, the minus sign is refused when the lower bound is 0 or more, 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 field shows its number with its literals while it does not have the keyboard (#,##0 "px" shows 575 px, $#,##0.00 a price) and turns into its input text when it takes the keyboard (575), the caret kept among the digits. Without an input mask, the field types the display format stripped of its literals; a % stays, it is a scale. The swap never changes the value and raises no event.
• A boolean is drawn as a switch whose knob slides to the end in the accent colour (BOOLEAN_SWITCH, the default) or as the classic check box (is_boolean_style = BOOLEAN_CHECKBOX). Both take Space and a click on their label, stay readable when disabled or read-only, and slide to the left in a right-to-left language.
• Tags (TYPE_TAGS): the user types labels that become pills with Enter, a comma or Tab (Tab keeps the keyboard in the field); Backspace in the empty input removes the last one, each pill has its cross, Left and Right walk the pills and Delete removes the one marked. The value is the tags joined by , ("vip, b2b"): the comma is the separator and never part of a tag, a tag written twice (whatever the case) is kept once. The options of the field are suggestions filtered as the user types (Down opens them all), a tag typed with the text of an option takes its value; ib_options_only keeps the tags to the options, ii_max_tags limits how many, is_pattern and ii_max_length judge each tag. A refused tag stays typed with its message.
• Ratings (TYPE_RATING): stars to click, ii_star_count of them (5 by default, up to 10), half stars with ib_half_stars. Hovering previews the stars without moving anything, a click on the value in place clears it; from the keyboard the arrows add or remove a star (swapped in a right-to-left language), Home and End give one or all of them, a digit that many, 0 or Delete clear it. A full star takes the accent colour. The value is the number of stars as text ("4", "3.5", empty when none), a number in of_values.