gtk-server.cfg(1)

🎀 gtk-server.cfg(1) — General Commands Manual 🎀

okay so bestie, you've found the manual page for gtk-server.cfg(1) from the General Commands Manual. This file is lowkey the main character energy of GTK-server configs, and the way it tells the server which libraries and functions to use is kind of iconic. no cap, every detail below matters, so let's get into it. 💅

💖 NAME 💖

gtk-server.cfg — the configfile for the gtk-server. periodt.

📜 SYNOPSIS 📜

gtk-server.cfg

🌈 DESCRIPTION 🌈

The gtk-server.cfg file is the configfile used by the GTK-server. If it's available in the same directory as your client script, the GTK-server will read this local configfile (preferred, fr fr). This way each client program can use its own GTK configuration. If the configfile is not available locally, the GTK-server follows this exact logic:

1. Try reading the environment variable GTK_SERVER_CONFIG. This variable should contain the full path and name to the configfile.
2. Try finding the (hidden) configfile in the homedir of the user. The name of the configfile should be preceded by a dot, e.g. .gtk-server.cfg.
3. Try finding the configfile in the /etc directory.
4. Try finding the configfile in the /usr/local/etc directory.

The gtk-server.cfg file contains the descriptions of the GTK functions which will be used by your client script. The format of the file is <KEYWORD = VALUE>. Lines starting with a hash # will be skipped. The keywords must be written using capitals.

The following keywords are recognized by the GTK-server:

• LIB_NAME = <library name 1, library name 2, ...> — tells the server the names of the libraries (.so or .dll) to open. This keyword may occur multiple times in the configfile. At a maximum 64 libraries can be opened simultaneously. The library name should end with the plain so suffix. If the GTK-server cannot find the library, it automatically will append a numeric suffix to the original name varying from 0 to 99 and attempt to open these library names also, until the correct numeric suffix was found.

Example:

LIB_NAME = libgtk-x11-2.0.so, libgdk-x11-2.0.so, libglib-2.0.so, libgobject-2.0.so

• INCLUDE = <file> — defines an additional configuration file with additional GTK function descriptions or macros.

Example:

INCLUDE = /etc/gtk-extra.cfg

• SEQUENCE = <maximum> — when opening a library, the GTK-server will search and attempt to use subsequent library version numbers up to this definition. The default value is 100.

Example:

SEQUENCE = 10

• FUNCTION_NAME = <func>, <callback>, <type>, <amount>, <arg1>...<argx> — every GTK function used by a script must be described here. Here's the order, bestie:
  • First, the name of the function itself must be mentioned.
  • After that, a callback signal if applicable. The real names for the GTK callback signals must be used here.
  • Then the type of the return value must be specified. The type can be one of the following: NONE, VOID, WIDGET, POINTER, BOOL, STRING, INT, LONG, DOUBLE, FLOAT or ADDRESS.
  • After that, it must be clear how many arguments the GTK function needs.
  • Finally, the type of each individual argument must be declared. The type of the arguments can be one of the following: NULL, WIDGET, POINTER, BOOL, STRING, INT, LONG, DOUBLE, FLOAT, ENUM, STR, CLASS, MACRO, DATA, BASE64 or VARARGS.
  • The ADDRESS return type is used to return the address of a function in memory.
  • The BASE64 argument type is used to send base64 encoded binary data to the GTK-server. The POINTER argument type can be used for generic pointers and non-GTK libraries.
  • The MACRO argument type can be used in case a user function needs to be registered. In case GTK must execute a user function, the described macro will be used. A MACRO type always needs a DATA type, in which additional data can be specified. Macros are explained in the MACRO section of this manpage.
  • The ENUM and STR argument types refer to their corresponding ENUM_NAME and STR_NAME definitions (see below). Instead of ENUM, the types INT or LONG may be used as well. Similarly, instead of STR, it is allowed to plainly use STRING.
  • The CLASS argument type refers to Motif widget classes. These are hardcoded and cannot be configured in the GTK-server configuration file.
  • The VARARGS argument defines the variable arguments list. The client script can enter a variable amount of arguments, but each argument should be prefixed with a type indication: i means int, l means long, s means string and so on. The NULL does not need a prefix.
  • The gtk-server.cfg file may not contain duplicate function definitions. This is verified by the GTK-server during startup.
  • Examples:

