How to build Help into a WPF Program

Over the last couple of days, I have spend an inordinate amount of time trying to figure out how to integrate on-line help into my WPF programs. I am amazed at how difficult it was to find concise and useful information on this subject. In fact, it makes me think that I must be missing something major. Also, it seems that none of my programming books do a very good job covering the subject.

In fact, creating the Help File and Linking to it are two separate topics and will be dealt with separately.

Lest there be any doubt, we are limiting ourselves to creating “CHM” help files.

Using HTML Help Workshop

This is a free download from Microsoft and it is pretty basic. It starts with HTML files into which you can put links to other HTML files. You add these HTML files to a Table of Contents as “Topics”. You can also insert Headings and Files. My theory is that a Heading is just like a Topic, except that it does not NEED to have an HTML file associated with it.

The biggest draw-back to this program is that it does not allow interactive editing of HTML files. Also, it was far from intuitive to use. I found an excellent Help Workstation Tutorial by Char James-Tanny. I downloaded it from http://frogleg.mvps.org/helptechnologies/htmlhelp/hhtutorials.html.

BUT – there is something better out there for preparation of CHM files.

Using HelpNDoc to create Help Files

A search for Free Help Authoring Tools brought me to http://www.helpndoc.com/ from whence I was able to download HelpNDoc which is free for non-commercial use.

This program is very cool and I think it could be just the thing I need for documenting programs. The reason that it would be better than MS Word or something like that is that it allows me to work in outlines and it allows me to enter hyperlinks. It would be really nice if allowed me to follow them while I was authoring something, but you can’t have everything.

It comes with a pretty good on-Line help system of its own and is pretty easy to use.

Another nice thing about it is that it outputs in any or all of four different formats: CHM, HTML, DPF and Word.

And if you look in the CHM folder, it seems that it puts out all the files that would be used by HTML Help Workshop. According to one source, HTML Help Workshop must be installed for HelpNDoc to compile its help projects.

It was not clear that it allows you to create indexes, but if this is important, one might be able to do this using HTML Help Workshop as a post-processing step. Experimentation would be useful here.

Linking to help from WPF Programs

As nice as these free programs are, neither explains how to link a WPF application to the help.

The Char James-Tanny tutorial does discuss linking using the hhctrl.ocx control from VB 5/6 and perhaps it would be possible to adapt those instructions.

Apparently, there is a System.Windows.Forms.HelpProvider control. This appears to not work with WPF controls.

I did, however, find a way to open CHM help files.

But first, a little about the structure of HelpNDoc.

HelpNDoc builds a help system out of Topics. Each Topic is one entry in the table of contents, and when as the help system is being built, it creates an HTML file on the topic. This HTML file gets compressed and included in the CHM file, but a copy of the HTML file is left in the CHM directory.

This topic gets a name or Help ID based on the Topic Name in the Table of Contents. You can change this Help ID by right clicking the TOC entry. This Help ID plus “.html” is used as the name of the HTML file for this topic.

You can also add Anchor points to a Topic. You can set an anchor by placing the cursor where you want the anchor, going to the Insert tab and clicking Insert/Remove Anchor on the right side of the ribbon. The program then prompts you to enter the name of the anchor. You can see a green bar where the anchor is placed, but unfortunately, I did not find a way to go back later and see what the name had been set to. I was able to see it after generating the help file by looking at the source code in the resulting HTML file.

So, now we have a generated CHM help file, HTML files holding topics that have been compiled into this help file and possibly anchors in some of the Topic/ HTML files. How do we access them.

The answer is to use the static ShowHelp method of System.Windows.Forms.Help. Here is what the calls will look like. Assume that the help file is named MyHelp.chm. Assume that the Help ID is MyTopic and that the topic file in that help file is therefore named MyTopic.html. Also, there is an anchor point in this file named MyAnchor. You might want to use a full path instead of just a filename.

To open the help file at the beginning, use:

Help.ShowHelp(null, @"MyHelp.chm");

The following will open the help file at the MyTopic page:

Help.ShowHelp(null, @" MyHelp.chm", "MyTopic.html");

And the following will open the help file at the anchor point:

Help.ShowHelp(null, @"MyHelp.chm", "MyTopic.html#MyAnchor");

So, that is enough to get me started. As I learn more, perhaps I will update this note.

Using my LG Dare as a Music Server

I like to listen to music while I am in my workshop. You would think this would be easy, and it would be if I were not so lazy. I want to be able to walk into the shop, throw a switch, and just have the music start – without thinking about a thing.

You might think that a radio would be just the thing, but there is only one passable FM radio station in my area and while I like a lot of their music, I don’t love it.

What about an old computer? Well, I don’t want to keep it on all the time or wait for it to boot up or log on or anything like that.

And how about Satellite Radio? Well, I am too cheap to pay for it.

But the LG Dare, plugged into a small charger, running all the time, might be just right. I plan to put the speakers onto the switch that I turn on when I enter the shop, so they will draw power only when I am using them.

Loading the Music

