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 input. It is an error if
60 exists but is not a named pipe. The named pipe
62 is deleted upon successful program termination. Default is
65 .Sx GUI MANIPULATION COMMANDS
66 for a list of commands understood by pipeglade.
70 if necessary, and uses it for output. It is an error if
72 exists but is not a named pipe. The named pipe
74 is deleted upon successful program termination. Default is
77 .Sx GUI FEEDBACK MESSAGES
78 for a description of possible output.
79 .It Fl u Ar builder-file
80 Displays the graphical user interface described in
85 Prints the GTK+ version and exits.
91 .Sh INTERFACE CREATION (USING GLADE)
92 The interface should be created using the
94 user interface designer and saved in GtkBuilder (.ui) format. The
95 main window must be named
99 signal should be connected to
101 Certain signals of the other widgets should be connected to
103 .Sx GUI FEEDBACK MESSAGES
104 for callback names and which signals of which widgets to connect to
106 .Sh GUI MANIPULATION COMMANDS
107 A command is a line of text. Lines whose first non-whitespace
110 are considered comments and ignored.
111 Any occurences of the two-character sequences
115 will be converted into newline or carriage return, respectively.
116 Every other character following a backslash will be left unchanged,
117 but the backslash will be removed.
118 The format of the commands is
127 is the name of the receiving widget.
129 is separated from the rest of the command by whitespace.
131 Invalid commands are reported on
133 and are otherwise ignored.
135 Widgets that can be manipulated programmatically, and the relevant
136 commands, are given below.
143 replaces the label text with
148 .Ic :set_from_icon_name
151 replaces the image with one of the standard icons.
158 replaces the image by the one found at
166 replaces the user-editable text with
174 replaces the user-editable text with
185 .Ic :insert_at_cursor
194 .Ic :place_cursor Brq Fa position | Ic end
196 places the text cursor at
198 or at the end of the text.
202 .Ic :place_cursor_at_line
205 places the text cursor at the beginning of
210 .Ic :scroll_to_cursor
212 scrolls to the cursor position if necessary.
219 replaces the button text with
224 .Ic :set_active Brq Ic 0 | 1
226 switches the button off
236 replaces the button text with
241 .Ic :set_active Brq Ic 0 | 1
243 switches the check mark off
253 replaces the button text with
260 switches the button on. All other buttons of the same group will go off
268 replaces the button text with
276 sets the selected value to
284 moves the slider to value
292 moves the progress bar to
303 replaces the text of the progress bar with
315 start and stop the spinner.
330 removes the last entry from the statusbar, revealing the penultimate
346 as a new selectable item.
369 refer to the underlying model (usually a
377 replaces the content at
381 (which should be compatible with the type of
386 .Ic :insert_row Brq Fa position | Ic end
388 inserts a new, empty row at
390 or at the end of the list.
395 .Fa origin Brq Fa destination | Ic end
401 or to the end of the list.
425 preselects the color.
428 .Bl -dash -offset indent -compact
430 a standard X11 color name, like
431 .Qq Li Dark Sea Green,
433 a hexadecimal value in the form
444 an RGB color in the form
454 an RGBA color in the form
465 The last two are in the format the widget reports; see
466 .Sx GUI FEEDBACK MESSAGES .
474 .Ss GtkFileChooserButton
482 to the extent it exists.
483 .Ss GtkFileChooserDialog
491 to the extent it exists.
495 .Ic :set_current_name
500 the suggested filename, which may not yet exist.
502 should either resemble an absolute path, or the
507 .Ic :set_current_name
534 unmarks all days on the calendar.
540 kills the user interface. A non-empty
542 is required but ignored.
549 makes the widget grayed out
561 the widget, or makes it visible
568 initiates the standard callback. The
573 had been activated, but with a different
581 The command doesn't change anything on the GUI.
582 .Sh GUI FEEDBACK MESSAGES
583 A message from the graphical user interface is a line of text. The
590 Message sending is initiated by callbacks. Callbacks are connected to
591 certain signals; this has to be done in
593 as part of the interface design.
595 provides the following callbacks:
596 .Bl -dash -offset indent -compact
598 .Ic cb_0 , cb_1 , cb_2 ,
601 are callbacks for use in various widgets. Their action depends on the
602 particular widget they are called from. The callbacks are identical
605 strings they send; the respective messages look like
629 is a callback that hides the window the originator is in. Its main
630 purpose is hiding of dialog windows. It doesn't report anything.
632 .Ic cb_send_dialog_selection
633 is a callback that sends the item the user has selected in a dialog.
648 is a callback that sends the content of the GtkTextBuffer that is
649 passed as user data. It reports
659 and backslashes are replaced by
662 .Ic cb_send_text_selection
663 is a callback that sends the highlighted part of the GtkTextBuffer
664 that is passed as user data. It reports
674 and backslashes are replaced by
678 The widgets capable of reporting user activity are:
680 There should be a dedicated
682 for sending (parts of) the text.
687 should be connected to either
690 .Ic cb_send_text_selection ,
706 being the name of the
711 signal should be connected to one of
712 .Ic cb_0 , cb_1 , cb_2 ,
722 .Ss GtkToggleButton, GtkCheckButton, GtkRadioButton
725 signal should be connected to one of
726 .Ic cb_0 , cb_1 , cb_2 ,
743 .Ss GtkEntry, GtkComboBoxText, GtkSpinButton
746 signal should be connected to one of
747 .Ic cb_0 , cb_1 , cb_2 ,
759 signal should be connected to one of
760 .Ic cb_0 , cb_1 , cb_2 ,
767 .Fa section floating_point_text
772 signal in the subordinated
774 should be connected to one of
775 .Ic cb_0 , cb_1 , cb_2 ,
783 and, if the set of selected rows has changed,
787 .Fa section row column value
789 one message per row and column in the underlying model.
791 can deal with columns of type
792 .Ic gboolean , gint , guint , glong , gulong , gint64 , guint64 , gfloat , gdouble ,
795 .Ss GtkTreeViewColumn
798 signal should be connected to one of
799 .Ic cb_0 , cb_1 , cb_2 ,
809 .Ss GtkFileChooserDialog (when subordinated to another window)
812 signal should be connected to
815 .Ic GtkFileChooserDialog
828 .Ic GtkFileChooserDialog
830 .Sx GtkMenuItem, GtkImageMenuItem
831 for their setup). The
832 .Ic GtkFileChooserDialog
838 signal connected to both
839 .Ic cb_send_dialog_selection
841 .Ic cb_hide_toplevel .
848 .Ic cb_hide_toplevel .
861 .Ss GtkFileChooserDialog (as the sole window)
866 signal should be connected to
869 .Ic GtkFileChooserDialog
875 signal connected to both
876 .Ic cb_send_dialog_selection
898 .Ss GtkDialog (when subordinated to another window)
901 signal should be connected to
919 .Sx GtkMenuItem, GtkImageMenuItem
920 for their setup). The
928 .Ic cb_hide_toplevel .
929 .Ss GtkDialog (as the sole window)
934 signal should be connected to
945 .Ss GtkFileChooserButton
948 signal should be connected to one of
949 .Ic cb_0 , cb_1 , cb_2 ,
958 if the user has changed the selection.
962 signal should be connected to one of
963 .Ic cb_0 , cb_1 , cb_2 ,
997 lie between 0 and 255, and
1003 signal should be connected to one of
1004 .Ic cb_0 , cb_1 , cb_2 ,
1011 .Fa section fontname
1013 .Ss GtkMenuItem, GtkImageMenuItem
1016 signal should be connected to one of
1017 .Ic cb_0 , cb_1 , cb_2 ,
1023 .Ic GtkImageMenuItem
1029 .Ic GtkFileChooserDialog
1033 if it exists. If there isn't any dialog attached to the
1045 .Ic day-selected-doubleclick
1046 signals should be connected to one or two of
1047 .Ic cb_0 , cb_1 , cb_2 ,
1061 .Ss Discovering Pipeglade Interactively
1062 Suppose the interface in
1072 signal is connected to
1079 will be reported on the terminal. Typing
1080 .Dl l1:set_text Button Label
1081 will change the text shown on the label into
1083 .Ss One-Shot File Dialog
1084 Suppose the interface in
1085 .Pa ./simple_open.ui
1087 .Ic GtkFileChooserDialog
1093 signal is connected to both
1094 .Ic cb_send_dialog_selection
1098 .Dl pipeglade -u simple_open.ui
1099 will open the dialog; pressing
1101 will close it after sending the selected filename to
1103 .Ss One-Shot User Notification
1105 .Pa ./simple_dialog.ui
1110 .Dl pipeglade -u simple_dialog.ui <<< \e
1111 .Dl \ \ \ \ \&"label1:set_text NOW READ THIS!\&"
1112 will set the label text accordingly and wait for user input.
1113 .Ss Continuous Input
1114 The following shell command displays a running clock:
1116 .Dl \ \ \ \ echo \&"label1:set_text `date`\&";
1117 .Dl \ \ \ \ sleep 1;
1118 .Dl done | pipeglade -u simple_dialog.ui
1119 .Ss Continuous Input and Output
1120 The following shell script fragment sets up
1122 for continuous communication with another program,
1124 .Dl pipeglade -i in.fifo -o out.fifo &
1125 .Dl # wait for in.fifo and out.fifo to appear
1126 .Dl while test \& ! \e( -e in.fifo -a -e out.fifo \e); do :; done
1127 .Dl main_prog <in.fifo >out.fifo
1130 exits 0 on success, and >0 if an error occurs.
1142 .An Bert Burgemeister Aq trebbu@googlemail.com .