Development/Architecture/KDE4/Providing Online Help (es): Difference between revisions

From KDE TechBase
m (translation to spanish)
 
({{Proposed_deletion|reason=Page was created before the current translation system.}})
 
(12 intermediate revisions by 3 users not shown)
Line 1: Line 1:
{{Proposed_deletion|reason=Page was created before the current translation system.}}
'''Arquitectura de KDE - Suministro de ayuda online'''
'''Arquitectura de KDE - Suministro de ayuda online'''


La construcción de un facil e intuitivo de usar implica un amplio rango de  
La construcción de un programa fácil e intuitivo de usar implica un amplio rango de  
facilidades que por lo general se llama ayuda online.
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 características que aun desconoce. Es importante reconocer que esta situación sólo puede ser tratada ofreciendo varios niveles de ayuda:


Making a program easy and intuitive to use involves a wide range of
*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.
facilities which are usually called online help. Online help has several,
partially conflicting goals: on the one, it should give the user answers
to the question "How can I do a certain task?", on the other hand it
should help the user exploring the application and finding features he
doesn't yet know about. It is important to recognize that this can only
be achieved by offering several levels of help:


*Tooltips are tiny labels that pop up over user interface elements when the mouse remains there longer. They are especially important for tool- bars, where icons are not always sufficient to explain the purpose of a button.
* La ayuda "¿Qué ese esto?" normalmente es una extensa explicación de un widget o de un ítem de un menú. También es mas patosa de usar: el los diálogos, 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 ítems del menú se activa normalmente mediante un botón en la "toolbar", que contiene una flecha y un signo de interrogación.<br/>El problema de este método es que el usuario no puede saber si un widget proporciona ayuda o no. Cuando el usuario activa el botón de signo de interrogación y pulsa sobre un elemento de la interfaz de usuario y no obtiene ayuda, se frustrará rápidamente.<br/><br/>La ventaja de la ayuda "¿Qué es esto?" proporcionada por Qt y KDE es que puede contener [http://doc.trolltech.com/4.4/richtext.html texto enriquecido], es decir, puede contener diferentes tipos de letra, texto cursiva y negrita e incluso imágenes y tablas.
*"What's this?" help is usually a longer and richer explanation of a widget or a menu item. It is also more clunky to use: In dialogs, it can be invoked in two ways: either by pressing Shift-F1 or by clicking on the question mark in the title bar (where the support of the latter depends on the window manager). The mouse pointer then turns into an arrow with a question mark, and the help window appears when a user interfact element has been clicked. "What's this?" help for menu items is usually activated by a button in the toolbar which contains an arrow and a question mark. <br/>The problem with this approach is that the user can't see whether a widget provides help or not. When the user activates the question mark button and doesn't get any help window when clicking on a user interface element, he will get frustrated very quickly.<br/><br/> The advantage of "What's this?" help windows as provided by Qt and KDE is that they can contain [http://doc.trolltech.com/4.4/richtext.html rich text], i.e. the may contain different fonts, bold and italic text and even images and tables.
<br/>
[[Image:Qt3-whatsthis.png|frame|center|QWhatsThis screenshot]]
[[Image:Kde4-queEsEsto.png‎|frame|center|Captura de pantalla ¿Qué es esto?]]
*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 [http://i18n.kde.org DocBook] markup language.
<br/>
*Finalmente, cada programa debería tener un manual. Normalmente se consulta un manual en khelpcenter, activando el menú de ayuda. Esto significa cargar una nueva aplicación y desviar la atención del usuario. Por tanto, la consulta del manual solo debería ser necesaria si las otras facilidades como los tooltips o la ayuda "¿Qué es esto?" no son suficientes. Por supuesto, un manual tiene la ventaja de que no explica un aspecto aislado de la interfaz de usuario, sino que explica aspectos de la aplicación en un contexto mas amplio. Los manuales de KDE están escritos usando el lenguaje de etiquetado [http://i18n.kde.org DocBook].  


From the programmer's point of view, Qt provides an easy to use API for online
Desde el punto de vista del programador, Qt proporciona una forma fácil de usar la API para la ayuda online. Para asignar un tooltip a un widget, simplemente usa el método setToolTip():
help. To assign a tooltip to widget, simply use its setToolTip() method.
<syntaxhighlight lang="cpp-qt">
<code cppqt3>
widget->setToolTip(i18n("Este widget hace algo."))
widget->setToolTip(i18n("This widget does something."))
</syntaxhighlight>
</code>


If the menu bars and tool bars are created using the [[../Action Pattern|action pattern]], the string used as tooltip is derived from the first argument
Si la barra de menú y la barra de herramientas han sido creadas usando [[../Action Pattern|action pattern]], la cadena usada como tooltip se hereda del primer argumento del constructor [http://api.kde.org/4.x-api/kdelibs-apidocs/kdeui/html/classKAction.html KAction]:
of the [http://api.kde.org/4.x-api/kdelibs-apidocs/kdeui/html/classKAction.html KAction] constructor:


<code cppqt3>
<syntaxhighlight lang="cpp-qt">
action = new KAction(i18n("&Delete"), "editdelete",
action = new KAction(i18n("&Delete"), "editdelete",
                     SHIFT+Key_Delete, actionCollection(), "del")
                     SHIFT+Key_Delete, actionCollection(), "del")
</code>
</syntaxhighlight>


Here it is also possible to assign a text which is shown in the status bar when the  respective menu item is highlighted:
Aquí también es posible asignar un texto que es mostrado en la barra de estado cuando el respectivo ítem del menú es "highlighted":


<code cppqt3>
<syntaxhighlight lang="cpp-qt">
action->setStatusText(i18n("Deletes the marked file"))
action->setStatusText(i18n("Borrar el fichero seleccionado"))
</code>
</syntaxhighlight>


The API for "What's this?' help is very similar. In dialogs, use the following
La Api para la ayuda "¿Qué es esto?" es muy similar. En los diálogos, usa el siguiente código:
code:


<code cppqt3>
<syntaxhighlight lang="cpp-qt">
widget->setWhatsThis(i18n("<qt>This demonstrates <b>Qt</b>'s"
widget->setWhatsThis(i18n("<qt>This demonstrates <b>Qt</b>'s"
                         " rich text engine.<ul>"
                         " rich text engine.<ul>"
Line 46: Line 41:
                         "<li>Bar</li>"
                         "<li>Bar</li>"
                         "</ul></qt>"))
                         "</ul></qt>"))
</code>
</syntaxhighlight>


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


The invocation of khelpcenter is encapsulated in the
Para los ítems del menú, usa:
[http://api.kde.org/4.x-api/kdelibs-apidocs/kdecore/html/classKToolInvocation.html KToolInvocation]
<syntaxhighlight lang="cpp-qt">
class. In order to show the manual of your application, just use the static method:
action->setWhatsThis(i18n("Borrar el fichero seleccionado"))
</syntaxhighlight>


<code cppqt3>
La invocación de khelpcenter esta encapsulada en la clase [http://api.kde.org/4.x-api/kdelibs-apidocs/kdecore/html/classKToolInvocation.html KToolInvocation]. Para mostrar el manual de tu aplicación, usa simplemente el método estático:
<syntaxhighlight lang="cpp-qt">
KToolInvocation::invokeHelp()
KToolInvocation::invokeHelp()
</code>
</syntaxhighlight>
 
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.


Este código muestra la primera página con la tabla de contenidos. Cuando quieras mostrar solo una sección del manual, puedes invocar a invokeHelp() con un argumento adicional que determina la sección a saltar.


''Initial Author:'' [mailto:[email protected] Bernd Gehrmann]
''Initial Author:'' [mailto:[email protected] Bernd Gehrmann]

Latest revision as of 20:25, 11 October 2023

 
Proposed for Deletion
This page has been proposed for deletion for the following reason:

Page was created before the current translation system.

Arquitectura de KDE - Suministro de ayuda online

La construcción de un programa fácil 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 características que aun desconoce. Es importante reconocer que esta situación 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 ítem de un menú. También es mas patosa de usar: el los diálogos, 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 ítems del menú se activa normalmente mediante un botón 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 si un widget proporciona ayuda o no. Cuando el usuario activa el botón de signo de interrogación y pulsa sobre un elemento de la interfaz de usuario y no obtiene ayuda, se frustrará rápidamente.

    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 imágenes y tablas.


Captura de pantalla ¿Qué es esto?


  • Finalmente, cada programa debería tener un manual. Normalmente se consulta un manual en khelpcenter, activando el menú de ayuda. Esto significa cargar una nueva aplicación y desviar la atención del usuario. Por tanto, la consulta del manual solo debería ser necesaria si las otras facilidades como los tooltips o la ayuda "¿Qué es esto?" no son suficientes. Por supuesto, un manual tiene la ventaja de que no explica un aspecto aislado de la interfaz de usuario, sino que explica aspectos de la aplicación en un contexto mas amplio. Los manuales de KDE están escritos usando el lenguaje de etiquetado DocBook.

Desde el punto de vista del programador, Qt proporciona una forma fácil de usar la API para la ayuda online. Para asignar un tooltip a un widget, simplemente usa el método setToolTip():

widget->setToolTip(i18n("Este widget hace algo."))

Si la barra de menú y la barra de herramientas han sido creadas usando action pattern, la cadena usada como tooltip se hereda del primer argumento del constructor KAction:

action = new KAction(i18n("&Delete"), "editdelete",
                     SHIFT+Key_Delete, actionCollection(), "del")

Aquí también es posible asignar un texto que es mostrado en la barra de estado cuando el respectivo ítem del menú es "highlighted":

action->setStatusText(i18n("Borrar el fichero seleccionado"))

La Api para la ayuda "¿Qué es esto?" es muy similar. En los diálogos, usa el siguiente código:

widget->setWhatsThis(i18n("<qt>This demonstrates <b>Qt</b>'s"
                        " rich text engine.<ul>"
                        "<li>Foo</li>"
                        "<li>Bar</li>"
                        "</ul></qt>"))


Para los ítems del menú, usa:

action->setWhatsThis(i18n("Borrar el fichero seleccionado"))

La invocación de khelpcenter esta encapsulada en la clase KToolInvocation. Para mostrar el manual de tu aplicación, usa simplemente el método estático:

KToolInvocation::invokeHelp()

Este código muestra la primera página con la tabla de contenidos. Cuando quieras mostrar solo una sección del manual, puedes invocar a invokeHelp() con un argumento adicional que determina la sección a saltar.

Initial Author: Bernd Gehrmann