Andrew May's WebLog : OneNote

OneNote: Importing Pages that Vanish

Andrew May — Fri, 01 Apr 2005 21:49:00 GMT

Here's an interesting little "gotcha" that was found by Saul Candib, the programmer-writer who is taking over documenting OneNote programming features, now that I've moved over to SharePoint.

Using my article Importing Content into OneNote 2003 SP1 as a guide, Saul wrote some code that imported content into OneNote. The code seemed to work fine: OneNote would create the page the user specified, and import the specified content no problem.

Except, once you closed OneNote, when you opened it again the page and all its contents were gone.

Turns out Saul wasn't specifying the '.one' file extension for the page. So the import routine worked perfectly; OneNote created the page and imported the content. You could even go in and add or edit the content on the new page, whatever you wanted. OneNote actually was saving the page in the My Notebooks folder, but without an extension. So the next time you launched OneNote, it saw the imported page as an unknown file and so didn't load it.

All of this was news to me. In my XML examples in the article, I used the .one file extension. For example:

But I never specifically called out that this was a requirement; to be honest, I don’t remember if I ever realized it was a requirement. I certainly never experimented with what happened if I didn't specify the file extension.

What's worse, in my example in the article, I wrote a really basic application that let the user enter the name of the page they wanted to create. But I didn't write any code that checked the specified page name to make sure it contained the file extension, or add the extension if the page name didn't. Shame on me.

OneNote XML Schema Map Notation, Take Two

Andrew May — Thu, 24 Feb 2005 20:08:00 GMT

So, I was so annoyed when I realized I had broken one of the basic rules of information design with my diagram of the OneNote 2003 SP1 SimpleImport schema, I had to take a few minutes and see if I could fix it. As I mentioned in my last entry, my diagram uses indenting and boxes to show the element hierarchy in the OneNote schema. But, because I was illustrating the same information (the element hierarchy) two different ways (indenting and boxing), the diagram contained redundant information, and was more complicated than it needed to be.

And I hated those damn boxes anyway. Chopping a diagram up into a grid like that only ends up distracting from the information. I knew it at the time, but I was on a deadline and couldn't come up with a better solution, so…

Below is my latest attempt. The grid lines are gone; element hierarchy is denoted now solely by the indenting of the element names. By formatting the information inside each element (such as data type and attributes) gray, I think I've been able to keep the element names prominent enough I don’t need boxes to denote where one element ends and another starts.

One thing that I still see as problematic is the indenting of the element information, like the data type and attributes. In this small example, I was able to keep all that information at the same left-alignment for all the elements, which again keeps that information from distracting from the element names. But, had the schema hierarchy included a few more levels, I would've had to move the element information even further over, perhaps to the point where it was so far removed from the element names in the top-level elements that it would seem disconnected.

All in all, I think this diagram is quite a bit more successful than the one that currently appears in the article. Looks like it's time to file a bug and get that image swapped out…

OneNote: An In-Depth Look at the OneNoteImporter Managed Assembly (Part 5 of 5)

Andrew May — Thu, 17 Feb 2005 17:57:00 GMT

In this series of entries, we're taking an in-depth at the OneNoteImporter manage class, which provides an object model interface for the programmability functionality added in OneNote 2003 SP 1.

Read part one here.

Read part two here.

Read part three here.

Read part four here.

Object Model Maps

The following figures diagram the OneNoteImporter assembly object model, including abstract classes and inheritance. The diagrams mainly document how the objects in the assembly relate to each other. In most cases, when a member takes an object as a parameter, or returns an object, that object is included on the diagram. Value types, such as string or integers, are for the most part not displayed.

For the sake of clarity, the following object information, pertaining to methods that most of the classes have, has been left off the diagrams:

· The Clone method returns the type of object from which you call it.

· The Equals method takes a System.Object as a parameter.

· The GetHashCode method returns a System.Int32 object suitable for use in hashing algorithms and data structures like a hash table.

· Inheritance from System.Object is not shown.

Figure 2. The Application Object (and Legend)

Figure 3. The ImportNode Abstract Class, and Page Class

Figure 4. The PageObject Abstract Class, and Derived Classes

Figure 5. The OutlineContent Abstract Class, and Derived Classes

Figure 6. The Data Abstract Class, and Derived Classes

Conclusion

The OneNoteImporter managed assembly provides a convenient and multi-functional ‘wrapper’ for working with the SimpleImporter and command line functionality in OneNote 2003 SP1. Moreover, using the provided source files for the assembly, a developer can customize and extend the classes as required for his particular application.

OneNote: An In-Depth Look at the OneNoteImporter Managed Assembly (Part 4 of 5)

Andrew May — Thu, 17 Feb 2005 17:38:00 GMT

