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]

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. This is the preferred communication interface. The client script language must start a 2-way pipe to the GTK-server to enable communication. (In KSH and AWK the symbol '|&' is used for that.)
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 remain on disk unless explicitly deleted by the script.

OPTIONS

The GTK-server can be started with the following option:

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.

INTERNAL COMMANDS

The GTK-server has 8 internal commands which can be used.

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.

gtk_server_connect <widgetID> <signal> <description>

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 last argument is the string which will be returned by the GTK-server when the signal has occured.

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:

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.

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.

AUTHORS

Orignal concept, design and implementation by Peter van Eerten, e-mail : peter@gtk-server.org

Current version of the GTK-server was created with help of many others - see the CREDITS file in the sourcepackage for credits.

This document was created by man2html, using the manual pages.
Time: 22:56:12 GMT, September 06, 2005