Click above to get retro games delivered to your door ever month!

Function:    TARGET()

Purpose:     Provide a pop-up target printer output selection menu.

Syntax:      TARGET( [ row [, column [, colors [, confirm ;
                     [, header [, fileext ] ] ] ] ] ] )

Arguments:   row         - Optional numeric value indicating the top row
                           on which to place the TARGET() selection menu.
                           If not specified or an invalid parameter is
                           passed, the default row is 10.  Valid rows are
                           from 0 to 10.

             column      - Optional numeric value indicating the left
                           column on which to place the TARGET() selection
                           menu.  If not specified or an invalid parameter
                           is passed, the default column is 21.  Valid
                           columns are from 0 to 41.

             colors      - Optional array of character strings specifying
                           the color settings to use.  This color array is
                           identical to the array required by BOXMENU().
                           The colors used for the different parts of the
                           menu are specified as follows:

                           colors[1]   -  Menu choices (item options)
                           colors[2]   -  Menu selection bar
                           colors[3]   -  Active menu box (on entry)
                           colors[4]   -  Inactive menu box (on exit)
                           colors[5]   -  Menu choice upon selection
                           colors[6]   -  Messages displayed on promptrow

             confirm     - Optional logical value indicating whether or
                           not to warn if a selected filename already
                           exists and to confirm an overwrite.  The
                           default value is True.

             header      - Optional character string to display as the
                           header in the BOXMENU() style print target
                           menu.  If this parameter is omitted or a
                           non-character type parameter is passed, the
                           default header text will be: "PRINT SELECTION
                           MENU".

             fileext     - Optional character string indicating the
                           default file extension to append to the end of
                           a target file name if one is entered.  Specify
                           only the three character file extension, do not
                           include the leading dot.  If omitted or a
                           non-character  argument is supplied the default
                           extension is ".PRN".  If the character string
                           is longer than three characters, only the first
                           three characters will be used for the file
                           extension.  To disable the automatic extension
                           append feature, pass a null ("") for the
                           <fileext>.

Returns:     The selected target output device as a character string of
             either "CON", "PRN", "LPT1", "LPT2", "LPT3", "COM1", "COM2",
             <filename>, or a null ("") if escape was pressed or Abort
             selected.

Description: TARGET() is a high level printer control function that takes
             the hassle out of prompting the user for directed printer or
             file output.  TARGET() pops up a centered BOXMENU() style
             menu which lets the user select a desired target for further
             output.  Selections include standard printer (PRN), other
             device (LPT 1,2,3, COM 1,2), screen, or to a file, the name
             of which the user is prompted to enter.

Notes:       All arguments are optional.  As with all Clipper functions,
             an argument may be skipped, but a "dummy" argument must be
             supplied in its place.

             The colors array is identical in structure to the array used
             in BOXMENU() and the same array may be used interchangeably.

             TARGET() maintains a PUBLIC memvar named RL_TARGET which
             saves the last target filename entered, if any.  This lets
             TARGET() display the last entered target filename on
             subsequent calls.

             The TARGET() menu appears as follows:

                         +-------------------------------------+
                         |        PRINT SELECTION MENU         |
                         --------------------------------------|
                         | Printer - print to the standard PRN |
                         | Device  - select a different port   |
                         | Screen  - send output to screen     |
                         | File    - send output to a file     |
                         | Abort   - cancel this request       |
                         +-------------------------------------+

             If the Device option is selected, a sub-menu appears with the
             following options:

                         +-------------------------------------+
                         |        PRINT SELECTION MENU         |
                         |-------------------------------------|
                         | Printer - print to the standard PRN |
                         | Device  - select a different port   |
                         | Screen  - +-------------+screen     |
                         | File    - |PRINT DEVICES|a file     |
                         | Abort   - --------------|uest       |
                         +-----------| 1.  LPT1    |-----------+
                                     | 2.  LPT2    |
                                     | 3.  LPT3    |
                                     | 4.  COM1    |
                                     | 5.  COM2    |
                                     +-------------+

             If the File option is selected a data entry box appears as
             follows:

                           +-------------------------------------+
                           |        PRINT SELECTION MENU         |
                           |-------------------------------------|
                           | Printer - print to the standard PRN |
                           | Device  - select a different port   |
                           | Screen  - send output to screen     |
                           | File    - send output to a file     |
                         +----------------------------------------+
                         |             Enter Filename             |
                         -----------------------------------------|
                         |                                        |
                         +----------------------------------------+

Example:     *-- query user for desired output
             mtarget = TARGET()
             IF .NOT.  mtarget == "CON"             && not to the screen
                SET PRINTER TO (mtarget)
                SET PRINT ON
                SET CONSOLE OFF
                DO MyReport
                SET PRINT OFF
                SET PRINTER TO
                SET CONSOLE ON
             ENDIF

Source:      RL_TARGE.PRG

See also:    GETFILE(), REPORTINIT(), STARTREPORT()