dockcontainer — u_pbt_dockcontainer #

← Referência dos componentes · Índice do guia

Painéis acopláveis ao estilo do Visual Studio: acoplagem por arrastar e largar, empilhamento em separadores, divisores redimensionáveis, janelas flutuantes, ocultação automática — e gravação/reposição da disposição.

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

Em resumo #

Tal como em tab, cada painel aloja um controlo PowerBuilder verdadeiro (dragobject): userobject, DataWindow ou outro componente PBToolboxAI. Ver Alojar controlos reais do PowerBuilder.

Início rápido #

// event open da window : os controlos de painel ja estao colocados sobre ela
uo_dock.of_add_panel(/*key*/ "document", /*position*/ "", /*relative_to*/ "", /*size*/ 0, /*title*/ "Document", /*content*/ uo_editor)

// O explorador, acoplado ao inicio do documento, com 260 pixels
uo_dock.of_add_panel(/*key*/ "explorer", /*position*/ uo_dock.POSITION_START, /*relative_to*/ "document", /*size*/ 260, /*title*/ "Explorador", /*content*/ uo_tree)

// As propriedades, acopladas ao fim do documento, com 300 pixels
uo_dock.of_add_panel(/*key*/ "properties", /*position*/ uo_dock.POSITION_END, /*relative_to*/ "document", /*size*/ 300, /*title*/ "Propriedades", /*content*/ uo_props)

// A zona central : nao pode ser fechada pela acoplagem, nem flutuar, nem ser ocultada
uo_dock.is_main = "document"

Propriedades #

Posições de acoplagem #

As constantes do componente alimentam as_position em of_add_panel e of_move_panel:

Propriedades de um painel — n_pbt_dock_panel #

Obtidas através de of_panel(chave).

Métodos #

Eventos #

Com o rato #

Para além de arrastar separadores e divisores, três gestos atuam sobre um painel — nunca sobre o painel principal:

Com o teclado #

O conteúdo de um painel é um verdadeiro controlo PowerBuilder: aí o teclado pertence ao seu código, como em qualquer janela. Aquilo de que o componente trata é o seu próprio invólucro — cabeçalhos, separadores, divisores:

Um divisor é um separator focável que anuncia a sua posição; os botões do cabeçalho (destacar, ocultar, fechar) têm um nome, e o painel ativo de um grupo está marcado com aria-selected. Uma deslocação com o teclado é comunicada em ue_layout_changed exatamente como um arrastamento com o rato.

Exemplos #

Uma window ao estilo de um IDE #

// event open : cada conteudo e um controlo PB verdadeiro colocado sobre a window
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*/ "Explorador", /*content*/ uo_tree)
uo_dock.of_add_panel(/*key*/ "properties", /*position*/ uo_dock.POSITION_END, /*relative_to*/ "document", /*size*/ 300, /*title*/ "Propriedades", /*content*/ uo_props)
uo_dock.of_add_panel(/*key*/ "output", /*position*/ uo_dock.POSITION_BOTTOM, /*relative_to*/ "document", /*size*/ 200, /*title*/ "Saida", /*content*/ uo_console)

// Um segundo painel empilhado em separador sobre "properties"
uo_dock.of_add_panel(/*key*/ "help", /*position*/ uo_dock.POSITION_STACK, /*relative_to*/ "properties", /*size*/ 0, /*title*/ "Ajuda", /*content*/ uo_help)

// O documento e a zona central
uo_dock.is_main = "document"

Memorizar e repor a disposição do utilizador #

// event close da window : gravar aquilo que o utilizador organizou
// Local variables
string ls_layout

// A disposicao atual, pronta a guardar
ls_layout = uo_dock.of_get_layout()
of_save_setting(/*name*/ "main_dock", /*value*/ ls_layout)

// event open : LER a disposicao gravada, DEPOIS criar os paineis
// Local variables
string ls_layout

// Primeiro a definicao : construir o dock lanca ue_layout_changed, que a poderia substituir
ls_layout = of_read_setting(/*name*/ "main_dock")

// Depois os paineis e a disposicao, numa SO rajada : um unico ue_layout_changed, na retoma
uo_dock.of_set_redraw(/*on*/ false)
of_create_panels()

// E a disposicao do ultimo fecho, se existir
if ls_layout <> "" then uo_dock.of_set_layout(/*json*/ ls_layout)

// Fim da rajada
uo_dock.of_set_redraw(/*on*/ true)

