Refactoring

[pipeglade.git] / pipeglade.1

.\" Copyright (c) 2014-2016 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 May 07, 2016
.Dt PIPEGLADE 1 PRM
.Os BSD
.Sh NAME
.Nm pipeglade
.Nd pipe-driven GTK+ interface
.Sh SYNOPSIS
.Nm
.Oo
.Op Fl i Ar in-fifo
.Op Fl o Ar out-fifo
.Op Fl b
.Op Fl u Ar builder-file
.Op Fl e Ar parent-xid
.Op Fl l Ar log-file
.Op Fl O Ar err-file
.Op Fl -display Ar X-server
.Oc |
.Op Fl h | G | V
.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
(typically 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 i Ar in-fifo
Creates a named pipe
.Ar in-fifo
if necessary, sets its permissions to
.Li 0600 ,
and uses it for command input.
.Pp
A command is a line of text.
Its format is
.Qq Ar id Ns Cm \&: Ns Ar action Bq Ar data ,
.Ar id
being the name of the receiving widget;
.Ar data
is separated from the rest of the command by a single whitespace
character.
Commands whose first non-whitespace character is
.Cm #
are considered comments and ignored silently, as are empty input lines.
Any occurences of the two-character sequences
.Cm \en
and
.Cm \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, sets its permissions to
.Li 0600 ,
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
.Qq Ar id Ns Cm \&: Ns Ar info Bq Ar data ,
.Ar id
being 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 b
Runs
.Nm
in the background after printing its process ID to
.Va stdout .
.Pp
It is an error if option
.Fl b
is used and not both
.Fl i Ar in-fifo
and
.Fl o Ar out-fifo
are specified.
.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 ids should be alphanumeric, including underscores, and the
main window must must be given the id
.Cm main .
.Pp
Default is
.Pa ./pipeglade.ui .
.It Fl e Ar parent-xid
Embeds the main window into the XEmbed socket
.Ar parent-xid
of another process.
.It Fl l Ar log-file
Appends for each command a line of
.Qq Ar time activity
to
.Ar log-file ,
.Ar time
being the number of microseconds elapsed during
.Ar activity .
.Ar time
and
.Ar activity
are separated by a tab character.
Permissions of
.Ar log-file
are set to
.Li 0600 .
A
.Ar log-file
name of
.Ql -
means
.Va stderr .
.It Fl O Ar err-file
Redirects
.Va stderr ,
appending its output to
.Ar err-file .
Permissions of
.Ar err-file
are set to
.Li 0600 .
.It Fl -display Ar X-server
Uses the display on
.Ar X-server
for user interaction.
.It Fl h
Prints a help message and exits.
.It Fl G
Prints the versions of the underlying GTK+ and cairo libraries and
exits.
.It Fl V
Prints the
.Nm
version and exits.
.El
.Sh WIDGETS
The widget classes able to communicate through
.Nm
are
.Sx GtkButton ,
.Sx GtkCalendar ,
.Sx GtkCheckButton ,
.Sx GtkColorButton ,
.Sx GtkComboBoxText ,
.Sx GtkDialog ,
.Sx GtkDrawingArea ,
.Sx GtkEntry ,
.Sx GtkEventBox ,
.Sx GtkExpander ,
.Sx GtkFileChooserButton ,
.Sx GtkFileChooserDialog ,
.Sx GtkFontButton ,
.Sx GtkFrame ,
.Sx GtkImage ,
.Sx GtkLabel ,
.Sx GtkMenuItem, GtkImageMenuItem ,
.Sx GtkNotebook ,
.Sx GtkPrintUnixDialog ,
.Sx GtkProgressBar ,
.Sx GtkRadioButton ,
.Sx GtkScale ,
.Sx GtkScrolledWindow
.Sx GtkSocket ,
.Sx GtkSpinButton ,
.Sx GtkSpinner ,
.Sx GtkStatusbar ,
.Sx GtkSwitch ,
.Sx GtkTextView ,
.Sx GtkToggleButton ,
.Sx GtkTreeView ,
.Sx GtkTreeViewColumn ,
and
.Sx GtkWindow .
.Pp
.Nm
references a widget by the
.Ar id
attribute it is given in Glade.
In the
.Pa .ui
file, a
.Cm GtkWindow
named
.Li foo
would appear as
.Dl <object class="GtkWindow" id="foo"> .
.Ss Any Widget (including widgets not mentioned above)
.Bl -tag -width "commands "
.It Commands
.Qq Ar id Ns Cm :set_sensitive Brq Cm 0 | 1
makes the widget grayed out
.Pq Cm 0
or responsive
.Pq Cm 1 .
.Pp
.Qq Ar id Ns Cm :set_visible Brq Cm 0 | 1
hides
.Pq Cm 0
the widget, or makes it visible
.Pq Cm 1 .
.Pp
.Qq Ar id Ns Cm :grab_focus
puts the keyboard focus onto the widget, if possible.
.Pp
.Qq Ar id Ns Cm :set_size_request Bq Ar width height
sets the widget's minimum size to
.Ar width
x
.Ar height .
Default is the widget's natural size.
.Pp
.Qo
.Ar id Ns Cm :style
.Bo Ar prop Ns Cm \&: Ns Ar val Ns Bo Cm \&; Ar prop Ns Cm \&: Ns Ar val ... Bc Bc
.Qc
sets properties
.Ar prop
of the widget style to
.Ar val .
Properties not explicitly specified are reset to their default values.
Examples:
.Bl -dash -offset indent -compact
.It
.Ql label1:style font:Bold 11; background-color:green
.It
.Ql label1:style font-style:italic; font-weight:bold; color:blue
.It
.Ql frame1:style border-color:red yellow; border-width:5px
.It
.Ql frame1:style border-radius:10px; transition:10s
.El
For a description of possible color notations see
.Sx GtkColorButton .
.Pp
.Qq Ar id Ns Cm :set_tooltip_text Bq Ar text
sets the widget's tooltip
.Ar text .
Default is disabling the tooltip.
.Pp
.Qq Ar id Ns Cm :block Brq Cm 0 | 1
blocks
.Pq Cm 1
or unblocks
.Pq Cm 0
feedback messages from widget.
Doesn't work for
.Sx GtkTreeView ;
address the underlying
.Cm GtkTreeSelection
instead.
Initially, all widgets are unblocked.
.Pp
.Qq Ar id Ns Cm :force
simulates a click on widget
.Ar id ,
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 GtkEventBox ,
.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
.Qq Ar id Ns Cm :load Ar file
reads arbitrary
.Nm
commands from
.Ar file .
A non-empty
.Ar id
is required but ignored.
.Cm :load
commands may be nested but on attempts to read from the same file, the
inner
.Cm :load
is ignored.
There is also a
.Cm :save
command; see
.Sx GtkTextView
and
.Sx GtkTreeView .
.Pp
.Qq Ar id Ns Cm :snapshot Ar file Ns Brq Cm .ps Ns | Ns Cm .eps Ns | Ns Cm .epsf Ns | Ns Cm .pdf Ns | Ns Cm .svg
writes a snapshot of the widget to an image file of the specified
type.
.Pp
.Qq Ar id Ns Cm :main_quit
kills the user interface.
A non-empty
.Ar id
is required but ignored.
.El
.Ss GtkButton
.Bl -tag -width "commands "
.It Commands
.Qq Ar id Ns Cm :set_label Ar string
replaces the button text with
.Ar string .
.It Feedback
.Qq Ar id Ns Cm \&:clicked
.Pp
.Cm GtkButton Ns
s with ids ending in
.Cm _ok , _apply , _cancel , _send_text ,
and
.Cm _send_selection
may work differently; see
.Sx GtkDialog , GtkFileChooserDialog ,
and
.Sx GtkTextView
for details.
.El
.Ss GtkCalendar
.Bl -tag -width "commands "
.It Commands
.Qq Ar id Ns Cm :select_date Ar yyyy Ns Cm - Ns Ar mm Ns Cm - Ns Ar dd
selects the date on the calendar.
.Pp
.Qq Ar id Ns Cm :mark_day Ar day
marks
.Ar day Pq 1-31
on the calendar.
.Pp
.Qq Ar id Ns Cm :clear_marks
unmarks all days on the calendar.
.It Feedback
.Qq Ar id Ns Cm \&:clicked Ar yyyy Ns Cm - Ns Ar mm Ns Cm - Ns Ar dd
.Pp
.Qq Ar id Ns Cm \&:doubleclicked Ar yyyy Ns Cm - Ns Ar mm Ns Cm - Ns Ar dd
.El
.Ss GtkCheckButton
.Bl -tag -width "commands "
.It Commands
.Qq Ar id Ns Cm :set_active Brq Cm 0 | 1
switches the check mark off
.Pq Cm 0
or on
.Pq Cm 1 .
.Pp
.Qq Ar id Ns Cm :set_label Ar string
replaces the button text with
.Ar string .
.It Feedback
.Qq Ar id Ns Cm \&:1
if switched on, or
.Qq Ar id Ns Cm \&:0
otherwise.
.El
.Ss GtkColorButton
.Bl -tag -width "commands "
.It Commands
.Qq Ar id Ns Cm :set_color Ar color
preselects the color.
.Ar color
can be
.Bl -dash -offset indent -compact
.It
a standard X11 color name, like
.Ql Dark Sea Green ,
.It
a hexadecimal value in the form
.Cm # Ns Ar rgb , Cm # Ns Ar rrggbb , Cm # Ns Ar rrrgggbbb ,
or
.Cm # Ns Ar rrrrggggbbbb ,
.It
an RGB color in the form
.Cm rgb( Ns Ar red Ns Cm \&, Ns Ar green Ns Cm \&, Ns Ar blue Ns Cm \&) ,
or
.It
an RGBA color in the form
.Cm rgba( Ns Ar red Ns Cm \&, Ns Ar green Ns Cm \&, Ns
.Ar blue Ns Cm \&, Ns Ar alpha Ns Cm \&) .
.El
.It Feedback
.Qq Ar id Ns Cm \&:color Cm rgb( Ns Ar red Ns Cm \&, Ns Ar green Ns Cm \&, Ns Ar blue Ns Cm \&)
or
.Qq Ar id 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 \&) .
.Ar red , green ,
and
.Ar blue
lie between 0 and 255, and
.Ar alpha
between 0 and 1.
.El
.Ss GtkComboBoxText
The
.Cm GtkComboBoxText
should contain a
.Cm GtkEntry .
.Bl -tag -width "commands "
.It Commands
.Qq Ar id Ns Cm :prepend_text Ar string
and
.Qq Ar id Ns Cm :append_text Ar string
prepend/append a new selectable item marked
.Ar string .
.Pp
.Qq Ar id Ns Cm :insert_text Ar position string
inserts item
.Ar string
at
.Ar position .
.Pp
.Qq Ar id Ns Cm :remove Ar position
removes the item at
.Ar position .
.It Feedback
.Qq Ar entry_id Ns Cm \&:text Ar text ,
.Ar entry_id
being the id of the child
.Cm GtkEntry .
.El
.Ss GtkDialog
A
.Cm GtkDialog
with id
.Ar foo
will be invoked by a
.Sx GtkMenuItem
or a
.Sx GtkImageMenuItem
with id
.Ar foo Ns Cm _invoke .
.Pp
The
.Cm GtkDialog
should have a
.Sq Cancel
.Sx GtkButton
with id
.Ar foo Ns Cm _cancel
.Po Cm main_cancel
if the dialog is the sole window of the GUI and therefore named
.Cm main
.Pc .
.Pp
If the
.Cm GtkDialog
has an
.Sq Ok
.Sx GtkButton
with id
.Ar foo Ns Cm _ok ,
it will take care of hiding the dialog window.
.Bl -tag -width "commands "
.It Commands
.Qq Ar id Ns Cm :set_title Ar string
replaces the text in the title bar with
.Ar string .
.Pp
.Qq Ar id Ns Cm :resize Bq Ar width height
changes the size of the dialog window to
.Ar width
x
.Ar height
pixels if specified, or to the default size.
.Pp
.Qq Ar id Ns Cm :move Ar x y
moves the dialog window to position
.Pq Ar x , y .
.Pp
.Qq Ar id Ns Cm :fullscreen
and
.Qq Ar id Ns Cm :unfullscreen
switch fullscreen mode on and off.
.It Feedback
.Qq Ar id Ns Cm \&:closed
if the
.Cm GtkDialog
window was closed by the window manager.
.El
.Ss GtkDrawingArea
Drawing commands
expect a context parameter of the form
.Bro Ar n Ns | Ns Cm = Ns Ar n Ns | Ns Ar n Ns Cm < Ns Ar m Brc
where
.Ar n
is an arbitrary non-negative integer that can be used later to
reference the command.
The first form,
.Ar n ,
appends its command to the current list of drawing operations.
The second form,
.Cm = Ns Ar n ,
replaces the first drawing operation with context parameter
.Ar n
by the new command.
The third form,
.Ar n Ns Cm < Ns Ar m ,
inserts its command before the first drawing operation with context
parameter
.Ar m .
Both second and third form fall back to appending.
.Pp
The default coordinate system is a left-handed system with its origin
in the upper-left corner.
Angles increase from the positive X axis towards the positve Y axis
.Pq clockwise in the default system .
.Bl -tag -width "commands "
.It Commands
.Qq Ar id Ns Cm :arc Bro Ar n Ns | Ns Cm = Ns Ar n Ns | Ns Ar n Ns Cm < Ns Ar m Brc x y radius angle1 angle2
adds a circular arc to the current path.
The arc is centered at
.Pq Ar x , y
and proceeds from
.Ar angle1
to
.Ar angle2
.Pq in degrees .
.Pp
.Qq Ar id Ns Cm :arc_negative Bro Ar n Ns | Ns Cm = Ns Ar n Ns | Ns Ar n Ns Cm < Ns Ar m Brc x y radius angle1 angle2
adds a circular arc to the current path.
The arc is centered at
.Pq Ar x , y
and proceeds in the direction of decreasing angles from
.Ar angle1
to
.Ar angle2
.Pq in degrees .
.Pp
.Qq Ar id Ns Cm :close_path Bro Ar n Ns | Ns Cm = Ns Ar n Ns | Ns Ar n Ns Cm < Ns Ar m Brc
adds a line segment from the current point to the point most recently
passed to
.Ar id Ns Cm :move_to
or
.Ar id Ns Cm :rel_move_to .
.Pp
.Qq Ar id Ns Cm :curve_to Bro Ar n Ns | Ns Cm = Ns Ar n Ns | Ns Ar n Ns Cm < Ns Ar m Brc x1 y1 x2 y2 x3 y3
adds a cubic Bezier spline from the current point to
.Pq Ar x3 , y3 ,
using
.Pq Ar x1 , y1
and
.Pq Ar x2 , y2
as control points.
If there is no current point, the curve will start at
.Pq Ar x1 , y1 .
.Pp
.Qq Ar id Ns Cm :fill Bro Ar n Ns | Ns Cm = Ns Ar n Ns | Ns Ar n Ns Cm < Ns Ar m Brc
fills the current path and clears it.
.Pp
.Qq Ar id Ns Cm :fill_preserve Bro Ar n Ns | Ns Cm = Ns Ar n Ns | Ns Ar n Ns Cm < Ns Ar m Brc
fills the current path without clearing it.
.Pp
.Qq Ar id Ns Cm :line_to Bro Ar n Ns | Ns Cm = Ns Ar n Ns | Ns Ar n Ns Cm < Ns Ar m Brc x y
adds a line from the current point to
.Pq Ar x , y ,
or creates a new current point at
.Pq Ar x , y .
.Pp
.Qq Ar id Ns Cm :move_to Bro Ar n Ns | Ns Cm = Ns Ar n Ns | Ns Ar n Ns Cm < Ns Ar m Brc x y
sets the current point to
.Pq Ar x , y .
.Pp
.Qq Ar id Ns Cm :rectangle Bro Ar n Ns | Ns Cm = Ns Ar n Ns | Ns Ar n Ns Cm < Ns Ar m Brc x y width height
adds a rectangle to the current path.
The top left corner is at
.Pq Ar x , y .
.Pp
.Qq Ar id Ns Cm :rel_curve_to Bro Ar n Ns | Ns Cm = Ns Ar n Ns | Ns Ar n Ns Cm < Ns Ar m Brc dx1 dy1 dx2 dy2 dx3 dy3
adds a cubic Bezier spline from the current point to
.Pq Ar dx3 , dy3 ,
using
.Pq Ar dx1 , dy1
and
.Pq Ar dx2 , dy2
as control points.
All coordinates are offsets relative to the current point.
.Pp
.Qq Ar id Ns Cm :rel_line_to Bro Ar n Ns | Ns Cm = Ns Ar n Ns | Ns Ar n Ns Cm < Ns Ar m Brc dx dy
adds a line from the current point to a point offset from there by
.Pq Ar dx , dy .
.Pp
.Qo Ar id Ns Cm :rel_move_for Bro Ar n Ns | Ns Cm = Ns Ar n Ns | Ns Ar n Ns Cm < Ns Ar m Brc
.Brq Cm c Ns | Ns Cm e Ns | Ns Cm n Ns | Ns Cm ne Ns | Ns Cm nw Ns | Ns Cm s Ns | Ns Cm se Ns | Ns Cm sw Ns | Ns Cm w
.Ar text
.Qc
moves the current point such that
.Qq Ar id Ns Cm :show_text Ar n text
will place the specified reference point of
.Ar text
on the original current point.
.Pp
.Qq Ar id Ns Cm :rel_move_to Bro Ar n Ns | Ns Cm = Ns Ar n Ns | Ns Ar n Ns Cm < Ns Ar m Brc dx dy
moves the current point by
.Pq Ar dx , dy .
.Pp
.Qq Ar id Ns Cm :remove Ar n
removes the elements with context parameter
.Ar n
from the
.Cm GtkDrawingArea Ar id .
.Pp
.Qq Ar id Ns Cm :rotate Bro Ar n Ns | Ns Cm = Ns Ar n Ns | Ns Ar n Ns Cm < Ns Ar m Brc Ar angle
rotates the user space axes by
.Ar angle
.Pq in degrees .
.Pp
.Qq Ar id Ns Cm :scale Bro Ar n Ns | Ns Cm = Ns Ar n Ns | Ns Ar n Ns Cm < Ns Ar m Brc Ar sx sy
scales the user space axes by
.Pq Ar sx , sy .
.Pp
.Qq Ar id Ns Cm :set_dash Bro Ar n Ns | Ns Cm = Ns Ar n Ns | Ns Ar n Ns Cm < Ns Ar m Brc l
sets the dash pattern to
.Ar l
on,
.Ar l
off.
.Pp
.Qq Ar id Ns Cm :set_dash Bro Ar n Ns | Ns Cm = Ns Ar n Ns | Ns Ar n Ns Cm < Ns Ar m Brc l1on l1off l2on l2off ...
resets the dash pattern to a line with arbitrary on/off portions.
.Pp
.Qq Ar id Ns Cm :set_dash Bro Ar n Ns | Ns Cm = Ns Ar n Ns | Ns Ar n Ns Cm < Ns Ar m Brc
resets the dash pattern to a solid line.
.Pp
.Qo Ar id Ns Cm :set_font_face Bro Ar n Ns | Ns Cm = Ns Ar n Ns | Ns Ar n Ns Cm < Ns Ar m Brc
.Brq Cm normal | italic | oblique
.Brq Cm normal | bold
.Bq Cm family
.Qc
sets the font face for subsequent calls of
.Ar id Ns Cm :show_text .
.Pp
.Qq Ar id Ns Cm :set_font_size Bro Ar n Ns | Ns Cm = Ns Ar n Ns | Ns Ar n Ns Cm < Ns Ar m Brc size
sets the font size for subsequent calls of
.Ar id Ns Cm :show_text .
.Pp
.Qq Ar id Ns Cm :set_line_cap Bro Ar n Ns | Ns Cm = Ns Ar n Ns | Ns Ar n Ns Cm < Ns Ar m Brc Brq Cm butt | round | square
sets the line cap style.
Default is
.Cm butt .
.Pp
.Qq Ar id Ns Cm :set_line_join Bro Ar n Ns | Ns Cm = Ns Ar n Ns | Ns Ar n Ns Cm < Ns Ar m Brc Brq Cm miter | round | bevel
sets the line junction style.
Default is
.Cm miter .
.Pp
.Qq Ar id Ns Cm :set_line_width Bro Ar n Ns | Ns Cm = Ns Ar n Ns | Ns Ar n Ns Cm < Ns Ar m Brc width
sets the line width.
Default
.Ar width
is 2.
.Pp
.Qq Ar id Ns Cm :set_source_rgba Bro Ar n Ns | Ns Cm = Ns Ar n Ns | Ns Ar n Ns Cm < Ns Ar m Brc color
sets the color.
.Ar color
is in the format used with
.Sx GtkColorButton .
.Pp
.Qq Ar id Ns Cm :show_text Bro Ar n Ns | Ns Cm = Ns Ar n Ns | Ns Ar n Ns Cm < Ns Ar m Brc text
writes
.Ar text ,
beginning at the current point.
.Pp
.Qq Ar id Ns Cm :stroke Bro Ar n Ns | Ns Cm = Ns Ar n Ns | Ns Ar n Ns Cm < Ns Ar m Brc
strokes the current path and clears it.
.Pp
.Qq Ar id Ns Cm :stroke_preserve Bro Ar n Ns | Ns Cm = Ns Ar n Ns | Ns Ar n Ns Cm < Ns Ar m Brc
strokes the current path without clearing it.
.Pp
.Qq Ar id Ns Cm :transform Bro Ar n Ns | Ns Cm = Ns Ar n Ns | Ns Ar n Ns Cm < Ns Ar m Brc Bq Ar xx yx xy yy x0 y0
modifies the current transformation matrix such that
.Pp
.Dl Va x' Li = Ar xx Va x Li + Ar xy Va y Li + Ar x0 ,
.Dl Va y' Li = Ar yx Va y Li + Ar yy Va y Li + Ar y0 .
.Pp
Default is resetting the current transformation matrix.
.Pp
.Qq Ar id Ns Cm :translate Bro Ar n Ns | Ns Cm = Ns Ar n Ns | Ns Ar n Ns Cm < Ns Ar m Brc Ar tx ty
translates the user space origin by
.Pq Ar tx , ty .
.It Feedback
none
.El
.Ss GtkEntry
.Bl -tag -width "commands "
.It Commands
.Qq Ar id Ns Cm :set_text Ar string
replaces the user-editable text with
.Ar string .
.Pp
.Qq Ar id Ns Cm :set_placeholder_text Ar string
sets the
.Ar string
that is displayed when the entry is empty and unfocused.
.It Feedback
.Qq Ar id Ns Cm \&:text Ar text ,
once for each change of
.Ar text .
.El
.Ss GtkEventBox
.Ar x , y
are mouse pointer coordinates relative to the
.Cm GtkEventBox .
.Bl -tag -width "commands "
.It Commands
none
.It Feedback
.Qq Ar id Ns Cm \&:button_press Ar b x y ,
.Qq Ar id Ns Cm \&:button_release Ar b x y
where
.Ar b
is the mouse button (normally 1, 2, or 3 for the left, middle, and
right button; others may exist).
.Pp
.Qq Ar id Ns Cm \&:motion Ar x y
is reported repeatedly while the mouse is being moved with a button
pressed.
.Pp
.Qq Ar id Ns Cm \&:key_press Ar key ,
.Ar key
being the key's name
.Po e.g.
.Ql Control_L ,
.Ql Tab ,
.Ql a
.Pc .
.El
.Ss GtkExpander
.Bl -tag -width "commands "
.It Commands
.Qq Ar id Ns Cm :set_label Ar string
replaces the expander label text with
.Ar string .
.Pp
.Qq Ar id Ns Cm :set_expanded Brq Cm 0 |  1
hides
.Pq Cm 0
the child widget, or makes it visible
.Pq Cm 1 .
.It Feedback
none
.El
.Ss GtkFileChooserButton
.Bl -tag -width "commands "
.It Commands
.Qq Ar id Ns Cm :set_filename Ar path
preselects
.Ar path
to the extent it exists.
.It Feedback
.Qq Ar id Ns Cm \&:file Ar pathname
if the selection has changed.
.El
.Ss GtkFileChooserDialog
A
.Cm GtkFileChooserDialog
with id
.Ar foo
will be invoked by a
.Sx GtkMenuItem
or a
.Sx GtkImageMenuItem
with id
.Ar foo Ns Cm _invoke .
.Pp
The
.Cm GtkFileChooserDialog
should have an
.Sq OK
.Sx GtkButton
with id
.Ar foo Ns Cm _ok
.Po Cm main_ok
if the dialog is the sole window of the GUI and therefore named
.Cm main
.Pc .
.Pp
The
.Cm GtkFileChooserDialog
may have a
.Sq Cancel
.Sx GtkButton
with id
.Ar foo Ns Cm _cancel
.Po Cm main_cancel
if the dialog is the sole window of the GUI and therefore named
.Cm main
.Pc .
.Pp
The
.Cm GtkFileChooserDialog
may have an
.Sq Apply
.Sx GtkButton
with id
.Ar foo Ns Cm _apply
.Po Cm main_apply
if the dialog is the sole window of the GUI and therefore named
.Cm main
.Pc .
.Bl -tag -width "commands "
.It Commands
.Qq Ar id Ns Cm :set_filename Ar path
preselects
.Ar path
to the extent it exists.
.Pp
.Qq Ar id Ns Cm :set_current_name Ar string
makes
.Ar string
the suggested filename, which may not yet exist.
.Ar string
should either resemble an absolute path, or the
.Ar directory
must be set separately by
.Ar id Ns Cm :set_filename Ar directory .
.Pp
.Qq Ar id Ns Cm :set_title Ar string
replaces the text in the title bar with
.Ar string .
.Pp
.Qq Ar id Ns Cm :resize Bq Ar width height
changes the size of the dialog window to
.Ar width
x
.Ar height
pixels if specified, or to the default size.
.Pp
.Qq Ar id Ns Cm :move Ar x y
moves the dialog window to position
.Pq Ar x , y .
.Pp
.Qq Ar id Ns Cm :fullscreen
and
.Qq Ar id Ns Cm :unfullscreen
switch fullscreen mode on and off.
.It Feedback
.Qq Ar id Ns Cm :file Ar pathname
and/or
.Qq Ar id Ns Cm :folder Ar pathname
.Pp
.Qq Ar id Ns Cm \&:closed
if the
.Cm GtkFileChooserDialog
window was closed by the window manager.
.El
.Ss GtkFontButton
.Bl -tag -width "commands "
.It Commands
.Qq Ar id Ns Cm :set_font_name Ar fontname
preselects the font.
.It Feedback
.Qq Ar id Ns Cm \&:font Ar fontname
.El
.Ss GtkFrame
.Bl -tag -width "commands "
.It Commands
.Qq Ar id Ns Cm :set_label Ar text
replaces the frame label text with
.Ar string .
.It Feedback
none
.El
.Ss GtkImage
.Bl -tag -width "commands "
.It Commands
.Qq Ar id Ns Cm :set_from_icon_name Ar icon-name
replaces the image with one of the standard icons.
.Pp
.Qq Ar id Ns Cm :set_from_file Ar path
replaces the image by the one found at
.Ar path Ns .
.It Feedback
none
.El
.Ss GtkLabel
.Bl -tag -width "commands "
.It Commands
.Qq Ar id Ns Cm :set_text Ar string
replaces the label text with
.Ar string .
.It Feedback
none
.El
.Ss GtkMenuItem, GtkImageMenuItem
.Bl -tag -width "commands "
.It Commands
none
.It Feedback
A
.Cm GtkMenuItem
or
.Cm GtkImageMenuItem
with id
.Ar foo Ns Cm _invoke
will invoke the
.Sx GtkDialog
or
.Sx GtkFileChooserDialog
with id
.Ar foo
if it exists.
If there isn't any dialog attached to the
.Cm GtkMenuItem ,
it reports
.Qq Ar id Ns Cm \&:active Ar label .
.El
.Ss GtkNotebook
.Bl -tag -width "commands "
.It Commands
.Qq Ar id Ns Cm :set_current_page Ar n
switches to zero-based page number
.Ar n .
.It Feedback
none
.El
.Ss GtkPrintUnixDialog
.Bl -tag -width "commands "
.It Commands
.Qq Ar id Ns Cm :print Ar file.ps
opens the print dialog.
Pressing the
.Ql Print
button sends
.Ar file.ps
to the printer the user selected in the dialog.
.It Feedback
.Qq Ar id Ns Cm \&:closed
if the
.Cm GtkPrintUnixDialog
window was closed by the window manager.
.El
.Ss GtkProgressBar
.Bl -tag -width "commands "
.It Commands
.Qq Ar id Ns Cm :set_fraction Ar x
moves the progress bar to
.Ar x
.Pq between 0 and 1 .
.Pp
.Qq Ar id Ns Cm :set_text Bq Ar string
replaces the text of the progress bar with
.Ar string .
Default is the progress percentage.
.It Feedback
none
.El
.Ss GtkRadioButton
.Bl -tag -width "commands "
.It Commands
.Qq Ar id Ns Cm :set_active 1
switches the button on.
All other buttons of the same group will go off automatically.
.Pp
.Qq Ar id Ns Cm :set_label Ar string
replaces the button text with
.Ar string .
.It Feedback
.Qq Ar id Ns Cm \&:1
if switched on, or
.Qq Ar id Ns Cm \&:0
otherwise.
.El
.Ss GtkScale
.Bl -tag -width "commands "
.It Commands
.Qq Ar id Ns Cm :set_value Ar x
moves the slider to value
.Ar x .
.Pp
.Qq Ar id Ns Cm :set_fill_level Bq Ar x
moves the fill level indicator to value
.Ar x .
Default is hiding the fill level indicator.
.Pp
.Qq Ar id Ns Cm :set_range Ar min max
changes the range.
.Pp
.Qq Ar id Ns Cm :set_increments Ar step page
sets the steps the slider moves while pressing arrow keys and
.Ql Page_Up Ns
.Pf / Ql Page_Down ,
respectively.
.It Feedback
.Qq Ar id Ns Cm \&:value Ar number
.El
.Ss GtkScrolledWindow
.Bl -tag -width "commands "
.It Commands
.Qq Ar id Ns Cm :hscroll Ar position
and
.Qq Ar id Ns Cm :vscroll Ar position
scroll
.Ar position
to the left or top edge of the
.Cm GtkScrolledWindow ,
respectively.
.Pp
.Qq Ar id Ns Cm :hscroll_to_range Ar pos0 pos1
and
.Qq Ar id Ns Cm :vscroll_to_range Ar pos0 pos1
scroll, if necessary, the range between
.Ar pos0
and
.Ar pos1
into the
.Cm GtkScrolledWindow .
If the range is greater than the window, the initial part of the range
will be visible.
.It Feedback
none
.El
.Ss GtkSocket
.Cm GtkSocket
may be unsupported by Glade, but its definition can be inserted
manually into the GtkBuilder
.Pq Pa .ui
file:
.Bd -literal -offset indent
<child>
  <object class="GtkSocket" id="socket1">
    <property name="visible">True</property>
    <property name="can_focus">True</property>
  </object>
  <packing>
    <property name="expand">True</property>
    <property name="fill">True</property>
    <property name="position">1</property>
  </packing>
