dockcontainer — u_pbt_dockcontainer #

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

Paneles acoplables al estilo de Visual Studio: acoplamiento mediante arrastrar y soltar, apilamiento en pestañas, separadores redimensionables, ventanas flotantes, ocultación automática — y guardado/restauración de la disposición.

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

De un vistazo #

Al igual que tab, cada panel aloja un control real de PowerBuilder (dragobject): userobject, DataWindow u otro componente PBToolboxAI. Véase Alojar controles reales de PowerBuilder.

Inicio rápido #

// event open de la ventana : los controles de panel ya estan colocados en ella
uo_dock.of_add_panel(/*key*/ "document", /*position*/ "", /*relative_to*/ "", /*size*/ 0, /*title*/ "Documento", /*content*/ uo_editor)

// El explorador, acoplado al inicio del documento, de 260 pixeles
uo_dock.of_add_panel(/*key*/ "explorer", /*position*/ uo_dock.POSITION_START, /*relative_to*/ "document", /*size*/ 260, /*title*/ "Explorador", /*content*/ uo_tree)

// Las propiedades, acopladas al final del documento, de 300 pixeles
uo_dock.of_add_panel(/*key*/ "properties", /*position*/ uo_dock.POSITION_END, /*relative_to*/ "document", /*size*/ 300, /*title*/ "Propiedades", /*content*/ uo_props)

// La zona central : ni cerrable por el acoplamiento, ni flotante, ni ocultable
uo_dock.is_main = "document"

Propiedades #

Posiciones de acoplamiento #

Las constantes del componente alimentan as_position en of_add_panel y of_move_panel:

Propiedades de un panel — n_pbt_dock_panel #

Obtenidas mediante of_panel(clave).

Métodos #

Eventos #

Con el ratón #

Además de arrastrar pestañas y divisores, tres gestos actúan sobre un panel — nunca sobre el panel principal:

Con el teclado #

El contenido de un panel es un verdadero control PowerBuilder: allí el teclado pertenece a su código, como en cualquier ventana. De lo que se encarga el componente es de su propio armazón — encabezados, pestañas, divisores:

Un divisor es un separator enfocable que anuncia su posición; los botones del encabezado (desacoplar, ocultar, cerrar) llevan un nombre, y el panel activo de un grupo está marcado con aria-selected. Un desplazamiento con el teclado se informa en ue_layout_changed exactamente igual que un arrastre con el ratón.

Ejemplos #

Una ventana al estilo de un IDE #

// event open : cada contenido es un control PB real colocado en la ventana
uo_dock.of_add_panel(/*key*/ "document", /*position*/ "", /*relative_to*/ "", /*size*/ 0, /*title*/ "Documento", /*content*/ uo_editor)
uo_dock.of_add_panel(/*key*/ "explorer", /*position*/ uo_dock.POSITION_START, /*relative_to*/ "document", /*size*/ 260, /*title*/ "Explorador", /*content*/ uo_tree)
uo_dock.of_add_panel(/*key*/ "properties", /*position*/ uo_dock.POSITION_END, /*relative_to*/ "document", /*size*/ 300, /*title*/ "Propiedades", /*content*/ uo_props)
uo_dock.of_add_panel(/*key*/ "output", /*position*/ uo_dock.POSITION_BOTTOM, /*relative_to*/ "document", /*size*/ 200, /*title*/ "Salida", /*content*/ uo_console)

// Un segundo panel apilado como pestana sobre "properties"
uo_dock.of_add_panel(/*key*/ "help", /*position*/ uo_dock.POSITION_STACK, /*relative_to*/ "properties", /*size*/ 0, /*title*/ "Ayuda", /*content*/ uo_help)

// El documento es la zona central
uo_dock.is_main = "document"

Memorizar y restaurar la disposición del usuario #

// event close de la ventana : guardar lo que el usuario ha organizado
string ls_layout
ls_layout = uo_dock.of_get_layout()
of_save_setting(/*name*/ "main_dock", /*value*/ ls_layout)

