Interfaces da caixa de diálogo Arquivo Rápido (OneNote)

Este tópico descreve as interfaces que você pode usar para personalizar programaticamente a caixa de diálogo Arquivo Rápido no OneNote 2013.

Caixa de diálogo Arquivo Rápido

A caixa de diálogo Arquivo Rápido no OneNote 2013 é uma caixa de diálogo personalizável que permite que os usuários selecionem um local dentro da estrutura de hierarquia do OneNote. Os locais selecionáveis incluem blocos de anotações, grupos de seções, seções, páginas e sub-páginas. A caixa de diálogo é usada tanto no aplicativo OneNote quanto por aplicativos externos por meio da API do OneNote 2013. A Figura 1 mostra a caixa de diálogo Arquivo Rápido em seu estado padrão.

Figura 1. Quick Filing dialog box without customizations

Na caixa de diálogo, os usuários podem navegar pela hierarquia Todos os Notebooks para procurar locais específicos ou pesquisar a estrutura da árvore do OneNote digitando na caixa de texto. Os aspectos da caixa de diálogo que podem ser personalizados incluem o título, a descrição, a lista de resultados recentes, marcar texto e estado da caixa, profundidade da árvore, botões e tipos de localização selecionáveis.

Você pode acessar a funcionalidade da caixa de diálogo Arquivo Rápido por meio de duas interfaces do OneNote 2013. A interface IQuickFilingDialog permite que os usuários instanciem, configurem e executem a caixa de diálogo. A interface IQuickFilingDialogCallback é chamada depois que a caixa de diálogo é fechada. A caixa de diálogo é executada no processo do OneNote, portanto, um mecanismo é necessário para manter o thread da caixa de diálogo em execução e, em seguida, capturar a seleção do usuário e o estado da caixa de diálogo quando ela estiver fechada.

Interface IQuickFilingDialog

Essa interface permite que o usuário personalize e execute a caixa de diálogo. O usuário pode instanciar uma caixa de diálogo por meio da classe Aplicativo usando o método Application.QuickFilingDialog . O método retorna uma instância da caixa de diálogo. Depois que as propriedades da caixa de diálogo são definidas, o método IQuickFilingDialog.Run é usado para executar a caixa de diálogo. Esse método executa a caixa de diálogo em um novo thread.

Propriedades

Nome	Tipo	Descrição
Título	string	Obtém ou define o texto do título que aparece na barra de título da janela da caixa de diálogo.
Descrição	string	Obtém ou define a descrição do texto para instruir o usuário sobre o que selecionar. Esse valor pode ser um texto de várias linhas.
Checkboxtext	string	Obtém ou define o texto que segue a caixa marcar. Se esse valor for definido como uma cadeia de caracteres não vazia, uma caixa de marcar será exibida na caixa de diálogo. Se o valor for uma cadeia de caracteres vazia, nenhuma caixa de marcar será exibida.
Checkboxstate	bool	Obtém ou define o estado da caixa marcar. Se o valor for definido como false, a caixa de marcar será desmarcada quando a caixa de diálogo for iniciada. Se o valor for definido como true, a caixa de marcar será selecionada quando a caixa de diálogo for iniciada, desde que CheckboxText seja uma cadeia de caracteres não vazia.
WindowHandle	ULong	Obtém a ID do identificador da janela da caixa de diálogo Arquivo Rápido.
TreeDepth	HierarchyElement	Obtém ou define o quão profunda a árvore do OneNote deve ser exibida na seção Todos os Notebooks. Por padrão, a árvore é exibida até as seções. Essa propriedade não afeta que tipo de elementos podem ser selecionados. Se TreeDepth for definido como um elemento mais baixo na hierarquia do OneNote do que pode ser selecionado por qualquer um dos botões, a profundidade da árvore exibida será o elemento selecionável mais baixo possível. Ou seja, se a profundidade da árvore estiver definida para ser exibida em páginas, mas o elemento selecionável mais baixo for uma seção, a árvore será exibida até seções.
ParentWindowHandle	ULong	Obtém ou define a ID do identificador da janela pai da caixa de diálogo. Se essa propriedade estiver definida, a caixa de diálogo Arquivo Rápido será modal para a janela pai atribuída quando a caixa de diálogo for aberta. Ou seja, um usuário não poderá acessar a janela pai até que a caixa de diálogo Arquivo Rápido seja fechada.
Posição	tagPOINT	Obtém ou define a posição da janela em relação à tela. Por padrão, a caixa de diálogo é exibida no meio da janela pai ou da área de trabalho.
SelectedItem	string	Obtém a ID do objeto do local do OneNote selecionado pelo usuário quando a caixa de diálogo é fechada. Se o usuário clicar no botão Cancelar , o objeto será definido como nulo.
PressedButton	ULong	Obtém qual botão foi clicado quando a caixa de diálogo foi fechada. Se o botão Cancelar tiver sido clicado, essa propriedade retornará um valor de -1. Todos os outros botões são atribuídos valores inteiros de 0, incrementados por 1 para cada botão adicionado à caixa de diálogo. O valor inteiro do botão OK padrão é 0.

