Just like in most other applications, pressing the F1 key in CODESYS brings up the Online Help viewer and displays appropriate assistance to the current user's context. So if you have got your own plug-in in the one hand, and a CHM file with the corresponding help topics on the other, the question is how to bring them together. This article shows how.

Possibilities

There are several possibilities to link your own plug-in component to Online Help.

• Commands (i.e. implementations of _3S.CoDeSys.Core.Commands.ICommand) can be bound to context sensitive help. That means if the user hilights a command in the menu bar or in the toolbar, pressing F1 can display information about this command.
• Controls (i.e. classes deriving from System.Windows.Forms.Control), including modal dialog boxes, can also be bound to context sensitive help. That means if a control currently has got the keyboard focus, pressing F1 can display information about that control. If the focused control does not have any information about context sensitive help, the parent control hierarchy is considered.
• Entire plug-ins can also be bound to context sensitive help. This is something like a fallback strategy if the two methods above do not yield a search result.
• Finally, message boxes displayed by our message service implementation can also be bound to context sensitive help.

Implementation Samples

Although the lookup algorithm is very powerful, using the concepts in your code is typically very easy. This chapter shows you the typical use cases. A detailed description of the lookup algorithm is given later on.

Simple URL lookup

Most of the time, pointing to a particular command (within menu or toolbar) or control and pressing F1 will display an exact help page URL that corresponds to that command or control. This can be accomplished by attaching an attribute to your implementing class.

 

[TypeGuid("...")]
[AssociatedOnlineHelpTopic("MyPlugIn.chm::/MyCommand.htm")]
public class MyCommand : IStandardCommand { }

[AssociatedOnlineHelpTopic("MyPlugIn.chm::/MyControl.htm")]
public class MyControl : Control { }

If you either miss to decorate all your controls and commands in your plug-in with those attributes,
or if you do not like to do so, there is also a chance to bind your entire plug-in component to a help
page URL. This URL is used as fallback if none of the above attributes could be found at the time of invocation.

Message Boxes

A message box can also be bound to context sensitive help, like so:

if (SystemInstances.Engine.MessageService is IMessageServiceWithOnlineHelp) 

((IMessageServiceWithOnlineHelp)SystemInstances.Engine.MessageService).SetOnlineHelpTopicForNextCall("MyPlugIn.chm::/MyMessageBox.htm"); 
SystemInstances.Engine.MessageService.Error(...);

 

The lookup algorithm

Typically, the code snippets presented above simply work as expected in practice, but for the sake of completeness we will also describe the lookup algorithm for reference.

• If a command is currently selected in the menu bar or in one of the toolbars, and that command has got a context sensitive help association (1), display online help (2) for that command.
• If the currently focused control has got a context sensitive help association (1), display online help (2) for that control. If it does not, recursively check the parent window hierarchy.
• If a message box is currently displayed which is associated with a help page URL, display that help page.
• If a command is currently selected in the menu bar or in one of the toolbars, and the assembly containing that implementation has got a default context sensitive help association (AssociatedOnlineHelpDefaultTopicAttribute), display that default help page URL.
• If the assembly which contains the implementation of the currently focused control has got a default context sensitive help association (AssociatedOnlineHelpDefaultTopicAttribute), display that default help page URL. If it does not, recursively check the parent window hierarchy.
• Display the online help homepage.

(1) The check whether an entity has got a context sensitive help association is performed as follows: The condition is true if that particular class meets one of the following criteria:

• The class implements the IHasAssociatedOnlineHelpTopic interface, and its GetOnlineHelpUrl() method returns a non-null value.
• The class implements the IHasAssociatedOnlineHelpTopic interface, and its GetOnlineHelpKeyword() method returns a non-null value.
• The class has got a AssociatedOnlineHelpTopicAttribute attribute.

(2) Displaying online help for a certain entity works as follows:

• If the class implements the IHasAssociatedOnlineHelpTopic, its GetOnlineHelpUrl() method is called. If it returns a non-null value, the returned help page URL is displayed.
• If the class implements the IHasAssociatedOnlineHelpTopic, its GetOnlineHelpKeyword() method is called. If it returns a non-null value, a keyword lookup with the returned value is triggered and the results are displayed.
• If the class has got the AssociatedOnlineHelpTopicAttribute attribute, the help page with the corresponding URL is displayed.