Application Interface (OneNote 2010)
The Application interface includes methods help retrieve, manipulate, and update OneNote information and content. The methods are in four general categories:
Notebook structure—Methods for working with notebook structure, including those for discovering, opening, modifying, closing, and deleting notebooks, section groups, and sections.
Page content—Methods for working with pages and page content, including those for discovering, modifying, saving, and deleting page content. Page content includes binary objects, such as ink and images, and text objects, such as outlines.
Navigation—Methods for finding, linking to, and navigating to pages and objects.
Functional—All other methods that perform certain actions or set parameters in OneNote.
In addition, the Application interface includes a number of properties and events.
Notebook Structure Methods
The methods described in this section enable you to discover, open, modify, close, and delete OneNote notebooks, section groups, and sections.
GetHierarchy Method
Description |
Gets the notebook node hierarchy structure, starting from the node you specify (all notebooks or a single notebook, section group, or section), and extending downward to all descendants at the level you specify. |
Syntax |
HRESULT GetHierarchy( |
Parameters |
|
The GetHierarchy method returns a string in OneNote 2010 XML format by default, or you can set the preferred XML schema version by using the optional xsSchema parameter.
Depending on the parameters you pass, the GetHierarchy method can return various lists (for example all notebooks, all sections in all notebooks, all pages within a given section, or all pages within a given notebook). For each node, the XML string returned provides properties (for example, the section or page title, ID, and last-modified time).
Not all combinations of start node and scope are valid. For example, if you specify a section start node and a notebook scope, GetHierarchy returns a null result because a notebook is higher in the node hierarchy than a section.
The following C# example shows how to use the GetHierarchy method to get the entire OneNote hierarchy, including all notebooks, down to the page level. It copies the output string to the Clipboard, from which you can paste the string into a text editor for review.
static void GetEntireHierarchy()
{
String strXML;
OneNote.Application onApplication = new OneNote.Application();
onApplication.GetHierarchy(null,
OneNote.HierarchyScope.hsPages, out strXML);
Clipboard.SetText(strXML);
MessageBox.Show("The XML has been copied to the clipboard");
}
UpdateHierarchy Method
Description |
Modifies or updates the hierarchy of notebooks. For example, you can add sections or section groups to a notebook, add a new notebook, move sections within a notebook, change the name of a section, add pages to a section, or change the order of pages within sections. |
Syntax |
HRESULT UpdateHierarchy( |
Parameters |
|
If you pass only a partial OneNote XML string for the bstrChangesXmlIn parameter, OneNote attempts to infer the changes you want. For example, if you include a Notebook element that contains only one section, OneNote adds the section after any existing sections. However, if the operation you specify is ambiguous, the result can be hard to determine. For example, if an existing notebook contains four sections, and the XML string you pass includes the notebook and only the fourth and first sections (in that order), OneNote might place the second and third sections before the fourth section or after the first section.
You cannot use the UpdateHierarchy method to delete part of a notebook. That is, passing an XML string that includes only part of an existing hierarchy does not delete sections that are not included in the string. To delete part of a hierarchy, use the DeleteHierarchy method.
The following C# code shows one way to use the UpdateHierarchy method to change the OneNote hierarchy, by changing the name of an existing section. It reads XML code from a sample file named ChangeSectionName.xml at the root of drive C, loads it into an XML document, and then passes the XML structure of that document to the method.
static void UpdateExistingHierarchy()
{
OneNote.Application onApplication = new OneNote.Application();
// Get the XML from the file.
XmlTextReader reader = new XmlTextReader("C:\\ChangeSectionName.xml");
reader.WhitespaceHandling = WhitespaceHandling.None;
XmlDocument xmlDocIn = new XmlDocument();
xmlDocIn.Load(reader);
// Update the hierarchy.
onApplication.UpdateHierarchy(xmlDocIn.OuterXml,
OneNote.XMLSchema.xs2007);
}
The following XML code is an excerpt of the ChangeSectionName.xml file that the previous C# code passes to the method. When the XML is passed to the UpdateHierarchy method, it changes the name of one of the sections in the existing hierarchy (by changing the value of the name attribute to "My Renamed Section"). It then removes all the sections except the one whose name was changed. In addition, the code removes unnecessary attributes from the target Section element, including the lastModifiedTime, isCurrentlyViewed, and color attributes, leaving only the name, ID, and path attributes intact.
<?xml version="1.0" ?>
<one:Notebooks xmlns:one="https://schemas.microsoft.com/office/onenote/12/2004/onenote">
<one:Notebook name="My Notebook" nickname="My Notebook" ID="{0B8E7305-AC2C-4BCB-8651-1CDA55AAE14C}{1}{B0}">
<one:Section name="My Renamed Section" ID="{5F4E2908-44BA-4C02-91FE-49FC665E9A33}{1}{B0}" path="C:\My Section.one" />
</one:Notebook>
</one:Notebooks>
The preceding XML code was obtained by using the code shown in the example for the GetHierarchy method, which is modified, as follows, to limit the scope to sections.
static void GetAllSections()
{
String strXML;
OneNote.Application onApplication = new OneNote.Application();
onApplication.GetHierarchy(System.String.Empty,
OneNote.HierarchyScope.hsSections, out strXML);
Clipboard.SetText(strXML.ToString());
MessageBox.Show("The XML has been copied to the Clipboard");
}
The following C# example shows a complete console application that searches for a section named "Sample_Section", prompts the user to input a new name for the section, and then uses the UpdateHierarchy method to change the section name to the name that the user typed. Before running the code, change "Sample_Section" to the name of a section that exists in your OneNote hierarchy.
static void Main(string[] args)
{
// OneNote 2010 Schema namespace.
string strNamespace = "https://schemas.microsoft.com/office/onenote/2010/onenote";
string outputXML;
Application onApplication = new Application();
onApplication.GetHierarchy(null, HierarchyScope.hsSections, out outputXML);
// Load a new XmlDocument.
XmlDocument xmlDoc = new XmlDocument();
xmlDoc.LoadXml(outputXML);
XmlNamespaceManager nsmgr = new XmlNamespaceManager(xmlDoc.NameTable);
nsmgr.AddNamespace("one", strNamespace);
// Search for the section named "Sample_Section".
XmlNode xmlNode = xmlDoc.SelectSingleNode("//one:Section[@name='Sample_Section']", nsmgr);
// Prompt for a new section title.
System.Console.Write("Please enter a new title for the section: ");
string input = System.Console.ReadLine();
xmlNode.Attributes["name"].Value = input;
// Update the section with the new title.
onApp.UpdateHierarchy(xmlNode.OuterXml);
System.Console.Write("Done!\n");
}
OpenHierarchy Method
Description |
Opens a section group or section that you specify. |
Syntax |
HRESULT OpenHierarchy( |
Parameters |
|
If you specify a section group that is not in an open notebook, the OpenHierarchy method opens the section group as a notebook. If you specify a section that is not in an open notebook, the OpenHierarchy method opens the section in the Recent Opened Sections section group. If you specify a section group or section that is already in an open notebook, nothing happens because the section group or section is already open, as well. In any case, OpenHierarchy returns the object ID for the section group, notebook, or section that you specify, so that you can use it in other operations.
You can also use the OpenHierarchy method to create new sections, instead of doing so by importing XML.
The following code shows how to use the OpenHierarchy method to open the Meetings section in the Work notebook and get the ID for the section. If the section does not already exist, OneNote creates it in the location that you specify.
static void OpenSection()
{
String strID;
OneNote.Application onApplication = new OneNote.Application();
onApplication.OpenHierarchy("C:\\Documents and Settings\\user\\My Documents\\OneNote Notebooks\\Work\\Meetings.one",
System.String.Empty, out strID, OneNote.CreateFileType.cftSection);
}
DeleteHierarchy Method
Description |
Deletes any hierarchy object (a section group, section, or page) from the OneNote notebook hierarchy. |
Syntax |
HRESULT DeleteHierarchy( |
Parameters |
|
CreateNewPage Method
Description |
Adds a new page to the section you specify. The new page is added as the last page of the section |
Syntax |
HRESULT CreateNewPage( |
Parameters |
|
The OneNote API includes the CreateNewPage method as a convenience. You can achieve the same result, with greater control over how the new page is positioned in the hierarchy, by calling the UpdateHierarchy method. The UpdateHierarchy method also lets you create subpages at the same time as you create a new page.
CloseNotebook Method
Description |
Closes the specified notebook. |
Syntax |
HRESULT CloseNotebook( |
Parameters |
|
You can use the CloseNotebook method to close the notebook you specify. When you call this method, OneNote synchronizes any offline files with current notebook content, if necessary, and then closes the specified notebook. After the method returns, the notebook no longer appears in the list of open notebooks in the OneNote user interface (UI).
GetHierarchyParent Method
Description |
Gets the OneNote ID for the parent object of a OneNote object. |
Syntax |
HRESULT GetHierarchyParent ( |
Parameters |
|
If the OneNote object has no parent object (for example, when a user wants to get the parent of a Notebook), an exception is thrown.
GetSpecialLocation Method
Description |
Finds the path to the location where OneNote stores certain special items, such as backups, unfiled notes, and the default notebook. |
Syntax |
HRESULT GetSpecialLocation( |
Parameters |
|
You can use this method to determine the location on disk of the Unfiled Notes folder. That is the folder in which OneNote stores notes that are created when you drag an item into OneNote, as well as notes that come directly from other applications (such as those that result when you click Send to OneNote in Microsoft Outlook or Microsoft Internet Explorer).
Page Content Methods
The methods described in this section enable you to discover, update, and delete the content on pages in OneNote notebooks, as well as to publish OneNote content.
GetPageContent Method
Description |
Gets all of the content (in OneNote XML format) of the specified page. |
Syntax |
HRESULT GetPageContent( |
Parameters |
|
By default, to avoid excess length in the XML string it returns, OneNote does not embed binary content in the XML code. For the same reason, it does not mark up the current selection with selection attributes. Binary objects include a OneNote ID in their tags. To get a binary object, you call the GetBinaryPageContent method and pass it the OneNote ID you get from the GetPageContent method. You use the GetPageContent method when you do not need the binary data immediately.
UpdatePageContent Method
Description |
Updates or modifies the content on the page. |
Syntax |
HRESULT UpdatePageContent( |
Parameters |
|
You can use this method to modify the page in various ways. For example, you can use the UpdatePageContent method to add an outline to a page, change the content of an outline, add images, add ink, move content, or modify text in outlines.
As a more specific example, you might use the GetPageContent method to export an existing page, make some changes to the XML code for the page, and then use the UpdatePageContent method to import the entire page again. Or, you might use this method to add new page objects, such as images, to the bottom of an existing page.
The only objects that you must include in the XML code that you pass to the UpdatePageContent method are page-level objects (such as outlines, images on the page, or ink on the page) that have changed. This method does not modify or remove page-level objects that you do not specify in the bstrPageChangesXmlIn parameter. The method entirely replaces page-level objects, such as outlines, whose IDs match those of the objects you pass. Consequently, you must fully specify all page-level objects in your code, including their existing content and changes you want to make to them.
For example, if your page contains an outline and a background page image, you can replace the outline and leave the image unchanged by completely specifying the outline in the XML code, using the ID of the existing outline, and not including the image in the code. Because the revised outline you include in the code completely replaces the existing outline, you must include the entire contents of the outline.
Also, the UpdatePageContent method modifies only element properties that you specify in the bstrPageChangesXmlIn parameter. For example, if you specify some, but not all, properties of the PageSettings element, the properties that you do not specify remain unchanged.
The following example shows how to use the UpdatePageContent method to change the title of a page and add some sample text to the page. Before running the code, substitute a valid page ID for the page ID shown in the code, so that the code works on your computer. You can get the page ID for a page by using the GetHierarchy method and examining the output.
static void UpdatePageContent()
{
OneNote.Application onApplication = new OneNote.Application();
String strImportXML;
strImportXML = "<?xml version=\"1.0\"?>" +
"<one:Page xmlns:one=\"https://schemas.microsoft.com/office/onenote/12/2004/onenote\"
ID=\"{3428B7BB-EF39-4B9C-A167-3FAE20630C37}{1}{B0}\">" +
" <one:PageSettings RTL=\"false\" color=\"automatic\">" +
" <one:PageSize>" +
" <one:Automatic/>" +
" </one:PageSize>" +
" <one:RuleLines visible=\"false\"/>" +
" </one:PageSettings>" +
" <one:Title style=\"font-family:Calibri;
font-size:17.0pt\" lang=\"en-US\">" +
" <one:OE alignment=\"left\">" +
" <one:T>" +
" <![CDATA[My Sample Page]]>" +
" </one:T>" +
" </one:OE>" +
" </one:Title>" +
" <one:Outline >" +
" <one:Position x=\"120\" y=\"160\"/>" +
" <one:Size width=\"120\" height=\"15\"/>" +
" <one:OEChildren>" +
" <one:OE alignment=\"left\">" +
" <one:T>" +
" <![CDATA[Sample Text]]>" +
" </one:T>" +
" </one:OE>" +
" </one:OEChildren>" +
" </one:Outline>" +
"</one:Page>";
// Update the page content.
onApplication.UpdatePageContent(strImportXML, System.DateTime.MinValue);
}
GetBinaryPageContent Method
Description |
Returns a binary object, such as ink or images, on a OneNote page as a base-64-encoded string. |
Syntax |
HRESULT GetBinaryPageContent( |
Parameters |
|
DeletePageContent Method
Description |
Deletes an object—such as an Outline, Ink, or Image object—from a page. |
Syntax |
HRESULT DeletePageContent( |
Parameters |
|
Publish Method
Description |
Exports the page you specify to a file in any format that OneNote supports. |
Syntax |
HRESULT Publish( |
Parameters |
|
Currently, OneNote supports the following file formats:
MHTML files (.mht)
Adobe Acrobat PDF files (.pdf)
XML Paper Specification (XPS) files (.xps)
OneNote 2010 or 2007 files (.one)
OneNote Package files (.onepkg)
Microsoft Word documents (.doc or .docx)
Microsoft Windows Enhanced Metafiles (.emf)
HTML files (.html)
This method produces exactly the same results you would get by clicking Publish in the UI and specifying the format.
Navigation Methods
The methods described in this section enable you to find, navigate to, and link to OneNote notebooks, section groups, sections, pages, and page objects.
NavigateTo Method
Description |
Navigates to the specified object (for example, sections, pages, and Outline elements within pages). |
Syntax |
HRESULT NavigateTo( |
Parameters |
|
NavigateToUrl Method
Description |
If passed a OneNote link (onenote://), opens the OneNote window to the corresponding location in OneNote. If the link is external to OneNote (such as http:// or file://), a security dialog box will appear. Upon dismissal, OneNote attempts to open the link and an HResult.hrObjectDoesNotExist error is returned. |
Syntax |
HRESULT NavigateTo( |
Parameters |
|
GetHyperLinkToObject Method
Description |
Gets a OneNote hyperlink to the specified notebook, section group, section, page, or page object. |
Syntax |
HRESULT GetHyperlinkToObject( |
Parameters |
|
When you attempt to navigate to the resulting link, OneNote opens and displays the specified object.
FindPages Method
Description |
Returns a list of pages that match the specified query term. |
Syntax |
HRESULT FindPages( |
Parameters |
|
FindPages works only if you have Microsoft Search 3.0 or 4.0 installed on your computer. Windows Vista and Windows 7 include this component. However, if you are running an earlier version of Windows, you must install Windows Search for FindPages to work.
FindMeta Method
Description |
Returns a list of OneNote objects that contain metadata that matches the specified query term. |
Syntax |
HRESULT FindMeta ( |
Parameters |
|
FindMeta works only if you have Microsoft Windows Search 3.0 or 4.0 installed on your computer. Windows Vista and Windows 7 include this component. However, if you are running an earlier version of Windows, you must install Windows Search for FindMeta to work.
Functional Methods
The methods described in this section enable you to perform certain actions or set parameters within the OneNote application.
MergeFiles Method
Description |
Allows users to merge changes for the same file into one. For the files to be considered the same, they must have the same OneNote ID. |
Syntax |
HRESULT MergeFiles ( |
Parameters |
|
The MergeFiles method was intended for mobile scenarios in which multiple versions of a OneNote file may exist.
MergeSections Method
Description |
Merges the content of one section into another in OneNote. |
Syntax |
HRESULT MergeSections ( |
Parameters |
|
This method performs the same operation as the Merge into Another Section feature that is visible when you right-click a section.
QuickFiling Method
Description |
Returns an instance of the IQuickFilingDialog dialog box, which can be used to select a location within the OneNote hierarchy tree. |
Syntax |
HRESULT QuickFiling ( |
SyncHierarchy Method
Description |
Forces OneNote to sync the specified object with the source file on disk. |
Syntax |
HRESULT SyncHierarchy ( |
Parameters |
bstrHierarchyID—The OneNote ID of the object to be synced. |
SetFilingLocation Method
Description |
Allows users to specify where and how certain types of content should be filed in OneNote. |
Syntax |
HRESULT SetFilingLocation ( |
Parameters |
|
The types of content that can be filed include Outlook items and Web Notes from Internet Explorer that are imported to OneNote through the Send to OneNote command in each application. The filing location of items that are printed into OneNote can also be set with this method.
Properties
This section describes the properties of the Application interface.
Property |
Description |
---|---|
Windows |
Gives users access to opened OneNote windows. This property allows users to enumerate through the set of OneNote windows and modify certain window properties. For more information, see Windows Interfaces. |
COMAddIns |
Returns the COMAddIns collection for OneNote. This collection contains all of the COM add-ins that are available to OneNote. The Count property of the COMAddins collection returns the number of available COM add-ins. For more information, see the COMAddIns object. |
LanguageSettings |
Enables you to access some APIs to change the common language settings of OneNote. |
Events
This section describes the events of the Application interface.
Warning
Events cannot currently be added in managed code.
OnNavigate Event
Description |
Allows a user to assign a function to be called when the OneNote UI is navigated away from the current OneNote location. |
Syntax |
Event OnNavigate ( |
OnHierarchyChange Method
Description |
Allows a user to assign a function to be called any time the OneNote hierarchy changes (for example, adding or deleting pages, or moving sections). Hierarchy changes are batched, so if multiple changes occur at or near the same time, OneNote raises the event once. |
Syntax |
Event OnHierarchyChange ( |
Parameters |
bstrActivePageID—Passes the OneNote ID of the active page. |