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.
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 is a line of text; its format is
110 is 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
168 .Bo Fa prop Ic : Ns Fa val Ns
171 .Fa prop Ic : Ns Fa val ...
177 of the widget style to
179 Properties not explicitly specified are reset to their default values.
181 .Bl -dash -offset indent -compact
183 .Qq Li label1:style font:Bold 11; background-color:green
185 .Qq Li label1:style font-style:italic; font-weight:bold; color:blue
187 .Qq Li frame1:style border-color:red yellow; border-width:5px
189 .Qq Li frame1:style border-radius:10px; transition:10s
191 For a description of possible color notations see
198 simulates a click on the
200 d widget, triggering a response as described with the widgets below.
202 .Bl -dash -offset indent -compact
204 The command is ignored by
211 .Sx GtkTreeViewColumn ;
213 .Sx GtkCalendar , GtkEntry , GtkFileChooserButton , GtkScale ,
216 report the currently selected item;
221 just open their respective dialogs.
228 kills the user interface. A non-empty
230 is required but ignored.
233 .Bl -tag -width "commands "
240 replaces the button text with
249 s with names ending in
250 .Ic _ok , _apply , _cancel , _send_text ,
253 may work differently; see
254 .Sx GtkDialog , GtkFileChooserDialog ,
260 .Bl -tag -width "commands "
271 selects the date on the calendar.
287 unmarks all days on the calendar.
310 .Bl -tag -width "commands "
314 .Ic :set_active Brq Ic 0 | 1
316 switches the check mark off
326 replaces the button text with
341 .Bl -tag -width "commands "
348 preselects the color.
351 .Bl -dash -offset indent -compact
353 a standard X11 color name, like
354 .Qq Li Dark Sea Green ,
356 a hexadecimal value in the form
367 an RGB color in the form
377 an RGBA color in the form
417 lie between 0 and 255, and
426 .Bl -tag -width "commands "
439 prepend/append a new selectable item marked
466 being the name of the child
492 if the dialog is the sole window of the GUI and therefore named
495 .Bl -tag -width "commands "
502 Most drawing commands expect an
504 parameter (an arbitrary non-negative integer) which can be used to reference the
505 command for later removal.
506 .Bl -tag -width "commands "
511 .Fa id x y radius angle1 angle2
513 adds a circular arc to the current path. The arc is centered at
515 and proceeds clockwise from
526 .Fa id x y radius angle1 angle2
528 adds a circular arc to the current path. The arc is centered at
530 and proceeds counterclockwise from
543 adds a line segment from the current point to the point most recently
554 .Fa id x1 y1 x2 y2 x3 y3
556 adds a cubic Bezier spline from the current point to
569 fills the current path and clears it.
576 fills the current path without clearing it.
583 adds a line from the current point to
591 sets the current point to
597 .Fa id x y width height
599 adds a rectangle to the current path. The top left corner is at
613 .Fa id dx1 dy1 dx2 dy2 dx3 dy3
615 adds a cubic Bezier spline from the current point to
621 as control points. All coordinates are offsets relative to the
629 adds a line from the current point to a point offset from there by
637 moves the current point by
645 removes the elements with
656 sets the dash pattern to
665 .Fa id l1on l1off l2on l2off ...
667 resets the dash pattern to a line with arbitrary on/off portions.
674 resets the dash pattern to a solid line.
681 sets the font size for subsequent calls of
689 .Brq Ic butt | round | square
691 sets the line cap style.
697 .Brq Ic miter | round | bevel
699 sets the line junction style.
715 is in the format used with
725 beginning at the current point.
732 strokes the current path and clears it.
739 strokes the current path without clearing it.
744 .Bl -tag -width "commands "
751 replaces the user-editable text with
759 once for each change of
763 .Bl -tag -width "commands "
770 replaces the expander label text with
780 the child widget, or makes it visible
785 .Ss GtkFileChooserButton
786 .Bl -tag -width "commands "
795 to the extent it exists.
802 if the selection has changed.
804 .Ss GtkFileChooserDialog
806 .Ic GtkFileChooserDialog
818 .Ic GtkFileChooserDialog
827 if the dialog is the sole window of the GUI and therefore named
832 .Ic GtkFileChooserDialog
841 if the dialog is the sole window of the GUI and therefore named
846 .Ic GtkFileChooserDialog
855 if the dialog is the sole window of the GUI and therefore named
858 .Bl -tag -width "commands "
867 to the extent it exists.
871 .Ic :set_current_name
876 the suggested filename, which may not yet exist.
878 should either resemble an absolute path, or the
899 .Bl -tag -width "commands "
915 .Bl -tag -width "commands "
922 replaces the frame label text with
928 .Bl -tag -width "commands "
932 .Ic :set_from_icon_name
935 replaces the image with one of the standard icons.
942 replaces the image by the one found at
948 .Bl -tag -width "commands "
955 replaces the label text with
960 .Ss GtkMenuItem, GtkImageMenuItem
961 .Bl -tag -width "commands "
975 .Sx GtkFileChooserDialog
978 if it exists. If there isn't any dialog attached to the
988 .Bl -tag -width "commands "
992 .Ic :set_current_page
995 switches to page number
1004 .Bl -tag -width "commands "
1011 moves the progress bar to
1022 replaces the text of the progress bar with
1024 Default is the progress percentage.
1029 .Bl -tag -width "commands "
1035 switches the button on. All other buttons of the same group will go off
1043 replaces the button text with
1058 .Bl -tag -width "commands "
1065 moves the slider to value
1071 .Fa floating_point_text
1075 .Bl -tag -width "commands "
1082 sets the selected value to
1092 .Bl -tag -width "commands "
1103 start and stop the spinner.
1108 .Bl -tag -width "commands "
1123 removes the last entry from the statusbar, revealing the penultimate
1130 empties the statusbar.
1135 .Bl -tag -width "commands "
1139 .Ic :set_active Brq Ic 0 | 1
1141 turns the switch off
1158 There should be a dedicated
1160 for sending (parts of) the text.
1170 will send the content of the
1177 will send the highlighted part the
1179 .Bl -tag -width "commands "
1186 replaces the user-editable text with
1197 .Ic :insert_at_cursor
1206 .Ic :place_cursor Brq Fa position | Ic end
1208 places the text cursor at
1210 or at the end of the text.
1214 .Ic :place_cursor_at_line
1217 places the text cursor at the beginning of
1222 .Ic :scroll_to_cursor
1224 scrolls to the cursor position if necessary.
1232 being the name of the
1238 and backslashes are replaced by
1242 .Bl -tag -width "commands "
1246 .Ic :set_active Brq Ic 0 | 1
1248 switches the button off
1258 replaces the button text with
1274 can deal with columns of type
1275 .Ic gboolean , gint , guint , glong , gulong , gint64 , guint64 , gfloat , gdouble ,
1282 refer to the underlying model (usually a
1283 .Ic GtkListStore ) .
1284 .Bl -tag -width "commands "
1291 replaces the content at
1295 (which should be compatible with the type of
1300 .Ic :insert_row Brq Fa position | Ic end
1302 inserts a new, empty row at
1304 or at the end of the list.
1309 .Fa origin Brq Fa destination | Ic end
1315 or to the end of the list.
1342 .Fa column_type row column value
1344 one message per selected row and column in the underlying model if
1345 the set of selected rows has changed.
1347 .Ss GtkTreeViewColumn
1348 .Bl -tag -width "commands "
1358 .Ss Discovering Pipeglade Interactively
1359 Suppose the interface in
1372 will be reported on the terminal. Typing
1373 .Dl label1:set_text Button Label
1374 will change the text shown on the label into
1376 .Ss One-Shot File Dialog
1377 Suppose the interface in
1378 .Pa ./simple_open.ui
1380 .Sx GtkFileChooserDialog
1387 .Dl pipeglade -u simple_open.ui
1388 will open the dialog; pressing
1390 will close it after sending the selected filename to
1392 .Ss One-Shot User Notification
1394 .Pa ./simple_dialog.ui
1399 .Dl pipeglade -u simple_dialog.ui <<< \e
1400 .Dl \ \ \ \ \&"label1:set_text NOW READ THIS!\&"
1401 will set the label text accordingly and wait for user input.
1402 .Ss Continuous Input
1403 The following shell command displays a running clock:
1405 .Dl \ \ \ \ echo \&"label1:set_text `date`\&";
1406 .Dl \ \ \ \ sleep 1;
1407 .Dl done | pipeglade -u simple_dialog.ui
1408 .Ss Continuous Input and Output
1409 The following shell script fragment sets up
1411 for continuous communication with another program,
1413 .Dl pipeglade -i in.fifo -o out.fifo &
1414 .Dl # wait for in.fifo and out.fifo to appear
1415 .Dl while test \& ! \e( -e in.fifo -a -e out.fifo \e); do :; done
1416 .Dl main_prog <out.fifo >in.fifo
1419 exits 0 on success, and >0 if an error occurs.
1431 .An Bert Burgemeister Aq trebbu@googlemail.com .