statusbar — u_pbt_statusbar #

← Referência dos componentes · Índice do guia

Barra de estado com painéis: texto rico, ícones, larguras fixas ou automáticas, alinhamento à esquerda ou à direita, painéis clicáveis, mini-barra de progresso e estados coloridos.

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

Em resumo #

Início rápido #

// event open da janela
// of_add_panel(id, texto, icone, alinhamento, largura)
// a chave encontra o painel mais tarde ; largura 0 = ajustada ao texto
uo_status.of_add_panel(/*key*/ "state",  /*text*/ "Pronto",         /*icon_file*/ "", /*align*/ uo_status.ALIGN_START,  /*width*/ 0)
uo_status.of_add_panel(/*key*/ "pos",   /*text*/ "Linha 12, Col 4", /*icon_file*/ "", /*align*/ uo_status.ALIGN_START,  /*width*/ 0)
uo_status.of_add_panel(/*key*/ "clock", /*text*/ "12:00",          /*icon_file*/ "", /*align*/ uo_status.ALIGN_END, /*width*/ 140)

// Atualizar um painel a qualquer momento, pelo seu identificador
uo_status.of_panel(/*key*/ "state").is_text = "A guardar..."

O modelo: painéis com chave #

A barra é uma sequência de painéis, adicionados por ordem. Um painel recebe um identificador na criação: é através dele que se volta a encontrá-lo mais tarde, para mudar o seu texto, o seu ícone ou o seu estado.

O identificador é uma chave de endereçamento, não um interruptor de interatividade:

• Identificador indicado: o painel pode ser reencontrado — muda-se o seu conteúdo, dá-se-lhe uma dica. Mantém-se inerte: uma barra de estado mostra acima de tudo, e um painel como Linha 12, Col 4 não deve parecer premível. Recebe no entanto o clique direito (ue_panel_rclicked) : um menu de contexto « Copiar » não é uma ativação.
• Identificador vazio: o painel é puramente decorativo. Não pode ser reencontrado nem clicado, e nenhuma dica lhe pode ser associada. Dê um identificador a todos os seus painéis: não custa nada e mantém a porta aberta. Conta no entanto em of_count e nas posições, e of_keys_at devolve para ele uma chave vazia.
• Para tornar um painel clicável, peça-o: of_panel(/*key*/ "id").ib_clickable = true. Um painel com uma lista pendente (of_add_menu_item) já o é.

// O painel mostra um novo texto
uo_status.of_panel(/*key*/ "state").is_text = "3 registos modificados"

Ver Base comum · Os items.

Propriedades #

Métodos #

Os argumentos de of_add_panel #

Sobre um painel — n_pbt_statusbar_panel #

Sobre uma entrada de lista — n_pbt_statusbar_menu_item #

Obtida com of_menu_item(/*keys*/ "enc/utf8"): o endereço tem dois níveis, o painel e depois a entrada. A lista é um menu nativo: uma propriedade alterada enquanto está aberto vê-se na abertura seguinte.

// The menu of the encoding panel, entry by entry
uo_status.of_add_menu_item(/*keys*/ "enc/utf8", /*label*/ "UTF-8")
uo_status.of_add_menu_item(/*keys*/ "enc/ansi", /*label*/ "ANSI")
uo_status.of_menu_item(/*keys*/ "enc/utf8").ib_checked = true     // the current value
uo_status.of_menu_item(/*keys*/ "enc/ansi").ib_enabled = false    // not available here

Constantes de estado #

Tal como para qualquer propriedade com valores predefinidos, deve utilizar-se a constante em vez da cadeia de caracteres:

// The panel takes the colors of a warning
uo_status.of_panel(/*key*/ "state").is_state = n_pbt_statusbar_panel.STATE_WARNING

Eventos #

Com o teclado #

A barra é uma única paragem de tabulação: só entram nela os painéis feitos para serem clicados, e as setas percorrem-nos.

Um painel que se limita a apresentar não é um controlo: não é focável nem anunciado como tal. Um painel clicável mas desativado permanece, esse sim, anunciado como indisponível em vez de passar por texto. Uma barra de progresso anuncia o seu valor, e uma indeterminada não anuncia nenhum — essa ausência é o sentido da palavra.

O foco sobrevive à reconstrução da barra: ela é redesenhada a cada mudança de texto e, sem isto, o foco cairia a cada segundo numa barra que apresenta um relógio.

Exemplos #

Larguras fixas e larguras automáticas #

// Largura 0 : o painel ocupa exatamente o espaco do seu texto
uo_status.of_add_panel(/*key*/ "", /*text*/ "Painel ajustado ao conteúdo", /*icon_file*/ "", /*align*/ uo_status.ALIGN_START, /*width*/ 0)

// Largura fixa em pixeis : util quando o texto muda com frequencia,
// para que os paineis vizinhos nao se desloquem a cada atualizacao
uo_status.of_add_panel(/*key*/ "pos", /*text*/ "Linha 1, Col 1", /*icon_file*/ "", /*align*/ uo_status.ALIGN_START, /*width*/ 150)

// Um painel empurrado para a extremidade oposta
uo_status.of_add_panel(/*key*/ "clock", /*text*/ "12:00", /*icon_file*/ "", /*align*/ uo_status.ALIGN_END, /*width*/ 140)