In this series of entries, we're taking an in-depth at the OneNoteImporter manage class, which provides an object model interface for the programmability functionality added in OneNote 2003 SP 1.

Read part one here.

Read part two here.

Read part three here.

Figure 1 diagrams the internal method calls of the Commit method. It shows the OneNoteImporter classes and methods called, and the Import XML elements generated at each step. The various calls to System.Xml methods are not diagrammed.

Figure 1. The Page.Commit Method, and XML Elements Generated

In our final entry, we'll look at some object model maps that detail how the OneNoteImporter class is structured.

Read part five here.

OneNote: An In-Depth Look at the OneNoteImporter Managed Assembly (Part 3 of 5)

Andrew May — Wed, 16 Feb 2005 23:47:00 GMT

In this series of entries, we're taking an in-depth at the OneNoteImporter manage class, which provides an object model interface for the programmability functionality added in OneNote 2003 SP 1.

Read part one here.

Read part two here.

Importing Objects into OneNote

The actual creation of the XML import document, and importing the page contents, takes place when you call the Page.Commit method. This method, in turn, invokes a number of methods in other OneNoteImporter objects. Because of this method’s importance and complexity, it’s worth examining how the method functions.

First, the code checks to see if the page has changed in any way from the last time it was imported. It does this by determining if the Page object’s CommitPending property is set to True. If it is, it calls the SimpleImporter.Import method.

The code calls the Page.ToString method to generate the XML string it passes to the Import method. The ToString method in turn calls the Page.SerializeToXml method.

This begins a series of recursive calls to the SerializeToXml methods of the various objects. Each object’s SerializeToXml method includes instructions to call the SerializeToXml method of any child objects, and append the resulting XML to the parent element. This in turn invokes the SerializeToXml method of any child objects the original child object might have, and so on, until the entire page structure has been serialized to xml in a single xml document.

The Page.SerializeToXml begins by creating a new XmlDocument object, and generating <Import> and <EnsurePage> elements and adding them to the document. Page object property values are used to set the various attributes of the <EnsurePage> element.

Note that the Commit method generates import XML with both <EnsurePage> and <PlaceObjects> elements for that page. Specifying an <EnsurePage> element for a page guarantees that the page exists before OneNote attempts to import objects onto it. So if your application includes a scenario where you only want to import objects onto a page if the page already exists, you’ll need to modify this method, or use another means.

The code then generates a <PlaceObjects> element. For each of the Page object’s children whose CommitPending property is set to True, the code calls the PageObject.SerializeToXml method.

If the page object’s DeletePending property is set to True, the PageObject.SerializeToXml method generates a <Delete> element. If not, the method does three things:

· Generates a <Position> element, whose attributes are set according to Position object property values.

· Calls the SerializeObjectToXml method for the specific PageObject-derived class involved, i.e., ImageObject, InkObject, or OutlineObject.

· Calls the SerializeToXml method for the specific OutlineContent-derived class involved, i.e., HtmlContent, InkContent, or ImageContent.

Executing the SerializeToXml method for each of these content types includes a call to the SerializeToXml method for the Data-derived object they contain: BinaryData, FileData, or StringData. In this way, the entire page structure is serialized to xml in a single xml document.

Note that the HtmlContent.SerializeToXml method includes a call to another internal method of that same object, called CleanHtml. The CleanHtml method reads through the html string or file data and makes sure the HTML is formatted in a way that OneNote accepts. It identifies and replaces problematic formatting with characters which OneNote can process. For example, the CleanHtml method wraps the HTML string with the appropriate <html> and <body> tags if the HTML lacks them.

The serialization of the page nodes is now complete. If the Page object had no children, the <PlaceObjects> element remains empty. In such a case, the Page.SerializeToXml method does not append it to the <Import> element.

Finally, the Page.SerializeToXml method determines the appropriate namespace designation and adds it to the <Import> element.

The ToString method then takes the XmlDocument object, saves it as a text stream, converts it to a string, and passes it back to the SimpleImporter.Import method. This Import method uses the XML string to import the specified content into OneNote.

Now that the content has been imported into OneNote, the Commit method performs some vital housekeeping. Using the RemoveChild method, it removes any of the Page object’s children who have their DeletePending property set to True. It then sets the private committed field to True, thereby making the Date, PreviousPage, RTL, and Title properties read-only. You cannot change these attributes once you import a page into OneNote.

Lastly, it sets the CommitPending property of the Page to False. This it turn sets the CommitPending properties of all the Page object’s remaining children to False as well.

In part four, we'll examine the internal method calls of the Commit method.

Read part four here.

OneNote: An In-Depth Look at the OneNoteImporter Managed Assembly (Part 2 of 5)

Andrew May — Tue, 15 Feb 2005 18:30:00 GMT

