Content-type: text/html
Manpage of gtk-server
gtk-server
Section: User Commands (1)
Index
Return to Main Contents
NAME
gtk-server - Enable GUI access to shellscripts and interpreted languages.
SYNOPSIS
gtk-server
<stdin> |
<tcp>=host:port[:max] |
<udp>=host:port |
<fifo>=filename
[log]
[cfg=filename]
DESCRIPTION
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
connection.
The GTK-server was inspired by 'dtksh' for the Common Desktop
Environment (CDE).
ARGUMENTS
The GTK-server must be started with one of the following
arguments:
- stdin
-
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.)
- tcp=host:port[:max]
-
Start the GTK-server with TCP connectivity. 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.
- udp=host:port
-
Start the GTK-server in UDP mode. The client script must connect to <host> and
<port> using the UDP protocol.
- fifo=<file>
-
Start the GTK-server with a named pipe. The pipe is created by the GTK-server
and has the name of <file>. When the script is finished the named pipe will be
deleted automatically.
OPTIONS
The GTK-server can be started with the following options:
- log
-
Start the GTK-server in debug mode. A file with the name 'gtk-server.log'
will be created in the directory which is defined in the 'gtk-server.cfg' file. This logfile
contains the strings which were received by the GTK-server, and the responses
of the GTK-server to those strings.
- cfg=<filename>
-
Explain to the GTK-server where it can find the configfile if it cannot be found at a standard
location.
- pre=<string>
-
Put the specified string in front of the GTK-server returnstrings.
- post=<string>
-
Put the specified string behind the GTK-server returnstrings.
SHARED OBJECT / DLL / MODULE
If the GTK-server is compiled as a shared object, you can import the function 'gtk'
into your 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 or Scriptbasic module,
which can be imported in a client program. See the respective directories in the sourcepackage
for details.
Only with the first call to the imported 'gtk'-function the options 'log', 'cfg', 'pre' and 'post' can be
submitted. For example:
gtk "log 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'.)
INTERNAL COMMANDS
The GTK-server recognizes the following internal commands:
- gtk_server_version
-
This command returns the current version of the GTK-server.
- 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>
-
If you need to retrieve the values passed to 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' in your client program, just after a signal
on this widget has occurend. This will retrieve the column. The argument may range from 0 to 7.
This function is not available when the GTK-server has been compiled for the XForms 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 your client
program. Any value other than 0 will propagate the event to GTK also.
This function is not available when the GTK-server has been compiled for the XForms backend.
- 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 backend.
- gtk_server_disconnect
-
Disconnects the signal which has occured last. Please note that this will only disconnect
a signal which has been defined with "gtk_server_connect" or "gtk_server_connect_after". The
signals defined in the configfile remain.
This function is not available when the GTK-server has been compiled for the XForms backend.
- gtk_server_enable_c_string_escaping
-
This command puts the GTK-server into C escaping mode. Returned strings are surrounded with
doublequotes, and the special characters BELL, CR, newline, TAB and doublequote will be
preceded by the escape sign '\'. This allows debugging of strings without the client
program actually interpreting the special characters.
- gtk_server_disable_c_string_escaping
-
Switches off the C escaping mode again (default).
- 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. Finally, when <argument> equals to 2, the status of
the mousebutton is returned, which is a value of the GdkModifierType 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 returnvalues, taken
from the documentation at www.gtk.org:
This function is not available when the GTK-server has been compiled for the XForms backend.
1 = SHIFT KEY
2 = CAPS_LOCK or SHIFT_LOCK
4 = CONTROL KEY
8 = MODIFIER1 (determined by your X configuration)
16 = MODIFIER2 (determined by your X configuration)
32 = MODIFIER3 (determined by your X configuration)
64 = MODIFIER4 (determined by your X configuration)
128 = MODIFIER5 (determined by your X configuration)
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_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 an error is returned and the GTK-server exits.
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_timeout <milliseconds> <widget> <signal>
-
This call sets up a timeout in the idle loop of GTK. When waiting for an event with 'gtk_server_callback wait',
each amount of configured milliseconds an event will be generated by GTK 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. Passing a '0' for milliseconds
will remove the timeout.
This function is not available when the GTK-server has been compiled for the XForms backend.
- 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.
- gtk_server_glade_file <filename>
-
When compiled with Glade support, this command will point to a Glade XML file containing a user
interface. The call will load the XML file and realize it.
This function is not available when the GTK-server has been compiled for the XForms backend.
- gtk_server_glade_string <variable>
-
When compiled with Glade support, this command will take a variable containing a Glade user
interface. The call will load the XML definition and realize it.
This function is not available when the GTK-server has been compiled for the XForms backend.
- gtk_server_glade_widget <widgetname>
-
When compiled with Glade support, this command will return a widgetID based on the name used in the
Glade XML file. Once the widgetID is known a signal can be connected to it, so the
widget can be checked for signals during the mainloop.
This function is not available when the GTK-server has been compiled for the XForms backend.
FILES
gtk-server.cfg
-
The configuration file for the GTK-server.
EXAMPLES
Examples of scripts using the GTK-server can be found in the sourcepackage. Also consult
the latest demoscripts at http://www.gtk-server.org/.
LICENSE
GPL License.
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.
BUGS
No bugs known yet.
SEE ALSO
gtk-server.cfg(1)
AUTHORS
Orignal concept, design and implementation by Peter van Eerten, e-mail : peter AT gtk-server DOT org
Current version of the GTK-server was created with help of many others - see the CREDITS file in
the sourcepackage for credits.
Index
- NAME
-
- SYNOPSIS
-
- DESCRIPTION
-
- ARGUMENTS
-
- OPTIONS
-
- SHARED OBJECT / DLL / MODULE
-
- INTERNAL COMMANDS
-
- FILES
-
- EXAMPLES
-
- LICENSE
-
- BUGS
-
- SEE ALSO
-
- AUTHORS
-
This document was created by
man2html,
using the manual pages.
Time: 17:40:35 GMT, August 26, 2006