shellexplorer — `u_pbt_shellexplorer` #

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

El árbol del shell de Windows: Escritorio, Este equipo, unidades, carpetas, Red — con los iconos reales del puesto.

▶ Verlo en vivo — Aplicación de demostración, mosaico Shell explorer : la vista previa, el código que lo produce y esta página, lado a lado.

En resumen #

Userobject	`u_pbt_shellexplorer`
Sirve para	Elegir una carpeta, o navegar, sin salir de la aplicación
Principio	Usted dice dónde empezar; el shell dice qué hay, y usted recibe lo que el usuario eligió

Inicio 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

El shell, no el sistema de archivos #

El componente no enumera directorios: interroga al shell (IShellFolder). Es lo que pone en el árbol Este equipo, la Red, la Papelera y las carpetas virtuales — el árbol que el usuario ya conoce, en vez de una lista de unidades.

Cada nodo se identifica por su nombre de análisis: una ruta para lo que está en el disco, una forma ::{GUID} para el resto. Es la única clave que el shell sabe releer — así que la única que hay que guardar.

🚨 ue_selected le da el nombre ADEMÁS de la ruta, y no es una comodidad. El nombre mostrado de una carpeta virtual no es el final de su ruta: «Este equipo» no tiene final. Una aplicación que corta la ruta para sacar una etiqueta mostrará ::{20D04FE0-…} a su usuario.

El árbol se construye a medida que se recorre: una rama solo se pide al abrirla. Leer un disco entero para dibujar un árbol congelaría la aplicación durante minutos en una unidad de red — y ese es el caso normal en las aplicaciones donde vive esta biblioteca.

// Event ue_selected : the path AND the display name
st_chemin.text = as_path
st_nom.text = as_name

Propiedades #

Propiedad	Tipo	Predeterminado	Función
`is_root`	string	`""`	Dónde empieza el árbol (constantes `ROOT_*`). Vacío = la raíz del shell. Una ruta empieza ahí en su lugar
`ib_show_files`	boolean	`false`	Muestra también los archivos. Falso por defecto: un árbol sirve para elegir un lugar, y una carpeta con cuatro mil archivos ya no es un lugar
`is_theme_style`	string	`fluent`	Estilo visual del componente (constantes `THEME_STYLE_*`)
`is_theme_mode`	string	`light`	Variante clara u oscura (constantes `THEME_MODE_*`)
`il_theme_accent`	long	`-1`	Color de acento de este componente (`-1` = acento del tema)
`is_tooltip`	string	`""`	Información sobre herramientas simple al pasar por encima del componente
`is_super_tooltip_title`	string	`""`	Título de la información enriquecida (tiene prioridad sobre `is_tooltip`)
`is_super_tooltip_text`	string	`""`	Texto de la información enriquecida (se acepta marcado enriquecido)
`is_super_tooltip_image`	string	`""`	Imagen de la información enriquecida

Métodos #

Método	Función
`of_expand ( string as_path )`	Abre una rama ya dibujada. Una rama que nadie ha alcanzado no puede abrirse. Devuelve `0` una vez aplicado, `-2` si el componente no está creado
`of_collapse ( string as_path )`	Cierra una rama. Sus hijos siguen ahí, así que reabrirla no cuesta nada. Devuelve `0` una vez aplicado, `-2` si el componente no está creado
`of_select ( string as_path )`	Selecciona un nodo ya dibujado, y lo informa igual que un clic
`of_refresh ( )`	Reconstruye el árbol desde la raíz. Lo que estaba abierto se cierra: el shell no puede decir qué cambió
`of_selected_key ( )`	El nombre de análisis del nodo elegido. La única clave que el shell sabe releer
`of_selected_name ( )`	El nombre mostrado, tal como el Explorador lo enseña. Nunca lo deduzca de la ruta
`of_reset ( )`	Vuelve a la raíz del shell, solo carpetas, nada seleccionado. Devuelve `0` una vez aplicado, `-2` si el componente no está creado

Eventos #

Evento	Se dispara cuando
`ue_selected (string as_path, string as_name)`	Se ha elegido un nodo: su ruta y su nombre mostrado
`ue_expanded (string as_path)`	Una rama se abre. El evento sale antes de que lleguen los hijos — el shell se interroga en ese momento, y en un recurso de red se toma su tiempo
`ue_activated (string as_path)`	Doble clic, o tecla Intro. Ahí una aplicación abre la carpeta, la carga, o cierra un selector
`ue_error (string as_message)`	El shell rechaza una rama — unidad desconectada, carpeta sin permisos. El árbol sigue utilizable

Los iconos vienen de la lista de imágenes del sistema del puesto, no de nosotros: un archivo .dwg lleva el icono de AutoCAD si AutoCAD está instalado, y el genérico si no. Es lo que el usuario espera, y nada más puede darlo.

Ejemplos #

Empezar en otro sitio que el Escritorio #

// 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 lo que el usuario ha validado #

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

Buenas prácticas #

🚨 Guarde of_selected_key(), muestre of_selected_name(). Cortar la ruta para una etiqueta funciona con C:\Clientes y muestra ::{20D04FE0-…} para Este equipo.
Deje ib_show_files en falso mientras busca una carpeta. Los archivos vuelven el árbol ilegible y lento.
Prevea ue_error desde la primera versión: una unidad de red desconectada es el caso ordinario, no la excepción.
Use ue_activated, no ue_selected, para validar. Seleccionar es mirar; hacer doble clic es decidir.
No refresque en bucle. of_refresh lo cierra todo: llámelo cuando el usuario lo pida, no en un temporizador.
Una ruta de partida estrecha vale más que un árbol entero cuando la aplicación ya sabe dónde trabaja: empiece en C:\Proyectos.

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.

Miembros	Función	Detallado en
`of_reset`	Poner el componente a cero	3.6 Poner un componente a cero: `of_reset()`
`of_register_shortcut` · `of_clear_shortcuts`	Atajos de teclado del componente	3.5 Los atajos de teclado
`of_is_created` · `of_is_ready` · `of_get_last_error`	Si ha nacido, si está listo, qué ha fallado	3.7 Diagnóstico
`of_save_as_png` · `of_save_as_jpg`	Exportar el render como imagen	3.8 Exportar la representación como imagen
`of_set_redraw`	Agrupar los cambios en un solo repintado	3.10 Buenas prácticas
`of_preload_icons`	Iconos mostrados sin retardo	Visualización instantánea: `of_icon`
`of_set_translation`	Traducir una etiqueta del componente	5.2 Adaptar una etiqueta: `of_set_translation`
`of_focus_webview`	Dar el foco al componente	6.4 Teclado y foco
`of_print` · `of_print_to_pdf`	Imprimir, o escribir un PDF	6.9 Imprimir
`of_set_property` · `of_get_property` · `of_component_name`	Controlar una propiedad por su nombre	3.1 El motor de propiedades

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.