// event open : VOLVER A CREAR primero los paneles, restaurar despues
string ls_layout

// Primero los paneles : las llamadas of_add_panel anteriores
of_create_panels()

// Luego la disposicion guardada en el ultimo cierre, si la hay
ls_layout = of_read_setting(/*name*/ "main_dock")
if ls_layout <> "" then uo_dock.of_set_layout(/*json*/ ls_layout)

El orden es obligatorio: of_set_layout no crea ningún panel, solo recoloca los que ya existen.

Seguir los cambios de forma continua #

// event ue_layout_changed de uo_dock : (string as_json)
// Guardado inmediato, sin esperar al cierre de la ventana.
of_save_setting(/*name*/ "main_dock", /*value*/ as_json)

Controlar un panel mediante su handle #

// Local variables
n_pbt_dock_panel lnv_panel

// El panel de propiedades : un titulo que cuenta los cambios, plegado en su borde
lnv_panel = uo_dock.of_panel(/*key*/ "properties")
lnv_panel.is_title  = "Propiedades (3 modificadas)"
lnv_panel.ib_pinned = false        // se repliega en una lengueta sobre el borde

// Ocultar un panel reservado a los administradores
uo_dock.of_panel(/*key*/ "audit").ib_visible = gb_administrator

Llamar la atención sobre un panel en segundo plano #

// Un proceso en segundo plano ha escrito en la consola : avisar sin robar el foco
uo_dock.of_notify_panel(/*key*/ "output")

Reorganizar desde el código #

// Mover un panel como si el usuario hubiera arrastrado su pestana
uo_dock.of_move_panel(/*key*/ "output", /*target*/ "document", /*position*/ "bottom")

// Apilarlo como pestana sobre otro panel
uo_dock.of_move_panel(/*key*/ "help", /*target*/ "properties", /*position*/ "stack")

Desacoplar un panel en una segunda pantalla #

// Ventana flotante nativa : el usuario puede colocarla en otra pantalla
uo_dock.of_float_panel(/*key*/ "properties")

// event ue_panel_docked de uo_dock : (string as_key)
// El usuario ha cerrado la ventana flotante : el panel ha vuelto.
of_log(/*msg*/ "Panel reacoplado : " + as_key)

Cerrar correctamente un panel #

// event ue_panel_closed de uo_dock : (string as_key)
// Retirar tambien el panel del contenedor para liberar el control alojado.
uo_dock.of_remove_panel(/*key*/ as_key)

Rechazar el cierre de un panel con trabajo sin guardar #

// event open de la ventana : preguntar antes de que se cierre un panel (desactivado por defecto)
uo_dock.ib_veto_close = true

// ue_panel_closing event of uo_dock : (string as_key) returns boolean
// El editor aun tiene cambios sin guardar : su panel sigue abierto.
if as_key = "editor" then
    if ib_editor_modified then return false
end if
return true

// Su codigo plantea la misma pregunta : -4 cuando se rechaza
if uo_dock.of_close_panel(/*key*/ "editor") = -4 then
    st_status.Text = "Guarde el documento antes de cerrar el editor."
end if

Buenas prácticas #

• Designe siempre un panel principal con is_main: sin zona central, el usuario puede ocultarlo todo y encontrarse ante una ventana vacía.
• Guarde la disposición en ue_layout_changed en lugar de únicamente al cerrar: así un cierre anómalo no pierde nada.
• of_set_layout va después de los of_add_panel, nunca antes.
• Utilice of_notify_panel para los procesos en segundo plano: es menos intrusivo que un cuadro de diálogo y la información permanece visible.
• Un control alojado es una ventana nativa: se dibuja por encima de la capa web, ningún efecto visual del componente pasa por delante de él.
• of_reset() antes de cualquier reconstrucción: sin él, los controles alojados anteriormente siguen reasignados al contenedor vaciado y reutilizar una clave falla.
• Para simples páginas exclusivas, sin acoplamiento ni flotación, tab es más ligero.

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