


term::interact::menu(n)  Terminal control term::interact::menu(n)


______________________________________________________________________________

NAME
       term::interact::menu - Terminal widget, menu

SYNOPSIS
       package require Tcl  8.4

       package require term::interact::menu  ?0.1?

       term::interact::menu object dict ?options...?

       object interact

       object done

       object clear

       object configure

       object configure option

       object configure option value...

       object cget option

_________________________________________________________________

DESCRIPTION
       This  package  provides  a class for the creation of a simple menu con-
       trol.

CLASS API
       The package exports a single command, the class command,  enabling  the
       creation of menu instances. Its API is:

       term::interact::menu object dict ?options...?
              This  command  creates  a  new menu object with the name object,
              initializes it, and returns the  fully  qualified  name  of  the
              object command as its result.

              The  argument is the menu to show, possibly followed by configu-
              ration options and their values. The options  are  explained  in
              the  section  Configuration.  The  menu  is  a dictionary maping
              labels to symbolic action codes.


OBJECT API
       The objects created by the class command  provide  the  methods  listed
       below:

       object interact
              Shows  the  menu  in  the  screen at the configured location and
              starts interacting with it. This opens its own  event  loop  for



term                           0.1                              1





term::interact::menu(n)  Terminal control term::interact::menu(n)


              the  processing  of incoming characters. The method returns when
              the interaction has completed. See  section  Interaction  for  a
              description of the possible interaction.

              The method returns the symbolic action of the menu item selected
              by the user at the end of the interaction.

       object done
              This method can be used by user supplied  actions  to  terminate
              the interaction with the object.

       object clear
              This  method  can be used by user supplied actions to remove the
              menu from the terminal.

       object configure

       object configure option

       object configure option value...

       object cget option
              Standard methods to retrieve and configure the  options  of  the
              menu.


CONFIGURATION
       A menu instance recognizes the following options:

       -in chan
              Specifies the channel to read character sequences from. Defaults
              to stdin.

       -out chan
              Specifies the channel to write the menu contents to. Defaults to
              stdout.

       -column int
              Specifies  the  column  of the terminal where the left margin of
              the menu display should appear. Defaults to 0,  i.e.  the  left-
              most column.

       -line int
              Specifies  the  line of the terminal where the top margin of the
              menu display should appear. Defaults to  0,  i.e.  the  top-most
              line.

       -height int
              Specifies  the  number  of  lines of text to show at most in the
              display. Defaults to 25.

       -actions dict
              Specifies a  dictionary  containing  additional  actions,  using
              character  sequences  as  keys. Note that these sequences cannot



term                           0.1                              2





term::interact::menu(n)  Terminal control term::interact::menu(n)


              override the hardwired sequences described in  section  Interac-
              tion.

       -hilitleft int

       -hilitright int
              By  default  the  entire  selected  menu entry is highlighted in
              revers output. However, when present these two options  restrict
              revers dispay to the specified sub-range of the entry.

       -framed bool
              By default the menu is shown using only header and footer out of
              characters box graphics. If this flag is set the menu  is  fully
              enclosed in a box.


INTERACTION
       A menu object recognizes the control sequences listed below and acts as
       described. The user can supply more control sequences to act on via the
       configuration, but is not able to overide these defaults.

       Cursor Up
              The  selection  is moved up one entry, except if the first entry
              of the menu is already selected.

       Cursor Down
              The selection is moved down one entry, except if the last  entry
              of the menu is already selected.

       Enter/Return
              The interaction with the object is terminated.


BUGS, IDEAS, FEEDBACK
       This  document,  and the package it describes, will undoubtedly contain
       bugs and other problems.  Please report such in the  category  term  of
       the          Tcllib         SF         Trackers         [http://source-
       forge.net/tracker/?group_id=12883].  Please also report any  ideas  for
       enhancements you may have for either package and/or documentation.

KEYWORDS
       control, menu, terminal, text display

CATEGORY
       Terminal control

COPYRIGHT
       Copyright (c) 2006 Andreas Kupries <andreas_kupries@users.sourceforge.net>









term                           0.1                              3


