shellexplorer — `u_pbt_shellexplorer` #

← Referência dos componentes · Índice do guia

A árvore da shell do Windows: Ambiente de trabalho, Este PC, unidades, pastas, Rede — com os ícones reais do posto.

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

Em resumo #

Userobject	`u_pbt_shellexplorer`
Serve para	Escolher uma pasta, ou navegar, sem sair da aplicação
Princípio	Você diz onde começar; a shell diz o que há, e você recebe o que o utilizador escolheu

Arranque rápido #

// Nothing to build : the tree starts at the shell root on its own
// (Desktop, This PC, Network - what the user already knows)
uo_tree.is_root = u_pbt_shellexplorer.ROOT_DESKTOP

A shell, não o sistema de ficheiros #

O componente não enumera directórios: interroga a shell (IShellFolder). É isso que põe na árvore Este PC, a Rede, a Reciclagem e as pastas virtuais — a árvore que o utilizador já conhece, em vez de uma lista de unidades.

Cada nó é identificado pelo seu nome de análise: um caminho para o que está no disco, uma forma ::{GUID} para o resto. É a única chave que a shell sabe reler — logo a única a guardar.

🚨 ue_selected dá-lhe o nome ALÉM do caminho, e isso não é uma comodidade. O nome apresentado de uma pasta virtual não é o fim do seu caminho: «Este PC» não tem fim. Uma aplicação que corta o caminho mostrará ::{20D04FE0-…} ao seu utilizador.

A árvore constrói-se à medida que se percorre: um ramo só é pedido ao abrir. Ler um disco inteiro para desenhar uma árvore congelaria a aplicação durante minutos numa unidade de rede — e esse é o caso normal nas aplicações onde esta biblioteca vive.

// Event ue_selected : the path AND the display name
st_path.text = as_path
st_name.text = as_name

Propriedades #

Propriedade	Tipo	Predefinição	Papel
`is_root`	string	`""`	Onde a árvore começa (constantes `ROOT_*`). Vazio = a raiz da shell. Um caminho começa aí em vez disso
`ib_show_files`	boolean	`false`	Mostra também os ficheiros. Falso por predefinição: uma árvore serve para escolher um lugar, e uma pasta com quatro mil ficheiros já não é um lugar
`ib_show_hidden`	boolean	definição do Explorador	Mostra os ficheiros e pastas ocultos. Enquanto a aplicação não a definir, segue a definição «Itens ocultos» do Explorador do posto — e relê-a. Os ficheiros protegidos do sistema só seguem o Explorador
`is_file_filter`	string	`""`	Que ficheiros são mostrados quando `ib_show_files` é verdadeiro: padrões separados por ponto e vírgula (`.pdf;.docx`), comparados com o nome real do ficheiro. As pastas aparecem sempre, para que o utilizador chegue ao ficheiro. Vazio = todos
`ib_enabled`	boolean	`true`	Falso: a árvore fica visível, esbatida, e já não responde ao clique nem ao teclado; sai da ordem de tabulação. A aplicação continua a controlá-la (`of_select`, `of_expand`, `of_refresh`)
`is_theme_style`	string	`""`	Estilo visual do componente (constantes `THEME_STYLE_*`); vazio = o da aplicação, seguido a cada mudança
`is_theme_mode`	string	`""`	Variante clara ou escura (constantes `THEME_MODE_*`); vazio = a da aplicação, seguida a cada mudança
`il_theme_accent`	long	`-1`	Cor de destaque deste componente (`-1` = destaque da aplicação, ou o do tema)
`is_tooltip`	string	`""`	Dica simples mostrada ao passar sobre o componente
`is_super_tooltip_title`	string	`""`	Título da dica enriquecida (tem precedência sobre `is_tooltip`)
`is_super_tooltip_text`	string	`""`	Texto da dica enriquecida (marcação rica aceite)
`is_super_tooltip_image`	string	`""`	Imagem da dica enriquecida

Métodos #