Métodos

SetRecentResults

Valor	Descrição
Descrição	Define qual lista de resultados recente será exibida na caixa de diálogo Arquivo Rápido e indica se deve incluir alguns locais de arquivamento especiais na lista. Os usuários podem selecionar uma lista de resultados recente na enumeração RecentResultType . Os usuários também podem optar por adicionar as seguintes opções à lista: Seção Atual, Página Atual ou Anotações Não Arquivadas. Se RecentResultType.rrtNone estiver selecionado, nenhuma lista de resultados recente será mostrada.
Sintaxe	HRESULT SetRecentResults ( [in]RecentResultType recentResults, [in]VARIANT_BOOL fShowCurrentSection, [in]VARIANT_BOOL fShowCurrentPage, [in]VARIANT_BOOL fShowUnfiledNotes);
Parâmetros	recentResults – Um objeto do tipo RecentResultType que indica qual lista de resultados recente, se houver, deve ser exibida. Se rrtNone estiver selecionado, nenhuma lista de resultados recente será exibida na caixa de diálogo. fShowCurrentSection – um valor booliano que indica se a seção atual deve ser incluída na lista de resultados recentes. fShowCurrentPage – um valor booliano que indica se a página atual deve ser incluída na lista de resultados recentes. fShowUnfiledNotes – um valor booliano que indica se a seção Notas Não arquivadas deve ser incluída na lista de resultados recentes.

Observação

Se um local de arquivamento especial não puder ser selecionado usando qualquer um dos botões na caixa de diálogo, ele não será mostrado na lista. Se nenhum item selecionável na lista de resultados recentes for encontrado, nenhuma lista de resultados recente será exibida.

O exemplo a seguir usa o método SetRecentResults para exibir a seção atual, a página atual e a seção Notas Não arquivadas na lista de resultados recentes.

        static void Main(string[] args)
        {
            Microsoft.Office.Interop.OneNote.Application app = 
                new Microsoft.Office.Interop.OneNote.Application();
            ... 
            // RECENT RESULTS
            qfDialog.SetRecentResults(RecentResultType.rrtFiling,
                /*Current Section*/ true,
                /*Current Page*/ true,
                /*Unfiled Notes*/ true);
            ...
        }

Addbutton

Valor	Descrição
Descrição	Permite que os usuários adicionem e personalizem botões na caixa de diálogo. Os usuários podem especificar o texto nos botões e quais elementos da hierarquia do OneNote podem ser selecionados por cada botão.
Sintaxe	HRESULT AddButton ( [in]BSTR bstrText, [in]HierarchyElement allowedElements, [in]HierarchyElement allowedReadOnlyElements, [in]VARIANT_BOOL fDefault);
Parâmetros	bstrText – Uma cadeia de caracteres que especifica o texto a ser exibido no botão. Para personalizar o botão OK padrão, passe um valor nulo como bstrText. allowedElements – Um HierarchyElement que indica quais elementos de hierarquia do OneNote não lidos um usuário pode selecionar usando o botão. Para selecionar vários itens, o usuário deve passar o operador OR para todos os valores equivalentes uint dos tipos HierarchyElement permitidos como HierarchyElement. allowedReadOnlyElements – Um HierarchyElement que indica quais elementos de hierarquia somente leitura do OneNote um usuário pode selecionar usando o botão. Para selecionar vários itens, o usuário deve passar o operador OR para todos os valores equivalentes uint dos tipos HierarchyElement permitidos como HierarchyElement. fDefault – um valor booliano que especifica se esse botão deve ser o botão padrão. Se vários botões forem definidos como padrão, o último botão especificado se tornará o botão padrão.

