Mantendo o estado da faixa de opções

A estrutura do Windows Ribon (Faixa de Opções) fornece a capacidade de preservar o estado de uma variedade de configurações e preferências do usuário entre sessões de aplicativo.

• Introdução
• Uma experiência previsível
• Salvar Configurações da Faixa de Opções
• Carregar Configurações da Faixa de Opções
• Tópicos relacionados

Introdução

Vários aspectos de uma faixa de opções, incluindo preferências de configuração e interação, podem ser personalizados por um usuário em tempo de execução para melhorar a usabilidade e a produtividade. A estrutura da Faixa de Opções fornece a funcionalidade para preservar essas configurações entre sessões de aplicativo por meio de dois métodos definidos na implementação da interface IUIRibbon : IUIRibbon::LoadSettingsFromStream e IUIRibbon::SaveSettingsToStream.

Uma experiência previsível

As Diretrizes de Experiência do Usuário da Faixa de Opções aconselham que, para fornecer a experiência de usuário mais previsível possível, os aplicativos da Faixa de Opções devem preservar o estado da faixa de opções (além da última guia selecionada) à medida que o aplicativo é fechado. Dessa forma, quando o mesmo aplicativo é iniciado, as configurações e personalizações da sessão anterior podem ser restauradas e o usuário pode esperar continuar interagindo com o aplicativo da mesma maneira que o deixou.

As configurações da faixa de opções que podem ser modificadas em tempo de execução e preservadas entre sessões de aplicativo são listadas no menu de contexto Comando. Eles incluem:

• Comandos adicionados à lista Comandos da Barra de Ferramentas de Acesso Rápido pelo usuário. Especificado por um objeto IUICollection por meio da chave de propriedade UI_PKEY_ItemsSource.

  A captura de tela a seguir mostra o menu de contexto Adicionar à Barra de Ferramentas de Acesso Rápido Comando.

  

• O estado de encaixe preferencial da Barra de Ferramentas de Acesso Rápido . Especificado pelo valor UI_CONTROLDOCK da chave de propriedade UI_PKEY_QuickAccessToolbarDock .

  Esta captura de tela mostra a Barra de Ferramentas de Acesso Rápido no local da barra de título do aplicativo padrão e a Barra de Ferramentas Mostrar Acesso Rápido abaixo do menu de contexto da Faixa de Opções Comando.

  

  Esta captura de tela mostra a Barra de Ferramentas de Acesso Rápido abaixo da faixa de opções.

  

• O estado minimizado da faixa de opções, conforme especificado pelo valor booliano da chave de propriedade UI_PKEY_Minimized .

  Observação

  O estado minimizado da faixa de opções não é equivalente ao estado recolhido da faixa de opções. Quando está no estado recolhido, a faixa de opções fica completamente oculta e não pode ser interagente. A estrutura invocará esse estado automaticamente se a janela do aplicativo for reduzida em tamanho, horizontal ou verticalmente, para o ponto em que a faixa de opções obscurece o workspace do aplicativo. A estrutura restaura a faixa de opções quando o tamanho da janela do aplicativo é aumentado.

   

  Esta captura de tela mostra o menu de contexto Minimizar a Faixa de Opções Comando.

  

  Esta captura de tela mostra uma faixa de opções minimizada.

  

Salvar Configurações da Faixa de Opções

O método IUIRibbon::SaveSettingsToStream grava uma representação binária do estado persistente da faixa de opções (descrita na seção anterior) em um objeto IStream . Em seguida, o aplicativo salva o conteúdo do objeto IStream em um arquivo ou no Registro do Windows.

O exemplo a seguir demonstra o código básico necessário para gravar o estado da faixa de opções em um objeto IStream usando o método IUIRibbon::SaveSettingsToStream .

// pRibbon        - Pointer to the IUIRibbon interface
// ppStatusStream - Pointer to the location of a newly created IStream object
HRESULT CApplication::SaveRibbonStatusToStream(
                        __in IUIRibbon *pRibbon, 
                        __out IStream **ppStatusStream)
{
  HRESULT hr = E_FAIL; 

  *ppStatusStream = NULL;
  IStream* pStream;
  if (SUCCEEDED(hr = CreateStreamOnHGlobal(
                       NULL,  // Internally allocate a new shared memory.
                       FALSE, // Free hGlobal after IStream object released.
                       &pStream)))
  {
    if (SUCCEEDED(hr = pRibbon->SaveSettingsToStream(*ppStatusStream)))
    {                  
      pStream->AddRef();
      *ppStatusStream = pStream;
    }
    pStream->Release();
  }
  return hr;
}

Carregar Configurações da Faixa de Opções

O método IUIRibbon::LoadSettingsFromStream é usado para recuperar as informações de estado persistentes da faixa de opções armazenadas como um objeto IStream pelo método IUIRibbon::SaveSettingsToStream . As informações no objeto IStream são aplicadas à interface do usuário da faixa de opções quando o aplicativo é inicializado.

O exemplo a seguir demonstra o código básico necessário para carregar o estado da faixa de opções de um objeto IStream com o método IUIRibbon::LoadSettingsFromStream .

// pRibbon       - Pointer to the IUIRibbon interface
// pStatusStream - Pointer to the IStream object that contains the Ribbon state information
HRESULT CApplication::LoadRibbonStatusFromStream(
                        __in IUIRibbon *pRibbon, 
                        __in IStream *pStatusStream)
{     
  HRESULT hr = E_FAIL;
  if (pStatusStream)
  {
    // Set the stream position to the beginning first.
    LARGE_INTEGER liStart = {0, 0};
    ULARGE_INTEGER ulActual;
    pStatusStream->Seek(liStart, STREAM_SEEK_SET, &ulActual);
    hr = pRibbon->LoadSettingsFromStream(pStatusStream);
  }
  return hr;
}

Para obter um desempenho ideal, o método IUIRibbon::LoadSettingsFromStream deve ser chamado da função de retorno de chamada IUIApplication::OnViewChanged durante a fase de inicialização da estrutura, conforme mostrado no exemplo a seguir.

IFACEMETHODIMP CMyRibbonApplication::OnViewChanged(
                                       UINT nViewID, 
                                       __in UI_VIEWTYPE typeID, 
                                       __in IUnknown* pView, 
                                       UI_VIEWVERB verb, 
                                       INT iReasonCode)
{
  HRESULT hr = E_NOTIMPL;
  if (UI_VIEWVERB_CREATE == verb)
  {
    IUIRibbon* pRibbon = NULL;
    hr = pView->QueryInterface(IID_PPV_ARGS(&pRibbon));

    if (SUCCEEDED(hr))
    {
      hr = _LoadRibbonSettings(pRibbon);
      pRibbon->Release();
    }
  }
  return hr;
}

HRESULT CMyRibbonApplication::_LoadRibbonSettings(IUIRibbon* pRibbon)
{
  ...
  pRibbon->LoadSettingsFromStream(pStream);
  ...
}

Várias instâncias do mesmo aplicativo de estrutura da Faixa de Opções podem gerenciar cada estado de faixa de opções independentemente de objetos IStream separados ou como um grupo por meio de um único objeto IStream.

Ao sincronizar o estado da faixa de opções em um grupo de instâncias de aplicativo, cada janela de nível superior deve escutar uma notificação de WM_ACTIVATE . A janela de nível superior que está sendo desativada salva seu estado de faixa de opções usando o método IUIRibbon::SaveSettingsToStream e a janela de nível superior que está sendo ativada carrega seu estado de faixa de opções usando o método IUIRibbon::LoadSettingsFromStream .

Tópicos relacionados

Barra de Ferramentas de Acesso Rápido