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 .RB [ -in ]
   8 .RB [ \-t
   9 .IR title ]
  10 .RB [ \-p
  11 .IR prompt ]
  12 .RB [ \-d
  13 .IR default ]
  14 .RB [ \-l | \-H
  15 .IR file ]
  16 .RB [ \- m
  17 .IR max ]
  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
  50 .SS Options
  51 .TP 5
  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
  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 .
  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.
 102 .SH AUTHOR
 103 Mark Wooding (mdw@nsict.org).
 104 .SH BUGS
 105 Hopefully none.