tiny_shell.h

Go to the documentation of this file.

#ifndef TINY_SHELL_CLASS
#define TINY_SHELL_CLASS

/*****************************************************************************\
*                                                                             *
*  Name   : tiny_shell                                                        *
*  Author : Chris Koeritz                                                     *
*                                                                             *
*  Purpose:                                                                   *
*                                                                             *
*    The tiny shell provides a simple way to create an application.           *
*  The templated tiny application will create your object (which you          *
*  derive from tiny shell) and will automatically provide an ini editor,      *
*  a debugging console and some miscellaneous windows support.                *
*                                                                             *
*  Notes:                                                                     *
*                                                                             *
*    All tiny_shell programs must plug in the DEFINE_INSTANCE_HANDLE macro.   *
*  This supports the need to find local resources without getting stuck in    *
*  the MFC resource chain.  See basis/portable.h for more details.            *
*                                                                             *
*  This is a heavy-weight header and is intended mainly for the definition    *
*  of main programs that use MFC.                                             *
*                                                                             *
*******************************************************************************
* Copyright (c) 1995-$now By Author.  This program is free software; you can  *
* redistribute it and/or modify it under the terms of the GNU General Public  *
* License as published by the Free Software Foundation; either version 2 of   *
* the License or (at your option) any later version.  This is online at:      *
*     http://www.fsf.org/copyleft/gpl.html                                    *
* Please send any updates to: fred@gruntose.com                               *
\*****************************************************************************/

#include "mfc_dll.h"

#include <basis/portable.h>
#include <opsystem/application_shell.h>

// forward.
class debugger;
class debugging_console_window;
class log_base;
class outcome;

class MFC_EXTENSIONS_CLASS_STYLE tiny_shell
: public CFrameWnd,
  public application_shell
{
public:  
  tiny_shell(const istring &window_title, const istring &name_root,
          int file_size = int(1.2 * MEGABYTE),
          const istring &logfile_name = "");
    // constructs a tiny_shell window with the "window_title".  the
    // "name_root" is used as the base part of the config file's name and
    // diagnostic log file's name.  if "logfile_name" is not empty, then
    // that is used for the name of the diagnostic log instead.

  virtual ~tiny_shell();

  virtual int execute() = 0;
    // must be overridden by the derived object.  this usually performs the
    // main activity of the particular tiny shell object.  the function will be
    // called after the SetupWindow() method is finished.  it is alright for
    // this function to be an empty implementation, in which case the normal
    // owl mechanisms take over.

  int execute_returned() const { return _execute_returned; }
    // the execute method completes long before the object exits (usually).
    // this records the value returned by the execute method.  if execute
    // never got invoked (due to problems in creating underlying graphical
    // objects), then this value is meaningless.

  bool Create();
    // performs the actual creation using the data passed to the constructor.
    // the creation process is split into two steps to appease MFC.

  inline u_int menu() const { return _menu; }
  inline void menu(u_int new_menu) { _menu = new_menu; }
    // observes or modifies the menu to be used with the tiny shell.  by
    // default, this is zero and will not be set.  if it is to be changed, it
    // should be set up by the derived class' constructor or by a derived
    // SetupWindow() function before calling the base SetupWindow().

  inline u_int icon() const { return _icon; }
  inline void icon(u_int new_icon) { _icon = new_icon; }
    // observes or modifies the program icon.  this also should be set up in
    // the constructor if it is to be used.

  outcome log(const istring &to_print);
  outcome print(const istring &to_print);
    // sends a debugging line into the debugging console and also to the
    // log file.

  debugging_console_window &console() const;
    // the window that gets sent debugging information.  this is public to
    // allow better control over the debugging window.  it is constructed by
    // the time of the execute() function, but must not be used before then.
    // the console will not be very useful until Create() has been invoked.

  debugger &debug() const;
    // this object is pointed at the "console" to allow debugging information
    // to be sent.  it also is valid by the time the execute() function is
    // called.  it can be passed around as a valid log_base object before then,
    // but items logged to it will be discarded until the tiny_shell window
    // is created (just before execute() is invoked).  the initial style of
    // delivery for the debugging items is "delayed" (see debugger.h), but this
    // can be changed.  however, it is not recommended because that can cause
    // misordering of debug messages when other senders are targeting the same
    // debugging window.

  virtual bool good_version() const;
    // this function should be implemented by derived tiny_shells as something
    // like: @code
    //   #include <i_library/i_library_version.h>
    //   ....
    //   bool tiny_shell_X::good_version() const {
    //     return CHECK_I_COMMUNICATION;
    //   } @endcode
    // where all dlls used by the tiny_shell based program are checked.  the
    // function's implementation should not expect any other class members
    // to be available yet.  the constructor of the derived tiny_shell should
    // also have done very minimal member construction yet, since this approach
    // is not airtight in the presence of a dll conflict.
//hmmm: make this approach airtight.  currently it suffers from needing to
//      create the tiny shell object before the version can be checked, which
//      is just busted.  we need some kind of thing that's both virtual and
//      static, kinda.

protected:
  // mfc encrudulations:
  DECLARE_MESSAGE_MAP()
  afx_msg void OnClose();
  afx_msg int OnCreate(LPCREATESTRUCT lpCreateStruct);
  afx_msg void OnMove(int x, int y);
  afx_msg void OnSize(u_int nType, int cx, int cy);
  void OnSetFocus(CWnd *old_window);

private:
  debugger *_debug;  // our debugging message zinger.
  debugging_console_window *_console;  // our window for showing info.
  u_int _menu;  // value for our menu resource.
  u_int _icon;  // value for our icon resource.
  CMenu _mfc_menu;  // holds the MFC menu object when we have a menu id.
  istring *_win_title;  // the name on the window.
  bool _exiting;  // the program is leaving if this is true.
  log_base *_held_logger;  // tracks the prior logger.
  istring *_logfile_name;  // name of the logfile if not default.
  int _execute_returned;  // the return value of the execute() method.

  afx_msg LRESULT do_execute(WPARAM wparam, LPARAM lparam);
    // called when the tiny shell has finished setting up the window and is
    // about to start running the client program.

  afx_msg LRESULT print_debug(WPARAM wparam, LPARAM lparam);
    // when DEBUG::EVENT events happen, this sends the message to
    // the console.

  // unused.
  tiny_shell(const tiny_shell &);
  tiny_shell &operator =(const tiny_shell &);
};

#endif 

---