In part one, we started to take an in-depth at the OneNoteImporter manage class, which provides an object model interface for the programmability functionality added in OneNote 2003 SP 1.

Read part one here.

Creating Objects

Creating the page and the object you want to import onto it is relatively straight-forward. The Page, PageObject-derived sub-classes, and OutlineContent-derived sub-classes all have one or more public constructors with which you create new instances. We should, however, briefly touch on a few issues to keep in mind.

Identifying Objects

Both the Page and PageObject-derived sub-classes have an internal Id property, which gets or sets an ObjectId object. The ObjectId represents the globally unique identifier (GUID) OneNote requires to identify each page and object imported. The data in an ObjectId consists of a private field representing the containing object’s identifier. The ObjectId object is generated when the page or object is constructed.

The ObjectId object cannot be accessed from outside the assembly. The OneNoteImporter assembly generates and maintains the GUIDs for the user. If you are programming for a scenario that requires you to have access to the GUIDs, there are two approaches to consider:

· Override the class, and make the GUID properties publicly accessible.

· Serialize and persist the Page object between sessions, and then deserialize it as necessary.

Note that the ObjectId class stores the object GUID internally as a System.Guid data type, which does not store the GUID in registry format, that is, surrounded by curly braces ({}). OneNote only accepts GUIDs in registry format. Therefore, the ObjectId.ToString method has been overridden so that it wraps the guid value in curly braces before returning the string.

Similarly, if you use the ObjectId(string) overloaded constructor, the constructor code strips off curly braces, if present. As they might be, if you were passing a serialized ObjectId as an argument.

Committing Objects for Importing

The CommitPending property determines whether or not an import node is included in the XML passed to the SimpleImporter.Import method. Objects with this property set to True represent one of the following:

· an object that hasn’t been imported into OneNote

· an object which as been changed since the last time it was imported; this includes objects marked for deletion from OneNote

· an object that contains a child object that is either of the two cases above

Only objects whose CommitPending property is set to True are serialized and included in the import XML string. By default, whenever an object is constructed from an ImportNode-derived class, this property is set to True. Let’s examine how this property is used, and when they value is changed.

Calling the Page.Commit method imports the page and its contents into OneNote. Once you import a page, the CommitPending property is set to False for that Page object and all the objects contained on it. If you immediately called the Commit method again, neither the page nor any of the objects on it would be included in the XML for the next import.

However, when you make a change to an object, such as changing a property value, the CommitPending property gets set back to True. Not only that, but the CommitPending property of any parent object gets set to True as well. This happens because of the way the import XML is structured. If you want to re-import a specific object, you must also include information about all the objects that contain it, such as the page it appears on. Setting the CommitPending property to True for all the parent objects ensure all the necessary information is included in the import XML string.

Here’s how it actually happens in the code:

You cannot access the CommitPending property from outside the OneNoteImporter class assembly, but if you change any public object properties, the CommitPending property is set to True, so that those object changes are imported into OneNote the next time you call the Page.Commit method. This includes setting the DeletePending property of an object to True.

In addition, the CommitPending property code also sets the CommitPending property of the parent object, if there is one, to True. Which in turns calls the CommitPending property code again, in case that parent object has a parent, and so on up the import node structure to the Page object.

Conversely, when the Commit method sets a Page object’s CommitPending property to False, the property code sets the CommitPending property of any children to False as well, which in turn calls the method again, in case any of those objects have children, and so on.

Adding Objects to Pages and Outlines

You can add content directly to a page, and to an outline on a page. The public Page.AddObject and OutlineObject.AddContent methods both call the internal ImportNode.AddChild method, which adds the child object to a private ArrayList object. A convenience constructor enables you to name the object when you add it, if you want.

OutlineContent objects are displayed in the order in which they are added to the OutlineObject object.

To import text into a OneNote page, you add an HtmlContent object to an OutlineObject, and then add the OutlineObject to the desired Page object.

Deleting Objects From OneNote

In the OneNoteImporter assembly, there are two levels of deleting objects:

· Marking an object for deletion the next time the page is imported into OneNote

· Removing an object from the OneNoteImporter object structure; for example, as removing an ImageContent object from an OutlineObject object

To delete an object from a OneNote page, use the Page.DeleteObject method. This method does not directly remove the object from the Page object’s private children array. Rather, it sets the DeletePending property of the specified object to True. Therefore, when you execute the Page.Commit method, the object gets deleted from the page in OneNote. Only then is the ImportNode.RemoveChild method called. It is this internal method that removes the object from the Page object’s array, using the ArrayList.Remove method. The RemoveChild method also sets the Page object’s CommitPending property to True; however, the Commit method then sets it to False.

