VB .NET - Usando o controle HelpProvider

Para implementar o recurso de ajuda em nossos sistemas o .NET Framework nos oferece a classe Help e o componente HelpProvider. A classe HelpProvider fornece uma ajuda suspensa ou on-line para os controles.

O componente HelpProvider para WIndows Forms é usado para associar um arquivo HTML Help ( ou um arquivo .chm produzido com o HTML Help Workshop ou um arquivo .htm) a suas aplicações Windows. Ele pode ser usado para fornecer um help de contexto para controles do formulário ou para controles específicos. Pode também abrir um arquivo de ajuda para áreas específicas tais como a página principal do conteúdo de uma tabela.

Cada instância de HelpProvider mantém uma coleção de referências para os controles associados. Para associar um arquivo de ajuda com o objeto HelpProvider definimos a propriedade HelpNamespace. Nela especificamos o tipo de Ajuda fornecida através da chamada de SetHelpNavigator e fornecendo um valor HelpNavigator para o controle especificado. Você define a palavra-chave ou o tópico para a ajuda chamando SetHelpKeyword.

Para associar uma Ajuda específica a um controle usamos o método SetHelpString. A string que você associar ao controle será exibida em uma janela pop-up quando o usuário pressionar a tecla F1 enquanto o controle tiver o foco.

Se HelpNamespace não tiver sido definido você precisa usar SetHelpSting para fornecer o texto da ajuda. Se você tiver definido tanto o HelpNamespace quanto o texto de ajuda, a ajuda baseada em HelpNamespace terá a precedência.

Para usar o componente para arrastá-lo da ToolBox para o seu formulário. Ele será incluído no tray do formulário com o nome padrão - HelpProvider1 .

  A única propriedade relevante que você precisa definir em tempo de desenho é a propriedade HelpNamespace que irá conter um valor string representando o caminho para o arquivo de ajuda fonte HTML Help. Este arquivo pode ser qualquer arquivo .htm ou .chm. (Você pode até usar um arquivo .txt )
-A janela de propriedades para o HelpProvider exibindo suas 4 propriedades.

O componente HelpProvider efetua sua associação com todos os controles do formulário e você pode verificar isto na janela de propriedades de cada controle.

Dentre estas propriedades destacamos:

  1. HelpButton

    Esta propriedade possui um valor booleano e determina se o símbolo para Ajuda (?) irá aparecer no seu formulário na caixa de controle. O botão irá aparecer somente se as propriedades do formulário MaximizeBox e MinimizeBox forem definidas como false.
     

  2. HelpNavigator

    Especifica uma constante indicando quais elementos do arquivo de ajuda serão exibidos. Os valores são

    Nome Descrição
    AssociateIndex Define que o index para o tópico definido é realizado na URL especificada.
    Find Define que a página de busca da URL específica será exibida.
    Index Define que o index de uma URL específica é exibida.
    KeywordIndex Define uma palavra-chave para buscar  a ação na URL.
    TableOfContents Define que a tabela de conteúdo da URL específica é exibida.
    Topic Especifica que o tópico referenciado pela URL é exibido.
  3. HelpKeyword

    Fornece a informação chave para retornar a ajuda associada com o controle de formulário e o arquivo de ajuda definido em  HelpNamespace.
     

  4. HelpString

    O valor de HelpString representa a mensagem de ajuda da janela de ajuda pop-up que aparece quando o usuário pressiona F1.

Em tempo de desenho você pode associar uma instância de HelpProvider com somente uma fonte de arquivo de ajuda. Além disto ele expõe os seguintes métodos:

SetHelpKeyword  -Define a palavra_chave usada para retornar a AJuda quando o usuário invocar a ajuda para um controle especifico.

SetHelpNavigator - Especifica o comando de Ajuda a usar quando retorna uma AJuda de um arquivo de ajuda para um controle.

SetHelpString  - Define a string de ajuda associada com o controle.

SetShowHelp - Define se a ajuda será exibida para o controle

 

Nota: Os métodos acima mencionados possuem os seguintes métodos relacionados:

  1. GetHelpKeyword
  2. GetHelpNavigator
  3. GetHelpString
  4. GetShowHelp

Usando o HelpProvider - A Ajuda pop-up

 

A ajuda pop-up fornece uma informação sensitiva ao contexto para um controle ou formulário. A mensagem de ajuda ou informação esta embutida no seu código. A mensagem de ajuda para o  contexto específico será exibida quando o usuário pressionar F1 no controle que tiver o foco.

 

Crie um novo projeto no VS.NET do tipo Windows Application e no formulário padrão insira alguns componentes labels , textbox e buttons  e

a seguir insira o componente helpProvider a partir da Toolbox no formulário , conforme figura abaixo:

 

Fig 5.0 - O formulário do projeto com o HelpProvider

Fig 6.0 - Configurano HelpString para o TextBox Nome

 

