rltech.texi

android-w.song.android.widget

Returns the number of characters deleted.
@end deftypefun

@deftypefun {char *} rl_copy_text (int start, int end)
Return a copy of the text between @var{start} and @var{end} in
the current line.
@end deftypefun

@deftypefun int rl_kill_text (int start, int end)
Copy the text between @var{start} and @var{end} in the current line
to the kill ring, appending or prepending to the last kill if the
last command was a kill command.  The text is deleted.
If @var{start} is less than @var{end},
the text is appended, otherwise prepended.  If the last command was
not a kill, a new kill ring slot is used.
@end deftypefun

@deftypefun int rl_push_macro_input (char *macro)
Cause @var{macro} to be inserted into the line, as if it had been invoked
by a key bound to a macro.  Not especially useful; use
@code{rl_insert_text()} instead.
@end deftypefun

@node Character Input
@subsection Character Input

@deftypefun int rl_read_key (void)
Return the next character available from Readline's current input stream.
This handles input inserted into
the input stream via @var{rl_pending_input} (@pxref{Readline Variables})
and @code{rl_stuff_char()}, macros, and characters read from the keyboard.
While waiting for input, this function will call any function assigned to
the @code{rl_event_hook} variable.
@end deftypefun

@deftypefun int rl_getc (FILE *stream)
Return the next character available from @var{stream}, which is assumed to
be the keyboard.
@end deftypefun

@deftypefun int rl_stuff_char (int c)
Insert @var{c} into the Readline input stream.  It will be "read"
before Readline attempts to read characters from the terminal with
@code{rl_read_key()}.  Up to 512 characters may be pushed back.
@code{rl_stuff_char} returns 1 if the character was successfully inserted;
0 otherwise.
@end deftypefun

@deftypefun int rl_execute_next (int c)
Make @var{c} be the next command to be executed when @code{rl_read_key()}
is called.  This sets @var{rl_pending_input}.
@end deftypefun

@deftypefun int rl_clear_pending_input (void)
Unset @var{rl_pending_input}, effectively negating the effect of any
previous call to @code{rl_execute_next()}.  This works only if the
pending input has not already been read with @code{rl_read_key()}.
@end deftypefun

@deftypefun int rl_set_keyboard_input_timeout (int u)
While waiting for keyboard input in @code{rl_read_key()}, Readline will
wait for @var{u} microseconds for input before calling any function
assigned to @code{rl_event_hook}.  @var{u} must be greater than or equal
to zero (a zero-length timeout is equivalent to a poll).
The default waiting period is one-tenth of a second.
Returns the old timeout value.
@end deftypefun

@node Terminal Management
@subsection Terminal Management

@deftypefun void rl_prep_terminal (int meta_flag)
Modify the terminal settings for Readline's use, so @code{readline()}
can read a single character at a time from the keyboard.
The @var{meta_flag} argument should be non-zero if Readline should
read eight-bit input.
@end deftypefun

@deftypefun void rl_deprep_terminal (void)
Undo the effects of @code{rl_prep_terminal()}, leaving the terminal in
the state in which it was before the most recent call to
@code{rl_prep_terminal()}.
@end deftypefun

@deftypefun void rl_tty_set_default_bindings (Keymap kmap)
Read the operating system's terminal editing characters (as would be
displayed by @code{stty}) to their Readline equivalents.
The bindings are performed in @var{kmap}.
@end deftypefun

@deftypefun void rl_tty_unset_default_bindings (Keymap kmap)
Reset the bindings manipulated by @code{rl_tty_set_default_bindings} so
that the terminal editing characters are bound to @code{rl_insert}.
The bindings are performed in @var{kmap}.
@end deftypefun

@deftypefun int rl_reset_terminal (const char *terminal_name)
Reinitialize Readline's idea of the terminal settings using
@var{terminal_name} as the terminal type (e.g., @code{vt100}).
If @var{terminal_name} is @code{NULL}, the value of the @code{TERM}
environment variable is used.
@end deftypefun

@node Utility Functions
@subsection Utility Functions

