8 respuestas en este tema

[Héctor Randolph]

Siempre es deseable que nuestras aplicaciones tengan suficientes pantallas de ayuda. Será aún mejor si la ayuda es sensible al contexto, es decir, si el programa tiene la capacidad de mostrar las pantallas de ayuda adecuadas al presionar la tecla F1 dependiendo del componente que se encuentra activo.

En este manual veremos como integrar a nuestros programas hechos en Lazarus los archivos de ayuda.

¿Cómo funciona la ayuda en Lazarus?

El sistema de ayuda de la LCL (Lazarus Component Library) se compone principalmente de dos partes:

• Las bases de datos de ayuda que contienen una correspondencia entre las palabras clave y los archivos de ayuda.
  
• Los visores de ayuda que son invocados por las bases de datos de ayuda para mostrar las páginas al usuario.

Estas partes se encuentran representadas dentro de la LCL a través de los siguientes componentes:

• El componente THelpDatabase administra el contenido que puede ser una colección de páginas web, o archivos xml de fpdoc o un archivo chm.
  
• EL componente THTMLBrowserHelpViewer muestra el contenido de la ayuda, por ejemplo, un visor para el tipo "mime" text/html puede lanzar un navegador web.

Cuando se hace una petición de ayuda, la LCL hace una consulta sobre cada uno de los THelpDatabase registrados y cada uno de ellos puede devolver una lista de entradas.

La LCL solicita a la base de datos que muestre la ayuda para una entrada, la base de datos extrae la información y entonces pregunta a la LCL por un visor que soporte el tipo mime del contenido. Entonces el visor muestra la ayuda.

Configurando la ayuda para nuestra aplicación.

Para seguir este ejemplo debemos crear una nueva aplicación desde el menú Archivo->Nuevo



En el formulario del Wizard seleccionamos Proyecto->Aplicación



Los componentes THelpDatabase y THTMLBrowserHelpViewer se encuentran en la sección System de la paleta de componentes.



Ahora dentro del formulario principal colocamos un componente THelpDatabase y se establecen las siguientes propiedades:

• AutoRegister := True;
  Para que la LCL considere esta base de datos cuando se hace una petición de ayuda.
  