</child>
.Ed
.Bl -tag -width "commands "
.It Commands
.Qq Ar id Ns Cm :id
requests a feedback message containing the socket
.Ar xid .
.It Feedback
.Qq Ar id Ns Cm :id Ar xid
can be used by another process to XEmbed its widgets into the
.Cm GtkSocket .
.Pp
.Qq Ar id Ns Cm :plug-added ,
.Qo
.Ar id Ns
.Cm :plug-removed
.Qc .
Notification that the other process has inserted its widgets into or
removed them from the
.Cm GtkSocket .
.El
.Ss GtkSpinButton
.Bl -tag -width "commands "
.It Commands
.Qq Ar id Ns Cm :set_text Ar string
sets the selected value to
.Ar string .
.Pp
.Qq Ar id Ns Cm :set_range Ar min max
changes the range.
.Pp
.Qq Ar id Ns Cm :set_increments Ar step page
sets the steps the value changes while pressing arrow keys/left mouse
button, and
.Ql Page_Up Ns
.Pf / Ql Page_Down Ns
/middle mouse button,
respectively.
.It Feedback
.Qq Ar id Ns Cm \&:text Ar text
.El
.Ss GtkSpinner
.Bl -tag -width "commands "
.It Commands
.Qq Ar id Ns Cm :start
and
.Qq Ar id Ns Cm :stop
start and stop the spinner.
.It Feedback
none
.El
.Ss GtkStatusbar
The context parameter
.Ar c
is an arbitrary non-whitespace string.
.Bl -tag -width "commands "
.It Commands
.Qq Ar id Ns Cm :push_id Ar c string ,
.Qq Ar id Ns Cm :push Ar string
associate
.Ar string
with context parameter
.Ar c
or
.Ql 0 ,
respectively, and display it in the statusbar.
.Pp
.Qq Ar id Ns Cm :pop_id Ar c ,
.Qq Ar id Ns Cm :pop
remove the latest entry associated with context parameter
.Ar c
or
.Ql 0 ,
respectively, from the statusbar.
.Pp
.Qq Ar id Ns Cm :remove_all_id Ar c ,
.Qq Ar id Ns Cm :remove_all
remove the entries associated with context parameter
.Ar c
or
.Ql 0 ,
respectively, from the statusbar.
.It Feedback
none
.El
.Ss GtkSwitch
.Bl -tag -width "commands "
.It Commands
.Qq Ar id Ns Cm :set_active Brq Cm 0 | 1
turns the switch off
.Pq Cm 0
or on
.Pq Cm 1 .
.It Feedback
.Qq Ar id Ns Cm \&:1
if switched on, or
.Qq Ar id Ns Cm \&:0
otherwise.
.El
.Ss GtkTextView
There should be a dedicated
.Sx GtkButton
for sending (parts of) the text.
If the id of the
.Cm GtkTextView
is
.Ar foo ,
a
.Sx GtkButton
with id
.Ar foo Ns Cm _send_text
will send the content of the
.Cm GtkTextView ;
a
.Sx GtkButton
with id
.Ar foo Ns Cm _send_selection
will send the highlighted part the
.Cm GtkTextView .
.Bl -tag -width "commands "
.It Commands
.Qq Ar id Ns Cm :set_text Ar string
replaces the user-editable text with (potentially empty)
.Ar string Ns .
.Pp
.Qq Ar id Ns Cm :delete
deletes the text.
.Pp
.Qq Ar id Ns Cm :insert_at_cursor Ar string
inserts
.Ar string
at cursor position.
.Pp
.Qq Ar id Ns Cm :place_cursor Brq Ar position | Cm end
places the text cursor at
.Ar position
or at the end of the text.
.Pp
.Qq Ar id Ns Cm :place_cursor_at_line Ar line
places the text cursor at the beginning of
.Ar line .
.Pp
.Qq Ar id Ns Cm :scroll_to_cursor
scrolls to the cursor position if necessary.
.Pp
.Qq Ar id Ns Cm :save Ar file
stores in
.Ar file
a
.Nm
command containing the text.
.It Feedback
.Qq Ar button_id Ns Cm :text Ar text ,
.Ar button_id
being the id of the
.Sx GtkButton .
Line endings in
.Ar text
are replaced by
.Cm \en ,
and backslashes are replaced by
.Cm \e\e .
.El
.Ss GtkToggleButton
.Bl -tag -width "commands "
.It Commands
.Qq Ar id Ns Cm :set_active Brq Cm 0 | 1
switches the button off
.Pq Cm 0
or on
.Pq Cm 1 .
.Pp
.Qq Ar id Ns Cm :set_label Ar string
replaces the button text with
.Ar string .
.It Feedback
.Qq Ar id Ns Cm \&:1
if switched on, or
.Qq Ar id Ns Cm \&:0
otherwise.
.El
.Ss GtkTreeView
.Nm
can deal with columns of type
.Cm gboolean , gint , guint , glong , gulong , gint64 , guint64 , gfloat , gdouble ,
and
.Cm gchararray .
.Pp
.Ar row
and
.Ar column
refer to the underlying model
.Cm ( GtkListStore
or
.Cm GtkTreeStore ) .
.Ar row
is a sequence of one or more colon-separated integers, e.g.
.Ql 3
or
.Ql 0:0:1 .
.Bl -tag -width "commands "
.It Commands
.Qq Ar id Ns Cm :set Ar row column data
replaces the content at
.Pq Ar row , column
with
.Ar data
(which should be compatible with the type of
.Ar column ) .
If necessary, new tree nodes are created to obtain the minimal tree
structure needed to support
.Ar row .
.Pp
.Qq Ar id Ns Cm :insert_row Brq Ar row Bo Cm as_child Bc | Cm end
inserts a new, empty row; either as a sibling of
.Ar row
at position
.Ar row ,
or as a child of
.Ar row ,
or at the end of the list, respectively.
.Pp
.Qq Ar id Ns Cm :move_row Ar origin Brq Ar destination | Cm end
moves the row at
.Ar origin
within its current level to
.Ar destination
or to the end.
.Pp
.Qq Ar id Ns Cm :remove_row Ar row
removes the row at position
.Ar row .
.Pp
.Qq Ar id Ns Cm :clear
removes all rows.
.Pp
.Qq Ar id Ns Cm :expand Ar row
expands one level of the subtree below
.Ar row .
.Pp
.Qq Ar id Ns Cm :expand_all Bq Ar row
expands the subtree below
.Ar row ,
or the whole tree.
.Pp
.Qq Ar id Ns Cm :collapse Bq Ar row
collapses the subtree below
.Ar row ,
or the whole tree.
.Pp
.Qq Ar id Ns Cm :set_cursor Bq Ar row
sets the cursor to
.Ar row ,
or unsets it.
.Pp
.Qq Ar id Ns Cm :scroll Ar row column
scrolls the cell at
.Pq Ar row , column
into view.
.Pp
.Qq Ar id Ns Cm :save Ar file
stores the content of the underlying model as a sequence of
.Nm
commands into
.Ar file .
.It Feedback
.Qq Ar id Ns Cm \&:clicked
.Pp
.Qq Ar id Ns Cm \&: Ns Ar column_type row column value ,
one message per cell in the underlying model for each selected row; or
.Pp
.Qq Ar id Ns Cm \&: Ns Ar column_type row column new_value ,
if the cell at
.Pq Ar row , column
has been edited.
.El
.Ss GtkTreeViewColumn
.Bl -tag -width "commands "
.It Commands
none
.It Feedback
.Qq Ar id Ns Cm \&:clicked
.El
.Ss GtkWindow
.Bl -tag -width "commands "
.It Commands
.Qq Ar id Ns Cm :set_title Ar string
replaces the text in the title bar with
.Ar string .
.Pp
.Qq Ar id Ns Cm :resize Bq Ar width height
changes the window size to
.Ar width
x
.Ar height
pixels if specified, or to the default size.
.Pp
.Qq Ar id Ns Cm :move Ar x y
moves the window to position
.Pq Ar x , y .
.Pp
.Qq Ar id Ns Cm :fullscreen
and
.Qq Ar id Ns Cm :unfullscreen
switch fullscreen mode on and off.
.It Feedback
.Qq Ar id Ns Cm \&:closed
if the
.Cm GtkWindow
was closed by the window manager.
.El
.Sh EXIT STATUS
.Ex -std
.Sh EXAMPLES
.Ss Discovering Pipeglade Interactively
Suppose the interface in
.Pa ./pipeglade.ui
has a
.Sx GtkLabel Ql label1
and a
.Sx GtkButton Ql button1 .
After invoking
.Pp
.Dl pipeglade
.Pp
and clicking the
.Sx GtkButton , Ql button1:clicked
will be reported on the terminal.
Typing
.Pp
.Dl label1:set_text The Button
.Pp
will change the text shown on the label into
.Ql The Button .
.Ss One-Shot File Dialog
Suppose the interface in
.Pa ./simple_open.ui
contains a
.Sx GtkFileChooserDialog
with an
.Sq OK
.Sx GtkButton
whose id is
.Ql main_ok .
Invoking
.Pp
.Dl pipeglade -u simple_open.ui
.Pp
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 Ql label1 ,
then
.Bd -literal -offset indent
pipeglade -u simple_dialog.ui <<< \e
    "label1:set_text NOW READ THIS!"
.Ed
will set the label text accordingly and wait for user input.
.Ss Continuous Input
The following shell command displays a running clock:
.Bd -literal -offset indent
while true; do
    echo "label1:set_text `date`";
    sleep 1;
done | pipeglade -u simple_dialog.ui
.Ed
.Ss Continuous Input and Output
The following shell script fragment sets up
.Nm
for continuous communication with another program,
.Pa main_prog :
.Bd -literal -offset indent
pipeglade -i in.fifo -o out.fifo -b
main_prog <out.fifo >in.fifo
.Ed
.Sh SEE ALSO
.Xr dialog 1 ,
.Xr glade 1 ,
.Xr gxmessage 1 ,
.Xr kdialog 1 ,
.Xr whiptail 1 ,
.Xr xmessage 1 ,
.Xr zenity 1
.Sh AUTHOR
.Nm
was written by
.An Bert Burgemeister
.Aq Mt trebbu@googlemail.com .
.Sh BUGS
Due to what appears to be a bug in cairo v1.14.0,
.Nm
used with this library version occasionally crashes on
.Cm GtkDrawingArea
commands.