Development/Architecture/KDE4/Providing Online Help (es)

Arquitectura de KDE - Suministro de ayuda online

La construcción de un programa facil e intuitivo de usar implica un amplio rango de facilidades que por lo general se llama ayuda online. La ayuda online persigue varios objetivos parcialmente contradictorios: por un lado, debería dar respuesta a la pregunta del usuario "¿Como puedo realizar una cierta tarea?", pero por el otro lado debería ayudar al usuario que explora la aplicación y se encuentra con caracteristicas que aun desconoce. Es importante reconocer que esta situacion sólo puede ser tratada ofreciendo varios niveles de ayuda:

• Los tooltips son las pequeñas etiquetas que aparecen sobre los elementos de la interfaz de usuario cuando el ratón permanece sobre estos durante un periodo de tiempo largo. Son especialmente importantes en las "toolbars", donde los iconos no siempre son suficientes para explicar el cometido de un botón.

• La ayuda "¿Qué ese esto?" normalmente es una extensa explicación de un widget o de un item de un menu. Tambien es mas patosa de usar: el los dialogos, puede ser invocada de dos maneras: presionando Shift+F1 o pulsando sobre el signo de interrogación en la barra de título (donde el soporte de este depende del administrador de ventanas). Entonces el puntero del ratón se convierte en una flecha con un signo de interrogación, y cuando se hace clic sobre un elemento de la interfaz de usuario aparece la ventana de ayuda. La ayuda "¿Que es esto?" de los items del menu se activa normalmento mediante un boton en la "toolbar", que contiene una flecha y un signo de interrogación.
  El problema de este método es que el usuario no puede saber cuando un widget proporciona ayuda o no. Cuando el usuario activa el boton de signo de interrogación, y no obtiene ninguna ayuda cuando pulsa sobre un elemento de la interfaz de usuario, se frustrará rapidamente.
  
  La ventaja de la ayuda "¿Qué es esto?" proporcionada por Qt y KDE es que puede contener texto enriquecido, es decir, puede contener diferentes tipos de letra, texto cursiva y negrita e incluso imagenes y tablas.

QWhatsThis screenshot

• Finally, every program should have a manual. A manual is normally viewed in khelpcenter by activating the help menu. That means, a complete additional application pops up and diverts the user from his work. Consequently, consulting the manual should only be necessary if other facilities like tooltips and what's this help are not sufficient. Of course, a manual has the advantage that it does not explain single, isolated aspects of the user interface. Instead, it can explain aspects of the application in a greater context. Manuals for KDE are written using the DocBook markup language.

From the programmer's point of view, Qt provides an easy to use API for online help. To assign a tooltip to widget, simply use its setToolTip() method. widget->setToolTip(i18n("This widget does something."))

If the menu bars and tool bars are created using the action pattern, the string used as tooltip is derived from the first argument of the KAction constructor:

action = new KAction(i18n("&Delete"), "editdelete",

                    SHIFT+Key_Delete, actionCollection(), "del")

Here it is also possible to assign a text which is shown in the status bar when the respective menu item is highlighted:

action->setStatusText(i18n("Deletes the marked file"))

The API for "What's this?' help is very similar. In dialogs, use the following code:

widget->setWhatsThis(i18n("<qt>This demonstrates Qt's"

" rich text engine.

" "
• Foo
" "
• Bar
" "

</qt>"))

For menu items, use action->setWhatsThis(i18n("Deletes the marked file"))

The invocation of khelpcenter is encapsulated in the KToolInvocation class. In order to show the manual of your application, just use the static method:

KToolInvocation::invokeHelp()

This displays the first page with the table of contents. When you want to display only a certain section of the manual, you can give an additional argument to invokeHelp() determining the anchor which the browser jumps to.

Initial Author: Bernd Gehrmann