Note You can even call the DeleteObject method for objects that have not been imported into OneNote. While this means the object is serialized and included in the XML string passed to the SimpleImporter.Import method, no error results. OneNote ignores XML elements directing it to delete objects not present on the specific page. This is by design, since the OneNote user may have manually deleted the object themselves.

Conversely, to remove an object from an outline, use the OutlineObject.RemoveContent method, which directly calls the ImportNode.RemoveChild method. So the object is removed from the OutlineObject object’s children array at the time the RemoveContent method executes. The RemoveChild content also sets the CommitPending property of the OutlineObject object to True, so that the entire updated outline (minus the removed object) is imported into OneNote again the next time the Page.Commit method executes.

Iterating through an import node’s children

Both the Page and OutlineObject objects implement the IEnumerable interface. Their respective public GetEnumerator methods provide the ability to iterate through their private children array.

In part three, we'll get to the whole point of the OneNoteImporter class: importing objects into OneNote.

Read part three here.

OneNote: An In-Depth Look at the OneNoteImporter Managed Assembly (Part 1 of 5)

Andrew May — Mon, 14 Feb 2005 18:56:00 GMT

A while back I wrote a series of entries dealing with how you can use Donovan Lange's OneNoteImporter manage class to make importing content into OneNote 2003 SP1 even easier. To recap: Donovan's OneNoteImporter managed class assembly provides an object model interface for the programmability functionality added in OneNote 2003 SP 1. Both the Send to OneNote from Outlook and Send to OneNote from Internet Explorer PowerToy add-ins actually use the OneNoteImporter class in their source code.

You can download the OneNoteImporter class source code from Donovan's blog here.

You can read my initial series of blog entries about the OneNoteImporter class here: part one, and part two.

For the next week or so I'll be running a series of entries that examine the OneNoteImporter class in more detail, and really get 'under the hood' on how the class is structured and functions.

Introduction

The OneNoteImporter managed class assembly provides an object model interface for the programmability functionality added in OneNote 2003 Service Pack (SP) 1.

The classes in this assembly enable you to:

· Import content into OneNote SP1 using the SimpleImport.Import method without having to explicitly author the XML string this method takes as a parameter. The OneNote managed assembly does this for you.

You do not need to be familiar with the SimpleImporter class, or the XML schema used by its Import method, to use the OneNoteImporter managed assembly. However, for more information about the SimpleImporter class and its operation, see Importing Content into Microsoft Office OneNote 2003 SP1.

· Navigate to a specific page in OneNote using the SimpleImport.NavigateTo method.

This is also covered in the article referenced above.

· Use class methods to invoke some of the more popular command line switches you can use to customize how the OneNote application launches.

For more information on customizing OneNote 2003 using command line switches, see Customizing OneNote 2003 SP 1 Using New Command Line Switches.

This article presents a detailed discussion of the internal design and function of the OneNoteImporter classes, in case a developer wants to modify the classes, or just know more about how they operate internally. For a general discussion of how to use the public members of the OneNoteImporter managed assembly, see OneNote Import Managed Assembly: The Quick Rundown (part one and part two).

Source files for the assembly are available from Donovan Lange's blog here. Developers are encouraged to modify the OneNoteImporter assembly as they desire and redistribute it with their application.

Note To avoid compatibility issues with other versions of the assembly that might be loaded on the user’s computer, include the .dll in your application directory, rather than the system directory.

There are several basic steps in using the OneNoteImporter assembly to import content in to OneNote:

· Create the page onto which you want to import content

· Create and add the content to the page

· Import the page into the desired OneNote location

We’ll discuss the internal operation of the assembly classes during each of these steps.

The OneNoteImporter assembly also enables you to update and delete pages or specific content on them, as long as you know their unique identifier. This is discussed in detail later in this article.

It’s worth noting at this point that the OneNoteImporter assembly is designed to import a single OneNote page at a time. The OneNote.SimpleImporter class can take an XML string that includes content to be imported onto multiple pages. However, when using the OneNoteImporter assembly, you create a separate XML string for each page you want to import.

Examining the Classes

Before discussing how the classes in the assembly function internally, let’s briefly look at the abstract classes that form the basis of the assembly. There are four such classes, from which almost all of the other assembly classes derive: ImportNode, PageObject, OutlineContent, and Data.

The ImportNode Class

The ImportNode class is the base class for the entire assembly. Almost all the other classes inherit from it, including the other three abstract classes. As mentioned before, the SimpleImporter.Import method takes an XML string comprised of elements that detail the OneNote page and contents you want to import. The ImportNode represents a single node (or element) in this XML structure, such as a page, or an object on a page.

This class provides several important pieces of common functionality:

· Serialization: The ImportNode contains an abstract method, SerializeToXML, that classes derived from it must implement. This ensures that each derived class contains the means to serialize itself into XML for the XML string passed to the SimpleImport.Import method. We discuss how the various classes implement this method later in the article.

