statusbar — u_pbt_statusbar #

← Referencia de componentes · Índice de la guía

Barra de estado con paneles: texto enriquecido, iconos, anchuras fijas o automáticas, alineación a la izquierda o a la derecha, paneles en los que se puede hacer clic, mini barra de progreso y estados con color.

▶ Verlo en vivo — Aplicación de demostración, mosaico Statusbar: la vista previa, el código que lo genera y esta página, uno al lado del otro.

De un vistazo #

Inicio rápido #

// event open de la ventana
// of_add_panel(clave, texto, icono, alineacion, anchura)
// la clave encuentra el panel mas tarde ; anchura 0 = ajustada al texto, -1 = toma el espacio libre
uo_status.of_add_panel(/*key*/ "state", /*text*/ "Ready",          /*icon_file*/ "", /*align*/ uo_status.ALIGN_START, /*width*/ -1)
uo_status.of_add_panel(/*key*/ "pos",   /*text*/ "Line 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)

// Actualizar un panel en cualquier momento, mediante su identificador
uo_status.of_panel(/*key*/ "state").is_text = "Guardando..."

El modelo: paneles con clave #

La barra es una sucesión de paneles, añadidos por orden. Un panel recibe un identificador al crearse: es por él como se le encuentra después para cambiar su texto, su icono o su estado.

El identificador es una clave de direccionamiento, no un interruptor de interactividad:

• Identificador indicado: el panel se puede volver a encontrar — se cambia su contenido, se le pone una información sobre herramientas. Sigue siendo inerte: una barra de estado muestra ante todo, y un panel como Línea 12, Col 4 no debe parecer pulsable. Recibe sin embargo el clic derecho (ue_panel_rclicked) : un menú contextual « Copiar » no es una activación.
• Identificador vacío: el panel es puramente decorativo. No se puede encontrar ni pulsar, y no se le puede adjuntar ninguna información sobre herramientas. Dé un identificador a todos sus paneles: no cuesta nada y deja la puerta abierta. Cuenta sin embargo en of_count y en las posiciones, y of_keys_at devuelve para él una clave vacía.
• Para hacer un panel pulsable, pídalo: of_panel(/*key*/ "id").ib_clickable = true. Un panel dotado de una lista desplegable (of_add_menu_item) ya lo es.

// El panel muestra un texto nuevo
uo_status.of_panel(/*key*/ "state").is_text = "3 registros modificados"

Véase Base común · Los items.

Propiedades #

Métodos #

Los argumentos de of_add_panel #

En un panel — n_pbt_statusbar_panel #

En una entrada de lista — n_pbt_statusbar_menu_item #

Obtenida con of_menu_item(/*keys*/ "enc/utf8"): la dirección tiene dos niveles, el panel y luego la entrada. La lista es un menú nativo: una propiedad cambiada mientras está abierto se ve en la siguiente apertura.

Las propiedades que hereda todo manejador de elemento — is_tooltip, is_super_tooltip_title, is_super_tooltip_text, is_super_tooltip_image, il_accent, il_back_color, il_text_color, il_back_color_hover, il_text_color_hover — no tienen efecto en una entrada: la lista es un menú nativo, que no muestra ni información sobre herramientas ni colores de una entrada. Se ignoran y se releen vacías (-1 para un color). Una posición en una lista cuenta entradas: un separador no lo es, y of_count("enc"), of_keys_at("enc", n), of_has("enc/utf8") recorren las entradas de un panel. Una clave que empieza por __ está reservada al componente.

// 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 #

Como para toda propiedad con valores predefinidos, utilice la constante en lugar de la cadena:

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

Eventos #

Con el teclado #

La barra es una sola parada de tabulación: solo entran en ella los paneles hechos para ser pulsados, y las flechas los recorren.

Un panel que se limita a mostrar no es un control: no es enfocable ni se anuncia como tal. Un panel pulsable pero desactivado sí permanece anunciado como no disponible, en lugar de pasar por texto. Una barra de progreso anuncia su valor, y una indeterminada no anuncia ninguno — esa ausencia es el sentido de la palabra. Un panel clicable atenuado sigue mostrando su información sobre herramientas — la que dice por qué está atenuado — y un panel con lista dice si su lista está abierta.

Un lector de pantalla oye los mensajes de of_flash_panel sin que el foco se mueva: para eso sirve una barra de estado (una región viva cortés). Los demás cambios — un texto nuevo, un estado nuevo — solo se leen con ib_announce = true; si no, un reloj al segundo hablaría todo el día.

El foco sobrevive a la reconstrucción de la barra: un panel añadido, quitado, oculto o atenuado la reconstruye, y el foco vuelve al mismo panel (al siguiente cuando ya no puede tomarlo). Un texto, un estado o un progreso cambian en su sitio, sin reconstruir nada — un reloj al segundo nunca roba el foco.

Ejemplos #

Anchuras fijas y anchuras automáticas #

// Anchura 0 : el panel ocupa exactamente el espacio de su texto
uo_status.of_add_panel(/*key*/ "", /*text*/ "Panel ajustado al contenido", /*icon_file*/ "", /*align*/ uo_status.ALIGN_START, /*width*/ 0)

// Anchura fija en pixeles : util cuando el texto cambia a menudo,
// para que los paneles vecinos no se muevan en cada actualizacion
uo_status.of_add_panel(/*key*/ "pos", /*text*/ "Línea 1, Col 1", /*icon_file*/ "", /*align*/ uo_status.ALIGN_START, /*width*/ 150)

// Un panel empujado al extremo opuesto
uo_status.of_add_panel(/*key*/ "clock", /*text*/ "12:00", /*icon_file*/ "", /*align*/ uo_status.ALIGN_END, /*width*/ 140)

Iconos y paneles con clic #

// Una clave hace el panel direccionable ; ib_clickable lo hace pulsable
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()   // linea de separacion entre dos grupos de paneles
uo_status.of_add_panel(/*key*/ "conn", /*text*/ "Conectado",   /*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)

// Solo estos dos responden al clic (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 enriquecido en un panel #

Los paneles aceptan el texto enriquecido con etiquetas: estilos, colores y pequeñas imágenes directamente en el texto.

// Una bienvenida a la izquierda
uo_status.of_add_panel(/*key*/ "", /*text*/ "Bienvenido [b]a[/b] [accent]PBToolboxAI[/accent]", &
                       /*icon_file*/ "", /*align*/ uo_status.ALIGN_START, /*width*/ 0)

// El estado de la conexion a la derecha
uo_status.of_add_panel(/*key*/ "", /*text*/ "[green]En línea[/green] [picture=mono:img\plug.svg,14,14]", &
                       /*icon_file*/ "", /*align*/ uo_status.ALIGN_END, /*width*/ 0)

// Variables locales
long ll_changed

// El texto enriquecido vale tambien para las actualizaciones
ll_changed = dw_list.ModifiedCount()
uo_status.of_panel(/*key*/ "state").is_text = "[b]" + String(ll_changed) + "[/b] records changed"

Seguir un proceso largo #

// Local variables
n_pbt_statusbar_panel lnv_import

// El panel de importacion, luego su handle para seguirlo
uo_status.of_add_panel(/*key*/ "import", /*text*/ "Importación", /*icon_file*/ "", /*align*/ uo_status.ALIGN_START, /*width*/ 220)
lnv_import = uo_status.of_panel(/*key*/ "import")

// Variables locales
long ll_percent

// En el bucle de tratamiento : la mini barra sigue el progreso
for ll_percent = 0 to 100 step 25
    lnv_import.ii_progress = ll_percent
    lnv_import.is_text     = "Import " + String(ll_percent) + " %"
next

// Al final : ocultar la mini barra y senalar el resultado
lnv_import.ii_progress = -1                       // valor negativo = barra oculta
lnv_import.is_text     = "Importación finalizada"
lnv_import.is_state    = lnv_import.STATE_SUCCESS

Señalar un aviso discreto #

// Local variables
n_pbt_statusbar_panel lnv_panel

// El panel de la conexion
lnv_panel = uo_status.of_panel(/*key*/ "conn")

// Sin conexion : el panel muestra un error ; conectado : vuelve a la normalidad
if not ib_connected then
    lnv_panel.is_text  = "Sin conexión"
    lnv_panel.is_state = lnv_panel.STATE_ERROR
else
    lnv_panel.is_text  = "Conectado"
    lnv_panel.is_state = lnv_panel.STATE_NONE   // vuelta a la apariencia normal
end if

Adaptar la barra al contexto #

// Ocultar un panel sin eliminarlo : mas tarde recuperara su sitio
uo_status.of_panel(/*key*/ "user").ib_visible = ib_user_signed_in

// Atenuarlo cuando la accion correspondiente no tiene sentido
uo_status.of_panel(/*key*/ "save").ib_enabled = ib_document_open

// Reorganizar : colocar el panel de estado al principio (posiciones contadas a partir de 1)
uo_status.of_move_panel(/*key*/ "state", /*index*/ 1)

// Retirar un panel que ya no sirve
uo_status.of_remove_panel(/*key*/ "import")

El asa de redimensionamiento #

// Arrastrar el asa de la esquina redimensiona la ventana que lleva la barra (oculta mientras esta maximizada)
uo_status.ib_show_resize_grip = true

Un panel que toma el espacio libre #

Como el panel « Listo » de toda barra de estado de Windows: crece con la ventana, empuja los paneles del final hasta el extremo, y su texto es el primero en recortarse cuando falta espacio.

// Una anchura de -1 : el panel toma todo el espacio libre
uo_status.of_add_panel(/*key*/ "state", /*text*/ "Ready", /*icon_file*/ "", /*align*/ uo_status.ALIGN_START, /*width*/ -1)
uo_status.of_add_panel(/*key*/ "clock", /*text*/ "12:00", /*icon_file*/ "", /*align*/ uo_status.ALIGN_END, /*width*/ 140)

// Lo mismo en un panel que ya existe
uo_status.of_panel(/*key*/ "state").ib_spring = true

Colocar la barra al pie de la ventana #

of_dock_bottom la coloca a lo largo del borde inferior de lo que la lleva, en todo el ancho: basta una llamada en el evento resize. En un marco MDI, las hojas se reparten lo que queda encima.

// evento resize de la ventana : la barra sigue el borde inferior
uo_status.of_dock_bottom()

// evento resize de un marco MDI : la barra abajo, las hojas encima
uo_status.of_dock_bottom()
mdi_1.Resize(WorkSpaceWidth(), WorkSpaceHeight() - uo_status.Height)

Retomar la MicroHelp #

En un marco MDI con MicroHelp, PowerBuilder escribe la ayuda del elemento de menú bajo el puntero, y SetMicroHelp escribe la suya. La barra retoma ese papel: nombre una vez el panel que muestra la ayuda (is_help_panel) y luego escriba is_help donde llamaba a SetMicroHelp. La ayuda se muestra encima del texto del panel, y "" le devuelve el texto.

// Una vez : el panel que muestra la ayuda (el primero, normalmente)
uo_status.is_help_panel = "state"

// Donde llamaba a SetMicroHelp : la ayuda aparece encima de Ready
uo_status.is_help = "Saving the order..."

// "" devuelve al panel su propio texto
uo_status.is_help = ""

// evento ue_item_hover de una menubar (uo_menu) : la ayuda de la entrada bajo el puntero
uo_status.is_help = this.of_item(/*keys*/ as_keys).is_tooltip

// evento getfocus de un campo (sle_name) : su Tag es su ayuda
uo_status.is_help = sle_name.Tag

Buenas prácticas #

• Dé una anchura fija a los paneles cuyo texto cambia a menudo (posición del cursor, contadores): los paneles vecinos dejarán de saltar en cada actualización.
• Haga del primer panel un muelle (ib_spring, o una anchura de -1): toma el espacio libre, y su texto es el primero en recortarse.
• Un panel es inerte por defecto: pida el clic con ib_clickable, y deje sin reacción los paneles que solo muestran.
• Reserve el final de la barra (ALIGN_END) a la información estable (hora, usuario, conexión) y el principio (ALIGN_START) al contexto actual; en lectura de derecha a izquierda, los dos lados se invierten solos.
• Emplee is_state en lugar de colores en el texto: el estado sigue tanto el tema claro como el oscuro.
• Recuerde devolver is_state a STATE_NONE y ii_progress a un valor negativo en cuanto el aviso o el proceso haya terminado.
• Una barra de estado no es un registro: más allá de cinco o seis paneles, es preferible una notificación toaster.
• Si el avance merece más que una mini barra de panel, pase a la progressbar.

Heredado de la base común #

Estos miembros existen en todos los componentes visuales — no son propios de este. Se detallan una sola vez, en los capítulos transversales; esta tabla solo dice dónde leerlos.

Dos ayudas no se heredan: of_icon y of_escape_markup viven en n_pbt_utils. Declare uno — n_pbt_utils lnv_utils, nada que crear — y llámelas sobre él.

← Referencia de componentes · Índice de la guía