dockcontainer — u_pbt_dockcontainer #

← Référence des composants · Sommaire du guide

Panneaux dockables façon Visual Studio : docking par glisser-déposer, empilement en onglets, séparateurs redimensionnables, fenêtres flottantes, masquage automatique — et sauvegarde/restauration de la disposition.

▶ Le voir en vrai — Application de démonstration, tuile Dock container : l'aperçu, le code qui le produit et cette page, côte à côte.

En bref #

Comme tab, chaque panneau héberge un vrai contrôle PowerBuilder (dragobject) : userobject, DataWindow, ou un autre composant PBToolboxAI. Voir Héberger de vrais contrôles PowerBuilder.

Démarrage rapide #

// event open de la fenetre : les controles de panneau sont deja poses dessus
uo_dock.of_add_panel(/*key*/ "document", /*position*/ "", /*relative_to*/ "", /*size*/ 0, /*title*/ "Document", /*content*/ uo_editor)

// L'explorateur, accole au debut du document, sur 260 pixels
uo_dock.of_add_panel(/*key*/ "explorer", /*position*/ uo_dock.POSITION_START, /*relative_to*/ "document", /*size*/ 260, /*title*/ "Explorateur", /*content*/ uo_tree)

// Les proprietes, accolees a la fin du document, sur 300 pixels
uo_dock.of_add_panel(/*key*/ "properties", /*position*/ uo_dock.POSITION_END, /*relative_to*/ "document", /*size*/ 300, /*title*/ "Proprietes", /*content*/ uo_props)

// La zone centrale : ni fermable par le docking, ni flottante, ni masquable
uo_dock.is_main = "document"

Propriétés #

Positions de docking #

Les constantes du composant alimentent as_position dans of_add_panel et of_move_panel :

Propriétés d'un panneau — n_pbt_dock_panel #

Obtenues par of_panel(cle).

Méthodes #

Événements #

À la souris #

Au-delà du glisser-déposer des onglets et des séparateurs, trois gestes agissent sur un panneau — jamais sur le panneau principal :

Au clavier #

Le contenu d'un panneau est un vrai contrôle PowerBuilder : le clavier y appartient à votre code, comme dans n'importe quelle fenêtre. Ce que le composant prend en charge, c'est son propre habillage — en-têtes, onglets, splitters :

Un splitter est un separator focalisable qui annonce sa position ; les boutons d'en-tête (détacher, masquer, fermer) portent un nom, et le panneau actif d'un groupe est marqué aria-selected. Un déplacement au clavier remonte dans ue_layout_changed exactement comme un glissement à la souris.

Exemples #

Une fenêtre façon IDE #

// event open : chaque contenu est un vrai controle PB pose sur la fenetre
uo_dock.of_add_panel(/*key*/ "document", /*position*/ "", /*relative_to*/ "", /*size*/ 0, /*title*/ "Document", /*content*/ uo_editor)
uo_dock.of_add_panel(/*key*/ "explorer", /*position*/ uo_dock.POSITION_START, /*relative_to*/ "document", /*size*/ 260, /*title*/ "Explorateur", /*content*/ uo_tree)
uo_dock.of_add_panel(/*key*/ "properties", /*position*/ uo_dock.POSITION_END, /*relative_to*/ "document", /*size*/ 300, /*title*/ "Proprietes", /*content*/ uo_props)
uo_dock.of_add_panel(/*key*/ "output", /*position*/ uo_dock.POSITION_BOTTOM, /*relative_to*/ "document", /*size*/ 200, /*title*/ "Sortie", /*content*/ uo_console)

// Un second panneau empile en onglet sur "properties"
uo_dock.of_add_panel(/*key*/ "help", /*position*/ uo_dock.POSITION_STACK, /*relative_to*/ "properties", /*size*/ 0, /*title*/ "Aide", /*content*/ uo_help)

// Le document est la zone centrale
uo_dock.is_main = "document"

Mémoriser et restaurer la disposition de l'utilisateur #

// event close de la fenetre : enregistrer ce que l'utilisateur a organise
// Local variables
string ls_layout

// La disposition courante, prete a ranger
ls_layout = uo_dock.of_get_layout()
of_save_setting(/*name*/ "main_dock", /*value*/ ls_layout)

// event open : LIRE la disposition enregistree, PUIS creer les panneaux
// Local variables
string ls_layout

// D'abord le reglage : construire le dock leve ue_layout_changed, qui pourrait l'ecraser
ls_layout = of_read_setting(/*name*/ "main_dock")

// Puis les panneaux et la disposition, en UNE rafale : un seul ue_layout_changed, a la reprise
uo_dock.of_set_redraw(/*on*/ false)
of_create_panels()

// Et la disposition de la derniere fermeture, s'il y en a une
if ls_layout <> "" then uo_dock.of_set_layout(/*json*/ ls_layout)

// Fin de la rafale
uo_dock.of_set_redraw(/*on*/ true)

