PIPEGLADE(1)

Programmer's Manual

PIPEGLADE(1)

NAME

pipeglade — pipe-driven GTK+ interface

SYNOPSIS

pipeglade

[[-i in-fifo] [-o out-fifo] [-b] [-u builder-file] [-e parent-xid] [-l log-file] [-O err-file] [--display X-server]] | [-h | -G | -V]

DESCRIPTION

pipeglade is a helper program that displays graphical user interfaces for other programs. It renders the GUI definition found in a GtkBuilder XML file (typically created using the glade(1) interface designer), and communicates with the main program solely through plain text messages via pipes or fifos. It provides access to a subset of features of a subset of widgets of GTK+ 3. Simple one-shot dialogs as well as more complex, long-running programs can be built using pipeglade; see EXAMPLES.

OPTIONS

-i in-fifo

Creates a named pipe in-fifo if necessary, sets its permissions to 0600, and uses it for command input.

A command is a line of text. Its format is “id:action [data]”, id being the name of the receiving widget; data is separated from the rest of the command by a single whitespace character. Commands whose first non-whitespace character is # are considered comments and ignored silently, as are empty input lines. Any occurences of the two-character sequences \n and \r will be converted into newline or carriage return, respectively. Every other character following a backslash will be left unchanged, but the backslash will be removed. Invalid commands are reported on stderr and are otherwise ignored. See WIDGETS for applicable commands.

It is an error if in-fifo exists but is not a named pipe. The named pipe in-fifo is deleted upon successful program termination.

Default command input is stdin.

-o out-fifo

Creates a named pipe out-fifo if necessary, sets its permissions to 0600, and uses it for output of feedback messages from the graphical user interface.

A feedback message is a line of text; its format is “id:info [data]”, id being the name of the sending widget. See WIDGETS for possible feedback messages.

It is an error if out-fifo exists but is not a named pipe. The named pipe out-fifo is deleted upon successful program termination.

Default feedback-message output is stdout.

-b

Runs pipeglade in the background after printing its process ID to stdout.

It is an error if option -b is used and not both -i in-fifo and -o out-fifo are specified.

-u builder-file

Displays the graphical user interface builder-file which should be created using the glade(1) user interface designer and saved in GtkBuilder (.ui) format. Widget ids should consist of alphanumeric ASCII characters including hyphens and underscores. The main window must must be given the id main.

Default is ./pipeglade.ui.

-e parent-xid

Embeds the main window into the XEmbed socket parent-xid of another process.

-l log-file

Appends for each command a line of “time activity” to log-file, time being the number of microseconds elapsed during activity. time and activity are separated by a tab character. Permissions of log-file are set to 0600. A log-file name of ‘-' means stderr.

-O err-file

Redirects stderr, appending its output to err-file. Permissions of err-file are set to 0600.

--display X-server

Uses the display on X-server for user interaction.

-h

Prints a help message and exits.

-G

Prints the versions of the underlying GTK+ and cairo libraries and exits.

-V

Prints the pipeglade version and exits.

WIDGETS

The widget classes able to communicate through pipeglade are GtkAspectFrame, GtkBox, GtkButton, GtkButtonBox, GtkCalendar, GtkCheckButton, GtkColorButton, GtkComboBoxText, GtkDialog, GtkDrawingArea, GtkEntry, GtkEventBox, GtkExpander, GtkFileChooserButton, GtkFileChooserDialog, GtkFontButton, GtkFrame, GtkGrid, GtkImage, GtkImageMenuItem, GtkInfoBar, GtkLabel, GtkLinkButton, GtkMenu, GtkMenuBar, GtkMenuButton, GtkMenuItem, GtkNotebook, GtkOverlay, GtkPaned, GtkPlug, GtkPrintUnixDialog, GtkProgressBar, GtkRadioButton, GtkScale, GtkScrolledWindow, GtkSeparator, GtkSeparatorMenuItem, GtkSizeGroup, GtkSocket, GtkSpinButton, GtkSpinner, GtkStatusbar, GtkSwitch, GtkTextView, GtkToggleButton, GtkTreeView, GtkTreeViewColumn, GtkViewport, and GtkWindow.

pipeglade references a widget by the id attribute it is given in Glade. In the .ui file, a GtkWindow named foo would appear as

<object class="GtkWindow" id="foo">.

Unspecific Widget

GtkAspectFrame

GtkBox

GtkButton

GtkButtonBox

GtkCalendar

GtkCheckButton

GtkColorButton

GtkComboBoxText

The GtkComboBoxText should contain a GtkEntry.

GtkDialog

A GtkDialog with id foo will be invoked by a GtkMenuItem or a GtkImageMenuItem with id foo_invoke.

The GtkDialog should have a ‘Cancel' GtkButton with id foo_cancel (main_cancel if the dialog is the sole window of the GUI and therefore named main).

If the GtkDialog has an ‘Ok' GtkButton with id foo_ok, it will take care of hiding the dialog window.

GtkDrawingArea

Drawing commands expect a context parameter of the form {n|=n|n<m} where n is an arbitrary non-negative integer that can be used later to reference the command. The first form, n, appends its command to the current list of drawing operations. The second form, =n, replaces the first drawing operation with context parameter n by the new command. The third form, n<m, inserts its command before the first drawing operation with context parameter m. Both second and third form fall back to appending.

The default coordinate system is a left-handed system with its origin in the upper-left corner. Angles increase from the positive X axis towards the positve Y axis (clockwise in the default system).

