Interfaces e campos da janela Propriedades

  • Artigo

O modelo de seleção para determinar quais informações são exibidas na janela Propriedades é baseado na janela que tem foco no IDE. Cada janela e objeto dentro da janela selecionada pode ter seu objeto de contexto de seleção enviado para o contexto de seleção global. O ambiente atualiza o contexto de seleção global com valores de um quadro de janela quando essa janela tem o foco. Quando o foco muda, o contexto de seleção também muda.

Seleção de rastreamento no IDE

A moldura da janela ou o site, de propriedade do IDE, tem um serviço chamado STrackSelection. As etapas a seguir mostram como uma alteração em uma seleção, causada pelo usuário alterando o foco para outra janela aberta ou selecionando um item de projeto diferente no Gerenciador de Soluções, é implementada para alterar o conteúdo exibido na janela Propriedades .

  1. O objeto criado pelo VSPackage que está localizado na janela selecionada chama QueryService para ter STrackSelection invocar ITrackSelection.

  2. O contêiner de seleção, fornecido pela janela selecionada, cria seu próprio ISelectionContainer objeto. Quando a seleção é alterada, o VSPackage chama OnSelectChange para notificar todos os ouvintes no ambiente, incluindo a janela Propriedades, sobre a alteração. Ele também fornece acesso a informações de hierarquia e item relacionadas à nova seleção.

  3. Chamando OnSelectChange e passando os itens de hierarquia selecionados no VSHPROPID_BrowseObject parâmetro preenche o ISelectionContainer objeto.

  4. Um objeto derivado da interface IDispatch é retornado para __VSHPROPID. VSHPROPID_BrowseObject para o item solicitado e o ambiente o encapsula em um ISelectionContainer (consulte a etapa a seguir). Se a chamada falhar, o ambiente fará uma segunda chamada para , passando a IVsHierarchy::GetPropertyela o contêiner de seleção __VSHPROPID. VSHPROPID_SelContainer que o item de hierarquia ou itens fornecidos.

    Seu projeto VSPackage não cria ISelectionContainer porque a janela fornecida pelo ambiente VSPackage que o implementa (por exemplo, Gerenciador de Soluções) constrói ISelectionContainer em seu nome.

  5. O ambiente invoca os métodos de ISelectionContainer para obter os objetos com base na IDispatch interface para preencher a janela Propriedades .

    Quando um valor na janela Propriedades é alterado, os VSPackages implementam IVsTrackSelectionEx::OnElementValueChangeEx e IVsTrackSelectionEx::OnSelectionChangeEx relatam a alteração no valor do elemento. Em seguida, o IVsUIShell ambiente invoca ou IConnectionPointContainer mantém as informações exibidas na janela Propriedades sincronizadas com os valores de propriedade. Para obter mais informações, consulte Atualizando valores de propriedade na janela Propriedades.

    Além de selecionar um item de projeto diferente no Gerenciador de Soluções para exibir propriedades relacionadas a esse item, você também pode escolher um objeto diferente em uma janela de formulário ou documento usando a lista suspensa disponível na janela Propriedades . Para obter mais informações, consulte Lista de objetos da janela Propriedades.

    Você pode alterar a maneira como as informações são exibidas na grade da janela Propriedades de alfabética para categórica e, se disponível, também pode abrir uma página de propriedades para um objeto selecionado clicando nos botões apropriados na janela Propriedades. Para obter mais informações, consulte Botões da janela de propriedades e Páginas de propriedades.

    Finalmente, a parte inferior da janela Propriedades também contém uma descrição do campo selecionado na grade da janela Propriedades. Para obter mais informações, consulte Obtendo descrições de campo da janela Propriedades.

Atualizando valores de propriedade na janela Propriedades

Há duas maneiras de manter a janela Propriedades sincronizada com as alterações de valor da propriedade. A primeira é chamar a IVsUIShell interface, que fornece acesso à funcionalidade básica de janelas, incluindo acesso e criação de janelas de ferramentas e documentos fornecidas pelo ambiente. As etapas a seguir descrevem esse processo de sincronização.

Atualizando valores de propriedade usando IVsUIShell

Para atualizar valores de propriedade usando a interface IVsUIShell

  1. Chame IVsUIShell (por meio SVsUIShell de serviço) sempre que VSPackages, projetos ou editores precisarem criar ou enumerar janelas de ferramentas ou documentos.

  2. Implementar para manter a janela Propriedades RefreshPropertyBrowser sincronizada com as alterações de propriedade de um projeto (ou qualquer outro objeto selecionado que está sendo navegado pela janela Propriedades) sem implementar IConnectionPointContainer e disparar OnChanged eventos.

  3. Implementar os IVsHierarchy métodos AdviseHierarchyEvents e estabelecer e UnadviseHierarchyEvents desabilitar, respectivamente, a notificação do cliente de eventos de hierarquia sem exigir que a hierarquia implemente IConnectionPointContainero .

Atualizando valores de propriedade usando IConnection