A ordem é imperativa: of_set_layout não cria nenhum painel, limita-se a recolocar os que já existem. E a definição lê-se antes da construção: cada of_add_panel muda a disposição, e um ue_layout_changed que a grave escreveria uma disposição construída a meio por cima daquela que ia repor.

Acompanhar as alterações continuamente #

// event ue_layout_changed de uo_dock : (string as_json)
// Lancado uma vez por rajada de alteracoes (a construcao, uma disposicao reposta) : gravado tal como esta.
of_save_setting(/*name*/ "main_dock", /*value*/ as_json)

Comandar um painel através do respetivo handle #

// Local variables
n_pbt_dock_panel lnv_panel

// O painel das propriedades : um titulo que conta as alteracoes, recolhido no seu bordo
lnv_panel = uo_dock.of_panel(/*key*/ "properties")
lnv_panel.is_title  = "Propriedades (3 modificadas)"
lnv_panel.ib_pinned = false        // recolhe-se numa patilha junto ao bordo

// Ocultar um painel reservado aos administradores
uo_dock.of_panel(/*key*/ "audit").ib_visible = gb_administrator

Chamar a atenção para um painel em segundo plano #

// Um processamento em segundo plano escreveu na consola : assinalar sem roubar o foco
uo_dock.of_notify_panel(/*key*/ "output")

Reorganizar a partir do código #

// Deslocar um painel como se o utilizador tivesse arrastado o seu separador
uo_dock.of_move_panel(/*key*/ "output", /*target*/ "document", /*position*/ "bottom")

// Empilha-lo em separador sobre outro painel
uo_dock.of_move_panel(/*key*/ "help", /*target*/ "properties", /*position*/ "stack")

Destacar um painel para um segundo ecrã #

// Janela flutuante nativa : o utilizador pode coloca-la noutro ecra
uo_dock.of_float_panel(/*key*/ "properties")

// event ue_panel_docked de uo_dock : (string as_key)
// O utilizador voltou a fechar a janela flutuante : o painel regressou.
of_log(/*msg*/ "Painel novamente acoplado: " + as_key)

Fechar um painel, voltar a abri-lo #

// event ue_panel_closed de uo_dock : (string as_key)
// O painel esta apenas oculto : o seu controlo fica no dock, nada surge na window.
st_status.Text = "Painel fechado: " + as_key

// Menu Ver, Propriedades : voltar a abrir o painel, a frente da sua pilha
uo_dock.of_panel(/*key*/ "properties").ib_visible = true

Fechar um painel oculta-o: o seu controlo fica alojado, e ib_visible = true volta a abri-lo à frente da sua pilha. of_remove_panel devolve o controlo à janela, ao seu lugar e visível se o era: reserve-o para um controlo que destrói a seguir.

Recusar o fecho de um painel com trabalho não guardado #

// event open da window : perguntar antes de um painel se fechar (desativado por omissao)
uo_dock.ib_veto_close = true

// ue_panel_closing event of uo_dock : (string as_key) returns boolean
// O editor ainda tem alteracoes nao guardadas : o seu painel fica aberto.
if as_key = "editor" then
    if ib_editor_modified then return false
end if
return true

// O seu codigo coloca a mesma pergunta : -4 quando e recusada
if uo_dock.of_close_panel(/*key*/ "editor") = -4 then
    st_status.Text = "Guarde o documento antes de fechar o editor."
end if

Boas práticas #

• Designar sempre um painel principal com is_main: sem zona central, o utilizador pode ocultar tudo e ficar perante uma window vazia.
• Ler a disposição gravada antes de criar os painéis, e depois gravá-la em ue_layout_changed em vez de o fazer apenas no fecho: assim, um encerramento anormal não perde nada, e a construção do dock já não substitui aquilo que ia repor.
• of_set_layout vem depois dos of_add_panel, nunca antes.
• Utilizar of_notify_panel para os processamentos em segundo plano: é menos intrusivo do que uma caixa de diálogo e a informação permanece visível.
• Um controlo alojado é uma janela nativa: desenha-se por cima da camada web, e nenhum efeito visual do componente passa por cima dele.
• Um controlo é alojado por um só contentor: dá-lo a um segundo dock (ou a um tab) retira-o ao primeiro. Um controlo que contém o próprio dock é recusado (-5).
• Fechar um painel oculta-o (ib_visible = true volta a abri-lo); of_remove_panel devolve o controlo à janela, visível se o era.
• of_reset() antes de qualquer reconstrução: sem ele, os controlos anteriormente alojados permanecem reparentados no contentor esvaziado e a reutilização de uma chave falha.
• Para simples páginas exclusivas, sem acoplagem nem flutuação, tab é mais leve.

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