12. Migrar da 4.0 para a 5.0 #

← Migrar da 3.0 para a 4.0 · Índice · Notas de versão →

A 5.0 não muda nenhuma assinatura dos trinta e sete componentes da 4.0, nem nenhum evento — exceto a barra de botões (buttonbar, 12.7) e o evento ue_link_clicked do visualizador Markdown (markdownview), que recebe um segundo argumento, as_kind (12.5). Três componentes mudam de palavras. A barra de progresso (progressbar) adota as dos indicadores — ib_label, il_color e is_label_format desaparecem a favor de ib_show_value, il_value_color, is_format e is_unit (12.1). O gráfico cartesiano (chartcartesian) escreve os seus números através de is_format, como os indicadores e o gráfico circular: of_set_value_format e of_clear_value_format desaparecem, e ii_point_count de uma série passa a il_point_count (12.4). A tabela dinâmica (crosstab) segue o mesmo caminho: of_set_value_format e of_clear_value_format desaparecem a favor de is_format — no campo, ou num só valor através de of_value — e de ib_negative_red (12.8). O compilador mostra-lhe cada linha a rever. A barra lateral (listbar) muda um evento: ue_item_rclicked recebe também o ponto do ecrã do clique, al_x e al_y (12.9). O painel de mosaicos (tilesbox) renomeia um evento: ue_tile_context(as_keys) passa a ue_tile_rclicked(as_keys, al_x, al_y), e a posição de of_move_tile e de of_insert_tile passa a long al_position (12.12). O menu radial (radialmenu) perde quatro propriedades de dica que nunca mostrou — is_tooltip, is_super_tooltip_title, is_super_tooltip_text e is_super_tooltip_image (12.5). O calendário (scheduler) muda três eventos de gesto: ue_appointment_changing recebe as_kind, ue_appointment_moved e ue_appointment_resized recebem os valores anteriores (12.10). O explorador da shell (shellexplorer) muda um evento: ue_error recebe também o caminho e um motivo constante, as_path e as_reason (12.11). O bloco de texto formatado (statictext) muda um evento: ue_hyperlink recebe também ab_opened, se a hiperligação se abriu de facto (12.5). O separador (tab) muda um evento: ue_tab_rclicked recebe também o ponto do ecrã do clique, al_x e al_y (12.13). O leitor de sons (soundplayer) muda três eventos: ue_started, ue_ended e ue_failed recebem também o número do som, al_sound (12.14). O toaster (toaster) muda um evento: ue_toast_dismissed recebe também o motivo do fecho, as_reason (12.15). O navegador web (webbrowser): of_go_back, of_go_forward e of_stop devolvem um long, e com ib_veto_navigation um endereço escrito pelo utilizador é perguntado a ue_navigating (12.17). A barra de ferramentas (toolbar) muda um evento: ue_item_rclicked recebe também o ponto do ecrã do clique, al_x e al_y (12.18). O leitor de vídeo (video) muda uma assinatura: of_stop passa a função que devolve um long (12.16) — uma chamada escrita como instrução continua a compilar. Três componentes mudam um evento de clique direito de um item, que recebe também o seu ponto do ecrã al_x, al_y: a barra de botões (ue_button_rclicked), o trilho de navegação (breadcrumb, ue_item_rclicked) e o gráfico cartesiano (ue_point_rclicked); a barra de estado (statusbar) dá esse ponto como os outros, sem o multiplicar pela escala do ecrã (12.19). A base (12.20): o motivo da falha de um componente não visual lê-se com of_get_last_error() — a propriedade is_last_error desaparece de crypto, restclient, soundplayer, speechout, xml, u_pbt_regex e u_pbt_zip —, e of_stop, of_close e of_reset dos componentes não visuais devolvem um long.

O resto não pede nada ao seu código: a grelha de dados (datagrid) e o friso (ribbon) ganham máscaras de entrada numéricas, e o editor de uma coluna numérica da grelha abre agora sobre o texto da máscara (12.2, 12.3). Os novos componentes da 5.0 são apresentados nas notas de versão.

12.1 progressbar: as palavras dos indicadores #

A 5.0 traz dois indicadores, linear (gauge) e de mostrador (angulargauge). Uma barra de progresso também mostra um valor numa escala: a biblioteca passa a falar uma só língua para isso, e a barra, que dizia o mesmo por outras palavras, adota as palavras dos indicadores. Nenhum nome antigo sobrevive: nem uma propriedade, nem um nome aceite por of_set_property.

