tab — u_pbt_tab #

← Referência dos componentes · Índice do guia

Separadores modernos que alojam controlos reais do PowerBuilder: faixa reposicionável, ícones por separador, separadores que se podem fechar, reordenação com o rato.

▶ Ver ao vivo — Aplicação de demonstração, mosaico Tab: a pré-visualização, o código que o produz e esta página, lado a lado.

Em resumo #

O argumento decisivo: uma página não é uma maqueta HTML, é um dragobject do PowerBuilder — um userobject, uma DataWindow, um conjunto de controlos ou até outro componente PBToolboxAI. O componente encarrega-se do posicionamento, do redimensionamento e da apresentação/ocultação na mudança de separador. Ver Alojar controlos reais do PowerBuilder.

Início rápido #

// event open da janela : cada pagina e um controlo PB ja colocado na janela
uo_tabs.of_add_page(/*key*/ "customers",  /*title*/ "Clientes",  /*page*/ uo_page_customers)
uo_tabs.of_add_page(/*key*/ "invoices", /*title*/ "Faturas", /*page*/ uo_page_invoices, /*closable*/ true)

// Um icone por separador, colocado no handle da pagina
uo_tabs.of_page(/*key*/ "customers").is_icon  = "mono:img\customers.svg"
uo_tabs.of_page(/*key*/ "invoices").is_icon = "mono:img\invoice.svg"

// Mostra o primeiro separador
uo_tabs.of_select_page(/*key*/ "customers")

// event ue_selection_changed de uo_tabs : (string as_from_key, string as_key)
// Uma chave vazia : ja nao se mostra nenhum separador (todos ocultos)
if as_key <> "" then of_load_page(as_key)

Propriedades #

Propriedades de uma página — n_pbt_tab_page #

Obtidas através de of_page(id), podem ser alteradas a quente, sem reconstruir a faixa.

Métodos #

of_add_page devolve um código negativo se o identificador estiver vazio, já estiver a ser utilizado ou se o controlo indicado não for válido ou já estiver alojado.

Quando há demasiados separadores — reduzem-se para caber na banda, mas nunca abaixo de uma largura legível: o ícone e a cruz de fecho ocupam o seu espaço para além do título, nunca no lugar dele. Os que já não cabem saem da banda, e na sua extremidade aparece um botão ···: abre a lista de todos os separadores visíveis, com o ativo assinalado, e a escolha passa para ele. O separador ativo permanece sempre visível. A banda não desliza — esse botão é o caminho para os separadores fora do enquadramento. Nada a programar, o comportamento é automático.

Teclado e rato — Ctrl+Tab e Ctrl+Page Down passam ao separador seguinte, Ctrl+Shift+Tab e Ctrl+Page Up ao anterior: só contam os separadores que podem ficar ativos (os ocultos e os desativados são saltados), e o percurso recomeça do início. Estas teclas respondem quando o teclado está na banda de separadores ou numa página que ela aloja — um controlo PowerBuilder da página tal como outro componente colocado nela; a partir de um controlo fora do tab, ficam para a janela. É um gesto do utilizador: ue_selection_changing é colocado se ib_veto_selection estiver ativo, e depois segue-se ue_selection_changed. Um clique do meio num separador que se pode fechar fecha-o, exatamente como a sua cruz: a mesma pergunta ue_tab_closing se ib_veto_close estiver ativo, e depois ue_tab_closed; num separador desativado ou que não se pode fechar, não faz nada. Nada a programar. Shift+F10 ou a tecla Menu num separador abre o seu menu sob o separador; Ctrl+Shift+seta desloca o separador com o foco quando ib_reorderable está a true. Se uma página precisar de Ctrl+Tab para si, coloque ib_cycle_keys a false.

Eventos #

Exemplos #

Um dossiê de páginas de negócio #

// event open : os userobjects de pagina ja estao colocados na janela
uo_tabs.of_set_redraw(/*on*/ false)

// Um separador por userobject de pagina
uo_tabs.of_add_page(/*key*/ "identity", /*title*/ "Identidade",  /*page*/ uo_identity)
uo_tabs.of_add_page(/*key*/ "addresses", /*title*/ "Moradas",  /*page*/ uo_addresses)
uo_tabs.of_add_page(/*key*/ "accounting",   /*title*/ "Contabilidade", /*page*/ uo_accounting)

// Um icone por separador, colocado no handle da pagina
uo_tabs.of_page(/*key*/ "identity").is_icon = "mono:img\user.svg"
uo_tabs.of_page(/*key*/ "addresses").is_icon = "mono:img\map.svg"
uo_tabs.of_page(/*key*/ "accounting").is_icon   = "mono:img\euro.svg"

// Uma so renderizacao para tudo e depois mostra-se o primeiro separador
uo_tabs.of_set_redraw(/*on*/ true)
uo_tabs.of_select_page(/*key*/ "identity")

Documentos que se podem fechar, abertos a pedido #

// Local variables
string ls_key, ls_label

// Abrir um documento num novo separador que se pode fechar : a sua chave e o seu titulo
ls_key = "report42"
ls_label = "Relatorio 42"
uo_tabs.of_add_page(/*key*/ ls_key, /*title*/ ls_label, /*page*/ uo_editor, /*closable*/ true, /*icon*/ "mono:img\doc.svg")
uo_tabs.of_select_page(/*key*/ ls_key)

// event ue_tab_closed de uo_tabs : (string as_key)
// O separador ja foi retirado ; falta libertar os dados de negocio.
of_free_document(as_key)

