mdw@git.distorted.org.uk Git - xtoys/blob - xgetline.1

   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).