· Selection for importing: This class also contains an internal Boolean property, CommitPending, that denotes whether or not to include this object in the XML string passed to the SimpleImport.Import method. By default, all objects based on the ImportNode or its derived classes have their CommitPending property set to True when they are constructed. This denotes that the object has not yet been imported into OneNote. We also discuss how and when an object’s CommitPending property is changed later in this article.

The PageObject class

The abstract PageObject class represents an object that can be added, updated, or deleted from the specified OneNote notebook page. There are three classes derived from the PageObject class in the assembly:

· ImageObject, which represents an image, such as a jpeg or gif, on a OneNote page

· InkObject, which represents ink on a OneNote page

· OutlineObject, which represents an outline on a OneNote page. OutlineObject objects are actually comprised of other object, such as images, ink, and text described in html format.

The SerializeToXml method is implemented in the PageObject class. It serializes the properties common to all PageObject classes:

· Whether to delete the object

· The object’s unique identifier

· The object’s position on the page

It then calls the abstract PageObject method SerializedObjectToXml. All classes derived from PageObject must implement this method, which serializes the specific attributes of each derived class.

The OutlineContent class

The abstract OutlineContent class represents an object that is part of an outline. There are three classes derived from the OutlineContent class in the assembly:

· HtmlContent, which represents text on a OneNote page, described in html format.

· InkContent, which represent ink that is part of an outline.

· ImageContent, which represent an image that is part of an outline.

The SerializeToXml method is abstract in this class; each class derived from the OutlineContent class must implement the serialization process.

The Data class

The final abstract class, Data, represents the actual data of the object to be imported. For example, for an image, this would be either the path to the image file, or the base 64-encoded data of the image itself. There are three concrete derived classes for the different types of data content an object can represent:

· BinaryData, which represents ink or image data that is base-64 encoded.

· FileData, which represents the path to a source file.

· StringData, which represents HTML content.

The SerializeToXml method is abstract in this class; each class derived from the Data class must implement the serialization process.

In the next entry, we'll look at creating objects.

Read part two here.

OneNote: XML Reference Schema Download Now Live

Andrew May — Fri, 14 Jan 2005 00:21:00 GMT

For those of you who have been waiting for an actual copy of the OneNote schema, wait no more. MSDN has just republished the Office 2003: XML Reference Schemas download, and this time it includes OneNote 2003 SP1. The download includes a copy of the OneNote import schema, as well as the complete element, type, and attribute documentation we posted online awhile back. It also include a copy of my article detailing how to use the schema to import content into OneNote.

What more could you ask for?

Oh yeah, it includes the complete schemas and documentation for some applications called Excel, InfoPath, Project, Visio and Word as well.

OneNote SDK Now Live on MSDN

Andrew May — Mon, 08 Nov 2004 22:59:00 GMT

Here's something that was published on MSDN last week that you might have missed: the OneNote Software Developers Kit (SDK).

Because the developer functionality in OneNote SP1 primarily consists of the SimpleImport interface, the OneNote SDK provides a full schema reference. Each element and type in the schema gets its own topic, complete with a full description and usage example. So if you're looking for detailed definitions of schema elements, this is just the reference you want.

The SDK should be available soon as a download as well. I'll let you know when that happens as well. In the meantime, check out the online version.

OneNote: Positioning Imported Content on Right-To-Left Pages

Andrew May — Wed, 04 Aug 2004 16:35:00 GMT

Here’s something I found in a code comment in the OneNoteImporter managed assembly source code. It applies to both the OneNoteImporter and the SimpleImporter API itself, and I haven’t seen it documented anywhere else, so I thought I’d pass it on here.

It concerns positioning objects on OneNote pages that read right-to-left. If you’ve used either the OneNoteImporter and the SimpleImporter API itself, you know you can use the RTL attribute of the <Page> element to set whether you want the page to read right-to-left or vice versa. You can then set the x and y attributes of an object’s <Position> element to determine where you want the object placed on the page. (If you’re using the OneNoteImporter assembly, then set the RTL property of the Page object, and the X and Y properties of the Position object, respectively.)

OneNote places the objects it imports onto the page based on absolute coordinates, expressed in points. Turns out that the coordinates differ, based on whether the page reads left-to-right or right-to-left.

Here’s how it works:

If you set the page to read left-to-right, then the origin (that is, the place there both x and y equal 0) is the upper left hand corner of the OneNote page. X coordinates advance in positive numbering from the left to the right; y coordinates advance in positive numbering horizontally down the page. Pretty straightforward.