// A cruz apenas no separador ativo, um ponto numa pagina que contem
// trabalho nao guardado, e um contador noutra
uo_tabs.is_close_mode = uo_tabs.CLOSE_ACTIVE
uo_tabs.of_page(/*key*/ "report42").ib_modified = true
uo_tabs.of_page(/*key*/ "inbox").is_badge = "3"

Páginas criadas a pedido #

Uma página pesada não precisa de existir antes de ser visitada: acrescente-a sem o seu controlo, e crie o controlo em ue_page_needed, como o CreateOnDemand de um Tab do PowerBuilder.

// event open da janela : as paginas pesadas sao acrescentadas SEM o seu controlo
uo_tabs.of_add_page(/*key*/ "orders", /*title*/ "Encomendas")
uo_tabs.of_add_page(/*key*/ "history", /*title*/ "Historico")

// event ue_page_needed de uo_tabs : (string as_key)
// Local variables
u_orders luo_orders

// A pagina e mostrada pela primeira vez : criar o seu controlo e depois entrega-lo
if as_key = "orders" then
    parent.OpenUserObject(luo_orders)
    uo_tabs.of_supply_page(/*key*/ as_key, /*page*/ luo_orders)
end if

Reordenação com o rato #

// The user may drag a tab to a new place
uo_tabs.ib_reorderable = true

// event ue_tab_reordered de uo_tabs : (string as_key, integer ai_index)
// ai_index = nova posicao, a partir de 1 (como of_move_page) : memoriza-se a ordem escolhida.
of_save_order(as_key, ai_index)

Faixa vertical #

// Banda de separadores do lado esquerdo, util quando as etiquetas sao longas
uo_tabs.is_position = uo_tabs.POSITION_START

Inativar ou ocultar um separador consoante os direitos #

// O caminho passa sempre pelo handle da pagina
uo_tabs.of_page(/*key*/ "accounting").ib_enabled = of_is_allowed("accounting")
uo_tabs.of_page(/*key*/ "audit").ib_visible  = gb_expert_mode

Reagir à seleção #

// event ue_selection_changed de uo_tabs : (string as_from_key, string as_key)
choose case as_key
    case "identity" ; uo_identity.of_refresh()
    case "addresses" ; uo_addresses.of_refresh()
    case "accounting"   ; uo_accounting.of_refresh()
end choose

Recusar uma mudança de separador ou um fecho #

// As duas perguntas tem de ser ATIVADAS: sem estas linhas o componente nao
// pergunta nada e muda de pagina ou fecha de imediato.
uo_tabs.ib_veto_selection = true
uo_tabs.ib_veto_close     = true

// event ue_selection_changing de uo_tabs : (string as_from_key, string as_key)
// Devolver FALSE mantem o utilizador na pagina que abandona.
if of_page_modified(as_from_key) then
    if MessageBox("Modificações", "Sair sem guardar?", Question!, YesNo!) = 2 then
        return false
    end if
end if
return true

// event ue_tab_closing de uo_tabs : (string as_key)
// Devolver FALSE mantem o separador e a pagina que aloja abertos.
return not of_page_modified(as_key)

Recomeçar com uma faixa vazia #

// of_reset devolve CADA pagina alojada a sua janela de origem antes de esvaziar
uo_tabs.of_reset()
uo_tabs.of_add_page(/*key*/ "home", /*title*/ "Início", /*page*/ uo_home)

Boas práticas #

• Os controlos alojados têm de existir antes da chamada: devem ser colocados na janela em tempo de desenho, cabendo ao componente ocultá-los e reposicioná-los.
• Recomenda-se carregar as páginas uma única vez no open e comandar em seguida apenas a seleção: é mais rápido do que acrescentar e retirar páginas continuamente.
• Deve chamar-se of_preload_icons no arranque se os separadores tiverem ícones: sem isso, a primeira abertura de um separador oculto apresenta um breve atraso antes do ícone.
• As duas perguntas são opt-in: coloque ib_veto_selection / ib_veto_close a true para poder recusar uma mudança de separador ou um fecho (um evento deixado vazio autoriza sempre a ação). Cada pergunta custa uma ida e volta ao PowerBuilder.
• Um controlo alojado é uma janela nativa: desenha-se por cima da camada web. Nenhum efeito visual do componente pode passar à frente dele.
• Não esquecer of_reset() antes de reconstruir uma faixa: sem essa chamada, a reutilização de um identificador de página falha e os controlos anteriores permanecem visíveis.
• Para zonas redimensionáveis e destacáveis em vez de páginas exclusivas, é preferível utilizar dockcontainer.
• No teclado, a barra de separadores segue o seu eixo: Esquerda/Direita (invertidas na escrita da direita para a esquerda), Cima/Baixo nas posições start/end, Início/Fim, Enter ou Espaço para ativar, Delete para fechar um separador que se pode fechar. Os separadores desativados e os que saíram da barra são saltados.
• Muitas páginas pesadas? Acrescente-as sem o seu controlo (of_add_page(key, title)) e crie cada uma em ue_page_needed: o ecrã abre depressa, e só existem as páginas visitadas.

Herdado da base comum #

Estes membros existem em todos os componentes visuais — não são próprios deste. São detalhados uma só vez, nos capítulos transversais; esta tabela apenas diz onde os ler.

Duas ajudas não são herdadas: of_icon e of_escape_markup vivem em n_pbt_utils. Declare um — n_pbt_utils lnv_utils, nada a criar — e chame-as nele.

← Referência dos componentes · Índice do guia