Condividi tramite

Uso delle librerie nel programma

  • Articolo

In questo argomento vengono descritti alcuni aspetti da considerare quando si usano librerie nel programma.

In questo argomento:

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 inoltre l'individuazione del 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 di 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à offriranno l'esperienza utente migliore dal programma. Se il programma personalizza le finestre di dialogo dei 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 della shell di Windows. Mentre gli oggetti del file system, ad esempio file e directory, sono rappresentati da oggetti shell di Windows, non tutti gli oggetti shell di Windows sono rappresentati dal file system. Le librerie, ad esempio, sono oggetti shell di Windows che non hanno un file system equivalente. L'uso degli oggetti shell di Windows nel programma consente al programma di accedere a tutti gli oggetti Shell e non solo agli oggetti del file system.

Per ottenere risultati ottimali, il programma userà l'API della libreria shell per interagire con le librerie e accedervi. 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 della 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 era comune usare una cartella nota, ad esempio la cartella Documenti personali, come la cartella predefinita nelle operazioni di salvataggio o apertura file. In Windows 7, la libreria corrispondente deve essere usata in modo che l'utente avrà la stessa esperienza nel programma come con altri programmi Windows 7, ad esempio Esplora risorse.

Se attualmente si usa l'API shell di Windows nel programma, l'aggiunta del supporto della libreria è semplice. Ad esempio, se attualmente si chiama la funzione SHGetKnownFolderItem per ottenere il percorso della cartella Documenti personali, è possibile sostituire il valore KNOWNFOLDERID della cartella Documenti noti con il valore KNOWNFOLDERID della libreria corrispondente.

La tabella seguente illustra la relazione tra i valori KNOWNFOLDERID di 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_LibreriaImmagini
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 gruppo Home. Il gruppo Home è 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 di DEFAULTSAVEFOLDERTYPE nella chiamata a metodo IShellLibrary::GetDefaultSaveFolder.

Uso di una finestra di dialogo file comune con librerie

Uso di una finestra di dialogo di file comune con librerie La finestra di dialogo File comune è stata aggiornata per supportare le librerie in Windows 7. La figura seguente mostra come viene visualizzata la finestra di dialogo file comune a un utente in Windows 7.

schermata della finestra di dialogo file comune che mostra le librerie

In Windows 7, se il programma visualizza attualmente una finestra di dialogo file comune e non modifica il modello di finestra di dialogo o associa uno dei relativi eventi, visualizzerà automaticamente la nuova versione di Windows 7 della finestra di dialogo. In particolare, durante la chiamata alla funzione della finestra di dialogo comune, i membri lpfnHook, hInstance, lpTemplatename della struttura OPENFILENAME devono essere impostati su NULL e i flag OFN_ENABLEHOOK e OFN_ENABLETEMPLATE devono essere disattivati.

In Windows 7, le interfacce correlateIFileDialogsostituiscono le funzioni comuni della finestra di dialogo file usate nelle versioni precedenti di Windows. Le funzioni della finestra di dialogo dei file comuni precedenti sono ancora supportate in Windows 7, ma non forniscono l'esperienza utente completa di Windows 7 e non supportano le librerie. Alcune delle nuove funzionalità supportate dalle interfacce relative a IFileDialogincludono:

  • L'utente può accedere alle proprietà dei file supportate da Esplora risorse di Windows 7 per cercare e selezionare i file.
  • Il programma può usare interfacce e metodi dell'API dello spazio dei nomi shell per lavorare con 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 dei file comuni.

È consigliabile usare le interfacce correlateIFileDialogquando:

  • è 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 sia in grado di selezionare più file da una finestra di dialogo di file comune. In questo modo si otterranno i percorsi corretti per l'oggetto selezionato perché una raccolta può avere contenuto archiviato in cartelle diverse.

Per altre informazioni sulle interfacce IFileDialogcorrelate, vedere:

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, deve consentire all'utente di selezionare anche una libreria. L'interfaccia IFileOpenDialog e la funzione SHBrowseForFolder consentono all'utente di selezionare una libreria quando viene richiesto di selezionare una cartella. L'interfaccia di IFileOpenDialog è preferibile rispetto alla funzione SHBrowseForFolder perché IFileOpenDialog supporta l'interfaccia utente di Windows 7.

Per consentire agli utenti di selezionare le cartelle quando si usa l'interfaccia IFileOpenDialog, chiamare SetOptions con il flag FOS_PICKFOLDERS impostato e assicurarsi che il flag 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 le cartelle quando si chiama la funzione SHBrowseForFolder, nel membro ulFlags della strutturaBROWSEINFO, impostare il flag BIF_USENEWUI e rimuovere il flag BIF_RETURNONLYFSDIRS.

BROWSEINFO    browseInfo;
browseInfo.ulFlags = BIF_USENEWUI | ~BIF_RETURNONLYFSDIRS;
// Set other member values
pidl = SHBrowseForFolder(&browseInfo);