Ícones e painéis clicáveis #

// Uma chave torna o painel enderecavel ; ib_clickable torna-o clicavel
uo_status.of_add_panel(/*key*/ "save", /*text*/ "Guardado", /*icon_file*/ "mono:img\save.svg", /*align*/ uo_status.ALIGN_START, /*width*/ 0)
uo_status.of_add_sep()   // traco de separacao entre dois grupos de paineis
uo_status.of_add_panel(/*key*/ "conn", /*text*/ "Ligado",   /*icon_file*/ "mono:img\plug.svg", /*align*/ uo_status.ALIGN_START, /*width*/ 0)
uo_status.of_add_panel(/*key*/ "user", /*text*/ "Alex Martin",  /*icon_file*/ "mono:img\user.svg", /*align*/ uo_status.ALIGN_END, /*width*/ 160)

// So estes dois respondem ao clique (ue_panel_clicked)
uo_status.of_panel(/*key*/ "conn").ib_clickable = true
uo_status.of_panel(/*key*/ "user").ib_clickable = true

// event ue_panel_clicked de uo_status
choose case as_key
    case "conn" ; open(w_connection_settings)
    case "user" ; open(w_profile)
end choose

Texto rico num painel #

Os painéis aceitam as etiquetas de texto rico: estilos, cores e pequenas imagens diretamente no texto.

// Uma saudacao a esquerda
uo_status.of_add_panel(/*key*/ "", /*text*/ "Bem-vindo [b]ao[/b] [accent]PBToolboxAI[/accent]", &
                       /*icon_file*/ "", /*align*/ uo_status.ALIGN_START, /*width*/ 0)

// O estado da ligacao a direita
uo_status.of_add_panel(/*key*/ "", /*text*/ "[green]Em linha[/green] [picture=mono:img\plug.svg,14,14]", &
                       /*icon_file*/ "", /*align*/ uo_status.ALIGN_END, /*width*/ 0)

// O texto rico vale igualmente para as atualizacoes
uo_status.of_panel(/*key*/ "state").is_text = "[b]" + String(ll_changed) + "[/b] registos modificados"

Acompanhar um processamento demorado #

// Local variables
n_pbt_statusbar_panel lnv_import

// O painel de importacao, depois o seu handle para o acompanhar
uo_status.of_add_panel(/*key*/ "import", /*text*/ "Importação", /*icon_file*/ "", /*align*/ uo_status.ALIGN_START, /*width*/ 220)
lnv_import = uo_status.of_panel(/*key*/ "import")

// No ciclo de processamento : a mini-barra acompanha o progresso
lnv_import.ii_progress = ll_percent
lnv_import.is_text     = "Importação " + String(ll_percent) + " %"

// No fim : ocultar a mini-barra e assinalar o resultado
lnv_import.ii_progress = -1                       // valor negativo = barra ocultada
lnv_import.is_text     = "Importação concluída"
lnv_import.is_state    = lnv_import.STATE_SUCCESS

Assinalar um alerta discreto #

// Local variables
n_pbt_statusbar_panel lnv_panel

// O painel da ligacao
lnv_panel = uo_status.of_panel(/*key*/ "conn")

// Sem ligacao : o painel mostra um erro ; ligado : volta ao normal
if not ib_connected then
    lnv_panel.is_text  = "Sem ligação"
    lnv_panel.is_state = lnv_panel.STATE_ERROR
else
    lnv_panel.is_text  = "Ligado"
    lnv_panel.is_state = lnv_panel.STATE_NONE   // regresso ao aspeto normal
end if

Adaptar a barra ao contexto #

// Ocultar um painel sem o suprimir : voltara a ocupar o seu lugar mais tarde
uo_status.of_panel(/*key*/ "user").ib_visible = ib_user_signed_in

// Esbate-lo quando a acao correspondente nao faz sentido
uo_status.of_panel(/*key*/ "save").ib_enabled = ib_document_open

// Reorganizar : colocar o painel de estado a cabeca (posicoes contadas a partir de 1)
uo_status.of_move_panel(/*key*/ "state", /*index*/ 1)

// Retirar um painel que se tornou inutil
uo_status.of_remove_panel(/*key*/ "import")

A pega de redimensionamento #

// Arrastar a pega de canto redimensiona a janela (oculta enquanto estiver maximizada)
uo_status.ib_show_resize_grip = true

Boas práticas #

• Atribua uma largura fixa aos painéis cujo texto muda com frequência (posição do cursor, contadores): os painéis vizinhos deixarão de saltar a cada atualização.
• Um painel é inerte por predefinição: peça o clique com ib_clickable, e deixe sem reação os painéis que só mostram.
• Reserve o fim da barra (ALIGN_END) para a informação estável (hora, utilizador, ligação) e o início (ALIGN_START) para o contexto atual; na leitura da direita para a esquerda, os dois lados trocam sozinhos.
• Utilize is_state em vez de cores no texto: o estado acompanha tanto o tema claro como o escuro.
• Não se esqueça de repor is_state em STATE_NONE e ii_progress num valor negativo assim que o alerta ou o processamento terminar.
• Uma barra de estado não é um registo de eventos: para além de cinco ou seis painéis, é preferível uma notificação toaster.
• Se o progresso merece mais do que uma mini-barra de painel, deve passar-se à progressbar.

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