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 24, 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 If there is no current point, the curve will start at
 577 .Pq Ar x1 , y1 .
 578 .Pp
 579 .Qq Ar name Ns Cm :fill Ar id
 580 fills the current path and clears it.
 581 .Pp
 582 .Qq Ar name Ns Cm :fill_preserve Ar id
 583 fills the current path without clearing it.
 584 .Pp
 585 .Qq Ar name Ns Cm :line_to Ar id x y
 586 adds a line from the current point to
 587 .Pq Ar x , y ,
 588 or creates a new current point at
 589 .Pq Ar x , y .
 590 .Pp
 591 .Qq Ar name Ns Cm :move_to Ar id x y
 592 sets the current point to
 593 .Pq Ar x , y .
 594 .Pp
 595 .Qq Ar name Ns Cm :rectangle Ar id x y width height
 596 adds a rectangle to the current path.
 597 The top left corner is at
 598 .Pq Ar x , y .
 599 .Pp
 600 .Qq Ar name Ns Cm :refresh
 601 redraws the
 602 .Cm GtkDrawingArea
 603 .Ar name .
 604 .Pp
 605 .Qq Ar name Ns Cm :rel_curve_to Ar id dx1 dy1 dx2 dy2 dx3 dy3
 606 adds a cubic Bezier spline from the current point to
 607 .Pq Ar dx3 , dy3 ,
 608 using
 609 .Pq Ar dx1 , dy1
 610 and
 611 .Pq Ar dx2 , dy2
 612 as control points.
 613 All coordinates are offsets relative to the current point.
 614 .Pp
 615 .Qq Ar name Ns Cm :rel_line_to Ar id dx dy
 616 adds a line from the current point to a point offset from there by
 617 .Pq Ar dx , dy .
 618 .Pp
 619 .Qo Ar name Ns Cm :rel_move_for Ar id Brq Cm c | e | n | ne | nw | s | se | sw | w
 620 .Ar text
 621 .Qc
 622 moves the current point such that
 623 .Qq Ar name Ns Cm :show_text Ar id text
 624 will place the specified reference point of
 625 .Ar text
 626 on the original current point.
 627 .Pp
 628 .Qq Ar name Ns Cm :rel_move_to Ar id dx dy
 629 moves the current point by
 630 .Pq Ar dx , dy .
 631 .Pp
 632 .Qq Ar name Ns Cm :remove Ar id
 633 removes the elements with
 634 .Ar id
 635 from the
 636 .Cm GtkDrawingArea Ar name .
 637 .Pp
 638 .Qq Ar name Ns Cm :set_dash Ar id l
 639 sets the dash pattern to
 640 .Ar l
 641 on,
 642 .Ar l
 643 off.
 644 .Pp
 645 .Qq Ar name Ns Cm :set_dash Ar id l1on l1off l2on l2off ...
 646 resets the dash pattern to a line with arbitrary on/off portions.
 647 .Pp
 648 .Qq Ar name Ns Cm :set_dash Ar id
 649 resets the dash pattern to a solid line.
 650 .Pp
 651 .Qo Ar name Ns Cm :set_font_family Ar id Brq Cm normal | italic | oblique
 652 .Brq Cm normal | bold
 653 .Bq Cm family
 654 .Qc
 655 sets the font face for subsequent calls of
 656 .Ar name Ns Cm :show_text .
 657 .Pp
 658 .Qq Ar name Ns Cm :set_font_size Ar id size
 659 sets the font size for subsequent calls of
 660 .Ar name Ns Cm :show_text .
 661 .Pp
 662 .Qq Ar name Ns Cm :set_line_cap Ar id Brq Cm butt | round | square
 663 sets the line cap style.
 664 .Pp
 665 .Qq Ar name Ns Cm :set_line_join Ar id Brq Cm miter | round | bevel
 666 sets the line junction style.
 667 .Pp
 668 .Qq Ar name Ns Cm :set_line_width Ar id width
 669 sets the line width.
 670 .Pp
 671 .Qq Ar name Ns Cm :set_source_rgba Ar id color
 672 sets the color.
 673 .Ar color
 674 is in the format used with
 675 .Sx GtkColorButton .
 676 .Pp
 677 .Qq Ar name Ns Cm :show_text Ar id text
 678 writes
 679 .Ar text ,
 680 beginning at the current point.
 681 .Pp
 682 .Qq Ar name Ns Cm :stroke Ar id
 683 strokes the current path and clears it.
 684 .Pp
 685 .Qq Ar name Ns Cm :stroke_preserve Ar id
 686 strokes the current path without clearing it.
 687 .It Feedback
 688 none
 689 .El
 690 .Ss GtkEntry
 691 .Bl -tag -width "commands "
 692 .It Commands
 693 .Qq Ar name Ns Cm :set_text Ar string
 694 replaces the user-editable text with
 695 .Ar string .
 696 .Pp
 697 .Qq Ar name Ns Cm :set_placeholder_text Ar string
 698 sets the
 699 .Ar string
 700 that is displayed when the entry is empty and unfocused.
 701 .It Feedback
 702 .Qq Ar name Ns Cm \&:text Ar text ,
 703 once for each change of
 704 .Ar text .
 705 .El
 706 .Ss GtkEventBox
 707 .Ar x , y
 708 are mouse pointer coordinates relative to the
 709 .Cm GtkEventBox .
 710 .Bl -tag -width "commands "
 711 .It Commands
 712 none
 713 .It Feedback
 714 .Qq Ar name Ns Cm \&:button_press Ar b x y ,
 715 .Qq Ar name Ns Cm \&:button_release Ar b x y
 716 where
 717 .Ar b
 718 is the mouse button (normally 1, 2, or 3 for the left, middle, and
 719 right button; others may exist).
 720 .Pp
 721 .Qq Ar name Ns Cm \&:motion Ar x y
 722 is reported repeatedly while the mouse is being moved with a button
 723 pressed.
 724 .Pp
 725 .Qq Ar name Ns Cm \&:key_press Ar key ,
 726 .Ar key
 727 being the key's name
 728 .Po e.g.
 729 .Ql Control_L ,
 730 .Ql Tab ,
 731 .Ql a
 732 .Pc .
 733 .El
 734 .Ss GtkExpander
 735 .Bl -tag -width "commands "
 736 .It Commands
 737 .Qq Ar name Ns Cm :set_label Ar string
 738 replaces the expander label text with
 739 .Ar string .
 740 .Pp
 741 .Qq Ar name Ns Cm :set_expanded Brq Cm 0 |  1
 742 hides
 743 .Pq Cm 0
 744 the child widget, or makes it visible
 745 .Pq Cm 1 .
 746 .It Feedback
 747 none
 748 .El
 749 .Ss GtkFileChooserButton
 750 .Bl -tag -width "commands "
 751 .It Commands
 752 .Qq Ar name Ns Cm :set_filename Ar path
 753 preselects
 754 .Ar path
 755 to the extent it exists.
 756 .It Feedback
 757 .Qq Ar name Ns Cm \&:file Ar pathname
 758 if the selection has changed.
 759 .El
 760 .Ss GtkFileChooserDialog
 761 A
 762 .Cm GtkFileChooserDialog
 763 that is named
 764 .Ar foo
 765 will be invoked by a
 766 .Sx GtkMenuItem
 767 or a
 768 .Sx GtkImageMenuItem
 769 that is named
 770 .Ar foo Ns Cm _invoke .
 771 .Pp
 772 The
 773 .Cm GtkFileChooserDialog
 774 should have an
 775 .Sq OK
 776 .Sx GtkButton
 777 named
 778 .Ar foo Ns Cm _ok
 779 .Po Cm main_ok
 780 if the dialog is the sole window of the GUI and therefore named
 781 .Cm main
 782 .Pc .
 783 .Pp
 784 The
 785 .Cm GtkFileChooserDialog
 786 may have a
 787 .Sq Cancel
 788 .Sx GtkButton
 789 named
 790 .Ar foo Ns Cm _cancel
 791 .Po Cm main_cancel
 792 if the dialog is the sole window of the GUI and therefore named
 793 .Cm main
 794 .Pc .
 795 .Pp
 796 The
 797 .Cm GtkFileChooserDialog
 798 may have an
 799 .Sq Apply
 800 .Sx GtkButton
 801 named
 802 .Ar foo Ns Cm _apply
 803 .Po Cm main_apply
 804 if the dialog is the sole window of the GUI and therefore named
 805 .Cm main
 806 .Pc .
 807 .Bl -tag -width "commands "
 808 .It Commands
 809 .Qq Ar name Ns Cm :set_filename Ar path
 810 preselects
 811 .Ar path
 812 to the extent it exists.
 813 .Pp
 814 .Qq Ar name Ns Cm :set_current_name Ar string
 815 makes
 816 .Ar string
 817 the suggested filename, which may not yet exist.
 818 .Ar string
 819 should either resemble an absolute path, or the
 820 .Ar directory
 821 must be set separately by
 822 .Ar name Ns Cm :set_filename Ar directory .
 823 .Pp
 824 .Qq Ar name Ns Cm :set_title Ar string
 825 replaces the text in the title bar with
 826 .Ar string .
 827 .Pp
 828 .Qq Ar name Ns Cm :resize Bq Ar width height
 829 changes the size of the dialog window to
 830 .Ar width
 831 x
 832 .Ar height
 833 pixels if specified, or to the default size.
 834 .Pp
 835 .Qq Ar name Ns Cm :move Ar x y
 836 moves the dialog window to position
 837 .Ar x , y .
 838 .Pp
 839 .Qq Ar name Ns Cm :fullscreen
 840 and
 841 .Qq Ar name Ns Cm :unfullscreen
 842 switch fullscreen mode on and off.
 843 .It Feedback
 844 .Qq Ar name Ns Cm :file Ar pathname
 845 and/or
 846 .Qq Ar name Ns Cm :folder Ar pathname
 847 .Pp
 848 .Qq Ar name Ns Cm \&:closed
 849 if the
 850 .Cm GtkFileChooserDialog
 851 window was closed by the window manager.
 852 .El
 853 .Ss GtkFontButton
 854 .Bl -tag -width "commands "
 855 .It Commands
 856 .Qq Ar name Ns Cm :set_font_name Ar fontname
 857 preselects the font.
 858 .It Feedback
 859 .Qq Ar name Ns Cm \&:font Ar fontname
 860 .El
 861 .Ss GtkFrame
 862 .Bl -tag -width "commands "
 863 .It Commands
 864 .Qq Ar name Ns Cm :set_label Ar text
 865 replaces the frame label text with
 866 .Ar string .
 867 .It Feedback
 868 none
 869 .El
 870 .Ss GtkImage
 871 .Bl -tag -width "commands "
 872 .It Commands
 873 .Qq Ar name Ns Cm :set_from_icon_name Ar icon-name
 874 replaces the image with one of the standard icons.
 875 .Pp
 876 .Qq Ar name Ns Cm :set_from_file Ar path
 877 replaces the image by the one found at
 878 .Ar path Ns .
 879 .It Feedback
 880 none
 881 .El
 882 .Ss GtkLabel
 883 .Bl -tag -width "commands "
 884 .It Commands
 885 .Qq Ar name Ns Cm :set_text Ar string
 886 replaces the label text with
 887 .Ar string .
 888 .It Feedback
 889 none
 890 .El
 891 .Ss GtkMenuItem, GtkImageMenuItem
 892 .Bl -tag -width "commands "
 893 .It Commands
 894 none
 895 .It Feedback
 896 A
 897 .Cm GtkMenuItem
 898 or
 899 .Cm GtkImageMenuItem
 900 with the name
 901 .Ar foo Ns Cm _invoke
 902 will invoke the
 903 .Sx GtkDialog
 904 or
 905 .Sx GtkFileChooserDialog
 906 named
 907 .Ar foo
 908 if it exists.
 909 If there isn't any dialog attached to the
 910 .Cm GtkMenuItem ,
 911 it reports
 912 .Qq Ar name Ns Cm \&:active Ar label .
 913 .El
 914 .Ss GtkNotebook
 915 .Bl -tag -width "commands "
 916 .It Commands
 917 .Qq Ar name Ns Cm :set_current_page Ar n
 918 switches to zero-based page number
 919 .Ar n .
 920 .It Feedback
 921 none
 922 .El
 923 .Ss GtkPrintUnixDialog
 924 .Bl -tag -width "commands "
 925 .It Commands
 926 .Qq Ar name Ns Cm :print Ar file.ps
 927 opens the print dialog.
 928 Pressing the
 929 .Ql Print
 930 button sends
 931 .Ar file.ps
 932 to the printer the user selected in the dialog.
 933 .It Feedback
 934 .Qq Ar name Ns Cm \&:closed
 935 if the
 936 .Cm GtkPrintUnixDialog
 937 window was closed by the window manager.
 938 .El
 939 .Ss GtkProgressBar
 940 .Bl -tag -width "commands "
 941 .It Commands
 942 .Qq Ar name Ns Cm :set_fraction Ar x
 943 moves the progress bar to
 944 .Ar x
 945 .Pq between 0 and 1 .
 946 .Pp
 947 .Qq Ar name Ns Cm :set_text Bq Ar string
 948 replaces the text of the progress bar with
 949 .Ar string .
 950 Default is the progress percentage.
 951 .It Feedback
 952 none
 953 .El
 954 .Ss GtkRadioButton
 955 .Bl -tag -width "commands "
 956 .It Commands
 957 .Qq Ar name Ns Cm :set_active 1
 958 switches the button on.
 959 All other buttons of the same group will go off automatically.
 960 .Pp
 961 .Qq Ar name Ns Cm :set_label Ar string
 962 replaces the button text with
 963 .Ar string .
 964 .It Feedback
 965 .Qq Ar name Ns Cm \&:1
 966 if switched on, or
 967 .Qq Ar name Ns Cm \&:0
 968 otherwise.
 969 .El
 970 .Ss GtkScale
 971 .Bl -tag -width "commands "
 972 .It Commands
 973 .Qq Ar name Ns Cm :set_value Ar x
 974 moves the slider to value
 975 .Ar x .
 976 .It Feedback
 977 .Qq Ar name Ns Cm \&:value Ar floating_point_text
 978 .El
 979 .Ss GtkScrolledWindow
 980 .Bl -tag -width "commands "
 981 .It Commands
 982 .Qq Ar name Ns Cm :hscroll Ar position
 983 and
 984 .Qq Ar name Ns Cm :vscroll Ar position
 985 scroll
 986 .Ar position
 987 to the left or top edge of the
 988 .Cm GtkScrolledWindow ,
 989 respectively.
 990 .Pp
 991 .Qq Ar name Ns Cm :hscroll_to_range Ar pos_0 pos_1
 992 and
 993 .Qq Ar name Ns Cm :vscroll_to_range Ar pos_0 pos_1
 994 scroll, if necessary, the range between
 995 .Ar pos_0
 996 and
 997 .Ar pos_1
 998 into the
 999 .Cm GtkScrolledWindow .
