listbar — u_pbt_listbar #

← Referência dos componentes · Índice do guia

Barra de navegação lateral: secções recolhíveis em acordeão que contêm entradas com ícone, com faixa de destaque na entrada atual e recolha para uma calha de ícones.

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

Em resumo #

É o único componente da biblioteca que publica ib_auto_width: a sua largura natural tem significado, uma vez que a calha recolhida é nitidamente mais estreita do que a barra expandida. Aliás, o caso corrente já está coberto sem ativar nada — ib_collapsed = true encolhe a barra até à calha e devolve-lhe a largura ao expandir.

Início rápido #

// event open da janela

uo_nav.of_add_section(/*key*/ "nav", /*titulo*/ "Navegacao")
uo_nav.of_add_item(/*keys*/ "nav/accueil",   /*etiqueta*/ "Inicio",    /*icone*/ "mono:img\home.svg")
uo_nav.of_add_item(/*keys*/ "nav/documents", /*etiqueta*/ "Documentos", /*icone*/ "mono:img\doc.svg")
uo_nav.of_add_item(/*keys*/ "nav/recherche", /*etiqueta*/ "Pesquisa",  /*icone*/ "mono:img\find.svg")

uo_nav.of_add_section(/*key*/ "config", /*titulo*/ "Definicoes")
uo_nav.of_add_item(/*keys*/ "config/preferences", /*etiqueta*/ "Preferencias", /*icone*/ "mono:img\gear.svg")

// A selecao coloca-se na ENTRADA, atraves do seu caminho completo
uo_nav.of_select_item("nav", "accueil")

// event ue_selection_changed de uo_nav: (string as_from_keys, string as_keys)
choose case as_keys
    case "nav/accueil"       ; of_ouvrir_accueil()
    case "nav/documents"     ; of_ouvrir_documents()
    case "config/preferences"; of_ouvrir_preferences()
end choose

Dois níveis, um caminho obrigatório #

Um identificador de entrada só é único dentro da respetiva secção: não existe, portanto, qualquer atalho para a entrada. Todo o acesso passa pela secção, o que torna a escrita inequívoca — ver Hierarquias.

// Componente  ->  seccao         ->  entrada     ->  propriedade
uo_nav        .of_section("nav") .of_item("docs") .is_text = "Documents"

Os eventos incluem igualmente o caminho completo, e com ele a entrada abandonada: ue_selection_changed(as_from_keys, as_keys).

Propriedades #

Propriedades de uma secção — n_pbt_listbar_section #

Propriedades de uma entrada — n_pbt_listbar_item #

Métodos #

No componente #

Numa secção — n_pbt_listbar_section #

Eventos #

Exemplos #

Menu lateral completo #

uo_nav.of_set_redraw(false)

uo_nav.of_add_section("dossiers", "Processos")
uo_nav.of_add_item("dossiers/recents",  "Recentes", "mono:img\clock.svg")
uo_nav.of_add_item("dossiers/clients",  "Clientes", "mono:img\user.svg")
uo_nav.of_add_item("dossiers/archives", "Arquivo",  "mono:img\box.svg")

uo_nav.of_add_section("outils", "Ferramentas")
uo_nav.of_add_item("outils/import", "Importar", "mono:img\import.svg")
uo_nav.of_add_item("outils/export", "Exportar", "mono:img\export.svg")

uo_nav.of_set_redraw(true)
uo_nav.of_select_item("dossiers", "recents")

Calha recolhível que liberta espaço #

// Recolher numa calha de icones: a barra encolhe por si propria (e retoma a sua
// largura quando a expandir).
uo_nav.ib_collapsed = true

// event ue_auto_width de uo_nav: (long al_width)
// A barra acaba de adotar a sua largura ideal: reposicionar o que esta a direita.
uo_contenu.x     = uo_nav.x + al_width
uo_contenu.width = parent.width - uo_contenu.x

Acordeão: recolher uma secção #

// Recolher a seccao do arquivo, raramente utilizada
uo_nav.of_section("archives").ib_collapsed = true

// event ue_section_toggled de uo_nav: (string as_keys, boolean ab_collapsed)
of_enregistrer_preference("section_" + as_keys, String(ab_collapsed))

Reagir à navegação #

// event ue_selection_changed de uo_nav: (string as_from_keys, string as_keys)
// O endereco leva os dois niveis: duas seccoes podem ter uma entrada "liste".
n_pbt_utils lnv_utils   // autoinstantiate: nada a criar, nada a destruir
string ls_ids[]

if lnv_utils.of_split_path(as_keys, ls_ids) < 2 then return
choose case ls_ids[1]
    case "dossiers" ; of_ouvrir_dossier(ls_ids[2])
    case "outils"   ; of_lancer_outil(ls_ids[2])
end choose

Recusar uma mudança de seleção #

// A pergunta e colocada por PREDEFINICAO: nada a ativar. Esta linha faz o
// contrario, elimina-a quando arbitrar nao serve e o custo se notaria.
uo_nav.ib_veto_selection = false

// event ue_selection_changing de uo_nav:
//   (string as_from_keys, string as_keys)
// Devolver FALSE mantem o utilizador na entrada que abandona.
if of_saisie_en_cours(as_from_keys) then
    MessageBox("Introdução", "Termine a ficha em curso antes de navegar.")
    return false
end if
return true

Atualizar uma entrada em tempo real #

n_pbt_listbar_item lnv_entree

// O caminho completo e obrigatorio: componente -> seccao -> entrada
lnv_entree = uo_nav.of_section("dossiers").of_item("recents")
lnv_entree.is_text  = "Recentes (12)"
lnv_entree.is_image = "mono:img\clock_full.svg"

// Esbater ou ocultar consoante os direitos, sem reconstruir a barra
uo_nav.of_section("outils").of_item("import").ib_enabled = of_a_le_droit("import")
uo_nav.of_section("outils").of_item("export").ib_visible = gb_mode_expert

Seleção controlada a partir do código #

// Colocar a selecao noutro sitio: a faixa de destaque acompanha
uo_nav.of_select_item("dossiers", "clients")

// Ou limpa-la completamente
uo_nav.of_clear_selection()

Reconstruir a barra #

// of_clear esvazia seccoes e entradas; of_reset acrescenta as predefinicoes do componente
uo_nav.of_clear()
of_construire_menu_selon_profil()

Boas práticas #

• Uma entrada adiciona-se pelo seu endereço: of_add_item("nav/accueil", ...). O handle de secção serve agora apenas para definir uma propriedade, e of_section("nav") devolve-o no primeiro acesso.
• Utilize mono: para os ícones: recolorem-se com o tema, tanto claro como escuro, e permanecem legíveis depois de a barra ser recolhida em calha.
• Um título de secção vazio serve de agrupamento discreto: as entradas ficam espaçadas sem que apareça qualquer linha de cabeçalho.
• ib_collapsed encolhe o userobject até à calha, mas não desloca os seus outros controlos: trate ue_auto_width para ocupar o espaço libertado, caso contrário este permanece vazio.
• No modo calha subsistem apenas os ícones: indique um tooltip em cada entrada para que as etiquetas permaneçam acessíveis.
• A pergunta é colocada por predefinição: um ue_selection_changing deixado vazio autoriza sempre o deslocamento, não tem nada a fazer. Desative-a com ib_veto_selection = false onde o clique é repetido — navegação por teclado, seleção pilotada em ciclo — porque cada pergunta custa uma ida e volta ao PowerBuilder.
• ib_enabled = false é preferível a ib_visible = false quando a entrada voltará a ficar disponível: o menu não muda de forma diante dos olhos do utilizador.

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