GAMBAS BOOK 3.19.1

The Embedder (gb.qt4) class provides a control element that can be used to embed X11 windows from another X11 application into a Gambas window. The Embedder class is considered obsolete with gb.qt5 and should not be used any further! You can read notes on the background by following these links:

http://gambas.8142.n7.nabble.com/Embedder-depricated-in-gb-qt5-td52992.html
http://www.mail-archive.com/gambas-user@lists.sourceforge.net/msg20712.html

The impressive possibilities of the Embedder class are to be demonstrated in a project in → Section 12.5.4, where you start another programme from a Gambas programme and embed its window in the Gambas programme. For example, if you embed the window of the editor LibreOffice-Writer, you can write or edit a text in the embedded window of LibreOffice-Writer, save the text and convert it to PDF format.

The following picture shows a Gambas programme with the embedded window of the programme 'GnuPlot', which has been given a script file with GnuPlot commands as an argument:

Figure 12.5.1: Program 'GnuPlot' - embedded in a Gambas program

Only essential properties of the Embedder class are described:

Table 12.5.1.1 : Properties of the Embedder class

The Embedder class has these methods, among others:

Table 12.5.2.1 : Selected methods of the Embedder class.

From the Embedder class, you will mainly use these events:

Table 12.5.3.1 : Methods of the Embedder class

You should follow these notes:

• As a necessary condition for a successful embedding: the application to be embedded must (largely) follow the XEmbed protocol.
• If the application to be embedded does not follow the XEmbed protocol, then focus management, window activation and other functions will not work properly.
• Carefully explore working with the program whose windows you want to embed in a Gambas program.
• You can embed the window of a programme into a Gambas programme that has already been started before the Gambas programme is started or is started from it at runtime of the Gambas programme. The last case is followed in the project. To embed a window of another programme into a Gambas programme via the Embed(x11id) method, you need its window x11ID. Involving classes of the gb.desktop component, the following strategy was implemented in the project:

1. First, the list with all top-level windows is updated → line 14.
2. Then, only the X11 IDs of the top-level windows are stored in an integer array → line 17, whose window titles correspond to a given pattern → lines 9 and 16. - Finally, the last element in the integer array → line 21 is used as the current argument for the Embed(..) method → line 22.

Here you can see an excerpt from the source code:

[1] …
[2] Public Sub btnEmbed_Click()
[3]   Dim sPattern As String
[4]   Dim iX11Id As Integer
[5]   Dim DTWindow As DesktopWindow
[6]   Dim aX11List As New Integer[]
[7] …
[8] ' Version with predefined URL
[9]   sPattern = "*Firefox*"
[10]   hProcess = Shell "firefox http://www.gambas-buch.de/dw/doku.php" For Read As "hProcess"
[11] …
[12]   Wait fWaitPeriod
[13]
[14]   Desktop.Windows.Refresh ' Updates the list of all top-level windows
[15]   For Each DTWindow In Desktop.Windows
[16]     If DTWindow.VisibleName LIKE sPattern Then
[17]        aX11List.Add(DTWindow.Id)
[18]     Endif
[19]   Next
[20]
[21]   Try iX11Id = aX11List[aX11List.Max]
[22]   Try embX11.Embed(iX11Id)
[23]   If Error Then Message.Warning(Error.Text)
[24]
[25] End ' btnEmbed_Click()
[26] …

Line 9 defines the search pattern, while line 10 starts the program whose window is to be embedded in the Gambas program. Of course, you can also give this programme suitable parameters, for example, to allow a specific web page to be displayed immediately in the Firefox web browser. However, this only works without errors if there is no other Firefox window or if the following is set in the Firefox settings:

Figure 12.5.4.1: Firefox window in the Gambas project programme

When testing the project, these notes may help you:

• The programmes whose windows you want to embed in a Gambas programme must necessarily be installed on the system. You should know the programme well.
• The embedded window must be released before the end of the programme.
• The waiting time in line 12 is necessary so that the list of top-level windows also contains the programme started at runtime. The waiting times vary between 0.2 seconds and 4 seconds depending on the programme and must be determined experimentally for each programme.
• This is how you activate some special keys or catch the mouse: Press the reset button! - then that also works … (almost always).
• A large number of files have been saved in the project folder so that you can display images or the contents of PDF files. Some files contain tested plot scripts.
• In the source code, make sure to change the window title so that when you start the project programme, it is obvious which programme window you want to embed.
• You can also embed the (main) window of a Gambas programme → Chapter 12.3.4 in a Gambas programme:

Figure 12.5.4.2: Gambas program window - embedded in the Gambas project program.

Here you can see the list of tested programmes whose windows could be successfully embedded in the Gambas programme.

sPattern = "*VLC*"
hProcess = Shell "vlc" For Read As "hProcess"

sPattern = "*Bluefish*"
hProcess = Shell "bluefish" For Read As "hProcess"

sPattern = "*Document*"
hProcess = Shell "abiword" For Read As "hProcess"

' General version
sPattern = "*Firefox*"
hProcess = Shell "firefox" For Read As "hProcess"

' Version with predefined URL
sPattern = "*Firefox*"
hProcess = Shell "firefox http://www.gambas-buch.de/dw/doku.php" For Read As "hProcess"

sPattern = "hans@linux: ~"
hProcess = Shell "gnome-terminal" For Read As "hProcess"

sPattern = "*Gambas 3*"
hProcess = Shell "gambas3" For Read As "hProcess"

sPattern = "*Image viewer*"
hProcess = Shell "gbr3 " & Application.Path &/ "GPE/gpe.gambas" For Read As "hProcess"

' General version
sPattern = "*Document*"
hProcess = Shell "evince --fullscreen"

' Version with predefined PDF-File
sPattern = "*k25.1.13.pdf*"
hProcess = Shell "evince --fullscreen " & Application.Path &/ "Text/k25.1.13.pdf" For Read As "hProcess"

' General version
sPattern = "*LibreOffice Writer*"
hProcess = Shell "soffice --writer --nologo"

' Version with predefined ODT-File
sPattern = "*LibreOffice Writer*"
hProcess = Shell "soffice --writer --nologo " & Application.Path &/ "Text/k25.1.13.odt" For Read As "hProcess"

sPattern = "*Gnuplot*"
hProcess = Shell "gnuplot -persist " & Application.Path &/ "GnuPlotScripts/start.plot" For Read As "hProcess"

In the programme tests by author Ingo Beckert, even this worked without errors - starting a Windows programme from a Gambas programme via the Wine runtime environment:

sPattern = "*Ole*"
hProcess = Shell "wine oleview" For Read As "hProcess"