10. Migrating from 2.0 to 3.0 #
← Migrating from 1.0 to 2.0 · Contents · Migrating from 3.0 to 4.0 →
3.0 removes no signature from the twenty-one components of 2.0 and changes none: your code compiles as it is. What changes is a handful of behaviours, and only one of them asks you to read your code again — positions, which now count from 1, like everything PowerBuilder counts. This page gives that change first, with the recipe, then the other behaviours a customer can notice, then what was added.
10.1 Positions count from 1 #
In 2.0, a position passed to a method (of_move_page(key, ai_index)…) started at 0, while the position returned by a reorder event (ue_tab_reordered(key, ai_index)…) started at 1: an index you received could not be handed back as it was. In 3.0, everything starts at 1 — 1 is the first place. The events did not change; the methods and properties joined them.
| What | 2.0 | 3.0 |
|---|---|---|
| tab | of_insert_page, of_move_page : 0 | 1 |
| listbar | of_insert_section, of_move_section, of_insert_item, of_move_item : 0 | 1 |
| toolbar | of_add_bar(key, band, index), of_move_item, of_insert_button, ii_band, ii_index : 0 | 1 |
| statusbar | of_insert_panel, of_move_panel, of_insert_menu_item, of_move_menu_item : 0 | 1 |
| stepbar | of_insert_step, of_move_step : 0 | 1 |
| tilesbox | of_insert_tile, of_move_tile, event ue_tile_moved : 0 | 1 |
| dockcontainer | of_move_panel(key, target, position, index): 0, -1 = last | 1, 0 or less = last |
| ribbon | of_insert_tab : 0 | 1 |
The ue_tab_reordered, ue_item_reordered and ue_bar_reordered events already returned a position from 1: they are unchanged. For a statusbar or stepbar insertion, a position of 0 or less appends at the end (like a negative index in 2.0); for a move, it means the first place.
Before / after #
// 2.0 : the first place was 0
uo_tabs.of_move_page(/*key*/ "orders", /*index*/ 0)
uo_toolbar.of_add_bar(/*key*/ "format", /*band*/ 1, /*index*/ 0)
uo_toolbar.of_bar(/*key*/ "format").ii_band = 0
// 3.0 : the first place is 1
uo_tabs.of_move_page(/*key*/ "orders", /*index*/ 1)
uo_toolbar.of_add_bar(/*key*/ "format", /*band*/ 2, /*index*/ 1)
uo_toolbar.of_bar(/*key*/ "format").ii_band = 1The recipe #
Search your code for of_insert_, of_move_, of_add_bar(, .ii_band and .ii_index: add 1 to every position you write as a literal. A position that comes from a reorder event or from a for li = 1 to … loop is already right — that is the whole point of the change. A position computed from 0 (li - 1) loses its - 1.
10.2 Cascaded entries return their full address #
An entry placed in a submenu is now named by its whole address, the one you gave to add it. In 2.0 the event lost the submenu level, and two submenus holding an entry of the same name were confused.
| What | 2.0 | 3.0 |
|---|---|---|
toolbar ue_menu_selected | "file/saveas/png8" | "file/saveas/fmt_other/png8" |
ribbon ue_menu_selected | "home/clip/paste/pdf" | "home/clip/paste/more/pdf" |
ribbon ue_app_menu_selected | "pdf" | "export/pdf" |
menubar ue_item_selected | "export/pdf" (print/pdf chosen) | "print/pdf" |
radialmenu of_item("csv"), of_add_item("import/csv/x") | the first csv found | the address decides |
A first-level menu entry has one level and does not change. And the toolbar's of_add_menu_item finally accepts the four-level address ("bar/dropdown/entry/sub") the documentation showed: it was refused with -5.
10.3 Other behaviours you may notice #
| What | 2.0 | 3.0 |
|---|---|---|
Rich text ([b], [accent]…) | an unknown [word] vanished with the text after it: report[final].pdf → report.pdf | shown as it is; only the real tags are interpreted |
statusbar ue_panel_rclicked(al_x, al_y) | pixels inside the component | screen pixels, as promised: pass them straight to a context menu |
Reading a colour back (il_text_color, il_accent…) | returned 0 (black), set or not | the colour set; -1 when none (the theme's). An unset badge colour still returns 0 |
code editor ii_doc_line, read back | the internal index (line − 1, -1 = none) | the line set; 0 = none |
picture and shell explorer ue_error | never raised (intercepted by the foundation) | raised; script errors stay on ue_script_error |
The button component is still shipped and supported, but it is deprecated in favour of buttonbar: a row of buttons fits in a single component, where ten button make ten.
10.4 What was added #
None of the following asks you to change your code. The new components of 3.0 are presented in the release notes.
| Object | Added |
|---|---|
u_pbt_base (every visual component) | of_set_property (string as_name, string as_value) → long, of_get_property (string as_name) → string, of_component_name () → string |
n_pbt_messagebox | of_add_choice (string as_key, string as_title, string as_description) → long, of_choose (long al_hwnd) → string |
n_pbt_utils | of_dir_has_subfolders (string as_dir) → boolean, of_speech_languages (ref string as_tags[]) → integer, of_speech_voices (ref string as_names[], ref string as_langs[]) → integer, of_locale_name (string as_tag) → string |
n_pbt_json, which 2.0 shipped as an undocumented internal tool, becomes the json component of 3.0 and changes names: of_str → of_add_string, of_bool → of_add_boolean, of_num → of_add_number, of_raw → of_add_raw, of_arr → of_set_array, of_members → of_set_members; all of them now return a long. If your code used it, these are the only names to change.
← Migrating from 1.0 to 2.0 · Contents · Migrating from 3.0 to 4.0 →