C++/C# Context-Sensitive Help Complications

This forum is for all Flare issues related to the Microsoft HTML Help target.
This target produces "CHM" files in the output.

C++/C# Context-Sensitive Help Complications

Postby GaryUK on Thu Mar 27, 2014 2:55 am

HI,

Apologies if this has been mentioned before but I couldn't search for C# because the search engine deems the word "C" to be to common.

Reading the documentation on context-sensitivity, it seems really simple: create an alias file, export the header files and there you go.

However! We seem to have some bizarre kind of requirement in C# where the Value (the unique numeric identifier) should be in Hex, and it should have 10000, 20000, 30000, 40000, or 50000 added to it, depending on the type of help (menu, dialog, button etc.). Apparently it stems from the MakeHM command, which is used in C# to generate the C header files. In addition, the Identifier must be equal to the C# header file dialog reference, with an "H" in front of it! These header files, which have nothing to do with help header files, contain lists of "actions" (I suppose), which start with "ID" if they refer to a menu item, or "IDD" if they refer to a dialog, "IDR" for something else, and so on. It is this that must be prefixed with an "H" in the help header file.

Has anyone else come across this insane setup, and it is really necessary?

I've had to start with the old help header files and every time I add a new topic I have to find the decimal number of the ID or IDD (etc.) file in the c# header file; convert it to hex; add 10000 or 20000 etc.; insert a line in the help header file with an H in front of the name and put the weird number in the Value column. I might add that the context-sensitive help doesn't actually work unless I use this strange number. It gets a bit tiresome.
GaryUK
Propeller Head
 
Posts: 58
Joined: Thu Aug 29, 2013 12:19 am
Location: Surrey UK

Re: C++/C# Context-Sensitive Help Complications

Postby GaryUK on Thu Mar 27, 2014 8:11 am

I can now shed more light on this. I'm just surprised that there is no mention of it in the Flare Context-sensitive help or the forum.

The Flare CSH documentation is all geared towards calculating a unique Identifier and Value in the help and making it the programmer's problem to tie the number to each dialog, menu item, toolbar button and so on, regardless of who provides the header file.

With the mechanism our developers use, the Context ID (Value column in the flali file) is calculated in the application using a hex conversion of the object id in the header file, plus an increment depending on the type of help (dialog help, menu help, etc.) This enables us to have different ids for pressing F1 whilst hovering over the menu option or toolbar icon, a button and so on, than we do for pressing F1 inside the dialog when it is opened. Usually, the help topic is the same in both cases but it can be different.

Whilst this makes the programmers' life easier, it means that I have to use the numbers they calculate and, for me, there is no automation as the Flare CSH documentation suggests. The tables are turned and the allure of automatically incremented topic Values is dashed. I have to type in the weird values in the Value column of the alias file. The way the documentation approaches it from a "Who provides the Header file" perspective is not sufficient. There is no mention of overriding the Value column - except to say: "12. (Optional) If you want to change the numerical value for an identifier, click twice in the Value cell and type the new number." It appears from the documentation that even if the developer provides the file, you control the number. Not true. Whether it is calculated or hard-coded, the developer is likely to give you the file with the numbers set in concrete.

Apparently, this calculated Value is a feature of context help in Windows, and is designed for use with the MakeHM Tool, which creates .h files containing a line for each variation of the object. I am surprised there is no mention of it elsewhere.

For the benefit of others who have come this route, the most astonishing thing to me was that the Identifier column in the alias file means absolutely nothing. You can type anything in there (as long as it is unique) and CSH will still work. However, we still put something relevant. Similarly, we have done away with the MakeHM header file import stage. When we need a new context ID, we just look at the header file, calculate the values we need and add them to the alias file. The header file that MakeHM creates isn't used by the compiled CHM or the application. The application uses the same calculation to open the required topic - it doesn't look it up in the header file.

I hope this helps someone else and isn't too cryptic.
GaryUK
Propeller Head
 
Posts: 58
Joined: Thu Aug 29, 2013 12:19 am
Location: Surrey UK

Re: C++/C# Context-Sensitive Help Complications

Postby Dave Lee on Thu Mar 27, 2014 9:33 am

I'm not quite sure I follow your process.

If your developers are producing a header file with all the unique identifier/value pairs, then you don't need to type in any of these values in the alias file editor. All you need to do is add the header (.h) file to the Flare project, and the alias file editor will display the identifier/value pairs that it finds in your header file. The only thing you need to do is select the identifier/value, and assign it to a topic (at this point the identifier/value and topic link are added to the alias file).

Our developers generate the header file (.h) for one of our projects. We use the identifier string (rather than the value) in our help calls, so they generate a header file where the identifier is based on the full form name (so it's unique), and the value is just an incremented number (as this isn't used).
When they produce a new header file, we just replace the old version in our project. Any new identifiers will show up in the alias editor as 'unassigned identifiers', which we can then assign to to a topic.
Dave Lee
Master Propellus Maximus
 
Posts: 5368
Joined: Mon Mar 05, 2007 8:33 am
Location: UK

Re: C++/C# Context-Sensitive Help Complications

Postby GaryUK on Wed Apr 02, 2014 2:31 am

I see what you mean. That sounds a lot easier. Thanks Dave, you've made the concepts much clearer to me.

The problem in our case is that we have different types of help , such as pressing F1 whilst hovering over the menu item vs clicking on the menu item to open the dialog and then pressing F1. Similar features exist for toolbar buttons and other objects. In the new version of our help, 9 times out of 10 these point top the same topic, but not always. However, traditionally, the menu item help topics were more like teasers and the dialog help was more detailed (not great for single-sourcing). This required several tiers of context ids, even though there was only one dialog. It has resulted in the production of "intermediate" header files which contain several context ids for each dialog box, the ids of which were calculated by this bizarre algorithm.

Wisely or not, I was given the responsibility for these "intermediate" header files in the application because the developers don't use them. So, rather than check them out, amend them and put them back, I just calculate the context id myself, add it to the alias file and compile the CHM. The application seems to work on the calculation rather than the header files anyway. I haven't built the application in ages and it still works when I add new topics.
GaryUK
Propeller Head
 
Posts: 58
Joined: Thu Aug 29, 2013 12:19 am
Location: Surrey UK


Return to Microsoft CHM Help

Who is online

Users browsing this forum: No registered users and 7 guests