@deftypefun int rl_save_state (struct readline_state *sp)
Save a snapshot of Readline's internal state to @var{sp}.
The contents of the @var{readline_state} structure are documented
in @file{readline.h}.
The caller is responsible for allocating the structure.
@end deftypefun

@deftypefun int rl_restore_state (struct readline_state *sp)
Restore Readline's internal state to that stored in @var{sp}, which must
have been saved by a call to @code{rl_save_state}.
The contents of the @var{readline_state} structure are documented
in @file{readline.h}.
The caller is responsible for freeing the structure.
@end deftypefun

@deftypefun void rl_free (void *mem)
Deallocate the memory pointed to by @var{mem}.  @var{mem} must have been
allocated by @code{malloc}.
@end deftypefun

@deftypefun void rl_replace_line (const char *text, int clear_undo)
Replace the contents of @code{rl_line_buffer} with @var{text}.
The point and mark are preserved, if possible.
If @var{clear_undo} is non-zero, the undo list associated with the
current line is cleared.
@end deftypefun

@deftypefun void rl_extend_line_buffer (int len)
Ensure that @code{rl_line_buffer} has enough space to hold @var{len}
characters, possibly reallocating it if necessary.
@end deftypefun

@deftypefun int rl_initialize (void)
Initialize or re-initialize Readline's internal state.
It's not strictly necessary to call this; @code{readline()} calls it before
reading any input.
@end deftypefun

@deftypefun int rl_ding (void)
Ring the terminal bell, obeying the setting of @code{bell-style}.
@end deftypefun

@deftypefun int rl_alphabetic (int c)
Return 1 if @var{c} is an alphabetic character.
@end deftypefun

@deftypefun void rl_display_match_list (char **matches, int len, int max)
A convenience function for displaying a list of strings in
columnar format on Readline's output stream.  @code{matches} is the list
of strings, in argv format, such as a list of completion matches.
@code{len} is the number of strings in @code{matches}, and @code{max}
is the length of the longest string in @code{matches}.  This function uses
the setting of @code{print-completions-horizontally} to select how the
matches are displayed (@pxref{Readline Init File Syntax}).
When displaying completions, this function sets the number of columns used
for display to the value of @code{completion-display-width}, the value of
the environment variable @env{COLUMNS}, or the screen width, in that order.
@end deftypefun

The following are implemented as macros, defined in @code{chardefs.h}.
Applications should refrain from using them.

@deftypefun int _rl_uppercase_p (int c)
Return 1 if @var{c} is an uppercase alphabetic character.
@end deftypefun

@deftypefun int _rl_lowercase_p (int c)
Return 1 if @var{c} is a lowercase alphabetic character.
@end deftypefun

@deftypefun int _rl_digit_p (int c)
Return 1 if @var{c} is a numeric character.
@end deftypefun

@deftypefun int _rl_to_upper (int c)
If @var{c} is a lowercase alphabetic character, return the corresponding
uppercase character.
@end deftypefun

@deftypefun int _rl_to_lower (int c)
If @var{c} is an uppercase alphabetic character, return the corresponding
lowercase character.
@end deftypefun

@deftypefun int _rl_digit_value (int c)
If @var{c} is a number, return the value it represents.
@end deftypefun

@node Miscellaneous Functions
@subsection Miscellaneous Functions

@deftypefun int rl_macro_bind (const char *keyseq, const char *macro, Keymap map)
Bind the key sequence @var{keyseq} to invoke the macro @var{macro}.
The binding is performed in @var{map}.  When @var{keyseq} is invoked, the
@var{macro} will be inserted into the line.  This function is deprecated;
use @code{rl_generic_bind()} instead.
@end deftypefun

@deftypefun void rl_macro_dumper (int readable)
Print the key sequences bound to macros and their values, using
the current keymap, to @code{rl_outstream}.
If @var{readable} is non-zero, the list is formatted in such a way
that it can be made part of an @code{inputrc} file and re-read.
@end deftypefun