• is_format é um formato de apresentação PowerBuilder aplicado ao valor ("#,##0", "$#,##0.00"), com os separadores do idioma de apresentação, exatamente como nos indicadores. Vazio, a barra mostra a percentagem, como antes.
• Os marcadores {percent}, {value}, {min} e {max} deixaram de existir. Uma etiqueta que misturava valor e percentagem ("{value} of {max} rows ({percent})") não tem equivalente exato: escolha o valor (formato e unidade) ou a percentagem (e uma unidade). O máximo, que o seu código conhece, escreve-se na unidade.
• is_unit é novo: um texto simples escrito depois da leitura, separado por um espaço — depois do valor como depois da percentagem. of_reset esvazia-o.
• Uma máscara que contém % escreve a parte concluída, não o valor: is_format = "0.0%" dá «35.0%» para 1 687 linhas de 4 820, arredondada por defeito como a percentagem — a percentagem com casas decimais que {percent} não sabia escrever.
• Uma espera em pausa ou em erro torna-se uma barra cheia. Na 4.0, uma barra de espera (ib_indeterminate) que recebia STATE_PAUSED ou STATE_ERROR ficava parada a meio do deslize, muitas vezes fora da pista: a falha não se via. Na 5.0 para como barra (anel) cheia da cor do estado, como a barra de tarefas do Windows, e o leitor de ecrã já não a anuncia ocupada, diz o seu estado.
• of_set_property("tooltip", …) e super_tooltip_* devolvem -5: a barra não publica tooltip, e a porta pelo nome, que punha um, está fechada como as propriedades.
• Novidade, sem nada a rever: is_orientation (ORIENTATION_VERTICAL: uma barra de pé, em vez de uma VProgressBar), is_accessible_name (o nome que o leitor de ecrã diz) e o texto de uma espera (só is_unit enquanto a barra está em espera).

// 4.0 : the label wrote the value through placeholders
uo_progress.ib_label        = true
uo_progress.il_color        = RGB(/*red*/ 0, /*green*/ 120, /*blue*/ 215)
uo_progress.is_label_format = "{value} of {max} rows"

// 5.0 : the words of the gauges - a display format for the value, then a unit
uo_progress.ib_show_value  = true
uo_progress.il_value_color = RGB(/*red*/ 0, /*green*/ 120, /*blue*/ 215)
uo_progress.is_format      = "#,##0"
uo_progress.is_unit        = "of 500 rows"

A receita: compile; cada ib_label, il_color e is_label_format de uma barra de progresso é assinalado. Substitua os dois primeiros por ib_show_value e il_value_color. Para o terceiro: um texto vazio continua vazio em is_format; uma etiqueta que escrevia o valor passa a um formato ("#,##0") e uma unidade; uma etiqueta que escrevia a percentagem deixa is_format vazio e põe o seu texto em is_unit. Um of_set_property que nomeava label, label_format ou color devolve agora -5 e não faz nada (of_get_last_error nomeia a propriedade): procure esses nomes no seu código.

12.2 datagrid: um editor numérico que escreve através de uma máscara #

Nenhuma assinatura muda, e ue_cell_edited continua a receber o número simples (1234.5). O que muda vê-se no ecrã: a escrita numa coluna numérica segue agora uma máscara de entrada, na sintaxe do DataWindow — a que indica pela nova propriedade is_mask da coluna, senão o seu formato de apresentação despojado dos literais.

// 5.0 : the input mask of a numeric column - the cell still receives the bare number
uo_grid.of_column(/*key*/ "revenue").is_mask = "#,##0.00"

A receita: nada a mudar. Um código que lia o texto escrito não o vê: ue_cell_edited continua a devolver o número. Uma coluna cuja escrita deve ficar livre (um código, um número de peça) é uma coluna de texto, não numérica.

12.3 ribbon: as máscaras de um contador #

Nada muda para um contador sem máscara. Duas novas propriedades do seu handle, na sintaxe do PowerBuilder: is_mask, a máscara de entrada ("#,##0.00", "0%"), e is_format, o formato de apresentação com os seus literais (0 "pt" mostra 11 pt, que se escreve 11). id_value e ue_value_changed mantêm o número simples, a troca entre os dois não levanta nenhum evento, e as máscaras seguem o contador no painel de um grupo recolhido.

