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

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