1 .\" Copyright (c) 2014, 2015 Bert Burgemeister <trebbu@googlemail.com>
3 .\" Permission is hereby granted, free of charge, to any person obtaining
4 .\" a copy of this software and associated documentation files (the
5 .\" "Software"), to deal in the Software without restriction, including
6 .\" without limitation the rights to use, copy, modify, merge, publish,
7 .\" distribute, sublicense, and/or sell copies of the Software, and to
8 .\" permit persons to whom the Software is furnished to do so, subject to
9 .\" the following conditions:
11 .\" The above copyright notice and this permission notice shall be
12 .\" included in all copies or substantial portions of the Software.
14 .\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
15 .\" EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
16 .\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
17 .\" NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
18 .\" LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
19 .\" OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
20 .\" WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
22 .Dd September 23, 2015
27 .Nd Pipe-Driven GTK+ Interface
36 .Op Fl u Ar builder-file
39 is a helper program that displays graphical user
40 interfaces for other programs. It renders the GUI definition
41 found in a GtkBuilder XML file (created using the
43 interface designer), and communicates with the main program solely
44 through plain text messages via pipes or fifos. It provides access to
45 a subset of features of a subset of widgets of GTK+ 3. Simple
46 one-shot dialogs as well as more complex, long-running programs can be
54 Prints a help message and exits.
55 .It Fl e Ar parent-xid
56 Embeds the main window into the XEmbed socket
62 if necessary, and uses it for command input.
64 A command is a line of text. Its format is
73 is the name of the receiving widget;
75 is separated from the rest of the command by a single whitespace
76 character. Commands whose first non-whitespace character is
78 are considered comments and ignored.
79 Any occurences of the two-character sequences
83 will be converted into newline or carriage return, respectively.
84 Every other character following a backslash will be left unchanged,
85 but the backslash will be removed. Invalid commands are reported on
87 and are otherwise ignored. See
89 for applicable commands.
93 exists but is not a named pipe. The named pipe
95 is deleted upon successful program termination.
97 Default command input is
102 if necessary, and uses it for output of feedback messages from the
103 graphical user interface.
105 A feedback message is a line of text; its format is
114 is the name of the sending widget. See
116 for possible feedback messages.
120 exists but is not a named pipe. The named pipe
122 is deleted upon successful program termination.
124 Default feedback-message output is
126 .It Fl u Ar builder-file
127 Displays the graphical user interface
129 which should be created using the
131 user interface designer and saved in GtkBuilder (.ui) format. Widget
132 names should be alphanumeric, including underscores, and the main
139 Prints the GTK+ version and exits.
146 .Ss Any Widget (including widgets not mentioned in this document)
147 .Bl -tag -width "commands "
154 makes the widget grayed out
166 the widget, or makes it visible
172 .Bo Fa prop Ic : Ns Fa val Ns
175 .Fa prop Ic : Ns Fa val ...
181 of the widget style to
183 Properties not explicitly specified are reset to their default values.
185 .Bl -dash -offset indent -compact
187 .Qq Li label1:style font:Bold 11; background-color:green
189 .Qq Li label1:style font-style:italic; font-weight:bold; color:blue
191 .Qq Li frame1:style border-color:red yellow; border-width:5px
193 .Qq Li frame1:style border-radius:10px; transition:10s
195 For a description of possible color notations see
202 simulates a click on the
204 d widget, triggering a response as described with the widgets below.
206 .Bl -dash -offset indent -compact
208 The command is ignored by
215 .Sx GtkTreeViewColumn ;
217 .Sx GtkCalendar , GtkEntry , GtkFileChooserButton , GtkScale ,
220 report the currently selected item;
225 just open their respective dialogs.
232 kills the user interface. A non-empty
234 is required but ignored.
237 .Bl -tag -width "commands "
244 replaces the button text with
253 s with names ending in
254 .Ic _ok , _apply , _cancel , _send_text ,
257 may work differently; see
258 .Sx GtkDialog , GtkFileChooserDialog ,
264 .Bl -tag -width "commands "
275 selects the date on the calendar.
291 unmarks all days on the calendar.
314 .Bl -tag -width "commands "
318 .Ic :set_active Brq Ic 0 | 1
320 switches the check mark off
330 replaces the button text with
345 .Bl -tag -width "commands "
352 preselects the color.
355 .Bl -dash -offset indent -compact
357 a standard X11 color name, like
358 .Qq Li Dark Sea Green ,
360 a hexadecimal value in the form
371 an RGB color in the form
381 an RGBA color in the form
421 lie between 0 and 255, and
430 .Bl -tag -width "commands "
443 prepend/append a new selectable item marked
470 being the name of the child
496 if the dialog is the sole window of the GUI and therefore named
499 .Bl -tag -width "commands "
506 Most drawing commands expect an
508 parameter (an arbitrary non-negative integer) which can be used to reference the
509 command for later removal.
510 .Bl -tag -width "commands "
515 .Fa id x y radius angle1 angle2
517 adds a circular arc to the current path. The arc is centered at
519 and proceeds clockwise from
530 .Fa id x y radius angle1 angle2
532 adds a circular arc to the current path. The arc is centered at
534 and proceeds counterclockwise from
547 adds a line segment from the current point to the point most recently
558 .Fa id x1 y1 x2 y2 x3 y3
560 adds a cubic Bezier spline from the current point to
573 fills the current path and clears it.
580 fills the current path without clearing it.
587 adds a line from the current point to
595 sets the current point to
601 .Fa id x y width height
603 adds a rectangle to the current path. The top left corner is at
617 .Fa id dx1 dy1 dx2 dy2 dx3 dy3
619 adds a cubic Bezier spline from the current point to
625 as control points. All coordinates are offsets relative to the
633 adds a line from the current point to a point offset from there by
641 moves the current point by
649 removes the elements with
660 sets the dash pattern to
669 .Fa id l1on l1off l2on l2off ...
671 resets the dash pattern to a line with arbitrary on/off portions.
678 resets the dash pattern to a solid line.
685 sets the font size for subsequent calls of
693 .Brq Ic butt | round | square
695 sets the line cap style.
701 .Brq Ic miter | round | bevel
703 sets the line junction style.
719 is in the format used with
729 beginning at the current point.
736 strokes the current path and clears it.
743 strokes the current path without clearing it.
748 .Bl -tag -width "commands "
755 replaces the user-editable text with
760 .Ic :set_placeholder_text
765 that is displayed when the entry is empty and unfocused.
772 once for each change of
776 .Bl -tag -width "commands "
783 replaces the expander label text with
793 the child widget, or makes it visible
798 .Ss GtkFileChooserButton
799 .Bl -tag -width "commands "
808 to the extent it exists.
815 if the selection has changed.
817 .Ss GtkFileChooserDialog
819 .Ic GtkFileChooserDialog
831 .Ic GtkFileChooserDialog
840 if the dialog is the sole window of the GUI and therefore named
845 .Ic GtkFileChooserDialog
854 if the dialog is the sole window of the GUI and therefore named
859 .Ic GtkFileChooserDialog
868 if the dialog is the sole window of the GUI and therefore named
871 .Bl -tag -width "commands "
880 to the extent it exists.
884 .Ic :set_current_name
889 the suggested filename, which may not yet exist.
891 should either resemble an absolute path, or the
912 .Bl -tag -width "commands "
928 .Bl -tag -width "commands "
935 replaces the frame label text with
941 .Bl -tag -width "commands "
945 .Ic :set_from_icon_name
948 replaces the image with one of the standard icons.
955 replaces the image by the one found at
961 .Bl -tag -width "commands "
968 replaces the label text with
973 .Ss GtkMenuItem, GtkImageMenuItem
974 .Bl -tag -width "commands "
988 .Sx GtkFileChooserDialog
991 if it exists. If there isn't any dialog attached to the
1001 .Bl -tag -width "commands "
1005 .Ic :set_current_page
1008 switches to page number
1016 .Ss GtkPrintUnixDialog
1017 .Bl -tag -width "commands "
1024 opens the print dialog. Pressing the
1028 to the printer the user selected in the dialog.
1033 .Bl -tag -width "commands "
1040 moves the progress bar to
1051 replaces the text of the progress bar with
1053 Default is the progress percentage.
1058 .Bl -tag -width "commands "
1064 switches the button on. All other buttons of the same group will go off
1072 replaces the button text with
1087 .Bl -tag -width "commands "
1094 moves the slider to value
1100 .Fa floating_point_text
1105 may be unsupported by Glade, but its definition can be inserted
1106 manually into the GtkBuilder (.ui) file:
1109 \ \ \ \ <object class="GtkSocket" id="socket1">
1110 \ \ \ \ \ \ <property name="visible">True</property>
1111 \ \ \ \ \ \ <property name="can_focus">True</property>
1114 \ \ \ \ \ \ <property name="expand">True</property>
1115 \ \ \ \ \ \ <property name="fill">True</property>
1116 \ \ \ \ \ \ <property name="position">1</property>
1120 .Bl -tag -width "commands "
1126 requests a feedback message containing the socket
1134 can be used by another process to XEmbed its widgets into the
1145 Notification that the other process has inserted its widgets into or
1146 removed them from the
1150 .Bl -tag -width "commands "
1157 sets the selected value to
1167 .Bl -tag -width "commands "
1178 start and stop the spinner.
1183 .Bl -tag -width "commands "
1198 removes the last entry from the statusbar, revealing the penultimate
1205 empties the statusbar.
1210 .Bl -tag -width "commands "
1214 .Ic :set_active Brq Ic 0 | 1
1216 turns the switch off
1233 There should be a dedicated
1235 for sending (parts of) the text.
1245 will send the content of the
1252 will send the highlighted part the
1254 .Bl -tag -width "commands "
1261 replaces the user-editable text with
1272 .Ic :insert_at_cursor
1281 .Ic :place_cursor Brq Fa position | Ic end
1283 places the text cursor at
1285 or at the end of the text.
1289 .Ic :place_cursor_at_line
1292 places the text cursor at the beginning of
1297 .Ic :scroll_to_cursor
1299 scrolls to the cursor position if necessary.
1307 being the name of the
1313 and backslashes are replaced by
1317 .Bl -tag -width "commands "
1321 .Ic :set_active Brq Ic 0 | 1
1323 switches the button off
1333 replaces the button text with
1349 can deal with columns of type
1350 .Ic gboolean , gint , guint , glong , gulong , gint64 , guint64 , gfloat , gdouble ,
1357 refer to the underlying model (usually a
1358 .Ic GtkListStore ) .
1359 .Bl -tag -width "commands "
1366 replaces the content at
1370 (which should be compatible with the type of
1375 .Ic :insert_row Brq Fa position | Ic end
1377 inserts a new, empty row at
1379 or at the end of the list.
1384 .Fa origin Brq Fa destination | Ic end
1390 or to the end of the list.
1417 .Fa column_type row column value
1419 one message per selected row and column in the underlying model if
1420 the set of selected rows has changed.
1422 .Ss GtkTreeViewColumn
1423 .Bl -tag -width "commands "
1433 .Ss Discovering Pipeglade Interactively
1434 Suppose the interface in
1447 will be reported on the terminal. Typing
1448 .Dl label1:set_text Button Label
1449 will change the text shown on the label into
1451 .Ss One-Shot File Dialog
1452 Suppose the interface in
1453 .Pa ./simple_open.ui
1455 .Sx GtkFileChooserDialog
1462 .Dl pipeglade -u simple_open.ui
1463 will open the dialog; pressing
1465 will close it after sending the selected filename to
1467 .Ss One-Shot User Notification
1469 .Pa ./simple_dialog.ui
1474 .Dl pipeglade -u simple_dialog.ui <<< \e
1475 .Dl \ \ \ \ \&"label1:set_text NOW READ THIS!\&"
1476 will set the label text accordingly and wait for user input.
1477 .Ss Continuous Input
1478 The following shell command displays a running clock:
1480 .Dl \ \ \ \ echo \&"label1:set_text `date`\&";
1481 .Dl \ \ \ \ sleep 1;
1482 .Dl done | pipeglade -u simple_dialog.ui
1483 .Ss Continuous Input and Output
1484 The following shell script fragment sets up
1486 for continuous communication with another program,
1488 .Dl pipeglade -i in.fifo -o out.fifo &
1489 .Dl # wait for in.fifo and out.fifo to appear
1490 .Dl while test \& ! \e( -e in.fifo -a -e out.fifo \e); do :; done
1491 .Dl main_prog <out.fifo >in.fifo
1494 exits 0 on success, and >0 if an error occurs.
1506 .An Bert Burgemeister Aq trebbu@googlemail.com .