// -*- C++ -*-

// (c) COPYRIGHT URI/MIT 1996,1998,1999
// Please first read the full copyright statement in the file COPYRIGHT.
//
// Authors:
//	jhrg,jimg	James Gallagher (jgallagher@gso.uri.edu)

// Graphical User Interface object. Starts the GUI in a separate process. The
// GUI must read commands from stdin and write responses to stdout. Users can
// signal that they do not want the GUI using an environment variable
// (DODS_USE_GUI) and can use a different GUI (specified with the DODS_GUI
// environment variable) so long as it conforms to the simple protocol of the
// default GUI. The GUI is sent the command in the DODS_GUI_INIT environment
// variable once it is started (but before any other commands are issued). If
// no such command is required, define this to be an empty string.
//
// jhrg 6/21/96

// $Log: Gui.h,v $
// Revision 1.8  1999/04/29 02:29:30  jimg
// Merge of no-gnu branch
//
// Revision 1.7  1998/11/23 15:05:55  tom
// late modifications to documentation
//
// Revision 1.6.6.1  1999/02/02 21:56:59  jimg
// String to string version
//
// Revision 1.6  1998/01/14 22:55:04  tom
// First draft of doc++ class documentation.
//
// Revision 1.5  1996/12/18 19:16:12  jimg
// Include assert.h. Arrgh!
//
// Revision 1.4  1996/08/13 18:29:21  jimg
// Added String.h - a bit of a retrenchment from my earlier `No nested
// includes' policy...
//
// Revision 1.3  1996/07/09 23:24:08  jimg
// Modified operator=() so that it passes -Wall (removed unused formal
// parameter RHS and provided a return value (*THIS).
//
// Revision 1.2  1996/07/08 23:18:36  jimg
// Added support for the HAVE_EXPECT compile-time switch. When defined as 1
// support for expect is built, when 0 it is not. Thus the dap++ library may be
// built so that expect is not required to link programs. However, the GUI will
// work only when expect/tcl are present and when client are linked with those
// libraries in addition to libdap++.a
// Fixed comments.
// Fixed some warnings (but left some...).
//
// Revision 1.1  1996/06/21 23:13:09  jimg
// Created based on code from Connect.h.
//

#ifndef _gui_h
#define _gui_h

#ifdef __GNUG__
#pragma "interface"
#endif

#include <assert.h>
#include <string>

/** This class manages a simple graphical user interface (GUI) for a
    DODS client.  The GUI consists of a process that can interpret
    tcl/tk commands.  The DODS client sends commands to the GUI
    process, who executes them and displays the results.

    The GUI process was created to display a progress indicator---a
    bar graph showing the progress of a data transfer.  The progress
    indicator uses three tcl programs which can be found in the
    #$(DODS_ROOT)/etc# directory: #dods_gui.tcl#, #error.tcl#, and
    #progress.tcl#.  The GUI process is a versatile feature, and may
    be used for more than a progress indicator.  It can display any
    graphical information that can be encoded into tcl/tk.

    Do not confuse the DODS Client GUI, managed by this class, with a
    DODS GUI Client, such as the DODS Matlab GUI, used for the
    graphical display of DODS datasets.  The two can work together,
    but otherwise have nothing to do with each other.

    The GUI process uses the following environment variables:
    
    \begin{description}

    \item{#DODS_USE_GUI#} If this variable exists and equals ``no'',
    the progress indicator will not appear. If it does not exist, or
    if it has any other value, the progress indicator will be
    activated. 

    \item{#DODS_GUI#} This is the name of the interpreter to be used
    to interpret the three tcl programs that make up the GUI.  If it
    does not exist, the program will default to #wish#.

    \item{#DODS_GUI_INIT#} This is the name of the program to start
    the GUI manager.  If the variable is not defined, the default will
    be the program that comes with DODS, #dods_gui.tcl#, found in the
    #$(DODS_ROOT)/etc# directory.

    \end{description}

    Note that since the job of the Gui class involves managing a
    process, there is no copy constructor or compare operators.

    @memo Implements a graphic user interface for a DODS client.  */