One can certainly use V-Cast/Rhapsody to load music. In fact, I had to install the V-Cast software on one of my computers in order to figure out the file structure of the Dare. But my goal is to pop micro-SD cards into and out of the Dare as my music store. I figure that it will be easier than using special software.

So, I loaded V-Cast onto the Vista side of the Timeline-X computer and told it to connect to the Dare. I then dragged some music  files from a windows explorer folder into the music directory on the Dare. I added a playlist and put a few songs into that as well.  The display on V-Cast shows that I had three folders: music, albums and playlists. I told the system to disconnect from the Dare, powered down the Dare, and removed the micro-SD card.

When I plugged the micro-SD card into my main computer, it had five folders on it:

• media
• my_flix
• my_music
• my_pix
• my_sounds

The music was in the my_music folder (with all file names in lower case). I could not find the playlist; I searched for it several times. My only guess is that this could be on the part of the Dare that is not removable. It seems that all the music goes into this folder without subdirectories.

Experimenting with iTunes

In my last post, I described tools I had written that would:

• Swap names of artists when they had been rendered with a comma. Holly, Buddy became Buddy Holly, etc.
• Update the metadata for the files based on their locations using the old structure.
• Remove the track number from the start of the file names.
• If the file was part of a collection, attempt to extract artist name from the file name and move it to a directory for that artist.

