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 #

Userobject	`u_pbt_listbar`
Classe de items	`n_pbt_listbar_section` (secção) → `n_pbt_listbar_item` (entrada)
Serve para	Substituir um menu lateral improvisado à custa de botões por uma navegação estruturada, com tema e recolhível
Opções opt-in	`ib_auto_width`, `ib_reorderable`, `ib_search`

ib_auto_width tem aqui um significado particular: 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; ib_auto_width relê-se sempre tal como o definiu.

Início rápido #

// evento open da janela

// Uma seccao e depois as suas entradas : cada entrada endereca-se por seccao/entrada
uo_nav.of_add_section(/*key*/ "nav", /*text*/ "Navigation")
uo_nav.of_add_item(/*keys*/ "nav/home",   /*text*/ "Home",      /*image*/ "mono:img\home.svg")
uo_nav.of_add_item(/*keys*/ "nav/docs",   /*text*/ "Documents", /*image*/ "mono:img\doc.svg")
uo_nav.of_add_item(/*keys*/ "nav/search", /*text*/ "Search",    /*image*/ "mono:img\find.svg")

// Uma segunda seccao, com uma unica entrada
uo_nav.of_add_section(/*key*/ "settings", /*text*/ "Settings")
uo_nav.of_add_item(/*keys*/ "settings/prefs", /*text*/ "Preferences", /*image*/ "mono:img\gear.svg")

// A selecao fica na ENTRADA, pelo seu endereco : a seccao e depois a entrada
uo_nav.of_select_item(/*keys*/ "nav/home")

// of_select_item lanca ue_selection_changed, como um clique : a primeira pagina abre-se ai

// evento ue_selection_changed de uo_nav : (string as_from_keys, string as_keys)
choose case as_keys
    case "nav/home"       ; of_open_home()
    case "nav/docs"       ; of_open_documents()
    case "settings/prefs" ; of_open_preferences()
end choose

Dois níveis, um endereço #

Um identificador de entrada só é único dentro da sua secção: uma entrada designa-se, portanto, pelo seu endereço, a secção e depois a entrada unidas por / — "nav/docs". É o componente que o recebe (of_item, of_select_item, of_remove_item…); uma secção designa-se apenas pela sua chave (of_section("nav")). Ver Hierarquias.