O exemplo a seguir adiciona três botões à caixa de diálogo Arquivo Rápido. O primeiro, All, pode ser selecionado por todos os elementos na árvore de hierarquia do OneNote. Os outros, Notebooks e Páginas, só poderão ser selecionados se seus elementos correspondentes, Notebooks e Páginas, forem selecionados.

        static void Main(string[] args)
        {
            Microsoft.Office.Interop.OneNote.Application app = 
                new Microsoft.Office.Interop.OneNote.Application();
            ... 
            
            // BUTTONS
            HierarchyElement heAll = (HierarchyElement) 
                ((uint)HierarchyElement.heNotebooks | 
                (uint)HierarchyElement.heSectionGroups | 
                (uint)HierarchyElement.heSections |  
                (uint)HierarchyElement.hePages);
            
            qfDialog.AddButton("All", heAll, heAll, true);
            qfDialog.AddButton("Notebooks", HierarchyElement.heNotebooks, 
                HierarchyElement.heNotebooks, false);
            qfDialog.AddButton("Pages", HierarchyElement.hePages, 
                HierarchyElement.hePages, false);
            ... 
        }

Run

Valor	Descrição
Descrição	Exibe a caixa de diálogo Arquivo Rápido de um novo thread. Ele usa uma referência à interface IQuickFilingDialogCallback , cujo método OnDialogClosed será chamado assim que a caixa de diálogo for fechada.
Sintaxe	HRESULT Run ( [in]IQuickFilingDialogCallback piCallback);
Parâmetros	piCallback – uma referência à interface IQuickFilingDialogCallback que será instanciada quando a caixa de diálogo for fechada.

O exemplo a seguir usa o método Executar para exibir a caixa de diálogo Arquivo Rápido de um novo thread.

    class OpenQuickFilingDialog
    {
            ... 
        static void Main(string[] args)
        {
            Microsoft.Office.Interop.OneNote.Application app = 
                new Microsoft.Office.Interop.OneNote.Application();
            ... 
            // Display Quick Filing UI
            qfDialog.Run(new Callback());
            ... 
        }
    }

TreeCollapsedState

Valor	Descrição
Descrição	Indica se a árvore de hierarquia deve ser expandida ou recolhida.
Sintaxe	HRESULT TreeCollapsedState( [in] TreeCollapsedStateType tcs);
Parâmetros	tcs – especifica se a árvore foi expandida ou recolhida.

NotebookFilterOut

Valor	Descrição
Descrição	Filtra a lista de blocos de anotações mostrados por tipo.
Sintaxe	HRESULT NotebookFilterOut( [in] NotebookFilterOutType nfo);
Parâmetros	nfo – especifica o conjunto de blocos de anotações que devem ser filtrados para fora da lista

ShowCreateNewNotebook

Valor	Descrição
Descrição	Exibe a opção criar um novo notebook na caixa de diálogo.
Sintaxe	HRESULT ShowCreateNewNotebook ();
Parâmetros	Nenhum

AddInitialEditor

Valor	Descrição
Descrição	Adiciona um usuário como editor inicial a um notebook na caixa de diálogo Arquivo Rápido.
Sintaxe	HRESULT AddInitialEditor (BSTR initialEditor);
Parâmetros	initialEditor – O endereço de email do usuário que você deseja adicionar como editor ao notebook. Quando o notebook é criado por meio da caixa de diálogo Arquivo Rápido, ele é compartilhado automaticamente com todos os Editores Iniciais.

ClearInitialEditors

Valor	Descrição
Descrição	Remove todos os editores iniciais da caixa de diálogo Arquivo Rápido.
Sintaxe	HRESULT ClearInitialEditors ();
Parâmetros	Nenhum

ShowSharingHyperlink

Valor	Descrição
Descrição	Exibe o Hiperlink do Tópico de Ajuda de Compartilhamento na caixa de diálogo Arquivo Rápido.
Sintaxe	HRESULT ShowSharingHyperlink();
Parâmetros	Nenhum

Interface IQuickFilingDialogCallback

Essa interface permite que o usuário acesse as propriedades da caixa de diálogo após o fechamento da caixa de diálogo. Quando a caixa de diálogo for fechada, o OneNote 2013 chamará o método IQuickFilingDialogCallback.OnDialogClose nesta interface.

