9. Migrar da 1.0 para a 2.0 #

← Licença e modo de demonstração · Índice · Migrar da 2.0 para a 3.0 →

A 2.0 traz cinco componentes e remodela a API dos dezasseis da 1.0. A remodelação resume-se a três regras; quase todos os erros de compilação que verá decorrem delas. Esta página dá as regras, um antes/depois e depois, componente a componente, cada assinatura retirada ou alterada. Os componentes ausentes das tabelas — button, messagebox, picture, pdfviewer, progressbar, webbrowser — não perderam nada.

9.1 As três regras #

1. Uma chave, um endereço. O identificador de um item chama-se as_key — um só nível, único sob o seu pai. Um item aninhado é alcançado por um endereço as_keys, os níveis unidos por /: "home/clipboard/paste". Os eventos devolvem esse endereço em um argumento, onde a 1.0 passava três (as_tab, as_group, as_id). Para o dividir: n_pbt_utils.of_split_path (as_keys, ref as_out[]).

2. Tudo se faz a partir do componente. Um handle (n_pbt_ribbon_group, n_pbt_toolbar_bar, n_pbt_tilesbox_group, n_pbt_listbar_section…) já não adiciona nada: adições e remoções estão no componente, com o endereço do pai. Os getters têm o nome do nível — of_tab, of_group, of_item, of_menu_item na faixa de opções, of_panel no dock e na barra de estado, of_page no tab, of_section na listbar, of_bar na toolbar, of_tile no tilesbox. Um handle serve agora apenas para ler e definir propriedades.

3. Uma adição devolve um código, não um handle. of_add_tab, of_add_group, of_add_bar, of_add_section… devolvem um long: 0 depois de aplicado, -5 perante um endereço errado (pai ausente, ou de outra natureza, chave vazia), -2 se o componente não estiver criado. Um handle não podia dizer que tinha recusado; um código pode. Quando há uma propriedade a definir, o getter dá o handle logo a seguir.

9.2 Antes / depois #

// 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

E o evento resultante:

// 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 ...

As propriedades dos handles (ib_enabled, is_text, is_image, ib_visible…) e o motor de propriedades não mudam: o que muda é a forma de chegar ao handle, não o que se faz com ele.

9.3 A receita #

1. Migre uma cópia das suas bibliotecas, como para qualquer mudança de versão do PowerBuilder — ver Primeiros passos. Substitua pbtoolboxai.pbl pelo da 2.0.
2. Lance um Full Build. Cada chamada a corrigir surge como erro de compilação, com o objeto e o script: a lista fica completa à primeira, nada há a adivinhar.
3. Corrija as chamadas com as tabelas da secção 9.4: um handle que adicionava passa a ser o componente mais o endereço; um lnv_x = of_add_… passa a ser uma chamada nua, e o handle obtém-se depois pelo getter do nível.
4. Nos seus scripts de eventos os argumentos mudaram de nome e de número — as_tab, as_group, as_id passam a as_keys. O PowerBuilder assinala cada referência a um argumento desaparecido; substitua a comparação de três valores pela de um endereço.
5. As funções internas renomeadas para xx_ (of_on_item_property, of_ensure_created, xx_of_send, o of_init dos handles) só lhe dizem respeito se tiver derivado um componente ou um handle e redefinido uma delas.

9.4 Componente a componente #

Nas tabelas, lnv_tab, lnv_group, lnv_item, lnv_bar, lnv_section, lnv_tile designam um handle da 1.0; uo o componente. Um endereço entre aspas mostra os níveis esperados. Os parâmetros inalterados são abreviados por ….

Base comum (todos os componentes) #

Ribbon #

Toolbar #

Tiles box #

Listbar #

Statusbar #

Tab #

Dock container #

Toaster, Statictext, Code editor #

← Licença e modo de demonstração · Índice · Migrar da 2.0 para a 3.0 →