Uso delle librerie nel programma
Questo argomento descrive alcune delle cose da considerare quando si usano librerie nel programma.
In questo argomento
- Panoramica della programmazione della libreria
- Programmazione con librerie
- Uso di una finestra di dialogo file comune con librerie
- Abilitazione della selezione della libreria dall'interfaccia utente
- Accesso al contenuto della libreria in un programma
- Salvataggio del contenuto utente in una raccolta
- Supporto delle operazioni di trascinamento e rilascio in una libreria
- Mantenere la sincronizzazione con una libreria
- Argomenti correlati
Panoramica della programmazione della libreria
Le librerie consentono agli utenti di organizzare il contenuto basato su file in modo significativo e non limitato dall'organizzazione del file system. Quando il programma supporta le librerie, consente all'utente di trovare il contenuto in modo che abbia senso per loro durante la presentazione di un'interfaccia utente coerente con l'esperienza utente di Windows 7. Le librerie semplificano anche il programma per individuare il contenuto basato su file archiviato in cartelle diverse o in computer diversi.
Gli argomenti di questa sezione descrivono come aggiungere il supporto della libreria al programma e sfruttare le nuove funzionalità offerte dalle librerie. Windows 7 offre alcuni di questo supporto per impostazione predefinita. Se il programma non modifica le finestre di dialogo file comuni attualmente usate, potrebbe richiedere una programmazione aggiuntiva molto piccola per supportare le librerie.
Questa sezione descrive alcune delle funzionalità principali fornite dalle librerie e come supportarle nel programma. Con queste informazioni, è possibile decidere quali funzionalità offrono la migliore esperienza utente dal programma. Se il programma personalizza le finestre di dialogo file comuni, le informazioni contenute in questa sezione consentono di determinare come usare le nuove finestre di dialogo di file comuni per usare le librerie e fornire funzionalità equivalenti in Windows 7.
Programmazione con librerie
Il modello di programmazione di Windows Shell descrive come un programma interagisce con gli oggetti di programmazione di Windows Shell. Mentre gli oggetti file system, ad esempio file e directory, sono rappresentati dagli oggetti Windows Shell, non tutti gli oggetti shell di Windows sono rappresentati dal file system. Le librerie, ad esempio, sono oggetti di Windows Shell che non hanno un equivalente del file system. L'uso di oggetti Windows Shell nel programma consente al programma di accedere a tutti gli oggetti Shell e non solo agli oggetti file system.
Per ottenere i risultati migliori, il programma userà l'API libreria shell per interagire con le librerie e accedere ai relativi contenuti. Mentre le librerie contengono elementi del file system, ad esempio cartelle e file, le librerie non sono elementi del file system. Di conseguenza, le API del file system non possono essere usate per accedere alle funzionalità della libreria o al contenuto della libreria.
Se si dispone di un programma esistente che attualmente usa molte API del file system, il programma può comunque sfruttare le funzionalità della libreria. L'API libreria shell può fornire riferimenti al file system agli elementi presenti in una libreria e questi riferimenti al file system, ad esempio il nome e il percorso del file, possono essere passati alle API del file system esistenti presenti nel programma esistente.
Passaggio da cartelle note a librerie
Prima di Windows 7 è stato comune usare una cartella nota, ad esempio la cartella Documenti personali, come la cartella predefinita nel salvataggio file o nelle operazioni di apertura dei file. In Windows 7, la libreria corrispondente deve essere usata in modo che l'utente avrà la stessa esperienza nel programma come si farebbe con altri programmi Windows 7, ad esempio Esplora windows.
Se si usa attualmente l'API di Windows Shell nel programma, l'aggiunta del supporto della libreria è semplice. Ad esempio, se si chiama la funzione SHGetKnownFolderItem per ottenere il percorso della cartella Documenti personali, è possibile sostituire il valore KNOWNFOLDERID della cartella Nota Documenti personali con il valore KNOWNFOLDERID della libreria corrispondente.
Nella tabella seguente viene illustrata la relazione tra i valori KNOWNFOLDERID delle cartelle note e il valore KNOWNFOLDERID della libreria corrispondente in Windows 7.
| Valori KNOWNFOLDERID della cartella nota | Valori KNOWNFOLDERID della libreria |
|---|---|
| FOLDERID_Documents | FOLDERID_DocumentsLibrary |
| FOLDERID_Pictures | FOLDERID_PicturesLibrary |
| FOLDERID_Music | FOLDERID_MusicLibrary |
| FOLDERID_RecordedTV | FOLDERID_RecordedTVLibrary |
HomeGroup e librerie condivise
L'aggiunta del supporto della libreria al programma consentirà il supporto per le librerie condivise in un HomeGroup. Il gruppo HomeGroup viene identificato dal relativo valore KNOWNFOLDERID di FOLDERID_HomeGroup. Il programma può trovare l'identificazione del percorso di salvataggio predefinito privato o condiviso dell'utente impostando il valore DEFAULTSAVEFOLDERTYPE nella chiamata al metodo IShellLibrary::GetDefaultSaveFolder .
Uso di una finestra di dialogo file comune con librerie
Usando una finestra di dialogo file comune con librerie, la finestra di dialogo file comune è stata aggiornata per supportare le librerie in Windows 7. La figura seguente illustra come viene visualizzata la finestra di dialogo file comune a un utente in Windows 7.
In Windows 7, se il programma visualizza attualmente una finestra di dialogo file comune e non modifica il modello di finestra di dialogo o l'hook di uno dei relativi eventi, verrà visualizzata automaticamente la nuova versione di Windows 7 della finestra di dialogo. In particolare, nella chiamata alla funzione di dialogo file comune, i flag lpfnHook, hInstance, lpTemplatename della struttura OPENFILENAME devono essere NULLe i flag OFN_ENABLEHOOK OFN_ENABLETEMPLATE devono essere chiari.
In Windows 7, le interfacce correlate a IFileDialog sostituiscono le funzioni comuni della finestra di dialogo file usate nelle versioni precedenti di Windows. Le funzioni della finestra di dialogo file comuni precedenti sono ancora supportate in Windows 7, ma non forniscono l'esperienza utente di Windows 7 completa e non supportano le librerie. Alcune delle nuove funzionalità supportate dalle interfacce correlate a IFileDialog includono:
- L'utente può accedere alle proprietà dei file supportate da Esplora windows 7 per cercare e selezionare i file.
- Il programma può usare interfacce e metodi dall'API dello spazio dei nomi shell per usare gli elementi.
- Il programma può usare un modello di personalizzazione basato sui dati anziché un modello di personalizzazione basato su file di risorse per aggiungere nuovi controlli alle finestre di dialogo file comuni.
È consigliabile usare le interfacce correlate a IFileDialog quando:
- è necessario personalizzare la finestra di dialogo file comune per il programma in Windows 7. In questo modo il programma potrà usare le librerie e supportare la personalizzazione della finestra di dialogo.
- si vuole che l'utente possa selezionare più file da una finestra di dialogo file comune. In questo modo si otterranno i percorsi corretti dell'oggetto selezionato perché una libreria può avere contenuto archiviato in cartelle diverse.
Per altre informazioni sulle interfacce correlate a IFileDialog, vedere:
- IFileDialog
- IFileOpenDialog
- IFileSaveDialog
- IFileDialogCustomize
- IFileDialogEvents
- IFileDialogControlEvents
Abilitazione della selezione della libreria dall'interfaccia utente
Se il programma consente all'utente di selezionare una cartella, ad esempio per le funzioni di importazione o esportazione, in Windows 7, dovrebbe consentire all'utente di selezionare anche una raccolta. La funzione IFileOpenDialog e SHBrowseForFolder consente all'utente di selezionare una libreria quando viene richiesto di selezionare una cartella. L'interfaccia IFileOpenDialog è preferita rispetto alla funzione SHBrowseForFolder perché IFileOpenDialog supporta l'interfaccia utente di Windows 7.
Per consentire agli utenti di selezionare cartelle quando si usa l'interfaccia IFileOpenDialog , chiamare SetOptions con il flag di FOS_PICKFOLDERS impostato e assicurarsi che il flag di FOS_FORCEFILESYSTEM sia deselezionato.
FILEOPENDIALOGOPTIONS fileOptions;
hr = fileOpenDialogBox->GetOptions(&fileOptions);
fileOptions = fileOptions | FOS_PICKFOLDERS | ~FOS_FORCEFILESYSTEM;
hr = fileOpenDialogBox->SetOptions(fileOptions);
Per consentire agli utenti di selezionare cartelle quando si chiama la funzione SHBrowseForFolder, nel membro ulFlags della struttura BROWSEINFO impostare il flag di BIF_USENEWUI e deselezionare il flag di BIF_RETURNONLYFSDIRS.
BROWSEINFO browseInfo;
browseInfo.ulFlags = BIF_USENEWUI | ~BIF_RETURNONLYFSDIRS;
// Set other member values
pidl = SHBrowseForFolder(&browseInfo);
Accesso al contenuto della libreria in un programma
Per accedere al contenuto di una libreria, è necessario usare l'API di Windows Shell. Le funzioni dell'API file system non possono essere usate per accedere al contenuto della libreria perché le librerie non sono oggetti file system. Se il programma usa un file browser personalizzato basato sull'API del file system, non sarà in grado di esplorare le librerie o accedere al contenuto della libreria.
Questa sezione descrive come accedere al contenuto della libreria in modo che sia possibile selezionare il modo migliore per aggiornare il programma in modo da usare le librerie.
Accesso al contenuto della libreria con l'interfaccia IShellLibrary
Il modo più semplice per un programma per accedere al contenuto della libreria consiste nell'usare l'API libreria shell. Se si lavora su un programma che usa l'API file system, l'API libreria shell può restituire le cartelle file system di una libreria, che riduce al minimo la modifica al codice del programma esistente.
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
Accesso al contenuto della libreria con le API shell
Poiché gli oggetti della libreria fanno parte del modello di programmazione shell, possono essere usati con altre API di Windows Shell. Ad esempio, è possibile usare le interfacce IShellItem e IShellFolder nel programma, insieme alle funzioni helper correlate, per accedere al contenuto di una raccolta nello stesso modo in cui si enumererebbe cartelle e contenuti di cartelle per accedere al contenuto con le API del file system.
Le API di Windows Shell supportano due modalità di enumerazione per accedere al contenuto di una libreria:
Enumerazione Sfoglia
L'enumerazione Sfoglia è la modalità di enumerazione predefinita ed enumera il contenuto di una cartella di libreria. Deselezionare il flag SHCONTF_NAVIGATION_ENUM per usare questa modalità.
Enumerazione di spostamento
L'enumerazione di spostamento enumera le cartelle della libreria. Impostare il flag SHCONTF_NAVIGATION_ENUM per usare questa modalità.
Se il programma usa un controllo albero personalizzato per esplorare le cartelle dell'utente, l'enumerazione delle cartelle nella modalità di enumerazione di spostamento ti darà un elenco di cartelle di una libreria coerenti con il modo in cui Esplora risorse enumera cartelle in Windows 7.
Per esempi di come usare queste funzionalità in un programma, vedere l'esempio ShellStorage in Windows SDK.
Salvataggio del contenuto utente in una raccolta
Il programma può salvare il contenuto utente in una raccolta e in una cartella nella raccolta. Analogamente, l'utente può salvare in una cartella specifica in una raccolta o può semplicemente salvare nella libreria.
Ogni libreria ha una cartella designata come percorso di salvataggio predefinito. Il percorso di salvataggio predefinito viene definito quando viene creata la libreria; Tuttavia, l'utente può riassegnare il percorso di salvataggio predefinito per essere qualsiasi cartella nella libreria. Anche se l'utente non deve configurare una posizione di salvataggio predefinita, è possibile modificarla. Se l'utente elimina la cartella attualmente impostata come percorso di salvataggio predefinito, la libreria configura automaticamente la cartella successiva nella libreria per essere il percorso di salvataggio predefinito.
Esistono diversi modi per salvare il contenuto utente in una raccolta.
Shell API
Se si usa il modello di programmazione shell e si salva un elemento shell, come rappresentato da un oggetto IShellItem, IStorage o IStream, in un oggetto libreria, l'elemento shell verrà archiviato automaticamente nel percorso di salvataggio predefinito della libreria.
API file system
Se si dispone di un programma esistente che usa molte chiamate API file system, è possibile ottenere un percorso alla cartella definita come percorso di salvataggio predefinito della libreria. Il percorso della cartella può quindi essere passato a un'API file system.
Per esempi di come usare queste funzionalità in un programma, vedere l'esempio ShellStorage in Windows SDK.
Supporto delle operazioni di trascinamento e rilascio in una libreria
Se il programma supporta le azioni di trascinamento e rilascio, tali azioni devono essere aggiornate per supportare l'interazione corretta della libreria. Se un file viene eliminato in una libreria, il file eliminato deve essere salvato nel percorso di salvataggio predefinito. Se una cartella viene eliminata in una raccolta, la cartella eliminata deve essere aggiunta come nuova cartella alla libreria. Se un file viene eliminato in una cartella esistente che non è il percorso di salvataggio predefinito, il file deve essere aggiunto alla cartella selezionata.
Per esempi di come aggiungere il supporto della libreria per le funzionalità di trascinamento e rilascio dei programmi, vedere l'esempio ShellLibraryCommandLine in Windows SDK.
Mantenere la sincronizzazione con una libreria
Questo argomento descrive come un programma può mantenere aggiornata la visualizzazione del contenuto di una libreria.
Aggiornamento bulk
Poiché l'utente può modificare le cartelle di una libreria in modo interattivo quando il programma non è in esecuzione, il programma deve chiamare SHResolveLibrary quando inizia a individuare e archiviare eventuali modifiche alla libreria. L'API Shell fornisce la funzione SHResolveLibrary per consentire a un programma di ottenere il contenuto corrente di una libreria e le posizioni correnti di tutte le cartelle che la libreria potrebbe contenere.
Si noti che SHResolveLibrary è una funzione di blocco che potrebbe richiedere molto tempo per restituire a seconda di ciò che è cambiato nella libreria. Di conseguenza, non deve essere chiamato da un thread dell'interfaccia utente.
Dopo che il programma è stato aggiornato, può quindi registrarsi per le notifiche di modifica per mantenere una visualizzazione corrente.
Notifica API shell
L'API di Windows Shell fornisce la funzione SHChangeNotifyRegister , che è il modo preferito per i processi non di servizio da notificare a una modifica nella libreria.
Per rilevare le modifiche agli elementi all'interno di una libreria usando l'API di Windows Shell, chiamare SHChangeNotifyRegister per registrare il programma per le notifiche delle modifiche agli elementi in una cartella della libreria. Questa funzione può inviare una notifica al programma se è presente una modifica in qualsiasi libreria o solo in una libreria specifica. Le notifiche vengono inviate immediatamente quando viene modificata una libreria.
Notifica API file system
Le notifiche del file system devono essere usate nei processi di servizio.
Per rilevare le modifiche agli elementi in una raccolta usando l'API file system, enumerare le cartelle nella libreria e chiamare FindFirstChangeNotification per ogni cartella da monitorare. Il programma riceverà una notifica quando viene modificata una cartella monitorata. Per trovare il file specifico dei file modificati nella cartella, chiamare ReadDirectoryChangesW. Per rilevare le modifiche nel file di descrizione della libreria, monitorare la cartella che la contiene. Il file di descrizione della libreria è disponibile nella cartella FOLDERID_Libraries . Il file di descrizione della libreria, tuttavia, non deve essere aperto o modificato.
Argomenti correlati