Development/Architecture/KDE4/Providing Online Help/pt-br

Arquitetura do KDE - Fornecendo ajuda online

Tornar um programa fácil e intuitivo de usar envolve uma grande variedade de facilidades que são geralmente chamadas de ajuda online. Ajuda online tem vários objetivos parcialmente conflitantes: de um lado, ela deveria dar aos usuários as respostas à pergunta: "Como posso fazer uma determinada tarefa?", por outro lado, deveria ajudar o usuário a explorar o aplicativo e encontrar recursos que ele ainda não conhece. É importante reconhecer que isso só pode ser alcançado através da oferta de vários níveis de ajuda:

• As tooltips (dicas) são pequenas etiquetas que aparecem sobre os elementos da interface de usuário quando o mouse permanece lá por mais tempo. Elas são especialmente importantes para barras de ferramentas, onde ícones não são sempre suficientes para explicar o propósito de um botão.
• A ajuda "O que é isso?" é geralmente uma explicação maior e mais rica de um widget ou um item de menu. Portanto, é mais complicada de usar: Em caixas de diálogo, ela pode ser chamada de duas maneiras: ou pressionando Shift-F1 ou clicando no ponto de interrogação na barra de título (onde o suporte desta última depende do gerenciador de janelas). O ponteiro do mouse, em seguida, se transforma em uma seta com um ponto de interrogação, e a janela de ajuda aparece quando um elemento da interface do usuário foi clicado. A ajuda "O que é isso?" para os itens de menu é geralmente ativada por um botão na barra de ferramentas que contém uma seta e um ponto de interrogação.
  O problema com essa abordagem é que o usuário não pode ver se um widget fornece ajuda ou não. Quando o usuário ativa o botão de ponto de interrogação e não recebe nenhuma janela de ajuda ao clicar em um elemento de interface do usuário, ele vai ficar frustrado muito rapidamente.
  
  A vantagem das janelas de ajuda "O que é isso?" como fornecidas pelo Qt e o KDE é que elas podem conter rich text, isto é, elas podem conter diferentes tipos de fontes, texto negrito e itálico e mesmo imagens e tabelas.

QWhatsThis screenshot

• Finalmente, cada programa deverá ter um manual. Um manual é normalmente visto em khelpcenter ativando o menu de ajuda. Isso significa que, uma aplicação adicional completa aparece e desvia o usuário de seu trabalho. Consequentemente, a consulta ao manual só deve ser necessária se outras facilidades, como tooltips e ajuda o que é isso não são suficientes. Naturalmente, um manual tem a vantagem de que ele não explica aspectos individuais isolados da interface de usuário. Em vez disso, ele pode explicar aspectos do aplicativo em um contexto maior. Manuais para o KDE são escritos usando a linguagem de marcação DocBook.

Do ponto de vista do programador, o Qt fornece uma API para ajuda online fácil para usar. Para atribuir uma dica para widget, simplesmente use o seu método setToolTip().

widget->setToolTip(i18n("This widget does something."))

Se as barras de menu e de ferramentas são criadas usando o action pattern, a string usada como tooltip é derivada do primeiro argumento do construtor do KAction:

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 <b>Qt</b>'s"
                        " rich text engine.<ul>"
                        "<li>Foo</li>"
                        "<li>Bar</li>"
                        "</ul></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