Content-type: text/html; charset=UTF-8
Man page of gtk-server
Section: User Commands (1)
Return to Main Contents
gtk-server - GUI access for shellscripts and interpreted languages.
The GTK-server is a binary which can be started from a (shell-)script or
an interpreted language.
It will read the configuration file 'gtk-server.cfg' after which a
client script can execute GTK functions. These GTK functions are sent in
plain text to the gtk-server, using a 2-way pipe, a named pipe or a TCP or UDP
The GTK-server was inspired by 'dtksh' for the Common Desktop
The GTK-server must be started with one of the following
Start the GTK-server with 2-way pipes. The client script language must start
a 2-way pipe to the GTK-server to enable communication. (In KSH and AWK for example, the
symbol '|&' is used for this.)
Start the GTK-server as TCP server. The client script language must
connect to this host and port. Commonly 'localhost' and a portnumber higher than
1024 are used. The 'max' part determines the maximum amount of client scripts
which can connect. If 'max' is omitted only 1 client script may connect.
Start the GTK-server as TCP client. The client script language acts like a server, sending
the commands to the GTK-server.
Start the GTK-server in UDP mode. The client script must connect to <host> and
<port> using the UDP protocol.
Start the GTK-server with a named pipe. The pipe is created by the GTK-server automatically
and has the name of <file>. When the script is finished the named pipe will be
deleted automatically. To avoid the pipe being created automatically, also use the option 'nocreate'.
Start the GTK-server with a message queue. The number must lay within the range from
1 to 65535 and specifies the queue number. When the script is finished the GTK-server will
delete the message queue from memory.
After the GTK-server has been started with a message queue, subsequent GTK requests must
be sent with the GTK-server binary using the argument 'msg'. The number of the communication
channel must be specified, as well as the string to be sent. For example:
gtk-server -msg=1,gtk_init NULL NULL
Here a GTK function is sent to communication channel 1. Make sure there is no space between
the number, the comma and the string, otherwise the GTK-server will regard these as separate
Message queues also can be retrieved using the Unix command 'ipcs', and can be deleted using
the Unix command 'ipcrm'.
The GTK-server accepts the following optional parameters:
Start the GTK-server in debug mode. A file with the name 'filename' will be created. This logfile
contains the strings which were received by the GTK-server, and the responses
of the GTK-server to those strings.
Define a signal which must be sent to the clientprogram when the GTK-server exits (UNIX only).
Explain to the GTK-server where it can find the configfile if it cannot be found at a standard
Put the specified string in front of the GTK-server returnstrings.
Put the specified string behind the GTK-server returnstrings.
To be used in combination with the fifo option. When specified the pipefile will not be created
by the GTK-server, but must be created by the client program.
This option can be used to synchronize communication. When specified the client script can send requests
starting with a self-defined handle, for example a unique number. The GTK-server will ignore this
handle when parsing the incoming request, but the returnstring for this request will start with the same handle.
When specified the GTK-server will try to spawn to the background.
When the GTK-server starts, it will read information about GTK-calls from the configfile.
This argument will dump the information to stdout. This is particularly usefull when
When the GTK-server starts, first execute the specified macro before doing anything else.
When running in socket mode, the GTK-server can send a string to handshake and identify itself with
the other side.
When running in socket mode, this option sets up an SSL connection. An optional certificatefile
can be provided which is presented by the GTK-server to the remote host during the SSL negotiation.
When running in socket mode, this option sets up an SSL connection. A certificatefile must be
provided to this option to verify the certificate presented by the remote host.
To be used in combination with the ssl option. This option should provide a password to decrypt
the SSL certificate's key if the key was encrypted.
The GTK-server will start a small graphical panel containing the output of the information exchange
between client script and GTK-server. Four buttons are visible: (1) the "Step" button to execute
the input from the client script line by line, (2) the "Run" button to let the client script execute its
commands all at once, (3) the "Pause" button to pause such execution and (4) a "Quit" button to stop the
By default, the GTK-server adds a newline after each reply. This option will prevent this from happening.
A GTK-server configfile can contain a standalone program implemented with macro's. As with most Unix
scripts, a shebang can be added to the first line of the configfile to execute it with the GTK-server:
The GTK-server searches for a macro with the name 'main' which will be executed first.
SHARED OBJECT / DLL / MODULE
If the GTK-server is compiled as a shared object, the function 'gtk' can be imported
into the client program. All GTK calls can be passed as a stringargument to this function
(formatted as S-expression). The function always will return a pointer to a string containing
the result of the last GTK call.
The C-prototype definition for the 'gtk' function in the GTK-server is as follows:
(char*) gtk (char* S-expression)
It is also possible to compile the GTK-server as an S-Lang, Scriptbasic or Kornshell module,
which can be imported in a client program. See the respective directories in the sourcepackage
Only with the first call to the imported 'gtk'-function the options 'log', 'cfg', 'pre' and 'post' can be
submitted. For example:
gtk "log=/dir/logfile cfg=/my/dir/gtk-server.cfg post=."
Now the GTK-server module will open the configfile at location '/my/dir', output it's logging
to the configured logfile and also will put a dot behind all returned answers. (These separate options
also may be preceded by the dummy command 'gtk_server_cfg'.)
The GTK-server recognizes the following internal commands:
This command returns the current version of the GTK-server.
This command returns the Foreign Function interface which has been used to compile the GTK-server: FFI,
FFCALL, C/Invoke or DYNCALL.
This command returns the backend which has been used to compile the GTK-server: GTK1, GTK2 or XForms.
This command returns the platform for which the GTK-server was compiled.
- gtk_server_callback <argument>
With this command the client program will fetch a signal for one of the widgets.
By default the widget ID is returned when a signal is received. If <argument> is 0,
the command will return to the client program immediately, and the client program
has to perform a GTK iteration by itself. If there was no signal, the returnvalue will
be 0. If <argument> is 1, the command also will
update all GTK widgets, but *only* return to the client script if a signal has occured. This setting will
be appropriate in most situations. Instead of '1' also the terms 'wait' or 'WAIT'
may be used. Finally, if <argument> is 2, the command will update all pending GTK-events and
return immediately with the last known signal. If there was no signal, the
returnvalue will be 0. Instead of 2 also the terms 'update' or 'UPDATE' may be used.
- gtk_server_callback_value <argument> <type>
If values need to be retrieved from a callback function, it can be performed with
this function. For example: the "select-row" signal for the CList widget in GTK1 will pass the row number
and column number to the callback function. These occur as the 1st and 2nd argument of the
signal. (Argument 0 passes the widget ID.) To retrieve the clicked column number of a CList widget,
perform the call 'gtk_server_callback_value 2 INT' in the client program, just after a signal
on this widget has occurend. This will retrieve the column. The first argument may range from 0 to 7.
The second argument 'type' may be INT or STRING to specify the type.
This function is not available when the GTK-server has been compiled for the XForms or Motif backend.
- gtk_server_connect <widgetID> <signal> <description> [flag]
This command adds an extra callback signal to a widget. The first argument refers to
the widget ID, which is returned when creating the widget. The second argument is the
signal name as used in GTK programming, e.g. "clicked", "enter", "pressed" and so on.
The third argument is the string which will be returned by the GTK-server when the
signal has occured. The optional last argument will explain GTK to propagate the event
further. If [flag] is omitted or 0, the occured signal will only be handled by the client
program. Any value other than 0 will propagate the event to GTK also.
When the GTK-server has been compiled for XForms, the ID of the form must be provided as first argument,
after which the event mask should be entered. The event mask can be one of KeyPressMask, KeyReleaseMask,
ButtonPressMask, ButtonReleaseMask, EnterWindowMask, LeaveWindowMask, PointerMotionMask or
ButtonMotionMask. These can be entered as a plain value (mentioned in the X-Server header files), or they
can be defined as an ENUM in the GTK-server config file.
When the GTK-server has been compiled for Motif, the ID of the widget is used as first argument, and the name of the callback
signal as second argument. If the callback signal name is set as the original Motif string, like 'XmNactivateCallback',
then this string can be converted to its real string by using the STR_NAME configuration field in the
GTK-server configfile. The real string names can be looked up in the header files from Motif.
- gtk_server_connect_after <widgetID> <signal> <description> [flag]
Similar to "gtk_server_connect", but the signal occurs after other signals take place.
This function is not available when the GTK-server has been compiled for the XForms or Motif backend.
- gtk_server_disconnect <widgetID> <description>
Disconnects a signal from a widget which has been defined with "gtk_server_connect" or
"gtk_server_connect_after" previously. The signals defined in the configfile can be disconnected
when the signalnames are used for description also. This function is not available when the GTK-server has
been compiled for the XForms backend.
This command puts the GTK-server into C escaping mode. Returned strings are surrounded with
doublequotes, and by default the special characters BELL, CR, newline, TAB, doublequote and backslash
will be preceded by the escape sign '\'. This allows debugging of strings without the client
program actually interpreting the special characters. To change the default set of characters,
use 'gtk_server_set_c_string_escaping' (see below).
Switches off the C escaping mode (default).
- gtk_server_set_c_string_escaping <argument>
Defines the set of characters which should be escaped before they are returned by the GTK-server.
- gtk_server_mouse <argument>
With this call the status of the mousepointer can be retrieved. When <argument> equals to 0,
the x-coordinate of the mouse on the widget is returned. When <argument> equals to 1, the
y-coordinate on the widget is returned. When <argument> equals to 2, the status of
the mousebutton is returned, which is a value of 1 (left button), 2 (middle button), 3 (right button),
4 or 5 (other buttons). It is required to connect the 'button-press-event' signal to the widget.
Finally, when <argument> equals to 3, the direction of the scrollbutton(s) on the mouse will
be returned: '0' means up, '1' down, '2' left and '3' means right. It is required to connect
the 'scroll-event' signal to the widget.
For XForms it is necessary to connect the 'ButtonPressMask' and 'PointerMotion' mask to the form, and for
Motif the signal 'XmNinputCallback' should be connected to the DrawingArea.
For Xforms, the result is an X event type enumeration. So if the returnvalue is 256, the left mousebutton is
pressed, if the returnvalue is 512, the middle mousebutton is pressed and with 1024 the right mousebutton
is pressed. Also modifier keys like CTRL, ALT, SHIFT etc. are notified. Here is a complete table of
1 = SHIFT KEY
2 = CAPS_LOCK or SHIFT_LOCK
4 = CONTROL KEY
8 = MODIFIER1 (determined by the configuration of X)
16 = MODIFIER2 (determined by the configuration of X)
32 = MODIFIER3 (determined by the configuration of X)
64 = MODIFIER4 (determined by the configuration of X)
128 = MODIFIER5 (determined by the configuration of X)
256 = MOUSEBUTTON1 (left)
512 = MOUSEBUTTON2 (middle)
1024 = MOUSEBUTTON3 (right)
2048 = MOUSEBUTTON4
4096 = MOUSEBUTTON5
The returned result also can contain a combination of the above values. E.g. the result
260 means that both the <CTRL> key and the left mousebutton are pressed at the same time.
- gtk_server_define <gtk function> <signal> <returnvalue> <amount> <arg1> ... <argn>
This call defines a new GTK function. If the GTK function is already available in the configfile
then it will be redefined automatically. The syntax to define a GTK function is similar to the
syntax used in the 'gtk-server.cfg' file. Please refer to the man page of 'gtk-server.cfg' for details.
- gtk_server_redefine <gtk function> <signal> <returnvalue> <amount> <arg1> ... <argn>
This call redefines a GTK function which is mentioned in the 'gtk-server.cfg' file. If the GTK
function is not available in the configfile then it will be defined as a new GTK function.
The syntax to redefine a GTK function is similar to the syntax used in the 'gtk-server.cfg' file.
Please refer to the man page of 'gtk-server.cfg' for details.
- gtk_server_require <libraryname>
Checks if <libraryname> is available on the system or not. If <libraryname> is not available, this call
will return a "0", else it will return a "1". If <libraryname> is not mentioned in the configfile, this call
will try to open it during runtime of the clientscript.
- gtk_server_timeout <milliseconds> <widget> <signal>
This call sets up a timeout in the idle loop of GTK or Motif. When waiting for an event with 'gtk_server_callback wait',
after an amount of configured milliseconds an event will be generated so the callback function returns with
the configured widgetID or string. Make sure to connect the signal in the GTK-server configfile
or with 'gtk_server_connect'-call first, otherwise the signal will not be recognized. This functions returns
a unique handle to identify the timeout. The handle can be used to remove the timeout with 'gtk_server_timeout_remove'.
GTK will execute the timeout repeatedly, but in Motif, the timeout will be executed once.
This function is not available when the GTK-server has been compiled for the XForms backend.
- gtk_server_timeout_remove <handle>
Remove a timeout which has been setup earlier. This function is not available when the GTK-server has been compiled
for the XForms backend.
Returns an undefined widget. This can be used in cases where GTK has no explicit call to create a widget of a
certain type, for example with GtkIter or GdkColor. This function is not available when the GTK-server has been compiled
for the XForms or Motif backend.
Returns the toplevel widget in an X hierarchy. This function is only available when the GTK-server is compiled for the
- gtk_server_echo <string1> <string2>...<stringn>
This is a debug function. It will return the string which is sent to the GTK-server. Convenient when in
STDIN mode, or when using the GTK-server from a programming language console. Also this function
can be used to keep an IP connection open when running in TCP/UDP mode.
Exits the GTK-server, freeing all allocated resources.
Returns the current process ID of the GTK-server (Unix only).
- gtk_server_macro_var <macro> <variablename>
Returns the value of a variable defined in a macro. The variablenames may vary from 'a' to 'z'. See also the 'gtk-server.cfg'
manpage for more info on macros.
- gtk_server_macro_define <macrodefinition>
Defines a macro. The definition should have the same format as in the configfile. The lines in a macro should be separated with a
newline. See also the 'gtk-server.cfg' manpage for more info on macros.
- gtk_server_macro_redefine <macrodefinition>
Redefines a macro. The definition should have the same format as in the configfile. See also the 'gtk-server.cfg' manpage for more info on macros.
Returns the value of the last key pressed. It is required to connect the 'key-press-event' to the widget first, otherwise the event
is not recognized by GTK. For example:
gtk_server_connect <widgetID> "key-press-event" "keypressed"
For XForms it is necessary to connect at least the 'KeyPressMask' event mask to the form. XForms uses the standard event masks from
the X header files. If the 'KeyPressMask' has a value of 1, it should be connected as follows:
gtk_server_connect <formID> 1
For Motif, only the DrawingArea widget can capture input. The signal 'XmNinputCallback' should be connected to the DrawingArea:
gtk_server_connect <DrawingAreaID> "XmNinputCallback" "keypressed"
When the GTK-server is compiled as a library, then this command can set the location of the log file and other options. Example:
gtk_server_cfg -log=/tm/gtk-server.log -post=.
Returns the value of a state key if it is pressed. If SHIFT is pressed, a '1' is returned, if CTRL is pressed '4', if ALT is pressed '8' and so on.
In GTK, it is required to connect the 'key-press-event' to the widget first, otherwise the event is not recognized by GTK. For Motif, the signal 'XmNinputCallback'
should be connected to the DrawingArea. This function is not available when the GTK-server has been compiled for the XForms backend. Example:
GTK: gtk_server_connect <widgetID> "key-press-event" "keypressed"
Motif: gtk_server_connect <DrawingArea> XmNinputCallback "keypressed"
- gtk_server_pack <format> <value1> [...value n]
Returns a memory layout in a base64 encoded string. It can be used when one of the arguments in a GTK function is defined as BASE64 type,
for example in case of an array or a struct. The <format> specifies the type, similar as in the 'printf' function: %c is a char, %s means short, %i means integer,
%l means long, %f means float and %d means double. The amount of <values> should match the amount of format specifiers. Example creating a memory layout
containing a struct with 4 integer members:
gtk_server_pack %i%i%i%i 1 1 5 6
The returned string AQAAAAEAAAAFAAAABgAAAA== can be passed on as an argument to the function which has BASE64 as argument type.
- gtk_server_unpack <format> <base64 string>
Returns an S-expression from a base64 encoded string. It can be used when one of the arguments in a GTK function is defined as PTR_BASE64 type,
for example in case an argument contains a definition for an array or a struct. The <format> specifies the type, similar as in the 'printf' function: %c is a char,
%s means short, %i means integer, %l means long, %f means float and %d means double. Example unpacking a memory layout containing a struct with 4 integer members:
gtk_server_unpack %i%i%i%i AQAAAAEAAAAFAAAABgAAAA==
This will return the string "1 1 5 6".
- gtk_server_data_format <format>
Defines the memory layout for PTR_BASE64 arguments. It should be set before the actual function with PTR_BASE64 argument types is used. Example:
- gtk_server_unpack_from_pointer <format> <pointer>
Returns an S-expression from a memory area pointed to by a pointer. It can be used when one of the arguments in a GTK function is defined as PTR_LONG type,
for example in case an argument contains a pointer to an array or a struct. The <format> specifies the type, similar as in the 'printf' function: %c is a char,
%s means short, %i means integer, %l means long, %f means float and %d means double. Example unpacking a memory layout containing a struct with 3 integer members:
gtk_server_unpack_from_pointer %i%i%i 7478512
- gtk_server_string_from_pointer <pointer>
Returns a string from a pointer to a character pointer. In C syntax, this is the '**' construct, which sometimes is used by the GTK API when returning error
messages. For example:
The configuration file for the GTK-server.
Examples of scripts using the GTK-server can be found in the sourcepackage. Also consult
the latest demoscripts at http://www.gtk-server.org/.
This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published
by the Free Software Foundation; either version 2 of the License,
or (at your option) any later version.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 59 Temple Place, Suite 330, Boston,
MA 02111-1307 USA.
Please report bugs to: email@example.com
Orignal concept, design and implementation by Peter van Eerten, e-mail : firstname.lastname@example.org
Current version of the GTK-server was created with help of many others - see the CREDITS file in
the sourcepackage for credits.
- SHARED OBJECT / DLL / MODULE
- INTERNAL COMMANDS
- SEE ALSO
This document was created by
using the manual pages.
Time: 13:40:28 GMT, June 30, 2019