L'ordre est impératif : of_set_layout ne crée aucun panneau, il ne fait que replacer ceux qui existent déjà. Et le réglage se lit avant la construction : chaque of_add_panel change la disposition, et un ue_layout_changed qui l'enregistre écrirait une disposition à moitié construite par-dessus celle que vous alliez restaurer.

Suivre les changements en continu #

// event ue_layout_changed de uo_dock : (string as_json)
// Leve une fois par rafale de changements (la construction, une disposition restauree) : enregistre tel quel.
of_save_setting(/*name*/ "main_dock", /*value*/ as_json)

Piloter un panneau par son handle #

// Local variables
n_pbt_dock_panel lnv_panel

// Le panneau des proprietes : un titre qui compte les modifications, et replie sur son bord
lnv_panel = uo_dock.of_panel(/*key*/ "properties")
lnv_panel.is_title  = "Proprietes (3 modifiees)"
lnv_panel.ib_pinned = false        // se replie en languette sur le bord

// Masquer un panneau reserve aux administrateurs
uo_dock.of_panel(/*key*/ "audit").ib_visible = gb_administrator

Attirer l'attention sur un panneau en arrière-plan #

// Un traitement de fond a ecrit dans la console : signaler sans voler le focus
uo_dock.of_notify_panel(/*key*/ "output")

Réorganiser depuis le code #

// Deplacer un panneau comme si l'utilisateur avait fait glisser son onglet
uo_dock.of_move_panel(/*key*/ "output", /*target*/ "document", /*position*/ "bottom")

// L'empiler en onglet sur un autre panneau
uo_dock.of_move_panel(/*key*/ "help", /*target*/ "properties", /*position*/ "stack")

Détacher un panneau sur un second écran #

// Fenetre flottante native : l'utilisateur peut la poser sur un autre ecran
uo_dock.of_float_panel(/*key*/ "properties")

// event ue_panel_docked de uo_dock : (string as_key)
// L'utilisateur a referme la fenetre flottante : le panneau est revenu.
of_log(/*msg*/ "Panneau re-docke : " + as_key)

Fermer un panneau, le rouvrir #

// event ue_panel_closed de uo_dock : (string as_key)
// Le panneau n'est que masque : son controle reste dans le dock, rien ne surgit sur la fenetre.
st_status.Text = "Panneau ferme : " + as_key

// Menu Affichage, Proprietes : rouvrir le panneau, au premier plan de sa pile
uo_dock.of_panel(/*key*/ "properties").ib_visible = true

Fermer un panneau le masque : son contrôle reste hébergé, et ib_visible = true le rouvre devant sa pile. of_remove_panel rend le contrôle à la fenêtre, à sa place et visible s'il l'était : réservez-le à un contrôle que vous détruisez ensuite.

Refuser la fermeture d'un panneau qui a du travail non enregistré #

// event open de la fenetre : demander avant qu'un panneau se ferme (desactive par defaut)
uo_dock.ib_veto_close = true

// ue_panel_closing event of uo_dock : (string as_key) returns boolean
// L'editeur porte encore des modifications non enregistrees : son panneau reste ouvert.
if as_key = "editor" then
    if ib_editor_modified then return false
end if
return true

// Votre code pose la meme question : -4 quand elle est refusee
if uo_dock.of_close_panel(/*key*/ "editor") = -4 then
    st_status.Text = "Enregistrez le document avant de fermer l'editeur."
end if

Bonnes pratiques #

• Désignez toujours un panneau principal avec is_main : sans zone centrale, l'utilisateur peut tout masquer et se retrouver devant une fenêtre vide.
• Lisez la disposition enregistrée avant de créer les panneaux, puis enregistrez-la sur ue_layout_changed plutôt qu'à la seule fermeture : une fermeture anormale ne perd alors rien, et la construction du dock n'écrase plus ce que vous alliez restaurer.
• of_set_layout vient après les of_add_panel, jamais avant.
• Utilisez of_notify_panel pour les traitements de fond : c'est moins intrusif qu'une boîte de dialogue et l'information reste visible.
• Un contrôle hébergé est une fenêtre native : il se dessine au-dessus de la couche web, aucun effet visuel du composant ne passe par-dessus lui.
• Un contrôle n'est hébergé que par un seul conteneur : le donner à un second dock (ou à un tab) le retire au premier. Un contrôle qui contient le dock lui-même est refusé (-5).
• Fermer un panneau le masque (ib_visible = true le rouvre) ; of_remove_panel rend le contrôle à la fenêtre, visible s'il l'était.
• of_reset() avant toute reconstruction : sans lui, les contrôles précédemment hébergés restent reparentés dans le conteneur vidé et réutiliser une clé échoue.
• Pour de simples pages exclusives, sans docking ni flottement, tab est plus léger.

Hérité du socle commun #

Ces membres existent sur tous les composants visuels — ils ne sont pas propres à celui-ci. Ils sont détaillés une seule fois, dans les chapitres transverses ; cette table dit seulement où les lire.

Deux aides ne sont pas héritées : of_icon et of_escape_markup vivent sur n_pbt_utils. Déclarez-en une — n_pbt_utils lnv_utils, rien à créer — et appelez-les dessus.

← Référence des composants · Sommaire du guide