.-                                      
help for ^winshow^                                 [STB-46: dm63; STB-53: dm63.1]
.-

Show or enter data in a window (Windows and Macintosh only)
-----------------------------------------------------------

    ^winshow^ [varlist] [^if^ exp] [^in^ range] [, ^max^disp^(^#^) ed^it ^new del fi^nd
           ^st^rict ^dateord(^string^) log(^varlist^) call(^program_name^)^
           ^cap^tion^(^string^) head^er^(^var^) ls^pace^(^#^) drop(^#^)^
           ^nonu^m ^nova^r ^node^sc ^noty^pe ^nopreserve^]


Description
-----------

^winshow^ generates a dialog box displaying one observation from the current
dataset. Further observations can be seen by using the VCR style buttons
at the bottom of the window:

                         |<   first record
                          <   previous record
                          >   next record
                         >|   last record

There may be more than one page of variables which can be reached by using
the `More-->' and `<--Back' buttons.

Information shown for each variable includes the variable name, label and
type. The value for the current observation is displayed in an edit box
with the associated value label (where applicable) to the right.

The data within the edit boxes may be edited (using the ^edit^ option) and
new observations appended to the dataset (if the ^new^ option is specified),
allowing a data-entry system to be developed. Edited or new values are checked
against the value labels (where available) for the variable concerned and a
warning issued for unassigned values. This guards against data-entry mistakes.
Similarly for continuous variables a valid range may be specified, outside of
which warnings are issued (see @winset@). Date variables are shown formatted
and may be entered in virtually any recognised format, being automatically
converted to elapsed dates by ^winshow^.


Options
-------

^maxdisp(^#^)^ specifies the maximum number of variables to be displayed
    on each page. Values greater than 15 tend to cause "too many dialog
    controls" errors. The default is 14.

^edit^ allows the dataset to be modified by changing the values displayed in
    the edit boxes. By default changes made to the data are ignored.

^new^ puts an extra button on the dialog which allows the user to append new
    observations to the end of the dataset.

^del^ puts a delete button on the dialog which deletes the current observation
    when pressed.

^find^ adds a find button allowing searches for particular observations.

^strict^ prohibits the entry of values which do not have a corresponding label
    for any variable which has an attached value label. By default the user
    is warned but not prevented from entering such values.

^dateord(^string^)^ determines how entered dates are to be interpreted, "dmy"
    by default. Dates can be entered into numeric fields with a "%d" format
    either directly (as elapsed days since 1 Jan 1960) or as strings which
    can be interpreted as dates. If a string is entered then the order becomes
    important to correctly interpret the date. See [U] 30.3.2 The date()
    function for details.

^log(^varlist^)^ requests verbose logging of changes made to the dataset.
    The values of the variables in varlist are reported for the observation
    being changed.

^call(^ado_filename^)^ allows the user to enhance the built in error checking
    of modified values. The user's program is passed a variable list of the
    modified variables and global macros contain their prospective values.

^caption(^title^)^ over-rides the default dialog box title with the user's own.

^header(^var^)^ adds a header to the dialog box displaying the current value of
    one variable in the dataset. This is useful when an observation is spread
    over several pages.

^lspace(^#^)^ determines the horizontal spacing between lines (default is 11).

^drop(^#^)^ defines the maximum depth of drop-down lists (default is 60).

^nonum^ prevents the variable order from being displayed.

^novar^ prevents the variable name from being displayed.

^nodesc^ prevents the variable label from being displayed.

^notype^ prevents the variable type from being displayed.

^nopreserve^ stops ^winshow^ issuing a @preserve@ on start-up, with the option
    to @restore@ the data (if modified) on closing.


Examples
--------

        . ^winshow^
        . ^winshow if sbp>100, edit^
        . ^winshow id gender age drug1-drug9 in 10/l, max(10)^


Author
------

         Tony Brady
         Imperial College School of Medicine, U.K.
         t.brady@@ic.ac.uk

Also see
--------

    STB: dm63 (STB-46)
On-line: help for @diablo@, @window@, @winset@