pipeglade.1

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