Things get a little more complicated when you set the page to read right-to-left. In this case, the origin (0,0) is the upper right hand corner. But the x and y coordinates still advance in positive numbering in the same directions: x to the left, y horizontally down the page. So for any objects on a right-to-left OneNote page, the x coordinate will actually be a negative number. Indeed, the x coordinates are increasingly negative as you to the left across the page.

Also remember that the x coordinate refers to the upper left corner of the object, regardless of the direction in which the OneNote page reads.

So let’s look at an example. The figure below represents a OneNote page, set to read right-to-left. For the sake of argument, assume the page is 600 pixels wide by 750 pixels long (I have no idea what the default size of a OneNote page is.) In this case, the upper left corner coordinates are (-600, 0); the lower left corner coordinates are (-600, 750). The (x, y) coordinates of the object A refer to the position of the upper left corner, and so would be (-400, 100), and not (-250, 100), which is the object’s upper right corner.

Make sense?

One last thing: you should also consider page margins when positioning an object on the page. While (0,0) is the absolute origin of the page, depending on user’s preference, their upper left hand corner margin should be at (½”,½”), or (36,36) in points. Which is (-36,36) if the page reads right-to-left.

OneNote import Managed Assembly: Customizing How OneNote Launches

Andrew May — Tue, 03 Aug 2004 21:29:00 GMT

Here’s still more functionality packed into the OneNoteImporter assembly:

You can also modify how OneNote starts by using the following methods of the Application object. These methods ‘wrap’ command line switches that customize how the OneNote application starts.

The table below lists the Application object methods, and the command line switch each invokes. If a method is overloaded, the number of overloads is noted next to the method name. In most cases, the method is overloaded to account for the fact that the command line switch takes a series of optional string arguments.

All the method parameters take strings, except the openReadonly parameter of the Open method, which takes a Boolean value.

Application method	Parameters	Command line switch
JoinSharedSession (2)	(sessionAddress) (sessionAddress, password, sectionPath)	/joinsharing
Open (2)	(sectionPath) (sectionPath, openReadonly)	/openro
PauseRecording	()	/pauserecording
Print	(sectionPath)	/print
StartAudioNote	()	/audionote
StartSharedSession (3)	() (sectionPath) (sectionPath, password)	/startsharing
StartSideNote	()	/sidenote
StartVideoNote (4)	() (recordingProfilepath) (videoDevice, audioDevice) (videoDevice, audioDevice, recordingProfilepath)	/videonote
StopRecording	()	/stoprecording

Be aware that these Application methods have been implemented as asynchronous command line calls. Because of this, your code continues to run after it calls Application method is called, independent of whether or not the OneNote application has yet launched.

In addition, you can use the Activate method to bring the OneNote application to the foreground.

For more information on the command line switches, see Customizing OneNote 2003 SP 1 Using New Command Line Switches.

Is there anything these guys didn’t think of?

OneNote Import Managed Assembly: The Quick Rundown (2 of 2)

Andrew May — Wed, 28 Jul 2004 16:41:00 GMT

In part one, we discussed how to use the OneNote managed class assembly to import content into OneNote. Now let’s actually look at the XML the Page class generates for the SimpleImporter.Import method.

Looking at the XML

If you want to preview what the XML that’s passed to the SimpleImport.Import method will look like before you run the Commit method, call the Page.ToString method. This is the method that actually serializes the page and its contents to XML prior to importing. Just remember that once you’ve committed a page, none of the object on that page will be included in the generated import XML, unless they’ve subsequently been modified in some way.

Also remember that the Commit method generates import XML with both <EnsurePage> and <PlaceObjects> elements for that page. Specifying an <EnsurePage> element for a page guarantees that the page exists before OneNote attempts to import objects onto it. So if your application includes a scenario where you only want to import objects onto a page if the page already exists, you’ll need to modify this method, or use another means.

So let’s a quick look at the code sample Donovan gives over on his blog (I think he’ll forgive me if I rewrite it in VB). This sample creates a new page, title “General”, with one object on that page: an outline containing the text “Hello world!”

Sub TrivialImportVB()

Dim p As New Page("General")

Dim outline As New OutlineObject

outline.AddContent(New HtmlContent("Hello <i>world</i>!"))

p.AddObject(outline)

p.Commit()

p.NavigateTo()

End Sub

And here’s the resulting XML that gets passed to the SimpleImport.Import method. Notice that the necessary GUIDs are there, and the HTML has even been cleaned up so that OneNote accepts it with no problem. How’s that for service?

<?xml version="1.0" encoding="utf-16"?>

<EnsurePage path="General" guid="{e5bf863a-7070-4058-a0f5-

343e4a45dc05}" date="2004-07-23T09:52:17.0963010-07:00" />

<PlaceObjects pagePath="General" pageGuid="{e5bf863a-7070-4058-a0f5-

343e4a45dc05}">