GtkEntry

GtkEventBox

x, y are mouse pointer coordinates relative to the GtkEventBox.

GtkExpander

GtkGrid

GtkFileChooserButton

GtkFileChooserDialog

A GtkFileChooserDialog with id foo will be invoked by a GtkMenuItem or a GtkImageMenuItem with id foo_invoke.

The GtkFileChooserDialog should have an ‘OK' GtkButton with id foo_ok (main_ok if the dialog is the sole window of the GUI and therefore named main).

The GtkFileChooserDialog may have a ‘Cancel' GtkButton with id foo_cancel (main_cancel if the dialog is the sole window of the GUI and therefore named main).

The GtkFileChooserDialog may have an ‘Apply' GtkButton with id foo_apply (main_apply if the dialog is the sole window of the GUI and therefore named main).

GtkFontButton

GtkFrame

GtkImage

GtkMenu

GtkMenuButton

GtkImageMenuItem

GtkImageMenuItem is deprecated.

GtkInfoBar

GtkLabel

GtkLinkButton

GtkMenuBar

GtkMenuItem

GtkNotebook

GtkOverlay

GtkPaned

GtkPlug

The main window can be turned into a GtkPlug and embedded into the XEmbed socket of another process; see OPTIONS, option -e.

GtkPrintUnixDialog

GtkProgressBar

GtkRadioButton

GtkScale

GtkScrolledWindow

GtkSeparator

GtkSeparatorMenuItem

GtkSizeGroup

GtkSocket

GtkSocket may be unsupported by Glade, but its definition can be inserted manually into the GtkBuilder (.ui) file:

<child> 
  <object class="GtkSocket" id="socket1"> 
    <property name="visible">True</property> 
    <property name="can_focus">True</property> 
  </object> 
  <packing> 
    <property name="expand">True</property> 
    <property name="fill">True</property> 
    <property name="position">1</property> 
  </packing> 
</child>

GtkSpinButton

GtkSpinner

GtkStatusbar

The context parameter c is an arbitrary non-whitespace string.

GtkSwitch

GtkTextView

There should be a dedicated GtkButton for sending (parts of) the text. If the id of the GtkTextView is foo, a GtkButton with id foo_send_text will send the content of the GtkTextView; a GtkButton with id foo_send_selection will send the highlighted part the GtkTextView.

GtkToggleButton

GtkTreeView

pipeglade can deal with columns of type gboolean, gint, guint, glong, gulong, gint64, guint64, gfloat, gdouble, and gchararray.

row and column refer to the underlying model (GtkListStore or GtkTreeStore). row is a sequence of one or more colon-separated integers, e.g. ‘3' or ‘0:0:1'.

GtkTreeViewColumn

GtkViewport

GtkWindow

SPECIAL SYNTAX

Style

“id:style [prop:val[; prop:val ...]]” sets properties prop of the widget style to val. Properties not explicitly specified are reset to their default values. Examples:

‘label1:style font:Bold 11; background-color:green'
‘label1:style font-style:italic; font-weight:bold; color:blue'
‘button1:style background-image:url("q.png")'
‘treeview1:style background-image:linear-gradient(45deg, yellow, blue);'
‘frame1:style border-color:red yellow; border-width:5px'
‘frame1:style border-radius:10px; transition:10s'

For color notations see Color, below.

Color

Possible color notations:

standard X11 colors names like ‘blue', ‘Dark Sea Green', or ‘Red';
‘transparent';
hexadecimal values in the form #rgb, #rrggbb, #rrrgggbbb, or #rrrrggggbbbb;
RGB colors in the form rgb(red,green,blue) or RGBA colors in the form rgba(red,green,blue,alpha); red, green, blue between 0 and 255 and alpha between 0 and 1;
color expressions like ‘darker(blue)' or ‘lighter(currentColor)'.

EXIT STATUS

The pipeglade utility exits 0 on success, and >0 if an error occurs.

EXAMPLES

Discovering Pipeglade Interactively

Suppose the interface in ./pipeglade.ui has a GtkLabel ‘label1' and a GtkButton ‘button1'. After invoking

pipeglade

and clicking the GtkButton, ‘button1:clicked' will be reported on the terminal. Typing

label1:set_text The Button

will change the text shown on the label into ‘The Button'.

One-Shot File Dialog

Suppose the interface in ./simple_open.ui contains a GtkFileChooserDialog with an ‘OK' GtkButton whose id is ‘main_ok'. Invoking

pipeglade -u simple_open.ui

will open the dialog; pressing ‘OK' will close it after sending the selected filename to stdout.

One-Shot User Notification

If the interface in ./simple_dialog.ui contains a GtkLabel ‘label1', then

pipeglade -u simple_dialog.ui <<< \ 
    "label1:set_text NOW READ THIS!"

will set the label text accordingly and wait for user input.

Continuous Input

The following shell command displays a running clock:

while true; do 
    echo "label1:set_text `date`"; 
    sleep 1; 
done | pipeglade -u simple_dialog.ui

Continuous Input and Output

The following shell script fragment sets up pipeglade for continuous communication with another program, main_prog:

pipeglade -i in.fifo -o out.fifo -b 
main_prog <out.fifo >in.fifo

AUTHOR

pipeglade was written by Bert Burgemeister <trebbu@googlemail.com>.

BUGS

Due to what appears to be a bug in cairo v1.14.0, pipeglade used with this library version occasionally crashes on GtkDrawingArea commands.

October 11, 2017

BSD