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 ...
Why your controls need help ids | |
Dialogs, Tab pages, and the like | |
|
Resources |
|
Programmatic element creation |
Menus and toolbars | |
Manually declaring help ids |
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.
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.
(Yet to come)
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=TRUENow, 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 $