User Tools

Site Tools


k11:k11.8:start

11.8 Program help

If you have developed and tested an extensive program, then you know the program functions or configuration settings best. Therefore, give the program and all future users a program help. You should set up the help function so that it can be called up in the main program using the F1 function key and terminated with the Escape key (ESC). Whether you choose a simple text file or an extensive help in HTML or PDF format is largely determined by the type and complexity of the program. The examples assume that the help file is located in different formats in the project folder. This compiles this file into the program.

11.8.1 Calling the help in the main program

The help in the main program is called by evaluating the event Form_KeyPress() in the main program after pressing the key F1 and displaying a further form - here FHelp - with the help text as a reaction:

PUBLIC SUB Form_KeyPress() 
  IF Key.Code = Key.F1 THEN 
' IF Key.Code = Key.F1 THEN AND FHelp.Closed = FALSE 
     FHelp.Show 
  ENDIF 
  IF Key.Code = Key.ESC AND FHelp.Closed = FALSE THEN 
     FHelp.Delete 
  ENDIF 
END ' Form_Open() 

If the Escape key has been pressed and the help window is displayed, the help window will be closed.

Hauptprogramm

Figure 11.8.1.1: Main program

Text-Format

Figure 11.8.1.2: Help window (text/plain format)

11.8.2 Help window - text file

  • The help text in the format Text/Plain is read into a TextArea as a display object.
  • Make sure that you have set the TextArea1. read-only property to TRUE.
  • You have no possibility to mark the help text in a special way.
  • In the Form_KeyPress () event in the form FHelp, the key code of the escape key is evaluated and responds by destroying the' Help window' object.

Since the program for the help window is very short, the complete source code is specified here:

' Gambas class file 
 
PUBLIC SUB Form_Open() 
  FHelp.X = 200 ' possibly adapt ..
  FHelp.Y = 200 
  FHelp.Text = "F1 help text - abort with ESC" 
  TextArea1.ReadOnly = TRUE
END ' Form_Open() 
 
PUBLIC SUB Form_Show() 
  FHelp.Arrangement = Arrange.Fill 
  TextArea1.Background = &H00FFFFDF& 
  TextArea1.Text = File.Load("help.txt")
END ' Form_Show() 
 
PUBLIC SUB Form_KeyPress() 
  IF Key.Code = Key.ESC AND FHelp.Closed = FALSE THEN 
     FHelp.Delete 
  ENDIF 
END ' Form_KeyPress()

11.8.3 Help window - HTML file

If the help file is in HTML format, you require a browser component as the display object.

Source code:

' Gambas class file 
 
PUBLIC SUB Form_Open() 
  FHelp.W = 560 
  FHelp.H = 238 
  FHelp.X = 20 ' possibly adapt ..
  FHelp.Y = 20 
  FHelp.Text = "F1 help text - abort with ESC" 
  WebBrowser1.X = 7 
  WebBrowser1.Y = 7 
END ' Form_Open() 
 
PUBLIC SUB Form_Show() 
  WebBrowser1.Path = Application.Path &/ "help.html" 
END 
 
PUBLIC SUB Form_KeyPress() 
  IF Key.Code = Key.ESC AND FHelp.Closed = FALSE THEN 
     FHelp.Delete 
  ENDIF 
END ' Form_KeyPress() 
 
PUBLIC SUB Form_Resize() 
  WebBrowser1.W = FHelp.W - 11 
  WebBrowser1.H = FHelp.H - 11 
END ' Form_Resize()

HTML-Hilfe

Figure 11.8.3.1: Help window (HTML format)

11.8.4 Help window - PDF file

If the help file is available as a PDF document, the program section for displaying the help is more extensive. The effort is particularly worthwhile for larger projects. Then you can use LibreOffice Writer to write, design and then convert the document into PDF format.

  • The complete source code of FHelp. class is displayed. The complete project can be found in the download area.
  • The procedure for rendering a PDF page is taken from a program by Daniel Campos Fernández.
  • The component gb.pdf must be included in the project via the project properties.

Source code:

' Gambas class file
 
Public pdfDokument As New PdfDocument
Public cIndex As Integer
Public CurrentPage As Integer
Public CurrentZoom As Float
 
Public Sub Form_Open()
  FHelp.H = 365
  FHelp.W = 650
  FHelp.X = 50 ' Possibly adjust coordinates
  FHelp.Y = 50
  HBox1.H = 24
End ' Form_Open()
 
Public Sub Form_KeyPress()
  If Key.Code = Key.ESC And FHelp.Closed = False Then
     FHelp.Delete
  Endif ' KeyCode ?