Método	Papel
`long of_expand ( string as_path )`	Abre um ramo, e os ramos fechados acima dele: uma só chamada para um caminho profundo, mesmo ainda não desenhado, a partir de qualquer raiz (sob o Ambiente de trabalho, `C:\` alcança-se por Este PC). Uma pasta criada depois de lido o seu pai encontra-se relendo esse pai uma vez. Maiúsculas e barra invertida final não contam. Um caminho inalcançável, ou que não é um ramo, dispara `ue_path_not_found`. Como o chevron, dispara `ue_expanded` para cada ramo que se abre pelo caminho (nenhum para um ramo já aberto). Devolve `0` depois de enviado, `-5` para um caminho vazio, `-2` se o componente não estiver criado
`long of_collapse ( string as_path )`	Fecha um ramo. Os seus filhos ficam, por isso reabri-lo não custa nada. Uma selecção dentro dele sobe para o ramo. Como um clique no seu chevron, dispara `ue_collapsed`, e `ue_selected` quando a selecção sobe para o ramo; nada se o ramo já estiver fechado. Devolve `0` depois de aplicado, `-5` para um caminho vazio, `-2` se o componente não estiver criado
`long of_select ( string as_path )`	Selecciona um nó. Os ramos acima dele abrem-se, a selecção fica à vista; um nó ainda não desenhado alcança-se como com `of_expand`, um inalcançável dispara `ue_path_not_found`. Como um clique, dispara `ue_selected` (nada se o nó já estiver seleccionado); `of_selected_key` relê-o depois de chegar. Devolve `0` depois de enviado, `-5` para um caminho vazio, `-2` se o componente não estiver criado
`long of_refresh ( { string as_path } )`	Relê a árvore a partir da shell — depois de a aplicação ter escrito no disco. Os ramos abertos reabrem-se e a selecção volta, encontrados pelo seu caminho; o que já não existe é abandonado, e uma selecção desaparecida dispara `ue_selected` com dois textos vazios. Com um caminho, só esse ramo é relido (um ramo nunca aberto não tem nada a reler). Devolve `0` uma vez pedido, `-5` para um caminho vazio, `-2` se o componente não estiver criado
`string of_selected_key ( )`	O nome de análise do nó escolhido. A única chave que a shell sabe reler
`string of_selected_name ( )`	O nome apresentado, tal como o Explorador o mostra. Nunca o deduza do caminho
`boolean of_selected_is_folder ( )`	Verdadeiro quando o nó escolhido é uma pasta, falso para um ficheiro ou sem selecção. Os eventos só dão o caminho
`boolean of_has ( string as_keys )`	Verdadeiro quando este caminho está desenhado na árvore, aberto ou não. Um caminho é UMA chave: as suas barras invertidas não são níveis. Maiúsculas não contam
`long of_count ( { string as_keys } )`	Sem caminho: quantas linhas a árvore mostra (um ramo fechado esconde os seus filhos). Com um caminho: quantos filhos foram lidos sob ele — `0` enquanto nunca foi aberto, pois um ramo só é lido ao abrir
`string of_keys_at ( string as_keys, long al_index )`	O caminho do filho de posição `al_index` (a partir de 1) sob um caminho, `""` fora dos limites. Um caminho de filho já está inteiro: volta tal qual para `of_has`, `of_count`, `of_select` ou `of_expand`. `of_keys_at(al_index)` percorre da mesma forma as linhas mostradas
`of_reset ( )`	Volta à raiz da shell, só pastas, nada seleccionado. Devolve `0` depois de aplicado, `-2` se o componente não estiver criado

Eventos #

Evento	Disparado quando
`ue_selected (string as_path, string as_name)`	Um nó é seleccionado — pelo utilizador (clique, teclado) ou por `of_select` / `of_collapse`: o seu caminho e o seu nome apresentado. Disparado também com dois textos vazios quando uma releitura descobre que o nó seleccionado desapareceu
`ue_expanded (string as_path)`	Um ramo abre-se — pelo utilizador (chevron, duplo clique, teclado) ou por `of_expand` / `of_select`, uma vez por cada ramo aberto pelo caminho. O evento parte antes de os filhos chegarem — a shell é interrogada nesse momento, e numa partilha de rede demora
`ue_activated (string as_path)`	Duplo clique, ou tecla Enter. É aí que uma aplicação abre a pasta, a carrega, ou fecha um selector
`ue_error (string as_message)`	A shell recusa um ramo ou a raiz — unidade desligada, pasta sem direitos, partilha que não responde em 30 segundos (`timeout`) —, com o caminho e o motivo. O ramo fecha-se e é pedido de novo na próxima abertura; uma raiz ilegível di-lo na árvore
`ue_collapsed (string as_path)`	Um ramo fecha-se — pelo utilizador ou por `of_collapse`. Uma selecção dentro dele sobe para o ramo, e `ue_selected` comunica-o
`ue_path_not_found (string as_path, string as_action, string as_reason)`	Um `of_expand` ou `of_select` não pôde ser servido: o caminho não existe, está fora da raiz, não é um ramo, ou o seu ramo é ilegível. `as_action` vale `expand` ou `select`

Os ícones vêm da lista de imagens do sistema do posto, não de nós: um ficheiro .dwg leva o ícone do AutoCAD se o AutoCAD estiver instalado, e o genérico se não. É o que o utilizador espera, e nada mais o pode dar.

Exemplos #

Começar noutro sítio que não o ambiente de trabalho #

// Only the drives, nothing above them
uo_tree.is_root = u_pbt_shellexplorer.ROOT_COMPUTER

// Or somewhere the application already knows
uo_tree.is_root = "C:\Projects"

Abrir o que o utilizador validou #

// Event ue_activated : a double-click, or Enter
of_open_folder(as_path)

Boas práticas #

🚨 Guarde of_selected_key(), mostre of_selected_name(). Cortar o caminho para uma etiqueta funciona com C:\Clientes e mostra ::{20D04FE0-…} para Este PC.
Deixe ib_show_files a falso enquanto procura uma pasta. Os ficheiros tornam a árvore ilegível e lenta.
Preveja ue_error desde a primeira versão: uma unidade de rede desligada é o caso comum, não a excepção.
Use ue_activated, não ue_selected, para validar. Seleccionar é olhar; fazer duplo clique é decidir.
Releia o ramo que mudou. Depois de escrever numa pasta, of_refresh(caminho) relê só essa pasta; of_refresh() relê tudo o que está aberto — o estado mantém-se, mas numa partilha de rede cada ramo aberto custa uma ida e volta.
Um caminho de partida estreito vale mais que uma árvore inteira quando a aplicação já sabe onde trabalha: comece em C:\Projectos.

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.

Membros	Função	Detalhado em
`of_reset`	Repor o componente a zero	3.6 Repor um componente a zero: `of_reset()`
`of_register_shortcut` · `of_clear_shortcuts`	Atalhos de teclado do componente	3.5 Os atalhos de teclado
`of_is_created` · `of_is_ready` · `of_get_last_error`	Se nasceu, se está pronto, o que falhou	3.7 Diagnóstico
`of_save_as_png` · `of_save_as_jpg`	Exportar a renderização como imagem	3.8 Exportar a representação como imagem
`of_set_redraw`	Agrupar as alterações num único repinte	3.10 Boas práticas
`of_preload_icons`	Ícones mostrados sem atraso	Apresentação instantânea: `of_icon`
`of_set_translation`	Traduzir uma legenda do componente	5.2 Adaptar uma etiqueta: `of_set_translation`
`of_focus_webview`	Dar o foco ao componente	6.4 Teclado e focus
`of_print` · `of_print_to_pdf`	Imprimir, ou escrever um PDF	6.9 Imprimir
`of_set_property` · `of_get_property` · `of_component_name`	Controlar uma propriedade pelo nome	3.1 O motor de propriedades

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.