@deftypefun int rl_variable_bind (const char *variable, const char *value)
Make the Readline variable @var{variable} have @var{value}.
This behaves as if the readline command
@samp{set @var{variable} @var{value}} had been executed in an @code{inputrc}
file (@pxref{Readline Init File Syntax}).
@end deftypefun

@deftypefun {char *} rl_variable_value (const char *variable)
Return a string representing the value of the Readline variable @var{variable}.
For boolean variables, this string is either @samp{on} or @samp{off}.
@end deftypefun

@deftypefun void rl_variable_dumper (int readable)
Print the readline variable names and their current values
to @code{rl_outstream}.
If @var{readable} is non-zero, the list is formatted in such a way
that it can be made part of an @code{inputrc} file and re-read.
@end deftypefun

@deftypefun int rl_set_paren_blink_timeout (int u)
Set the time interval (in microseconds) that Readline waits when showing
a balancing character when @code{blink-matching-paren} has been enabled.
@end deftypefun

@deftypefun {char *} rl_get_termcap (const char *cap)
Retrieve the string value of the termcap capability @var{cap}.
Readline fetches the termcap entry for the current terminal name and
uses those capabilities to move around the screen line and perform other
terminal-specific operations, like erasing a line.  Readline does not
use all of a terminal's capabilities, and this function will return
values for only those capabilities Readline uses.
@end deftypefun

@node Alternate Interface
@subsection Alternate Interface

An alternate interface is available to plain @code{readline()}.  Some
applications need to interleave keyboard I/O with file, device, or
window system I/O, typically by using a main loop to @code{select()}
on various file descriptors.  To accomodate this need, readline can
also be invoked as a `callback' function from an event loop.  There
are functions available to make this easy.

@deftypefun void rl_callback_handler_install (const char *prompt, rl_vcpfunc_t *lhandler)
Set up the terminal for readline I/O and display the initial
expanded value of @var{prompt}.  Save the value of @var{lhandler} to
use as a function to call when a complete line of input has been entered.
The function takes the text of the line as an argument.
@end deftypefun

@deftypefun void rl_callback_read_char (void)
Whenever an application determines that keyboard input is available, it
should call @code{rl_callback_read_char()}, which will read the next
character from the current input source.
If that character completes the line, @code{rl_callback_read_char} will
invoke the @var{lhandler} function saved by @code{rl_callback_handler_install}
to process the line.
Before calling the @var{lhandler} function, the terminal settings are
reset to the values they had before calling
@code{rl_callback_handler_install}.
If the @var{lhandler} function returns,
the terminal settings are modified for Readline's use again.
@code{EOF} is  indicated by calling @var{lhandler} with a
@code{NULL} line.
@end deftypefun

@deftypefun void rl_callback_handler_remove (void)
Restore the terminal to its initial state and remove the line handler.
This may be called from within a callback as well as independently.
If the @var{lhandler} installed by @code{rl_callback_handler_install}
does not exit the program, either this function or the function referred
to by the value of @code{rl_deprep_term_function} should be called before
the program exits to reset the terminal settings.
@end deftypefun

@node A Readline Example
@subsection A Readline Example

Here is a function which changes lowercase characters to their uppercase
equivalents, and uppercase characters to lowercase.  If
this function was bound to @samp{M-c}, then typing @samp{M-c} would
change the case of the character under point.  Typing @samp{M-1 0 M-c}
would change the case of the following 10 characters, leaving the cursor on
the last character changed.

@example
/* Invert the case of the COUNT following characters. */
int
invert_case_line (count, key)
     int count, key;
@{
  register int start, end, i;

  start = rl_point;

  if (rl_point >= rl_end)
    return (0);

  if (count < 0)
    @{
      direction = -1;
      count = -count;
    @}
  else
    direction = 1;
      
  /* Find the end of the range to modify. */
  end = start + (count * direction);

  /* Force it to be within range. */
  if (end > rl_end)
    end = rl_end;
  else if (end < 0)
    end = 0;

  if (start == end)
    return (0);

  if (start > end)
    @{
      int temp = start;
      start = end;