1 .\" Copyright (c) 2014-2016 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
34 .Op Fl u Ar builder-file
35 .Op Fl e Ar parent-xid
38 .Op Fl -display Ar X-server
43 is a helper program that displays graphical user
44 interfaces for other programs.
45 It renders the GUI definition found in a GtkBuilder XML file
46 (typically created using the
48 interface designer), and communicates with the main program solely
49 through plain text messages via pipes or fifos.
50 It provides access to a subset of features of a subset of widgets of
52 Simple one-shot dialogs as well as more complex, long-running programs
62 if necessary, sets its permissions to
64 and uses it for command input.
66 A command is a line of text.
68 .Qq Ar id Ns Cm \&: Ns Ar action Bq Ar data ,
70 being the name of the receiving widget;
72 is separated from the rest of the command by a single whitespace
74 Commands whose first non-whitespace character is
76 are considered comments and ignored silently, as are empty input lines.
77 Any occurences of the two-character sequences
81 will be converted into newline or carriage return, respectively.
82 Every other character following a backslash will be left unchanged,
83 but the backslash will be removed.
84 Invalid commands are reported on
86 and are otherwise ignored.
89 for applicable commands.
93 exists but is not a named pipe.
96 is deleted upon successful program termination.
98 Default command input is
103 if necessary, sets its permissions to
105 and uses it for output of feedback messages from the
106 graphical user interface.
108 A feedback message is a line of text; its format is
109 .Qq Ar id Ns Cm \&: Ns Ar info Bq Ar data ,
111 being the name of the sending widget.
114 for possible feedback messages.
118 exists but is not a named pipe.
121 is deleted upon successful program termination.
123 Default feedback-message output is
128 in the background after printing its process ID to
131 It is an error if option
138 .It Fl u Ar builder-file
139 Displays the graphical user interface
141 which should be created using the
143 user interface designer and saved in GtkBuilder (.ui) format.
144 Widget ids should be alphanumeric, including underscores, and the
145 main window must must be given the id
150 .It Fl e Ar parent-xid
151 Embeds the main window into the XEmbed socket
155 Appends for each command a line of
160 being the number of microseconds elapsed during
165 are separated by a tab character.
179 appending its output to
185 .It Fl -display Ar X-server
188 for user interaction.
190 Prints a help message and exits.
192 Prints the versions of the underlying GTK+ and cairo libraries and
200 The widget classes able to communicate through
207 .Sx GtkComboBoxText ,
213 .Sx GtkFileChooserButton ,
214 .Sx GtkFileChooserDialog ,
219 .Sx GtkMenuItem, GtkImageMenuItem ,
221 .Sx GtkPrintUnixDialog ,
225 .Sx GtkScrolledWindow
232 .Sx GtkToggleButton ,
234 .Sx GtkTreeViewColumn ,
239 references a widget by the
241 attribute it is given in Glade.
249 .Dl <object class="GtkWindow" id="foo"> .
250 .Ss Any Widget (including widgets not mentioned above)
251 .Bl -tag -width "commands "
253 .Qq Ar id Ns Cm :set_sensitive Brq Cm 0 | 1
254 makes the widget grayed out
259 .Qq Ar id Ns Cm :set_visible Brq Cm 0 | 1
262 the widget, or makes it visible
265 .Qq Ar id Ns Cm :grab_focus
266 puts the keyboard focus onto the widget, if possible.
268 .Qq Ar id Ns Cm :set_size_request Bq Ar width height
269 sets the widget's minimum size to
273 Default is the widget's natural size.
277 .Bo Ar prop Ns Cm \&: Ns Ar val Ns Bo Cm \&; Ar prop Ns Cm \&: Ns Ar val ... Bc Bc
281 of the widget style to
283 Properties not explicitly specified are reset to their default values.
285 .Bl -dash -offset indent -compact
287 .Ql label1:style font:Bold 11; background-color:green
289 .Ql label1:style font-style:italic; font-weight:bold; color:blue
291 .Ql frame1:style border-color:red yellow; border-width:5px
293 .Ql frame1:style border-radius:10px; transition:10s
295 For a description of possible color notations see
298 .Qq Ar id Ns Cm :set_tooltip_text Bq Ar text
299 sets the widget's tooltip
301 Default is disabling the tooltip.
303 .Qq Ar id Ns Cm :force
304 simulates a click on widget
306 triggering a response as described with the widgets below.
308 .Bl -dash -offset indent -compact
310 The command is ignored by
318 .Sx GtkTreeViewColumn ;
320 .Sx GtkCalendar , GtkEntry , GtkFileChooserButton , GtkScale ,
323 report the currently selected item;
328 just open their respective dialogs.
331 .Qq Ar id Ns Cm :load Ar file
338 is required but ignored.
340 commands may be nested but on attempts to read from the same file, the
351 .Qq Ar id Ns Cm :main_quit
352 kills the user interface.
355 is required but ignored.
358 .Bl -tag -width "commands "
360 .Qq Ar id Ns Cm :set_label Ar string
361 replaces the button text with
364 .Qq Ar id Ns Cm \&:clicked
368 .Cm _ok , _apply , _cancel , _send_text ,
371 may work differently; see
372 .Sx GtkDialog , GtkFileChooserDialog ,
378 .Bl -tag -width "commands "
380 .Qq Ar id Ns Cm :select_date Ar yyyy Ns Cm - Ns Ar mm Ns Cm - Ns Ar dd
381 selects the date on the calendar.
383 .Qq Ar id Ns Cm :mark_day Ar day
388 .Qq Ar id Ns Cm :clear_marks
389 unmarks all days on the calendar.
391 .Qq Ar id Ns Cm \&:clicked Ar yyyy Ns Cm - Ns Ar mm Ns Cm - Ns Ar dd
393 .Qq Ar id Ns Cm \&:doubleclicked Ar yyyy Ns Cm - Ns Ar mm Ns Cm - Ns Ar dd
396 .Bl -tag -width "commands "
398 .Qq Ar id Ns Cm :set_active Brq Cm 0 | 1
399 switches the check mark off
404 .Qq Ar id Ns Cm :set_label Ar string
405 replaces the button text with
414 .Bl -tag -width "commands "
416 .Qq Ar id Ns Cm :set_color Ar color
417 preselects the color.
420 .Bl -dash -offset indent -compact
422 a standard X11 color name, like
425 a hexadecimal value in the form
426 .Cm # Ns Ar rgb , Cm # Ns Ar rrggbb , Cm # Ns Ar rrrgggbbb ,
428 .Cm # Ns Ar rrrrggggbbbb ,
430 an RGB color in the form
431 .Cm rgb( Ns Ar red Ns Cm \&, Ns Ar green Ns Cm \&, Ns Ar blue Ns Cm \&) ,
434 an RGBA color in the form
435 .Cm rgba( Ns Ar red Ns Cm \&, Ns Ar green Ns Cm \&, Ns
436 .Ar blue Ns Cm \&, Ns Ar alpha Ns Cm \&) .
439 .Qq Ar id Ns Cm \&:color Cm rgb( Ns Ar red Ns Cm \&, Ns Ar green Ns Cm \&, Ns Ar blue Ns Cm \&)
441 .Qq Ar id Ns Cm \&:color Cm rgba( Ns Ar red Ns Cm \&, Ns Ar green Ns Cm \&, Ns Ar blue Ns Cm \&, Ns Ar alpha Ns Cm \&) .
445 lie between 0 and 255, and
454 .Bl -tag -width "commands "
456 .Qq Ar id Ns Cm :prepend_text Ar string
458 .Qq Ar id Ns Cm :append_text Ar string
459 prepend/append a new selectable item marked
462 .Qq Ar id Ns Cm :insert_text Ar position string
468 .Qq Ar id Ns Cm :remove Ar position
472 .Qq Ar entry_id Ns Cm \&:text Ar text ,
474 being the id of the child
487 .Ar foo Ns Cm _invoke .
495 .Ar foo Ns Cm _cancel
497 if the dialog is the sole window of the GUI and therefore named
508 it will take care of hiding the dialog window.
509 .Bl -tag -width "commands "
511 .Qq Ar id Ns Cm :set_title Ar string
512 replaces the text in the title bar with
515 .Qq Ar id Ns Cm :resize Bq Ar width height
516 changes the size of the dialog window to
520 pixels if specified, or to the default size.
522 .Qq Ar id Ns Cm :move Ar x y
523 moves the dialog window to position
526 .Qq Ar id Ns Cm :fullscreen
528 .Qq Ar id Ns Cm :unfullscreen
529 switch fullscreen mode on and off.
531 .Qq Ar id Ns Cm \&:closed
534 window was closed by the window manager.
539 expect a context parameter of the form
540 .Bro Ar n Ns | Ns Cm = Ns Ar n Ns | Ns Ar n Ns Cm < Ns Ar m Brc
543 is an arbitrary non-negative integer that can be used later to
544 reference the command.
547 appends its command to the current list of drawing operations.
550 replaces the first drawing operation with context parameter
554 .Ar n Ns Cm < Ns Ar m ,
555 inserts its command before the first drawing operation with context
558 Both second and third form fall back to appending.
560 The default coordinate system is a left-handed system with its origin
561 in the upper-left corner.
562 Angles increase from the positive X axis towards the positve Y axis
563 .Pq clockwise in the default system .
564 .Bl -tag -width "commands "
566 .Qq Ar id Ns Cm :arc Bro Ar n Ns | Ns Cm = Ns Ar n Ns | Ns Ar n Ns Cm < Ns Ar m Brc x y radius angle1 angle2
567 adds a circular arc to the current path.
568 The arc is centered at
576 .Qq Ar id Ns Cm :arc_negative Bro Ar n Ns | Ns Cm = Ns Ar n Ns | Ns Ar n Ns Cm < Ns Ar m Brc x y radius angle1 angle2
577 adds a circular arc to the current path.
578 The arc is centered at
580 and proceeds in the direction of decreasing angles from
586 .Qq Ar id Ns Cm :close_path Bro Ar n Ns | Ns Cm = Ns Ar n Ns | Ns Ar n Ns Cm < Ns Ar m Brc
587 adds a line segment from the current point to the point most recently
589 .Ar id Ns Cm :move_to
591 .Ar id Ns Cm :rel_move_to .
593 .Qq Ar id Ns Cm :curve_to Bro Ar n Ns | Ns Cm = Ns Ar n Ns | Ns Ar n Ns Cm < Ns Ar m Brc x1 y1 x2 y2 x3 y3
594 adds a cubic Bezier spline from the current point to
601 If there is no current point, the curve will start at
604 .Qq Ar id Ns Cm :fill Bro Ar n Ns | Ns Cm = Ns Ar n Ns | Ns Ar n Ns Cm < Ns Ar m Brc
605 fills the current path and clears it.
607 .Qq Ar id Ns Cm :fill_preserve Bro Ar n Ns | Ns Cm = Ns Ar n Ns | Ns Ar n Ns Cm < Ns Ar m Brc
608 fills the current path without clearing it.
610 .Qq Ar id Ns Cm :line_to Bro Ar n Ns | Ns Cm = Ns Ar n Ns | Ns Ar n Ns Cm < Ns Ar m Brc x y
611 adds a line from the current point to
613 or creates a new current point at
616 .Qq Ar id Ns Cm :move_to Bro Ar n Ns | Ns Cm = Ns Ar n Ns | Ns Ar n Ns Cm < Ns Ar m Brc x y
617 sets the current point to
620 .Qq Ar id Ns Cm :rectangle Bro Ar n Ns | Ns Cm = Ns Ar n Ns | Ns Ar n Ns Cm < Ns Ar m Brc x y width height
621 adds a rectangle to the current path.
622 The top left corner is at
625 .Qq Ar id Ns Cm :rel_curve_to Bro Ar n Ns | Ns Cm = Ns Ar n Ns | Ns Ar n Ns Cm < Ns Ar m Brc dx1 dy1 dx2 dy2 dx3 dy3
626 adds a cubic Bezier spline from the current point to
633 All coordinates are offsets relative to the current point.
635 .Qq Ar id Ns Cm :rel_line_to Bro Ar n Ns | Ns Cm = Ns Ar n Ns | Ns Ar n Ns Cm < Ns Ar m Brc dx dy
636 adds a line from the current point to a point offset from there by
639 .Qo Ar id Ns Cm :rel_move_for Bro Ar n Ns | Ns Cm = Ns Ar n Ns | Ns Ar n Ns Cm < Ns Ar m Brc
640 .Brq Cm c Ns | Ns Cm e Ns | Ns Cm n Ns | Ns Cm ne Ns | Ns Cm nw Ns | Ns Cm s Ns | Ns Cm se Ns | Ns Cm sw Ns | Ns Cm w
643 moves the current point such that
644 .Qq Ar id Ns Cm :show_text Ar n text
645 will place the specified reference point of
647 on the original current point.
649 .Qq Ar id Ns Cm :rel_move_to Bro Ar n Ns | Ns Cm = Ns Ar n Ns | Ns Ar n Ns Cm < Ns Ar m Brc dx dy
650 moves the current point by
653 .Qq Ar id Ns Cm :remove Ar n
654 removes the elements with context parameter
657 .Cm GtkDrawingArea Ar id .
659 .Qq Ar id Ns Cm :rotate Bro Ar n Ns | Ns Cm = Ns Ar n Ns | Ns Ar n Ns Cm < Ns Ar m Brc Ar angle
660 rotates the user space axes by
664 .Qq Ar id Ns Cm :save Ar file Ns Brq Cm .ps Ns | Ns Cm .eps Ns | Ns Cm .epsf Ns | Ns Cm .pdf Ns | Ns Cm .svg
665 writes the content of the
667 to an image file of the specified type.
669 .Qq Ar id Ns Cm :scale Bro Ar n Ns | Ns Cm = Ns Ar n Ns | Ns Ar n Ns Cm < Ns Ar m Brc Ar sx sy
670 scales the user space axes by
673 .Qq Ar id Ns Cm :set_dash Bro Ar n Ns | Ns Cm = Ns Ar n Ns | Ns Ar n Ns Cm < Ns Ar m Brc l
674 sets the dash pattern to
680 .Qq Ar id Ns Cm :set_dash Bro Ar n Ns | Ns Cm = Ns Ar n Ns | Ns Ar n Ns Cm < Ns Ar m Brc l1on l1off l2on l2off ...
681 resets the dash pattern to a line with arbitrary on/off portions.
683 .Qq Ar id Ns Cm :set_dash Bro Ar n Ns | Ns Cm = Ns Ar n Ns | Ns Ar n Ns Cm < Ns Ar m Brc
684 resets the dash pattern to a solid line.
686 .Qo Ar id Ns Cm :set_font_face Bro Ar n Ns | Ns Cm = Ns Ar n Ns | Ns Ar n Ns Cm < Ns Ar m Brc
687 .Brq Cm normal | italic | oblique
688 .Brq Cm normal | bold
691 sets the font face for subsequent calls of
692 .Ar id Ns Cm :show_text .
694 .Qq Ar id Ns Cm :set_font_size Bro Ar n Ns | Ns Cm = Ns Ar n Ns | Ns Ar n Ns Cm < Ns Ar m Brc size
695 sets the font size for subsequent calls of
696 .Ar id Ns Cm :show_text .
698 .Qq Ar id Ns Cm :set_line_cap Bro Ar n Ns | Ns Cm = Ns Ar n Ns | Ns Ar n Ns Cm < Ns Ar m Brc Brq Cm butt | round | square
699 sets the line cap style.
703 .Qq Ar id Ns Cm :set_line_join Bro Ar n Ns | Ns Cm = Ns Ar n Ns | Ns Ar n Ns Cm < Ns Ar m Brc Brq Cm miter | round | bevel
704 sets the line junction style.
708 .Qq Ar id Ns Cm :set_line_width Bro Ar n Ns | Ns Cm = Ns Ar n Ns | Ns Ar n Ns Cm < Ns Ar m Brc width
714 .Qq Ar id Ns Cm :set_source_rgba Bro Ar n Ns | Ns Cm = Ns Ar n Ns | Ns Ar n Ns Cm < Ns Ar m Brc color
717 is in the format used with
720 .Qq Ar id Ns Cm :show_text Bro Ar n Ns | Ns Cm = Ns Ar n Ns | Ns Ar n Ns Cm < Ns Ar m Brc text
723 beginning at the current point.
725 .Qq Ar id Ns Cm :stroke Bro Ar n Ns | Ns Cm = Ns Ar n Ns | Ns Ar n Ns Cm < Ns Ar m Brc
726 strokes the current path and clears it.
728 .Qq Ar id Ns Cm :stroke_preserve Bro Ar n Ns | Ns Cm = Ns Ar n Ns | Ns Ar n Ns Cm < Ns Ar m Brc
729 strokes the current path without clearing it.
731 .Qq Ar id Ns Cm :transform Bro Ar n Ns | Ns Cm = Ns Ar n Ns | Ns Ar n Ns Cm < Ns Ar m Brc Bq Ar xx yx xy yy x0 y0
732 modifies the current transformation matrix such that
734 .Dl Va x' Li = Ar xx Va x Li + Ar xy Va y Li + Ar x0 ,
735 .Dl Va y' Li = Ar yx Va y Li + Ar yy Va y Li + Ar y0 .
737 Default is resetting the current transformation matrix.
739 .Qq Ar id Ns Cm :translate Bro Ar n Ns | Ns Cm = Ns Ar n Ns | Ns Ar n Ns Cm < Ns Ar m Brc Ar tx ty
740 translates the user space origin by
746 .Bl -tag -width "commands "
748 .Qq Ar id Ns Cm :set_text Ar string
749 replaces the user-editable text with
752 .Qq Ar id Ns Cm :set_placeholder_text Ar string
755 that is displayed when the entry is empty and unfocused.
757 .Qq Ar id Ns Cm \&:text Ar text ,
758 once for each change of
763 are mouse pointer coordinates relative to the
765 .Bl -tag -width "commands "
769 .Qq Ar id Ns Cm \&:button_press Ar b x y ,
770 .Qq Ar id Ns Cm \&:button_release Ar b x y
773 is the mouse button (normally 1, 2, or 3 for the left, middle, and
774 right button; others may exist).
776 .Qq Ar id Ns Cm \&:motion Ar x y
777 is reported repeatedly while the mouse is being moved with a button
780 .Qq Ar id Ns Cm \&:key_press Ar key ,
790 .Bl -tag -width "commands "
792 .Qq Ar id Ns Cm :set_label Ar string
793 replaces the expander label text with
796 .Qq Ar id Ns Cm :set_expanded Brq Cm 0 | 1
799 the child widget, or makes it visible
804 .Ss GtkFileChooserButton
805 .Bl -tag -width "commands "
807 .Qq Ar id Ns Cm :set_filename Ar path
810 to the extent it exists.
812 .Qq Ar id Ns Cm \&:file Ar pathname
813 if the selection has changed.
815 .Ss GtkFileChooserDialog
817 .Cm GtkFileChooserDialog
825 .Ar foo Ns Cm _invoke .
828 .Cm GtkFileChooserDialog
835 if the dialog is the sole window of the GUI and therefore named
840 .Cm GtkFileChooserDialog
845 .Ar foo Ns Cm _cancel
847 if the dialog is the sole window of the GUI and therefore named
852 .Cm GtkFileChooserDialog
859 if the dialog is the sole window of the GUI and therefore named
862 .Bl -tag -width "commands "
864 .Qq Ar id Ns Cm :set_filename Ar path
867 to the extent it exists.
869 .Qq Ar id Ns Cm :set_current_name Ar string
872 the suggested filename, which may not yet exist.
874 should either resemble an absolute path, or the
876 must be set separately by
877 .Ar id Ns Cm :set_filename Ar directory .
879 .Qq Ar id Ns Cm :set_title Ar string
880 replaces the text in the title bar with
883 .Qq Ar id Ns Cm :resize Bq Ar width height
884 changes the size of the dialog window to
888 pixels if specified, or to the default size.
890 .Qq Ar id Ns Cm :move Ar x y
891 moves the dialog window to position
894 .Qq Ar id Ns Cm :fullscreen
896 .Qq Ar id Ns Cm :unfullscreen
897 switch fullscreen mode on and off.
899 .Qq Ar id Ns Cm :file Ar pathname
901 .Qq Ar id Ns Cm :folder Ar pathname
903 .Qq Ar id Ns Cm \&:closed
905 .Cm GtkFileChooserDialog
906 window was closed by the window manager.
909 .Bl -tag -width "commands "
911 .Qq Ar id Ns Cm :set_font_name Ar fontname
914 .Qq Ar id Ns Cm \&:font Ar fontname
917 .Bl -tag -width "commands "
919 .Qq Ar id Ns Cm :set_label Ar text
920 replaces the frame label text with
926 .Bl -tag -width "commands "
928 .Qq Ar id Ns Cm :set_from_icon_name Ar icon-name
929 replaces the image with one of the standard icons.
931 .Qq Ar id Ns Cm :set_from_file Ar path
932 replaces the image by the one found at
938 .Bl -tag -width "commands "
940 .Qq Ar id Ns Cm :set_text Ar string
941 replaces the label text with
946 .Ss GtkMenuItem, GtkImageMenuItem
947 .Bl -tag -width "commands "
956 .Ar foo Ns Cm _invoke
960 .Sx GtkFileChooserDialog
964 If there isn't any dialog attached to the
967 .Qq Ar id Ns Cm \&:active Ar label .
970 .Bl -tag -width "commands "
972 .Qq Ar id Ns Cm :set_current_page Ar n
973 switches to zero-based page number
978 .Ss GtkPrintUnixDialog
979 .Bl -tag -width "commands "
981 .Qq Ar id Ns Cm :print Ar file.ps
982 opens the print dialog.
987 to the printer the user selected in the dialog.
989 .Qq Ar id Ns Cm \&:closed
991 .Cm GtkPrintUnixDialog
992 window was closed by the window manager.
995 .Bl -tag -width "commands "
997 .Qq Ar id Ns Cm :set_fraction Ar x
998 moves the progress bar to
1000 .Pq between 0 and 1 .
1002 .Qq Ar id Ns Cm :set_text Bq Ar string
1003 replaces the text of the progress bar with
1005 Default is the progress percentage.
1010 .Bl -tag -width "commands "
1012 .Qq Ar id Ns Cm :set_active 1
1013 switches the button on.
1014 All other buttons of the same group will go off automatically.
1016 .Qq Ar id Ns Cm :set_label Ar string
1017 replaces the button text with
1020 .Qq Ar id Ns Cm \&:1
1022 .Qq Ar id Ns Cm \&:0
1026 .Bl -tag -width "commands "
1028 .Qq Ar id Ns Cm :set_value Ar x
1029 moves the slider to value
1032 .Qq Ar id Ns Cm :set_fill_level Bq Ar x
1033 moves the fill level indicator to value
1035 Default is hiding the fill level indicator.
1037 .Qq Ar id Ns Cm :set_range Ar min max
1040 .Qq Ar id Ns Cm :set_increments Ar step page
1041 sets the steps the slider moves while pressing arrow keys and
1043 .Pf / Ql Page_Down ,
1046 .Qq Ar id Ns Cm \&:value Ar number
1048 .Ss GtkScrolledWindow
1049 .Bl -tag -width "commands "
1051 .Qq Ar id Ns Cm :hscroll Ar position
1053 .Qq Ar id Ns Cm :vscroll Ar position
1056 to the left or top edge of the
1057 .Cm GtkScrolledWindow ,
1060 .Qq Ar id Ns Cm :hscroll_to_range Ar pos0 pos1
1062 .Qq Ar id Ns Cm :vscroll_to_range Ar pos0 pos1
1063 scroll, if necessary, the range between
1068 .Cm GtkScrolledWindow .
1069 If the range is greater than the window, the initial part of the range
1076 may be unsupported by Glade, but its definition can be inserted
1077 manually into the GtkBuilder
1080 .Bd -literal -offset indent
1082 <object class="GtkSocket" id="socket1">
1083 <property name="visible">True</property>
1084 <property name="can_focus">True</property>
1087 <property name="expand">True</property>
1088 <property name="fill">True</property>
1089 <property name="position">1</property>
1093 .Bl -tag -width "commands "
1096 requests a feedback message containing the socket
1099 .Qq Ar id Ns Cm :id Ar xid
1100 can be used by another process to XEmbed its widgets into the
1103 .Qq Ar id Ns Cm :plug-added ,
1108 Notification that the other process has inserted its widgets into or
1109 removed them from the
1113 .Bl -tag -width "commands "
1115 .Qq Ar id Ns Cm :set_text Ar string
1116 sets the selected value to
1119 .Qq Ar id Ns Cm :set_range Ar min max
1122 .Qq Ar id Ns Cm :set_increments Ar step page
1123 sets the steps the value changes while pressing arrow keys/left mouse
1126 .Pf / Ql Page_Down Ns
1127 /middle mouse button,
1130 .Qq Ar id Ns Cm \&:text Ar text
1133 .Bl -tag -width "commands "
1135 .Qq Ar id Ns Cm :start
1137 .Qq Ar id Ns Cm :stop
1138 start and stop the spinner.
1143 The context parameter
1145 is an arbitrary non-whitespace string.
1146 .Bl -tag -width "commands "
1148 .Qq Ar id Ns Cm :push_id Ar c string ,
1149 .Qq Ar id Ns Cm :push Ar string
1152 with context parameter
1156 respectively, and display it in the statusbar.
1158 .Qq Ar id Ns Cm :pop_id Ar c ,
1159 .Qq Ar id Ns Cm :pop
1160 remove the latest entry associated with context parameter
1164 respectively, from the statusbar.
1166 .Qq Ar id Ns Cm :remove_all_id Ar c ,
1167 .Qq Ar id Ns Cm :remove_all
1168 remove the entries associated with context parameter
1172 respectively, from the statusbar.
1177 .Bl -tag -width "commands "
1179 .Qq Ar id Ns Cm :set_active Brq Cm 0 | 1
1180 turns the switch off
1185 .Qq Ar id Ns Cm \&:1
1187 .Qq Ar id Ns Cm \&:0
1191 There should be a dedicated
1193 for sending (parts of) the text.
1201 .Ar foo Ns Cm _send_text
1202 will send the content of the
1207 .Ar foo Ns Cm _send_selection
1208 will send the highlighted part the
1210 .Bl -tag -width "commands "
1212 .Qq Ar id Ns Cm :set_text Ar string
1213 replaces the user-editable text with (potentially empty)
1216 .Qq Ar id Ns Cm :delete
1219 .Qq Ar id Ns Cm :insert_at_cursor Ar string
1224 .Qq Ar id Ns Cm :place_cursor Brq Ar position | Cm end
1225 places the text cursor at
1227 or at the end of the text.
1229 .Qq Ar id Ns Cm :place_cursor_at_line Ar line
1230 places the text cursor at the beginning of
1233 .Qq Ar id Ns Cm :scroll_to_cursor
1234 scrolls to the cursor position if necessary.
1236 .Qq Ar id Ns Cm :save Ar file
1241 command containing the text.
1243 .Qq Ar button_id Ns Cm :text Ar text ,
1251 and backslashes are replaced by
1255 .Bl -tag -width "commands "
1257 .Qq Ar id Ns Cm :set_active Brq Cm 0 | 1
1258 switches the button off
1263 .Qq Ar id Ns Cm :set_label Ar string
1264 replaces the button text with
1267 .Qq Ar id Ns Cm \&:1
1269 .Qq Ar id Ns Cm \&:0
1274 can deal with columns of type
1275 .Cm gboolean , gint , guint , glong , gulong , gint64 , guint64 , gfloat , gdouble ,
1282 refer to the underlying model
1285 .Cm GtkTreeStore ) .
1287 is a sequence of one or more colon-separated integers, e.g.
1291 .Bl -tag -width "commands "
1293 .Qq Ar id Ns Cm :set Ar row column data
1294 replaces the content at
1298 (which should be compatible with the type of
1300 If necessary, new tree nodes are created to obtain the minimal tree
1301 structure needed to support
1304 .Qq Ar id Ns Cm :insert_row Brq Ar row Bo Cm as_child Bc | Cm end
1305 inserts a new, empty row; either as a sibling of
1311 or at the end of the list, respectively.
1313 .Qq Ar id Ns Cm :move_row Ar origin Brq Ar destination | Cm end
1316 within its current level to
1320 .Qq Ar id Ns Cm :remove_row Ar row
1321 removes the row at position
1324 .Qq Ar id Ns Cm :clear
1327 .Qq Ar id Ns Cm :expand Ar row
1328 expands one level of the subtree below
1331 .Qq Ar id Ns Cm :expand_all Bq Ar row
1332 expands the subtree below
1336 .Qq Ar id Ns Cm :collapse Bq Ar row
1337 collapses the subtree below
1341 .Qq Ar id Ns Cm :set_cursor Bq Ar row
1346 .Qq Ar id Ns Cm :scroll Ar row column
1351 .Qq Ar id Ns Cm :save Ar file
1352 stores the content of the underlying model as a sequence of
1357 .Qq Ar id Ns Cm \&:clicked
1359 .Qq Ar id Ns Cm \&: Ns Ar column_type row column value ,
1360 one message per cell in the underlying model for each selected row; or
1362 .Qq Ar id Ns Cm \&: Ns Ar column_type row column new_value ,
1367 .Ss GtkTreeViewColumn
1368 .Bl -tag -width "commands "
1372 .Qq Ar id Ns Cm \&:clicked
1375 .Bl -tag -width "commands "
1377 .Qq Ar id Ns Cm :set_title Ar string
1378 replaces the text in the title bar with
1381 .Qq Ar id Ns Cm :resize Bq Ar width height
1382 changes the window size to
1386 pixels if specified, or to the default size.
1388 .Qq Ar id Ns Cm :move Ar x y
1389 moves the window to position
1392 .Qq Ar id Ns Cm :fullscreen
1394 .Qq Ar id Ns Cm :unfullscreen
1395 switch fullscreen mode on and off.
1397 .Qq Ar id Ns Cm \&:closed
1400 was closed by the window manager.
1405 .Ss Discovering Pipeglade Interactively
1406 Suppose the interface in
1409 .Sx GtkLabel Ql label1
1411 .Sx GtkButton Ql button1 .
1417 .Sx GtkButton , Ql button1:clicked
1418 will be reported on the terminal.
1421 .Dl label1:set_text The Button
1423 will change the text shown on the label into
1425 .Ss One-Shot File Dialog
1426 Suppose the interface in
1427 .Pa ./simple_open.ui
1429 .Sx GtkFileChooserDialog
1437 .Dl pipeglade -u simple_open.ui
1439 will open the dialog; pressing
1441 will close it after sending the selected filename to
1443 .Ss One-Shot User Notification
1445 .Pa ./simple_dialog.ui
1447 .Sx GtkLabel Ql label1 ,
1449 .Bd -literal -offset indent
1450 pipeglade -u simple_dialog.ui <<< \e
1451 "label1:set_text NOW READ THIS!"
1453 will set the label text accordingly and wait for user input.
1454 .Ss Continuous Input
1455 The following shell command displays a running clock:
1456 .Bd -literal -offset indent
1458 echo "label1:set_text `date`";
1460 done | pipeglade -u simple_dialog.ui
1462 .Ss Continuous Input and Output
1463 The following shell script fragment sets up
1465 for continuous communication with another program,
1467 .Bd -literal -offset indent
1468 pipeglade -i in.fifo -o out.fifo -b
1469 main_prog <out.fifo >in.fifo
1482 .An Bert Burgemeister
1483 .Aq Mt trebbu@googlemail.com .
1485 Due to what appears to be a bug in cairo v1.14.0,
1487 used with this library version occasionally crashes on