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_path.text = as_path
st_name.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
`ib_show_hidden`	boolean	ajuste del Explorador	Muestra los archivos y carpetas ocultos. Mientras la aplicación no la fije, sigue el ajuste «Elementos ocultos» del Explorador del puesto — y lo relee. Los archivos protegidos del sistema solo siguen al Explorador
`is_file_filter`	string	`""`	Qué archivos se muestran cuando `ib_show_files` es verdadero: patrones separados por punto y coma (`.pdf;.docx`), comparados con el nombre real del archivo. Las carpetas siempre aparecen, para que el usuario llegue al archivo. Vacío = todos
`ib_enabled`	boolean	`true`	Falso: el árbol sigue visible, atenuado, y ya no responde ni al clic ni al teclado; sale del orden de tabulación. La aplicación lo sigue manejando (`of_select`, `of_expand`, `of_refresh`)
`is_theme_style`	string	`""`	Estilo visual del componente (constantes `THEME_STYLE_*`); vacío = el de la aplicación, seguido en cada cambio
`is_theme_mode`	string	`""`	Variante clara u oscura (constantes `THEME_MODE_*`); vacío = la de la aplicación, seguida en cada cambio
`il_theme_accent`	long	`-1`	Color de acento de este componente (`-1` = acento de la aplicación, o el 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
`long of_expand ( string as_path )`	Abre una rama, y las ramas cerradas por encima: una sola llamada para una ruta profunda, aunque no esté dibujada, desde cualquier raíz (bajo el Escritorio, `C:\` se alcanza por Este equipo). Una carpeta creada después de leer su padre se encuentra releyendo una vez ese padre. Mayúsculas y barra invertida final no cuentan. Una ruta inalcanzable, o que no es una rama, dispara `ue_path_not_found`. Como el chevron, dispara `ue_expanded` por cada rama que se abre en el camino (ninguno para una rama ya abierta). Devuelve `0` una vez enviado, `-5` para una ruta vacía, `-2` si el componente no está creado
`long of_collapse ( string as_path )`	Cierra una rama. Sus hijos siguen ahí, así que reabrirla no cuesta nada. Una selección dentro de ella sube a la rama. Como un clic en su chevron, dispara `ue_collapsed`, y `ue_selected` cuando la selección sube a la rama; nada si la rama ya está cerrada. Devuelve `0` una vez aplicado, `-5` para una ruta vacía, `-2` si el componente no está creado
`long of_select ( string as_path )`	Selecciona un nodo. Las ramas por encima se abren, la selección queda a la vista; un nodo aún no dibujado se alcanza como con `of_expand`, uno inalcanzable dispara `ue_path_not_found`. Como un clic, dispara `ue_selected` (nada si el nodo ya está seleccionado); `of_selected_key` lo relee una vez llegado. Devuelve `0` una vez enviado, `-5` para una ruta vacía, `-2` si el componente no está creado
`long of_refresh ( { string as_path } )`	Relee el árbol desde el shell — después de que la aplicación haya escrito en el disco. Las ramas abiertas se reabren y la selección vuelve, encontradas por su ruta; lo que ya no existe se abandona, y una selección desaparecida dispara `ue_selected` con dos textos vacíos. Con una ruta, solo esa rama se relee (una rama nunca abierta no tiene nada que releer). Devuelve `0` una vez solicitado, `-5` para una ruta vacía, `-2` si el componente no está creado
`string of_selected_key ( )`	El nombre de análisis del nodo elegido. La única clave que el shell sabe releer
`string of_selected_name ( )`	El nombre mostrado, tal como el Explorador lo enseña. Nunca lo deduzca de la ruta
`boolean of_selected_is_folder ( )`	Verdadero cuando el nodo elegido es una carpeta, falso para un archivo o si no hay selección. Los eventos solo dan la ruta
`boolean of_has ( string as_keys )`	Verdadero cuando esta ruta está dibujada en el árbol, abierta o no. Una ruta es UNA clave: sus barras invertidas no son niveles. Las mayúsculas no cuentan
`long of_count ( { string as_keys } )`	Sin ruta: cuántas filas muestra el árbol (una rama cerrada oculta a sus hijos). Con una ruta: cuántos hijos se leyeron bajo ella — `0` mientras nunca se abrió, ya que una rama solo se lee al abrirse
`string of_keys_at ( string as_keys, long al_index )`	La ruta del hijo de rango `al_index` (desde 1) bajo una ruta, `""` fuera de los límites. Una ruta de hijo ya está completa: se reinyecta tal cual en `of_has`, `of_count`, `of_select` u `of_expand`. `of_keys_at(al_index)` recorre igual las filas mostradas
`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 selecciona un nodo — por el usuario (clic, teclado) o por `of_select` / `of_collapse`: su ruta y su nombre mostrado. También se dispara con dos textos vacíos cuando una relectura encuentra que el nodo seleccionado ha desaparecido
`ue_expanded (string as_path)`	Se abre una rama — por el usuario (chevron, doble clic, teclado) o por `of_expand` / `of_select`, una vez por cada rama abierta en el camino. 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 o la raíz — unidad desconectada, carpeta sin permisos, recurso que no responde en 30 segundos (`timeout`) —, con la ruta y el motivo. La rama se cierra y se vuelve a pedir en su próxima apertura; una raíz ilegible lo dice en el árbol
`ue_collapsed (string as_path)`	Se cierra una rama — por el usuario o por `of_collapse`. Una selección dentro de ella sube a la rama, y `ue_selected` lo informa
`ue_path_not_found (string as_path, string as_action, string as_reason)`	Un `of_expand` o un `of_select` no pudo servirse: la ruta no existe, queda fuera de la raíz, no es una rama, o su rama es ilegible. `as_action` vale `expand` o `select`

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_open_folder(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.
Relea la rama que ha cambiado. Tras escribir en una carpeta, of_refresh(ruta) relee solo esa carpeta; of_refresh() relee todo lo abierto — el estado se conserva, pero en un recurso de red cada rama abierta cuesta un viaje de ida y vuelta.
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.