Accedere al contenuto della raccolta in un programma

Per accedere al contenuto di una libreria, è necessario usare l'API shell di Windows. Le funzioni dell'API del 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 browser di file personalizzato basato sull'API del file system, non sarà in grado di esplorare le librerie o accedere al contenuto della raccolta.

Questa sezione descrive come accedere al contenuto della raccolta in modo da poter selezionare il modo migliore per aggiornare il programma in modo che funzioni con le librerie.

Accesso al contenuto della raccolta con l'interfaccia IShellLibrary

Il modo più semplice per consentire a un programma di accedere al contenuto della libreria consiste nell'usare l'API della libreria shell . Se si usa un programma che usa l'API del file system, l'API della libreria shell può restituire le cartelle del file system di una libreria, riducendo 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 della shell di Windows. Ad esempio, è possibile usare le interfacceIShellIteme IShellFolder nel programma, insieme alle funzioni helper correlate, per accedere al contenuto di una raccolta nello stesso modo in cui si enumererebbe le cartelle e il contenuto delle cartelle per accedere al contenuto con le API del file system.

Le API della shell di Windows supportano due modalità di enumerazione per accedere al contenuto di una libreria:

  • Sfoglia enumerazione

    L'enumerazione Browse è 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 navigazione

    L'enumerazione navigazione enumera le cartelle della biblioteca. Impostare il flag SHCONTF_NAVIGATION_ENUM per usare questa modalità.

Se il programma usa un controllo albero personalizzato per spostarsi nelle cartelle dell'utente, enumerando le cartelle nella modalità di enumerazione di spostamento, verrà visualizzato un elenco delle cartelle di una raccolta coerente con il modo in cui Esplora risorse enumera le 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 libreria

Il programma può salvare i contenuti dell'utente sia in una raccolta che in una cartella all'interno della raccolta. Analogamente, l'utente può salvare in una cartella specifica in una raccolta o semplicemente salvare nella raccolta.

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 in modo che sia qualsiasi cartella nella libreria. Anche se l'utente non deve configurare un percorso di salvataggio predefinito, ha la possibilità di modificarlo. Se l'utente elimina la cartella attualmente impostata come percorso di salvataggio predefinito, la libreria configurerà automaticamente la cartella successiva nella libreria in modo che sia il percorso di salvataggio predefinito.

Esistono diversi modi per salvare il contenuto utente in una raccolta.

  • API shell

    Se si usa il modello di programmazione Shell e si salva un elemento shell, come rappresentato da un IShellItem, IStorage o IStream, in un oggetto libreria, l'elemento Shell verrà archiviato automaticamente nel percorso di salvataggio predefinito della libreria.

  • API del file-system

    Se si dispone di un programma esistente che usa molte chiamate API del file system, è possibile ottenere un percorso della cartella definita come percorso di salvataggio predefinito della libreria. Il percorso della cartella può quindi essere passato a un'API del file system.

Per esempi di come usare queste funzionalità in un programma, vedere l'esempio ShellStorage in Windows SDK.

Supporto alle operazioni di drag-and-drop in una libreria

Se il tuo programma supporta le funzionalità di trascina e rilascia, queste devono essere aggiornate per supportare la corretta interazione con la libreria. Se un file viene eliminato in una raccolta, 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 inserito in una cartella esistente che non è il percorso di salvataggio predefinito, il file dovrebbe essere aggiunto alla cartella selezionata.

Per esempi su come aggiungere il supporto delle librerie ai tuoi programmi con funzionalità di drag-and-drop, consulta l'esempio ShellLibraryCommandLine nel Windows SDK.

Mantenere la sincronizzazione con una libreria

In questo argomento viene descritto come un programma può mantenere la visualizzazione del contenuto di una raccolta up-to-date.

Aggiornamento in blocco

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 i percorsi correnti di qualsiasi cartella che potrebbe contenere la libreria.

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 portato up-to-date, può quindi registrarsi per le notifiche di modifica per mantenere una visualizzazione corrente.

Notifica dell'API shell

L'API della shell di Windows fornisce la funzioneSHChangeNotifyRegister, che rappresenta il modo preferito per i processi non di servizio per ricevere una notifica di una modifica nella libreria.

Per rilevare le modifiche apportate agli elementi all'interno di una libreria usando l'API shell di Windows, chiamare SHChangeNotifyRegister per registrare il programma per le notifiche delle modifiche apportate agli elementi in una cartella di libreria. Questa funzione può notificare 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 del servizio.

Per rilevare le modifiche apportate agli elementi in una libreria usando l'API del file system, enumerare le cartelle nella libreria e chiamare FindFirstChangeNotification per ogni cartella da monitorare. Il programma riceverà una notifica quando cambia 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 lo 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.

Informazioni sulle librerie

IShellLibrary

Collegamenti Shell

Cartelle Conosciute

Schema di descrizione della libreria

IID_PPV_ARGS