9. Migrating from 1.0 to 2.0 #

← License and demo mode · Contents · Migrating from 2.0 to 3.0 →

2.0 brings five components and reshapes the API of the sixteen from 1.0. The reshaping comes down to three rules; nearly every compile error you will see follows from them. This page gives the rules, a before/after, then, component by component, every signature removed or changed. The components absent from the tables — button, messagebox, picture, pdfviewer, progressbar, webbrowser — have lost nothing.

9.1 The three rules #

1. One key, one address. An item's identifier is called as_key — one level, unique under its parent. A nested item is reached through an address as_keys, levels joined by /: "home/clipboard/paste". Events hand that address back in one argument, where 1.0 passed three (as_tab, as_group, as_id). To split it: n_pbt_utils.of_split_path (as_keys, ref as_out[]).

2. Everything is done from the component. A handle (n_pbt_ribbon_group, n_pbt_toolbar_bar, n_pbt_tilesbox_group, n_pbt_listbar_section…) no longer adds anything: additions and removals live on the component, with the parent's address. Getters are named after the level — of_tab, of_group, of_item, of_menu_item on the ribbon, of_panel on the dock and the status bar, of_page on the tab, of_section on the listbar, of_bar on the toolbar, of_tile on the tiles box. A handle is now only for reading and setting properties.

3. An addition returns a code, not a handle. of_add_tab, of_add_group, of_add_bar, of_add_section… return a long: 0 once applied, -5 on a wrong address (parent missing, or of another kind, empty key), -2 when the component is not created. A handle could not say it had refused; a code can. When a property is to be set, the getter gives the handle right after.

9.2 Before / after #

// 1.0
n_pbt_ribbon_tab   lnv_tab
n_pbt_ribbon_group lnv_group
lnv_tab   = uo_ribbon.of_add_tab("home", "Home")
lnv_group = lnv_tab.of_add_group("clip", "Clipboard")
lnv_group.of_add_button("paste", "Paste", "img/paste.svg")
lnv_group.of_item("paste").ib_enabled = false

// 2.0
uo_ribbon.of_add_tab("home", "Home")
uo_ribbon.of_add_group("home/clip", "Clipboard")
uo_ribbon.of_add_button("home/clip/paste", "Paste", "img/paste.svg")
uo_ribbon.of_item("home/clip/paste").ib_enabled = false

And the event that follows:

// 1.0
event ue_clicked (string as_tab, string as_group, string as_id)
   if as_tab = "home" and as_group = "clip" and as_id = "paste" then ...

// 2.0
event ue_clicked (string as_keys)
   if as_keys = "home/clip/paste" then ...

Handle properties (ib_enabled, is_text, is_image, ib_visible…) and the property engine are unchanged: what moves is how you reach the handle, not what you do with it.

9.3 The recipe #

1. Migrate a copy of your libraries, as for any PowerBuilder version change — see Getting started. Replace pbtoolboxai.pbl with the 2.0 one.
2. Run a Full Build. Every call to fix comes out as a compile error, with the object and the script: the list is complete on the first pass, nothing to guess.
3. Fix the calls with the tables of section 9.4: a handle that added becomes the component plus the address; an lnv_x = of_add_… becomes a bare call, and the handle is then taken from the level's getter.
4. In your event scripts the arguments changed name and number — as_tab, as_group, as_id become as_keys. PowerBuilder flags each reference to a vanished argument; replace the three-value comparison with an address comparison.
5. The internal functions renamed to xx_ (of_on_item_property, of_ensure_created, xx_of_send, the handles' of_init) only concern you if you derived a component or a handle and overrode one of them.

9.4 Component by component #

In the tables, lnv_tab, lnv_group, lnv_item, lnv_bar, lnv_section, lnv_tile stand for a 1.0 handle; uo for the component. A quoted address shows the levels expected. Unchanged parameters are shortened to ….

Shared foundation (every component) #

Ribbon #

Toolbar #

Tiles box #

Listbar #

Statusbar #

Tab #

Dock container #

Toaster, Statictext, Code editor #

← License and demo mode · Contents · Migrating from 2.0 to 3.0 →