Uso de bibliotecas en el programa
En este tema se describen algunos de los aspectos que se deben tener en cuenta al usar bibliotecas en el programa.
En este tema:
- Introducción a la programación de bibliotecas
- Programación con bibliotecas
- Uso de un cuadro de diálogo de archivo común con bibliotecas
- Habilitación de la selección de biblioteca desde la interfaz de usuario
- Acceso al contenido de la biblioteca en un programa
- Guardar contenido de usuario en una biblioteca
- Compatibilidad con operaciones de arrastrar y colocar en una biblioteca
- Mantener la sincronización con una biblioteca
- Temas relacionados
Introducción a la programación de bibliotecas
Las bibliotecas permiten a los usuarios organizar su contenido basado en archivos de forma que sea significativo para ellos y no limitado por la organización del sistema de archivos. Cuando el programa admite bibliotecas, permite al usuario encontrar su contenido de una manera que tenga sentido para ellos al presentar una interfaz de usuario coherente con la experiencia del usuario de Windows 7. Las bibliotecas también facilitan que el programa localice contenido basado en archivos que se almacena en carpetas diferentes o en máquinas diferentes.
En los temas de esta sección se describe cómo agregar compatibilidad con bibliotecas al programa y aprovechar las nuevas funcionalidades que ofrecen las bibliotecas. Windows 7 proporciona parte de esta compatibilidad de forma predeterminada. Si el programa no modifica los cuadros de diálogo de archivos comunes que usa actualmente, puede requerir muy poca programación adicional para admitir bibliotecas.
En esta sección se describen algunas de las características clave que proporcionan las bibliotecas y cómo admitirlas en el programa. Con esta información, puede decidir qué características proporcionarán la mejor experiencia de usuario del programa. Si el programa personaliza los cuadros de diálogo de archivos comunes, la información de esta sección puede ayudarle a determinar cómo usar los nuevos cuadros de diálogo de archivos comunes para usar bibliotecas y proporcionar una funcionalidad equivalente en Windows 7.
Programación con bibliotecas
El modelo de programación de Windows Shell describe cómo interactúa un programa con objetos de programación de Windows Shell. Mientras que los objetos del sistema de archivos, como archivos y directorios, se representan mediante objetos shell de Windows, no todos los objetos de Windows Shell se representan mediante el sistema de archivos. Las bibliotecas, por ejemplo, son objetos de Windows Shell que no tienen un equivalente del sistema de archivos. El uso de objetos de Shell de Windows en el programa permite que el programa tenga acceso a todos los objetos shell y no solo a los objetos del sistema de archivos.
Para obtener los mejores resultados, el programa usaría la API de biblioteca de Shell para interactuar con las bibliotecas y acceder a su contenido. Aunque las bibliotecas contienen elementos del sistema de archivos, como carpetas y archivos, las bibliotecas no son elementos del sistema de archivos. Por lo tanto, las API del sistema de archivos no se pueden usar para acceder a las características de la biblioteca o al contenido de la biblioteca.
Si tiene un programa existente que actualmente usa muchas API del sistema de archivos, el programa todavía puede aprovechar las características de la biblioteca. La API de la biblioteca de Shell puede proporcionar referencias del sistema de archivos a los elementos que se encuentran en una biblioteca y estas referencias del sistema de archivos, como el nombre de archivo y la ruta de acceso, se pueden pasar a las API del sistema de archivos existentes que se encuentran en el programa existente.
Pasar de carpetas conocidas a bibliotecas
Antes de Windows 7 era habitual usar una carpeta conocida, como la carpeta Mis documentos, como la carpeta predeterminada en las operaciones de guardado de archivos o de apertura de archivos. En Windows 7, se debe usar la biblioteca correspondiente para que el usuario tenga la misma experiencia en el programa que con otros programas de Windows 7, como el Explorador de Windows.
Si actualmente usa la API de Windows Shell en el programa, agregar compatibilidad con la biblioteca es sencilla. Por ejemplo, si actualmente llama a la función SHGetKnownFolderItem para obtener la ubicación de la carpeta Mis documentos, puede reemplazar el valor KNOWNFOLDERID de la carpeta conocida Mis documentos por el valor KNOWNFOLDERID de la biblioteca correspondiente.
En la tabla siguiente se muestra la relación entre los valores KNOWNFOLDERID de carpetas conocidas y el valor KNOWNFOLDERID de la biblioteca correspondiente en Windows 7.
| Valores conocidos de Folder KNOWNFOLDERID | Valores DE LIBRARY KNOWNFOLDERID |
|---|---|
| FOLDERID_Documents | FOLDERID_DocumentsLibrary |
| FOLDERID_Pictures | FOLDERID_PicturesLibrary |
| FOLDERID_Music | FOLDERID_MusicLibrary |
| FOLDERID_RecordedTV | FOLDERID_RecordedTVLibrary |
Grupo hogar y bibliotecas compartidas
Agregar compatibilidad con bibliotecas al programa permitirá la compatibilidad con bibliotecas compartidas en un grupo hogar. El Grupo Hogar se identifica mediante su valor KNOWNFOLDERID de FOLDERID_HomeGroup. El programa puede encontrar la ubicación de guardado predeterminada privada o compartida del usuario estableciendo el valor DEFAULTSAVEFOLDERTYPE en la llamada al método IShellLibrary::GetDefaultSaveFolder .
Uso de un cuadro de diálogo de archivo común con bibliotecas
Uso de un cuadro de diálogo de archivo común con bibliotecas El cuadro de diálogo archivo común se ha actualizado para admitir bibliotecas en Windows 7. En la ilustración siguiente se muestra cómo aparece el cuadro de diálogo archivo común para un usuario en Windows 7.
En Windows 7, si el programa muestra actualmente un cuadro de diálogo de archivo común y no cambia la plantilla del cuadro de diálogo ni enlaza ninguno de sus eventos, mostrará automáticamente la nueva versión de Windows 7 del cuadro de diálogo. En concreto, en la llamada a la función de cuadro de diálogo de archivo común, los miembros lpfnHook, hInstance, lpTemplatename de la estructura OPENFILENAME deben ser NULL y las marcas OFN_ENABLEHOOK y OFN_ENABLETEMPLATE deben estar desactivadas.
En Windows 7, las interfaces relacionadas con IFileDialog reemplazan las funciones del cuadro de diálogo de archivos comunes que se usaron en versiones anteriores de Windows. Las funciones anteriores del cuadro de diálogo de archivos comunes siguen siendo compatibles con Windows 7, pero no proporcionan la experiencia completa del usuario de Windows 7 y no admiten bibliotecas. Algunas de las nuevas características admitidas por las interfaces relacionadas con IFileDialog incluyen:
- El usuario puede acceder a las propiedades del archivo compatibles con el Explorador de Windows 7 para buscar y seleccionar los archivos.
- El programa puede usar interfaces y métodos de la API del espacio de nombres de Shell para trabajar con los elementos.
- El programa puede usar un modelo de personalización controlado por datos en lugar de un modelo de personalización controlado por archivos de recursos para agregar nuevos controles a los cuadros de diálogo de archivo comunes.
Debe usar las interfaces relacionadas con IFileDialog cuando:
- Debes personalizar el cuadro de diálogo de archivo común para tu programa en Windows 7. Esto permitirá que el programa funcione con bibliotecas y admita la personalización del cuadro de diálogo.
- desea que el usuario pueda seleccionar varios archivos de un cuadro de diálogo de archivo común. Esto garantizará que obtiene las rutas de acceso correctas al objeto seleccionado porque una biblioteca puede tener contenido almacenado en carpetas diferentes.
Para obtener más información sobre las interfaces relacionadas con IFileDialog, consulte:
- IFileDialog
- IFileOpenDialog
- IFileSaveDialog
- IFileDialogCustomize
- IFileDialogEvents
- IFileDialogControlEvents
Habilitación de la selección de biblioteca desde la interfaz de usuario
Si el programa permite al usuario seleccionar una carpeta, como para las funciones de importación o exportación, en Windows 7, también debe permitir que el usuario seleccione una biblioteca. La interfaz IFileOpenDialog y la función SHBrowseForFolder permiten al usuario seleccionar una biblioteca cuando se le pida que seleccione una carpeta. La interfaz IFileOpenDialog es preferible a la función SHBrowseForFolder porque IFileOpenDialog admite la interfaz de usuario de Windows 7.
Para permitir que los usuarios seleccionen carpetas al usar la interfaz IFileOpenDialog , llame a SetOptions con la marca FOS_PICKFOLDERS establecida y asegúrese de que la marca FOS_FORCEFILESYSTEM esté desactivada.
FILEOPENDIALOGOPTIONS fileOptions;
hr = fileOpenDialogBox->GetOptions(&fileOptions);
fileOptions = fileOptions | FOS_PICKFOLDERS | ~FOS_FORCEFILESYSTEM;
hr = fileOpenDialogBox->SetOptions(fileOptions);
Para permitir que los usuarios seleccionen carpetas al llamar a la función SHBrowseForFolder, en el miembro ulFlags de la estructura BROWSEINFO , establezca la marca BIF_USENEWUI y desactive la marca BIF_RETURNONLYFSDIRS.
BROWSEINFO browseInfo;
browseInfo.ulFlags = BIF_USENEWUI | ~BIF_RETURNONLYFSDIRS;
// Set other member values
pidl = SHBrowseForFolder(&browseInfo);
Acceso al contenido de la biblioteca en un programa
Para acceder al contenido de una biblioteca, debe usar la API de Windows Shell. Las funciones de la API del sistema de archivos no se pueden usar para tener acceso al contenido de la biblioteca porque las bibliotecas no son objetos del sistema de archivos. Si el programa usa un explorador de archivos personalizado basado en la API del sistema de archivos, no podrá examinar bibliotecas ni acceder al contenido de la biblioteca.
En esta sección se describe cómo puede acceder al contenido de la biblioteca para que pueda seleccionar la mejor manera de actualizar el programa para trabajar con bibliotecas.
Acceso al contenido de la biblioteca con la interfaz IShellLibrary
La manera más fácil de acceder a contenido de la biblioteca es usar la API de biblioteca de Shell. Si está trabajando en un programa que usa la API del sistema de archivos, la API de biblioteca de Shell puede devolver las carpetas del sistema de archivos de una biblioteca, lo que minimiza el cambio en el código de programa existente.
IShellLibrary *picturesLibrary;
hr = SHLoadLibraryFromKnownFolder(FOLDERID_PicturesLibrary,
STGM_READ,
IID_PPV_ARGS(&picturesLibrary));
// picturesLibrary now points to the user's picture library
IShellItemArray *pictureFolders;
hr = pslLibrary->GetFolders(LFF_FORCEFILESYSTEM, IID_PPV_ARGS(&pictureFolders));
// pictureFolders now contains an array of Shell items that
// represent the folders found in the user's pictures library
Acceso al contenido de la biblioteca con las API de Shell
Dado que los objetos de biblioteca forman parte del modelo de programación de Shell, se pueden usar con otras API de Windows Shell. Por ejemplo, puede usar las interfaces IShellItem e IShellFolder del programa, junto con funciones auxiliares relacionadas, para acceder al contenido de una biblioteca de la misma manera que enumeraría carpetas y contenido de carpetas para acceder al contenido con las API del sistema de archivos.
Las API de Windows Shell admiten dos modos de enumeración para acceder al contenido de una biblioteca:
Examinar enumeración
Examinar enumeración es el modo de enumeración predeterminado y enumera el contenido de una carpeta de biblioteca. Borre la marca SHCONTF_NAVIGATION_ENUM para usar este modo.
Enumeración de navegación
La enumeración de navegación enumera las carpetas de la biblioteca. Establezca la marca SHCONTF_NAVIGATION_ENUM para usar este modo.
Si el programa usa un control de árbol personalizado para navegar por las carpetas del usuario, enumerar las carpetas en el modo de enumeración de navegación le proporcionará una lista de las carpetas de una biblioteca que es coherente con la forma en que el Explorador de Windows enumera las carpetas en Windows 7.
Para obtener ejemplos de cómo usar estas características en un programa, consulte el ejemplo ShellStorage en Windows SDK.
Guardar contenido de usuario en una biblioteca
El programa puede guardar el contenido del usuario en una biblioteca, así como en una carpeta de la biblioteca. Del mismo modo, el usuario puede guardar en una carpeta específica de una biblioteca o simplemente guardarla en la biblioteca.
Cada biblioteca tiene una carpeta que se designa como la ubicación de guardado predeterminada. La ubicación de guardado predeterminada se define cuando se crea la biblioteca; sin embargo, el usuario puede reasignar la ubicación de guardado predeterminada para que sea cualquier carpeta de la biblioteca. Aunque el usuario no necesita configurar una ubicación de guardado predeterminada, tiene la opción de cambiarla. Si el usuario elimina la carpeta que está establecida actualmente como la ubicación de guardado predeterminada, la biblioteca configurará automáticamente la siguiente carpeta de la biblioteca para que sea la ubicación de guardado predeterminada.
Hay varias maneras de guardar el contenido del usuario en una biblioteca.
Shell API
Si usa el modelo de programación shell y guarda un elemento de Shell, representado por un IShellItem, IStorage o IStream, en un objeto de biblioteca, el elemento shell se almacenará automáticamente en la ubicación de guardado predeterminada de la biblioteca.
API del sistema de archivos
Si tiene un programa existente que usa muchas llamadas API del sistema de archivos, puede obtener una ruta de acceso a la carpeta que se define como la ubicación de guardado predeterminada de la biblioteca. A continuación, la ruta de acceso de la carpeta se puede pasar a una API del sistema de archivos.
Para obtener ejemplos de cómo usar estas características en un programa, consulte el ejemplo ShellStorage en Windows SDK.
Compatibilidad con operaciones de arrastrar y colocar en una biblioteca
Si el programa admite acciones de arrastrar y colocar, se deben actualizar para admitir la interacción correcta de la biblioteca. Si se quita un archivo en una biblioteca, el archivo quitado debe guardarse en la ubicación de guardado predeterminada. Si se quita una carpeta en una biblioteca, la carpeta quitada se debe agregar como una nueva carpeta a la biblioteca. Si un archivo se coloca en una carpeta existente que no es la ubicación de guardado predeterminada, el archivo debe agregarse a la carpeta seleccionada.
Para obtener ejemplos de cómo agregar compatibilidad de biblioteca con la funcionalidad de arrastrar y colocar de los programas, consulte el ejemplo ShellLibraryCommandLine en Windows SDK.
Mantener la sincronización con una biblioteca
En este tema se describe cómo un programa puede mantener actualizada su vista del contenido de una biblioteca.
Actualización masiva
Dado que el usuario puede modificar las carpetas de una biblioteca de forma interactiva cuando el programa no se está ejecutando, el programa debe llamar a SHResolveLibrary cuando empiece a detectar y almacenar los cambios en la biblioteca. La API de Shell proporciona la función SHResolveLibrary para permitir que un programa obtenga el contenido actual de una biblioteca y las ubicaciones actuales de cualquier carpeta que pueda contener la biblioteca.
Tenga en cuenta que SHResolveLibrary es una función de bloqueo que podría tardar mucho tiempo en devolverse en función de lo que ha cambiado en la biblioteca. Por lo tanto, no se debe llamar desde un subproceso de interfaz de usuario.
Una vez actualizado el programa, puede registrarse para que las notificaciones de cambio mantengan una vista actual.
Notificación de API de Shell
La API de Windows Shell proporciona la función SHChangeNotifyRegister , que es la manera preferida de notificar a los procesos que no son de servicio un cambio en la biblioteca.
Para detectar cambios en los elementos de una biblioteca mediante la API de Windows Shell, llame a SHChangeNotifyRegister para registrar el programa para recibir notificaciones de cambios en los elementos de una carpeta de biblioteca. Esta función puede notificar al programa si hay un cambio en cualquier biblioteca o simplemente en una biblioteca específica. Las notificaciones se envían inmediatamente cuando se cambia una biblioteca.
Notificación de API del sistema de archivos
Las notificaciones del sistema de archivos deben usarse en los procesos de servicio.
Para detectar cambios en los elementos de una biblioteca mediante la API del sistema de archivos, enumere las carpetas de la biblioteca y llame a FindFirstChangeNotification para cada carpeta que se va a supervisar. El programa recibirá una notificación cuando cambie una carpeta supervisada. Para buscar el archivo específico de los archivos que cambiaron en la carpeta, llame a ReadDirectoryChangesW. Para detectar cambios en el archivo de descripción de la biblioteca, supervise la carpeta que la contiene. El archivo de descripción de la biblioteca se puede encontrar en la carpeta FOLDERID_Libraries . Sin embargo, el archivo de descripción de la biblioteca no debe abrirse ni modificarse.
Temas relacionados