[xtoys] / xgetline.1

.\" -*-nroff-*-
.TH xgetline 1 "15 November 1998" "Straylight/Edgeware" "xtoys"
.SH NAME
xgetline \- request a line of text in an X dialogue box
.SH SYNOPSIS
.B xgetline
.RI [ gtk-options ...]
.RB [ -Hin ]
.RB [ \- M
.IR max ]
.RB [ \-d
.IR default ]
.RB [ \-l
.IR file ]
.RB [ \-p
.IR prompt ]
.RB [ \-t
.IR title ]
.SH DESCRIPTION
The
.B xgetline
program reads a line of text from the user via a pretty GTK dialogue
box.  The title bar contents, prompt string, and default text are all
configurable.  If the user enters a string and clicks the
.B OK
button (or
presses
.IR enter ),
the string is echoed to standard output and
.B xgetline
returns an exit status of zero.  If the user cancels the dialogue box
(by closing it, or pressing
.IR escape ),
.B xgetline
echoes nothing and returns an exit status of one.
.PP
The
.B xgetline
program is intended to be used in window manager configuration files, to
allow users to fill in bits of text (e.g., hostnames or shell commands)
in generally useful places.  For example, the author has the following
shell command attached to a hotkey:
.PP
.RS 5
.ft B
.nf
cmd=$(xgetline -t "Shell command in window" -p "_Command:") &&
  xterm -T "$cmd" -e sh -c "$cmd"