Uma classe que herda essa interface precisa ser definida.

Métodos

A seção a seguir descreve os métodos associados às interfaces detalhadas anteriormente.

OnDialogClosed

Valor	Descrição
Descrição	Permite que os usuários adicionem funcionalidade para capturar e usar a seleção do usuário na caixa de diálogo. Esse método é chamado depois que a caixa de diálogo Arquivo Rápido é fechada. Esse método é uma função que as interfaces IQuickFilingDialogCallback precisam definir.
Sintaxe	HRESULT OnDialogClosed ( [in]IQuickFilingDialog dialog);
Parâmetros	caixa de diálogo – o objeto IQuickFilingDialog que chamou o método OnDialogClose .

O exemplo a seguir é uma interface IQuickFilingDialogCallback de exemplo. O método OnDialogClose imprime a seleção do usuário da caixa de diálogo Arquivo Rápido para o console.

    class Callback : IQuickFilingDialogCallback
    {
        public Callback(){}
        public void OnDialogClosed(IQuickFilingDialog qfDialog)
        {
            Console.WriteLine(qfDialog.SelectedItem);
            Console.WriteLine(qfDialog.PressedButton);
            Console.WriteLine(qfDialog.CheckboxState);
        }
    }

Exemplo

O exemplo de código a seguir abre uma caixa de diálogo Arquivo Rápido que tem um título personalizado, descrição, lista de resultados recente, profundidade da árvore, marcar caixa e botões. O item selecionado do usuário, o botão pressionado e o estado da caixa de marcar serão exibidos em uma janela do console quando a caixa de diálogo for fechada. Para ver o botão de página habilitado, o usuário terá que pesquisar uma página e selecioná-la, pois a profundidade da árvore é definida como seções. A caixa de diálogo não é filho de nenhuma janela.

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.Threading;
using Microsoft.Office.Interop.OneNote;
namespace SampleQFD
{
    class OpenQuickFilingDialog
    {
        private static EventWaitHandle wh = new AutoResetEvent(false);
        private static IQuickFilingDialog qfDialog;
        private static String strTitle = "Sample Title";
        private static String strDescription = "Sample Description";
        private static String strCheckboxText = "Sample Checkbox";
        static void Main(string[] args)
        {
            Microsoft.Office.Interop.OneNote.Application app = 
                new Microsoft.Office.Interop.OneNote.Application();
            // Instantiate Quick Filing UI
            qfDialog = app.QuickFiling();
            #region//SET API PARAMETERS
            // TITLE
            qfDialog.Title = strTitle;
            // DESCRIPTION
            qfDialog.Description = strDescription;
            // RECENT RESULTS
            qfDialog.SetRecentResults(RecentResultType.rrtFiling,
                /*Current Section*/ true,
                /*Current Page*/ true,
                /*Unfiled Notes*/ true);
            // TREE DEPTH
            qfDialog.TreeDepth = HierarchyElement.heSections;
            // CHECKBOX
            qfDialog.CheckboxText = strCheckboxText;
            qfDialog.CheckboxState = false;
            // BUTTONS
            HierarchyElement heAll = (HierarchyElement) 
                ((uint)HierarchyElement.heNotebooks | 
                (uint)HierarchyElement.heSectionGroups | 
                (uint)HierarchyElement.heSections |  
                (uint)HierarchyElement.hePages);
            
            qfDialog.AddButton("All", heAll, heAll, true);
            qfDialog.AddButton("Notebooks", HierarchyElement.heNotebooks, 
                HierarchyElement.heNotebooks, false);
            qfDialog.AddButton("Pages", HierarchyElement.hePages, 
                HierarchyElement.hePages, false);
            // PARENTWINDOW
            #endregion
            // Display Quick Filing UI
            qfDialog.Run(new Callback());
            // Clean up and Wait so console window does not close
            qfDialog = null;
            wh.WaitOne();
        }
    }
    class Callback : IQuickFilingDialogCallback
    {
        public Callback(){}
        public void OnDialogClosed(IQuickFilingDialog qfDialog)
        {
            Console.WriteLine(qfDialog.SelectedItem);
            Console.WriteLine(qfDialog.PressedButton);
            Console.WriteLine(qfDialog.CheckboxState);
        }
    }
}

Confira também

• Referência do desenvolvedor do OneNote