FUNCTION_NAME = gtk_window_new, delete-event, WIDGET, 1, LONG
FUNCTION_NAME = XtVaCreateWidget, NONE, WIDGET, 4, STRING, CLASS, WIDGET, VARARGS

• ENUM_NAME = <name>, <integer> — the GTK and also the XForms API use a lot of predefined constants and enumerations. With this optional configuration line these can be defined also. The client script can use the same enumeration name, and the GTK-server will substitute to the corresponding value automatically. Values may be entered in decimal, octal or hexadecimal format. With octal use a preceding 0, and hexadecimal a preceding 0x or 0X.
  • Please note that enumeration names only may contain integer values. So in a defined GTK function, only at arguments defined as INT, LONG or ENUM the GTK-server will check for an enumeration name. If it cannot match an enumeration name, it is assumed there is a real value.
  • Duplicate enumeration names are not allowed. This is verified by the GTK-server during startup.

Example:

ENUM_NAME = GTK_WINDOW_TOPLEVEL, 0

• STR_NAME = <name>, <string> — the Motif API uses a lot of predefined strings. With this optional configuration line these strings can be set to their real names. The client script can use the original string name, and the GTK-server will substitute to the corresponding real string value automatically.
  • The GTK-server will lookup the string names in any argument defined as a STRING.
  • Duplicate string names are not allowed. This is verified by the GTK-server during startup.

Example:

STR_NAME = XmNactivateCallback, activateCallback

• ALIAS_NAME = <alias>, <real name> — some functions in external libraries may have the same name as an existing statement in a programming language. For example, shell scripts can use the statement read, while the function read also can be imported from libc. In order to avoid the client interpreter mixing up these statements, it is possible to define an alias. So instead of using the real name, the client program can use the defined alias to invoke the external function.
  • Aliasing also allows the programmer to rename external functions so they comply to the standard of the client language.
  • Duplicate alias names are not allowed. This is verified by the GTK-server during startup.

Example:

ALIAS_NAME = libc_read, read

• MACRO <name> <...> ENDMACRO — for an explanation on macros see below.

🫶 Pointer arguments 🫶

Some GTK functions return a result in their pointer arguments. The way to retrieve the value from such arguments is to create a definition for the GTK function with special parameters. For example:

FUNCTION_NAME = gdk_window_get_pointer, NONE, WIDGET, 4, WIDGET, PTR_INT, PTR_INT, NULL

In this case, a call to gdk_window_get_pointer will return a widget but also the values stored in the second and third argument. The returned result will be formatted in S-expression syntax, just as the GTK-server also accepts S-expression syntax. Next to the type PTR_INT the types PTR_LONG, PTR_FLOAT, PTR_DOUBLE, PTR_STRING, PTR_BOOL, PTR_SHORT, PTR_WIDGET and PTR_BASE64 can be used.

When actually invoking the defined function, a dummy argument can be used in case of the numeric PTR argument types. Also the PTR_BASE64 type should have a dummy argument in place.

The PTR_STRING and PTR_WIDGET argument types however assume a pointer with sufficiently allocated memory.

In case of the PTR_BASE64 type, the function argument will return a Base64 encoded string which contains binary data. Before invoking the actual function, make sure to first set the memory layout of the binary data with the internal gtk_server_data_format function. After that, the returned Base64 string can be decoded using the internal gtk_server_unpack function. 🦋

🧚 MACROS 🧚

Okay bestie, so here’s the tea: in GTK sometimes you need more than one function to define a widget. Those functions can be grouped into a macro, and from a clientscript you can just use the macro’s name to invoke it. A macro can have this exact layout:

