Difference between revisions of "Build Environment Effort/HID List"

Revision as of 14:30, 13 November 2009

The problem

Functions and GUI elements like controls, dialogs or windows in OOo have IDs. Such an ID is called "help ID" (HID). The reason for that is - surprise! - that this ID is used to assign help content to the command or to the GUI element. As an example, a user can activate the "Extended Help" feature in OOo and click on a menu entry, a toolbar button or a button in a dialog. In the latter case a HID is retrieved from the button that was clicked, in the other cases a HID is taken from the command that is bound to the menu entry or toolbar button. The HID is "wrapped" into a help URL and the OOo Help Content Provider is asked to provide help content for this URL.

The HID can also be used to automate OOo: the testtool application uses HIDs to instruct OOo to execute a command or click a button. OOo contains a testtool client component that is instructed by the testtool through a remote bridge. If this client receives a HID for a command, it executes this command using the Dispatch API of the currently active com::sun::star::frame::Frame object (from a user's POV: the currently active document window). If the client receives a HID for a GUI element, it searches for the GUI element with that HID in the currently active TopWindow and performs an action on it.

In the testtool application and the executed test scripts HIDs are strings, sometimes called "long names".

The testtool client in OOo receives the HelpIDs and in case of long names for commands (slots) these names are the same as the internal command names, and so OOo is able to execute these commands using the OOo Dispatch API without any further treatment. On the other hand, HIDs for GUI elements inside OOo are long integer values and OOo doesn't know anything about "long names" for them. In the same way the mentioned help URLs that OOo sends to the help content provider either contain the "long name" of a command or the numerical ID of a GUI element.

Obviously OOo and the HID "customers" speak different languages and so a translator is needed. This translator is the famous (notorious?) "HID list", hid.lst. It defines a mapping from long name to numerical IDs for all GUI elements that have such an ID. If a test script contains a "long name" of a GUI element, the test tool "translates" it into the assigned numerical ID and uses it to address said GUI element. OTOH if a help is requested for a GUI element, the help content provider internally "translates" the ID in the help URL to the "long name" und uses that one to find the content assigned to it. So far, so good.

Unfortunately the hid.lst imposes some problems on our build process:

• it is built at the end of the build, but it is needed in the helpcontent2 module, where it is even committed to the SCM repository. So this list always is not the most current one.
• the testtool can't work correctly if the hid.lst from the CWS is not "delivered" correctly; there is always some confusion and uncertainty which list is the correct one to use
• the HID list generation is an awkward and time consuming process

So it would be desirable to get rid of the hid.lst by letting all participants (help, testtool, OOo itself) work with the same "long names". As commands already work without integer IDs, all changes relate to GUI elements only.

The proposal

GUI elements all derive from the Window class in vcl. This class has two methods that deal with HelpIds:

void SetHelpId ( ULONG nId ); ULONG GetHelpId() const; void SetSmartHelpId (