ui: Help IDs in OpenOffice.org

Project tools

Issue tracker

How do I...

Help IDs in OpenOffice.org

In OpenOffice.org, ever user interface element (a dialog control, a menu item, whatever), needs to have a unique help id. To some extent, you as the developer are responsible for ensuring this ...

Content

Why your controls need help ids
Dialogs, Tab pages, and the like
	Resources
	Programmatic element creation
Menus and toolbars
Manually declaring help ids

Why your controls need help ids

Every visible "item" in the UI must have a unique help id, so help content can be created for it
Automated testing using the QA test tool needs help ids to address certain UI elements within the test scripts.

Dialogs, Tab pages, and the like

Resources

If you declare your dialogs (which from now on will be a placeholder for Dialog, ModalDialog, TabPage, and other such "control containers") using resources, some things are done automatically. For instance, let's consider the following resource:

    ModalDialog RID_DLG_IDENTIFIER
    {
        // ... some stuff
        Text = "the dialog";

        FixedText FT_LABEL
        {
            // Pos/Size/etc. ...
            Text = "the label";
        };
        Control CTL_CONTROL
        {
            // Pos/Size/etc. ...
        };
        OKButton PB_OK
        {
            // Pos/Size/etc. ...
        };
        CancelButton PB_CANCEL
        {
            // Pos/Size/etc. ...
        };
    };

Here, you don't have to care about the fixed text, and the buttons (and even the dialog itself). Simply forget about them: HelpIDs will be generated automatically for them, both for usage with the help system, and for usage with the QA test tool.

However, you need to care for the Control. For this "generic" type (as opposed to the concrete types you usually encounter), you need to manually ensure that it gets a help id, and that this help id is usable for others. See " Manually declaring help ids" below for how you do this.

Programmatic element creation

If you create your UI elements programmatically (e.g. within the C++ source code at runtime), then you also need to declare help ids manually.

Menus and toolbars

(Yet to come)

Manually declaring help ids

If you have an UI element which needs a manually declared help id, the following is necessary:

Find a number: Usually, the project you live in has a file *help*.hrc (or so) where help ids for this project are declared. Find a free place therein, and add a new define such as
```
    #define HID_MY_PERSONAL_HELP_ID         ( base + offset )
          
```
Here, base is usually a project-wide base id, and offset an incrementing number within this project. For instance, if you're within the project svx, base would be HID_SVX_START.

However, care must be taken: Every project does not only have a start for its help ids, but also an end. It's really a project-relative range of ids you are allowed to use. If you leave this range, bad (and hard to notice) things will happen at runtime. In svx, for example, the range you have to respect ends with HID_SVX_END.

Now how can you determine this range, and what do you do when the range is used up? Look at svtools/solar.hrc: This is where all help id ranges (and for that matter, other id ranges such as for resource ids) are defined. If you want to know where your particular range ends, or if you need a new range: Use this file.

To stay with our example: You will find that svtools.hrc defines two ranges for svx, one from HID_SVX_START to HID_SVX_END and one from HID_SVX_EXT0_START to HID_SVX_EXT0_END ...

Assign this number: Set the new help id at your UI element. In a resource file, you may do this with

    HelpId = HID_MY_PERSONAL_HELP_ID;

In C++, you'd do this with

    m_aMyControl.SetHelpId( HID_MY_PERSONAL_HELP_ID );

Export the number: With the previous steps, the help id is already available to the online help. However, your QA engineer will tell you that s/he cannot test the new dialog/tabpage/whatever, because the QA test tool does not have access to your control(s). This is because you need to export the help ids which you declared manually (in opposite to the ones which where declared implicitly during the build).

Every project should have a hidother.src file, usually located in the util directory. Grab it, and add your new id there as follows:
```
    hidspecial HID_MY_PERSONAL_HELP_ID { HelpId = HID_MY_PERSONAL_HELP_ID; };
        
```
If your project does not yet have a hidother.src file just create one. To get it built you also have to insert the following line in your makefile.mk just somewhere below the TRAGET= line:
```
    GEN_HID_OTHER=TRUE
        
```
Now, build the project, and deliver it. When you (now or later) build the instsetoo project, a file called hid.lst will be generated, and placed in <platform>/bin.<minor> (e.g. unxlngi5.pro/bin.m38/hid.lst). This should make your QA engineer happy ....

Last modified: $Date: 2004/09/01 12:14:46 $

The free and open productivity suite