MACRO <name>
$a : GTK_function
GTK_function $1 $2 $3
...
RETURN <value>
ENDMACRO

Each line in the macro may contain only one GTK function. A macro can be invoked with arguments. Inside the macro those arguments are denoted with $1, $2, $3 and so on. The $0 points to the macroname itself. You can also refer to all arguments at once with $@. A macro can accept up to 9 arguments. If there are more arguments, then those are ignored. 💅

Macros may also use variables. Variablenames must start with a dollarsign $. After that, only the first letter of the variablename is important, which means there are at most 26 variables in each macro (lowercase). ✨

Within a macro, it is possible to assign a result of a GTK function to a variable. However, it is important that the colon symbol, which is the assignment operator, is not attached to the variablename or the GTK functionname. For example:

$window : gtk_window_new GTK_WINDOW_TOPLEVEL

Also it is possible to assign a string to a variable. To do this, the string should be preceded by the & sign. For example:

$var : &Hello world

Variables in macros are initialized to zero automatically, but keep their values after the macro object has been executed. Afterwards the variables can be retrieved in your clientscript by using the call gtk_server_macro_var. For example:

gtk_server_macro_var <macroname> var

There are a few commands to use in macros. These should be written in capitals. For example, it is possible to perform a relative jump on the condition of the value of a variable. The command VALUE jumps when a variable contains a value not equal to zero, and the command EMPTY jumps when a variable is zero. The command JUMP always jumps, no matter what condition. For example:

$var VALUE 3

In this example, the GTK-server will jump three statements forward in case the variable var is not equal to zero. The commands EMPTY, VALUE and JUMP can jump forward and backward, but only within the macro object. Jumps outside the macro will just go to the end of the macro, or to the beginning if the jump is negative. 🦋

Next to jumps, a comparison between variables can be made with COMPARE. When two variables are compared, the result of the comparison will be put into the local z-variable. So if the contents of the compared variables are equal, the z-variable will be 0. Else the local z-variable will be 1. For example:

$event COMPARE $window
$z EMPTY -5

Also it is possible to setup associative arrays. An associative array is globally visible to all macros. With associative arrays the main returnvalue of a macro can be connected to another value. This way multiple results can be returned from a macro. An array with one element can be defined as follows:

$ebox ASSOC $pix

If, to another macro, the ebox is passed as an argument, the associated value can be retrieved in that macro as follows:

$pix GET $1

In this example, the pix variable will be assigned the value associated to the first argument of the macro. There is no limit to the amount of associations; associative arrays can be of endless length, for example:

$ebox ASSOC $pix
$pix ASSOC $widget
$widget ASSOC $window
[...]

All values can be retrieved using an inverse GET:

$pix GET $1
$widget GET $pix
$window GET $widget
[...]

Note that with all operator commands, which are GET, ASSOC, COMPARE, VALUE, EMPTY, and the :, the left operand must be a variable. 👑

It is not allowed to define a macro within a macro. Also, duplicate macro names are not allowed. However, macros may invoke other macros. Also, macros may return a value to the client script with the keyword RETURN. For example:

RETURN $window

To find out which value is assigned to a variable, the command DEBUG can be used. This will print the result in the logfile, if logging is enabled. Example:

DEBUG $button

The Highlevel Universal GUI (HUG) defined in the GTK-server configfile is implemented using macro objects. 🫶

---

🌸 EXAMPLES 🌸

An example of a gtk-server.cfg file can be found in the sourcepackage. 🎀

---

👑 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.

---

🦋 SEE ALSO 🦋

• gtk-server(1)
• stop-gtk-server(1)

---

💜 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. 🌈

---

Okay bestie, that’s the end of gtk-server.cfg(1) 💖 The footer in this copy is just the page name gtk-server.cfg(1), with no separate source/version or date line attached — so I’m not gonna invent one, periodt. Bye! 🎀