• KeywordPrefix:= 'HTML/'
  Todas las palabras clave deberán comenzar con este prefijo (solamente como ejemplo se eligió el prefijo 'HTML/'
  
• 
  BaseURL:='file://ayuda/'
  Contiene la url base en donde se encuentran los archivos de ayuda. En este ejemplo se hace referencia a una carpeta llamada 'ayuda' en la ruta relativa del ejecutable. Se pueden colocar rutas absolutas del tipo 'file:///C:\mi_programa\ayuda' o 'file:///usr/lib/ayuda/'; También es posible colocar una url del tipo: 'http://www.mis_paginas.com/ayuda'

Colocamos un componente THTMLBrowserHelpViewer en el formulario y establecemos las siguientes propiedades:

• AutoRegister := True;
  Para indicar que se debe utilizar este visor para mostrar la ayuda en el navegador de internet.

Con esto hemos terminado la primera parte del trabajo.

[Héctor Randolph]

Implementando la ayuda para los controles en nuestros formularios

Ya hemos configurado nuestro sistema de ayuda, ahora solo resta colocar las referencias en cada uno de nuestros componentes. Para ilustrar la manera de hacerlo, en este ejemplo vamos a colocar un TEdit, un TMemo y un TButton.

Primero colocamos un TEdit y modificamos las siguientes propiedades:

• HelpType:= htKeyword
  Para indicar que la entrada en la base de datos es una palabra clave.
• HelpKeyword:='HTML/edit1.html'
  En este caso la palabra clave corresponde al nombre del archivo html que contiene la ayuda para nuestro componente, debemos recordar que anteriormente hemos colocado a nuestra base de datos el prefijo 'HTML/', por esta razón nuestra palabra clave será el prefijo + el nombre del archivo.

Haremos algo similar con el componente TMemo y estas son sus propiedades:

• HelpType:= htKeyword
• HelpKeyword:='HTML/memo1.html'

Esto mismo se aplica para cualquier componente de nuestra aplicación aún estando en otro formulario. Esto es posible ya que hemos registrado tanto la base de datos de ayuda como el visor y serán válidos de manera global. Es posible registrar más de una base de datos (en otros formularios por ejemplo) y también es posible eliminar esos registro.

Para ilustrar como se puede llamar directamente por comandos a una sección de nuestros archivos de ayuda,
vamos a utilizar un TButton para mostrar la tabla de contenidos. Para esto vamos a utilizar la función ShowHelpOrErrorForKeyword.

Nota: debemos añadir la unidad HelpIntfs que contiene la función ShowHelpOrErrorForKeyword.

Colocamos el siguiente código en el evento onClick del TButton:

delphi

procedure TForm1.Button1Click(Sender: TObject);
begin
  ShowHelpOrErrorForKeyword('','HTML/index.html');
end;

Esto suponiendo que el archivo index.html muestra la tabla de contenidos.


Construyendo los archivos de ayuda en HTML.

En este ejemplo hemos utilizados tres archivos html que son:

• edit1.html Muestra la ayuda para el componente TEdit
• memo1.html Muestra la ayuda para el componente TMemo
• index.html Muestra la tabla de contenidos

El contenido de estos archivos podría ser de la siguiente manera:

index.html

html5

<html>
<body>
  <p>
  Este es un ejemplo de archivo de ayuda para una aplicaci&oacute;n en <strong>Lazarus</strong>
  </p>
  
  <h1>Tabla de contenidos:</h1>
 
  <ul>
    <li><a href="edit1.html">Componente Edit1</a></li>
	<li><a href="memo1.html">Componente Memo1</a></li>
  </ul>	
</body>
</html>

edit1.html

html5

<html>
<body>
  <h3>Componente Edit1</h3>
  <p>
    Utilice este p&aacute;rafo para mostrar la ayuda correspondiente al componente Edit1 de su aplicaci&oacute;n.
  </p>
  <a href="index.html">Ir al &iacute;ndice</a>  
</body>
</html>

memo1.html

html5

<html>
<body>
  <h3>Componente Memo1</h3>
  <p>
    Utilice este p&aacute;rafo para mostrar la ayuda correspondiente al componente Memo1 de su aplicaci&oacute;n.
  </p>
  <a href="index.html">Ir al &iacute;ndice</a>
</body>
</html>

Probando los archivos de ayuda

Ahora vamos hacia el componente TEdit1 y cuando tenga el foco presionamos la tecla F1. El sistema de ayuda abrirá una ventana del navegador de internet y mostrará la ayuda correspondiente.



Espero que sea de utilidad

[Héctor Randolph]

Tips:

En el ejemplo anterior se construyó un archivo de ayuda para cada componente. Sin embargo, se pueden incluir varios temas en un mismo archivo y después llamarlos utilizando la capacidad de HTML de recibir los nombres de los anchors o enlaces.

Creamos un solo archivo para ambos componentes

componentes.html

html5

<html>
<body>
  <h3><a name="edit1">Componente Edit1</a></h3>
  <p>
    Utilice este p&aacute;rafo para mostrar la ayuda correspondiente al componente Edit1 de su aplicaci&oacute;n.
  </p>
  
  <h3><a name="memo1">Componente Memo1</a></h3>
  <p>
    Utilice este p&aacute;rafo para mostrar la ayuda correspondiente al componente Memo1 de su aplicaci&oacute;n.
  </p>
  
  <a href="index.html">Ir al &iacute;ndice</a>
  
</body>
</html>

La tabla de contenidos cambia ligeramente

index.html

html5

<html>
<body>
  <p>
  Este es un ejemplo de archivo de ayuda para una aplicaci&oacute;n en <strong>Lazarus</strong>
  </p>
  
  <h1>Tabla de contenidos:</h1>
 
  <ul>
    <li><a href="componentes.html#edit1">Componente Edit1</a></li>
	<li><a href="componentes.html#memo1">Componente Memo1</a></li>
  </ul>	
</body>
</html>

Se puede observar que en el archivo "componentes.html" se muestran ambos temas de ayuda y añadimos dos enlaces con los nombres edit1 y memo1.

Desde nuestro programa en Lazarus incluímos las siguientes palabras clave:

Para el componente TEdit1
  HelpKeyword:='HTML/componentes.html#edit1'
 
Para el componente TMemo1
  HelpKeyword:='HTML/componentes.html#memo1'

De esta forma se mostrará el mismo archivo de ayuda en ambos casos, pero el navegador se debe posicionar en el lugar correcto.

[luk2009]

De verdad muy interesante, gracias. y como observo que manejas muy bien el tema lazarus, espero que cojas confianza y publiques mucho material como este.

[Dmanth]

Por casualidad lazarus no tendra un help, igual al de windows me refiero uno que sea un recuadro con un indice un menu etc, ya saben cual es...

Ese es como mas Profecional lo malo es que dudo que alla uno asi en linux...

[martinartaza]

Muchas gracias por tu valioso aporte, una cosita, me ando de 10 cuando aprieto F1 en el edit o en el memo, pero no logro hacer compilar el codigo que asocias al boton.

o sea no me anda lo siguiente.

delphi

procedure TForm1.Button1Click(Sender: TObject);
begin
  ShowHelpOrErrorForKeyword('','HTML/index.html');
end;

No me compila, estoy usando lazarus 9.30 en ubuntu 10.04.
Bueno, igual es un bombazo lo que posteaste, muy bueno.

[Héctor Randolph]

Hola martinartaza

La función ShowHelporErrorForKeyword está en la unidad HelpIntfs , debes añadirla en la sección uses de tu código para poder compilar.

delphi

uses
  Classes, SysUtils, LResources, Forms, Controls, Graphics, Dialogs,
  StdCtrls, Buttons, HelpIntfs;

Saludos

[martinartaza]

Disculpa, no lei la letra chiquita

Nota: debemos añadir la unidad HelpIntfs que contiene la función ShowHelpOrErrorForKeyword.

Muchas gracias, cuando llegue a casa lo pruebo.

[rretamar]

Muy buen aporte. Gracias.