Add support for GtkSocket

[pipeglade.git] / pipeglade.1

.\" Copyright (c) 2014, 2015 Bert Burgemeister <trebbu@googlemail.com>
.\"
.\" Permission is hereby granted, free of charge, to any person obtaining
.\" a copy of this software and associated documentation files (the
.\" "Software"), to deal in the Software without restriction, including
.\" without limitation the rights to use, copy, modify, merge, publish,
.\" distribute, sublicense, and/or sell copies of the Software, and to
.\" permit persons to whom the Software is furnished to do so, subject to
.\" the following conditions:
.\"
.\" The above copyright notice and this permission notice shall be
.\" included in all copies or substantial portions of the Software.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
.\" EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
.\" NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
.\" LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
.\" OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
.\" WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
.\"
.Dd September 23, 2015
.Dt PIPEGLADE 1 CON
.Os BSD
.Sh NAME
.Nm pipeglade
.Nd Pipe-Driven GTK+ Interface
.Sh SYNOPSIS
.Nm
.Op Fl h
.Op Fl G
.Op Fl V
.Nm
.Op Fl i Ar in-fifo
.Op Fl o Ar out-fifo
.Op Fl u Ar builder-file
.Sh DESCRIPTION
.Nm
is a helper program that displays graphical user
interfaces for other programs.  It renders the GUI definition
found in a GtkBuilder XML file (created using the
.Xr glade 1
interface designer), and communicates with the main program solely
through plain text messages via pipes or fifos.  It provides access to
a subset of features of a subset of widgets of GTK+ 3.  Simple
one-shot dialogs as well as more complex, long-running programs can be
built using
.Nm ;
see
.Sx EXAMPLES .
.Sh OPTIONS
.Bl -tag -width Ds
.It Fl h
Prints a help message and exits.
.It Fl i Ar in-fifo
Creates a named pipe
.Ar in-fifo
if necessary, and uses it for command input.
.Pp
A command is a line of text.  Its format is
.Qo
.Fa name Ns
.Ic \&: Ns
.Fa action
.Bq Fa data
.Qc
where
.Fa name
is the name of the receiving widget;
.Fa data
is separated from the rest of the command by a single whitespace
character.  Commands whose first non-whitespace character is
.Ic #
are considered comments and ignored.
Any occurences of the two-character sequences
.Ic \en
and
.Ic \er
will be converted into newline or carriage return, respectively.
Every other character following a backslash will be left unchanged,
but the backslash will be removed.  Invalid commands are reported on
.Va stderr
and are otherwise ignored.  See
.Sx WIDGETS
for applicable commands.
.Pp
It is an error if
.Ar in-fifo
exists but is not a named pipe.  The named pipe
.Ar in-fifo
is deleted upon successful program termination.
.Pp
Default command input is
.Va stdin .
.It Fl o Ar out-fifo
Creates a named pipe
.Ar out-fifo
if necessary, and uses it for output of feedback messages from the
graphical user interface.
.Pp
A feedback message is a line of text; its format is
.Qo
.Fa name Ns
.Ic \&: Ns
.Fa info
.Bq Fa data
.Qc
where
.Fa name
is the name of the sending widget.  See
.Sx WIDGETS
for possible feedback messages.
.Pp
It is an error if
.Ar out-fifo
exists but is not a named pipe.  The named pipe
.Ar out-fifo
is deleted upon successful program termination.
.Pp
Default feedback-message output is
.Va stdout .
.It Fl u Ar builder-file
Displays the graphical user interface
.Ar builder-file
which should be created using the
.Xr glade 1
user interface designer and saved in GtkBuilder (.ui) format.  Widget
names should be alphanumeric, including underscores, and the main
window must be named
.Ic main .
.Pp
Default is
.Pa ./pipeglade.ui .
.It Fl G
Prints the GTK+ version and exits.
.It Fl V
Prints the
.Nm pipeglade
version and exits.
.El
.Sh WIDGETS
.Ss Any Widget (including widgets not mentioned in this document)
.Bl -tag -width "commands "
.It Commands
.Qo
.Fa name Ns
.Ic :set_sensitive
.Brq Ic 0 |  1
.Qc
makes the widget grayed out
.Pq Ic 0
or responsive
.Pq Ic 1 .
.Pp
.Qo
.Fa name Ns
.Ic :set_visible
.Brq Ic 0 |  1
.Qc
hides
.Pq Ic 0
the widget, or makes it visible
.Pq Ic 1 .
.Pp
.Qo
.Fa name Ns
.Ic :style
.Bo Fa prop Ic : Ns Fa val Ns
.Bo
.Ic ;
.Fa prop Ic : Ns Fa val ...
.Bc
.Bc
.Qc
sets properties
.Fa prop
of the widget style to
.Fa val .
Properties not explicitly specified are reset to their default values.
Examples:
.Bl -dash -offset indent -compact
.It
.Qq Li label1:style font:Bold 11; background-color:green
.It
.Qq Li label1:style font-style:italic; font-weight:bold; color:blue
.It
.Qq Li frame1:style border-color:red yellow; border-width:5px
.It
.Qq Li frame1:style border-radius:10px; transition:10s
.El
For a description of possible color notations see
.Sx GtkColorButton .
.Pp
.Qo
.Fa name Ns
.Ic :force
.Qc
simulates a click on the
.Fa name Ns
d widget, triggering a response as described with the widgets below.
Exceptions:
.Bl -dash -offset indent -compact
.It
The command is ignored by
.Sx GtkComboBoxText
(address its child
.Sx GtkEntry
instead),
.Sx GtkTreeView ,
and
.Sx GtkTreeViewColumn ;
.It
.Sx GtkCalendar , GtkEntry , GtkFileChooserButton , GtkScale ,
and
.Sx GtkSpinButton
report the currently selected item;
.It
.Sx GtkColorButton
and
.Sx GtkFontButton
just open their respective dialogs.
.El
.Pp
.Qo
.Fa name Ns
.Ic :main_quit
.Qc
kills the user interface.  A non-empty
.Fa name
is required but ignored.
.El
.Ss GtkButton
.Bl -tag -width "commands "
.It Commands
.Qo
.Fa name Ns
.Ic :set_label
.Fa string
.Qc
replaces the button text with
.Fa string .
.It Feedback
.Qo
.Fa name Ns
.Ic \&:clicked
.Qc
.Pp
.Ic GtkButton Ns
s with names ending in
.Ic _ok , _apply , _cancel , _send_text ,
and
.Ic _send_selection
may work differently; see
.Sx GtkDialog , GtkFileChooserDialog ,
and
.Sx GtkTextView
for details.
.El
.Ss GtkCalendar
.Bl -tag -width "commands "
.It Commands
.Qo
.Fa name Ns
.Ic :select_date
.Fa yyyy Ns
.Ic - Ns
.Fa mm Ns
.Ic - Ns
.Fa dd
.Qc
selects the date on the calendar.
.Pp
.Qo
.Fa name Ns
.Ic :mark_day
.Fa day
.Qc
marks
.Fa day
.Pq 1-31
on the calendar.
.Pp
.Qo
.Fa name Ns
.Ic :clear_marks
.Qc
unmarks all days on the calendar.
.It Feedback
.Qo
.Fa name Ns
.Ic \&:clicked
.Fa yyyy Ns
.Ic - Ns
.Fa mm Ns
.Ic - Ns
.Fa dd
.Qc
.Pp
.Qo
.Fa name Ns
.Ic \&:doubleclicked
.Fa yyyy Ns
.Ic - Ns
.Fa mm Ns
.Ic - Ns
.Fa dd
.Qc
.El
.Ss GtkCheckButton
.Bl -tag -width "commands "
.It Commands
.Qo
.Fa name Ns
.Ic :set_active Brq Ic 0 | 1
.Qc
switches the check mark off
.Pq Ic 0
or on
.Pq Ic 1 .
.Pp
.Qo
.Fa name Ns
.Ic :set_label
.Fa string
.Qc
replaces the button text with
.Fa string .
.It Feedback
.Qo
.Fa name Ns
.Ic \&:1
.Qc
if switched on, or
.Qo
.Fa name Ns
.Ic \&:0
.Qc
otherwise.
.El
.Ss GtkColorButton
.Bl -tag -width "commands "
.It Commands
.Qo
.Fa name Ns
.Ic :set_color
.Fa color
.Qc
preselects the color.
.Fa color
can be
.Bl -dash -offset indent -compact
.It
a standard X11 color name, like
.Qq Li Dark Sea Green ,
.It
a hexadecimal value in the form
.Ic # Ns
.Fa rgb ,
.Ic # Ns
.Fa rrggbb ,
.Ic # Ns
.Fa rrrgggbbb ,
or
.Ic # Ns
.Fa rrrrggggbbbb ,
.It
an RGB color in the form
.Ic rgb( Ns
.Fa red Ns
.Ic \&, Ns
.Fa green Ns
.Ic \&, Ns
.Fa blue Ns
.Ic \&) ,
or
.It
an RGBA color in the form
.Ic rgba( Ns
.Fa red Ns
.Ic \&, Ns
.Fa green Ns
.Ic \&, Ns
.Fa blue Ns
.Ic \&, Ns
.Fa alpha Ns
.Ic \&) .
.El
.It Feedback
.Qo
.Fa name Ns
.Ic \&:color
.Ic rgb( Ns
.Fa red Ns
.Ic \&, Ns
.Fa green Ns
.Ic \&, Ns
.Fa blue Ns
.Ic \&)
.Qc
or
.Qo
.Fa name Ns
.Ic \&:color
.Ic rgba( Ns
.Fa red Ns
.Ic \&, Ns
.Fa green Ns
.Ic \&, Ns
.Fa blue Ns
.Ic \&, Ns
.Fa alpha Ns
.Ic \&)
.Qc .
.Fa red , green ,
and
.Fa blue
lie between 0 and 255, and
.Fa alpha
between 0 and 1.
.El
.Ss GtkComboBoxText
The
.Ic GtkComboBoxText
should contain a
.Ic GtkEntry .
.Bl -tag -width "commands "
.It Commands
.Qo
.Fa name Ns
.Ic :prepend_text
.Fa string
.Qc
and
.Qo
.Fa name Ns
.Ic :append_text
.Fa string
.Qc
prepend/append a new selectable item marked
.Fa string .
.Pp
.Qo
.Fa name Ns
.Ic :insert_text
.Fa position string
.Qc
inserts item
.Fa string
at
.Fa position .
.Pp
.Qo
.Fa name Ns
.Ic :remove
.Fa position
.Qc
removes the item at
.Fa position .
.It Feedback
.Qo
.Fa entry_name Ns
.Ic \&:text
.Fa text
.Qc ,
.Fa entry_name
being the name of the child
.Ic GtkEntry .
.El
.Ss GtkDialog
A
.Ic GtkDialog
that is named
.Fa foo
will be invoked by a
.Sx GtkMenuItem
or a
.Sx GtkImageMenuItem
that is named
.Fa foo Ns
.Ic _invoke .
.Pp
The
.Ic GtkDialog
should have a
.Sq Cancel
.Sx GtkButton
named
.Fa foo Ns
.Ic _cancel
.Po
.Ic main_cancel
if the dialog is the sole window of the GUI and therefore named
.Ic main
.Pc .
.Bl -tag -width "commands "
.It Commands
none
.It Feedback
none
.El
.Ss GtkDrawingArea
Most drawing commands expect an
.Fa id
parameter (an arbitrary non-negative integer) which can be used to reference the
command for later removal.
.Bl -tag -width "commands "
.It Commands
.Qo
.Fa name Ns
.Ic :arc
.Fa id x y radius angle1 angle2
.Qc
adds a circular arc to the current path.  The arc is centered at
.Pq Fa x , y
and proceeds clockwise from
.Fa angle1
to
.Fa angle2
.Po
in degrees
.Pc .
.Pp
.Qo
.Fa name Ns
.Ic :arc_negative
.Fa id x y radius angle1 angle2
.Qc
adds a circular arc to the current path.  The arc is centered at
.Pq Fa x , y
and proceeds counterclockwise from
.Fa angle1
to
.Fa angle2
.Po
in degrees
.Pc .
.Pp
.Qo
.Fa name Ns
.Ic :close_path
.Fa id
.Qc
adds a line segment from the current point to the point most recently
passed to
.Fa name Ns
.Ic :move_to
or
.Fa name Ns
.Ic :rel_move_to .
.Pp
.Qo
.Fa name Ns
.Ic :curve_to
.Fa id x1 y1 x2 y2 x3 y3
.Qc
adds a cubic Bezier spline from the current point to
.Pq Fa x3 , y3 ,
using
.Pq Fa x1 , y1
and
.Pq Fa x2 , y2
as control points.
.Pp
.Qo
.Fa name Ns
.Ic :fill
.Fa id
.Qc
fills the current path and clears it.
.Pp
.Qo
.Fa name Ns
.Ic :fill_preserve
.Fa id
.Qc
fills the current path without clearing it.
.Pp
.Qo
.Fa name Ns
.Ic :line_to
.Fa id x y
.Qc
adds a line from the current point to
.Pq Fa x , y .
.Pp
.Qo
.Fa name Ns
.Ic :move_to
.Fa id x y
.Qc
sets the current point to
.Pq Fa x , y .
.Pp
.Qo
.Fa name Ns
.Ic :rectangle
.Fa id x y width height
.Qc
adds a rectangle to the current path.  The top left corner is at
.Pq Fa x , y .
.Pp
.Qo
.Fa name Ns
.Ic :refresh
.Qc
redraws the
.Ic GtkDrawingArea
.Fa name .
.Pp
.Qo
.Fa name Ns
.Ic :rel_curve_to
.Fa id dx1 dy1 dx2 dy2 dx3 dy3
.Qc
adds a cubic Bezier spline from the current point to
.Pq Fa dx3 , dy3 ,
using
.Pq Fa dx1 , dy1
and
.Pq Fa dx2 , dy2
as control points.  All coordinates are offsets relative to the
current point.
.Pp
.Qo
.Fa name Ns
.Ic :rel_line_to
.Fa id dx dy
.Qc
adds a line from the current point to a point offset from there by
.Pq Fa dx , dy .
.Pp
.Qo
.Fa name Ns
.Ic :rel_move_to
.Fa id dx dy
.Qc
moves the current point by
.Pq Fa dx , dy .
.Pp
.Qo
.Fa name Ns
.Ic :remove
.Fa id
.Qc
removes the elements with
.Fa id
from the
.Ic GtkDrawingArea
.Fa name .
.Pp
.Qo
.Fa name Ns
.Ic :set_dash
.Fa id l
.Qc
sets the dash pattern to
.Fa l
on,
.Fa l
off.
.Pp
.Qo
.Fa name Ns
.Ic :set_dash
.Fa id l1on l1off l2on l2off ...
.Qc
resets the dash pattern to a line with arbitrary on/off portions.
.Pp
.Qo
.Fa name Ns
.Ic :set_dash
.Fa id
.Qc
resets the dash pattern to a solid line.
.Pp
.Qo
.Fa name Ns
.Ic :set_font_size
.Fa id size
.Qc
sets the font size for subsequent calls of
.Fa name Ns
.Ic :show_text .
.Pp
.Qo
.Fa name Ns
.Ic :set_line_cap
.Fa id
.Brq Ic butt | round | square
.Qc
sets the line cap style.
.Pp
.Qo
.Fa name Ns
.Ic :set_line_join
.Fa id
.Brq Ic miter | round | bevel
.Qc
sets the line junction style.
.Pp
.Qo
.Fa name Ns
.Ic :set_line_width
.Fa id width
.Qc
sets the line width.
.Pp
.Qo
.Fa name Ns
.Ic :set_source_rgba
.Fa id color
.Qc
sets the color.
.Fa color
is in the format used with
.Sx GtkColorButton .
.Pp
.Qo
.Fa name Ns
.Ic :show_text
.Fa id text
.Qc
writes
.Fa text ,
beginning at the current point.
.Pp
.Qo
.Fa name Ns
.Ic :stroke
.Fa id
.Qc
strokes the current path and clears it.
.Pp
.Qo
.Fa name Ns
.Ic :stroke_preserve
.Fa id
.Qc
strokes the current path without clearing it.
.It Feedback
none
.El
.Ss GtkEntry
.Bl -tag -width "commands "
.It Commands
.Qo
.Fa name Ns
.Ic :set_text
.Fa string
.Qc
replaces the user-editable text with
.Fa string .
.It Feedback
.Qo
.Fa name Ns
.Ic \&:text
.Fa text
.Qc ,
once for each change of
.Fa text .
.El
.Ss GtkExpander
.Bl -tag -width "commands "
.It Commands
.Qo
.Fa name Ns
.Ic :set_label
.Fa string
.Qc
replaces the expander label text with
.Fa string .
.Pp
.Qo
.Fa name Ns
.Ic :set_expanded
.Brq Ic 0 |  1
.Qc
hides
.Pq Ic 0
the child widget, or makes it visible
.Pq Ic 1 .
.It Feedback
none
.El
.Ss GtkFileChooserButton
.Bl -tag -width "commands "
.It Commands
.Qo
.Fa name Ns
.Ic :set_filename
.Fa path
.Qc
preselects
.Fa path
to the extent it exists.
.It Feedback
.Qo
.Fa name Ns
.Ic \&:file
.Fa pathname
.Qc
if the selection has changed.
.El
.Ss GtkFileChooserDialog
A
.Ic GtkFileChooserDialog
that is named
.Fa foo
will be invoked by a
.Sx GtkMenuItem
or a
.Sx GtkImageMenuItem
that is named
.Fa foo Ns
.Ic _invoke
.Pp
The
.Ic GtkFileChooserDialog
should have an
.Sq OK
.Sx GtkButton
named
.Fa foo Ns
.Ic _ok
.Po
.Ic main_ok
if the dialog is the sole window of the GUI and therefore named
.Ic main
.Pc .
.Pp
The
.Ic GtkFileChooserDialog
may have a
.Sq Cancel
.Sx GtkButton
named
.Fa foo Ns
.Ic _cancel
.Po
.Ic main_cancel
if the dialog is the sole window of the GUI and therefore named
.Ic main
.Pc .
.Pp
The
.Ic GtkFileChooserDialog
may have an
.Sq Apply
.Sx GtkButton
named
.Fa foo Ns
.Ic _apply
.Po
.Ic main_apply
if the dialog is the sole window of the GUI and therefore named
.Ic main
.Pc .
.Bl -tag -width "commands "
.It Commands
.Qo
.Fa name Ns
.Ic :set_filename
.Fa path
.Qc
preselects
.Fa path
to the extent it exists.
.Pp
.Qo
.Fa name Ns
.Ic :set_current_name
.Fa string
.Qc
makes
.Fa string
the suggested filename, which may not yet exist.
.Fa string
should either resemble an absolute path, or the
.Fa directory
must be set
separately by
.Fa name Ns
.Ic :set_filename
.Fa directory .
.It Feedback
.Qo
.Fa name Ns
.Ic :file
.Fa  pathname
.Qc
and/or
.Qo
.Fa name Ns
.Ic :folder
.Fa  pathname
.Qc
.El
.Ss GtkFontButton
.Bl -tag -width "commands "
.It Commands
.Qo
.Fa name Ns
.Ic :set_font_name
.Fa fontname
.Qc
preselects the font.
.It Feedback
.Qo
.Fa name Ns
.Ic \&:font
.Fa fontname
.Qc
.El
.Ss GtkFrame
.Bl -tag -width "commands "
.It Commands
.Qo
.Fa name Ns
.Ic :set_label
.Fa text
.Qc
replaces the frame label text with
.Fa string .
.It Feedback
none
.El
.Ss GtkImage
.Bl -tag -width "commands "
.It Commands
.Qo
.Fa name Ns
.Ic :set_from_icon_name
.Fa icon-name
.Qc
replaces the image with one of the standard icons.
.Pp
.Qo
.Fa name Ns
.Ic :set_from_file
.Fa path
.Qc
replaces the image by the one found at
.Fa path Ns .
.It Feedback
none
.El
.Ss GtkLabel
.Bl -tag -width "commands "
.It Commands
.Qo
.Fa name Ns
.Ic :set_text
.Fa string
.Qc
replaces the label text with
.Fa string .
.It Feedback
none
.El
.Ss GtkMenuItem, GtkImageMenuItem
.Bl -tag -width "commands "
.It Commands
none
.It Feedback
A
.Ic GtkMenuItem
or
.Ic GtkImageMenuItem
with the name
.Fa foo Ns
.Ic _invoke
will invoke the
.Sx GtkDialog
or
.Sx GtkFileChooserDialog
named
.Fa foo
if it exists.  If there isn't any dialog attached to the
.Ic GtkMenuItem ,
it reports
.Qo
.Fa name Ns
.Ic \&:active
.Fa label
.Qc .
.El
.Ss GtkNotebook
.Bl -tag -width "commands "
.It Commands
.Qo
.Fa name Ns
.Ic :set_current_page
.Fa numeric
.Qc
switches to page number
.Fa numeric
.Po
starting from 0
.Pc .
.It Feedback
none
.El
.Ss GtkPrintUnixDialog
.Bl -tag -width "commands "
.It Commands
.Qo
.Fa name Ns
.Ic :print
.Fa file.ps
.Qc
opens the print dialog.  Pressing the
.Qq Print
button sends
.Fa file.ps
to the selected printer.
.It Feedback
none
.El
.Ss GtkProgressBar
.Bl -tag -width "commands "
.It Commands
.Qo
.Fa name Ns
.Ic :set_fraction
.Fa numeric
.Qc
moves the progress bar to
.Fa numeric
.Po
between 0 and 1
.Pc .
.Pp
.Qo
.Fa name Ns
.Ic :set_text
.Bq Fa string
.Qc
replaces the text of the progress bar with
.Fa string .
Default is the progress percentage.
.It Feedback
none
.El
.Ss GtkRadioButton
.Bl -tag -width "commands "
.It Commands
.Qo
.Fa name Ns
.Ic :set_active 1
.Qc
switches the button on.  All other buttons of the same group will go off
automatically.
.Pp
.Qo
.Fa name Ns
.Ic :set_label
.Fa string
.Qc
replaces the button text with
.Fa string .
.It Feedback
.Qo
.Fa name Ns
.Ic \&:1
.Qc
if switched on, or
.Qo
.Fa name Ns
.Ic \&:0
.Qc
otherwise.
.El
.Ss GtkScale
.Bl -tag -width "commands "
.It Commands
.Qo
.Fa name Ns
.Ic :set_value
.Fa numeric
.Qc
moves the slider to value
.Fa numeric .
.It Feedback
.Qo
.Fa name Ns
.Ic \&:value
.Fa floating_point_text
.Qc
.El
.Ss GtkSocket
.Ic GtkSocket
may be unsupported by Glade so its definition needs to be inserted
manually into the GtkBuilder (.ui) file:
.Bf -literal
 <child>
   <object class="GtkSocket" id="socket1">
     <property name="visible">True</property>
     <property name="can_focus">True</property>
   </object>
   <packing>
     <property name="expand">False</property>
     <property name="fill">True</property>
     <property name="position">1</property>
   </packing>
 </child>
