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.
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.
58 if necessary, and uses it for command input.
60 A command is a line of text. Its format is
69 is the name of the receiving widget;
71 is separated from the rest of the command by a single whitespace
72 character. Commands whose first non-whitespace character is
74 are considered comments and ignored.
75 Any occurences of the two-character sequences
79 will be converted into newline or carriage return, respectively.
80 Every other character following a backslash will be left unchanged,
81 but the backslash will be removed. Invalid commands are reported on
83 and are otherwise ignored. See
85 for applicable commands.
89 exists but is not a named pipe. The named pipe
91 is deleted upon successful program termination.
93 Default command input is
98 if necessary, and uses it for output of feedback messages from the
99 graphical user interface.
101 A feedback message a line of text; its format is
110 ist the name of the sending widget. See
112 for possible feedback messages.
116 exists but is not a named pipe. The named pipe
118 is deleted upon successful program termination.
120 Default feedback-message output is
122 .It Fl u Ar builder-file
123 Displays the graphical user interface
125 which should be created using the
127 user interface designer and saved in GtkBuilder (.ui) format. Widget
128 names should be alphanumeric, including underscores, and the main
135 Prints the GTK+ version and exits.
142 .Ss Any Widget (including widgets not mentioned in this document)
143 .Bl -tag -width "commands "
150 makes the widget grayed out
162 the widget, or makes it visible
170 sets the color of the widget. Default is the original color. The
173 is identical to the format used with
178 .Ic :override_background_color
181 sets the background color of the widget. Default is the original
182 background color. The format of
184 is identical to the format used with
192 sets the font of the widget. Default is the original font.
195 .Qq Li Monospace,Serif Bold Italic Condensed 16 ,
204 simulates a click on the
206 d widget, triggering a response as described with the widgets below.
208 .Bl -dash -offset indent -compact
210 The command is ignored by
217 .Sx GtkTreeViewColumn ;
219 .Sx GtkCalendar , GtkEntry , GtkFileChooserButton , GtkScale ,
222 report the currently selected item;
227 just open their respective dialogs.
234 kills the user interface. A non-empty
236 is required but ignored.
239 .Bl -tag -width "commands "
246 replaces the button text with
255 s with names ending in
256 .Ic _ok , _apply , _cancel , _send_text ,
259 may work differently; see
260 .Sx GtkDialog , GtkFileChooserDialog ,
266 .Bl -tag -width "commands "
277 selects the date on the calendar.
293 unmarks all days on the calendar.
316 .Bl -tag -width "commands "
320 .Ic :set_active Brq Ic 0 | 1
322 switches the check mark off
332 replaces the button text with
347 .Bl -tag -width "commands "
354 preselects the color.
357 .Bl -dash -offset indent -compact
359 a standard X11 color name, like
360 .Qq Li Dark Sea Green ,
362 a hexadecimal value in the form
373 an RGB color in the form
383 an RGBA color in the form
423 lie between 0 and 255, and
432 .Bl -tag -width "commands "
445 prepend/append a new selectable item marked
472 being the name of the child
498 if the dialog is the sole window of the GUI and therefore named
501 .Bl -tag -width "commands "
508 Most drawing commands expect an
510 parameter (an arbitrary non-negative integer) which can be used to reference the
511 command for later removal.
512 .Bl -tag -width "commands "
517 .Fa id x y radius angle1 angle2
519 adds a circular arc to the current path. The arc is centered at
521 and proceeds clockwise from
532 .Fa id x y radius angle1 angle2
534 adds a circular arc to the current path. The arc is centered at
536 and proceeds counterclockwise from
549 adds a line segment from the current point to the point most recently
560 .Fa id x1 y1 x2 y2 x3 y3
562 adds a cubic Bezier spline from the current point to
575 fills the current path and clears it.
582 fills the current path without clearing it.
589 adds a line from the current point to
597 sets the current point to
603 .Fa id x y width height
605 adds a rectangle to the current path. The top left corner is at
619 .Fa id dx1 dy1 dx2 dy2 dx3 dy3
621 adds a cubic Bezier spline from the current point to
627 as control points. All coordinates are offsets relative to the
635 adds a line from the current point to a point offset from there by
643 moves the current point by
651 removes the elements with
662 sets the dash pattern to
671 .Fa id l1on l1off l2on l2off ...
673 resets the dash pattern to a line with arbitrary on/off portions.
680 resets the dash pattern to a solid line.
687 sets the font size for subsequent calls of
695 .Brq Ic butt | round | square
697 sets the line cap style.
703 .Brq Ic miter | round | bevel
705 sets the line junction style.
721 is in the format used with
731 beginning at the current point.
738 strokes the current path and clears it.
745 strokes the current path without clearing it.
750 .Bl -tag -width "commands "
757 replaces the user-editable text with
765 once for each change of
769 .Bl -tag -width "commands "
776 replaces the expander label text with
786 the child widget, or makes it visible
791 .Ss GtkFileChooserButton
792 .Bl -tag -width "commands "
801 to the extent it exists.
808 if the selection has changed.
810 .Ss GtkFileChooserDialog
812 .Ic GtkFileChooserDialog
824 .Ic GtkFileChooserDialog
833 if the dialog is the sole window of the GUI and therefore named
838 .Ic GtkFileChooserDialog
847 if the dialog is the sole window of the GUI and therefore named
852 .Ic GtkFileChooserDialog
861 if the dialog is the sole window of the GUI and therefore named
864 .Bl -tag -width "commands "
873 to the extent it exists.
877 .Ic :set_current_name
882 the suggested filename, which may not yet exist.
884 should either resemble an absolute path, or the
905 .Bl -tag -width "commands "
921 .Bl -tag -width "commands "
928 replaces the frame label text with
934 .Bl -tag -width "commands "
938 .Ic :set_from_icon_name
941 replaces the image with one of the standard icons.
948 replaces the image by the one found at
954 .Bl -tag -width "commands "
961 replaces the label text with
966 .Ss GtkMenuItem, GtkImageMenuItem
967 .Bl -tag -width "commands "
981 .Sx GtkFileChooserDialog
984 if it exists. If there isn't any dialog attached to the
994 .Bl -tag -width "commands "
998 .Ic :set_current_page
1001 switches to page number
1010 .Bl -tag -width "commands "
1017 moves the progress bar to
1028 replaces the text of the progress bar with
1030 Default is the progress percentage.
1035 .Bl -tag -width "commands "
1041 switches the button on. All other buttons of the same group will go off
1049 replaces the button text with
1064 .Bl -tag -width "commands "
1071 moves the slider to value
1077 .Fa floating_point_text
1081 .Bl -tag -width "commands "
1088 sets the selected value to
1098 .Bl -tag -width "commands "
1109 start and stop the spinner.
1114 .Bl -tag -width "commands "
1129 removes the last entry from the statusbar, revealing the penultimate
1136 empties the statusbar.
1141 .Bl -tag -width "commands "
1145 .Ic :set_active Brq Ic 0 | 1
1147 turns the switch off
1164 There should be a dedicated
1166 for sending (parts of) the text.
1176 will send the content of the
1183 will send the highlighted part the
1185 .Bl -tag -width "commands "
1192 replaces the user-editable text with
1203 .Ic :insert_at_cursor
1212 .Ic :place_cursor Brq Fa position | Ic end
1214 places the text cursor at
1216 or at the end of the text.
1220 .Ic :place_cursor_at_line
1223 places the text cursor at the beginning of
1228 .Ic :scroll_to_cursor
1230 scrolls to the cursor position if necessary.
1238 being the name of the
1244 and backslashes are replaced by
1248 .Bl -tag -width "commands "
1252 .Ic :set_active Brq Ic 0 | 1
1254 switches the button off
1264 replaces the button text with
1280 can deal with columns of type
1281 .Ic gboolean , gint , guint , glong , gulong , gint64 , guint64 , gfloat , gdouble ,
1288 refer to the underlying model (usually a
1289 .Ic GtkListStore ) .
1290 .Bl -tag -width "commands "
1297 replaces the content at
1301 (which should be compatible with the type of
1306 .Ic :insert_row Brq Fa position | Ic end
1308 inserts a new, empty row at
1310 or at the end of the list.
1315 .Fa origin Brq Fa destination | Ic end
1321 or to the end of the list.
1348 .Fa column_type row column value
1350 one message per selected row and column in the underlying model if
1351 the set of selected rows has changed.
1353 .Ss GtkTreeViewColumn
1354 .Bl -tag -width "commands "
1364 .Ss Discovering Pipeglade Interactively
1365 Suppose the interface in
1378 will be reported on the terminal. Typing
1379 .Dl label1:set_text Button Label
1380 will change the text shown on the label into
1382 .Ss One-Shot File Dialog
1383 Suppose the interface in
1384 .Pa ./simple_open.ui
1386 .Sx GtkFileChooserDialog
1393 .Dl pipeglade -u simple_open.ui
1394 will open the dialog; pressing
1396 will close it after sending the selected filename to
1398 .Ss One-Shot User Notification
1400 .Pa ./simple_dialog.ui
1405 .Dl pipeglade -u simple_dialog.ui <<< \e
1406 .Dl \ \ \ \ \&"label1:set_text NOW READ THIS!\&"
1407 will set the label text accordingly and wait for user input.
1408 .Ss Continuous Input
1409 The following shell command displays a running clock:
1411 .Dl \ \ \ \ echo \&"label1:set_text `date`\&";
1412 .Dl \ \ \ \ sleep 1;
1413 .Dl done | pipeglade -u simple_dialog.ui
1414 .Ss Continuous Input and Output
1415 The following shell script fragment sets up
1417 for continuous communication with another program,
1419 .Dl pipeglade -i in.fifo -o out.fifo &
1420 .Dl # wait for in.fifo and out.fifo to appear
1421 .Dl while test \& ! \e( -e in.fifo -a -e out.fifo \e); do :; done
1422 .Dl main_prog <out.fifo >in.fifo
1425 exits 0 on success, and >0 if an error occurs.
1437 .An Bert Burgemeister Aq trebbu@googlemail.com .