Usando bibliotecas em seu programa
Este tópico descreve algumas das coisas a considerar ao usar bibliotecas em seu programa.
Neste tópico:
- Visão geral da programação da Biblioteca
- Programação com Bibliotecas
- Usando uma caixa de diálogo de ficheiro comum com bibliotecas
- Habilitando a seleção de bibliotecas a partir da interface do usuário
- Acessando o conteúdo da biblioteca em um programa
- Salvar conteúdo do usuário em uma biblioteca
- Suporte a operações de arrastar e soltar numa biblioteca
- Manter a sincronia com uma biblioteca
- Tópicos relacionados
Visão geral da programação da biblioteca
As bibliotecas permitem que os usuários organizem seu conteúdo baseado em arquivos de uma forma que seja significativa para eles e não limitada pela organização do sistema de arquivos. Quando seu programa oferece suporte a bibliotecas, ele permite que o usuário encontre seu conteúdo de uma maneira que faça sentido para ele, ao mesmo tempo em que apresenta uma interface de usuário consistente com a experiência do usuário do Windows 7. As bibliotecas também facilitam a localização do conteúdo baseado em arquivo armazenado em pastas diferentes ou em máquinas diferentes.
Os tópicos desta seção descrevem como você pode adicionar suporte a bibliotecas ao seu programa e aproveitar os novos recursos que as bibliotecas oferecem. O Windows 7 fornece parte desse suporte por padrão. Se o seu programa não modificar as caixas de diálogo de arquivo comuns que ele usa atualmente, ele pode exigir muito pouca programação adicional para suportar bibliotecas.
Esta seção descreve alguns dos principais recursos que as bibliotecas fornecem e como suportá-los em seu programa. Com essas informações, você pode decidir quais recursos fornecerão a melhor experiência de usuário do seu programa. Se o seu programa personalizar as caixas de diálogo de arquivo comuns, as informações nesta seção podem ajudá-lo a determinar como usar as novas caixas de diálogo de arquivo comum para usar bibliotecas e fornecer funcionalidade equivalente no Windows 7.
Programação com Bibliotecas
O modelo de programação do Shell do Windows descreve como um programa interage com objetos de programação do Shell do Windows. Embora os objetos do sistema de arquivos, como arquivos e diretórios, sejam representados por objetos do Shell do Windows, nem todos os objetos do Shell do Windows são representados pelo sistema de arquivos. Bibliotecas, por exemplo, são objetos do Shell do Windows que não têm um equivalente de sistema de arquivos. Usar objetos do Shell do Windows em seu programa permite que seu programa acesse todos os objetos do Shell e não apenas objetos do sistema de arquivos.
Para obter os melhores resultados, seu programa usaria o Shell Library API para interagir com bibliotecas e acessar seu conteúdo. Embora as bibliotecas contenham itens do sistema de arquivos, como pastas e arquivos, as bibliotecas não são itens do sistema de arquivos. Como tal, as APIs do sistema de arquivos não podem ser usadas para acessar recursos ou conteúdo da biblioteca.
Se você tiver um programa existente que atualmente usa muitas APIs do sistema de arquivos, seu programa ainda poderá aproveitar os recursos da biblioteca. O API da Biblioteca do Shell do é capaz de fornecer referências de sistema de ficheiros para os itens encontrados numa biblioteca, e essas referências de sistema de ficheiros, como o nome do ficheiro e o caminho, podem ser passadas para as APIs de sistema de ficheiros já existentes no seu programa atual.
Movendo-se de pastas conhecidas para bibliotecas
Antes do Windows 7, era comum usar uma pasta conhecida, como a pasta Meus Documentos, como a pasta padrão em operações de salvamento ou abertura de arquivos. No Windows 7, a biblioteca correspondente deve ser usada para que o usuário tenha a mesma experiência em seu programa como teria com outros programas do Windows 7, como o Windows Explorer.
Se você estiver usando a API do Shell do Windows em seu programa, adicionar suporte à biblioteca é simples. Por exemplo, se você atualmente chamar a função deSHGetKnownFolderItempara obter o local da pasta Meus Documentos, poderá substituir o valor KNOWNFOLDERID da pasta conhecida Meus Documentos pelo valor KNOWNFOLDERID da biblioteca correspondente.
A tabela a seguir mostra a relação entre os valores KNOWNFOLDERID de pastas conhecidas e o valor KNOWNFOLDERID da biblioteca correspondente no Windows 7.
| Valores conhecidos da pasta KNOWNFOLDERID | Valores da biblioteca KNOWNFOLDERID |
|---|---|
| FOLDERID_Documentos | FOLDERID_BibliotecaDocumentos |
| FOLDERID_Pictures | FOLDERID_BibliotecaDeImagens |
| FOLDERID_Music | FOLDERID_MusicLibrary |
| FOLDERID_RecordedTV | FOLDERID_BibliotecaDeTVGravada |
Grupo Doméstico e bibliotecas partilhadas
Adicionar suporte de biblioteca ao seu programa habilitará o suporte para bibliotecas compartilhadas em um Grupo Doméstico. O Grupo Doméstico é identificado por seu KNOWNFOLDERID valor de FOLDERID_HomeGroup. O seu programa pode identificar o local de salvamento padrão privado ou compartilhado do usuário, definindo o valor DEFAULTSAVEFOLDERTYPE na chamada para o método IShellLibrary::GetDefaultSaveFolder.
Usando uma caixa de diálogo de arquivo comum com bibliotecas
Usando uma caixa de diálogo de arquivo comum com bibliotecas A caixa de diálogo de arquivo comum foi atualizada para oferecer suporte a bibliotecas no Windows 7. A ilustração a seguir mostra como a caixa de diálogo de arquivo comum aparece para um usuário no Windows 7.
No Windows 7, se o programa exibir atualmente uma caixa de diálogo de arquivo comum e não alterar o modelo de caixa de diálogo ou conectar nenhum de seus eventos, ele exibirá a nova versão do Windows 7 da caixa de diálogo automaticamente. Especificamente, na chamada para a função de caixa de diálogo de arquivo comum, o lpfnHook, hInstance, lpTemplatename membros da estrutura deOPENFILENAME dodevem estar NULL e os sinalizadores OFN_ENABLEHOOK e OFN_ENABLETEMPLATE devem ser claros.
No Windows 7, as interfaces relacionadas ao IFileDialogsubstituem as funções comuns da caixa de diálogo de arquivo que foram usadas em versões anteriores do Windows. As funções de caixa de diálogo de arquivo comuns anteriores ainda são suportadas no Windows 7, mas não fornecem a experiência completa do usuário do Windows 7 e não oferecem suporte a bibliotecas. Alguns dos novos recursos suportados pelas interfaces relacionadas com o IFileDialogincluem:
- O usuário pode acessar as propriedades de arquivo suportadas pelo Windows 7 Windows Explorer para pesquisar e selecionar os arquivos.
- O programa pode usar interfaces e métodos da API de namespace do Shell para trabalhar com os itens.
- O programa pode usar um modelo de personalização controlado por dados em vez de um modelo de personalização controlado por arquivo de recursos para adicionar novos controles às caixas de diálogo de arquivo comuns.
Você deve usar as interfaces relacionadas ao IFileDialogquando:
- você precisa personalizar a caixa de diálogo de arquivo comum para o seu programa no Windows 7. Isso permitirá que seu programa trabalhe com bibliotecas e suporte à personalização de sua caixa de diálogo.
- Você deseja que o usuário possa selecionar vários arquivos de uma caixa de diálogo de arquivo comum. Isso garantirá que você obtenha os caminhos corretos para o objeto selecionado, pois uma biblioteca pode ter conteúdo armazenado em pastas diferentes.
Para obter mais informações sobre as interfaces relacionadas ao IFileDialog , consulte:
- IFileDialog
- IFileOpenDialog
- IFileSaveDialog
- IFileDialogCustomize
- IFileDialogEvents
- IFileDialogControlEvents
Habilitando a seleção de bibliotecas a partir da interface do usuário
Se o seu programa permite que o usuário selecione uma pasta, como para funções de importação ou exportação, no Windows 7, ele deve permitir que o usuário selecione uma biblioteca também. O interface de IFileOpenDialog e função SHBrowseForFolder permitem que o usuário selecione uma biblioteca quando solicitado a selecionar uma pasta. A interface IFileOpenDialog é preferida sobre a função SHBrowseForFolder porque IFileOpenDialog suporta a interface do usuário do Windows 7.
Para permitir que os usuários selecionem pastas ao usar a interfaceIFileOpenDialog, chame SetOptions com o sinalizador FOS_PICKFOLDERS definido e verifique se o sinalizador FOS_FORCEFILESYSTEM está limpo.
FILEOPENDIALOGOPTIONS fileOptions;
hr = fileOpenDialogBox->GetOptions(&fileOptions);
fileOptions = fileOptions | FOS_PICKFOLDERS | ~FOS_FORCEFILESYSTEM;
hr = fileOpenDialogBox->SetOptions(fileOptions);
Para permitir que os utilizadores selecionem pastas ao chamar a função SHBrowseForFolder, no membro ulFlags da estruturaBROWSEINFO, defina o sinalizador BIF_USENEWUI e desmarque o sinalizador BIF_RETURNONLYFSDIRS.
BROWSEINFO browseInfo;
browseInfo.ulFlags = BIF_USENEWUI | ~BIF_RETURNONLYFSDIRS;
// Set other member values
pidl = SHBrowseForFolder(&browseInfo);
Acessando o conteúdo da biblioteca em um programa
Para acessar o conteúdo de uma biblioteca, você deve usar a API do Shell do Windows. As funções da API do sistema de arquivos não podem ser usadas para acessar o conteúdo da biblioteca porque as bibliotecas não são objetos do sistema de arquivos. Se o programa usar um navegador de arquivos personalizado baseado na API do sistema de arquivos, ele não poderá navegar em bibliotecas ou acessar o conteúdo da biblioteca.
Esta seção descreve como você pode acessar o conteúdo da biblioteca para que você possa selecionar a melhor maneira de atualizar seu programa para trabalhar com bibliotecas.
Acessando o conteúdo da biblioteca com a interface IShellLibrary
A maneira mais fácil de um programa acessar o conteúdo da biblioteca é usar o Shell Library API. Se você estiver trabalhando em um programa que usa a API do sistema de arquivos, a API do Shell Library pode retornar as pastas do sistema de arquivos de uma biblioteca, o que minimiza a alteração no código do 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
Acessando o conteúdo da biblioteca com as APIs do Shell
Como os objetos de biblioteca fazem parte do modelo de programação do Shell, eles podem ser usados com outras APIs do Shell do Windows. Por exemplo, pode usar as interfaces IShellItem e IShellFolder no seu programa, juntamente com funções auxiliares relacionadas, para aceder ao conteúdo de uma biblioteca da mesma forma que enumerar pastas e respetivo conteúdo para aceder ao conteúdo com as APIs do sistema de ficheiros.
As APIs do Shell do Windows oferecem suporte a dois modos de enumeração para acessar o conteúdo de uma biblioteca:
Procurar enumeração
A enumeração de navegação é o modo de enumeração padrão e enumera o conteúdo de uma pasta de biblioteca. Desmarque o sinalizador SHCONTF_NAVIGATION_ENUM para usar esse modo.
Enumeração de navegação
A enumeração de navegação enumera as pastas da biblioteca. Defina o sinalizador SHCONTF_NAVIGATION_ENUM para usar esse modo.
Se o programa usa um controle de árvore personalizado para navegar pelas pastas do usuário, enumerar as pastas no modo de enumeração de navegação fornecerá uma lista de pastas de uma biblioteca que é consistente com como o Windows Explorer enumera pastas no Windows 7.
Para obter exemplos de como usar esses recursos em um programa, consulte o exemplo ShellStorage no SDK do Windows.
Guardar conteúdo de utilizador numa biblioteca
Seu programa pode salvar o conteúdo do usuário em uma biblioteca, bem como em uma pasta na biblioteca. Da mesma forma, o usuário pode salvar em uma pasta específica em uma biblioteca ou eles podem apenas salvar na biblioteca.
Cada biblioteca tem uma pasta que é designada como o local de salvamento padrão. O local de salvamento padrão é definido quando a biblioteca é criada; no entanto, o usuário pode reatribuir o local de salvamento padrão para ser qualquer pasta na biblioteca. Embora o usuário não precise configurar um local de salvamento padrão, ele tem a opção de alterá-lo. Se o usuário excluir a pasta que está atualmente definida como o local de salvamento padrão, a biblioteca configurará automaticamente a próxima pasta na biblioteca para ser o local de salvamento padrão.
Há várias maneiras de salvar o conteúdo do usuário em uma biblioteca.
API do Shell
Se você estiver usando o modelo de programação do Shell e salvar um item do Shell, conforme representado por um IShellItem, IStorage ou IStream, em um objeto de biblioteca, o item do Shell será armazenado automaticamente no local de salvamento padrão da biblioteca.
API do sistema de arquivos
Se você tiver um programa existente que usa muitas chamadas de API do sistema de arquivos, poderá obter um caminho para a pasta definida como o local de salvamento padrão da biblioteca. O caminho da pasta pode então ser passado para uma API do sistema de arquivos.
Para obter exemplos de como usar esses recursos em um programa, consulte o exemplo ShellStorage no SDK do Windows.
Suporte a operações de arrastar e soltar numa biblioteca
Se o seu programa suportar ações de arrastar e soltar, elas devem ser atualizadas para suportar a interação correta com a biblioteca. Se um arquivo for solto em uma biblioteca, o arquivo descartado deverá ser salvo no local de salvamento padrão. Se uma pasta for solta em uma biblioteca, a pasta descartada deverá ser adicionada como uma nova pasta à biblioteca. Se um arquivo for solto em uma pasta existente que não seja o local de salvamento padrão, o arquivo deverá ser adicionado à pasta selecionada.
Para obter exemplos de como adicionar suporte de biblioteca à funcionalidade de arrastar e soltar dos programas, consulte o exemplo ShellLibraryCommandLine no SDK do Windows.
Manter-se sincronizado com uma biblioteca
Este tópico descreve como um programa pode manter a sua exibição do conteúdo de uma biblioteca up-to-date.
Atualização em massa
Como o usuário pode modificar as pastas de uma biblioteca interativamente quando o programa não está em execução, o programa deve chamar SHResolveLibrary quando ele começar a descobrir e armazenar quaisquer alterações na biblioteca. A API do Shell fornece a função de SHResolveLibrary para permitir que um programa obtenha o conteúdo atual de uma biblioteca e os locais atuais de quaisquer pastas que a biblioteca possa conter.
Observe que SHResolveLibrary é uma função de bloqueio que pode levar muito tempo para retornar dependendo do que mudou na biblioteca. Como tal, ele não deve ser chamado a partir de um thread da interface do usuário.
Depois que o programa for trazido up-to-date, ele pode se registrar para notificações de alteração para manter uma exibição atual.
Notificação da API do Shell
A API do Shell do Windows fornece a função SHChangeNotifyRegister, que é a maneira preferida para processos fora de serviço serem notificados de uma alteração na biblioteca.
Para detetar alterações em itens dentro de uma biblioteca usando a API do Shell do Windows, chame SHChangeNotifyRegister para registrar seu programa para notificações de alterações em itens em uma pasta de biblioteca. Esta função pode notificar o seu programa se houver uma alteração em qualquer biblioteca ou apenas em uma biblioteca específica. As notificações são enviadas imediatamente quando uma biblioteca é alterada.
Notificação da API do sistema de arquivos
As notificações do sistema de arquivos devem ser usadas em processos de serviço.
Para detetar alterações em itens em uma biblioteca usando a API do sistema de arquivos, enumere as pastas na biblioteca e chame FindFirstChangeNotification para cada pasta a ser monitorada. Seu programa receberá uma notificação quando uma pasta monitorada for alterada. Para localizar o arquivo específico de arquivos que foram alterados na pasta, chame ReadDirectoryChangesW. Para detetar alterações no arquivo de descrição da biblioteca, monitore a pasta que o contém. O arquivo de descrição da biblioteca pode ser encontrado na pasta FOLDERID_Libraries. O arquivo de descrição da biblioteca, no entanto, não deve ser aberto ou modificado.
Tópicos relacionados