Constructs related to ::tycho::Query


Related class: ::tycho::Query Contents: Procs

Procs

::tycho::query {text queries {entrywidth 40} }
Query the user for one or more responses of various types (a line of text, multiple lines of text, a row of radio buttons, an option menu button, or a query mediated by some other dialog). Return only after the user enters information and hits OK or Cancel button. If the OK button is hit, the entire contents of the query will be returned as a list in the form {tag value tag value ...}. This list can be directly assigned to an array using array set, making it easy to use the results of the query. If the Cancel button is hit an empty string will be returned. The first argument is the label for the entire query, and will appear at the top of the query window. The second argument is the queries, which is actually a collection of method invocations for the Query class. The format of this argument is given in more detail below. The third argument is the width of the entry box in characters. It is optional and defaults to 40.

For example, the following call will create a dialog with one of each of the five kinds of queries:

   ::tycho::query {title text} { \
         {line v {v label} foo} \
         {lines w {w label} bar 4} \
         {radio x {x label} {A B C} A} \
         {choice y {y label} {A B C} A} \
         {mediated z {z label} red \
             {::tycho::querycolor {Choose a color}}}}
This will return a list of the form {v value w value x value y value z value}.

The queries argument is a list of method invocations. There are four relevant methods, shown with their arguments below:

  • line tag label default
  • lines tag label default height
  • radio tag label possibilities default
  • mediated tag label default command
  • In addition, all four can accept any number of additional arguments. These arguments are passed to the widget that implements the query (a Tk entry, a Tycho Edit, a set of Tk radio buttons, or a single Tk button, respectively). These additional arguments can be used to control the appearance of the query.

    The arguments above are explained below:

  • tag: a string that uniquely identifies the query. No two queries in the same dialog box can have the same tag.
  • label: a string that is inserted in the display to the left of the query.
  • default: the initial value of the query.
  • height: the number of lines in a multi-line text query. An Edit widget is used, providing an emacs-like text editor.
  • possibilities: a list of button names. These are the labels that appear on each of the radio buttons.
  • command: a command to invoke for a mediated query. Before invoking this command, the current (default) value of the query will be appended to the command, separated by a space. The command should return the new value of the query.
  • This procedure indirectly calls update, a Tk utility that processes pending events, including mouse events. If this procedure is called from within an Itcl object, directly or indirectly, it may be necessary to take precautions to prevent the calling object from being deleted during the call. Because of a defect in at least some versions of Itcl, failure to do so can result in catastrophic failure of the application (a core dump). In Tycho objects, the safeEval method should be used to evaluate this procedure or any method or procedure that in turn calls this procedure. If the procedure is called from the top level or from a Tcl procedure that is not itself called from within an Itcl object, then there is no cause for worry.

    ::tycho::queryinfo {text {initvalue ""} {entrywidth 40} }
    Query the user for a single typed response. This is a slightly simpler version of query, usable when only a single one-line text response is required. Return only after the user enters information and hits OK or Cancel button. If the OK button is hit, the value entered will be returned. If the Cancel button is hit an empty string will be returned. The first argument is the text of the query. The second argument is optional, and gives a default response. In other words, it will appear initially in the entry box. The third argument is the width of the entry box in characters It is also optional and defaults to 40.

    This procedure indirectly calls update, a Tk utility that processes pending events, including mouse events. If this procedure is called from within an Itcl object, directly or indirectly, it may be necessary to take precautions to prevent the calling object from being deleted during the call. Because of a defect in at least some versions of Itcl, failure to do so can result in catastrophic failure of the application (a core dump). In Tycho objects, the safeEval method should be used to evaluate this procedure or any method or procedure that in turn calls this procedure. If the procedure is called from the top level or from a Tcl procedure that is not itself called from within an Itcl object, then there is no cause for worry.

    Index of classes



    Author: Edward A. Lee, Joel R. King, Bilung Lee, John Reekie
    Contributor: Christopher Hylands
    Version: @(#)Query.itcl 1.16 12/04/96
    Copyright: (c) 1995-1996 The Regents of the University of California.