11. Migrating from 3.0 to 4.0 #

← Migrating from 2.0 to 3.0 · Contents · Release notes →

4.0 removes two methods from the thirty-two components of 3.0 — of_set_data of the crosstab, renamed of_from_datastore (11.33), and of_transform of n_pbt_xml, which goes with XSLT (11.31) — and changes signatures the compiler shows you line by line: three properties renamed (id_minimum and id_maximum of the progress bar, 11.6; il_doc_line of the code editor, 11.28), event arguments added or renamed (ue_tile_moved, 11.6; ue_failed of the REST client, 11.6, and of the video, 11.26; ue_error of the picture, 11.25; ue_cell_double_clicked, 11.33; ue_closed of the command palette, 11.36; the toaster's ue_toast_clicked, ue_toast_action and ue_toast_dismissed, 11.38), of_count and of_keys_at in long (11.34) and methods that now return a code (of_refresh, of_select, of_show, of_scroll_to_end, of_set_header…). 11.6 also aligns two counts, one event and the path of the JSON tree with the rest of the library: that is where, with the sections cited, code that compiled needs touching. What changes is concentrated on the ribbon (ribbon), which went through a complete review. Two changes ask you to read your code again: the questions asked before a ribbon gallery tile and before a side bar (listbar) selection (11.1) and the handles freed by a removal (11.2). The others fix behaviours you may have worked around (11.3) — among them the right-click on an item, which now produces a single event in every component, and the breadcrumb (breadcrumb), whose addresses and refusals were reviewed. Then come the n_pbt_menu2ribbon generator (11.4) and what was added (11.5). The tabs (tab) follow the same rule: their two questions, before a tab change and before a close, are now optional (11.1). Finally, themes follow the application (11.7): the application accent survives a change of theme, and a theme axis left empty follows the application's. The security review of crypto (11.8) closes a JWT algorithm confusion, replaces several silences with a refusal that states its reason and sets the rule for the relative paths of files.

The complete review of 28/09/2026 read every shipped component again; what it changes has one section per component: restclient (11.9), speechout (11.10), statictext and rich text (11.11), breadcrumb (11.12), buttonbar and the window keyboard (11.13), button (11.14), menubar (11.15), ribbon (11.16), toolbar (11.17), statusbar (11.18), dockcontainer (11.19), tab (11.20), listbar (11.21), tilesbox (11.22), stepbar (11.23), progressbar (11.24), picture (11.25), video (11.26), pdfviewer (11.27), codeeditor (11.28), jsontree and xmltree (11.29, 11.30), xml (11.31), json (11.32), crosstab (11.33), shellexplorer (11.35), commandpalette (11.36), radialmenu (11.37), toaster (11.38) and messagebox (11.39); the common base has two sections, 11.34 and 11.40. One rule runs through them, PowerBuilder's own (SelectTab raises SelectionChanged): a change requested by your code raises the same event as a user gesture, and asks the veto question if you switched it on; the method returns -4 when you refuse. It holds for a selection (of_select_*), an opening or a folding (of_expand, of_collapse, of_open), a zoom, a full screen, a chapter; nothing is raised when nothing changes, and of_reset stays silent. Setting a VALUE (a check mark, a text, a volume, a filter) stays silent, like SetItem. ue_layout_changed is raised in both cases: it says that a layout to store has changed.

11.1 The questions before a change are now opt-in #

In 3.0 the ribbon asked the ue_gallery_selection_changing question by default before keeping a tile: ib_veto_gallery was true. In 4.0 it is false, like every cancelable event of the library: each question costs a round trip to PowerBuilder, and only an application that answers it should pay for it. An application that did not script the event sees no difference. New: of_select_gallery_item raises ue_gallery_selection_changed like a click and, with the question switched on, asks it too; a refusal makes it return -4, the tile does not change.

// 4.0 : the question is only asked on request. If your ue_gallery_selection_changing
// returns false for some tiles, switch it on where the ribbon is built.
uo_ribbon.ib_veto_gallery = true

The recipe: search your ribbon descendants for ue_gallery_selection_changing; wherever it is scripted, add ib_veto_gallery = true to the build. Wherever you wrote ib_veto_gallery = false to switch the question off, the line is now useless and can go.

The side bar (listbar): ib_veto_selection #

Same rule: in 3.0 the listbar asked ue_selection_changing by default before every selection change (ib_veto_selection was true). In 4.0 it is false. If you scripted ue_selection_changing to refuse a move, set ib_veto_selection = true: without it the event is no longer raised and the selection moves without asking you. When switched on, the question is asked for a selection requested by your code too (of_select_item, of_clear_selection), as in 3.0; a refusal now makes them return -4, and the selection does not move. ue_selection_changed fires as before.

// 4.0 : the listbar only asks on request. If your ue_selection_changing
// returns false (unsaved changes), switch the question on where the bar is built.
uo_nav.ib_veto_selection = true

The recipe: search your u_pbt_listbar descendants for ue_selection_changing; wherever it returns false, add ib_veto_selection = true to the build. Wherever you wrote ib_veto_selection = false to switch the question off, the line is now useless and can go.

The tabs (tab): ib_veto_selection and ib_veto_close #

Same rule, two questions: in 3.0 the tab component asked ue_selection_changing by default before every tab change and ue_tab_closing before every close (ib_veto_selection and ib_veto_close were true). In 4.0 both are false. If you scripted ue_selection_changing or ue_tab_closing to refuse, set ib_veto_selection = true or ib_veto_close = true: without it the event is no longer raised and the tab changes or closes without asking you. When switched on, the question is asked for of_select_page too, as in 3.0, but before the tab changes: a refusal makes it return -4 and nothing moves; an agreement changes the tab at once, ue_selection_changed fires as before, and of_selected_key() read right after already returns the new key.

// 4.0 : the tab only asks on request. If your ue_selection_changing or
// ue_tab_closing returns false (unsaved changes), switch the questions on.
uo_tabs.ib_veto_selection = true
uo_tabs.ib_veto_close     = true

The recipe: search your u_pbt_tab descendants for ue_selection_changing and ue_tab_closing; wherever one returns false, add the matching line to the build. Wherever you wrote = false to switch a question off, the line is now useless and can go.

11.2 Adds say what they refuse, removals free their handles #

In 3.0, an add the ribbon ignored — a key already taken, a menu entry under a plain button — still returned 0, and nothing appeared. In 4.0 it returns -5, and the code of the send (-2 when the component is not created) instead of a fixed 0. And a removal frees the handles of what leaves: a variable holding the handle of a removed control is no longer valid.

// 4.0 : after a removal or of_clear, ask the component for the handle again
uo_ribbon.of_clear()
uo_ribbon.of_add_tab(/*key*/ "home", /*title*/ "Home")
uo_ribbon.of_add_group(/*keys*/ "home/clip", /*title*/ "Clipboard")
uo_ribbon.of_add_button(/*keys*/ "home/clip/paste", /*label*/ "Paste", /*image*/ "")
uo_ribbon.of_item(/*keys*/ "home/clip/paste").ib_enabled = false

The recipe: do not keep a handle beyond a removal or an of_clear — ask for it again with of_tab, of_group, of_item or of_menu_item, which costs nothing. Where a build error matters to you, test the code the add returns.

11.3 Other behaviours you may notice #

When the window is narrow, the ribbon folds its groups into a button that opens a panel. That panel is where the most visible differences come from:

If you had worked around one of these defects — for instance by handling ue_menu_selected with an empty address to catch the clicks of a folded group — remove the workaround: the documented event now arrives.

11.4 The n_pbt_menu2ribbon generator #

In 3.0, the code written by n_pbt_menu2ribbon used handle methods that no longer existed: it did not compile without edits. In 4.0 it writes the current API — every add by its address, through the component —, carries submenus over at any depth, keeps greyed and checked items as they are, and its router covers ue_clicked, ue_toggled and ue_menu_selected. The keys change: each one is now the ClassName of the menu item (m_fichier/g1/m_ouvrir) instead of the dotted path (m_principal.m_fichier.m_ouvrir).

The recipe: a ribbon already built by hand, or from generated code you then fixed, has nothing to change. To start again from the generator, run it again and paste the new router too: the old one read dotted keys.

11.5 What was added #

None of the following asks you to change your code. The new components of 4.0 are presented in the release notes.

11.6 Names and counts aligned with the rest of the library #

Seven places spoke differently from the rest of the library. 4.0 aligns them rather than keeping the gap: two names change — the compiler shows you each line to fix —, two counts now start at 1, like every position in the product, the path the JSON tree hands back becomes the path of n_pbt_json, the XML tree's under a default namespace an XPath that works, and an ambient event becomes opt-in. These are the only changes in 4.0 that ask you to touch code that used to compile.

The recipe: (1) recompile — the compiler flags il_minimum, il_maximum and as_to_keys: rename them id_minimum, id_maximum and as_to_key; (2) look for json paths that address an array and add 1 to each index — a loop for i = 0 to n - 1 over "lines/" + String(i) becomes for i = 1 to n; (3) a toolbar layout saved by 3.0 counts from 0: add 1 to the band and index of each bar before handing it to of_set_layout, or let the user rearrange once — read back as it is, it would put its first two bands together; (4) where ue_cycle is scripted, set ib_track_cycle = true at construction; (5) where you read a path from the JSON tree (ue_node_clicked, of_selected_path) or gave one (of_select_path), replace the dots with / and add 1 to each array index — lines.0.sku becomes lines/1/sku, which goes as it is to n_pbt_json.of_get_string.

11.7 Themes follow the application #

The theme review made every component hold the rule chapter 4 already announced: the application decides the theme and the accent, a component departs from them only as far as it is asked to. No method is renamed; what changes shows on screen, when reading the properties back, and in two return codes.

The recipe: (1) if you set the accent again after each PBT_SetDefaultTheme, it is no longer needed — and if you relied on a change of theme to clear the accent, call PBT_SetDefaultThemeAccent(-1); (2) test the return code of PBT_SetDefaultTheme when the name comes from user input or a file; (3) where you set both axes on every component to follow the application, leave them empty; (4) a tile whose badge went back "to the theme" with il_badge_color = 0 is now written -1.

11.8 crypto: what security now refuses, and where relative paths go #

The security review of crypto shuts a real door — a JWT forged with the PUBLIC key passed when the algorithm was missing — and replaces several silences with a refusal that states its reason. No method is removed; an ECDSA signature changes form, and the relative paths of files follow one rule.

The recipe: (1) ALWAYS pass a JWT's algorithm as a constant (n_pbt_crypto.JWT_RS256), never read from the token nor from an INI that may lack it; (2) if a server verified your EC signatures in P1363 (.NET VerifyData by default), convert them or verify them in DER (DSASignatureFormat.Rfc3279DerSequence); (3) an il_pbkdf2_rounds set out of bounds must come back between 1,000 and 10,000,000; (4) a file a relative path wrote next to the EXE is now in the application's start folder — give a full path if you want another one.

11.9 restclient: headers that state their refusal, redirections that keep the request #

The review of restclient replaces two silent losses — a change never made behind a redirection, an authentication never sent behind a malformed header — with the right behaviour or a refusal that states its reason. No method is removed; three become functions, two properties arrive, and Windows authentication leaves only when you ask for it. One point holds for the five nonvisual components that raise events: an error in your event code now shows.

The recipe: (1) test what of_set_header, of_set_bearer and of_set_basic return when the value comes from user input, an INI or a database — a call that ignores the return still compiles, but the -5 is now the only trace of a refused header; (2) an intranet API with Windows authentication that answered 200 now answers 401: set ib_windows_auth = true on THAT client; (3) a 32-bit application reading a body over 16 MB as text moves to of_download; (4) if you shared a request id between two objects, read the answer on the object that sent it; (5) an error that now shows in SystemError from ue_response or ue_failed already existed: it was swallowed.

11.10 speechout: live settings, a silent destruction #

The review of speechout keeps two promises the documentation made and the code did not — a setting changed during a reading applies to the next sentence, of_speak_from past the text returns -5 — and removes an event raised at the wrong moment. No method is removed. Added: of_add_abbreviation, of_clear_abbreviations, the ue_mark event and two tags, [mark=name] and [rate=150]…[/rate].

The recipe: (1) test the -5 of of_speak_from when the index comes from a click; (2) if your ue_stopped did something when the window closed, call of_close() yourself in its close — the destruction no longer raises it; (3) do not keep sentence numbers from one version to the next: take them from ue_sentence, as the documentation always said.

11.11 statictext and rich text: markup read from left to right #

The review of statictext mostly fixed the shared markup text (4.7): these lines apply to the label of every component — tab title, status bar panel, toast, dialog. No method is removed. Added: of_refresh_parent_color(), and the [action], [hyperlink] areas and [foldarea] headers of a statictext are reachable with the keyboard (Tab, then Enter or Space).

The recipe: (1) an ii_padding = 0 written to mean "the theme's margin" becomes -1 — or goes; (2) a markup image stored on a network share goes through of_icon(); (3) a ue_clicked that reacted to a section being folded will no longer be called: folding is not scripted.

11.12 breadcrumb: what gives when the path does not fit, and leaving the field #

The second review of the breadcrumb (breadcrumb) fixed the fold by width, the OVERFLOW_SHRINK mode and what a segment takes along with it. No method is removed. One line applies to every native menu of the library: type-ahead.

The recipe: (1) an of_edit() whose 0 you tested without setting ib_editable now returns -4; (2) a ue_path_entered may arrive when the user clicks elsewhere in the window — it is the same text as with Enter; (3) after an of_insert_item in the middle of the trail, ask again for the handles of the segments that follow.

11.13 buttonbar and window keyboard: the key goes to the component of the focus #

The second review of the button bar (buttonbar) touched the window keyboard, shared by every component that answers Enter, Escape, an Alt+letter or a registered shortcut (button, buttonbar, and the of_register_shortcut shortcuts of every component). No method is removed; one is added, of_focus_button.

The recipe: (1) on a bar, give a shortcut to ONE button — of_register_shortcut("Ctrl+S", "save") — the keyless form returns -5; (2) after removing and re-adding the default button, set is_default again; (3) to put the focus on a given button ("No" rather than "Yes"), call of_focus_button("no").

11.14 button: a grayed-out button lets go, and Alt+letter answers #

The review of the button (button, deprecated in favor of buttonbar but still delivered and fixed) changes what it does on the keyboard and what its properties read back. No method is removed or added.

The recipe: write the key names of is_shortcut in English ("Ctrl+Enter") and read the property back when in doubt: "" means refused. If you grayed out a default button to "disable Enter", nothing to change: that is now what happens.

11.15 menubar: a menu bar that gives the focus back, and Alt+letter from anywhere #

The review of the menu bar (menubar) changes what it does with the focus and the keyboard, and what every native menu does in right-to-left writing. No method is removed nor changes its signature.

The recipe: in ue_item_selected, work on GetFocus() or on the DataWindow being edited as with a PowerBuilder menu; put an & in every title; if your application used Alt+letter for something else, register it (of_register_shortcut): it keeps the priority.

11.16 ribbon: a choice that holds, menus that stay open, refusals that say so #

The second review of the ribbon (ribbon) fixes what the user saw — a font choice undone, a menu closing under the pointer — and applies the library's rule to the ribbon: an add or a removal that cannot happen returns -5. No method is removed nor changes its signature.

The recipe: (1) ue_selection_changed and ue_minimized are raised when your code calls of_select_tab or sets ib_minimized too, as for a click: if you called your handling yourself right behind it, remove that call, it would run twice; (2) test the -5 of the adds if your build may repeat a key; (3) an is_app_button = "" that meant “File” is now written is_app_button = "File". The removals under a control and the handle of an application menu entry are in table 11.5.

11.17 toolbar: one shortcut rule, a single tooltip, refusals that say so #

The second review of the toolbar (toolbar) aligns its shortcuts with the window's and makes visible what was written to no effect. No method is removed nor changes its signature; two return codes appear (-5).

The recipe: (1) a tool shortcut on a bare key (other than F1 to F24) takes Ctrl or Alt; (2) on a toolbar, of_register_shortcut receives the address of the tool or entry; (3) to place the main bar, call of_add_bar(MAIN_BAR, band, rank) before its first tool.

11.18 statusbar: a grip that resizes, a message that does not replace the text #

The second review of the status bar (statusbar) gives the resize grip its real role and turns every empty or unknown key into a refusal. No method is removed nor changes its signature; of_flash_panel gains a return code (-5).

The recipe: (1) set ib_show_resize_grip on a status bar placed at the bottom of a resizable window; (2) test the return of of_flash_panel like that of the other keyed methods; (3) give a key to every panel you want to read back or change.

11.19 dockcontainer: an of_select_panel that finds the panel, floating windows that remember #

The second review of the panel container (dockcontainer) gives of_select_panel an effect on a collapsed or floating panel, and makes the layout remember the floating windows. No method is removed nor changes its signature.

The recipe: (1) ue_panel_selected, ue_panel_floated and ue_panel_pinned are raised after of_select_panel, of_float_panel and ib_pinned too, as for a gesture: if you called your handling yourself right behind them, remove that call, it would run twice; (2) test the -5 of of_move_panel, of_float_panel and of_select_panel; (3) a layout saved before 4.0 restores as it is, its panels stay docked.

11.20 tab: honest return codes, a right-click that goes back to the application #

The second review of the tabs (tab) makes of_add_page and of_select_page say what they refuse, announces the layout when your code hides a tab, and hands the right-click back to the application when the built-in menu is off. No method is removed nor changes its signature; one event is added.

The recipe: (1) test the -5 of of_add_page (a page is hosted only once) and of of_select_page; (2) if you store the layout in ue_layout_changed, nothing to do — it now follows your ib_visible too; (3) where ib_context_menu = false left the right-click unanswered, script ue_tab_rclicked.

11.21 listbar: a hidden entry never selected, a checked layout #

The second review of the navigation bar (listbar) makes of_select_item refuse a hidden entry and of_set_layout a text that is not a layout, and adds a count pill, the Left / Right keys and the right click of an entry. No method is removed or changes its signature.

The recipe: (1) ue_selection_changed is raised after an of_select_item of your code too (opening the home page at start-up, for instance), as for a click: if you opened the page yourself right behind it, leave that to the event, otherwise it would open twice; (2) test the -5 of of_select_item if you hide entries, and that of of_set_layout if the layout comes from a file; (3) a section without a title no longer folds: give it a title if it must fold.

11.22 tilesbox: a title that no longer creates a group, rearranging from the keyboard #

The second review of the tile panel (tilesbox) stops a group's title from creating that group, makes of_add_live_item refuse an empty text, gives one Tab stop per group and adds rearranging from the keyboard. No method is removed or changes its signature. il_badge_color now follows the rule of every colour (see the picture, button, tilesbox row above).

The recipe: (1) create a group with of_add_group before changing its title; (2) test the -5 of of_add_live_item if the text of a face can be empty; (3) what you did in ue_tile_moved now also applies to a move from the keyboard.

11.23 stepbar: "everything done" anchored on the last step, removed steps that no longer leave anything behind #

The second review of the step bar (stepbar) makes "everything done" consistent with the rule of the current step (an identity, not a rank), makes a removed step take what belonged to it, and fixes four display defects. No signature changes.

The recipe: if your code adds a step after setting "everything done" (ii_current = of_count() + 1) and wants the bar to stay so, set ii_current = of_count() + 1 again after the add. If you rebuild the bar with the same keys, set the colours and tooltips you want again: they no longer survive the removal.

11.24 progressbar: a bar that fits its control, a label that follows the language #

The second review of the progress bar (progressbar) makes it fit where an HProgressBar stood, sends the component only the values that change the drawing, writes the percentage in the display language and adds is_label_format (a label of your own) and is_state (paused, error). No signature changes.

The recipe: (1) if you computed a percentage by hand, set id_maximum and assign the raw value, on every row if you like; (2) if an automated test read the label, expect the format of the display language; (3) to show a pause or an error, prefer is_state to a colour chosen with il_color.

11.25 picture: an assignment reads the file again, a failure says why #

The second review of the image (picture) makes it read the disk at every assignment, like the native Picture, gives ue_error a second argument that says why the image is missing, refuses an http:// address instead of failing with no reason, and raises only one ue_clicked on a double click. ue_error is the only signature that changes.

The recipe: (1) if a script opened a record on ue_clicked and another action on ue_double_clicked, nothing to do — the double click no longer opens the record again; (2) replace any parsing of the text of as_message with a test of as_reason; (3) an image on an intranet server over http is downloaded first (n_pbt_restclient.of_download into a temporary folder), then shown by its path; (4) if you added a ?v= to the path to force re-reading a rewritten image, remove it: assigning again is enough.

11.26 video: subtitles and formats that play, a failure that says why #

The second review of the player (video) gives ue_failed a second argument that says why a film does not play, refuses an http:// address, plays .mkv and .mov, loads subtitles given by URL, and pauses the film when the component is hidden. ue_failed is the only signature that changes.

The recipe: (1) add as_reason to your ue_failed script and test it rather than the message text; (2) a film or a subtitle from an http intranet server is downloaded first (n_pbt_restclient.of_download to a temporary folder), then played by its path; (3) ue_fullscreen_changed, ue_pip_changed, ue_source_changed and ue_chapter_changed are raised after your own calls too (of_fullscreen, of_pip, of_next, of_seek…), as for a gesture: if your code called its handling itself right behind them, remove that call, it would run twice; (4) a wallboard that must play hidden sets ib_pause_when_hidden = false; (5) to replace the track of a language, of_remove_subtitles then of_add_subtitles.

11.27 pdfviewer: of_refresh says what it does, nothing downloads behind your back #

The second review of the viewer (pdfviewer) gives of_refresh a return code — and, to keep the same name with the same meaning, the ones of webbrowser and shellexplorer too —, reports every link of the document, and refuses what will never show instead of leaving you waiting. No event signature changes.

The recipe: (1) a call uo_pdf.of_refresh() compiles as is; test its return if you want to know there was nothing to read again; (2) a document of more than 1.5 MB held in memory is written to a temporary file, then shown by its path; (3) in ue_link_clicked, expect a mailto: and a disk path too, not only a web address; (4) to copy the document on screen, copy the file of is_source rather than of_print_to_pdf.

11.28 codeeditor: a search you can see, a “go to” that moves the caret, replace #

The second review of the code editor (codeeditor) brings on screen what the search finds, keeps the user's caret during a search, renames ii_doc_line and adds what a script editor is expected to do: replace, drive the caret, know whether to save, show an error in the gutter. No event signature changes.

The recipe: (1) replace ii_doc_line with il_doc_line; (2) test the -4 of of_find if the search can be switched off; (3) to “go to the line” of an error while moving the caret, set il_caret_line (and of_add_marker to show it) — il_doc_line only marks; (4) if you followed ue_caret_changed to learn where a snippet was inserted, read il_caret_line after of_insert_text; (5) a Save button can follow ib_modified, which you set back to false after saving.

11.29 jsontree and xmltree: the keyboard stays with the tree, a search that no longer moves the selection #

The second review of the JSON tree (jsontree) covered the engine it shares with the XML tree (xmltree): what follows applies to both unless stated. No signature changes; the JSON tree gains of_expand_path, of_collapse_path, of_is_expanded, of_copy and the ue_node_toggled event, raised by a user gesture as by of_expand_path and of_collapse_path.

The recipe: (1) if a window relied on Enter in the tree to trigger its default button, add that step to ue_node_clicked; (2) no longer look for an empty key in ue_selection_changed (a closing line is no longer selected); (3) do not parse the text of ue_error: it follows the language; (4) to restore a user's folds, read of_is_expanded and set them again with of_expand_path / of_collapse_path.

11.30 xmltree: every line has its XPath, any XPath selects #

The second review of the XML tree (xmltree) takes up everything the previous section says about the shared engine. It adds what is specific to XML: a path that ALWAYS designates the node of the line, readable as it is by n_pbt_xml. No signature changes; the XML tree gains of_selected_xml, of_copy, of_expand_path, of_collapse_path, of_is_expanded and the ue_node_toggled event.

The recipe: (1) if you went up from a text or comment line to its element through of_selected_path, take the parent of the path (what comes before the last /); (2) do not parse the text of ue_error: it follows the language; (3) a path saved in 3.0 under mixed namespaces is found again by handing it to of_select_path, which now accepts any XPath, then reading of_selected_path back.

11.31 xml: refusals that say so, namespaces that hold #

The second review of n_pbt_xml changes no signature. It makes of_remove follow the library's codes, refuses a read while a built document has an element open, and makes namespaces hold: what a mutator writes reads back in the right namespace, or is refused with a reason.

The recipe: (1) an of_remove tested for = 0 (nothing removed) still works; test < 0 (nothing could be tried); (2) if you read a document WHILE building it (an of_exists to check, an of_count to number), close its elements first, or keep the count yourself; (3) an of_add_xml fragment no longer has to declare its target's namespace again: one that wrote xmlns='' to leave it still can; (4) test the return of of_set_attr / of_add_child with a prefixed name, and declare the prefix (or bind it with of_register_namespace).

11.32 json: an array that builds quickly, numbers that keep their digits, an empty text that says so #

The second review of n_pbt_json removes and changes no signature. It adds the decimal and longlong overloads of of_set_number and of_add_number, and the readers of_get_decimal and of_get_longlong. Building an array with of_add_* no longer rescans the whole array on each add: 2,000 rows build in a fraction of a second instead of several minutes. Two rules are now written in the documentation, unchanged: a null string is written "" (for a JSON null, of_set_raw(path, "null")), and a key written twice is read at its FIRST occurrence.

The recipe: (1) if you tested of_load(...) = -4 to recognise an empty file, test < 0; (2) a decimal amount given to of_set_number is now written with every digit, with no change to your code; (3) read an id of more than 15 digits with of_get_longlong, an amount with of_get_decimal, no longer with of_get_number.

11.33 crosstab: of_from_datastore, refusals that say so, the displayed value on a double-click #

The second review of the crosstab renames of_set_data to of_from_datastore, the name of the datagrid and the scheduler, which read a DataStore the same way (same arguments, same codes). Any add, filter or format that names an unknown field now returns -5 instead of 0. The table only draws the columns that can be seen: a customer code or a daily date posed in Columns no longer freezes the screen. New: is_thousands, CF_ICONS, the VALUEFILTER_* and DATE_* constants.

The recipe: (1) replace of_set_data with of_from_datastore; (2) if you ignored the code returned by of_add_*_field or a filter, check < 0 — a typo finally shows; (3) in ue_cell_double_clicked, test IsNull(ad_value) before computing, and read ad_value as the displayed value (a share, not a sum, in a "%" mode).

11.34 Common base: of_count and of_keys_at count in long #

of_count returned an integer and of_keys_at took an integer rank — on every component, on their handles and on the non-visual objects that carry them (commandpalette, messagebox, speechout, toaster). Past 32,767 elements the count overflowed: a calendar (scheduler) fed from a 40,000-row DataStore could no longer be counted, and its last rows could not be walked. The four signatures are now in long: long of_count ( ), long of_count ( string as_keys ), string of_keys_at ( long al_index ), string of_keys_at ( string as_keys, long al_index ).

The recipe: a call does not change. An integer variable that receives of_count() stays right up to 32,767: declare it long. A descendant that overrode of_count or of_keys_at takes the new signature — the compiler shows you the line.

11.35 shellexplorer: a refresh that keeps the state, each row for itself #

The review of the shell explorer keeps its events: of_select, of_expand and of_collapse raise them like a click, as in 3.0. of_refresh and ib_show_files no longer close the tree. New: is_file_filter (the files shown), ib_show_hidden (hidden items, by default the Explorer setting), ib_enabled and of_refresh(path), which reads one branch again.

The recipe: (1) ue_selected and ue_expanded are raised after an of_select or an of_expand of your code too, once the folder is reached (a path still to be read arrives a little later): do your work in the event, not right behind the call, or read of_selected_key() once the selection is there; (2) in ue_selected, handle as_path = "" (the selection is gone); (3) test -5 on an empty path; (4) set ib_show_hidden = false if your users must never see hidden items, whatever their Explorer says.

11.36 commandpalette: each object only touches its own palette, a close that always says so, the application's language #

There is only one palette on screen at a time: when a second palette object opens its own, it replaces the first one. An object now answers only for its palette and its chord. ue_opened and ue_closed are still raised on of_open / of_close: they tell the life cycle of the window, not a gesture (same rule as the audio and video players). New: of_insert_command (a command at a chosen rank), of_anchor_under (the palette under a control, in screen pixels), and on the handle is_group, is_hint, is_keywords, is_icon.

The recipe: (1) if your code triggers ue_closed() itself, give it a reason (""); a script that only receives it compiles as it is; (2) if you waited for ue_opened after of_open, also handle ue_closed("cancelled"), "failed", "blocked"; (3) test 2 and -5 on the return of of_register_shortcut; (4) rename a command key that holds a comma.

11.37 radialmenu: a bare key that aims true, an open wheel that follows the application, a label that can be read #

The wheel is drawn once, and the application keeps running while it is on screen: what you change in the meantime now counts. The hub spells nothing out (it had not done so since 3.0, whatever the documentation said): the pointed branch is what shows its whole label.

The recipe: (1) of_show returns a long: a bare call compiles as it is; (2) replace of_show(-1, -1) with of_show(); (3) if you undid in ue_dismissed what you set up on opening, nothing to do: it now also comes when a wheel replaces another; (4) a handle obtained by a key two branches carry no longer changes anything: give the address.

11.38 toaster: events that say which toast, refusals that say so, a toast that waits to be seen #

The three toast events change signature, of_add_button returns a code, and a toast is no longer lost when the application is minimized.

The recipe: (1) add long al_id as the first argument of your ue_toast_clicked, ue_toast_action and ue_toast_dismissed, and replace Long(as_key) with al_id; as_key is now the key of the toast; (2) if you read the return of of_add_button as a number of buttons, read of_count(); (3) to keep a sound on an information or a success, set is_sound = SOUND_ALWAYS.

11.39 messagebox: an empty required field is never accepted, choices with unique keys #

Five behaviours change; no signature does.

The recipe: (1) a required field is now accepted by hand — if you relied on the automatic click to move on, give the field a default value (is_input_value); (2) give each choice a unique key, with no / or |, and test for -5 when your keys come from data.

11.40 Common base: the language announced by default, the decimal numbers of every machine #

Two fixes of the common base, valid for every component; no signature changes.

The recipe: nothing to change. An application that chooses its language still sees it applied; a screen reader that read a component of an English application in French now reads it in English.

11.41 Keyboard, focus and room: what the 4.0 tests put right #

Behaviours seen while playing the components in a real application; no signature changes, one method is added.

The recipe: nothing to change. An application whose focused CommandButton had to ignore Enter disables it (Enabled = false) or moves the focus away; for a large folder, replace the loop of of_add_child with one of_add_children.

11.42 Data and keyboard: what the second batch of 4.0 tests put right #

Behaviours seen while playing the data components in a real application; no signature changes.

The recipe: nothing to change. An application that handled Escape pressed in a component itself (a shortcut registered by of_register_shortcut) keeps it: a shortcut comes before the window.

11.43 Content and media: what the third batch of 4.0 tests put right #

Behaviours seen while playing the content and media components in a real application; no signature changes.

The recipe: nothing to change. An application that counted on ue_started to know that of_speak had been accepted reads its return code (0) instead; one that compares the language of ue_started with is_lang now learns about the fallback from that difference too, besides ue_voice_fallback.

11.44 Data: read a cell, sort and search more finely (json, jsontree, xmltree, crosstab) #

These 4.0 additions remove no signature. Two change what you see without you writing anything: the crosstab's Ctrl+C now copies the headers, and ue_cell_double_clicked receives one more argument.

The recipe: a script of ue_cell_double_clicked has nothing to change, the argument comes before the value. An application that pastes the result of Ctrl+C into a process that expects figures only sets ib_copy_headers = false.

11.45 Navigation and containers: tabs from the keyboard, panels on a double click (tab, dockcontainer, ribbon, stepbar, listbar) #

These 4.0 additions remove no signature. Three gestures change what a user sees without you writing anything: the middle click and Ctrl+Tab on a tab, and the double click on a dockcontainer panel or on the title bar of its floating window.

The recipe: nothing to change. In a tab page, Ctrl+Tab now changes tab even when the focus is in a control of the page, as in a Windows property sheet. To maximise a dockcontainer floating window, its Maximise button is still there.

11.46 Menus: the menu bar's chevron, a drop-down list in the toolbar, ten thousand commands (menubar, toolbar, commandpalette) #

These 4.0 additions remove no signature. One default behaviour changes: a menu bar that is too narrow no longer wraps, it folds its last titles into a chevron. And of_open of a command palette no longer refuses to open without ipo_owner or ipo_receiver.

The recipe: a menu bar whose variable height was wanted sets ib_wrap = true; an application that laid out its controls in ue_auto_height at every resize has nothing more to do after the first one. An application shortcut on Ctrl+Alt + a letter that the user's keyboard types with AltGr no longer fires while he types: choose another key.

11.47 Content and media: a log line by line, the actual size of a picture, a film that waits (statictext, picture, video) #

These 4.0 additions remove no signature and change no default. Two behaviours become more precise: the zoom of a picture may go past its ceiling to reach the actual size, and a film from a URL played without a network says so.

The recipe: nothing to change. A log that rewrote is_text at every line moves to of_append_text; code that tested REASON_UNSUPPORTED for a film from a URL without a network tests REASON_NETWORK.

11.48 Review of 03/10/2026: a layout put back is announced, an export to a relative path lands in the right place (toolbar, crosstab) #

No signature changes. Two behaviours line up with the rule of the library: every change of the layout is announced, and a relative path to write to is resolved as for the other exports.

The recipe: an application that saves the layout in ue_layout_changed saves the same value again after of_set_layout — harmless. An export that relied on the current folder of the moment gives a full path.

← Migrating from 2.0 to 3.0 · Contents · Release notes →