End ' Form_KeyPress()
 
Public Sub Form_Show()
  pdfDokument.Close()
  Try pdfDokument.Open(Application.Path &/ "help.pdf")
  If Error Then
     Message.Error(Error.Text)
     Return
  Endif ' ERROR ?
 
  CurrentZoom = 1
  CurrentPage = 1
 
  RenderPage()
 
  btnPrev.Enabled = False
  If pdfDokument.Count > 1 Then
     btnNext.Enabled = True
  Else
     btnNext.Enabled = False
  Endif ' pdfDokument.Count > 1 ?
  btnZoomPlus.Enabled = True
  btnZoomMinus.Enabled = True
  btnRotate.Enabled = True
  picBox.Visible = True
 
End 'Form_Show()
 
Public Sub RenderPage()
  Dim hPic As Picture
  Dim iCount As Integer
 
  pdfDokument.Zoom = CurrentZoom
  ViewPort.Scroll(0, 0)
  hPic = pdfDokument[CurrentPage].Image.Picture
 
  Draw.Begin(hPic)
    For iCount = 0 To pdfDokument[CurrentPage].Result.Count - 1
      Draw.Rect(pdfDokument[CurrentPage].Result[iCount].Left,
                pdfDokument[CurrentPage].Result[iCount].Top,
                pdfDokument[CurrentPage].Result[iCount].Width,
                pdfDokument[CurrentPage].Result[iCount].Height)
    Next ' iCount
  Draw.End()
 
  picBox.Picture = hPic
  picBox.Resize(pdfDokument[CurrentPage].Width, pdfDokument[CurrentPage].Height)
  Form_Resize()
End ' RenderPage()
 
Public Sub Form_Resize()
  If CurrentPage = 0 Then Return
  picBox.Left = (ViewPort.Width - pdfDokument[CurrentPage].Width) / 2
End ' Form_Resize()
 
Public Sub btnNext_Click()
  Inc CurrentPage
  If CurrentPage = pdfDokument.Count Then btnNext.Enabled = False
  btnPrev.Enabled = True
  RenderPage()
End ' btnNext_Click()
 
Public Sub btnPrev_Click()
  Dec CurrentPage
  If CurrentPage = 1 Then btnPrev.Enabled = False
  btnNext.Enabled = True
  RenderPage()
End ' btnPrev_Click()
 
Public Sub btnZoomPlus_Click()
  If CurrentZoom < 3 Then CurrentZoom += 0.1
  If CurrentZoom = 3 Then btnZoomPlus.Enabled = False
  btnZoomMinus.Enabled = True
  RenderPage()
End ' btZoomIn_Click()
 
Public Sub btnZoomMinus_Click()
  If CurrentZoom > 0.5 Then CurrentZoom -= 0.1
  If CurrentZoom = 0.5 Then btnZoomMinus.Enabled = False
  btnZoomPlus.Enabled = True
  RenderPage()
End ' btZoomOut_Click()
 
Public Sub btnRotate_Click()
  Select Case pdfDokument.Orientation
    Case PdfDocument.Normal
         pdfDokument.Orientation = PdfDocument.Sideways
    Case PdfDocument.Sideways
         pdfDokument.Orientation = PdfDocument.Inverted
    Case PdfDocument.Inverted
         pdfDokument.Orientation = PdfDocument.SidewaysInverted
    Case PdfDocument.SidewaysInverted
         pdfDokument.Orientation = PdfDocument.Normal
  End Select ' pdfDokument.Orientation
  RenderPage()
End ' Rotation
 
Public Sub Form_Close()
  pdfDokument.Close()
End ' Form_Close()

Figure 11.8.4.1: Help window (PDF format)

11.8.5 Notes

Where to display the help window is determined by the size and location of the main program window. If you do not enter any coordinates, you will find the help window in the upper left corner of the screen with the default values FHelp.X = 0 and FHelp.Y = 0.

If one takes the type and number of program windows as criteria, one can differentiate between the following types in a Gambas project:

  • Project with exactly one single window
  • Project with several single windows
  • MDI application as a project with a main window and individual windows in the container component Workspace
  • Project with exactly one single window and at least one embedded but externally started program (Embedder).

In all cases you can insert the program help according to the above mentioned procedure. In the MDI application with the container component Workspace, you can provide each subprogram with its own help.

11.8.6 Download

The website uses a temporary session cookie. This technically necessary cookie is deleted when the browser is closed. You can find information on cookies in our privacy policy.
k11/k11.8/start.txt · Last modified: 23.09.2023 by honsek

Page Tools