[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
.RB [ -in ]
.RB [ \-t
.IR title ]
.RB [ \-p
.IR prompt ]
.RB [ \-d
.IR default ]
.RB [ \-l | \-H
.IR file ]
.RB [ \- m
.IR max ]
.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 \-i, \-\-invisible
Don't echo characters to the screen when they're typed.  Useful when
requesting passwords and similar secrets.
.TP 5
.BI "\-t, \-\-title " title
Sets the title of the dialogue box to
.IR title .
The default title is
.RB ` "Input request" '.
.TP 5
.BI "\-p, \-\-prompt " prompt
Sets the prompt string in the dialogue box to
.IR prompt .
The default is to have no prompt string.
.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
.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 "\-H, \-\-history " file
Reads a file and displays the contents in a drop-down list, as for
.B \-\-list
above.  Once the user has entered a string, a new list written to 
.I file
containing the newly entered string as the first item; other lines
matching the newly entered string are not written.
.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.
.SH AUTHOR
Mark Wooding (mdw@nsict.org).
.SH BUGS
Hopefully none.
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
0a47c222	7	.RB [ -in ]
90b2c5d4	8	.RB [ \-t
	9	.IR title ]
	10	.RB [ \-p
	11	.IR prompt ]
	12	.RB [ \-d
	13	.IR default ]
0a47c222	14	.RB [ \-l \| \-H
	15	.IR file ]
	16	.RB [ \- m
	17	.IR max ]
90b2c5d4	18	.SH DESCRIPTION
	19	The
	20	.B xgetline
	21	program reads a line of text from the user via a pretty GTK dialogue
	22	box. The title bar contents, prompt string, and default text are all
	23	configurable. If the user enters a string and clicks the
	24	.B OK
	25	button (or
	26	presses
	27	.IR enter ),
	28	the string is echoed to standard output and
	29	.B xgetline
	30	returns an exit status of zero. If the user cancels the dialogue box
	31	(by closing it, or pressing
	32	.IR escape ),
	33	.B xgetline
	34	echoes nothing and returns an exit status of one.
	35	.PP
	36	The
	37	.B xgetline
	38	program is intended to be used in window manager configuration files, to
	39	allow users to fill in bits of text (e.g., hostnames or shell commands)
	40	in generally useful places. For example, the author has the following
	41	shell command attached to a hotkey:
	42	.PP
	43	.RS 5
	44	.ft B
	45	.nf
	46	cmd=`xgetline -t "Shell command in window" -p "Command:"` &&
	47	xterm -T "$cmd" -e sh -c "$cmd"
	48	.ft R
	49	.fi
e571b0f1	50	.SS Options
90b2c5d4	51	.TP 5
f3b35b6b	52	.B \-i, \-\-invisible
	53	Don't echo characters to the screen when they're typed. Useful when
	54	requesting passwords and similar secrets.
	55	.TP 5
90b2c5d4	56	.BI "\-t, \-\-title " title
	57	Sets the title of the dialogue box to
	58	.IR title .
	59	The default title is
	60	.RB ` "Input request" '.
	61	.TP 5
	62	.BI "\-p, \-\-prompt " prompt
	63	Sets the prompt string in the dialogue box to
	64	.IR prompt .
	65	The default is to have no prompt string.
	66	.TP 5
	67	.BI "\-d, \-\-default " default
	68	Sets the default text in the entry field to
	69	.IR default .
0a47c222	70	The default default is the first item in the empty string. The special
	71	default string
	72	.RB ` @ '
	73	sets the default to be the first item in the history list, if one is
	74	supplied.
	75	.TP 5
	76	.BI "\-l, \-\-list " file
	77	Reads a list of alternatives from
	78	.I file
	79	and displays them in a drop-down list box. The user can rapidly select
	80	an item from the drop-down list using the mouse or cursor keys. The
	81	file is not modified (but see the
	82	.B \-\-history
	83	option below).
	84	.TP 5
	85	.B "\-n, \-\-no-choice"
	86	One of the items from the selection list must be chosen; the user may
	87	not type an entry in directly.
	88	.TP 5
	89	.BI "\-H, \-\-history " file
	90	Reads a file and displays the contents in a drop-down list, as for
	91	.B \-\-list
	92	above. Once the user has entered a string, a new list written to
	93	.I file
	94	containing the newly entered string as the first item; other lines
	95	matching the newly entered string are not written.
	96	.TP 5
	97	.BI "\-m, \-\-histmax " max
	98	When writing an updated history file, do not write more than
	99	.I max
	100	lines. The default is 20; a value of 0 disables a length limit on the
	101	history file.
90b2c5d4	102	.SH AUTHOR
	103	Mark Wooding (mdw@nsict.org).
	104	.SH BUGS
	105	Hopefully none.