<Html><Data><![CDATA[<html><body>Hello

<i>world</>!</body></html>]]></Data></Html>

</Outline>

</Object>

</PlaceObjects>

</Import>

Object Model Diagrams

And what’s an object model without an object model map? Anyone who’s read this blog has probably realized how fond I am of presenting technical information graphically (which I’m sure has nothing to do with my being the programmer-writer for PowerPoint and Publisher.) So here are some diagrams of how the classes fit together. But first, some caveats:

The following diagrams show only the public members of each class. None of the abstract classes are diagramed, and I’ve left any inheritance information off the diagrams, although I’ve listed any members that a class inherits in the individual classes themselves. For example, ImageObject, InkObject, and OutlineObject all inherit the Height, Position, and Width properties from the abstract class PageObject, which is not diagrammed.

I mainly want to show how the various object relate to one another. For the most part, if a member gets or sets a data type, I haven’t bothered showing that in the diagram. In addition, for the sake of clarity, I’ve left off the following information for basic methods that most classes here have:

· The Clone method returns the type of object from which you call it.

· The Equals method takes a System.Object as a parameter.

· The GetHashCode method returns a System.Int32 suitable for use in hashing algorithms and data structures like a hash table.

Trust me, I’ve got much more detailed diagrams of the internal workings of each class tacked up around my office, and those will most likely make it into the finished article, which discusses the class source code. But these should give you a good at-a-glance idea of how things flow.

Figure 1. Page object (and legend)

Figure 2. ImageObject, InkObject, and OutlineObject

Figure 3. HtmlContent, ImageContent, and InkContent

OneNote Import Managed Assembly: The Quick Rundown (1 of 2)

Andrew May — Tue, 27 Jul 2004 18:30:00 GMT

If you haven’t already seen this, get over to Donovan Lange’s blog. Donovan, Omar, and David have put together an abstracted managed assembly that provides an object model for the SimpleImport functionality OneNote added for SP1. That’s right; you don’t even have to create the XML for the import yourself. The OneNote guys have you covered.

