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