April 2008 - Posts

• HTML help from within WPF applications

  I don't know if you have noticed already, but the WPF framework doesn't contain any class for providing context sensitive help in a WPF application. I am not certain why this is, but I doubt that they simply forgot about it.  My (non educated, actually more like 'complete' ) guess: Vista was supposed to have included some new help system (based on XML I believe), which didn't ship in the end product.  I think the WPF designers wanted to use this, but when it got dropped, had no time to find a replacement.  If anyone knows the real reason why nothing was done in the help department, I would love to know about it. Anyway, A couple of months ago, I had a project that needed this feature, so I set about implementing my own version, based on the Help component provided for windows forms (for the methods at least). You can find the end result in my ControlFramework lib. Using the code There are basically 2 different operations that need to be done for incorporating context sensitive help.  You need to assign the help topics to your controls and you need to set up your application for displaying a help file. Here's a more detailed explanation: Setting up the application: add a Help control to your application (through a field (in the main window/application object) or as a resource in xaml) and assign it a default help file. ex: help.DefaultHelpFile = "help1.chm"; Note: Thanks to Sam Jack for letting me know that some systems require a full path to the help file for it to display properly.  So if your help file is missing icons, check if you are using a relative or absolute path to the help file. Add a CommandBinding to the control handling help (usually the main window) for the Help command and provide the CanExecute and Executed events. ex: <CommandBinding Command="Help" CanExecute="HelpCanExecute" Executed="HelpExecuted"/> Implement the commandBinding's CanExecute event by checking if there is a control that has keyboard focus. private void HelpCanExecute(object sender, CanExecuteRoutedEventArgs e) { e.CanExecute = Keyboard.FocusedElement is UIElement; } Implement the commandBinding's Executed event by calling "Help.ShowHelpFor(Keyboard.FocusedElement as UIElement)".  This will show the help topic assigned to the control that currently has keyboard focus. void HelpExecuted(object aSender, ExecutedRoutedEventArgs e) { help.ShowHelpFor(Keyboard.FocusedElement as UIElement); } Assigning help info to your controls: This is done using attached properties Topic: This property will assign  a help topic to the control and all it's children.  The value should be the name of the html file that contains the help for the control. This property is required for all controls that need to display a help page.  Note that it is an inherited property, so if you have a single help page for a group of controls (such as a window or Page), you only need to assign the attached property 'Topic' to the container (aka the Window or Page), all other controls will inherit the value. Ex: <Button jc:Help.Topic="button.html"> Button with help </Button> HelpFile: This is an optional attached property that you can use which provides a feature that wasn't found in the previous (WinForms) version of Help. It allows you to declare a help file to use other than the default one assigned to the Help control.  So you can use multiple help files from 1 application. I don't know if this is a very useful feature, but I was thinking in the direction of plug-ins: if your application can display custom xaml somehow, external writers will still be able to provide help for there work without having to hack into you help file or building up a custom help system.  they simply provide there own help file which will be displayed instead of the default one when help is activated on there xaml.  (noted disadvantage: you don't have a global help file, but multiple files). <TextBox jc:Help.Topic="textbox.html" jc:Help.HelpFile="Help2.chm"> Text with help from other file </TextBox> That pretty much covers the basics of the Help control.  There are also some useful functions that work similar to those found in the WinForms version. You have 'ShowHelp()' to show the default help file and "ShowHelpTopic(string TopicID)" to display a specific topic (the id is the name of the html page).   I believe "ShowHelpContents()", "ShowHelpSearch()" and "ShowHelpIndex()" are pretty self explanatory. The Next entry will probably be about how I implemented all this (You'll be amazed how simple it all was thanks to Microsoft). Posted Apr 08 2008, 02:44 PM by Bragi with 11 comment(s)

• Prologue

  Well, I guess I have finally succeeded in setting up my blog, so I should probably start writing about stuff. Anyway, I am Belgian, so English isn't my native tongue.  If you find any grammar or typing error (I'm sure you already have), don't shoot me, blame the TV, which for years, was my primary English tutor.  These days, it's become the Internet, so no improvement there. I have a ton of interesting topics waiting to be written about, they just need to be pushed out of my head onto the keyboard, a hard task for someone who doesn't consider himself fluent in natural languages. So, if you believe a little push is needed, drop me a mail. Upcoming topics will be about some of the free controls I have created (you know, the usual stuff like the itch they scratched, how they should be used, techniques that accompany them,...).  First topics will probably be about help integration, static Treeview items combined with itemsSource, breadcrumbs,.... Oh, before I forget, about me: I'm the lead developer at JaStDev, an upstart focused on WPF stuff, so the blog will be mostly about xaml. Posted Apr 04 2008, 02:40 PM by Bragi with no comments