| blob | 059b73fb5b5858ade0f2de0a80d513346f51f5fa |
1 .\" Copyright (c) 2014-2016 Bert Burgemeister <trebbu@googlemail.com>
2 .\"
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:
10 .\"
11 .\" The above copyright notice and this permission notice shall be
12 .\" included in all copies or substantial portions of the Software.
13 .\"
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.
21 .\"
22 .Dd March 27, 2016
23 .Dt PIPEGLADE 1 CON
24 .Os BSD
25 .Sh NAME
26 .Nm pipeglade
27 .Nd Pipe-Driven GTK+ Interface
28 .Sh SYNOPSIS
29 .Nm
30 .Op Fl h
31 .Op Fl G
32 .Op Fl V
33 .Nm
34 .Op Fl i Ar in-fifo
35 .Op Fl o Ar out-fifo
36 .Op Fl u Ar builder-file
37 .Op Fl -display Ar X-server
38 .Sh DESCRIPTION
39 .Nm
40 is a helper program that displays graphical user
41 interfaces for other programs. It renders the GUI definition
42 found in a GtkBuilder XML file (typically created using the
43 .Xr glade 1
44 interface designer), and communicates with the main program solely
45 through plain text messages via pipes or fifos. It provides access to
46 a subset of features of a subset of widgets of GTK+ 3. Simple
47 one-shot dialogs as well as more complex, long-running programs can be
48 built using
49 .Nm ;
50 see
51 .Sx EXAMPLES .
52 .Sh OPTIONS
53 .Bl -tag -width Ds
54 .It Fl h
55 Prints a help message and exits.
56 .It Fl e Ar parent-xid
57 Embeds the main window into the XEmbed socket
58 .Ar parent-xid
59 of another process.
60 .It Fl i Ar in-fifo
61 Creates a named pipe
62 .Ar in-fifo
63 if necessary, and uses it for command input.
64 .Pp
65 A command is a line of text. Its format is
66 .Qq Fa name Ns Ic \&: Ns Fa action Bq Fa data
67 where
68 .Fa name
69 is the name of the receiving widget;
70 .Fa data
71 is separated from the rest of the command by a single whitespace
72 character. Commands whose first non-whitespace character is
73 .Ic #
74 are considered comments and ignored silently, as are empty input lines.
75 Any occurences of the two-character sequences
76 .Ic \en
77 and
78 .Ic \er
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
82 .Va stderr
83 and are otherwise ignored. See
84 .Sx WIDGETS
85 for applicable commands.
86 .Pp
87 It is an error if
88 .Ar in-fifo
89 exists but is not a named pipe. The named pipe
90 .Ar in-fifo
91 is deleted upon successful program termination.
92 .Pp
93 Default command input is
94 .Va stdin .
95 .It Fl o Ar out-fifo
96 Creates a named pipe
97 .Ar out-fifo
98 if necessary, and uses it for output of feedback messages from the
99 graphical user interface.
100 .Pp
101 A feedback message is a line of text; its format is
102 .Qq Fa name Ns Ic \&: Ns Fa info Bq Fa data
103 where
104 .Fa name
105 is the name of the sending widget. See
106 .Sx WIDGETS
107 for possible feedback messages.
108 .Pp
109 It is an error if
110 .Ar out-fifo
111 exists but is not a named pipe. The named pipe
112 .Ar out-fifo
113 is deleted upon successful program termination.
114 .Pp
115 Default feedback-message output is
116 .Va stdout .
117 .It Fl u Ar builder-file
118 Displays the graphical user interface
119 .Ar builder-file
120 which should be created using the
121 .Xr glade 1
122 user interface designer and saved in GtkBuilder (.ui) format. Widget
123 names should be alphanumeric, including underscores, and the main
124 window must be named
125 .Ic main .
126 .Pp
127 Default is
128 .Pa ./pipeglade.ui .
129 .It Fl -display Ar X-server
130 Uses the display on
131 .Ar X-server
132 for user interaction.
133 .It Fl G
134 Prints the GTK+ version and exits.
135 .It Fl V
136 Prints the
137 .Nm
138 version and exits.
139 .El
140 .Sh WIDGETS
141 The widget classes able to communicate through
142 .Nm
143 are
144 .Sx GtkButton ,
145 .Sx GtkCalendar ,
146 .Sx GtkCheckButton ,
147 .Sx GtkColorButton ,
148 .Sx GtkComboBoxText ,
149 .Sx GtkDialog ,
150 .Sx GtkDrawingArea ,
151 .Sx GtkEntry ,
152 .Sx GtkEventBox ,
153 .Sx GtkExpander ,
154 .Sx GtkFileChooserButton ,
155 .Sx GtkFileChooserDialog ,
156 .Sx GtkFontButton ,
157 .Sx GtkFrame ,
158 .Sx GtkImage ,
159 .Sx GtkLabel ,
160 .Sx GtkMenuItem, GtkImageMenuItem ,
161 .Sx GtkNotebook ,
162 .Sx GtkPrintUnixDialog ,
163 .Sx GtkProgressBar ,
164 .Sx GtkRadioButton ,
165 .Sx GtkScale ,
166 .Sx GtkScrolledWindow
167 .Sx GtkSocket ,
168 .Sx GtkSpinButton ,
169 .Sx GtkSpinner ,
170 .Sx GtkStatusbar ,
171 .Sx GtkSwitch ,
172 .Sx GtkTextView ,
173 .Sx GtkToggleButton ,
174 .Sx GtkTreeView ,
175 .Sx GtkTreeViewColumn ,
176 and
177 .Sx GtkWindow .
178 .Pp
179 .Nm
180 references a widget by the
181 .Fa name
182 it is given in Glade. In the .ui file, this
183 .Fa name
184 is represented by the
185 .Li id
186 attribute of the referenced object; therefore, a
187 .Ic GtkWindow
188 named
189 .Li foo
190 would appear in the .ui file as
191 .Li <object class="GtkWindow" id="foo"> .
192 .Ss Any Widget (including widgets not mentioned above)
193 .Bl -tag -width "commands "
194 .It Commands
195 .Qq Fa name Ns Ic :set_sensitive Brq Ic 0 | 1
196 makes the widget grayed out
197 .Pq Ic 0
198 or responsive
199 .Pq Ic 1 .
200 .Pp
201 .Qq Fa name Ns Ic :set_visible Brq Ic 0 | 1
202 hides
203 .Pq Ic 0
204 the widget, or makes it visible
205 .Pq Ic 1 .
206 .Pp
207 .Qq Fa name Ns Ic :grab_focus
208 puts the keyboard focus onto the widget, if possible.
209 .Pp
210 .Qq Fa name Ns Ic :set_size_request Bq Fa width height
211 sets the widget's minimum size to
212 .Fa width
213 x
214 .Fa height .
215 Default is the widget's natural size.
216 .Pp
217 .Qo
218 .Fa name Ns Ic :style
219 .Bo Fa prop Ic : Ns Fa val Ns Bo Ic ; Fa prop Ic : Ns Fa val ... Bc Bc
220 .Qc
221 sets properties
222 .Fa prop
223 of the widget style to
224 .Fa val .
225 Properties not explicitly specified are reset to their default values.
226 Examples:
227 .Bl -dash -offset indent -compact
228 .It
229 .Qq Li label1:style font:Bold 11; background-color:green
230 .It
231 .Qq Li label1:style font-style:italic; font-weight:bold; color:blue
232 .It
233 .Qq Li frame1:style border-color:red yellow; border-width:5px
234 .It
235 .Qq Li frame1:style border-radius:10px; transition:10s
236 .El
237 For a description of possible color notations see
238 .Sx GtkColorButton .
239 .Pp
240 .Qq Fa name Ns Ic :set_tooltip_text Bq Fa text
241 sets the widget's tooltip
242 .Fa text .
243 Default is disabling the tooltip.
244 .Pp
245 .Qq Fa name Ns Ic :force
246 simulates a click on the
247 .Fa name Ns
248 d widget, triggering a response as described with the widgets below.
249 Exceptions:
250 .Bl -dash -offset indent -compact
251 .It
252 The command is ignored by
253 .Sx GtkComboBoxText
254 (address its child
255 .Sx GtkEntry
256 instead),
257 .Sx GtkEventBox ,
258 .Sx GtkTreeView ,
259 and
260 .Sx GtkTreeViewColumn ;
261 .It
262 .Sx GtkCalendar , GtkEntry , GtkFileChooserButton , GtkScale ,
263 and
264 .Sx GtkSpinButton
265 report the currently selected item;
266 .It
267 .Sx GtkColorButton
268 and
269 .Sx GtkFontButton
270 just open their respective dialogs.
271 .El
272 .Pp
273 .Qq Fa name Ns Ic :load Fa file
274 reads arbitrary
275 .Nm
276 commands from
277 .Fa file .
278 A non-empty
279 .Fa name
280 is required but ignored.
281 .Ic :load
282 commands may be nested but on attempts to read from the same file, the
283 inner
284 .Ic :load
285 is ignored. There is also a
286 .Ic :save
287 command; see
288 .Sx GtkTextView
289 and
290 .Sx GtkTreeView .
291 .Pp
292 .Qq Fa name Ns Ic :main_quit
293 kills the user interface. A non-empty
294 .Fa name
295 is required but ignored.
296 .El
297 .Ss GtkButton
298 .Bl -tag -width "commands "
299 .It Commands
300 .Qq Fa name Ns Ic :set_label Fa string
301 replaces the button text with
302 .Fa string .
303 .It Feedback
304 .Qq Fa name Ns Ic \&:clicked
305 .Pp
306 .Ic GtkButton Ns
307 s with names ending in
308 .Ic _ok , _apply , _cancel , _send_text ,
309 and
310 .Ic _send_selection
311 may work differently; see
312 .Sx GtkDialog , GtkFileChooserDialog ,
313 and
314 .Sx GtkTextView
315 for details.
316 .El
317 .Ss GtkCalendar
318 .Bl -tag -width "commands "
319 .It Commands
320 .Qq Fa name Ns Ic :select_date Fa yyyy Ns Ic - Ns Fa mm Ns Ic - Ns Fa dd
321 selects the date on the calendar.
322 .Pp
323 .Qq Fa name Ns Ic :mark_day Fa day
324 marks
325 .Fa day Pq 1-31
326 on the calendar.
327 .Pp
328 .Qq Fa name Ns Ic :clear_marks
329 unmarks all days on the calendar.
330 .It Feedback
331 .Qq Fa name Ns Ic \&:clicked Fa yyyy Ns Ic - Ns Fa mm Ns Ic - Ns Fa dd
332 .Pp
333 .Qq Fa name Ns Ic \&:doubleclicked Fa yyyy Ns Ic - Ns Fa mm Ns Ic - Ns Fa dd
334 .El
335 .Ss GtkCheckButton
336 .Bl -tag -width "commands "
337 .It Commands
338 .Qq Fa name Ns Ic :set_active Brq Ic 0 | 1
339 switches the check mark off
340 .Pq Ic 0
341 or on
342 .Pq Ic 1 .
343 .Pp
344 .Qq Fa name Ns Ic :set_label Fa string
345 replaces the button text with
346 .Fa string .
347 .It Feedback
348 .Qq Fa name Ns Ic \&:1
349 if switched on, or
350 .Qq Fa name Ns Ic \&:0
351 otherwise.
352 .El
353 .Ss GtkColorButton
354 .Bl -tag -width "commands "
355 .It Commands
356 .Qq Fa name Ns Ic :set_color Fa color
357 preselects the color.
358 .Fa color
359 can be
360 .Bl -dash -offset indent -compact
361 .It
362 a standard X11 color name, like
363 .Qq Li Dark Sea Green ,
364 .It
365 a hexadecimal value in the form
366 .Ic # Ns Fa rgb , Ic # Ns Fa rrggbb , Ic # Ns Fa rrrgggbbb ,
367 or
368 .Ic # Ns Fa rrrrggggbbbb ,
369 .It
370 an RGB color in the form
371 .Ic rgb( Ns Fa red Ns Ic \&, Ns Fa green Ns Ic \&, Ns Fa blue Ns Ic \&) ,
372 or
373 .It
374 an RGBA color in the form
375 .Ic rgba( Ns Fa red Ns Ic \&, Ns Fa green Ns Ic \&, Ns
376 .Fa blue Ns Ic \&, Ns Fa alpha Ns Ic \&) .
377 .El
378 .It Feedback
379 .Qq Fa name Ns Ic \&:color Ic rgb( Ns Fa red Ns Ic \&, Ns Fa green Ns Ic \&, Ns Fa blue Ns Ic \&)
380 or
381 .Qq Fa name Ns Ic \&:color Ic rgba( Ns Fa red Ns Ic \&, Ns Fa green Ns Ic \&, Ns Fa blue Ns Ic \&, Ns Fa alpha Ns Ic \&) .
382 .Fa red , green ,
383 and
384 .Fa blue
385 lie between 0 and 255, and
386 .Fa alpha
387 between 0 and 1.
388 .El
389 .Ss GtkComboBoxText
390 The
391 .Ic GtkComboBoxText
392 should contain a
393 .Ic GtkEntry .
394 .Bl -tag -width "commands "
395 .It Commands
396 .Qq Fa name Ns Ic :prepend_text Fa string
397 and
398 .Qq Fa name Ns Ic :append_text Fa string
399 prepend/append a new selectable item marked
400 .Fa string .
401 .Pp
402 .Qq Fa name Ns Ic :insert_text Fa position string
403 inserts item
404 .Fa string
405 at
406 .Fa position .
407 .Pp
408 .Qq Fa name Ns Ic :remove Fa position
409 removes the item at
410 .Fa position .
411 .It Feedback
412 .Qq Fa entry_name Ns Ic \&:text Fa text ,
413 .Fa entry_name
414 being the name of the child
415 .Ic GtkEntry .
416 .El
417 .Ss GtkDialog
418 A
419 .Ic GtkDialog
420 that is named
421 .Fa foo
422 will be invoked by a
423 .Sx GtkMenuItem
424 or a
425 .Sx GtkImageMenuItem
426 that is named
427 .Fa foo Ns Ic _invoke .
428 .Pp
429 The
430 .Ic GtkDialog
431 should have a
432 .Sq Cancel
433 .Sx GtkButton
434 named
435 .Fa foo Ns Ic _cancel
436 .Po Ic main_cancel
437 if the dialog is the sole window of the GUI and therefore named
438 .Ic main
439 .Pc .
440 .Pp
441 If the
442 .Ic GtkDialog
443 has an
444 .Sq Ok
445 .Sx GtkButton
446 named
447 .Fa foo Ns Ic _ok ,
448 it will take care of hiding the dialog window.
449 .Bl -tag -width "commands "
450 .It Commands
451 none
452 .It Feedback
453 none
454 .El
455 .Ss GtkDrawingArea
456 Most drawing commands expect an
457 .Fa id
458 parameter (an arbitrary non-negative integer) which can be used to reference the
459 command for later removal.
460 .Pp
461 All coordinates refer to a left-handed coordinate system with its
462 origin in the upper-left corner.
463 .Bl -tag -width "commands "
464 .It Commands
465 .Qq Fa name Ns Ic :arc Fa id x y radius angle1 angle2
466 adds a circular arc to the current path. The arc is centered at
467 .Pq Fa x , y
468 and proceeds clockwise from
469 .Fa angle1
470 to
471 .Fa angle2
472 .Po
473 in degrees
474 .Pc .
475 .Pp
476 .Qq Fa name Ns Ic :arc_negative Fa id x y radius angle1 angle2
477 adds a circular arc to the current path. The arc is centered at
478 .Pq Fa x , y
479 and proceeds counterclockwise from
480 .Fa angle1
481 to
482 .Fa angle2
483 .Po
484 in degrees
485 .Pc .
486 .Pp
487 .Qq Fa name Ns Ic :close_path Fa id
488 adds a line segment from the current point to the point most recently
489 passed to
490 .Fa name Ns Ic :move_to
491 or
492 .Fa name Ns Ic :rel_move_to .
493 .Pp
494 .Qq Fa name Ns Ic :curve_to Fa id x1 y1 x2 y2 x3 y3
495 adds a cubic Bezier spline from the current point to
496 .Pq Fa x3 , y3 ,
497 using
498 .Pq Fa x1 , y1
499 and
500 .Pq Fa x2 , y2
501 as control points.
502 .Pp
503 .Qq Fa name Ns Ic :fill Fa id
504 fills the current path and clears it.
505 .Pp
506 .Qq Fa name Ns Ic :fill_preserve Fa id
507 fills the current path without clearing it.
508 .Pp
509 .Qq Fa name Ns Ic :line_to Fa id x y
510 adds a line from the current point to
511 .Pq Fa x , y .
512 .Pp
513 .Qq Fa name Ns Ic :move_to Fa id x y
514 sets the current point to
515 .Pq Fa x , y .
516 .Pp
517 .Qq Fa name Ns Ic :rectangle Fa id x y width height
518 adds a rectangle to the current path. The top left corner is at
519 .Pq Fa x , y .
520 .Pp
521 .Qq Fa name Ns Ic :refresh
522 redraws the
523 .Ic GtkDrawingArea
524 .Fa name .
525 .Pp
526 .Qq Fa name Ns Ic :rel_curve_to Fa id dx1 dy1 dx2 dy2 dx3 dy3
527 adds a cubic Bezier spline from the current point to
528 .Pq Fa dx3 , dy3 ,
529 using
530 .Pq Fa dx1 , dy1
531 and
532 .Pq Fa dx2 , dy2
533 as control points. All coordinates are offsets relative to the
534 current point.
535 .Pp
536 .Qq Fa name Ns Ic :rel_line_to Fa id dx dy
537 adds a line from the current point to a point offset from there by
538 .Pq Fa dx , dy .
539 .Pp
540 .Qq Fa name Ns Ic :rel_move_to Fa id dx dy
541 moves the current point by
542 .Pq Fa dx , dy .
543 .Pp
544 .Qq Fa name Ns Ic :remove Fa id
545 removes the elements with
546 .Fa id
547 from the
548 .Ic GtkDrawingArea Fa name .
549 .Pp
550 .Qq Fa name Ns Ic :set_dash Fa id l
551 sets the dash pattern to
552 .Fa l
553 on,
554 .Fa l
555 off.
556 .Pp
557 .Qq Fa name Ns Ic :set_dash Fa id l1on l1off l2on l2off ...
558 resets the dash pattern to a line with arbitrary on/off portions.
559 .Pp
560 .Qq Fa name Ns Ic :set_dash Fa id
561 resets the dash pattern to a solid line.
562 .Pp
563 .Qq Fa name Ns Ic :set_font_size Fa id size
564 sets the font size for subsequent calls of
565 .Fa name Ns Ic :show_text .
566 .Pp
567 .Qq Fa name Ns Ic :set_line_cap Fa id Brq Ic butt | round | square
568 sets the line cap style.
569 .Pp
570 .Qq Fa name Ns Ic :set_line_join Fa id Brq Ic miter | round | bevel
571 sets the line junction style.
572 .Pp
573 .Qq Fa name Ns Ic :set_line_width Fa id width
574 sets the line width.
575 .Pp
576 .Qq Fa name Ns Ic :set_source_rgba Fa id color
577 sets the color.
578 .Fa color
579 is in the format used with
580 .Sx GtkColorButton .
581 .Pp
582 .Qq Fa name Ns Ic :show_text Fa id text
583 writes
584 .Fa text ,
585 beginning at the current point.
586 .Pp
587 .Qq Fa name Ns Ic :stroke Fa id
588 strokes the current path and clears it.
589 .Pp
590 .Qq Fa name Ns Ic :stroke_preserve Fa id
591 strokes the current path without clearing it.
592 .It Feedback
593 none
594 .El
595 .Ss GtkEntry
596 .Bl -tag -width "commands "
597 .It Commands
598 .Qq Fa name Ns Ic :set_text Fa string
599 replaces the user-editable text with
600 .Fa string .
601 .Pp
602 .Qq Fa name Ns Ic :set_placeholder_text Fa string
603 sets the
604 .Fa string
605 that is displayed when the entry is empty and unfocused.
606 .It Feedback
607 .Qq Fa name Ns Ic \&:text Fa text ,
608 once for each change of
609 .Fa text .
610 .El
611 .Ss GtkEventBox
612 .Fa x , y
613 are mouse pointer coordinates relative to the
614 .Ic GtkEventBox .
615 .Bl -tag -width "commands "
616 .It Commands
617 none
618 .It Feedback
619 .Qq Fa name Ns Ic \&:button_press Fa b x y ,
620 .Qq Fa name Ns Ic \&:button_release Fa b x y
621 where
622 .Fa b
623 is the mouse button (normally 1, 2, or 3 for the left, middle, and
624 right button; others may exist).
625 .Pp
626 .Qq Fa name Ns Ic \&:motion Fa x y
627 is reported repeatedly while the mouse is being moved with a button
628 pressed.
629 .Pp
630 .Qq Fa name Ns Ic \&:key_press Fa key ,
631 .Fa key
632 being the key's name
633 .Pq e.g. Li Control_L , Tab , a .
634 .El
635 .Ss GtkExpander
636 .Bl -tag -width "commands "
637 .It Commands
638 .Qq Fa name Ns Ic :set_label Fa string
639 replaces the expander label text with
640 .Fa string .
641 .Pp
642 .Qq Fa name Ns Ic :set_expanded Brq Ic 0 | 1
643 hides
644 .Pq Ic 0
645 the child widget, or makes it visible
646 .Pq Ic 1 .
647 .It Feedback
648 none
649 .El
650 .Ss GtkFileChooserButton
651 .Bl -tag -width "commands "
652 .It Commands
653 .Qq Fa name Ns Ic :set_filename Fa path
654 preselects
655 .Fa path
656 to the extent it exists.
657 .It Feedback
658 .Qq Fa name Ns Ic \&:file Fa pathname
659 if the selection has changed.
660 .El
661 .Ss GtkFileChooserDialog
662 A
663 .Ic GtkFileChooserDialog
664 that is named
665 .Fa foo
666 will be invoked by a
667 .Sx GtkMenuItem
668 or a
669 .Sx GtkImageMenuItem
670 that is named
671 .Fa foo Ns Ic _invoke .
672 .Pp
673 The
674 .Ic GtkFileChooserDialog
675 should have an
676 .Sq OK
677 .Sx GtkButton
678 named
679 .Fa foo Ns Ic _ok
680 .Po Ic main_ok
681 if the dialog is the sole window of the GUI and therefore named
682 .Ic main
683 .Pc .
684 .Pp
685 The
686 .Ic GtkFileChooserDialog
687 may have a
688 .Sq Cancel
689 .Sx GtkButton
690 named
691 .Fa foo Ns Ic _cancel
692 .Po Ic main_cancel
693 if the dialog is the sole window of the GUI and therefore named
694 .Ic main
695 .Pc .
696 .Pp
697 The
698 .Ic GtkFileChooserDialog
699 may have an
700 .Sq Apply
701 .Sx GtkButton
702 named
703 .Fa foo Ns Ic _apply
704 .Po Ic main_apply
705 if the dialog is the sole window of the GUI and therefore named
706 .Ic main
707 .Pc .
708 .Bl -tag -width "commands "
709 .It Commands
710 .Qq Fa name Ns Ic :set_filename Fa path
711 preselects
712 .Fa path
713 to the extent it exists.
714 .Pp
715 .Qq Fa name Ns Ic :set_current_name Fa string
716 makes
717 .Fa string
718 the suggested filename, which may not yet exist.
719 .Fa string
720 should either resemble an absolute path, or the
721 .Fa directory
722 must be set separately by
723 .Fa name Ns Ic :set_filename Fa directory .
724 .It Feedback
725 .Qq Fa name Ns Ic :file Fa pathname
726 and/or
727 .Qq Fa name Ns Ic :folder Fa pathname
728 .El
729 .Ss GtkFontButton
730 .Bl -tag -width "commands "
731 .It Commands
732 .Qq Fa name Ns Ic :set_font_name Fa fontname
733 preselects the font.
734 .It Feedback
735 .Qq Fa name Ns Ic \&:font Fa fontname
736 .El
737 .Ss GtkFrame
738 .Bl -tag -width "commands "
739 .It Commands
740 .Qq Fa name Ns Ic :set_label Fa text
741 replaces the frame label text with
742 .Fa string .
743 .It Feedback
744 none
745 .El
746 .Ss GtkImage
747 .Bl -tag -width "commands "
748 .It Commands
749 .Qq Fa name Ns Ic :set_from_icon_name Fa icon-name
750 replaces the image with one of the standard icons.
751 .Pp
752 .Qq Fa name Ns Ic :set_from_file Fa path
753 replaces the image by the one found at
754 .Fa path Ns .
755 .It Feedback
756 none
757 .El
758 .Ss GtkLabel
759 .Bl -tag -width "commands "
760 .It Commands
761 .Qq Fa name Ns Ic :set_text Fa string
762 replaces the label text with
763 .Fa string .
764 .It Feedback
765 none
766 .El
767 .Ss GtkMenuItem, GtkImageMenuItem
768 .Bl -tag -width "commands "
769 .It Commands
770 none
771 .It Feedback
772 A
773 .Ic GtkMenuItem
774 or
775 .Ic GtkImageMenuItem
776 with the name
777 .Fa foo Ns Ic _invoke
778 will invoke the
779 .Sx GtkDialog
780 or
781 .Sx GtkFileChooserDialog
782 named
783 .Fa foo
784 if it exists. If there isn't any dialog attached to the
785 .Ic GtkMenuItem ,
786 it reports
787 .Qq Fa name Ns Ic \&:active Fa label .
788 .El
789 .Ss GtkNotebook
790 .Bl -tag -width "commands "
791 .It Commands
792 .Qq Fa name Ns Ic :set_current_page Fa n
793 switches to zero-based page number
794 .Fa n .
795 .It Feedback
796 none
797 .El
798 .Ss GtkPrintUnixDialog
799 .Bl -tag -width "commands "
800 .It Commands
801 .Qq Fa name Ns Ic :print Fa file.ps
802 opens the print dialog. Pressing the
803 .Qq Print
804 button sends
805 .Fa file.ps
806 to the printer the user selected in the dialog.
807 .It Feedback
808 none
809 .El
810 .Ss GtkProgressBar
811 .Bl -tag -width "commands "
812 .It Commands
813 .Qq Fa name Ns Ic :set_fraction Fa x
814 moves the progress bar to
815 .Fa x
816 .Pq between 0 and 1 .
817 .Pp
818 .Qq Fa name Ns Ic :set_text Bq Fa string
819 replaces the text of the progress bar with
820 .Fa string .
821 Default is the progress percentage.
822 .It Feedback
823 none
824 .El
825 .Ss GtkRadioButton
826 .Bl -tag -width "commands "
827 .It Commands
828 .Qq Fa name Ns Ic :set_active 1
829 switches the button on. All other buttons of the same group will go off
830 automatically.
831 .Pp
832 .Qq Fa name Ns Ic :set_label Fa string
833 replaces the button text with
834 .Fa string .
835 .It Feedback
836 .Qq Fa name Ns Ic \&:1
837 if switched on, or
838 .Qq Fa name Ns Ic \&:0
839 otherwise.
840 .El
841 .Ss GtkScale
842 .Bl -tag -width "commands "
843 .It Commands
844 .Qq Fa name Ns Ic :set_value Fa x
845 moves the slider to value
846 .Fa x .
847 .It Feedback
848 .Qq Fa name Ns Ic \&:value Fa floating_point_text
849 .El
850 .Ss GtkScrolledWindow
851 .Bl -tag -width "commands "
852 .It Commands
853 .Qq Fa name Ns Ic :hscroll Fa position
854 and
855 .Qq Fa name Ns Ic :vscroll Fa position
856 scroll
857 .Fa position
858 to the left or top edge of the
859 .Ic GtkScrolledWindow ,
860 respectively.
861 .Pp
862 .Qq Fa name Ns Ic :hscroll_to_range Fa pos_0 pos_1
863 and
864 .Qq Fa name Ns Ic :vscroll_to_range Fa pos_0 pos_1
865 scroll, if necessary, the range between
866 .Fa pos_0
867 and
868 .Fa pos_1
869 into the
870 .Ic GtkScrolledWindow .
871 If the range is greater than the window, the initial part of the range
872 will be visible.
873 .It Feedback
874 none
875 .El
876 .Ss GtkSocket
877 .Ic GtkSocket
878 may be unsupported by Glade, but its definition can be inserted
879 manually into the GtkBuilder (.ui) file:
880 .Bf -literal
881 \ \ <child>
882 \ \ \ \ <object class="GtkSocket" id="socket1">
883 \ \ \ \ \ \ <property name="visible">True</property>
884 \ \ \ \ \ \ <property name="can_focus">True</property>
885 \ \ \ \ </object>
886 \ \ \ \ <packing>
887 \ \ \ \ \ \ <property name="expand">True</property>
888 \ \ \ \ \ \ <property name="fill">True</property>
889 \ \ \ \ \ \ <property name="position">1</property>
890 \ \ \ \ </packing>
891 \ \ </child>
892 .Ef
893 .Bl -tag -width "commands "
894 .It Commands
895 .Qq Fa name Ns Ic :id
896 requests a feedback message containing the socket
897 .Fa xid .
898 .It Feedback
899 .Qq Fa name Ns Ic :id Fa xid
900 can be used by another process to XEmbed its widgets into the
901 .Ic GtkSocket .
902 .Pp
903 .Qq Fa name Ns Ic :plug-added ,
904 .Qo
905 .Fa name Ns
906 .Ic :plug-removed
907 .Qc .
908 Notification that the other process has inserted its widgets into or
909 removed them from the
910 .Ic GtkSocket .
911 .El
912 .Ss GtkSpinButton
913 .Bl -tag -width "commands "
914 .It Commands
915 .Qq Fa name Ns Ic :set_text Fa string
916 sets the selected value to
917 .Fa string .
918 .It Feedback
919 .Qq Fa name Ns Ic \&:text Fa text
920 .El
921 .Ss GtkSpinner
922 .Bl -tag -width "commands "
923 .It Commands
924 .Qq Fa name Ns Ic :start
925 and
926 .Qq Fa name Ns Ic :stop
927 start and stop the spinner.
928 .It Feedback
929 none
930 .El
931 .Ss GtkStatusbar
932 The context
933 .Fa id
934 parameter is an arbitrary non-negative integer.
935 .Bl -tag -width "commands "
936 .It Commands
937 .Qq Fa name Ns Ic :push_id Fa id string ,
938 .Qq Fa name Ns Ic :push Fa string
939 associate
940 .Fa string
941 with context id
942 .Fa id
943 or 0, respectively, and display it in the statusbar.
944 .Pp
945 .Qq Fa name Ns Ic :pop_id Fa id ,
946 .Qq Fa name Ns Ic :pop
947 remove the latest entry associated with context id
948 .Fa id
949 or 0, respectively, from the statusbar.
950 .Pp
951 .Qq Fa name Ns Ic :remove_all
952 empties the statusbar.
953 .It Feedback
954 none
955 .El
956 .Ss GtkSwitch
957 .Bl -tag -width "commands "
958 .It Commands
959 .Qq Fa name Ns Ic :set_active Brq Ic 0 | 1
960 turns the switch off
961 .Pq Ic 0
962 or on
963 .Pq Ic 1 .
964 .It Feedback
965 .Qq Fa name Ns Ic \&:1
966 if switched on, or
967 .Qq Fa name Ns Ic \&:0
968 otherwise.
969 .El
970 .Ss GtkTextView
971 There should be a dedicated
972 .Sx GtkButton
973 for sending (parts of) the text.
974 If the name of the
975 .Ic GtkTextView
976 is
977 .Fa foo ,
978 a
979 .Sx GtkButton
980 named
981 .Fa foo Ns Ic _send_text
982 will send the content of the
983 .Ic GtkTextView ;
984 a
985 .Sx GtkButton
986 named
987 .Fa foo Ns Ic _send_selection
988 will send the highlighted part the
989 .Ic GtkTextView .
990 .Bl -tag -width "commands "
991 .It Commands
992 .Qq Fa name Ns Ic :set_text Fa string
993 replaces the user-editable text with (potentially empty)
994 .Fa string Ns .
995 .Pp
996 .Qq Fa name Ns Ic :delete
997 deletes the text.
998 .Pp
999 .Qq Fa name Ns Ic :insert_at_cursor Fa string
1000 inserts
1001 .Fa string
1002 at cursor position.
1003 .Pp
1004 .Qq Fa name Ns Ic :place_cursor Brq Fa position | Ic end
1005 places the text cursor at
1006 .Fa position
1007 or at the end of the text.
1008 .Pp
1009 .Qq Fa name Ns Ic :place_cursor_at_line Fa line
1010 places the text cursor at the beginning of
1011 .Fa line .
1012 .Pp
1013 .Qq Fa name Ns Ic :scroll_to_cursor
1014 scrolls to the cursor position if necessary.
1015 .Pp
1016 .Qq Fa name Ns Ic :save Fa file
1017 stores in
1018 .Fa file
1019 a
1020 .Nm
1021 command containing the text.
1022 .It Feedback
1023 .Qq Fa button_name Ns Ic :text Fa text ,
1024 .Fa button_name
1025 being the name of the
1026 .Sx GtkButton .
1027 Line endings in
1028 .Fa text
1029 are replaced by
1030 .Ic \en ,
1031 and backslashes are replaced by
1032 .Ic \e\e .
1033 .El
1034 .Ss GtkToggleButton
1035 .Bl -tag -width "commands "
1036 .It Commands
1037 .Qq Fa name Ns Ic :set_active Brq Ic 0 | 1
1038 switches the button off
1039 .Pq Ic 0
1040 or on
1041 .Pq Ic 1 .
1042 .Pp
1043 .Qq Fa name Ns Ic :set_label Fa string
1044 replaces the button text with
1045 .Fa string .
1046 .It Feedback
1047 .Qq Fa name Ns Ic \&:1
1048 if switched on, or
1049 .Qq Fa name Ns Ic \&:0
1050 otherwise.
1051 .El
1052 .Ss GtkTreeView
1053 .Nm
1054 can deal with columns of type
1055 .Ic gboolean , gint , guint , glong , gulong , gint64 , guint64 , gfloat , gdouble ,
1056 and
1057 .Ic gchararray .
1058 .Pp
1059 .Fa row
1060 and
1061 .Fa column
1062 refer to the underlying model
1063 .Ic ( GtkListStore
1064 or
1065 .Ic GtkTreeStore ) .
1066 .Fa row
1067 is a sequence of one or more colon-separated integers, e.g.
1068 .Qq 3
1069 or
1070 .Qq 0:0:1 .
1071 .Bl -tag -width "commands "
1072 .It Commands
1073 .Qq Fa name Ns Ic :set Fa row column data
1074 replaces the content at
1075 .Pq Fa row , column
1076 with
1077 .Fa data
1078 (which should be compatible with the type of
1079 .Fa column ) .
1080 If necessary, new tree nodes are created to obtain the minimal tree
1081 structure needed to support
1082 .Fa row .
1083 .Pp
1084 .Qq Fa name Ns Ic :insert_row Brq Fa row Bo Ic as_child Bc | Ic end
1085 inserts a new, empty row; either as a sibling of
1086 .Fa row
1087 at position
1088 .Fa row ,
1089 or as a child of
1090 .Fa row ,
1091 or at the end of the list, respectively.
1092 .Pp
1093 .Qq Fa name Ns Ic :move_row Fa origin Brq Fa destination | Ic end
1094 moves the row at
1095 .Fa origin
1096 within its current level to
1097 .Fa destination
1098 or to the end.
1099 .Pp
1100 .Qq Fa name Ns Ic :remove_row Fa row
1101 removes the row at position
1102 .Fa row .
1103 .Pp
1104 .Qq Fa name Ns Ic :clear
1105 removes all rows.
1106 .Pp
1107 .Qq Fa name Ns Ic :expand Fa row
1108 expands one level of the subtree below
1109 .Fa row .
1110 .Pp
1111 .Qq Fa name Ns Ic :expand_all Bq Fa row
1112 expands the subtree below
1113 .Fa row ,
1114 or the whole tree.
1115 .Pp
1116 .Qq Fa name Ns Ic :collapse Bq Fa row
1117 collapses the subtree below
1118 .Fa row ,
1119 or the whole tree.
1120 .Pp
1121 .Qq Fa name Ns Ic :set_cursor Bq Fa row
1122 sets the cursor to
1123 .Fa row ,
1124 or unsets it.
1125 .Pp
1126 .Qq Fa name Ns Ic :scroll Fa row column
1127 scrolls the cell at
1128 .Pq Fa row , column
1129 into view.
1130 .Pp
1131 .Qq Fa name Ns Ic :save Fa file
1132 stores the content of the underlying model as a sequence of
1133 .Nm
1134 commands into
1135 .Fa file .
1136 .It Feedback
1137 .Qq Fa name Ns Ic \&:clicked
1138 .Pp
1139 .Qq Fa name Ns Ic \&: Ns Fa column_type row column value ,
1140 one message per cell in the underlying model for each selected row; or
1141 .Pp
1142 .Qq Fa name Ns Ic \&: Ns Fa column_type row column new_value ,
1143 if the cell at
1144 .Pq Fa row , column
1145 has been edited.
1146 .El
1147 .Ss GtkTreeViewColumn
1148 .Bl -tag -width "commands "
1149 .It Commands
1150 none
1151 .It Feedback
1152 .Qq Fa name Ns Ic \&:clicked
1153 .El
1154 .Ss GtkWindow
1155 .Bl -tag -width "commands "
1156 .It Commands
1157 .Qq Fa name Ns Ic :set_title Fa string
1158 replaces the text in the title bar with
1159 .Fa string .
1160 .Pp
1161 .Qq Fa name Ns Ic :resize Bq Fa width height
1162 changes the window size to
1163 .Fa width
1164 x
1165 .Fa height
1166 pixels if specified, or to the default size.
1167 .Pp
1168 .Qq Fa name Ns Ic :move Fa x y
1169 moves the window to position
1170 .Fa x , y .
1171 .Pp
1172 .Qq Fa name Ns Ic :fullscreen
1173 and
1174 .Qq Fa name Ns Ic :unfullscreen
1175 switch fullscreen mode on and off.
1176 .It Feedback
1177 none
1178 .El
1179 .Sh EXAMPLES
1180 .Ss Discovering Pipeglade Interactively
1181 Suppose the interface in
1182 .Pa ./pipeglade.ui
1183 has a
1184 .Sx GtkLabel Li label1
1185 and a
1186 .Sx GtkButton Li button1 .
1187 After invoking
1188 .Dl pipeglade
1189 and clicking the
1190 .Sx GtkButton , Qq button1:clicked
1191 will be reported on the terminal. Typing
1192 .Dl label1:set_text Button Label
1193 will change the text shown on the label into
1194 .Qq Button Label .
1195 .Ss One-Shot File Dialog
1196 Suppose the interface in
1197 .Pa ./simple_open.ui
1198 contains a
1199 .Sx GtkFileChooserDialog
1200 with an
1201 .Sq OK
1202 .Sx GtkButton
1203 named
1204 .Li main_ok .
1205 Invoking
1206 .Dl pipeglade -u simple_open.ui
1207 will open the dialog; pressing
1208 .Sq OK
1209 will close it after sending the selected filename to
1210 .Va stdout .
1211 .Ss One-Shot User Notification
1212 If the interface in
1213 .Pa ./simple_dialog.ui
1214 contains a
1215 .Sx GtkLabel Li label1 ,
1216 then
1217 .Dl pipeglade -u simple_dialog.ui <<< \e
1218 .Dl \ \ \ \ \&"label1:set_text NOW READ THIS!\&"
1219 will set the label text accordingly and wait for user input.
1220 .Ss Continuous Input
1221 The following shell command displays a running clock:
1222 .Dl while true; do
1223 .Dl \ \ \ \ echo \&"label1:set_text `date`\&";
1224 .Dl \ \ \ \ sleep 1;
1225 .Dl done | pipeglade -u simple_dialog.ui
1226 .Ss Continuous Input and Output
1227 The following shell script fragment sets up
1228 .Nm
1229 for continuous communication with another program,
1230 .Li main_prog :
1231 .Dl pipeglade -i in.fifo -o out.fifo &
1232 .Dl # wait for in.fifo and out.fifo to appear
1233 .Dl while test \& ! \e( -e in.fifo -a -e out.fifo \e); do :; done
1234 .Dl main_prog <out.fifo >in.fifo
1235 .Sh EXIT STATUS
1236 .Nm
1237 exits 0 on success, and >0 if an error occurs.
1238 .Sh SEE ALSO
1239 .Xr glade 1 ,
1240 .Xr dialog 1 ,
1241 .Xr gxmessage 1 ,
1242 .Xr kdialog 1 ,
1243 .Xr whiptail 1 ,
1244 .Xr xmessage 1 ,
1245 .Xr zenity 1
1246 .Sh AUTHOR
1247 .Nm
1248 was written by
1249 .An Bert Burgemeister Aq trebbu@googlemail.com .
1250 .Sh BUGS
1251 Please report them to the author.