OneNote) (快速歸檔對話框介面

發行項
03/18/2024

本主題描述您可以用來以程序設計方式自定義 OneNote 2013 中 [快速歸檔] 對話框的介面。

[快速歸檔] 對話框

OneNote 2013 中的 [快速歸檔] 對話框是可自定義的對話框，可讓用戶選取 OneNote 階層結構內的位置。可選取的位置包括筆記本、區段群組、區段、頁面和子頁面。對話框會透過 OneNote 2013 API 在 OneNote 應用程式內和外部應用程式中使用。圖 1 顯示 [快速歸檔] 對話框的預設狀態。

圖 1： Quick Filing dialog box without customizations

沒有自訂的 [快速歸檔]

在對話框中，用戶可以流覽 [所有筆記本] 階層來尋找特定位置，或在文本框中輸入來搜尋 OneNote 樹狀結構。可自定義的對話框層面包括標題、描述、最近的結果清單、複選框文字和狀態、樹狀結構深度、按鈕，以及可選取的位置類型。

您可以透過兩個 OneNote 2013 介面來存取 [快速歸檔] 對話框功能。 IQuickFilingDialog 介面可讓使用者具現化、設定及執行對話框。關閉對話框之後，會呼叫 IQuickFilingDialogCallback 介面。對話框是在 OneNote 進程中執行，因此需要一個機制來讓對話框的線程保持執行，然後在關閉對話框時擷取使用者的選取範圍和對話框的狀態。

IQuickFilingDialog 介面

此介面可讓使用者自定義及執行對話框。使用者可以使用Application.QuickFilingDialog方法，透過Application類別具現化對話框。方法會傳回對話框的實例。設定對話框的屬性之後， 就會使用 IQuickFilingDialog.Run 方法來執行對話方塊。這個方法會在新的線程上執行對話框。

屬性

名稱	類型	描述
Title	字串	取得或設定出現在對話框視窗標題列中的標題文字。
描述	字串	取得或設定文字描述，以指示用戶要選取的專案。此值可以是多行文字。
CheckboxText	字串	取得或設定複選框後面的文字。如果此值設定為非空字串，對話框中會出現複選框。如果值是空字串，則不會出現任何複選框。
CheckboxState	bool	取得或設定複選框的狀態。如果值設定為 false，則會在對話框啟動時清除複選框。如果值設定為 true，只要 CheckboxText 是非空字串，對話框啟動時就會選取複選框。
WindowHandle	ulong	取得 [快速歸檔] 對話框視窗的句柄標識碼。
TreeDepth	HierarchyElement	取得或設定 OneNote 樹狀結構在 [所有筆記本] 區段中的顯示深度。根據預設，樹狀結構會顯示到區段。這個屬性不會影響可以選取的項目類型。如果 TreeDepth 設定為 OneNote 階層中低於任何按鈕可選取的專案，則顯示的樹狀結構深度會是最低的可選取專案。也就是說，如果樹狀結構深度設定為向下顯示為頁面，但可選取的最低元素是區段，則樹狀結構會向下顯示為區段。
ParentWindowHandle	ulong	取得或設定對話框之父視窗的句柄標識碼。如果設定此屬性，則對話框開啟時，[快速歸檔] 對話框將會強制回應指派的父視窗。也就是說，在 [快速歸檔] 對話框關閉之前，用戶將無法存取父視窗。
位置	tagPOINT	取得或設定視窗相對於螢幕的位置。根據預設，對話框會出現在父視窗或桌面的中間。
SelectedItem	字串	取得關閉對話框時，用戶所選取 OneNote 位置的物件識別碼。如果使用者按兩下 [ 取消 ] 按鈕，則對象會設定為 Null。
PressedButton	ulong	取得關閉對話框時所按的按鈕。如果按下 [ 取消 ] 按鈕，此屬性會傳回 -1 的值。所有其他按鈕都會從 0 指派整數值，每個新增至對話框的按鈕都會遞增 1。預設 [ 確定 ] 按鈕的整數值為 0。

方法

SetRecentResults

值	描述
描述	設定 [快速歸檔] 對話框中會顯示的最近結果清單，並指出是否要在清單中包含一些特殊的檔案位置。用戶可以從 RecentResultType 列舉中選取最近的結果清單。使用者也可以選擇將下列選項新增至清單：目前區段、目前頁面或未填入的附註。如果選取 RecentResultType.rrtNone ，就不會顯示最近的結果清單。
語法	`HRESULT SetRecentResults (` `[in]RecentResultType recentResults,` `[in]VARIANT_BOOL fShowCurrentSection,` `[in]VARIANT_BOOL fShowCurrentPage,` `[in]VARIANT_BOOL fShowUnfiledNotes);`
參數	recentResults – RecentResultType 類型的物件，指出應該出現哪一個最近的結果清單。如果選取 rrtNone ，對話框中就不會出現最近的結果清單。 fShowCurrentSection – 布爾值，指出目前區段是否應該包含在最近的結果清單中。 fShowCurrentPage – 布爾值，指出目前頁面是否應該包含在最近的結果清單中。 fShowUnfiledNotes – 布爾值，指出 [未填入的附注] 區段是否應該包含在最近的結果清單中。

注意事項

如果無法使用對話框中的任何按鈕來選取特殊檔案位置，就不會顯示在清單中。如果在最近的結果清單中找不到可選取的專案，就不會顯示最近的結果清單。

下列範例會使用 SetRecentResults 方法，以顯示最近結果清單中的目前區段、目前頁面和 Unfiled Notes 區段。

        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

值	描述
描述	允許使用者在對話框中新增和自定義按鈕。用戶可以指定按鈕上的文字，以及每個按鈕可以選取 OneNote 階層的哪些元素。
語法	`HRESULT AddButton (` `[in]BSTR bstrText,` `[in]HierarchyElement allowedElements,` `[in]HierarchyElement allowedReadOnlyElements,` `[in]VARIANT_BOOL fDefault);`
參數	bstrText – 字串，指定要出現在按鈕上的文字。若要自定義預設的 [確定] 按鈕，請將 null 值傳入為 bstrText。 allowedElements – HierarchyElement ，指出使用者可以使用按鈕選取的非只讀 OneNote 階層元素。若要選取多個專案，用戶應該傳入 OR 運算符，以取得允許做為 HierarchyElement 之 HierarchyElement 類型的所有 uint 對等值。 allowedReadOnlyElements – HierarchyElement ，指出使用者可以使用按鈕選取的 OneNote 只讀階層元素。若要選取多個專案，用戶應該針對允許做為HierarchyElement之HierarchyElement類型的所有 uint 對等值傳入 OR 運算符。 fDefault – 布爾值，指定此按鈕是否應為預設按鈕。如果將多個按鈕設定為預設值，最後一個指定的按鈕會變成預設按鈕。

下列範例會在 [快速歸檔] 對話框中新增三個按鈕。 OneNote 階層樹狀結構中的所有元素都可以選取第一個 [ 全部]。只有在選取其他 筆記本 和頁面的對應元素時，才能選取其他專案 Notebook 和 Pages。

        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

值	描述
描述	顯示新線程中的 [快速歸檔] 對話框。它會參考 IQuickFilingDialogCallback 介面，其 OnDialogClosed 方法會在對話框關閉後呼叫。
語法	`HRESULT Run (` `[in]IQuickFilingDialogCallback piCallback);`
參數	piCallback – IQuickFilingDialogCallback 介面的參考，將在對話框關閉後具現化。

下列範例會使用 Run 方法來顯示新線程中的 [快速歸檔] 對話方塊。

    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

值	描述
描述	指出階層樹狀結構應該展開或折疊。
語法	`HRESULT TreeCollapsedState(` `[in] TreeCollapsedStateType tcs);`
參數	tcs - 指定樹狀結構是展開還是折疊。

NotebookFilterOut

值	描述
描述	篩選依類型顯示的筆記本清單。
語法	`HRESULT NotebookFilterOut(` `[in] NotebookFilterOutType nfo);`
參數	nfo - 指定要篩選出列表的筆記本集合

ShowCreateNewNotebook

值	描述
描述	在對話框中顯示 [建立新的筆記本] 選項。
語法	`HRESULT ShowCreateNewNotebook ();`
參數	無

AddInitialEditor

值	描述
描述	在 [快速歸檔] 對話框中，將使用者新增為筆記本的初始編輯器。
語法	`HRESULT AddInitialEditor (BSTR initialEditor);`
參數	initialEditor - 您想要新增為筆記本編輯器之使用者的電子郵件位址。透過 [快速歸檔] 對話框建立筆記本時，會自動與所有初始編輯器共用。

ClearInitialEditors

值	描述
描述	從 [快速歸檔] 對話框中移除所有初始編輯器。
語法	`HRESULT ClearInitialEditors ();`
參數	無

ShowSharingHyperlink

值	描述
描述	在 [快速歸檔] 對話框中顯示 [共享説明主題超連結]。
語法	`HRESULT ShowSharingHyperlink();`
參數	無

IQuickFilingDialogCallback 介面

這個介面可讓使用者在對話框關閉之後存取對話框屬性。對話框關閉后，OneNote 2013 會在此介面中呼叫 IQuickFilingDialogCallback.OnDialogClose 方法。

必須定義繼承這個介面的類別。

方法

下一節描述與先前詳述之介面相關聯的方法。

OnDialogClosed

值	描述
描述	可讓使用者新增功能，以擷取並使用對話框中的用戶選取專案。這個方法會在 [快速歸檔] 對話框關閉之後呼叫。這個方法是 IQuickFilingDialogCallback 介面必須定義的函式。
語法	`HRESULT OnDialogClosed (` `[in]IQuickFilingDialog dialog);`
參數	dialog – 呼叫 OnDialogClose 方法的 IQuickFilingDialog 物件。

下列範例是 範例 IQuickFilingDialogCallback 介面。 OnDialogClose 方法會將使用者從 [快速歸檔] 對話框中選取的專案列印到控制台。

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

範例

下列程式代碼範例會開啟具有自定義標題、描述、最近的結果清單、樹狀結構深度、複選框和按鈕的 [快速歸檔] 對話框。當對話框關閉時，控制台視窗中會顯示用戶選取的專案、按下按鈕和複選框狀態。若要查看已啟用的頁面按鈕，用戶必須搜尋頁面並加以選取，因為樹狀結構深度會設定為區段。對話框不是任何視窗的子系。

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);
        }
    }
}

另請參閱

OneNote 開發人員參考

共用方式為

OneNote) (快速歸檔對話框介面

[快速歸檔] 對話框

IQuickFilingDialog 介面

屬性

方法

IQuickFilingDialogCallback 介面

方法

範例

另請參閱

意見反應

其他資源