.ft R
.fi
.SS Options
.TP 5
.B "\-H, \-\-history"
With
.BR \-l ,
update the file with the newly entered line at the top.  Other lines
matching the newly entered string are not written.  No effect without
.BR \-l .
.TP 5
.BI "\-M, \-\-histmax " max
When writing an updated history file, do not write more than
.I max
lines.  The default is 20; a value of 0 disables a length limit on the
history file.
.TP 5
.BI "\-d, \-\-default " default
Sets the default text in the entry field to
.IR default .
The default default is the first item in the empty string.  The special
default string
.RB ` @ '
sets the default to be the first item in the history list, if one is
supplied.
.TP 5
.B \-i, \-\-invisible
Don't echo characters to the screen when they're typed.  Useful when
requesting passwords and similar secrets.
.TP 5
.BI "\-l, \-\-list " file
Reads a list of alternatives from
.I file
and displays them in a drop-down list box.  The user can rapidly select
an item from the drop-down list using the mouse or cursor keys.  The
file is not modified (but see the
.B \-\-history
option below).
.TP 5
.B "\-n, \-\-no-choice"
One of the items from the selection list must be chosen; the user may
not type an entry in directly.
.TP 5
.BI "\-p, \-\-prompt " prompt
Sets the prompt string in the dialogue box to
.IR prompt .
If the prompt string contains an underscore character
.RB ` _ ',
then the following character appears underlined; pressing Alt and the
leftmost underlined character (the `mnemonic') moves the input focus to
the entry widget.  If you want a literal underscore, type two
consecutive underscores.  The default is to have no prompt string.
.TP 5
.BI "\-t, \-\-title " title
Sets the title of the dialogue box to
.IR title .
The default title is
.RB ` "Input request" '.
.SH BUGS
Hopefully none.
.SH SEE ALSO
.BR gtk-options (7).
.SH AUTHOR
Mark Wooding (mdw@distorted.org.uk).
Commit	Line	Data
b6eb57e6	1	.\" --nroff--
ec19d7af	2	.TH xgetline 1 "15 November 1998" "Straylight/Edgeware" "xtoys"
90b2c5d4	3	.SH NAME
	4	xgetline \- request a line of text in an X dialogue box
	5	.SH SYNOPSIS
	6	.B xgetline
bce8c6ee MW	7	.RI [ gtk-options ...]
	8	.RB [ -Hin ]
	9	.RB [ \- M
	10	.IR max ]
90b2c5d4	11	.RB [ \-d
90b2c5d4	12	.IR default ]
bce8c6ee	13	.RB [ \-l
0a47c222	14	.IR file ]
bce8c6ee MW	15	.RB [ \-p
	16	.IR prompt ]
	17	.RB [ \-t
	18	.IR title ]
90b2c5d4	19	.SH DESCRIPTION
	20	The
	21	.B xgetline
	22	program reads a line of text from the user via a pretty GTK dialogue
	23	box. The title bar contents, prompt string, and default text are all
	24	configurable. If the user enters a string and clicks the
	25	.B OK
	26	button (or
	27	presses
	28	.IR enter ),
	29	the string is echoed to standard output and
	30	.B xgetline
	31	returns an exit status of zero. If the user cancels the dialogue box
	32	(by closing it, or pressing
	33	.IR escape ),
	34	.B xgetline
	35	echoes nothing and returns an exit status of one.
	36	.PP
	37	The
	38	.B xgetline
	39	program is intended to be used in window manager configuration files, to
	40	allow users to fill in bits of text (e.g., hostnames or shell commands)
	41	in generally useful places. For example, the author has the following
	42	shell command attached to a hotkey:
	43	.PP
	44	.RS 5
	45	.ft B
	46	.nf
583efdd3	47	cmd=$(xgetline -t "Shell command in window" -p "_Command:") &&
90b2c5d4	48	xterm -T "$cmd" -e sh -c "$cmd"
	49	.ft R
	50	.fi
e571b0f1	51	.SS Options
90b2c5d4	52	.TP 5
bce8c6ee MW	53	.B "\-H, \-\-history"
	54	With
	55	.BR \-l ,
	56	update the file with the newly entered line at the top. Other lines
	57	matching the newly entered string are not written. No effect without
	58	.BR \-l .
f3b35b6b	59	.TP 5
bce8c6ee MW	60	.BI "\-M, \-\-histmax " max
	61	When writing an updated history file, do not write more than
	62	.I max
	63	lines. The default is 20; a value of 0 disables a length limit on the
	64	history file.
90b2c5d4	65	.TP 5
	66	.BI "\-d, \-\-default " default
	67	Sets the default text in the entry field to
	68	.IR default .
0a47c222	69	The default default is the first item in the empty string. The special
	70	default string
	71	.RB ` @ '
	72	sets the default to be the first item in the history list, if one is
	73	supplied.
	74	.TP 5
bce8c6ee MW	75	.B \-i, \-\-invisible
	76	Don't echo characters to the screen when they're typed. Useful when
	77	requesting passwords and similar secrets.
	78	.TP 5
0a47c222	79	.BI "\-l, \-\-list " file
	80	Reads a list of alternatives from
	81	.I file
	82	and displays them in a drop-down list box. The user can rapidly select
	83	an item from the drop-down list using the mouse or cursor keys. The
	84	file is not modified (but see the
	85	.B \-\-history
	86	option below).
	87	.TP 5
	88	.B "\-n, \-\-no-choice"
	89	One of the items from the selection list must be chosen; the user may
	90	not type an entry in directly.
	91	.TP 5
bce8c6ee MW	92	.BI "\-p, \-\-prompt " prompt
	93	Sets the prompt string in the dialogue box to
	94	.IR prompt .
583efdd3 MW	95	If the prompt string contains an underscore character
	96	.RB ` _ ',
	97	then the following character appears underlined; pressing Alt and the
	98	leftmost underlined character (the `mnemonic') moves the input focus to
	99	the entry widget. If you want a literal underscore, type two
	100	consecutive underscores. The default is to have no prompt string.
0a47c222	101	.TP 5
bce8c6ee MW	102	.BI "\-t, \-\-title " title
	103	Sets the title of the dialogue box to
	104	.IR title .
	105	The default title is
	106	.RB ` "Input request" '.
90b2c5d4	107	.SH BUGS
90b2c5d4	108	Hopefully none.
bce8c6ee MW	109	.SH SEE ALSO
bce8c6ee MW	110	.BR gtk-options (7).
f6795c17 MW	111	.SH AUTHOR
f6795c17 MW	112	Mark Wooding (mdw@distorted.org.uk).