// 5.0 : a font size shown "11 pt", typed "11"
uo_ribbon.of_item(/*keys*/ "home/font/size").is_format = "0 ~"pt~""

A receita: nada a mudar.

12.4 chartcartesian: o formato dos números através de is_format #

O gráfico cartesiano escrevia os seus números através de uma função de quatro argumentos (casas decimais, prefixo, sufixo, separador de milhares). A 5.0 põe gráficos e indicadores sob uma só língua: um formato de apresentação PowerBuilder, o de uma coluna de DataWindow, na propriedade is_format — do gráfico inteiro, e de um eixo através do seu handle. As secções positivo;negativo;zero, os literais e a percentagem vêm com ele, e os separadores continuam a ser os do idioma de apresentação. Nenhum nome antigo sobrevive.

• O formato de um eixo prevalece sobre o do gráfico, e mantém-no. Definir o formato do gráfico já não apaga o dos eixos (a forma de of_set_value_format sem eixo fazia-o): um eixo volta ao formato do gráfico com is_format = "".
• Sem formato (vazio, ou um formato que não é numérico), o número escreve-se tal como está, à milésima, com o separador decimal do idioma de apresentação — como fazia o formato predefinido.

// 4.0 : decimals, prefix, suffix and thousands as four arguments
uo_chart.of_set_value_format(/*decimals*/ 0, /*prefix*/ "$", /*suffix*/ "K", /*thousands*/ true)
uo_chart.of_set_value_format(/*axis*/ u_pbt_chartcartesian.AXIS_VALUE2, /*decimals*/ 1, /*prefix*/ "", /*suffix*/ " u", /*thousands*/ false)

// 5.0 : a display format, written as in a DataWindow - for the chart, then for one axis
uo_chart.is_format = "$#,##0K"
uo_chart.of_axis(/*axis*/ u_pbt_chartcartesian.AXIS_VALUE2).is_format = '0.0" u"'