1000 If the range is greater than the window, the initial part of the range
1001 will be visible.
1002 .It Feedback
1003 none
1004 .El
1005 .Ss GtkSocket
1006 .Cm GtkSocket
1007 may be unsupported by Glade, but its definition can be inserted
1008 manually into the GtkBuilder
1009 .Pq Pa .ui
1010 file:
1011 .Bd -literal -offset indent
1012 <child>
1013   <object class="GtkSocket" id="socket1">
1014     <property name="visible">True</property>
1015     <property name="can_focus">True</property>
1016   </object>
1017   <packing>
1018     <property name="expand">True</property>
1019     <property name="fill">True</property>
1020     <property name="position">1</property>
1021   </packing>
1022 </child>
1023 .Ed
1024 .Bl -tag -width "commands "
1025 .It Commands
1026 .Qq Ar name Ns Cm :id
1027 requests a feedback message containing the socket
1028 .Ar xid .
1029 .It Feedback
1030 .Qq Ar name Ns Cm :id Ar xid
1031 can be used by another process to XEmbed its widgets into the
1032 .Cm GtkSocket .
1033 .Pp
1034 .Qq Ar name Ns Cm :plug-added ,
1035 .Qo
1036 .Ar name Ns
1037 .Cm :plug-removed
1038 .Qc .
1039 Notification that the other process has inserted its widgets into or
1040 removed them from the
1041 .Cm GtkSocket .
1042 .El
1043 .Ss GtkSpinButton
1044 .Bl -tag -width "commands "
1045 .It Commands
1046 .Qq Ar name Ns Cm :set_text Ar string
1047 sets the selected value to
1048 .Ar string .
1049 .It Feedback
1050 .Qq Ar name Ns Cm \&:text Ar text
1051 .El
1052 .Ss GtkSpinner
1053 .Bl -tag -width "commands "
1054 .It Commands
1055 .Qq Ar name Ns Cm :start
1056 and
1057 .Qq Ar name Ns Cm :stop
1058 start and stop the spinner.
1059 .It Feedback
1060 none
1061 .El
1062 .Ss GtkStatusbar
1063 The context
1064 .Ar id
1065 parameter is an arbitrary non-whitespace string.
1066 .Bl -tag -width "commands "
1067 .It Commands
1068 .Qq Ar name Ns Cm :push_id Ar id string ,
1069 .Qq Ar name Ns Cm :push Ar string
1070 associate
1071 .Ar string
1072 with context id
1073 .Ar id
1074 or
1075 .Ql 0 ,
1076 respectively, and display it in the statusbar.
1077 .Pp
1078 .Qq Ar name Ns Cm :pop_id Ar id ,
1079 .Qq Ar name Ns Cm :pop
1080 remove the latest entry associated with context id
1081 .Ar id
1082 or
1083 .Ql 0 ,
1084 respectively, from the statusbar.
1085 .Pp
1086 .Qq Ar name Ns Cm :remove_all_id Ar id ,
1087 .Qq Ar name Ns Cm :remove_all
1088 remove the entries associated with context id
1089 .Ar id
1090 or
1091 .Ql 0 ,
1092 respectively, from the statusbar.
1093 .It Feedback
1094 none
1095 .El
1096 .Ss GtkSwitch
1097 .Bl -tag -width "commands "
1098 .It Commands
1099 .Qq Ar name Ns Cm :set_active Brq Cm 0 | 1
1100 turns the switch off
1101 .Pq Cm 0
1102 or on
1103 .Pq Cm 1 .
1104 .It Feedback
1105 .Qq Ar name Ns Cm \&:1
1106 if switched on, or
1107 .Qq Ar name Ns Cm \&:0
1108 otherwise.
1109 .El
1110 .Ss GtkTextView
1111 There should be a dedicated
1112 .Sx GtkButton
1113 for sending (parts of) the text.
1114 If the name of the
1115 .Cm GtkTextView
1116 is
1117 .Ar foo ,
1118 a
1119 .Sx GtkButton
1120 named
1121 .Ar foo Ns Cm _send_text
1122 will send the content of the
1123 .Cm GtkTextView ;
1124 a
1125 .Sx GtkButton
1126 named
1127 .Ar foo Ns Cm _send_selection
1128 will send the highlighted part the
1129 .Cm GtkTextView .
1130 .Bl -tag -width "commands "
1131 .It Commands
1132 .Qq Ar name Ns Cm :set_text Ar string
1133 replaces the user-editable text with (potentially empty)
1134 .Ar string Ns .
1135 .Pp
1136 .Qq Ar name Ns Cm :delete
1137 deletes the text.
1138 .Pp
1139 .Qq Ar name Ns Cm :insert_at_cursor Ar string
1140 inserts
1141 .Ar string
1142 at cursor position.
1143 .Pp
1144 .Qq Ar name Ns Cm :place_cursor Brq Ar position | Cm end
1145 places the text cursor at
1146 .Ar position
1147 or at the end of the text.
1148 .Pp
1149 .Qq Ar name Ns Cm :place_cursor_at_line Ar line
1150 places the text cursor at the beginning of
1151 .Ar line .
1152 .Pp
1153 .Qq Ar name Ns Cm :scroll_to_cursor
1154 scrolls to the cursor position if necessary.
1155 .Pp
1156 .Qq Ar name Ns Cm :save Ar file
1157 stores in
1158 .Ar file
1159 a
1160 .Nm
1161 command containing the text.
1162 .It Feedback
1163 .Qq Ar button_name Ns Cm :text Ar text ,
1164 .Ar button_name
1165 being the name of the
1166 .Sx GtkButton .
1167 Line endings in
1168 .Ar text
1169 are replaced by
1170 .Cm \en ,
1171 and backslashes are replaced by
1172 .Cm \e\e .
1173 .El
1174 .Ss GtkToggleButton
1175 .Bl -tag -width "commands "
1176 .It Commands
1177 .Qq Ar name Ns Cm :set_active Brq Cm 0 | 1
1178 switches the button off
1179 .Pq Cm 0
1180 or on
1181 .Pq Cm 1 .
1182 .Pp
1183 .Qq Ar name Ns Cm :set_label Ar string
1184 replaces the button text with
1185 .Ar string .
1186 .It Feedback
1187 .Qq Ar name Ns Cm \&:1
1188 if switched on, or
1189 .Qq Ar name Ns Cm \&:0
1190 otherwise.
1191 .El
1192 .Ss GtkTreeView
1193 .Nm
1194 can deal with columns of type
1195 .Cm gboolean , gint , guint , glong , gulong , gint64 , guint64 , gfloat , gdouble ,
1196 and
1197 .Cm gchararray .
1198 .Pp
1199 .Ar row
1200 and
1201 .Ar column
1202 refer to the underlying model
1203 .Cm ( GtkListStore
1204 or
1205 .Cm GtkTreeStore ) .
1206 .Ar row
1207 is a sequence of one or more colon-separated integers, e.g.
1208 .Ql 3
1209 or
1210 .Ql 0:0:1 .
1211 .Bl -tag -width "commands "
1212 .It Commands
1213 .Qq Ar name Ns Cm :set Ar row column data
1214 replaces the content at
1215 .Pq Ar row , column
1216 with
1217 .Ar data
1218 (which should be compatible with the type of
1219 .Ar column ) .
1220 If necessary, new tree nodes are created to obtain the minimal tree
1221 structure needed to support
1222 .Ar row .
1223 .Pp
1224 .Qq Ar name Ns Cm :insert_row Brq Ar row Bo Cm as_child Bc | Cm end
1225 inserts a new, empty row; either as a sibling of
1226 .Ar row
1227 at position
1228 .Ar row ,
1229 or as a child of
1230 .Ar row ,
1231 or at the end of the list, respectively.
1232 .Pp
1233 .Qq Ar name Ns Cm :move_row Ar origin Brq Ar destination | Cm end
1234 moves the row at
1235 .Ar origin
1236 within its current level to
1237 .Ar destination
1238 or to the end.
1239 .Pp
1240 .Qq Ar name Ns Cm :remove_row Ar row
1241 removes the row at position
1242 .Ar row .
1243 .Pp
1244 .Qq Ar name Ns Cm :clear
1245 removes all rows.
1246 .Pp
1247 .Qq Ar name Ns Cm :expand Ar row
1248 expands one level of the subtree below
1249 .Ar row .
1250 .Pp
1251 .Qq Ar name Ns Cm :expand_all Bq Ar row
1252 expands the subtree below
1253 .Ar row ,
1254 or the whole tree.
1255 .Pp
1256 .Qq Ar name Ns Cm :collapse Bq Ar row
1257 collapses the subtree below
1258 .Ar row ,
1259 or the whole tree.
1260 .Pp
1261 .Qq Ar name Ns Cm :set_cursor Bq Ar row
1262 sets the cursor to
1263 .Ar row ,
1264 or unsets it.
1265 .Pp
1266 .Qq Ar name Ns Cm :scroll Ar row column
1267 scrolls the cell at
1268 .Pq Ar row , column
1269 into view.
1270 .Pp
1271 .Qq Ar name Ns Cm :save Ar file
1272 stores the content of the underlying model as a sequence of
1273 .Nm
1274 commands into
1275 .Ar file .
1276 .It Feedback
1277 .Qq Ar name Ns Cm \&:clicked
1278 .Pp
1279 .Qq Ar name Ns Cm \&: Ns Ar column_type row column value ,
1280 one message per cell in the underlying model for each selected row; or
1281 .Pp
1282 .Qq Ar name Ns Cm \&: Ns Ar column_type row column new_value ,
1283 if the cell at
1284 .Pq Ar row , column
1285 has been edited.
1286 .El
1287 .Ss GtkTreeViewColumn
1288 .Bl -tag -width "commands "
1289 .It Commands
1290 none
1291 .It Feedback
1292 .Qq Ar name Ns Cm \&:clicked
1293 .El
1294 .Ss GtkWindow
1295 .Bl -tag -width "commands "
1296 .It Commands
1297 .Qq Ar name Ns Cm :set_title Ar string
1298 replaces the text in the title bar with
1299 .Ar string .
1300 .Pp
1301 .Qq Ar name Ns Cm :resize Bq Ar width height
1302 changes the window size to
1303 .Ar width
1304 x
1305 .Ar height
1306 pixels if specified, or to the default size.
1307 .Pp
1308 .Qq Ar name Ns Cm :move Ar x y
1309 moves the window to position
1310 .Ar x , y .
1311 .Pp
1312 .Qq Ar name Ns Cm :fullscreen
1313 and
1314 .Qq Ar name Ns Cm :unfullscreen
1315 switch fullscreen mode on and off.
1316 .It Feedback
1317 .Qq Ar name Ns Cm \&:closed
1318 if the
1319 .Cm GtkWindow
1320 was closed by the window manager.
1321 .El
1322 .Sh EXIT STATUS
1323 .Ex -std
1324 .Sh EXAMPLES
1325 .Ss Discovering Pipeglade Interactively
1326 Suppose the interface in
1327 .Pa ./pipeglade.ui
1328 has a
1329 .Sx GtkLabel Ql label1
1330 and a
1331 .Sx GtkButton Ql button1 .
1332 After invoking
1333 .Pp
1334 .Dl pipeglade
1335 .Pp
1336 and clicking the
1337 .Sx GtkButton , Ql button1:clicked
1338 will be reported on the terminal.
1339 Typing
1340 .Pp
1341 .Dl label1:set_text Button Label
1342 .Pp
1343 will change the text shown on the label into
1344 .Ql Button Label .
1345 .Ss One-Shot File Dialog
1346 Suppose the interface in
1347 .Pa ./simple_open.ui
1348 contains a
1349 .Sx GtkFileChooserDialog
1350 with an
1351 .Sq OK
1352 .Sx GtkButton
1353 named
1354 .Ql main_ok .
1355 Invoking
1356 .Pp
1357 .Dl pipeglade -u simple_open.ui
1358 .Pp
1359 will open the dialog; pressing
1360 .Sq OK
1361 will close it after sending the selected filename to
1362 .Va stdout .
1363 .Ss One-Shot User Notification
1364 If the interface in
1365 .Pa ./simple_dialog.ui
1366 contains a
1367 .Sx GtkLabel Ql label1 ,
1368 then
1369 .Bd -literal -offset indent
1370 pipeglade -u simple_dialog.ui <<< \e
1371     "label1:set_text NOW READ THIS!"
1372 .Ed
1373 will set the label text accordingly and wait for user input.
1374 .Ss Continuous Input
1375 The following shell command displays a running clock:
1376 .Bd -literal -offset indent
1377 while true; do
1378     echo "label1:set_text `date`";
1379     sleep 1;
1380 done | pipeglade -u simple_dialog.ui
1381 .Ed
1382 .Ss Continuous Input and Output
1383 The following shell script fragment sets up
1384 .Nm
1385 for continuous communication with another program,
1386 .Pa main_prog :
1387 .Bd -literal -offset indent
1388 pipeglade -i in.fifo -o out.fifo &
1389 # wait for in.fifo and out.fifo to appear
1390 while test ! \e( -e in.fifo -a -e out.fifo \e); do :; done
1391 main_prog <out.fifo >in.fifo
1392 .Ed
1393 .Sh SEE ALSO
1394 .Xr dialog 1 ,
1395 .Xr glade 1 ,
1396 .Xr gxmessage 1 ,
1397 .Xr kdialog 1 ,
1398 .Xr whiptail 1 ,
1399 .Xr xmessage 1 ,
1400 .Xr zenity 1
1401 .Sh AUTHOR
1402 .Nm
1403 was written by
1404 .An Bert Burgemeister
1405 .Aq Mt trebbu@googlemail.com .
1406 .Sh BUGS
1407 Due to what appears to be a bug in cairo v1.14.0,
1408 .Nm
1409 used with this library version occasionally crashes on
1410 .Cm GtkDrawingArea
1411 commands.