mdw@git.distorted.org.uk Git - xtoys/blame_incremental

... / ...

Commit	Line	Data
	1	.\" --nroff--
	2	.TH xgetline 1 "15 November 1998" "Straylight/Edgeware" "xtoys"
	3	.SH NAME
	4	xgetline \- request a line of text in an X dialogue box
	5	.SH SYNOPSIS
	6	.B xgetline
	7	.RI [ gtk-options ...]
	8	.RB [ -Hin ]
	9	.RB [ \- M
	10	.IR max ]
	11	.RB [ \-d
	12	.IR default ]
	13	.RB [ \-l
	14	.IR file ]
	15	.RB [ \-p
	16	.IR prompt ]
	17	.RB [ \-t
	18	.IR title ]
	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
	47	cmd=$(xgetline -t "Shell command in window" -p "_Command:") &&
	48	xterm -T "$cmd" -e sh -c "$cmd"
	49	.ft R
	50	.fi
	51	.SS Options
	52	.TP 5
	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 .
	59	.TP 5
	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.
	65	.TP 5
	66	.BI "\-d, \-\-default " default
	67	Sets the default text in the entry field to
	68	.IR default .
	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
	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
	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
	92	.BI "\-p, \-\-prompt " prompt
	93	Sets the prompt string in the dialogue box to
	94	.IR prompt .
	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.
	101	.TP 5
	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" '.
	107	.SH BUGS
	108	Hopefully none.
	109	.SH SEE ALSO
	110	.BR gtk-options (7).
	111	.SH AUTHOR
	112	Mark Wooding (mdw@distorted.org.uk).