A receita: compile; cada of_set_value_format e of_clear_value_format é assinalado. Escreva o formato como numa DataWindow: decimals dá o número de 0 depois do ponto (-1 = #,##0.###), thousands a , do agrupamento, o prefixo e o sufixo escrevem-se antes e depois (entre aspas se contiverem algarismos ou espaços). O formato de um eixo vai para of_axis(<eixo>).is_format.

12.5 Outros comportamentos que pode ver #

A receita: nada a mudar.

12.6 O que foi acrescentado #

Nada do que se segue pede para alterar o seu código. Os oito novos componentes da 5.0 são apresentados nas notas de versão.

12.7 buttonbar: chave, rótulo e depois ícone; o « & » e o atalho #

A barra de botões falava de forma diferente do resto da biblioteca: o ícone antes do rótulo, a posição como segundo argumento, e um is_shortcut que queria dizer « letra Alt » onde em todo o lado quer dizer « atalho » — is_shortcut = "Ctrl+S" armava Alt+C. A 5.0 alinha-a com button, a barra de ferramentas e o CommandButton do PowerBuilder.

• is_shortcut de um botão é um atalho. Durante a 5.0, uma letra sozinha ainda é lida aí como a letra Alt da 4.0 (passa para is_mnemonic); escreva antes o « & » no rótulo. Um atalho que a janela nunca pode lançar (uma letra sozinha, Ctrl+Shift) é recusado: is_shortcut relê-se vazio, of_register_shortcut devolve -5.
• Um botão desativado já não rouba uma tecla. O botão predefinido desativado de uma barra, ou a letra Alt de um botão desativado, deixa o Enter e a letra para a janela — já não vão para o botão de OUTRA barra (duas folhas MDI); o atalho de um botão desativado deixa a sua tecla para a janela (um acelerador de menu, por exemplo). As setas saltam um botão desativado.

// 4.0 : the icon before the label
uo_bar.of_add_button(/*key*/ "save", /*image_file*/ "img\save.png", /*text*/ "Save")

// The Alt letter went to is_shortcut (the letter S alone), the chord to of_register_shortcut
uo_bar.of_register_shortcut(/*chord*/ "Ctrl+S", /*key*/ "save")

// 5.0 : key, label, icon - the "&" of the label gives Alt+S
uo_bar.of_add_button(/*key*/ "save", /*text*/ "&Save", /*image*/ "img\save.png")

// The chord is a property of the button, shown in its tooltip
uo_bar.of_button(/*key*/ "save").is_shortcut = "Ctrl+S"

A receita: compile; uma chamada de of_insert_button é assinalada (a posição passa para o fim). Um of_add_button de três argumentos continua a compilar: troque os dois últimos (o rótulo e depois o ícone) — um botão cujo rótulo é um caminho de ficheiro mostra-lhe os que faltam. Substitua cada is_shortcut de uma letra por um « & » no rótulo, e duplique todo o « & » que deva ser mostrado (R&&D).

12.8 crosstab: o formato dos valores através de is_format #

A tabela dinâmica escrevia os números de uma medida através de uma função de quatro ou cinco argumentos (casas decimais, separador de milhares, símbolo, símbolo antes), que valia para todos os valores de um campo: o mesmo campo duas vezes em Valores — o montante, e a sua parte do total — não podia ter dois formatos. A 5.0 põe-no sob a língua dos gráficos e dos indicadores: um formato de apresentação PowerBuilder em is_format, no handle do campo (of_field) para todos os seus valores, ou no handle de um valor (of_value(position), novo) só para ele. Vazio, um valor recebe o Format da coluna do DataWindow. Nenhum nome antigo sobrevive.

• O separador de milhares de um valor sem formato continua a ser is_thousands, como o menu Opções da grelha: é o que fazia um of_set_value_format com separador vazio. A moeda que o menu do chip propõe continua a ser is_currency_symbol.
• Um valor sem formato mostra agora o Format da sua coluna do DataWindow, lido por of_from_datastore: um montante cuja coluna tem #,##0.00 aparece com duas casas decimais sem uma linha de código.

// 4.0 : decimals, thousands, symbol and its side as arguments - for every value of the field
uo_cross.of_set_value_format(/*field*/ "amount", /*decimals*/ 2, /*thousands*/ "locale", /*suffix*/ "$", /*symbol_before*/ true)

// 5.0 : a display format, written as in a DataWindow - for the field, then for its second value alone
uo_cross.of_field(/*field*/ "amount").is_format = "$#,##0.00"
uo_cross.of_value(/*position*/ 2).is_format = "#,##0"

A receita: compile; cada of_set_value_format e of_clear_value_format é assinalado. Escreva o formato como numa DataWindow: ai_decimals dá o número de 0 depois do ponto, um separador de milhares dá a , do agrupamento ("none": nenhum), o símbolo escreve-se antes ou depois (entre aspas se contiver algarismos ou espaços). O formato de um só valor vai para of_value(<posição>).is_format.

12.9 listbar: o clique direito traz o seu ponto, uma disposição anuncia-se #

A barra lateral junta-se à biblioteca em três pontos: o clique direito de uma entrada dá o seu ponto do ecrã como o das árvores, das grelhas e do kanban; uma ordem do código que muda a disposição anuncia-a como um gesto; uma entrada desativada já não se torna a seleção. Ganha também um evento para o clique na entrada já selecionada, uma pesquisa e a construção a partir de um DataStore (12.6).

// 4.0 : PointerX() of the userobject - the menu opened too high under a ribbon
m_entry.PopMenu(PointerX(), PointerY())

// 5.0 : the pointer of the WINDOW for a PowerBuilder menu (al_x, al_y serve a menu of the library)
m_entry.PopMenu(parent.PointerX(), parent.PointerY())

A receita: nada se recusa a compilar — um script de ue_item_rclicked mantém as_keys. Abra o seu menu no ponteiro da janela (parent.PointerX()), ou passe al_x, al_y a of_show de um contextmenu. Defina a seleção inicial antes de ativar ib_veto_selection, e verifique que o seu ue_layout_changed aceita a chamada que of_set_layout dispara agora.

12.10 scheduler: a natureza de uma alteração e os valores anteriores #

O calendário junta-se ao diagrama de Gantt: a pergunta feita antes de um gesto diz se se trata de uma deslocação ou de um redimensionamento, e os eventos que se seguem dão os valores anteriores — um registo, uma anulação ou uma confirmação já não têm de guardar a sua própria cópia de cada compromisso. Uma seleção que o seu código retira é anunciada, e quatro chamadas recusam agora o que aceitavam em silêncio.

// 5.0 : ue_appointment_changing event of uo_sched : (string as_key, string as_kind, string as_start, string as_end, string as_resource) returns boolean
// A resize keeps the day : only a move is checked
if as_kind = u_pbt_scheduler.CHANGE_RESIZE then return true

// Nothing on a Saturday or a Sunday : returning false puts the appointment back
if DayNumber(Date(Left(as_start, 10))) = 1 or DayNumber(Date(Left(as_start, 10))) = 7 then return false
return true

A receita: nada se recusa a compilar — um script de ue_appointment_changing, ue_appointment_moved ou ue_appointment_resized mantém os seus argumentos, os novos acrescentam-se. Se o seu ue_selection_changed ativa botões, recebe agora "" quando o compromisso selecionado desaparece; reveja os códigos de retorno de of_add_appointment, of_scroll_to_time, of_set_field e of_show_appointment, que podem agora devolver -5. Para gravar os gestos sem código, veja ib_write_back.

12.11 shellexplorer: o erro diz o seu motivo #

O explorador da shell dá agora, em ue_error como em ue_path_not_found, um motivo que o seu código pode testar — uma constante REASON_* de u_pbt_shellexplorer, a mesma em todas as línguas do Windows. Já não dispara ue_selected para a pasta já seleccionada, e anuncia com ue_collapsed um ramo que fecha por si. Ganha também o clique direito numa pasta (ue_node_rclicked) e o endereço da raiz.

// 5.0 : ue_error event of uo_tree : (string as_path, string as_reason, string as_message)
// Test the reason, never the text of the shell
if as_reason = u_pbt_shellexplorer.REASON_TIMEOUT then
    st_status.text = "The network folder " + as_path + " does not answer"
else
    st_status.text = as_message
end if

A receita: nada se recusa a compilar — um script de ue_error mantém as_message, os novos argumentos acrescentam-se. Um teste sobre o TEXTO de as_reason em ue_path_not_found ("not found", "outside the root") reescreve-se com uma constante REASON_*; uma aplicação que recarregava um painel em cada ue_selected fá-lo agora uma vez por mudança.

12.12 tilesbox: o clique direito traz o seu ponto, uma ordem do código anuncia-se, a disposição deixa os direitos à aplicação #

O painel de mosaicos junta-se à biblioteca: o seu clique direito dá o ponto do ecrã como o das árvores, das grelhas e do kanban; uma ordem do código que desloca um mosaico, recolhe um grupo ou muda um tamanho lança os mesmos eventos que um gesto; a disposição já não transporta a visibilidade, que continua a ser assunto da aplicação. Ganha também o deslocamento de um mosaico para outro grupo a partir do código (12.6).

// 4.0 : the right click of a tile
// ue_tile_context event of uo_tiles : (string as_keys)

// 5.0 : the same script, under the new name, with the screen point
// ue_tile_rclicked event of uo_tiles : (string as_keys, long al_x, long al_y)

A receita: compile; o seu script de ue_tile_context fica num evento que já não existe — mova-o para ue_tile_rclicked, que mantém as_keys. Se o seu ue_layout_changed guarda a disposição, vê agora também o que o seu código muda; um ue_tile_moved que só deve reagir ao utilizador ignora os deslocamentos que o seu código acabou de fazer. Se guardava a visibilidade na disposição, defina-a pelo código na abertura (ib_visible), segundo os direitos.

12.13 tab: o clique direito traz o seu ponto, uma disposição aplicada anuncia-se #

O separador junta-se à biblioteca: o clique direito de um separador, com o menu integrado desligado, dá o seu ponto do ecrã como o das árvores, das grelhas e do kanban, e of_set_layout que muda a disposição anuncia-a como um gesto. Um arrasto devolvido ao seu lugar já não anuncia nada. Ganha também páginas criadas a pedido (ue_page_needed, of_supply_page), o duplo clique (ue_tab_double_clicked), ib_cycle_keys, is_close_mode, ii_strip_width e, numa página, ib_modified e is_badge — ver a página do separador.

// 4.0 : the right click of a tab, built-in menu off
// ue_tab_rclicked event of uo_tabs : (string as_key)

// 5.0 : the same script, with the screen point
// ue_tab_rclicked event of uo_tabs : (string as_key, long al_x, long al_y)

A receita: nada se recusa a compilar — um script de ue_tab_rclicked mantém as_key. Abra o seu menu no ponteiro da janela (parent.PointerX()), ou passe al_x, al_y a of_show de um contextmenu. Verifique que o seu ue_layout_changed aceita a chamada que of_set_layout agora lhe faz.

12.14 soundplayer: o número de um som, uma recusa devolvida de imediato #

O leitor de sons muda três coisas que o seu código pode ver. Os seus eventos transportam o número do som: ue_started, ue_ended e ue_failed recebem um último argumento, al_sound — o número que of_play_over e of_enqueue devolvem agora (devolviam 0), e que o novo of_stop_sound aceita. Uma fonte recusada de imediato é um código: of_play, of_play_over, of_crossfade e of_preload devolvem -5, a razão em of_get_last_error(), para uma fonte vazia, um endereço http://, um endereço file:// mal formado ou um formato recusado pelo nome — e já não disparam ue_failed; o som em curso continua. Na fila (of_enqueue), a recusa chega sempre por ue_failed, na sua vez. Outros -5: of_pause e of_resume sem nada a suspender ou retomar, of_beep e of_beep_sync a 0 Hz ou 0 ms, of_meter fora de 1 a 64 barras.

// Local variables
string ls_url
long ll_rc

// The address of the sound, typed by the user
ls_url = sle_url.text

// 4.0 : of_play returned 0, and an http:// address came back later through ue_failed
// 5.0 : the refusal is a code, at once ; of_get_last_error() gives the reason
ll_rc = inv_sound.of_play(/*source*/ ls_url)
if ll_rc = -5 then
	MessageBox("Sound", inv_sound.of_get_last_error())
end if

O que muda sem pedir nada ao seu código: of_stop apaga-se agora sobre il_fade_ms, como a documentação prometia (ue_stopped continua a chegar de imediato); no fim de il_timeout_ms, só o som da chamada síncrona é cortado — o fundo, as sobreposições e a fila continuam; of_crossfade para uma fonte recusada mantém a faixa em curso; of_level vale 0 e of_spectrum não devolve nenhuma barra, com o medidor desligado; of_equalizer(ab_on, ai_gains[]) repõe a 0 uma banda que o array não alcança; of_clear_queue esquece também os sons que a fila já tocou; as mensagens de ue_failed seguem a língua de apresentação (as_reason continua a ser a palavra a testar). O leitor ganha também a fila navegável (of_next, of_previous, of_queue_index, ue_source_changed, ib_queue_repeat), o ciclo sem interrupções (ib_gapless_loop, REASON_TOO_LONG), o segmento (of_play_range), o silêncio (ib_muted) e o armazenamento em memória tampão (ue_buffering, of_is_buffering) — ver a página do leitor de sons.

A receita: nada se recusa a compilar — um script de ue_started, ue_ended ou ue_failed mantém os seus argumentos, al_sound acrescenta-se. Reveja os testes do código de retorno de of_play_over e of_enqueue (um = 0 passa a > 0), e o código que esperava ue_failed para um endereço http:// ou uma fonte vazia: testa agora o -5 da chamada.

12.15 toaster: o motivo de um fecho, um toast fechado pelo código anuncia-se sempre #

O toaster diz porque é que um toast se fechou: ue_toast_dismissed recebe um último argumento, as_reason — REASON_TIMEOUT, REASON_USER (a sua cruz), REASON_CODE (of_close, of_close_all) ou REASON_OWNER_CLOSED (a sua window fechou-se). E todo o toast fechado pelo código o anuncia, mesmo fechado logo após of_show, antes de ser desenhado, ou enquanto esperava o seu lugar: uma aplicação que esperava ue_toast_dismissed para libertar o seu estado já não depende de uma corrida.

// 4.0
// event ue_toast_dismissed de inv_toaster : (long al_id, string as_key)

// 5.0 : o mesmo script, com o motivo
// event ue_toast_dismissed de inv_toaster : (long al_id, string as_key, string as_reason)

A receita: nada se recusa a compilar — um script de ue_toast_dismissed mantém al_id e as_key, as_reason acrescenta-se. Reveja o código que supunha que um toast fechado de imediato por of_close não diria nada: agora anuncia-o. Os toasts continuam ligados ao toaster que os mostrou: um of_close sobre o identificador de outro toaster devolve -5. O toaster ganha também of_close_all (fechar todos os seus toasts) e of_get_last_error — ver a página do toaster.

12.16 video: uma recusa devolvida de imediato, um filme e as suas legendas numa chamada, o mesmo filme retomado #

O leitor de vídeo muda cinco coisas que o seu código pode ver. Uma recusa é devolvida de imediato, como no leitor de sons (12.14): of_play(), of_play(source) e of_play_range devolvem -5, a razão em of_get_last_error(), para uma fonte vazia, um endereço http:// ou um formato recusado pelo nome (avi, wmv, flv) — e já não levantam ue_failed; o filme em curso continua. A propriedade is_source mantém o seu ue_failed: uma propriedade não tem código de retorno. O mesmo filme não é recarregado: of_play(source) ou is_source sobre o filme já carregado retoma-o onde está (ue_resumed) em vez de o recomeçar; of_seek(0) recomeça-o. Uma procura fica no segmento de of_play_range, a do utilizador como of_seek: Início leva ao começo do segmento, um clique além do seu fim ao seu fim — antes, Início saía do excerto e um clique além parava o filme. Uma entrada da lista que não pode tocar levanta primeiro ue_source_changed, depois um só ue_failed — vinha antes, e duas vezes. of_stop passa a função: não devolvia nada (subrotina), devolve 0, ou -2 quando o componente não está criado — como of_stop do navegador web.

// Local variables
string ls_path
long ll_rc

// The film chosen by the user
ls_path = sle_film.text

// 4.0 : of_play returned 0, and an http:// address or an .avi came back later through ue_failed
// 5.0 : the refusal is a code, at once ; the reason is in of_get_last_error
ll_rc = uo_video.of_play(/*source*/ ls_path)
if ll_rc = -5 then
	MessageBox("Video", uo_video.of_get_last_error())
end if

O que muda sem pedir nada ao seu código: um marcador atingido por uma procura EM PAUSA já não levanta ue_marker_reached (só ue_seeked); Espaço e o botão Reproduzir de um leitor sem filme já não fazem nada (levantavam ue_failed(REASON_NO_SOURCE)); a língua de legendas escolhida pelo utilizador segue para o filme seguinte da lista; um cartaz http:// é recusado e is_poster relê-se vazio; um is_subtitles recusado relê-se vazio; um ficheiro de legendas do posto que não se encontra levanta ue_subtitles_failed(REASON_NOT_FOUND); o menu de velocidade usa-se pelo teclado e as suas setas já não mudam o volume; em ecrã inteiro a barra mostra-se pelo teclado; a posição lembrada (ib_remember_position) já não depende da escrita do caminho, e só os 200 últimos filmes são guardados (uma posição da 4.0 é relida uma vez). O leitor ganha of_play(source, subtitles) (o filme e as SUAS legendas: definidas antes de um segundo filme, iam-se com o primeiro), ib_forward_seek, of_watched_ms, of_watched_percent, ue_watched_completely e ib_skip_failed — veja a página do leitor de vídeo.

A receita: nada se recusa a compilar. Releia o código que esperava ue_failed depois de of_play para um endereço http://, uma fonte vazia ou um .avi: testa agora o -5 da chamada. Releia também um botão « Reproduzir » que contava com of_play(source) para recomeçar: acrescente of_seek(0).

12.17 webbrowser: um gesto do utilizador é perguntado, uma página de of_show_html não tem endereço #

Com ib_veto_navigation = true, ue_navigating é agora perguntado também para um gesto do utilizador: um endereço escrito na barra, Abrir link do menu de contexto, uma nova janela aberta por um clique. Na 4.0 estes três caminhos não perguntavam. Só um endereço definido pelo seu código nunca é perguntado, e também não um redirecionamento do servidor: para uma lista de servidores que valha também para os redirecionamentos, defina a nova propriedade is_allowed_hosts.

A receita: nada se recusa a compilar, um long ignorado compila. Um script de ue_navigating escrito para as ligações do site vê agora também os endereços escritos pelo utilizador: se decide pelo endereço, que compare o seu anfitrião, como o exemplo da página do componente — ou confie a lista a is_allowed_hosts. O código que lia as_url de ue_load_completed, ou is_address, após of_show_html recebe uma cadeia vazia.

12.18 toolbar: o clique direito traz o seu ponto, uma ordem do código anuncia-se #

A barra de ferramentas junta-se à biblioteca: o clique direito de uma ferramenta dá o seu ponto de ecrã, como o das árvores, das grelhas e do separador, e deslocar uma barra por ii_band / ii_index despoleta ue_bar_reordered como o gesto. Duas adições recusam o que aceitavam em silêncio, e um atalho definido onde nada vive deixa de ser registado. Ganha também is_text numa barra, um nome para cada ferramenta e cada campo lido por um leitor de ecrã, e um teclado que atravessa os campos — ver a página da barra de ferramentas.

// 4.0 : the right click of a tool
// ue_item_rclicked event of uo_toolbar : (string as_keys)

// 5.0 : the same script, with the screen point
// ue_item_rclicked event of uo_toolbar : (string as_keys, long al_x, long al_y)

A receita: nada se recusa a compilar — um script de ue_item_rclicked mantém as_keys. Abra o seu menu no ponto al_x, al_y (passe-o a of_show de um contextmenu). Verifique que um script de ue_bar_reordered aceita também as deslocações feitas pelo seu código, teste o código de retorno de of_add_datepicker se a data vier de um campo regional, e defina is_shortcut depois de acrescentar a ferramenta ou a entrada.

12.19 O clique direito de um item traz o seu ponto: buttonbar, breadcrumb, chartcartesian, statusbar #

Uma só regra para todo o clique direito sobre um item da biblioteca: o evento recebe a chave (ou o endereço) do item, depois al_x, al_y, o ponto onde abrir um menu, em píxeis de ecrã — o ponteiro, ou, pelo teclado (tecla Menu, Shift+F10), o canto inferior esquerdo do item (inferior direito numa leitura da direita para a esquerda; o meio de uma forma que não é um retângulo: um ponto de um gráfico). Um contextmenu da biblioteca abre-se aí tal como estão: uo_menu.of_show(al_x, al_y). Três eventos que não o traziam recebem-no; a barra de estado multiplicava o seu pela escala do ecrã, e um menu aberto nesse ponto caía longe do ponteiro num ecrã a 125 % ou 150 %.

// 5.0 : the menu of a button, opened where the user right-clicked it
// ue_button_rclicked event of uo_buttons : (string as_key, long al_x, long al_y)
is_menu_button = as_key
uo_menu.of_show(/*x*/ al_x, /*y*/ al_y)

A receita: nada se recusa a compilar — um script destes eventos mantém os seus argumentos. Abra o seu menu no ponto al_x, al_y (passe-o a of_show de um contextmenu); um menu PowerBuilder mantém PopMenu(PointerX(), PointerY()) da sua janela. Um script que corrigia ele próprio a escala das coordenadas de ue_panel_rclicked já não o deve fazer.

12.20 A base: o erro de um componente é o seu, cada verbo devolve um código #

Cinco alterações tocam toda a biblioteca, ou toda uma família de componentes. Só uma se recusa a compilar: is_last_error de um componente não visual, agora of_get_last_error().

// Local variables
string ls_why

// 4.0 : ls_why = inv_crypto.is_last_error
// 5.0 : the reason of a failure, by the same method as every component
ls_why = inv_crypto.of_get_last_error()

A receita: o compilador mostra cada .is_last_error a substituir por .of_get_last_error(). Uma chamada a of_stop, of_close ou of_reset escrita como instrução continua a compilar. Um script que lia of_get_last_error() de um componente para saber da falha de outra chamada (um export da DLL chamado diretamente, outro componente) lê agora o motivo desse componente, ou nada: pergunte-o a quem falhou.

Acrescentado, nada a refazer: is_accessible_name e is_accessible_description em todos os componentes visuais — o nome e a descrição que um leitor de ecrã diz (3.4); of_from_datastore de um DataWindow ou de um DataWindowChild em crosstab e datagrid, como nos outros componentes ligados a dados; a forma completa de of_insert_command (commandpalette), que recebe a explicação, o atalho e as palavras-chave como of_add_command, com uma posição em long.

← Migrar da 3.0 para a 4.0 · Índice · Notas de versão →