// Uma seccao pela sua chave, uma entrada pelo seu endereco
uo_nav.of_section(/*key*/ "nav").is_title = "Navigation"
uo_nav.of_item(/*keys*/ "nav/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 #

Propriedade	Tipo	Predefinição	Função
`ib_collapsed`	boolean	`false`	`true` recolhe a barra numa calha de ícones: os títulos de secção e as etiquetas dão lugar a um filete entre secções, e todas as entradas continuam visíveis, mesmo as de uma secção recolhida (o recolhimento volta à saída da calha). Uma entrada sem ícone mostra a sua inicial, e cada entrada diz a sua etiqueta ao passar o rato
`ib_auto_width`	boolean	`false`	Opt-in: o mesmo para a largura, incluindo expandida (a barra ajusta-se à etiqueta mais comprida). Quanto ao recolhimento em calha, esse já encolhe sozinho; `ue_auto_width` segue-se em ambos os casos
`ib_reorderable`	boolean	`false`	Opt-in: o utilizador pode deslocar uma entrada com o rato. O deslocamento mantém-se dentro da sua secção — um identificador de entrada só é único aí, pelo que atravessar arriscaria duas chaves idênticas (aciona `ue_item_reordered`)
`ib_veto_selection`	boolean	`false`	Opt-in: perguntar antes de a seleção se mover — um gesto do utilizador e `of_select_item` / `of_clear_selection` (dispara `ue_selection_changing`, que pode recusar; uma ordem recusada devolve `-4`). Desativado por omissão, como todo evento cancelável da biblioteca: defina `true` quando precisar de poder recusar (dados não guardados). Cada pergunta de um gesto custa uma ida e volta ao PowerBuilder (~35 ms)
`ib_search`	boolean	`false`	Opt-in: um campo de pesquisa no topo da barra. O que o utilizador escreve filtra as entradas (`is_filter`, `ue_filter_changed`); Ctrl+F alcança o campo, Escape esvazia-o, Seta para baixo desce para a primeira entrada, Enter escolhe a primeira correspondência. Não é desenhado na calha (falta espaço): `is_filter` aplica-se na mesma
`is_filter`	string	`""`	O texto que filtra a barra, lido em direto: as entradas cuja etiqueta — ou o título da secção — o contém, sem distinguir maiúsculas nem acentos. Uma secção que contém uma correspondência mostra-se expandida, o seu recolhimento intacto; uma secção sem correspondências desaparece enquanto o filtro se mantiver. Definido pelo seu código não dispara nada (um valor, como SetFilter); escrito pelo utilizador, `ue_filter_changed`. Enquanto filtra, um título não se recolhe e uma entrada não se arrasta. Em demonstração as seis entradas desenhadas contam-se sem o filtro: uma pesquisa nunca alcança uma sétima
`is_theme_style`	string	`""`	Estilo visual do componente (constantes `THEME_STYLE_*`); vazio = o da aplicação, seguido a cada mudança
`is_theme_mode`	string	`""`	Variante clara ou escura (constantes `THEME_MODE_*`); vazio = a da aplicação, seguida a cada mudança
`il_theme_accent`	long	`-1`	Cor de destaque deste componente (`-1` = destaque da aplicação, ou o do tema)
`is_tooltip`	string	`""`	Tooltip simples apresentado ao passar sobre o componente
`is_super_tooltip_title`	string	`""`	Título do tooltip enriquecido (prevalece sobre `is_tooltip`)
`is_super_tooltip_text`	string	`""`	Texto do tooltip enriquecido (aceita marcação enriquecida)
`is_super_tooltip_image`	string	`""`	Imagem do tooltip enriquecido

Propriedades de uma secção — `n_pbt_listbar_section` #

Propriedade	Tipo	Predefinição	Função
`is_title`	string	`""`	Título da secção. Aceita o texto formatado com etiquetas. Um título vazio não apresenta qualquer linha de cabeçalho: a secção passa a ser um simples agrupamento invisível; um espaço separa-a da secção de cima (um filete no trilho), e ela deixa de se recolher — ninguém a poderia reabrir
`ib_collapsed`	boolean	`false`	Acordeão: `true` recolhe as entradas desta secção. O cabeçalho permanece visível e o respetivo galão roda; `ue_section_toggled` segue, como num clique no cabeçalho
`ib_pinned`	boolean	`false`	`true` fixa a secção no fundo da barra (Definições, Ajuda): um rodapé que permanece visível enquanto o resto da barra desliza, empurrado para baixo quando há espaço de sobra, e no fundo do trilho também. Várias secções fixadas empilham-se pela sua ordem. Só muda o desenho: a disposição (`of_get_layout`) mantém a ordem das secções, e a seta Baixo passa da última entrada de cima para a primeira do rodapé
`is_image`	string	`""`	Ícone antes do título da secção (formas aceites: caminho, `mono:`, `tint:`, recurso de DLL). Uma cadeia vazia retira-o
`is_tooltip`	string	`""`	Dica simples mostrada ao passar sobre o título da secção
`is_super_tooltip_title`	string	`""`	Título da dica enriquecida do título da secção (tem prioridade sobre `is_tooltip`)
`is_super_tooltip_text`	string	`""`	Texto da dica enriquecida da secção (marcação rica aceite)
`is_super_tooltip_image`	string	`""`	Imagem da dica enriquecida da secção
`il_accent`	long	`-1`	Destaque desta secção, ou seja, do seu título e de nada mais: as suas entradas mantêm o seu (`-1` = o do componente)
`il_back_color`	long	`-1`	Fundo do título da secção, em `RGB(r,g,b)` (`-1` = o do componente)
`il_text_color`	long	`-1`	Cor do texto do título da secção (`-1` = a do componente)
`il_back_color_hover`	long	`-1`	Fundo do título sob o ponteiro (`-1` = o do componente)
`il_text_color_hover`	long	`-1`	Cor do texto do título sob o ponteiro (`-1` = a do componente)

Propriedades de uma entrada — `n_pbt_listbar_item` #

Propriedade	Tipo	Predefinição	Função
`is_text`	string	`""`	Etiqueta da entrada, modificável em tempo real sem reconstruir a barra. Aceita o texto formatado com etiquetas
`is_image`	string	`""`	Ícone, modificável em tempo real (formas aceites: caminho, `mono:`, `tint:`, recurso de DLL)
`ib_enabled`	boolean	`true`	`false` desativa a entrada: fica no seu lugar e já não responde a nada — nem clique, nem Enter, nem clique direito, e as setas saltam-na; a sua dica continua a aparecer, para dizer porquê. O seu código também não a pode selecionar (`of_select_item` devolve `-5`); desativar a entrada já selecionada mantém-na selecionada
`ib_visible`	boolean	`true`	`false` oculta a entrada sem a remover da barra. Uma entrada oculta não pode passar a ser a seleção (`of_select_item` devolve `-5`); ocultar a que está selecionada mantém-na selecionada, e voltar a mostrá-la devolve-a tal como estava
`is_badge`	string	`""`	Pastilha de contador no fim da entrada (`"12"` por ler), nas cores de pastilha do tema; no trilho, no canto do ícone. Qualquer texto curto, marcação aceite. Uma cadeia vazia retira-a
`of_is_selected ( )` → `boolean`	—	—	Esta entrada é a selecionada? Só leitura, e de propósito: a seleção é um estado da barra inteira, não um indicador por entrada. Para a definir, `of_select_item` no componente
`is_tooltip`	string	`""`	Tooltip simples apresentado ao passar sobre o item
`is_super_tooltip_title`	string	`""`	Título do tooltip enriquecido do item (prevalece sobre `is_tooltip`)
`is_super_tooltip_text`	string	`""`	Texto do tooltip enriquecido do item (aceita marcação enriquecida)
`is_super_tooltip_image`	string	`""`	Imagem do tooltip enriquecido do item
`il_accent`	long	`-1`	Acento desta entrada: a barra que a marca quando está selecionada usa-o (`-1` = o do componente). Para «esta entrada a vermelho», `il_back_color` / `il_text_color`
`il_back_color`	long	`-1`	Fundo próprio da entrada, em `RGB(r,g,b)` (`-1` = o que o tema dá)
`il_text_color`	long	`-1`	Cor do texto da entrada (`-1` = o que o tema dá)
`il_back_color_hover`	long	`-1`	Fundo da entrada sob o ponteiro (`-1` = o que o tema dá)
`il_text_color_hover`	long	`-1`	Cor do texto da entrada sob o ponteiro (`-1` = o que o tema dá)

Métodos #

No componente #

Método	Função
`of_add_section (string as_key, string as_text)`	Adiciona uma secção no fim da barra. Um texto vazio não desenha nenhuma linha de título. O handle vem de `of_section("nav")` quando quiser definir uma propriedade. Devolve `0` uma vez aplicado, `-5` se a chave estiver vazia, já ocupada ou contiver `/` ou `	`,` -2` se o componente não estiver criado
`of_insert_section (string as_key, string as_text, integer ai_index)`	Adiciona uma secção na posição escolhida (primeira posição = 1) em vez de no fim. O índice conta secções, não linhas. Um nome já ocupado é recusado: duas secções com o mesmo nome tornariam ambíguo o endereço de cada uma das suas entradas. Devolve `0` uma vez aplicado, `-5` se a chave estiver vazia, já ocupada ou contiver `/` ou `	`,` -2` se o componente não estiver criado
`of_move_section (string as_key, integer ai_index)`	Move uma secção para a posição `ai_index`, com as suas entradas. Mover só o cabeçalho deixaria cair as suas entradas na secção que fica acima delas. Devolve `0` uma vez aplicado, `-5` para uma secção que esta barra nunca adicionou, `-2` se o componente não estiver criado
`of_remove_section (string as_key)`	Retira uma secção e tudo o que contém. Esvaziá-la mantendo as suas entradas deixá-las-ia órfãs: teriam um identificador de secção que já não nomeia nada. Se a seleção lá estava, `ue_selection_changed` anuncia que já não há. Devolve `0` uma vez aplicado, `-5` para uma secção que esta barra nunca adicionou, `-2` se o componente não estiver criado
`of_section (string as_key)`	Handle de uma secção, pela sua chave: o título, o ícone, o recolhimento e as cores definem-se através dele (criado no primeiro acesso). Uma entrada alcança-se antes a partir do componente, pelo seu endereço (`of_item`)
`of_add_item (string as_keys, string as_text, string as_image)`	Adiciona uma entrada no seu endereço, `"nav/home"`: a secção onde aterra e depois o seu próprio identificador. Uma sobrecarga omite o ícone. Devolve `0` uma vez adicionada, `-5` se a secção não foi adicionada por esta barra, se o endereço já estiver ocupado ou se a chave contiver `	`,` -2` se o componente não estiver criado
`of_item (string as_keys)`	Handle de uma entrada, pelo seu endereço (criado no primeiro acesso). Um endereço que não é `secção/entrada` dá um handle que não nomeia nada: o que se escreve por ele não faz nada (uma secção alcança-se com `of_section`)
`of_insert_item (string as_keys, string as_text, integer ai_index)`	Insere uma entrada na posição `ai_index` dentro da sua secção (primeira posição = 1). Devolve `0` uma vez adicionada, `-5` se a secção não foi adicionada por esta barra, se o endereço já estiver ocupado ou se a chave contiver `	`,` -2` se o componente não estiver criado
`of_insert_item (string as_keys, string as_text, string as_image, integer ai_index)`	O mesmo, com o ícone da entrada: `of_add_item` aceita um, por isso inserir também tem de poder. Devolve `0` uma vez adicionada, `-5` se a secção não foi adicionada por esta barra, se o endereço já estiver ocupado ou se a chave contiver `	`,` -2` se o componente não estiver criado
`of_move_item (string as_keys, integer ai_index)`	Move uma entrada existente dentro da sua secção, mantendo o seu estado. Devolve `0` uma vez aplicado, `-5` para um endereço que esta barra nunca adicionou, `-2` se o componente não estiver criado
`of_remove_item (string as_keys)`	Retira uma entrada, designada pelo seu endereço. Se era a seleção, `ue_selection_changed` anuncia que já não há. Devolve `0` uma vez aplicado, `-5` para um endereço que esta barra nunca adicionou, `-2` se o componente não estiver criado
`of_clear ( )`	Esvazia a barra: todas as secções e todas as entradas. Se uma entrada estava selecionada, `ue_selection_changed` anuncia que já não há (endereço vazio); `ue_layout_changed` não é disparado, está a reconstruir. Devolve `0` depois de aplicado, `-2` se o componente não estiver criado
`of_select_item (string as_keys)`	Seleciona uma entrada, como um clique nela: com `ib_veto_selection` ativo, `ue_selection_changing` é perguntado primeiro; depois segue `ue_selection_changed`, como num clique (logo após o seu script, a partir da fila de eventos), e `of_selected_key()` lido logo a seguir já devolve o novo endereço. Entrada já selecionada: nada é perguntado nem disparado. Devolve `0` depois de selecionada (ou se já selecionada), `-4` se o seu `ue_selection_changing` recusou (nada se move), `-5` para um endereço que esta barra nunca adicionou, uma entrada oculta, uma entrada desativada ou uma entrada que o limite da demonstração não desenha — lido ANTES de a pergunta ser feita —, `-2` se o componente não estiver criado. `ue_item_invoked` não é disparado: responde a um gesto do utilizador
`of_get_layout ( )`	Relê a disposição atual em JSON: as secções por ordem, cada uma com as suas entradas por ordem e o seu estado recolhido. Guarde-a (ficheiro, base de dados, registo) e devolva-a com `of_set_layout` no arranque seguinte. O mesmo par tem os mesmos nomes em todos os componentes reorganizáveis
`of_set_layout (string as_layout_json)`	Repõe uma disposição lida com `of_get_layout` ou recebida com `ue_layout_changed`. O que a disposição não nomeia mantém o seu lugar no fim: uma disposição de ontem não deve fazer desaparecer o que foi acrescentado desde então. Aplicá-la dispara `ue_layout_changed` uma vez quando muda algo, nunca `ue_section_toggled`: um recolhimento reposto é um estado devolvido, não um recolhimento. Devolve `0` depois de aplicado, `-5` para um texto vazio ou que não é um objeto JSON (um ficheiro truncado): nada é enviado; o recolhimento de uma secção ausente é ignorado, `-2` se o componente não estiver criado
`of_clear_selection ( )`	Não deixa nenhuma entrada selecionada, como qualquer movimento: com `ib_veto_selection` ativo, `ue_selection_changing` é perguntado primeiro, depois segue `ue_selection_changed` com um endereço vazio. Nada selecionado já: nada é perguntado nem disparado. Devolve `0` uma vez aplicado, `-4` se o seu `ue_selection_changing` recusou (a entrada continua selecionada), `-2` se o componente não estiver criado
`of_from_datastore (datastore ads)`	Constrói a barra a partir das linhas de um DataStore — ou de um DataWindow, de um DataWindowChild, a mesma chamada: uma linha = uma entrada, o menu de uma aplicação lido da sua tabela de direitos. Uma coluna desempenha um papel quando tem o seu nome (`section`, `section_text`, `key`, `text`, `image`, `badge`, `enabled`) ou quando `of_map` o diz; `ROLE_SECTION` é obrigatório. O carregamento substitui as entradas: as secções que declarou mantêm título, ícone, recolhimento e fixação, e uma secção que as linhas nomeiam e que a barra não tem é acrescentada no fim, pela ordem das linhas, intitulada por `ROLE_SECTION_TEXT` (senão pela sua chave). Sem `ROLE_KEY`, a chave de uma entrada é o seu número de linha. `ROLE_ENABLED` desativa uma entrada com 0, N, F, false, no ou off. Uma linha cuja secção ou chave está vazia, contém `/` ou `	`, ou repete um endereço é posta de lado: a chamada devolve na mesma` 0 `e` of_get_last_error `nomeia-a. Uma seleção cuja entrada não volta sai, com` ue_selection_changed`. Devolve` 0 `depois de carregado,` -5 `se o DataStore não for válido ou não tiver colunas,` -2` se o componente não estiver criado
`of_map (string as_role, string as_column)`	Dá um papel a uma coluna do DataStore quando o seu nome não o diz: `of_map(u_pbt_listbar.ROLE_SECTION, "menu_group")`. Papéis: `ROLE_SECTION`, `ROLE_SECTION_TEXT` (o título de uma secção que as linhas criam), `ROLE_KEY`, `ROLE_TEXT`, `ROLE_IMAGE`, `ROLE_BADGE`, `ROLE_ENABLED`. Antes ou depois de `of_from_datastore`: depois, as linhas são relidas. Uma coluna vazia devolve o papel à coluna que tem o seu nome. Devolve `0` depois de definido, `-5` se o papel não for uma das constantes `ROLE_` ou a coluna não for uma coluna do DataStore do último carregamento, `-2` se o componente não estiver criado
`of_selected_key ( )`	Endereço da entrada selecionada — `"nav/docs"`, `""` se não houver nenhuma. É exatamente o que `ue_selection_changed` lhe entrega: uma comparação é uma comparação, não uma recomposição. Sempre a entrada atual, lida no componente: após um clique, e logo após `of_select_item` também
`of_reset ( )`	Esvazia a barra e depois devolve o componente ao seu estado novo. Se uma entrada estava selecionada, `ue_selection_changed` dispara com um endereço vazio; `ue_layout_changed` não é disparado. Devolve `0` depois de aplicado, `-2` se o componente não estiver criado
`of_set_redraw (boolean)`	Agrupa uma rajada de modificações numa única representação. Devolve `0` depois de aplicado, `-2` se o componente não estiver criado
`of_save_as_png (string)` · `of_save_as_jpg (string)`	Exporta a representação como imagem. Devolve `0` depois de a imagem ser escrita, `-4` se a escrita falhar, `-2` se o componente não estiver criado

Numa secção — `n_pbt_listbar_section` #

Método	Função
`of_count ( )`	Número de entradas da secção, ocultas incluídas
`of_keys_at (long al_index)`	Endereço da entrada na posição `al_index` (a partir de 1) — `"nav/docs"`, pronto a passar tal qual a `of_item`
`of_has (string as_key)`	A secção contém esta entrada?

Eventos #

Evento	Acionado quando
`ue_selection_changed (string as_from_keys, string as_keys)`	A seleção mudou: o utilizador escolheu uma entrada (clique, Enter, Espaço), o seu código moveu-a (`of_select_item`, `of_clear_selection` — uma ordem também o dispara, como SelectItem dispara SelectionChanged), ou a entrada selecionada saiu (`of_remove_item`, `of_remove_section`, `of_clear`, `of_reset` — `as_keys` fica então vazio). Mesmos argumentos que `ue_selection_changing`: a pergunta e o seu desfecho leem-se da mesma forma, e o par `as_from_*` designa a entrada abandonada (vazio se não houver nenhuma)
`ue_section_toggled (string as_key, boolean ab_collapsed)`	O utilizador recolhe ou expande uma secção: clique no título, Enter no título, ou as setas Esquerda / Direita (invertidas da direita para a esquerda), ou o seu código que define `ib_collapsed` de uma secção
`ue_item_reordered (string as_keys, integer ai_index)`	O utilizador terminou de arrastar uma entrada. `ai_index` é a sua nova ordem dentro da secção, a partir de 1, como `of_move_item`. Guarde essa ordem para devolver ao utilizador a barra tal como a deixou
`ue_layout_changed (string as_layout_json)`	A disposição a guardar mudou: uma entrada ou uma secção moveu-se, uma secção foi recolhida ou expandida, algo foi retirado, uma disposição foi reposta — pelo utilizador ou pelo seu código. Disparado uma vez por cada mudança real: uma deslocação para o lugar já ocupado não dispara nada; `of_set_layout` dispara-o uma vez quando a disposição aplicada muda algo. Traz a disposição inteira, não só o que se moveu: guardá-la é uma atribuição. As adições, o trilho, `of_clear` e `of_reset` não o disparam: é construção, não disposição
`ue_item_rclicked (string as_keys, long al_x, long al_y)`	O utilizador clicou com o botão direito numa entrada — ou premiu nela a tecla Menu, Shift+F10: o seu endereço, `"nav/docs"`, e `al_x`, `al_y` em píxeis do ecrã, os que `of_show` de um `contextmenu` recebe. Um evento por clique direito, e a entrada não é selecionada. Um menu PowerBuilder abre-se no ponteiro da sua janela: `m_menu.PopMenu(parent.PointerX(), parent.PointerY())`. Uma entrada desativada não dispara nada
`ue_item_invoked (string as_keys)`	O utilizador invocou uma entrada — um clique, Enter, Espaço, Enter no campo de pesquisa —, incluindo a entrada já selecionada: abra (ou traga de volta) a sua página aqui, e uma folha fechada pela sua cruz volta a abrir-se a partir da barra. Só um gesto: `of_select_item` nunca o dispara. Depois de `ue_selection_changed` quando a seleção se moveu; nunca para uma entrada desativada, nem para uma mudança que `ue_selection_changing` recusou
`ue_filter_changed (string as_text)`	O utilizador escreveu no campo de pesquisa (`ib_search`): `as_text` filtra agora a barra; Escape esvazia-o. `is_filter` definido pelo seu código aplica-se sem este evento
`ue_selection_changing (string as_from_keys, string as_keys)` → boolean	Cancelável, colocado antes de a seleção se mover — um gesto do utilizador, `of_select_item` ou `of_clear_selection` —, e só quando `ib_veto_selection = true` (desativado por omissão). Devolva `false` para ficar onde está: nada se move, e a ordem do seu código devolve `-4`
`ue_auto_width (long al_width)`	O componente recalculou a sua largura ideal — requer `ib_auto_width = true`
`ue_ready ( )`	O componente terminou o carregamento; tudo o que foi enviado antes foi reproduzido
`ue_runtime_missing ( )`	O runtime WebView2 está ausente: o componente permanece vazio
`ue_bg_color (long al_color)`	O componente calculou a cor de fundo do respetivo tema; o userobject já a adotou (`backcolor`)

Exemplos #

// A barra inteira numa so renderizacao
uo_nav.of_set_redraw(/*on*/ false)

// Primeira seccao e as suas tres entradas
uo_nav.of_add_section(/*key*/ "folders", /*text*/ "Folders")
uo_nav.of_add_item(/*keys*/ "folders/recent",    /*text*/ "Recent",    /*image*/ "mono:img\clock.svg")
uo_nav.of_add_item(/*keys*/ "folders/customers", /*text*/ "Customers", /*image*/ "mono:img\user.svg")
uo_nav.of_add_item(/*keys*/ "folders/archives",  /*text*/ "Archives",  /*image*/ "mono:img\box.svg")

// Segunda seccao e as suas duas entradas
uo_nav.of_add_section(/*key*/ "tools", /*text*/ "Tools")
uo_nav.of_add_item(/*keys*/ "tools/import", /*text*/ "Import", /*image*/ "mono:img\import.svg")
uo_nav.of_add_item(/*keys*/ "tools/export", /*text*/ "Export", /*image*/ "mono:img\export.svg")

// Uma so renderizacao para tudo e depois a primeira entrada e selecionada
uo_nav.of_set_redraw(/*on*/ true)
uo_nav.of_select_item(/*keys*/ "folders/recent")

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

// evento ue_auto_width de uo_nav : (long al_width)
// A barra acabou de adotar a sua largura ideal : realinhar o que esta a sua direita.
uo_content.x     = uo_nav.x + al_width
uo_content.width = parent.width - uo_content.x

Acordeão: recolher uma secção #

// Recolher a seccao das pastas, pouco usada
uo_nav.of_section(/*key*/ "folders").ib_collapsed = true

// evento ue_section_toggled de uo_nav : (string as_key, boolean ab_collapsed)
// Lembrar o recolhimento escolhido pelo utilizador
of_save_preference("section_" + as_key, String(ab_collapsed))

Definições e Ajuda fixadas no fundo #

Uma secção sem título, fixada: nenhuma linha de cabeçalho, duas entradas que ficam no fundo da barra mesmo quando a navegação, mais longa do que a janela, desliza. Um clique aí seleciona como em qualquer outro lado: ue_selection_changed recebe foot/settings.

// Uma seccao SEM titulo (nenhuma linha de cabecalho), fixada no fundo da barra :
// fica visivel enquanto as entradas de cima deslizam
uo_nav.of_add_section(/*key*/ "foot", /*text*/ "")
uo_nav.of_add_item(/*keys*/ "foot/settings", /*text*/ "Settings", /*image*/ "mono:img\gear.svg")
uo_nav.of_add_item(/*keys*/ "foot/help",     /*text*/ "Help",     /*image*/ "mono:img\help.svg")
uo_nav.of_section(/*key*/ "foot").ib_pinned = true

Reagir à navegação #

// evento ue_selection_changed de uo_nav : (string as_from_keys, string as_keys)
// O endereco traz os dois niveis : duas seccoes podem ter ambas uma entrada "list".
// Local variables
n_pbt_utils lnv_utils   // autoinstantiate : nada a criar, nada a destruir
string ls_keys[]

// Divide o endereco : [1] = a seccao, [2] = a entrada
if lnv_utils.of_split_path(/*keys*/ as_keys, /*out*/ ls_keys) < 2 then return
choose case ls_keys[1]
    case "folders" ; of_open_folder(ls_keys[2])
    case "tools"   ; of_run_tool(ls_keys[2])
end choose

Reabrir a página da entrada atual #

ue_selection_changed só diz as mudanças: clicar de novo na entrada já selecionada não a move. Numa aplicação MDI cujo utilizador fechou a folha, é no entanto o gesto que a deve reabrir — ue_item_invoked responde a cada clique, incluindo a entrada atual.

// event ue_item_invoked de uo_nav : (string as_keys)
// Cada clique abre a pagina da entrada, mesmo ja selecionada :
// uma folha fechada pela sua cruz reabre-se a partir da barra
of_open_sheet(as_keys)

// event ue_item_rclicked de uo_nav : (string as_keys, long al_x, long al_y)
// Local variables
m_entry lm_menu

// Um menu PowerBuilder abre-se no ponteiro da JANELA ; al_x, al_y (pixeis
// do ecra) servem um menu da biblioteca : uo_menu.of_show(al_x, al_y)
lm_menu = create m_entry
lm_menu.m_root.PopMenu(parent.PointerX(), parent.PointerY())
destroy lm_menu

Pesquisar na barra #

// Um campo de pesquisa no topo da barra : Ctrl+F alcanca-o, Escape esvazia-o,
// Enter escolhe a primeira correspondencia
uo_nav.ib_search = true

// O codigo tambem filtra : so ficam as entradas que contem o texto
uo_nav.is_filter = "inv"

// Local variables
datastore lds_rights

// A tabela de direitos do utilizador : uma linha = uma entrada do menu
lds_rights = create datastore
lds_rights.DataObject = "d_menu_rights"
lds_rights.SetTransObject(SQLCA)
lds_rights.Retrieve()

// As colunas que nao tem o nome de um papel sao nomeadas por of_map
uo_nav.of_map(/*role*/ u_pbt_listbar.ROLE_SECTION, /*column*/ "menu_group")
uo_nav.of_map(/*role*/ u_pbt_listbar.ROLE_SECTION_TEXT, /*column*/ "group_title")
uo_nav.of_map(/*role*/ u_pbt_listbar.ROLE_KEY, /*column*/ "menu_code")
uo_nav.of_map(/*role*/ u_pbt_listbar.ROLE_ENABLED, /*column*/ "allowed")

// As entradas sao substituidas ; uma linha posta de lado e dita por of_get_last_error
uo_nav.of_from_datastore(/*ads*/ lds_rights)
destroy lds_rights

Recusar uma mudança de seleção #

// A pergunta esta desativada por OMISSAO : ativa-la para poder recusar uma mudanca
uo_nav.ib_veto_selection = true

// evento ue_selection_changing de uo_nav :
//   (string as_from_keys, string as_keys)
// Devolver FALSE mantem o utilizador na entrada que deixa.
if of_has_unsaved_changes(as_from_keys) then
    MessageBox("Entrada", "Termine a ficha atual antes de navegar.")
    return false
end if
return true

Atualizar uma entrada em tempo real #

// Local variables
n_pbt_listbar_item lnv_entry

// A entrada designa-se pelo seu endereco : a seccao e depois a entrada
lnv_entry = uo_nav.of_item(/*keys*/ "folders/recent")
lnv_entry.is_text  = "Recent (12)"
lnv_entry.is_image = "mono:img\clock_full.svg"

// Desativar ou ocultar consoante as permissoes, sem reconstruir a barra
uo_nav.of_item(/*keys*/ "tools/import").ib_enabled = of_is_allowed("import")
uo_nav.of_item(/*keys*/ "tools/export").ib_visible = gb_expert_mode

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

// Colocar a selecao noutro lado : a faixa de destaque segue, e
// ue_selection_changed parte como num clique
uo_nav.of_select_item(/*keys*/ "folders/customers")

// Ou apaga-la por completo
uo_nav.of_clear_selection()

Reconstruir a barra #

// of_clear esvazia seccoes e entradas ; of_reset repoe tambem as predefinicoes
uo_nav.of_clear()
of_build_menu_for_profile()

Boas práticas #

Uma entrada adiciona-se pelo seu endereço: of_add_item("nav/home", ...). 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. Uma tal secção não se recolhe.
Com o teclado: as setas Cima / Baixo percorrem títulos e entradas, Esquerda / Direita recolhem e expandem uma secção (invertidas da direita para a esquerda), Enter ou Espaço escolhe, uma letra salta para a linha seguinte que começa por ela (a mesma letra repetida passa à seguinte), a tecla Menu ou Shift+F10 abre o clique direito da entrada.
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 só ficam os ícones: cada entrada diz a sua etiqueta ao passar o rato, e uma entrada sem ícone mostra a sua inicial. Dê mesmo assim um ícone a cada uma — uma inicial distingue-se mal de outra.
A pergunta só é feita se a ativar (ib_veto_selection = true): faça-o apenas onde precisar de poder recusar uma mudança, porque cada pergunta custa uma ida e volta ao PowerBuilder. Ativada, é feita também para of_select_item e of_clear_selection, que devolvem então -4 numa recusa: defina a seleção inicial antes de ativar ib_veto_selection.
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.

Membros	Função	Detalhado em
`of_count` · `of_keys_at` · `of_has`	Percorrer o que o componente contém	3.2 Os items
`of_reset`	Repor o componente a zero	3.6 Repor um componente a zero: `of_reset()`
`of_register_shortcut` · `of_clear_shortcuts`	Atalhos de teclado do componente	3.5 Os atalhos de teclado
`of_is_created` · `of_is_ready` · `of_get_last_error`	Se nasceu, se está pronto, o que falhou	3.7 Diagnóstico
`of_save_as_png` · `of_save_as_jpg`	Exportar a renderização como imagem	3.8 Exportar a representação como imagem
`of_set_redraw`	Agrupar as alterações num único repinte	3.10 Boas práticas
`of_preload_icons`	Ícones mostrados sem atraso	Apresentação instantânea: `of_icon`
`of_set_translation`	Traduzir uma legenda do componente	5.2 Adaptar uma etiqueta: `of_set_translation`
`of_focus_webview`	Dar o foco ao componente	6.4 Teclado e focus
`of_print` · `of_print_to_pdf`	Imprimir, ou escrever um PDF	6.9 Imprimir
`of_set_property` · `of_get_property` · `of_component_name`	Controlar uma propriedade pelo nome	3.1 O motor de propriedades
`is_accessible_name` · `is_accessible_description`	O nome e a descrição que um leitor de ecrã diz	3.4 Propriedades e eventos opcionais

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

listbar — `u_pbt_listbar` #

Em resumo #

Início rápido #

Dois níveis, um endereço #

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 #

Calha recolhível que liberta espaço #

Acordeão: recolher uma secção #

Definições e Ajuda fixadas no fundo #

Reagir à navegação #

Reabrir a página da entrada atual #

O seu menu no clique direito de uma entrada #

Pesquisar na barra #

Construir o menu a partir de uma tabela de direitos #

Recusar uma mudança de seleção #

Atualizar uma entrada em tempo real #

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

Reconstruir a barra #

Boas práticas #

Herdado da base comum #

listbar — u_pbt_listbar #

Em resumo #

Início rápido #

Dois níveis, um endereço #

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 #

Calha recolhível que liberta espaço #

Acordeão: recolher uma secção #

Definições e Ajuda fixadas no fundo #

Reagir à navegação #

Reabrir a página da entrada atual #

O seu menu no clique direito de uma entrada #

Pesquisar na barra #

Construir o menu a partir de uma tabela de direitos #

Recusar uma mudança de seleção #

Atualizar uma entrada em tempo real #

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

Reconstruir a barra #

Boas práticas #

Herdado da base comum #

listbar — `u_pbt_listbar` #

Propriedades de uma secção — `n_pbt_listbar_section` #

Propriedades de uma entrada — `n_pbt_listbar_item` #

Numa secção — `n_pbt_listbar_section` #