GAMBAS BOOK 3.18.2

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.

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.

Figure 11.8.1.1: Main program

Figure 11.8.1.2: Help window (text/plain format)

• 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()

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()

Figure 11.8.3.1: Help window (HTML format)

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)

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.

Wenn Sie ein umfangreiches Programm entwickelt und getestet haben, dann kennen Sie die Programm-Funktionen oder die Konfigurationseinstellungen am besten. Spendieren Sie deshalb dem Programm und damit allen zukünftigen Nutzern eine Programm-Hilfe. Die Hilfe sollten Sie so einrichten, dass diese über die Funktionstaste F1 im Hauptprogramm aufgerufen werden kann und mit der Escape-Taste (ESC) wieder beendet wird. Ob Sie sich für eine einfache Textdatei oder eine umfangreiche Hilfe im HTML-Format oder PDF-Format entscheiden, wird wesentlich durch die Art und die Komplexität des Programms mit bestimmt. In den Beispielen wird davon ausgegangen, dass die Hilfedatei in unterschiedlichen Formaten im Projektordner liegt. Damit wird diese Datei mit in das Programm compiliert.

Die Hilfe im Hauptprogramm wird aufgerufen, indem nach einem Druck auf die Taste F1 das Ereignis Form_KeyPress() im Hauptprogramm ausgewertet wird und als Reaktion ein weiteres Formular – hier FHelp – mit dem Hilfetext angezeigt wird:

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() 

Wenn die Escape-Taste gedrückt wurde und das Hilfefenster angezeigt wird, dann wird das Hilfefenster geschlossen.

Abbildung 11.8.1.1: Hauptprogramm

Abbildung 11.8.1.2: Hilfefenster (Format Text/Plain)

• Der Hilfetext im Format Text/Plain wird in eine TextArea als Anzeige-Objekt eingelesen.
• Stellen Sie sicher, dass Sie die Eigenschaft TextArea1.ReadOnly auf TRUE gesetzt haben.
• Sie haben keine Möglichkeit, den Hilfstext in besonderer Weise auszuzeichnen.
• Es wird im Form_KeyPress()-Ereignis im Formular FHelp der Key.Code der Escape-Taste ausgewertet und mit dem Zerstören des Objekts 'Hilfefenster' reagiert.

Da das Programm für das Hilfefenster nur sehr kurz ist, wird der hier komplette Quelltext angegeben:

' Gambas class file 
 
PUBLIC SUB Form_Open() 
  FHelp.X = 200 ' u.U. anpassen... 
  FHelp.Y = 200 
  FHelp.Text = "F1-Hilfetext - Abbruch mit 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()

Liegt die Hilfedatei im HTML-Format vor, dann benötigen Sie als Anzeige-Objekt eine Browser-Komponente.

Quelltext:

' Gambas class file 
 
PUBLIC SUB Form_Open() 
  FHelp.W = 560 
  FHelp.H = 238 
  FHelp.X = 20 ' u.U. anpassen... 
  FHelp.Y = 20 
  FHelp.Text = "F1-Hilfetext - Abbruch mit 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()

Abbildung 11.8.3.1: Hilfefenster (HTML-Format)

Wenn die Hilfedatei als PDF-Dokument vorliegt, ist der Programmabschnitt zur Anzeige der Hilfe umfangreicher. Der Aufwand lohnt vor allem für größere Projekte. Dann können Sie die Hilfe zum Beispiel komfortabel mit LibreOffice Writer schreiben, gestalten und abschließend das Dokument sofort in das PDF-Format konvertieren.

• Es wird der komplette Quelltext von FHelp.class angezeigt. Das vollständige Projekt finden Sie im Download-Bereich.
• Die Prozedur zum Rendern einer PDF-Seite ist einem Programm von Daniel Campos Fernández entnommen.
• Die Komponente gb.pdf müssen Sie über die Projekteigenschaften in das Projekt aufnehmen.

Quelltext:

' 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 ' u.U. Koordinaten anpassen
  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()

Abbildung 11.8.4.1: Hilfefenster (PDF-Format)

Wo das Hilfefenster angezeigt werden soll, wird durch die Größe und Lage des Hauptprogramm-Fensters bestimmt. Geben Sie keine Koordinaten vor, dann finden Sie das Hilfefenster in der linken oberen Bildschirmecke mit den Standardwerten FHelp.X = 0 und FHelp.Y = 0.

Nimmt man als Kriterium die Art und Anzahl der Programm-Fenster, kann man bei einem Gambas-Projekt folgende Typen unterscheiden:

• Projekt mit genau einem Einzelfenster
• Projekt mit mehreren Einzelfenstern
• MDI-Anwendung als Projekt mit einem Haupt-Fenster und einzelnen Fenstern in der Container-Komponente Workspace
• Projekt mit genau einem Einzelfenster und mindestens einem eingebetteten, jedoch extern gestartetem Programm (Embedder).

In allen Fällen kann man die Programm-Hilfe nach dem o.a. Verfahren einfügen. Bei der MDI-Anwendung mit der Containerkomponente Workspace können Sie jedes Teil-Programm mit einer eigenen Hilfe versehen.