Agora você já pode configurar a propriedade HelpString para cada controle no formulário para o qual desejamos uma ajuda . Na figura 6.0 temos a configuração feita para o campo txtNome. Verifique se a propriedade ShowHelp esteja definida como True.  Rodando o projeto e pressionando F1 em cada campo TextBox para o qual HelpString for definida teremos a exibição do texto da ajuda conforme figura abaixo:

 

Você pode fazer a mesma coisa via código assim :

Private Sub frmHelpProvider_Load(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles MyBase.Load

HelpProvider1.SetHelpString(txtNome, "Você pressionou F1.  Como posso ajudá-lo ?")

HelpProvider1.SetShowHelp(txtNome, True)

End Sub

 

 

Habilitando o botão de Ajuda no formulário

O botão de ajuda aparece como um '?' na barra de título do formulário. Você pode habilitar este botão para o seu formulário definindo a propriedade HelpButton como True.(Lembre-se que as propriedades  MaximizeBox e MinimizeBox devem estar definidas como false).

Ao clicar no botão ? em tempo de execução o cursor do seu mouse irá ser alterado para exibir o ?. Com o novo cursor exibido clique no campo para o qual você definiu a propriedade HelpString e a janela pop-up de ajuda será exibida.

O evento HelpRequested

Cada controle , incluindo o formulário , dispara seu próprio evento HelpRequested em resposta a pressionamento da tecla F1 pelo usuário. Você pode se aproveitar deste fato e colocar a implementação de invocação de sua ajuda neste evento via código.

Abaixo temos um código que implementa a ajuda usando o evento HelpRequested para o campo txtEmail :

Private Sub txtEmail_HelpRequested(ByVal sender As Object, ByVal hlpevent As System.Windows.Forms.HelpEventArgs) _

Handles txtEmail.HelpRequested
 

Help.ShowPopup(Me, "Informe o Email do usuário . Use caracteres válidos. ", hlpevent.MousePos)


End Sub

Se você quiser pode também responder a um pedido de ajuda do usuário a partir do pressionamento de outra tecla. Abaixo um exemplo:

Private Sub txtEmail_KeyDown(ByVal sender As Object, ByVal e As System.Windows.Forms.KeyEventArgs) Handles txtEmail.KeyDown

If e.KeyCode = Keys.F1 Then

     Help.ShowPopup(Me, "Informe o Email para o usuário.", Cursor.Position)

     e.Handled = True

End If

End Sub

 

 

Incluindo Ajuda usando arquivos .htm

A primeira coisa a fazer para definir e usar um arquivo de ajuda é definir a propriedade HelpNamespace para uma URL valida. A URL será o caminho para um página web off-line( arquivo .htm)  ou uma URL remota. Abaixo um exemplo onde estou definindo o arquivo supercd.htm como arquivo de ajuda a ser exibido quando o usuário pressionar F1.

Para usar o mesmo componente HelpProvider para exibir diferentes páginas html de ajuda para diferentes contextos você terá que alterar via código o  nome da propriedade HelpNamespace para o recurso de ajuda apropriado. A alteração pode ser feita no evento HelpRequested.

Exemplo:

Private Sub txtNome_HelpRequested(ByVal sender As Object, ByVal hlpevent As System.Windows.Forms.HelpEventArgs) _

Handles txtNome.HelpRequested

    HelpProvider1.HelpNamespace = IO.Path.GetDirectoryName(HelpProvider1.HelpNamespace) & "\asptotal.htm"

End Sub

 

Incluindo ajuda HTML Help (.cfm)

Para encerrar este artigo vou falar da ajuda usando arquivos .chm . Estes arquivos podem ser gerados usando o HTML Help WorkShop da Microsoft que você pode pegar em :  http://go.microsoft.com/fwlink/?LinkId=14188. Para saber como gerar ajuda no formato .chm leia o artigo:  Usando HTML HELP em suas aplicações Visual Basic

Você deve definir a propriedade HelpNamespace do componente para uma URL valida apontando para o arquivo de ajuda .chm. (O arquivo pode estar no cliente ou ter localização remota). O próximo passo é definir a propriedade ShowHelp para controle como True.

Para abrir uma seção especifica da sua ajuda escolha um valor apropriado para a propriedade HelpNavigator de forma que o arquivo de ajuda seja aberto de forma apropriada usando o valor da propriedade HelpKeyword. Esta propriedade gerencia um contexto específico relacionado com uma palavra-chave que você inclui na sua ajuda antes de efetuar a compilação. Pode ser um entrada de um índice , um valor para busca ou o nome do arquivo que é parte da compilação.

Para alterar as propriedades HelpKeyword/HelpNavigator de um controle em tempo de execução , você deve usar os métodos SetHelpKeyword/SetHelpNavigator do componente HelpProvider.

E estamos conversados... Até o próximo artigo.

Eu sei , é apenas VB .NET , mas eu gosto...

 

 

José Carlos Macoratti