I ran this on the M:\ drive and it worked (even though I had to designate the M drive using \\wd-netcenter\Music rather than “M:\”.

This is all well and good, but it left me with a couple of problems:

• iTunes put a lot of crap into the library that was NOT on the M drive. I don’t want this crap in the library.
• I wanted to give all the tracks a default Rating of two stars. That way I can change only the ones I want to be other than “normal”.
• Previously, there had been a lot of track in the library that did not in fact exist on the disk. I needed some way to expunge those.

I decide to try to write code to do this.

I wondered if I could do this my editing playlists. These could be in either tab-separated text or XML. I created a Playlist and added a track to it. I then exported the playlist to a text file, modified it to change the rating and then imported it again. The import worked, but it did not change the rating.

 

Working with Library.xml

I learned that I could export the entire library as an XML file (but not a text file) by using File -> Library -> Export. It was easy to spot fields for Location and Rating.

According to Francisco Balena, there are two ways to manage XML. I started with what he said would be the easier one: using an xml reader and an xml writer. I figured out how to use them, but I also soon learned that this is handling the xml at a very low level and would require a huge amount of coding.

Instead, I loaded the whole thing into an xml document and then figured out how to navigate down to the information on the individual tracks. I did this pretty much by trial and error – looking at the library.xml file as text in one window and opening nodes in Visual Studio to figure out which child of each node I wanted to use.

I did run into one interesting problem. Visual Studio would not allow me to use “M:\” as the root of my music server. Instead, I had to call it \\wd-netcenter\Music. I have no idea why.

I put a feature into Music Manager to update the library.xml file. It does two things:

• If the Location is other than on the M drive, it removes the track from the DOM.
• If there is no Rating, it adds a rating of “40” which corresponds to two stars, my default.

I then started iTunes while holding the shift key. This allows me to specify the XML library I want to enter. I had to key in the file names, since the file-open dialog only shows .ITL files. It took two or three hours to complete this and when it was done, it told me that the file was incompatible and offered to try to repair it. This appears to be taking even longer. I think it is trying to reload album artwork or something like that.

Well, this DID work. It took about 6 hours to grind through everything, but in the end, it appears to have worked. Still, I am not interested in waiting for 6 hours to do a small update. Plus, it appears that there are still a lot of duplicate files. I can probably find them fairly easily by scanning, but I am not looking forward to deleting them one by one.

I think the iTunes SDK will be better suited to what I want to do

 

Repairing the damage done by the XML efforts

By searching the Internet, I found numerous articles on how to link to the iTunes COM object. It looked pretty easy – except for one thing. I could not initiate the App object. It kept telling me that: The folder containing “LibraryOut” cannot be found, and is required. Please choose or create a new iTunes library.

I wrestled with this for several hours. I could not find a library.itl file that iTunes seemed to be using. This was supposed to be in MyMusic\iTunes, but the one I found there did not have a late enough data on it and did not seem to change when I made changes to the library. Also, I renamed it and iTunes still seemed to start when invoked by itself. I finally gave up and went out to split some wood and think about it.

I have now decided that the problem must be that when I tried to start iTunes using the output file from my XML efforts, it changed the directory in which it was looking for the íTunesLibrary.itl file as well as the name of the file it was looking for.

Here is what I will do:

• Change registry so that \HKEY_CURRENT_USER\Software\Microsoft\Windows\CurrentVersion\Explorer\ShellFolders\MyMusic now points to “M:\”. Also changed ..\User Shell Folders\My Music.
• Made sure there was a directory named m:\iTunes.
• I note that there is an iTunes Library.itl file in there and it is dated from this morning before I tried to do the import from the XML efforts. I held the shift key down while starting iTunes so that it prompted me to select the library.
• I now note that the date on my iTunes Library.itl is set to current time.
• I tried to run the program again and this time I got a different error.
• I closed iTunes and tried again. This time I was prompted to specify the name of the library which I did. The program now seems to work as expected.
• BUT – it seems that the location information is gone from most of the files. I am going to just empty the library and reload the whole thing.

Getting iTunes reloaded

Well, I got to where I wanted to – at least to step 1.

Here is what I did:

• Cleared the entire library by selecting everything in it and clicking Delete.
• Reloaded it by File -> Add Folder to Library.
• That took many hours.
• I then wrote a program to set all the Ratings to 2 stars (40). I ran it and that worked, but again took a couple of hours.
• I went through the entire list and changed the ratings of the tracks that I liked better than 2 stars. I added some smart playlists.
• I tried to write one of them to a CD (as an “MP3 CD”). It was going to be 200 files with 600+ MB of data. It has been grinding for a couple of hours. I don’t know if it is hung or not.

Conclusion:

iTunes seems to be pretty cool, but it is severely lacking in a couple of aspects. Here is no easy way to:

· Find and remove duplicate music.

· Copy sets of tracks (i.e. a playlist) to another directory for eventual movement to a phone.

· Move files to a different directory.

· Set the rating on a group of files at the same time.

As a result, I expect that I will write a program to assist with using iTunes. I will come up with a rough spec on this and post it.

 

 

Notes on using the iTunes SDK

While waiting around for the library to load, I did some internet searching and found that there is an SDK for iTunes. I registered as a Free apple developer (see PasswordSafe) and downloaded the SDK. Mostly, it consists of a help file. Turns out that the DLL is already installed with iTunes.

Here are some useful sites that I found:

http://www.robertprice.co.uk/robblog/archive/2006/8/iTunes_Now_Playing_In_C_.shtml

http://www.ohscope.com/2009/04/02/itunes-com-api-in-c/

http://www.codeproject.com/KB/cs/itunes_and_net.aspx

http://ratnakarg.wordpress.com/tag/c-itunes-sdk/

The following tells how to iterate over the tracks in the library and assign artwork to them. Should be easy to modify to make other modifications as well.

http://www.diller.ca/?p=40

The following tells how to add names to a playlist

http://www.itunessdk.com/blog/itunes-sdk-examples/

And this one that deletes tracks where the source is no longer available:

http://www.hanselman.com/blog/RemovingDeadTracksDuplicatesThatDontExistFromITunesUsingC.aspx

This one shows how to build a simple viewer/player based on the iTunes library.

http://www.codeproject.com/KB/audio-video/iTuneit.aspx

And this one shows how to make an audio recorder in c# based on iTunes

http://www.codeproject.com/KB/audio-video/MP3WaveAudioRecorder.aspx

Messing with my Music Collection

Today, I am messing with my music collection. The goal was to get it ready for a massive import into iTunes.

 

Previous System

In the past, I tried to organize my music by putting it into a directory with folders named for major genres. Under those were folders named for artists. Under those were albums and the recorded MP3 tracks were in those folders. For singles, I had an “album” named “Singles” or something like that.

My Jukebox program would read this information into a database and allow me to select and play recordings and groups of recordings. This worked well enough, but was not portable to portable devices.

Another problem was that much or most of my music had been recorded from vinyl. There was no metadata in those MP3 files and iTunes and other library systems depended heavily upon that information.

 

The Music Manager Program

Back in the Spring, I wrote a “Music Manager” program. This program placed information from the file structure of my programs into the metadata. This was a huge step forward.

Yesterday, I copied all my music from its original location in the “M” drive (out in the garage) to directory E:\Music for iTunes. It was still organized by album.

I had already used the Metadata Update feature of Music Manager to insert metadata into the music files based on their file names and where they were on the directory tree.

This morning, I used Music Manager to reorganize this information:

1. If the artist name had a comma in it, I used the Artist Name Update feature (which I wrote this morning) to reverse what was before and after the comma. If there is also an ampersand in it, pause for manual intervention.

1. Rerun the Metadata Update feature to update the metadata to reflect the new artist name.

2. Added a feature to remove track number from the song titles. At the same time, I moved the tracks out of the album directories, putting them in directories directly under the artist.

3. I have not yet processed the JPG and XML files or removed the album files.

 

About Play Lists

This is what I learned about Playlists.

• You can export them by right-clicking into a tab separated value text file.
• I want to add a feature to Music Manager that will copy everything from an exported playlist to a particular disk or SD card location.
• Eventually, I will move the library back to the shared drive so that all computers can access it.
• I will need a feature to “Move” a play list so that it can be used on a computer that thinks the master directory of music is at a different location.
• It would be good to know the relationship between a rating in the metadata(If there is one) and the rating in iTunes. Also, what happens if I import a playlist that gives a different rating to a song than how it is already rated in iTunes. What if I import a playlist with songs that are not already present in iTunes. Would this be a way that I could set ratings programmatically?