A segunda maneira de manter a janela Propriedades em sincronia com as alterações de valor de propriedade é implementar IConnection no objeto conectável para indicar a existência das interfaces de saída. Se você deseja localizar o nome da propriedade, derive seu objeto de ICustomTypeDescriptor. A ICustomTypeDescriptor implementação pode modificar os descritores de propriedade que retorna e alterar o nome de uma propriedade. Para localizar a descrição, crie um atributo que derive e DescriptionAttribute substitua a propriedade Description.

Considerações na implementação da interface IConnection

  1. IConnection Fornece acesso a um subobjeto enumerador com a IEnumConnectionPoints interface. Ele também fornece acesso a todos os subobjetos do ponto de conexão, cada um dos quais implementa a IConnectionPoint interface.

  2. Qualquer objeto de navegação é responsável pela implementação de um IPropertyNotifySink evento. A janela Propriedades aconselhará o evento definido através de IConnection.

  3. Um ponto de conexão controla quantas conexões (uma ou mais) ele permite em sua implementação do Advise. Um ponto de conexão que permite que apenas uma interface possa retornar E_NOTIMPL do EnumConnections método.

  4. Um cliente pode chamar a interface para obter acesso a um subobjeto enumerador com a IConnectionIEnumConnectionPoints interface. A IEnumConnectionPoints interface pode então ser chamada para enumerar pontos de conexão para cada ID de interface de saída (IID).

  5. IConnection também pode ser chamado para obter acesso a subobjetos de ponto de conexão com a IConnectionPoint interface para cada IID de saída. Por meio da IConnectionPoint interface, um cliente inicia ou encerra um loop de consultoria com o objeto conectável e a própria sincronização do cliente. O cliente também pode chamar a interface para obter um objeto enumerador com a IConnectionPointIEnumConnections interface para enumerar as conexões que ele conhece.

Obtendo descrições dos campos na janela Propriedades

Na parte inferior da janela Propriedades , uma área de descrição exibe informações relacionadas ao campo de propriedade selecionado. Esse recurso está ativado por padrão. Se quiser ocultar o campo de descrição, clique com o botão direito do mouse na janela Propriedades e clique em Descrição. Isso também remove a marca de seleção ao lado do título Descrição na janela de menu. Você pode exibir o campo novamente seguindo as mesmas etapas para ativar novamente a Descrição .

As informações no campo de descrição vêm de ITypeInfo. Cada método, interface, coclasse e assim por diante pode ter um atributo não localizado helpstring na biblioteca de tipos. A janela Propriedades recupera a cadeia de caracteres de GetDocumentation.

Para especificar cadeias de ajuda localizadas

  1. Adicione o helpstringdll atributo à instrução library na biblioteca de tipos (typelib).

    Observação

    Esta etapa é opcional se a biblioteca de tipos estiver em um arquivo de biblioteca de objetos (.olb).

  2. Especifique helpstringcontext atributos para as cadeias de caracteres. Você também pode especificar helpstring atributos.

    Esses atributos são distintos dos helpfile atributos e helpcontext , que estão contidos nos tópicos da Ajuda do arquivo .chm reais.

    Para recuperar as informações de descrição a serem exibidas para o nome da propriedade realçada, a janela Propriedades chama GetDocumentation2 a propriedade selecionada, especificando o atributo desejado lcid para a cadeia de caracteres de saída. Internamente, ITypeInfo2 localiza o arquivo de .dll especificado no helpstringdll atributo e chama DLLGetDocumentation esse arquivo .dll com o contexto e lcid o atributo especificados.

    A assinatura e implementação de DLLGetDocumentation são:

STDAPI DLLGetDocumentation
(
   ITypeLib * /* ptlib */,
   ITypeInfo * /* ptinfo */,
   LCID /* lcid */,
   DWORD dwCtx,
   BSTR * pbstrHelpString
);

A DLLGetDocumentation função deve ser uma exportação definida no arquivo .def para a DLL.

Internamente, um arquivo .olb é criado que é na verdade uma DLL. Essa DLL contém um recurso, o arquivo de biblioteca de tipos (.tlb) e uma função exportada, DLLGetDocumentation.

No caso de arquivos .olb, o atributo é opcional porque é o mesmo arquivo que contém o helpstringdll próprio arquivo .tlb.

Para que as cadeias de caracteres apareçam no painel Descrições, portanto, o mínimo necessário é especificar o helpstring atributo na biblioteca de tipos. Se desejar que essas cadeias de caracteres sejam localizadas, você precisará especificar o atributo (opcional) e o helpstringdllhelpstringcontext atributo (obrigatório) e implementar DLLGetDocumentation.

Não há interfaces adicionais que precisem ser implementadas ao obter informações localizadas por meio do atributo idl e DLLGetDocumentationdo helpstringcontext .

Outra maneira de obter o nome localizado e a descrição de uma propriedade é implementando GetLocalizedPropertyInfoo . Para obter mais informações relacionadas à implementação desse método, consulte Campos e interfaces da janela Propriedades.

Confira também