class Gui {
private:
    int _gui;			// Expect file descriptor for GUI.
    int _gui_pid;		// Process ID of GUI.
    bool _show_gui;		// True if we should use the GUI.
    bool _user_wants_gui;	// True if the user wants the GUI.
    bool _progress_visible;	// True when the PI is mapped.

    string _cmd;		// Command used to create object.

    bool _start_gui();

    // Suppress these. Don't allow copying or cloning these objects since
    // they contain active subprocesses. When compiled with `-Wall' operator=
    // generates a warning about the lack of a return value - ignore it.
    void clone(const Gui &) {assert(false);}
    Gui(const Gui &) {assert(false);}
    Gui &operator=(const Gui &) {assert(false); return *this;}

public:
  /** The class constructor for Gui does not start the GUI process.
      It only fills in the state variables and awaits further
      attention from the client process.

      If the constructor is called with a string argument, that is
      used as the command to start the GUI process.  If the {\it cmd}
      argument is omitted, the default value is taken from the
      #DODS_GUI# environment variable.  If that variable is not
      defined, the default value of #wish# is used.

      @name Gui();
      @memo The Gui class constructor.
      */
  //@{
  ///
    Gui(const string cmd);
  ///
    Gui();
  //@}
    ~Gui();

  /** This function can be used to query whether the progress
      indicator is visible or not.  It may also be used to set whether
      it is to be seen or not.

      @memo Set or test progress indicator visibility.
      @param state If {\it state} is omitted (or is -1, the default), 
      the function returns the visibility state.  If {\it state} is 
      included, the function sets the visibility state to the given 
      value.
      @return Returns TRUE if the GUI is visible, false otherwise.
      */
    bool progress_visible(int state = -1);

  /** This function returns the state of two internal flags.  The
      first, under program control, indicates whether or not to use
      the GUI at all.  This is a private value called #_show_gui#.
      The second flag is derived from the value of the environment
      variable #DODS_USE_GUI#, and is set when the class instance is
      created.  It is also a private value (#_user_wants_gui#), and
      cannot be modified.  The GUI is displayed only if both these
      flags are TRUE.

      This function can be used to modify the value of the #_show_gui#
      flag.

      @memo Should the GUI be used? 
      @param state If {\it state} is omitted (or is -1, the default),
      the function returns the result of the operation #_show_gui# AND
      #_user_wants_gui#.  If {\it state} is included, the function
      sets the value of the #_show_gui# flag.
      @return The value of #_show_gui# AND #_user_wants_gui#.
      */
    bool show_gui(int state = -1);

  /** Submits a command to the GUI process for execution.
 
      It may be that users turn off the GUI (because they are sick of
      it).  In that case, this command will simply return false. It
      does no harm to call the command when no GUI is running. Care
      should be taken to send only valid commands---invalid commands
      may put the GUI into an inoperable state.
    
      If the GUI is not running, this function starts it.

      The GUI process command interpreter is specified
      with the #DODS_GUI# environment variable, or with the
      constructor function.

      @memo Send the GUI process a command.
      @return TRUE if the command succeeded, FALSE otherwise.
      @param command A command to submit to the GUI process for
      execution.  
      */
    bool command(string command);

  /** Submits a command to the GUI process for execution and returns
      the command result.  This function is designed to interact with
      modal dialogs, such as GUI elements that return some information
      from the user (for example, a username and password).

      The GUI process command interpreter is specified
      with the #DODS_GUI# environment variable, or with the
      constructor function.

      @memo Send the GUI process a command and get the reply.  
      @param command The command to be executed by the GUI process.
      @param result The value returned by the GUI as the result of
      executing the given command is stored in {\it result} as a
      string.  If there are multiple values then they are separated by
      whitespace.
      @return If for some reason the GUI cannot get a response from
      the user the function returns FALSE, and the contents of RESULT
      are undefined.  Returns TRUE if the GUI element returned #OK# or
      #CANCEL#, FALSE otherwise. The response is returned in 
      {\it result}.
      */
    bool response(string command, string &result);
};

#endif // _gui_h