GAMBAS BOOK 3.19.1

In contrast to the first two projects, in which signals selected by a Gambas client from other d-bus-capable applications were only intercepted on the D-bus and in some cases the contents in the Arguments variant array were also evaluated, here you will be presented with two projects with which you can send a self-defined signal on the one hand (server) or intercept and evaluate it on the other (client):

Figure 24.9.6.2.1: Signal transmitter

The source code for a project that is also to send D-Bus signals always includes the preparation of the signal to be sent in a special class file - whose name you can freely define - and the actual signal transmitter in the start class, such as in the class FMain.class.

Signal definition

The preparation of the signal to be transmitted is done in the class file SGBVersion.class. The prefix S stands for signal definition and GBVersion for the signal name, which is also called member. You can define the signal name yourself:

[1] ' Gambas class file
[2]
[3] Inherits DBusObject
[4] Create Static
[5]
[6] ' (Pseudo-) signature of the list of arguments: "s" => String
[7]
[8] Event org_gambas_SignalTX_SGBVersion_GBVersion(Version As String)

The preparation of the signal to be sent is done quickly. The class SGBVersion.class inherits in line 3 from the class DBusObject. Therefore, every instance of SGBVersion.class is of the data type DBusObject. In line 8, the signal is defined. A D-Bus signal is always defined as an event in Gambas. For the syntax of the signals to be sent, see chapter 24.9.6.0.4 Send signals. Since the signature of the signal is “s” - only a string is sent - the list of arguments consists of only one element: version with the data type string. The native Gambas data type 'String' is automatically converted to the appropriate D-Bus data type when sending.

Signal transmitter

Before you can send a signal, you must export the DBus object in which the signal was defined (SGBVersion.class) to the session D-bus using the DBus.Raise(…) or DBus[AppName].Raise(…) method so that d-bus-enabled programs can observe the defined signals.

Source code transmitter:

[1] ' Gambas class file
[2]
[3] Private $sDBusName As String
[4] Private $hDBusObject As SGBVersion
[5] Private $sDBusObjectPath As String
[6]
[7] Public Sub Form_Open()
[8]
[9]   FMain.Resizable = False
[10]   DBus.Unique = True
[11] ' For tests only: DBus.Debug = True
[12]
[13]   $hDBusObject = New SGBVersion
[14]   $sDBusObjectPath = "/SGBVersion"
[15]
[16]   DBus.Session.Register($hDBusObject, $sDBusObjectPath)
[17]
[18] End
[19]
[20] Public Sub btnSendSignal_Click()
[21]
[22]   lblCaption.Foreground = Color.Red
[23]   SendSignal()
[24]   Wait 0.1
[25]   lblCaption.Foreground = Color.Black
[26]
[27] End
[28]
[29] Private Sub SendSignal()
[30]
[31]   Dim aArguments As New Variant[]
[32]
[33]   aArguments.Add(System.FullVersion)
[34]
[35]   DBus.Raise($hDBusObject, "org.gambas.SignalTX.SGBVersion.GBVersion", aArguments)
[36] ' $sDBusName = DBus.Name
[37] ' DBus[$sDBusName].Raise($hDBusObject, "org.gambas.SignalTX.SGBVersion.GBVersion", aArguments)
[38]
[39] End
[40]
[41] Public Sub Form_Close()
[42]
[43]   If DBus.IsRegistered($hDBusObject) Then DBus.Session.Unregister($hDBusObject)
[44]   FMain.Close()
[45]
[46] End

Comment:

• In line 16, the D-bus object with the D-bus object path '/SGBVersion' is exported to the D-bus.
• In lines 22 and 25, the colour in the display is changed only briefly to signal the sending of the signal.
• The content of the signal is a string containing the current Gambas version with System.FullVersion (line 33).
• The sending of the signal is triggered in line 35 or alternatively in line 37.
• Since a D-Bus object with the D-Bus object path '/SGBVersion' has been exported to the D-Bus, it is logged off again in line 43 before the programme is terminated.

The client SignalRX observes the signal with the name 'GBVersion' and the D-Bus object path '/SGBVersion' of the application with the D-Bus name org.gambas.SignalTX on the session D-Bus. When the signal arrives, the content - the current Gambas version on the system - is read and displayed in a text area together with the preceding date and the current time:

Figure 24.9.6.2.2: Signal receiver

The source code for the client is given in full and then commented on:

[1] ' Gambas class file
[2]
[3] Private $hDBusSignal As DBusSignal
[4] Private $sDBusInterface As String
[5] Private $sDBusSignalName As String
[6]
[7] Public Sub Form_Open()
[8]
[9]   Dim sMessage As String
[10]
[11]   If Not DBus.Session.Applications.Exist("org.gambas.SignalTX") Then
[12]      sMessage = ("There is no suitable data server on the session bus!")
[13]      sMessage &= "<center><font color='red'>"
[14]      sMessage &= ("The program is terminated.")
[15]      sMessage &= "</font></center>"
[16]      Message.Warning(sMessage)
[17]      Quit
[18]   Endif
[19]
[20]   FMain.Resizable = False
[21]   lblCaption.Text = ("WATCHING SPECIAL SIGNAL")
[22] ' For tests only: DBus.Debug = True
[23]
[24]   $sDBusInterface = "org.gambas.SignalTX.SGBVersion"
[25]   $sDBusSignalName = "GBVersion" ' The signal name is called 'Member'
[26]
[27]   $hDBusSignal = New DBusSignal(DBus.Session, $sDBusInterface, True) As "ObservedSignal"
[28]
[29] End
[30]
[31] Public Sub ObservedSignal_Signal(Signal As String, Arguments As Variant[])
[32]
[33]   If Signal = $sDBusSignalName Then
[34]      TextArea1.Insert("Zeit: " & Format(Now(), "dd.mm.yyyy hh:nn:ss") & "    Signal-Name:  " & Signal & " -> " & Arguments[0] & gb.NewLine)
[35]      TextArea1.Pos = TextArea1.Length
[36]   Endif
[37]
[38] End
[39]
[40] Public Sub Form_Close()
[41]
[42]   If $hDBusSignal Then $hDBusSignal.Enabled = False
[43]   FMain.Close()
[44]
[45] End

Comment:

• Line 11 checks whether the (server) programme exists. However, this type of check only works if the property DBus.Unique has been set to the value True in the source code of the server. In Chapter 24.9.2.1 you can read about the alternative for the default DBus.Unique = False.

Figure 24.9.6.2.3: False start …

• A new signal observer with the event name 'ObservedSignal' is created at line 27.
• How to react when the observed signal arrives and thus triggers the 'Signal' event is specified in the event handling routine in lines 31 to 38.
• The signal observer is switched off in line 42 before the client programme is terminated.