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