[Cin] Cinelerra context help - a complete implementation

[Georgy Salnikov]

Hi all,

This new implementation of Cinelerra context help can be requested from
almost any Cinelerra window or subwindow by pointing with the mouse cursor
on the GUI element of interest and pressing Alt/h. That HTML manual page
will be shown via the configured web browser, which is assumed as most
relevant to the GUI element being currently under the mouse pointer. For
more information see issue 568 on the bugtracker:
https://www.cinelerra-gg.org/bugtracker/view.php?id=568

How to install, configure and demonstrate the new functionality
---------------------------------------------------------------

1. Apply the patch (see BT568) to the CinGG source tree:
https://www.cinelerra-gg.org/bugtracker/file_download.php?file_id=775&type=bug

2. After patching one new file appears: doc/ContextManual.pl. This is a perl
script. It must be given exetutable permissions.

3. Build and install CinGG as usual.

4. The prerequisite for context help is CinelerraGG HTML manual. After
installation of CinGG itself, place the complete unchanged directory
CinelerraGG_Manual, as it was produced by latex2html from the manual
package, into the 'doc' directory of the installed Cinelerra package. This
will be the directory bin/doc/CinelerraGG_Manual if CinGG was built
--with-single-user. The script ContextManual.pl should appear after
installation also here, in bin/doc.

5. In principle, this is sufficient. Nevertheless, the
bin/doc/ContextManual.pl script can be configured further. Look in the
script text. You can define your preferable web browser, or redefine it to
'echo' for debug purposes. There are also some predefined HTML pages for
Contents and Index, and several explicitly rewritten keyphrases. However,
there can be hardly a need to redefine anything except the name of the
browser executable.

6. Start Cinelerra and open a project with some assets, effects, keyframes,
etc. May be, open some additional Cinelerra dialog windows, plugin settings,
etc. Try to point with the mouse on different GUI elements or on empty
spaces in different windows and press Alt/h. You should get different manual
pages in the browser (if browser was not yet started, it should start
automatically).

How it works, from the user's point of view
-------------------------------------------

The hotkey to request context help is Alt/h. Why? A simple 'h' does not fit:
in text fields it has to input the letter 'h'. So is Shift/h: it would mean
the capital letter 'H'. Ctrl/h and Ctrl/Shift/h are also not suitable: it is
<Backspace>. Something like <F1> would be also not good, <Fn> are already
utilized in Compositor. Unlike these all, Alt/h seems to be a good hotkey
and, to the best of my knowledge, it is not assigned to anything else
throughout the whole Cinelerra code.

What particular help page is shown, depends on the mouse cursor location
while Alt/h is pressed. Usually, when the mouse is located in some window or
dialog, the help page related to the functionality of this window or dialog
is shown. In this case the mouse can point either on some widget, or on an
empty area in the window.

In Cinelerra GUI there are several rich loaded windows, Timeline and
Compositor for example. In such a case different help pages can be requested
depending on the particular GUI element under the mouse. For example,
pressing Alt/h while pointing on the Autos curve in a track would show help
on automation keyframes, pointing on the Overlay mode button in the patchbay
would show help on overlays, pointing on the camera control in Compositor
would show help on camera and projector.

If no context dependent help page is found, the manual page of Contents
itself is shown. Most probably it means, that either the meaning of this
window is obvious (so is the 'Tip of the day' window, for example), or it is
not (yet) documented.

Requesting context help for plugins
-----------------------------------

There are following possibilities to request help page for the particular
plugin of interest.

1) Pressing Alt/h with mouse in the dialog window of plugin settings

2) Pressing Alt/h while pointing with the mouse on the plugin bar in a track
(or transition bar, or transition icon)

3) Pressing Alt/h while pointing on the plugin name (icon) in the Resources
window. If plugin tooltips are on, help for the highlighted (plugin under
mouse) is shown. If plugin tooltips are off, help for the selected plugin is
shown (it is made so, because in the latter case it would be difficult to
figure out, without a visual feedback, which particular item is currently
under mouse).

4) Pressing Alt/h while pointing on the plugin name in the Attach Effect
dialog

Requesting context help on Contour Shuttle
------------------------------------------

Contour Shuttle has no Alt/h, yeh. Nevertheless, its help page can be
requested by simultaneous pressing both Alt keys (left and right) on the
keyboard followed by pressing any button on the Contour Shuttle. Here,
pressing both Alt keys is necessary due to the way of X11 to track the
status of modifiers. To cancel this mode, press any single modifier key
(Alt, Ctrl or Shift) once.

_______________________________________________________________________________

Georgy Salnikov
NMR Group
Novosibirsk Institute of Organic Chemistry
Lavrentjeva, 9, 630090 Novosibirsk, Russia
Phone   +7-383-3307864
Email   sge at nmr.nioch.nsc.ru
_______________________________________________________________________________