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 #

Arranque rápido #

// Open event of the window : the tree starts where the application works
uo_tree.is_root = "C:\Projects"

Depois, no evento ue_selected da árvore:

// Event ue_selected : the folder the user chose, by its display name
st_folder.text = as_name

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 #

Uma propriedade escrita com o valor que já tem não relê nada da shell: uma janela pode aplicar as suas definições em cada abertura sem pagar por isso.

Métodos #

Eventos #

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.

Porque falha um caminho ou um ramo: as constantes REASON_* #

ue_path_not_found e ue_error dão o seu motivo como constante de u_pbt_shellexplorer, a mesma nos dois eventos e em todas as línguas do Windows: teste-a, nunca o texto.

Teclado e rato #

• Clique num nó: é seleccionado (ue_selected, nunca uma segunda vez para o nó já seleccionado); no seu chevron: abre-se ou fecha-se; duplo clique: ue_activated, e um ramo abre-se ou fecha-se; clique direito: o nó é seleccionado, depois ue_node_rclicked.
• Cima / Baixo: o nó anterior, o seguinte; Home / End: o primeiro, o último; Page Up / Page Down: de um ecrã. Ctrl + Cima / Baixo desloca sem mudar a selecção.
• Direita abre o nó, depois desce para o primeiro filho; Esquerda fecha-o, depois sobe ao pai — invertidas numa aplicação da direita para a esquerda. Retrocesso sobe ao pai; * do teclado numérico abre o nó e os ramos já lidos por baixo.
• Enter: ue_activated (e um ramo abre-se ou fecha-se); F5 relê o ramo em mão (of_refresh); tecla do menu de contexto ou Shift + F10: ue_node_rclicked.
• As primeiras letras de um nome, espaço incluído, seleccionam o nó mostrado que começa assim; a mesma letra escrita de novo passa ao seguinte.

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)

Dizer porque um ramo não se abre #

// Event ue_error : test the reason, never the text of the shell
if as_reason = u_pbt_shellexplorer.REASON_TIMEOUT then
    st_status.text = "The network folder " + as_path + " does not answer"
else
    st_status.text = as_message
end if

Abrir o seu menu com um clique direito #

// The entries of the menu, once : uo_menu is a contextmenu of the window, and
// is_menu_path a string instance variable that keeps the folder right-clicked
uo_menu.of_add_item(/*keys*/ "open", /*text*/ "Open")
uo_menu.of_add_item(/*keys*/ "refresh", /*text*/ "Refresh")

// event ue_node_rclicked of uo_tree : (string as_path, long al_x, long al_y)
// The folder is selected first, as in the Explorer : the menu opens where the
// user clicked (from the keyboard, under the folder)
is_menu_path = as_path
uo_menu.of_show(/*x*/ al_x, /*y*/ al_y)

// event ue_item_selected of uo_menu : (string as_keys)
// The entry chosen acts on the folder right-clicked
choose case as_keys
    case "open"
        of_open_folder(is_menu_path)
    case "refresh"
        uo_tree.of_refresh(/*path*/ is_menu_path)
end choose

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. Teste as_reason, nunca o texto: REASON_TIMEOUT diz que uma partilha não responde em todas as línguas do Windows.
• 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.

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