Usando bibliotecas em seu programa
Este tópico descreve algumas das coisas a serem consideradas ao usar bibliotecas em seu programa.
Neste tópico:
- Visão geral da programação de biblioteca
- Programação com bibliotecas
- Usando uma caixa de diálogo de arquivo comum com bibliotecas
- Habilitando a seleção de biblioteca da interface do usuário
- Acessando o conteúdo da biblioteca em um programa
- Salvando o conteúdo do usuário em uma biblioteca
- Suporte a operações de arrastar e soltar em uma biblioteca
- Manter a sincronização com uma biblioteca
- Tópicos relacionados
Visão geral da programação de biblioteca
As bibliotecas permitem que os usuários organizem seu conteúdo baseado em arquivo de uma maneira significativa para eles e não limitada pela organização do sistema de arquivos. Quando o programa dá suporte a bibliotecas, ele permite que o usuário encontre seu conteúdo de uma maneira que faça sentido para ele ao apresentar uma interface do 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 computadores diferentes.
Os tópicos nesta seção descrevem como você pode adicionar suporte à biblioteca ao seu programa e aproveitar os novos recursos que as bibliotecas oferecem. O Windows 7 fornece parte desse suporte por padrão. Se o programa não modificar as caixas de diálogo de arquivo comuns que ele usa atualmente, poderá exigir muito pouca programação adicional para dar suporte a bibliotecas.
Esta seção descreve alguns dos principais recursos que as bibliotecas fornecem e como dar suporte a elas em seu programa. Com essas informações, você pode decidir quais recursos fornecerão a melhor experiência do usuário do seu programa. Se o programa personalizar as caixas de diálogo de arquivo comuns, as informações nesta seção poderão ajudá-lo a determinar como usar as novas caixas de diálogo de arquivo comuns para usar bibliotecas e fornecer funcionalidade equivalente no Windows 7.
Programação com bibliotecas
O modelo de programação do Windows Shell descreve como um programa interage com objetos de programação do Windows Shell. 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. As bibliotecas, por exemplo, são objetos do Shell do Windows que não têm um equivalente de sistema de arquivos. O uso de objetos do Windows Shell em seu programa permite que seu programa acesse todos os objetos Shell e não apenas objetos do sistema de arquivos.
Para obter os melhores resultados, seu programa usaria a API da Biblioteca de Shell 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. Dessa forma, as APIs do sistema de arquivos não podem ser usadas para acessar recursos de biblioteca ou conteúdo de 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. A API da Biblioteca do Shell pode fornecer referências do sistema de arquivos aos itens encontrados em uma biblioteca e essas referências do sistema de arquivos, como o nome e o caminho do arquivo, podem ser passadas para as APIs existentes do sistema de arquivos que estão em seu programa existente.
Migrando 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 de arquivo ou abertura de arquivo. No Windows 7, a biblioteca correspondente deve ser usada para que o usuário tenha a mesma experiência em seu programa como faria com outros programas do Windows 7, como o Windows Explorer.
Se você estiver usando atualmente a API do Shell do Windows em seu programa, adicionar suporte à biblioteca será simples. Por exemplo, se você atualmente chamar a função SHGetKnownFolderItem para 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 KNOWNFOLDERID da pasta conhecida | Valores KNOWNFOLDERID da biblioteca |
|---|---|
| FOLDERID_Documents | FOLDERID_DocumentsLibrary |
| FOLDERID_Pictures | FOLDERID_PicturesLibrary |
| FOLDERID_Music | FOLDERID_MusicLibrary |
| FOLDERID_RecordedTV | FOLDERID_RecordedTVLibrary |
HomeGroup e bibliotecas compartilhadas
Adicionar suporte à biblioteca ao programa habilitará o suporte para bibliotecas compartilhadas em um Grupo Doméstico. O Grupo Doméstico é identificado por seu valor KNOWNFOLDERID de FOLDERID_HomeGroup. Seu programa pode encontrar a identificação do 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 arquivo comum foi atualizada para dar suporte a bibliotecas no Windows 7. A ilustração a seguir mostra como a caixa de diálogo arquivo comum é exibida para um usuário no Windows 7.
No Windows 7, se o programa atualmente exibir uma caixa de diálogo de arquivo comum e não alterar o modelo da caixa de diálogo ou conectar qualquer um de seus eventos, ele exibirá automaticamente a nova versão do Windows 7 da caixa de diálogo. Especificamente, na chamada para a função de caixa de diálogo de arquivo comum, os membros lpfnHook, hInstance, lpTemplatename da estrutura OPENFILENAME devem ser NULL e os sinalizadores OFN_ENABLEHOOK e OFN_ENABLETEMPLATE devem estar limpos.
No Windows 7, as interfaces relacionadas a IFileDialog substituem 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 têm suporte no Windows 7, mas não fornecem a experiência completa do usuário do Windows 7 e não dão suporte a bibliotecas. Alguns dos novos recursos compatíveis com as interfaces relacionadas ao IFileDialog incluem:
- O usuário pode acessar as propriedades de arquivo compatíveis com o Windows Explorer do Windows 7 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 a IFileDialog quando:
- você precisa personalizar a caixa de diálogo de arquivo comum para seu programa no Windows 7. Isso permitirá que seu programa funcione com bibliotecas e dê suporte à personalização da 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 porque uma biblioteca pode ter conteúdos armazenados em pastas diferentes.
Para obter mais informações sobre as interfaces relacionadas a IFileDialog, consulte:
- IFileDialog
- IFileOpenDialog
- IFileSaveDialog
- Ifiledialogcustomize
- IFileDialogEvents
- IFileDialogControlEvents
Habilitando a seleção de biblioteca da interface do usuário
Se o programa permitir que o usuário selecione uma pasta, como para funções de importação ou exportação, no Windows 7, ele também deverá permitir que o usuário selecione uma biblioteca. A interface IFileOpenDialog e a função SHBrowseForFolder permitem que o usuário selecione uma biblioteca quando solicitado a selecionar uma pasta. A interface IFileOpenDialog é preferencial em relação à função SHBrowseForFolder porque IFileOpenDialog dá suporte à interface do usuário do Windows 7.
Para permitir que os usuários selecionem pastas ao usar a interface IFileOpenDialog , chame SetOptions com o sinalizador FOS_PICKFOLDERS definido e verifique se o sinalizador FOS_FORCEFILESYSTEM está claro.
FILEOPENDIALOGOPTIONS fileOptions;
hr = fileOpenDialogBox->GetOptions(&fileOptions);
fileOptions = fileOptions | FOS_PICKFOLDERS | ~FOS_FORCEFILESYSTEM;
hr = fileOpenDialogBox->SetOptions(fileOptions);
Para permitir que os usuários selecionem pastas ao chamar a função SHBrowseForFolder, no membro ulFlags da estrutura BROWSEINFO , 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á procurar 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 para um programa acessar o conteúdo da biblioteca é usar a API da Biblioteca de Shell. Se você estiver trabalhando em um programa que usa a API do sistema de arquivos, a API da Biblioteca do Shell poderá 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 shell, eles podem ser usados com outras APIs do Shell do Windows. Por exemplo, você pode usar as interfaces IShellItem e IShellFolder em seu programa, juntamente com funções auxiliares relacionadas, para acessar o conteúdo de uma biblioteca da mesma forma que você enumeraria pastas e conteúdos de pastas para acessar o conteúdo com as APIs do sistema de arquivos.
As APIs do Windows Shell dão suporte a dois modos de enumeração para acessar o conteúdo de uma biblioteca:
Procurar enumeração
Procurar enumeraçã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 usar 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 das pastas de uma biblioteca consistente com a forma 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.
Salvando o conteúdo do usuário em uma 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 pode apenas salvar na biblioteca.
Cada biblioteca tem uma pasta 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á 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.
Shell API
Se você estiver usando o modelo de programação shell e salvar um item shell, conforme representado por um IShellItem, IStorage ou IStream, em um objeto de biblioteca, o item 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 à API do sistema de arquivos, poderá obter um caminho para a pasta definida como o local de salvamento padrão da biblioteca. Em seguida, o caminho da pasta pode 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 em uma biblioteca
Se o programa der suporte a ações de arrastar e soltar, elas deverão ser atualizadas para dar suporte à interação correta da biblioteca. Se um arquivo for removido em uma biblioteca, o arquivo descartado deverá ser salvo no local de salvamento padrão. Se uma pasta for descartada em uma biblioteca, a pasta descartada deverá ser adicionada como uma nova pasta à biblioteca. Se um arquivo for removido para uma pasta existente que não é o local de salvamento padrão, o arquivo deverá ser adicionado à pasta selecionada.
Para obter exemplos de como adicionar suporte à biblioteca para a funcionalidade de arrastar e soltar de seus programas, consulte o exemplo ShellLibraryCommandLine no SDK do Windows.
Mantendo-se sincronizado com uma biblioteca
Este tópico descreve como um programa pode manter sua exibição do conteúdo de uma biblioteca atualizada.
Atualização em Massa
Como o usuário pode modificar as pastas de uma biblioteca interativamente quando o programa não estiver em execução, seu programa deve chamar SHResolveLibrary quando começar a descobrir e armazenar quaisquer alterações na biblioteca. A API do Shell fornece a função SHResolveLibrary para habilitar um programa para obter 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. Dessa forma, ele não deve ser chamado de um thread de interface do usuário.
Depois que o programa for atualizado, ele poderá 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 preferencial para processos que não são de serviço serem notificados sobre uma alteração na biblioteca.
Para detectar alterações em itens em 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. Essa função poderá notificar 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 de API do sistema de arquivos
As notificações do sistema de arquivos devem ser usadas em processos de serviço.
Para detectar 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á notificação quando uma pasta monitorada for alterada. Para localizar o arquivo específico de arquivos que foram alterados na pasta, chame ReadDirectoryChangesW. Para detectar alterações no arquivo de descrição da biblioteca, monitore a pasta que a contém. O arquivo de descrição da biblioteca pode ser encontrado na pasta FOLDERID_Libraries . No entanto, o arquivo de descrição da biblioteca não deve ser aberto ou modificado.
Tópicos relacionados