| blob | 58c8d9949a1a3cda72c1a2e54a9fe14b4bd7b223 |
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 .Qq Fa name Ns Ic :set_title Fa string
452 replaces the text in the title bar with
453 .Fa string .
454 .Pp
455 .Qq Fa name Ns Ic :resize Bq Fa width height
456 changes the size of the dialog window to
457 .Fa width
458 x
459 .Fa height
460 pixels if specified, or to the default size.
461 .Pp
462 .Qq Fa name Ns Ic :move Fa x y
463 moves the dialog window to position
464 .Fa x , y .
465 .Pp
466 .Qq Fa name Ns Ic :fullscreen
467 and
468 .Qq Fa name Ns Ic :unfullscreen
469 switch fullscreen mode on and off.
470 .It Feedback
471 none
472 .El
473 .Ss GtkDrawingArea
474 Most drawing commands expect an
475 .Fa id
476 parameter (an arbitrary non-negative integer) which can be used to reference the
477 command for later removal.
478 .Pp
479 All coordinates refer to a left-handed coordinate system with its
480 origin in the upper-left corner.
481 .Bl -tag -width "commands "
482 .It Commands
483 .Qq Fa name Ns Ic :arc Fa id x y radius angle1 angle2
484 adds a circular arc to the current path. The arc is centered at
485 .Pq Fa x , y
486 and proceeds clockwise from
487 .Fa angle1
488 to
489 .Fa angle2
490 .Po
491 in degrees
492 .Pc .
493 .Pp
494 .Qq Fa name Ns Ic :arc_negative Fa id x y radius angle1 angle2
495 adds a circular arc to the current path. The arc is centered at
496 .Pq Fa x , y
497 and proceeds counterclockwise from
498 .Fa angle1
499 to
500 .Fa angle2
501 .Po
502 in degrees
503 .Pc .
504 .Pp
505 .Qq Fa name Ns Ic :close_path Fa id
506 adds a line segment from the current point to the point most recently
507 passed to
508 .Fa name Ns Ic :move_to
509 or
510 .Fa name Ns Ic :rel_move_to .
511 .Pp
512 .Qq Fa name Ns Ic :curve_to Fa id x1 y1 x2 y2 x3 y3
513 adds a cubic Bezier spline from the current point to
514 .Pq Fa x3 , y3 ,
515 using
516 .Pq Fa x1 , y1
517 and
518 .Pq Fa x2 , y2
519 as control points.
520 .Pp
521 .Qq Fa name Ns Ic :fill Fa id
522 fills the current path and clears it.
523 .Pp
524 .Qq Fa name Ns Ic :fill_preserve Fa id
525 fills the current path without clearing it.
526 .Pp
527 .Qq Fa name Ns Ic :line_to Fa id x y
528 adds a line from the current point to
529 .Pq Fa x , y .
530 .Pp
531 .Qq Fa name Ns Ic :move_to Fa id x y
532 sets the current point to
533 .Pq Fa x , y .
534 .Pp
535 .Qq Fa name Ns Ic :rectangle Fa id x y width height
536 adds a rectangle to the current path. The top left corner is at
537 .Pq Fa x , y .
538 .Pp
539 .Qq Fa name Ns Ic :refresh
540 redraws the
541 .Ic GtkDrawingArea
542 .Fa name .
543 .Pp
544 .Qq Fa name Ns Ic :rel_curve_to Fa id dx1 dy1 dx2 dy2 dx3 dy3
545 adds a cubic Bezier spline from the current point to
546 .Pq Fa dx3 , dy3 ,
547 using
548 .Pq Fa dx1 , dy1
549 and
550 .Pq Fa dx2 , dy2
551 as control points. All coordinates are offsets relative to the
552 current point.
553 .Pp
554 .Qq Fa name Ns Ic :rel_line_to Fa id dx dy
555 adds a line from the current point to a point offset from there by
556 .Pq Fa dx , dy .
557 .Pp
558 .Qq Fa name Ns Ic :rel_move_to Fa id dx dy
559 moves the current point by
560 .Pq Fa dx , dy .
561 .Pp
562 .Qq Fa name Ns Ic :remove Fa id
563 removes the elements with
564 .Fa id
565 from the
566 .Ic GtkDrawingArea Fa name .
567 .Pp
568 .Qq Fa name Ns Ic :set_dash Fa id l
569 sets the dash pattern to
570 .Fa l
571 on,
572 .Fa l
573 off.
574 .Pp
575 .Qq Fa name Ns Ic :set_dash Fa id l1on l1off l2on l2off ...
576 resets the dash pattern to a line with arbitrary on/off portions.
577 .Pp
578 .Qq Fa name Ns Ic :set_dash Fa id
579 resets the dash pattern to a solid line.
580 .Pp
581 .Qq Fa name Ns Ic :set_font_size Fa id size
582 sets the font size for subsequent calls of
583 .Fa name Ns Ic :show_text .
584 .Pp
585 .Qq Fa name Ns Ic :set_line_cap Fa id Brq Ic butt | round | square
586 sets the line cap style.
587 .Pp
588 .Qq Fa name Ns Ic :set_line_join Fa id Brq Ic miter | round | bevel
589 sets the line junction style.
590 .Pp
591 .Qq Fa name Ns Ic :set_line_width Fa id width
592 sets the line width.
593 .Pp
594 .Qq Fa name Ns Ic :set_source_rgba Fa id color
595 sets the color.
596 .Fa color
597 is in the format used with
598 .Sx GtkColorButton .
599 .Pp
600 .Qq Fa name Ns Ic :show_text Fa id text
601 writes
602 .Fa text ,
603 beginning at the current point.
604 .Pp
605 .Qq Fa name Ns Ic :stroke Fa id
606 strokes the current path and clears it.
607 .Pp
608 .Qq Fa name Ns Ic :stroke_preserve Fa id
609 strokes the current path without clearing it.
610 .It Feedback
611 none
612 .El
613 .Ss GtkEntry
614 .Bl -tag -width "commands "
615 .It Commands
616 .Qq Fa name Ns Ic :set_text Fa string
617 replaces the user-editable text with
618 .Fa string .
619 .Pp
620 .Qq Fa name Ns Ic :set_placeholder_text Fa string
621 sets the
622 .Fa string
623 that is displayed when the entry is empty and unfocused.
624 .It Feedback
625 .Qq Fa name Ns Ic \&:text Fa text ,
626 once for each change of
627 .Fa text .
628 .El
629 .Ss GtkEventBox
630 .Fa x , y
631 are mouse pointer coordinates relative to the
632 .Ic GtkEventBox .
633 .Bl -tag -width "commands "
634 .It Commands
635 none
636 .It Feedback
637 .Qq Fa name Ns Ic \&:button_press Fa b x y ,
638 .Qq Fa name Ns Ic \&:button_release Fa b x y
639 where
640 .Fa b
641 is the mouse button (normally 1, 2, or 3 for the left, middle, and
642 right button; others may exist).
643 .Pp
644 .Qq Fa name Ns Ic \&:motion Fa x y
645 is reported repeatedly while the mouse is being moved with a button
646 pressed.
647 .Pp
648 .Qq Fa name Ns Ic \&:key_press Fa key ,
649 .Fa key
650 being the key's name
651 .Pq e.g. Li Control_L , Tab , a .
652 .El
653 .Ss GtkExpander
654 .Bl -tag -width "commands "
655 .It Commands
656 .Qq Fa name Ns Ic :set_label Fa string
657 replaces the expander label text with
658 .Fa string .
659 .Pp
660 .Qq Fa name Ns Ic :set_expanded Brq Ic 0 | 1
661 hides
662 .Pq Ic 0
663 the child widget, or makes it visible
664 .Pq Ic 1 .
665 .It Feedback
666 none
667 .El
668 .Ss GtkFileChooserButton
669 .Bl -tag -width "commands "
670 .It Commands
671 .Qq Fa name Ns Ic :set_filename Fa path
672 preselects
673 .Fa path
674 to the extent it exists.
675 .It Feedback
676 .Qq Fa name Ns Ic \&:file Fa pathname
677 if the selection has changed.
678 .El
679 .Ss GtkFileChooserDialog
680 A
681 .Ic GtkFileChooserDialog
682 that is named
683 .Fa foo
684 will be invoked by a
685 .Sx GtkMenuItem
686 or a
687 .Sx GtkImageMenuItem
688 that is named
689 .Fa foo Ns Ic _invoke .
690 .Pp
691 The
692 .Ic GtkFileChooserDialog
693 should have an
694 .Sq OK
695 .Sx GtkButton
696 named
697 .Fa foo Ns Ic _ok
698 .Po Ic main_ok
699 if the dialog is the sole window of the GUI and therefore named
700 .Ic main
701 .Pc .
702 .Pp
703 The
704 .Ic GtkFileChooserDialog
705 may have a
706 .Sq Cancel
707 .Sx GtkButton
708 named
709 .Fa foo Ns Ic _cancel
710 .Po Ic main_cancel
711 if the dialog is the sole window of the GUI and therefore named
712 .Ic main
713 .Pc .
714 .Pp
715 The
716 .Ic GtkFileChooserDialog
717 may have an
718 .Sq Apply
719 .Sx GtkButton
720 named
721 .Fa foo Ns Ic _apply
722 .Po Ic main_apply
723 if the dialog is the sole window of the GUI and therefore named
724 .Ic main
725 .Pc .
726 .Bl -tag -width "commands "
727 .It Commands
728 .Qq Fa name Ns Ic :set_filename Fa path
729 preselects
730 .Fa path
731 to the extent it exists.
732 .Pp
733 .Qq Fa name Ns Ic :set_current_name Fa string
734 makes
735 .Fa string
736 the suggested filename, which may not yet exist.
737 .Fa string
738 should either resemble an absolute path, or the
739 .Fa directory
740 must be set separately by
741 .Fa name Ns Ic :set_filename Fa directory .
742 .Pp
743 .Qq Fa name Ns Ic :set_title Fa string
744 replaces the text in the title bar with
745 .Fa string .
746 .Pp
747 .Qq Fa name Ns Ic :resize Bq Fa width height
748 changes the size of the dialog window to
749 .Fa width
750 x
751 .Fa height
752 pixels if specified, or to the default size.
753 .Pp
754 .Qq Fa name Ns Ic :move Fa x y
755 moves the dialog window to position
756 .Fa x , y .
757 .Pp
758 .Qq Fa name Ns Ic :fullscreen
759 and
760 .Qq Fa name Ns Ic :unfullscreen
761 switch fullscreen mode on and off.
762 .It Feedback
763 .Qq Fa name Ns Ic :file Fa pathname
764 and/or
765 .Qq Fa name Ns Ic :folder Fa pathname
766 .El
767 .Ss GtkFontButton
768 .Bl -tag -width "commands "
769 .It Commands
770 .Qq Fa name Ns Ic :set_font_name Fa fontname
771 preselects the font.
772 .It Feedback
773 .Qq Fa name Ns Ic \&:font Fa fontname
774 .El
775 .Ss GtkFrame
776 .Bl -tag -width "commands "
777 .It Commands
778 .Qq Fa name Ns Ic :set_label Fa text
779 replaces the frame label text with
780 .Fa string .
781 .It Feedback
782 none
783 .El
784 .Ss GtkImage
785 .Bl -tag -width "commands "
786 .It Commands
787 .Qq Fa name Ns Ic :set_from_icon_name Fa icon-name
788 replaces the image with one of the standard icons.
789 .Pp
790 .Qq Fa name Ns Ic :set_from_file Fa path
791 replaces the image by the one found at
792 .Fa path Ns .
793 .It Feedback
794 none
795 .El
796 .Ss GtkLabel
797 .Bl -tag -width "commands "
798 .It Commands
799 .Qq Fa name Ns Ic :set_text Fa string
800 replaces the label text with
801 .Fa string .
802 .It Feedback
803 none
804 .El
805 .Ss GtkMenuItem, GtkImageMenuItem
806 .Bl -tag -width "commands "
807 .It Commands
808 none
809 .It Feedback
810 A
811 .Ic GtkMenuItem
812 or
813 .Ic GtkImageMenuItem
814 with the name
815 .Fa foo Ns Ic _invoke
816 will invoke the
817 .Sx GtkDialog
818 or
819 .Sx GtkFileChooserDialog
820 named
821 .Fa foo
822 if it exists. If there isn't any dialog attached to the
823 .Ic GtkMenuItem ,
824 it reports
825 .Qq Fa name Ns Ic \&:active Fa label .
826 .El
827 .Ss GtkNotebook
828 .Bl -tag -width "commands "
829 .It Commands
830 .Qq Fa name Ns Ic :set_current_page Fa n
831 switches to zero-based page number
832 .Fa n .
833 .It Feedback
834 none
835 .El
836 .Ss GtkPrintUnixDialog
837 .Bl -tag -width "commands "
838 .It Commands
839 .Qq Fa name Ns Ic :print Fa file.ps
840 opens the print dialog. Pressing the
841 .Qq Print
842 button sends
843 .Fa file.ps
844 to the printer the user selected in the dialog.
845 .It Feedback
846 none
847 .El
848 .Ss GtkProgressBar
849 .Bl -tag -width "commands "
850 .It Commands
851 .Qq Fa name Ns Ic :set_fraction Fa x
852 moves the progress bar to
853 .Fa x
854 .Pq between 0 and 1 .
855 .Pp
856 .Qq Fa name Ns Ic :set_text Bq Fa string
857 replaces the text of the progress bar with
858 .Fa string .
859 Default is the progress percentage.
860 .It Feedback
861 none
862 .El
863 .Ss GtkRadioButton
864 .Bl -tag -width "commands "
865 .It Commands
866 .Qq Fa name Ns Ic :set_active 1
867 switches the button on. All other buttons of the same group will go off
868 automatically.
869 .Pp
870 .Qq Fa name Ns Ic :set_label Fa string
871 replaces the button text with
872 .Fa string .
873 .It Feedback
874 .Qq Fa name Ns Ic \&:1
875 if switched on, or
876 .Qq Fa name Ns Ic \&:0
877 otherwise.
878 .El
879 .Ss GtkScale
880 .Bl -tag -width "commands "
881 .It Commands
882 .Qq Fa name Ns Ic :set_value Fa x
883 moves the slider to value
884 .Fa x .
885 .It Feedback
886 .Qq Fa name Ns Ic \&:value Fa floating_point_text
887 .El
888 .Ss GtkScrolledWindow
889 .Bl -tag -width "commands "
890 .It Commands
891 .Qq Fa name Ns Ic :hscroll Fa position
892 and
893 .Qq Fa name Ns Ic :vscroll Fa position
894 scroll
895 .Fa position
896 to the left or top edge of the
897 .Ic GtkScrolledWindow ,
898 respectively.
899 .Pp
900 .Qq Fa name Ns Ic :hscroll_to_range Fa pos_0 pos_1
901 and
902 .Qq Fa name Ns Ic :vscroll_to_range Fa pos_0 pos_1
903 scroll, if necessary, the range between
904 .Fa pos_0
905 and
906 .Fa pos_1
907 into the
908 .Ic GtkScrolledWindow .
909 If the range is greater than the window, the initial part of the range
910 will be visible.
911 .It Feedback
912 none
913 .El
914 .Ss GtkSocket
915 .Ic GtkSocket
916 may be unsupported by Glade, but its definition can be inserted
917 manually into the GtkBuilder (.ui) file:
918 .Bf -literal
919 \ \ <child>
920 \ \ \ \ <object class="GtkSocket" id="socket1">
921 \ \ \ \ \ \ <property name="visible">True</property>
922 \ \ \ \ \ \ <property name="can_focus">True</property>
923 \ \ \ \ </object>
924 \ \ \ \ <packing>
925 \ \ \ \ \ \ <property name="expand">True</property>
926 \ \ \ \ \ \ <property name="fill">True</property>
927 \ \ \ \ \ \ <property name="position">1</property>
928 \ \ \ \ </packing>
929 \ \ </child>
930 .Ef
931 .Bl -tag -width "commands "
932 .It Commands
933 .Qq Fa name Ns Ic :id
934 requests a feedback message containing the socket
935 .Fa xid .
936 .It Feedback
937 .Qq Fa name Ns Ic :id Fa xid
938 can be used by another process to XEmbed its widgets into the
939 .Ic GtkSocket .
940 .Pp
941 .Qq Fa name Ns Ic :plug-added ,
942 .Qo
943 .Fa name Ns
944 .Ic :plug-removed
945 .Qc .
946 Notification that the other process has inserted its widgets into or
947 removed them from the
948 .Ic GtkSocket .
949 .El
950 .Ss GtkSpinButton
951 .Bl -tag -width "commands "
952 .It Commands
953 .Qq Fa name Ns Ic :set_text Fa string
954 sets the selected value to
955 .Fa string .
956 .It Feedback
957 .Qq Fa name Ns Ic \&:text Fa text
958 .El
959 .Ss GtkSpinner
960 .Bl -tag -width "commands "
961 .It Commands
962 .Qq Fa name Ns Ic :start
963 and
964 .Qq Fa name Ns Ic :stop
965 start and stop the spinner.
966 .It Feedback
967 none
968 .El
969 .Ss GtkStatusbar
970 The context
971 .Fa id
972 parameter is an arbitrary non-negative integer.
973 .Bl -tag -width "commands "
974 .It Commands
975 .Qq Fa name Ns Ic :push_id Fa id string ,
976 .Qq Fa name Ns Ic :push Fa string
977 associate
978 .Fa string
979 with context id
980 .Fa id
981 or 0, respectively, and display it in the statusbar.
982 .Pp
983 .Qq Fa name Ns Ic :pop_id Fa id ,
984 .Qq Fa name Ns Ic :pop
985 remove the latest entry associated with context id
986 .Fa id
987 or 0, respectively, from the statusbar.
988 .Pp
989 .Qq Fa name Ns Ic :remove_all
990 empties the statusbar.
991 .It Feedback
992 none
993 .El
994 .Ss GtkSwitch
995 .Bl -tag -width "commands "
996 .It Commands
997 .Qq Fa name Ns Ic :set_active Brq Ic 0 | 1
998 turns the switch off
999 .Pq Ic 0
1000 or on
1001 .Pq Ic 1 .
1002 .It Feedback
1003 .Qq Fa name Ns Ic \&:1
1004 if switched on, or
1005 .Qq Fa name Ns Ic \&:0
1006 otherwise.
1007 .El
1008 .Ss GtkTextView
1009 There should be a dedicated
1010 .Sx GtkButton
1011 for sending (parts of) the text.
1012 If the name of the
1013 .Ic GtkTextView
1014 is
1015 .Fa foo ,
1016 a
1017 .Sx GtkButton
1018 named
1019 .Fa foo Ns Ic _send_text
1020 will send the content of the
1021 .Ic GtkTextView ;
1022 a
1023 .Sx GtkButton
1024 named
1025 .Fa foo Ns Ic _send_selection
1026 will send the highlighted part the
1027 .Ic GtkTextView .
1028 .Bl -tag -width "commands "
1029 .It Commands
1030 .Qq Fa name Ns Ic :set_text Fa string
1031 replaces the user-editable text with (potentially empty)
1032 .Fa string Ns .
1033 .Pp
1034 .Qq Fa name Ns Ic :delete
1035 deletes the text.
1036 .Pp
1037 .Qq Fa name Ns Ic :insert_at_cursor Fa string
1038 inserts
1039 .Fa string
1040 at cursor position.
1041 .Pp
1042 .Qq Fa name Ns Ic :place_cursor Brq Fa position | Ic end
1043 places the text cursor at
1044 .Fa position
1045 or at the end of the text.
1046 .Pp
1047 .Qq Fa name Ns Ic :place_cursor_at_line Fa line
1048 places the text cursor at the beginning of
1049 .Fa line .
1050 .Pp
1051 .Qq Fa name Ns Ic :scroll_to_cursor
1052 scrolls to the cursor position if necessary.
1053 .Pp
1054 .Qq Fa name Ns Ic :save Fa file
1055 stores in
1056 .Fa file
1057 a
1058 .Nm
1059 command containing the text.
1060 .It Feedback
1061 .Qq Fa button_name Ns Ic :text Fa text ,
1062 .Fa button_name
1063 being the name of the
1064 .Sx GtkButton .
1065 Line endings in
1066 .Fa text
1067 are replaced by
1068 .Ic \en ,
1069 and backslashes are replaced by
1070 .Ic \e\e .
1071 .El
1072 .Ss GtkToggleButton
1073 .Bl -tag -width "commands "
1074 .It Commands
1075 .Qq Fa name Ns Ic :set_active Brq Ic 0 | 1
1076 switches the button off
1077 .Pq Ic 0
1078 or on
1079 .Pq Ic 1 .
1080 .Pp
1081 .Qq Fa name Ns Ic :set_label Fa string
1082 replaces the button text with
1083 .Fa string .
1084 .It Feedback
1085 .Qq Fa name Ns Ic \&:1
1086 if switched on, or
1087 .Qq Fa name Ns Ic \&:0
1088 otherwise.
1089 .El
1090 .Ss GtkTreeView
1091 .Nm
1092 can deal with columns of type
1093 .Ic gboolean , gint , guint , glong , gulong , gint64 , guint64 , gfloat , gdouble ,
1094 and
1095 .Ic gchararray .
1096 .Pp
1097 .Fa row
1098 and
1099 .Fa column
1100 refer to the underlying model
1101 .Ic ( GtkListStore
1102 or
1103 .Ic GtkTreeStore ) .
1104 .Fa row
1105 is a sequence of one or more colon-separated integers, e.g.
1106 .Qq 3
1107 or
1108 .Qq 0:0:1 .
1109 .Bl -tag -width "commands "
1110 .It Commands
1111 .Qq Fa name Ns Ic :set Fa row column data
1112 replaces the content at
1113 .Pq Fa row , column
1114 with
1115 .Fa data
1116 (which should be compatible with the type of
1117 .Fa column ) .
1118 If necessary, new tree nodes are created to obtain the minimal tree
1119 structure needed to support
1120 .Fa row .
1121 .Pp
1122 .Qq Fa name Ns Ic :insert_row Brq Fa row Bo Ic as_child Bc | Ic end
1123 inserts a new, empty row; either as a sibling of
1124 .Fa row
1125 at position
1126 .Fa row ,
1127 or as a child of
1128 .Fa row ,
1129 or at the end of the list, respectively.
1130 .Pp
1131 .Qq Fa name Ns Ic :move_row Fa origin Brq Fa destination | Ic end
1132 moves the row at
1133 .Fa origin
1134 within its current level to
1135 .Fa destination
1136 or to the end.
1137 .Pp
1138 .Qq Fa name Ns Ic :remove_row Fa row
1139 removes the row at position
1140 .Fa row .
1141 .Pp
1142 .Qq Fa name Ns Ic :clear
1143 removes all rows.
1144 .Pp
1145 .Qq Fa name Ns Ic :expand Fa row
1146 expands one level of the subtree below
1147 .Fa row .
1148 .Pp
1149 .Qq Fa name Ns Ic :expand_all Bq Fa row
1150 expands the subtree below
1151 .Fa row ,
1152 or the whole tree.
1153 .Pp
1154 .Qq Fa name Ns Ic :collapse Bq Fa row
1155 collapses the subtree below
1156 .Fa row ,
1157 or the whole tree.
1158 .Pp
1159 .Qq Fa name Ns Ic :set_cursor Bq Fa row
1160 sets the cursor to
1161 .Fa row ,
1162 or unsets it.
1163 .Pp
1164 .Qq Fa name Ns Ic :scroll Fa row column
1165 scrolls the cell at
1166 .Pq Fa row , column
1167 into view.
1168 .Pp
1169 .Qq Fa name Ns Ic :save Fa file
1170 stores the content of the underlying model as a sequence of
1171 .Nm
1172 commands into
1173 .Fa file .
1174 .It Feedback
1175 .Qq Fa name Ns Ic \&:clicked
1176 .Pp
1177 .Qq Fa name Ns Ic \&: Ns Fa column_type row column value ,
1178 one message per cell in the underlying model for each selected row; or
1179 .Pp
1180 .Qq Fa name Ns Ic \&: Ns Fa column_type row column new_value ,
1181 if the cell at
1182 .Pq Fa row , column
1183 has been edited.
1184 .El
1185 .Ss GtkTreeViewColumn
1186 .Bl -tag -width "commands "
1187 .It Commands
1188 none
1189 .It Feedback
1190 .Qq Fa name Ns Ic \&:clicked
1191 .El
1192 .Ss GtkWindow
1193 .Bl -tag -width "commands "
1194 .It Commands
1195 .Qq Fa name Ns Ic :set_title Fa string
1196 replaces the text in the title bar with
1197 .Fa string .
1198 .Pp
1199 .Qq Fa name Ns Ic :resize Bq Fa width height
1200 changes the window size to
1201 .Fa width
1202 x
1203 .Fa height
1204 pixels if specified, or to the default size.
1205 .Pp
1206 .Qq Fa name Ns Ic :move Fa x y
1207 moves the window to position
1208 .Fa x , y .
1209 .Pp
1210 .Qq Fa name Ns Ic :fullscreen
1211 and
1212 .Qq Fa name Ns Ic :unfullscreen
1213 switch fullscreen mode on and off.
1214 .It Feedback
1215 none
1216 .El
1217 .Sh EXAMPLES
1218 .Ss Discovering Pipeglade Interactively
1219 Suppose the interface in
1220 .Pa ./pipeglade.ui
1221 has a
1222 .Sx GtkLabel Li label1
1223 and a
1224 .Sx GtkButton Li button1 .
1225 After invoking
1226 .Dl pipeglade
1227 and clicking the
1228 .Sx GtkButton , Qq button1:clicked
1229 will be reported on the terminal. Typing
1230 .Dl label1:set_text Button Label
1231 will change the text shown on the label into
1232 .Qq Button Label .
1233 .Ss One-Shot File Dialog
1234 Suppose the interface in
1235 .Pa ./simple_open.ui
1236 contains a
1237 .Sx GtkFileChooserDialog
1238 with an
1239 .Sq OK
1240 .Sx GtkButton
1241 named
1242 .Li main_ok .
1243 Invoking
1244 .Dl pipeglade -u simple_open.ui
1245 will open the dialog; pressing
1246 .Sq OK
1247 will close it after sending the selected filename to
1248 .Va stdout .
1249 .Ss One-Shot User Notification
1250 If the interface in
1251 .Pa ./simple_dialog.ui
1252 contains a
1253 .Sx GtkLabel Li label1 ,
1254 then
1255 .Dl pipeglade -u simple_dialog.ui <<< \e
1256 .Dl \ \ \ \ \&"label1:set_text NOW READ THIS!\&"
1257 will set the label text accordingly and wait for user input.
1258 .Ss Continuous Input
1259 The following shell command displays a running clock:
1260 .Dl while true; do
1261 .Dl \ \ \ \ echo \&"label1:set_text `date`\&";
1262 .Dl \ \ \ \ sleep 1;
1263 .Dl done | pipeglade -u simple_dialog.ui
1264 .Ss Continuous Input and Output
1265 The following shell script fragment sets up
1266 .Nm
1267 for continuous communication with another program,
1268 .Li main_prog :
1269 .Dl pipeglade -i in.fifo -o out.fifo &
1270 .Dl # wait for in.fifo and out.fifo to appear
1271 .Dl while test \& ! \e( -e in.fifo -a -e out.fifo \e); do :; done
1272 .Dl main_prog <out.fifo >in.fifo
1273 .Sh EXIT STATUS
1274 .Nm
1275 exits 0 on success, and >0 if an error occurs.
1276 .Sh SEE ALSO
1277 .Xr glade 1 ,
1278 .Xr dialog 1 ,
1279 .Xr gxmessage 1 ,
1280 .Xr kdialog 1 ,
1281 .Xr whiptail 1 ,
1282 .Xr xmessage 1 ,
1283 .Xr zenity 1
1284 .Sh AUTHOR
1285 .Nm
1286 was written by
1287 .An Bert Burgemeister Aq trebbu@googlemail.com .
1288 .Sh BUGS
1289 Please report them to the author.