I’m currently putting together an article that highlights this class library and all the functionality it provides. I’ve been pouring over the code for the last week or so, and I think I’ve finally got it. (The assembly itself is written in C#. Did I mention I’m about as fluent in C# as in ancient Armenian?) I have to say, this is some very well-thought-out work.

The OneNote guys have included detailed technical documentation in the download itself, but I thought it might be worth taking a few minutes and putting together a high-level overview of how the classes work. So if you just want to get up and running, and aren’t too concerned about how the assembly does what it does so well, then read on.

I’m going to assume you have a passing familiarity with the OneNote SimpleImport class and the xml schema it uses. (If you don’t, follow the links and then come back. I’ll wait.)

They’ve really made the class library easy to use. Here’s all you need to do:

Create a new Page object

Not much to say here. Once you’ve created the page, you can set its attributes using various properties such as Date, PreviousPage, RTL, SectionPath, and Title. The PreviousPage property sets the value of the ‘InsertAfter’ XML attribute; the others are pretty self-explanatory.

Create the content you want to add to your new page

There are three types of objects you can add to a page: ImageObject, InkObject, or OutlineObject objects. All page objects share common properties, such as Height, Width, and Position.

Note While the OutlineObject inherits the Height property from its base class for consistency, outlines cannot have an explicitly specified height. Therefore, accessing or modifying the Height property of an OutlineObject will result in an error.

Each ImageObject and InkObject contains data representing the actual image or ink content you want to add to the page. You get and set this data by using the ImageData and InkData properties, respectively.

You use these properties to get or set a BinaryData or FileData object. The BinaryData class represents raw binary data in memory. When you add an ImageObject or InkObject object containing BinaryData to a page, the OneNote Import Managed Assembly ensures this data is properly base-64 encoded. The FileData class represents data that is stored in an external file, and is marshaled to OneNote as a file path.

For the most part, you’ll really only need to create BinaryData and FileData objects directly when you want to update existing image or ink objects. The ImageObject and InkObject each provide convenience constructors that create the appropriate data object, when passed a System.IO.FileInfo object or binary array of bytes as a method parameter.

OutlineObject objects are slightly more complex because outlines can be comprised of ImageContent, InkContent and HtmlContent objects. Add content to an OutlineObject using the AddContent method. Outline content objects are displayed within the outline in the same order in which they are added to the OutlineObject object.

The ImageContent and InkContent classes are very similar to the ImageObject and InkObject classes. Again, the actual image or ink content is represented by either a BinaryData or FileData object. This object is also created based on the specified argument passed to the ImageContent or InkContent constructor, and you can subsequently access it using the ImageData or InkData property, respectively. Note that neither the ImageContent or InkContent classes contain properties for setting their position and size on the page, as these properties are set for the outline as a whole.

The HtmlContent object also contains data within the HtmlData property, except it’s data is represented as either a FileData or StringData object. The StringData object represent string data as a System.String. Constructors on the HtmlContent object enable you to create a new HtmlContent object based off of pre-existing HTML in a string object or a FileInfo object containing the path to an HTML file.

Add objects to the page

Add the objects you’ve created to the Page object using the AddObject method. You can add as many as you want, in any order. How the objects are arranged on the page depends on the coordinates specified in the Position child object for each ImageObject, InkObject, or OutlineObject.

Import the page

Now that you’ve got your page set up with all your content, it’s time to import it into OneNote. You do this using the Page.Commit method. This method does several vital things, including:

· Creates the XML document to be used for the OneNote SimpleImport class.

· Specifies the correct OneNote namespace, based on whether the OneNote SP1 Preview or SP1 release version is installed on the current machine. (Now, how thoughtful is that?)

· Adds an <EnsurePage> element for the page, using the Page object properties you’ve set.

· If your page contains objects, then the method also creates a <PlaceObjects> element to insert, edit, or delete those objects as specified.

· Serializes the page and all its contents to XML, and adds them to the XML import document. In the course of this, it also does some minor checking of any HTML content to format it property for OneNote.

· Validates the XML it created, to make sure OneNote accepts it.

· Calls the SimpleImporter class and imports the content into OneNote.

Pretty slick, no?

Here’s some things to keep in mind:

Generating GUIDs

The OneNote classes internally generate the necessary GUIDs that OneNote needs to identify each object and page. You cannot access a page or object’s GUID from outside the OneNote class assembly. The GUIDs do appear in the XML passed to the SimpleImporter.Import method, of course.

On a sidenote, Donovan tells me he intends to change this. Originally, the intent was to hide the GUIDs for the benefit of new users. But it turns out that many scenerios require control over the Page and PageObject GUIDs. If you do need access to these GUIDs, here’s two strategies to consider:

· Override the class, and make the GUID properties publicly accessible.

· Serialize and persist the Page object between sessions, and then deserialize it as necessary.

Re-Importing Objects

Page objects keep track of whether they have been committed (or in other words, imported) and, additionally, keep track of modifications that require an update (that is, another import). So, after you commit a Page for the first time, if you then immediately call the Commit method again, none of the original objects would be re-imported. However, suppose that, after you commit a page, you then added new objects to that page, or changed the content or properties of an existing object on the page. In that case those new or modified objects will be re-imported the next time you execute the Commit method.

The OneNote SimpleImport API does not permit you to change a page’s date, title, insertAfter, or RTL attributes once you’ve imported the page. Because of this, once you’ve called the Commit method for a Page object, the following Page properties become read-only and throw an exception if you try and set them: Date, PreviousPage, RTL, and Title.

Deleting Objects

You can delete an object from a page using the Page.DeleteObject method. Much like the Page.AddObject method, the deletion does not in fact occur until you execute the Commit method; only then is it deleted within OneNote and removed as a child of the Page object.

Next time, I'll include an example and we'll take a look at the XML actually produced.

OneNote 2003 SP1 Preview Documentation Live On MSDN

Andrew May — Thu, 10 Jun 2004 17:51:00 GMT

The title pretty much says it all. The final versions of the OneNote SP1 Preview documentation I posted here in draft version about a month ago went live on MSDN last night:

Importing Content into OneNote 2003 SP1 Preview

Customizing OneNote 2003 SP 1 Using New Command Line Switches

So we’ve pulled together the information from my assorted blog entries, cleaned it up, and made it ready for prime time. It’s worth taking a look at, even if you’ve already read the original blog entries. And do me a favor: rate the articles. It’s the only way we know if we’re addressing your needs. Thanks.

OneNote Namespace Change for SP1

Andrew May — Wed, 12 May 2004 21:31:00 GMT

Here’s a heads-up for developers that are using the SimpleImport interface available in the OneNote 2003 Service Pack 1 (SP1) Preview. Be advised that the namespace for the Import method will be different in the final released SP1 from what it is in the Preview version.

The current namespace for the OneNote SP1 Preview is:

http://schemas.microsoft.com/office/onenote/01/2004/import

While the final namespace for OneNote SP1 will be:

http://schemas.microsoft.com/office/onenote/2004/import

From what I understand, it’s become standard procedure here in Office to use a ‘beta’ namespace for early versions of a product, and then switch to another namespace once the schema has been finalized. Just be advised that if you’re programming against the Preview namespace, you’ll need to update your code for the new namespace in order for it to be compatible with the final OneNote SP1, once it’s released.

I’ve already edited my blog entry detailing how to use the SimpleImport functionality, but I wanted to call this out in a separate entry for anyone who’s already using the documentation.