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