.Ef
.Bl -tag -width "commands "
.It Commands
.Qo
.Fa name Ns
.Ic :id
.Qc
requests a feedback message containing the socket
.Fa id .
.It Feedback
.Qo
.Fa name Ns
.Ic :id
.Fa id
.Qc
can be used by another process to XEmbed its widgets into the
.Ic GtkSocket .
.Pp
.Qo
.Fa name Ns
.Ic :plug-added
.Qc ,
.Qo
.Fa name Ns
.Ic :plug-removed
.Qc .
Notification that the other process has inserted its widgets into or
removed them from the
.Ic GtkSocket .
.El
.Ss GtkSpinButton
.Bl -tag -width "commands "
.It Commands
.Qo
.Fa name Ns
.Ic :set_text
.Fa string
.Qc
sets the selected value to
.Fa string .
.It Feedback
.Qo
.Fa name Ns
.Ic \&:text
.Fa text
.Qc
.El
.Ss GtkSpinner
.Bl -tag -width "commands "
.It Commands
.Qo
.Fa name Ns
.Ic :start
.Qc
and
.Qo
.Fa name Ns
.Ic :stop
.Qc
start and stop the spinner.
.It Feedback
none
.El
.Ss GtkStatusbar
.Bl -tag -width "commands "
.It Commands
.Qo
.Fa name Ns
.Ic :push
.Fa string
.Qc
displays
.Fa string
in the statusbar.
.Pp
.Qo
.Fa name Ns
.Ic :pop
.Qc
removes the last entry from the statusbar, revealing the penultimate
entry.
.Pp
.Qo
.Fa name Ns
.Ic :remove_all
.Qc
empties the statusbar.
.It Feedback
none
.El
.Ss GtkSwitch
.Bl -tag -width "commands "
.It Commands
.Qo
.Fa name Ns
.Ic :set_active Brq Ic 0 | 1
.Qc
turns the switch off
.Pq Ic 0
or on
.Pq Ic 1 .
.It Feedback
.Qo
.Fa name Ns
.Ic \&:1
.Qc
if switched on, or
.Qo
.Fa name Ns
.Ic \&:0
.Qc
otherwise.
.El
.Ss GtkTextView
There should be a dedicated
.Sx GtkButton
for sending (parts of) the text.
If the name of the
.Ic GtkTextView
is
.Fa foo ,
a
.Sx GtkButton
named
.Fa foo Ns
.Ic _send_text
will send the content of the
.Ic GtkTextView ;
a
.Sx GtkButton
named
.Fa foo Ns
.Ic _send_selection
will send the highlighted part the
.Ic GtkTextView .
.Bl -tag -width "commands "
.It Commands
.Qo
.Fa name Ns
.Ic :set_text
.Fa string
.Qc
replaces the user-editable text with
.Fa string Ns .
.Pp
.Qo
.Fa name Ns
.Ic :delete
.Qc
deletes the text.
.Pp
.Qo
.Fa name Ns
.Ic :insert_at_cursor
.Fa string
.Qc
inserts
.Fa string
at cursor position.
.Pp
.Qo
.Fa name Ns
.Ic :place_cursor Brq Fa position | Ic end
.Qc
places the text cursor at
.Fa position
or at the end of the text.
.Pp
.Qo
.Fa name Ns
.Ic :place_cursor_at_line
.Fa line
.Qc
places the text cursor at the beginning of
.Fa line .
.Pp
.Qo
.Fa name Ns
.Ic :scroll_to_cursor
.Qc
scrolls to the cursor position if necessary.
.It Feedback
.Qo
.Fa button_name Ns
.Ic :text
.Fa text
.Qc ,
.Fa button_name
being the name of the
.Sx GtkButton .
Line endings in
.Fa text
are replaced by
.Ic \en ,
and backslashes are replaced by
.Ic \e\e .
.El
.Ss GtkToggleButton
.Bl -tag -width "commands "
.It Commands
.Qo
.Fa name Ns
.Ic :set_active Brq Ic 0 | 1
.Qc
switches the button off
.Pq Ic 0
or on
.Pq Ic 1 .
.Pp
.Qo
.Fa name Ns
.Ic :set_label
.Fa string
.Qc
replaces the button text with
.Fa string .
.It Feedback
.Qo
.Fa name Ns
.Ic \&:1
.Qc
if switched on, or
.Qo
.Fa name Ns
.Ic \&:0
.Qc
otherwise.
.El
.Ss GtkTreeView
.Nm
can deal with columns of type
.Ic gboolean , gint , guint , glong , gulong , gint64 , guint64 , gfloat , gdouble ,
and
.Ic gchararray .
.Pp
.Fa row
and
.Fa column
refer to the underlying model (usually a
.Ic GtkListStore ) .
.Bl -tag -width "commands "
.It Commands
.Qo
.Fa name Ns
.Ic :set
.Fa row column data
.Qc
replaces the content at
.Pq Fa row , column
with
.Fa data
(which should be compatible with the type of
.Fa column ) .
.Pp
.Qo
.Fa name Ns
.Ic :insert_row Brq Fa position | Ic end
.Qc
inserts a new, empty row at
.Fa position
or at the end of the list.
.Pp
.Qo
.Fa name Ns
.Ic :move_row
.Fa origin Brq Fa destination | Ic end
.Qc
moves the row at
.Fa origin
to
.Fa destination
or to the end of the list.
.Pp
.Qo
.Fa name Ns
.Ic :remove_row
.Fa position
.Qc
removes the row at
.Fa position .
.Pp
.Qo
.Fa name Ns
.Ic :scroll
.Fa row column
.Qc
scrolls the cell at
.Pq Fa row , column
into view.
.It Feedback
.Qo
.Fa name Ns
.Ic \&:clicked
.Qc
.Pp
.Qo
.Fa name Ns
.Ic \&: Ns
.Fa column_type row column value
.Qc ,
one message per selected row and column in the underlying model if
the set of selected rows has changed.
.El
.Ss GtkTreeViewColumn
.Bl -tag -width "commands "
.It Commands
none
.It Feedback
.Qo
.Fa name Ns
.Ic \&:clicked
.Qc
.El
.Sh EXAMPLES
.Ss Discovering Pipeglade Interactively
Suppose the interface in
.Pa ./pipeglade.ui
has a
.Sx GtkLabel
.Li label1
and a
.Sx GtkButton
.Li button1 .
After invoking
.Dl pipeglade
and clicking the
.Sx GtkButton ,
.Qq button1:clicked
will be reported on the terminal.  Typing
.Dl label1:set_text Button Label
will change the text shown on the label into
.Qq Button Label .
.Ss One-Shot File Dialog
Suppose the interface in
.Pa ./simple_open.ui
contains a
.Sx GtkFileChooserDialog
with an
.Sq OK
.Sx GtkButton
named
.Li main_ok .
Invoking
.Dl pipeglade -u simple_open.ui
will open the dialog; pressing
.Sq OK
will close it after sending the selected filename to
.Va stdout .
.Ss One-Shot User Notification
If the interface in
.Pa ./simple_dialog.ui
contains a
.Sx GtkLabel
.Li label1 ,
then
.Dl pipeglade -u simple_dialog.ui <<< \e
.Dl \ \ \ \ \&"label1:set_text NOW READ THIS!\&"
will set the label text accordingly and wait for user input.
.Ss Continuous Input
The following shell command displays a running clock:
.Dl while true; do
.Dl \ \ \ \ echo \&"label1:set_text `date`\&";
.Dl \ \ \ \ sleep 1;
.Dl done | pipeglade -u simple_dialog.ui
.Ss Continuous Input and Output
The following shell script fragment sets up
.Nm
for continuous communication with another program,
.Li main_prog :
.Dl pipeglade -i in.fifo -o out.fifo &
.Dl # wait for in.fifo and out.fifo to appear
.Dl while test \& ! \e( -e in.fifo -a -e out.fifo \e); do :; done
.Dl main_prog <out.fifo >in.fifo
.Sh EXIT STATUS
.Nm
exits 0 on success, and >0 if an error occurs.
.Sh SEE ALSO
.Xr glade 1 ,
.Xr dialog 1 ,
.Xr gmessage 1 ,
.Xr kdialog 1 ,
.Xr whiptail 1 ,
.Xr xmessage 1 ,
.Xr zenity 1
.Sh AUTHOR
.Nm
was written by
.An Bert Burgemeister Aq trebbu@googlemail.com .
.\" .Sh BUGS