Added RFC 2190 H.263 code as created by Guilhem Tardy and AliceStreet

[pwlib.git] / include / pwlib / applicat.h

/*
 * applicat.h
 *
 * GUI application class.
 *
 * Portable Windows Library
 *
 * Copyright (c) 1993-1998 Equivalence Pty. Ltd.
 *
 * The contents of this file are subject to the Mozilla Public License
 * Version 1.0 (the "License"); you may not use this file except in
 * compliance with the License. You may obtain a copy of the License at
 * http://www.mozilla.org/MPL/
 *
 * Software distributed under the License is distributed on an "AS IS"
 * basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
 * the License for the specific language governing rights and limitations
 * under the License.
 *
 * The Original Code is Portable Windows Library.
 *
 * The Initial Developer of the Original Code is Equivalence Pty. Ltd.
 *
 * Portions are Copyright (C) 1993 Free Software Foundation, Inc.
 * All Rights Reserved.
 *
 * Contributor(s): ______________________________________.
 *
 * $Log$
 * Revision 1.35  2001/05/22 12:49:32  robertj
 * Did some seriously wierd rewrite of platform headers to eliminate the
 *   stupid GNU compiler warning about braces not matching.
 *
 * Revision 1.34  2000/01/10 02:25:01  craigs
 * Added macro to allow multiple ancestors
 *
 * Revision 1.33  1999/08/07 07:13:22  robertj
 * Fixed problems with "balloon help" text popup.
 *
 * Revision 1.32  1999/03/10 03:49:50  robertj
 * More documentation adjustments.
 *
 * Revision 1.31  1999/03/09 08:01:47  robertj
 * Changed comments for doc++ support (more to come).
 *
 * Revision 1.30  1999/02/16 08:08:45  robertj
 * MSVC 6.0 compatibility changes.
 *
 * Revision 1.29  1998/09/23 06:22:49  robertj
 * Added open source copyright license.
 *
 * Revision 1.28  1998/04/07 13:33:22  robertj
 * Changed startup code to support PApplication class.
 *
 * Revision 1.27  1997/04/27 05:50:17  robertj
 * DLL support.
 *
 * Revision 1.26  1995/12/23 03:43:40  robertj
 * Changed version numbers.
 *
 * Revision 1.25  1995/12/10 11:28:21  robertj
 * Added extra user information to processes and applications.
 * Changed default default OnAbout() function to have user specified dialog.
 *
 * Revision 1.24  1995/10/14 14:51:16  robertj
 * Changed return values to references for efficency.
 *
 * Revision 1.23  1995/08/24 12:58:57  robertj
 * Added standard colours for balloon help windows.
 *
 * Revision 1.22  1995/07/31 12:15:40  robertj
 * Removed PContainer from PChannel ancestor.
 *
 * Revision 1.21  1995/04/02 09:27:17  robertj
 * Added "balloon" help.
 *
 * Revision 1.20  1995/03/14 12:40:57  robertj
 * Updated documentation to use HTML codes.
 *
 * Revision 1.19  1995/02/22  10:50:25  robertj
 * Changes required for compiling release (optimised) version.
 *
 * Revision 1.18  1995/02/19  04:08:41  robertj
 * Added dynamically linked command processing.
 *
 * Revision 1.17  1994/12/13  12:01:18  robertj
 * Fixed documentation error.
 *
 * Revision 1.16  1994/12/05  11:16:43  robertj
 * Documentation.
 * Normalised some variable types.
 *
 * Revision 1.15  1994/11/26  03:41:17  robertj
 * Added DoContextHelp versions using default help file (MSC bug).
 *
 * Revision 1.14  1994/11/24  11:48:25  robertj
 * Documentation.
 *
 * Revision 1.13  1994/08/23  11:32:52  robertj
 * Oops
 *
 * Revision 1.12  1994/08/22  00:46:48  robertj
 * Added pragma fro GNU C++ compiler.
 *
 * Revision 1.11  1994/08/21  23:43:02  robertj
 * Added delayed close of interactors to avoid the "delete this" problem.
 *
 * Revision 1.10  1994/07/17  10:46:06  robertj
 * Moved help menu function from application to toplevelwindow.
 *
 * Revision 1.9  1994/06/25  11:55:15  robertj
 * Unix version synchronisation.
 *
 * Revision 1.8  1994/04/03  08:34:18  robertj
 * Added help and focus functionality.
 *
 * Revision 1.7  1994/03/07  07:38:19  robertj
 * Major enhancementsacross the board.
 *
 * Revision 1.6  1994/01/03  04:42:23  robertj
 * Mass changes to common container classes and interactors etc etc etc.
 *
 * Revision 1.5  1993/12/31  06:38:11  robertj
 * Made inlines optional for debugging purposes.
 *
 * Revision 1.4  1993/08/27  18:17:47  robertj
 * Added timer support functions.
 *
 * Revision 1.3  1993/08/21  01:50:33  robertj
 * Made Clone() function optional, default will assert if called.
 *
 * Revision 1.2  1993/07/14  12:49:16  robertj
 * Fixed RCS keywords.
 *
 */


#define _PAPPLICATION

#ifdef __GNUC__
#pragma interface
#endif


class PTopLevelWindow;

#ifndef PAPPLICATION_ANCESTOR
#define PAPPLICATION_ANCESTOR    public PProcess
#endif


///////////////////////////////////////////////////////////////////////////////
// PApplication

/**A class to embody a GUI application. There is always exactly one instance
   of a descendednt of this class in an application. It should be possible to
   write the application so that this is the only global variable present. All
   other data is contained within this instance or its member variables or
   their member variables etc.
*/
class PApplication : PAPPLICATION_ANCESTOR
{
  PCLASSINFO(PApplication, PProcess);

  public:
   /**Create a new application instance.
     */
    PApplication(
      const char * manuf = "",         /// Name of manufacturer
      const char * name = "",          /// Name of product
      WORD majorVersion = 1,           /// Major version number of the product
      WORD minorVersion = 0,           /// Minor version number of the product
      CodeStatus status = ReleaseCode, /// Development status of the product
      WORD buildNumber = 1             /// Build number of the product
    );

    /** Destroy the application
     */
    ~PApplication();


    /**@name Overrides from class PProcess */
   /**This is the windows application main event loop. A typical application
       would override this function to perform all application initialisation
       and then call the ancestor function to execute the event loop.
     */
    virtual void Main();

   /**Terminate the application. This will destroy the main window and exit
       the event loop in Main(). This is usually only used in abnormal abort
       situations.
     */
    virtual void Terminate();


    /**@name New functions for class */
   /**Get the current processes application object. Note that there can only
       be one instance of an application class in a program image.

       @return
       Pointer to the current application.
     */
    static PApplication & Current();

   /**This function is called in the main program execution loop for
       handling events. This may be overridden to allow operations to be
       handled after each event that is handled by the system.
     */
    virtual void PassMainLoop();

   /**Get the top level window for the application. This will be the first
       instance of a descendent from \Ref{PTopLevelWindow}.

       @return
       pointer to the top level window for the application.
     */
    PTopLevelWindow * GetWindow() const;


   /**This enum describes the possible parameter list types that may be passed
       to the application. The mechanism by which these are passed is platform
       dependent.
     */
    enum ParameterTypes {
      /// The parameters are a list of files to be opened
      OpenFiles,        
      /// The parameters are a list of files to be printed
      PrintFiles,       
      /// The parameters are arbitrary strings
      GeneralParameters 
    };

   /**Get the type of the parameter list. The ParameterTypes values indicate
       that the parameter list should be parsed as a set of files to be opened
       or printed, or in the GeneralParameters case it leaves it entirely up
       to the application to decide what to do. In this case they may be parsed
       by the \Ref{PArgList} class.

       @return
       type of the application arguments
     */
    ParameterTypes GetParameterType() const;


   /**Set the menu item string to be used in the system standard "About" menu
       item. This string is used whenever the SetMenu() function is executed
       on a \Ref{PTopLevelWindow} class.
     */
    void SetAboutMenuItemString(
      const PString & newName /// New menu item title for the "About" function
    );

   /**Get the menu item string to be used in the system standard "About" menu
       item. This string is used whenever the SetMenu() function is executed
       on a \Ref{PTopLevelWindow} class.

       @return
       string used for "About" menus.
     */
    PString GetAboutMenuItemString() const;

   /**Set the resource ID to be used in the \Ref{OnAbout()} function.
     */
    void SetAboutDialogID(
      PRESOURCE_ID newID /// New resource ID for the "About" dialog.
    );

   /**Get the resource ID to be used in the \Ref{OnAbout()} function.

       @return
       Resource ID for "About" dialog.
     */
    PRESOURCE_ID GetAboutDialogID() const;

   /**Function which gets called when the about menu item is selected. An
       application could override this function to display a fancy "About"
       dialog.

       The default behaviour is to display the dialog specified by the
       \Ref{SetAboutDialogID()} function. If this dialog has not been set
       then a \Ref{PSimpleDialog} with the manufacturer, program name
       and version is displayed.
     */
    virtual void OnAbout();


   /**Set the default help file for the application. This file is used by the
       DoContextHelp() function in this class.
     */
    void SetDefaultHelpFile(
      const PFilePath & name /// Name of help file to be used by application.
    );

   /**Set the default help file for the application. This file is used by the
       DoContextHelp() function in this class.

       @return
       Name of help file to be used by application.
     */
    PFilePath GetDefaultHelpFile() const;

   /**Execute context sensitive help with the specified context key and
       help file. This will start the platform standard help system to display
       the help information for the context.
     */
    void DoContextHelp(
      const PString & context  /// Context string index into the help file
    );
    void DoContextHelp(
      PINDEX contextId         /// Context numerical index into the help file
    );
    void DoContextHelp(
      const PString & context, /// Context string index into the help file
      const PFilePath & file   /// File to search for the context in.
    );
    void DoContextHelp(
      PINDEX contextId,        /// Context numerical index into the help file
      const PFilePath & file   /// File to search for the context in.
    );

   /**Do all logic regarding the inflation and deflation of balloon help. The
       #action# parameter indicates the action to take in the
       balloon help system.
       
       A zero value for #action# indicates that the mouse was moved
       over the indicated interactor and if it stops moving, a balloon popup
       is to be displayed.

       A value for #action# of one indicates that current balloon
       is to be set to the #interactor# parameter.

       A value for #action# of two indicates that current balloon
       is to be returned and no other action taken.

       This is an internal function and is not normally called by the
       application.

       @return
       The balloon window displayed.
     */
    PBalloon * DoBalloonHelp(
      PInteractor * interactor,  /// Interactor in which cursor is over.
      int action = 0             /// Action to take in the balloon help system.
    );


   /**Find the interactor that is at the specified absolute screen
       coordinates. The interactor must be owned by the application.

       @return
       pointer to interactor at point or NULL if no interactor there.
     */
    PInteractor * FindInteractor(
      const PPoint & pt    /// Point to check.
    ) const;


   /**Get the size of the screen in pixels. Note that on some platforms the
       "screen" may be made up of smaller screens next to each other, and is
       not actually rectangular. In this case it returns the largest bounding
       rectangle of all sub-screens.

       @return
       the coordiantes of the screen in pixels.
     */
    const PRect & GetScreenRect() const;

   /**Get the size of the primary screen in pixels. This is always the screen
      that has its origin at 0,0 in multi screen systems.

       @return
       the coordiantes of the screen in pixels.
     */
    const PDim & GetPrimaryScreenSize() const;

   /**Get the resolution for the screen.

       @return
       dots per meter (or inch) in x and y for the screen.
     */
    const PDim & GetScreenResolution(
      BOOL imperial = FALSE
      /// Indicate that the return value is in imperial (TRUE) or metric (FALSE)
    ) const;

   /**Get the number of colours that can be simultaneously be displayed on
       the screen.

       @return
       number of colours.
     */
    long GetScreenColours() const;

   /**Get the number of bits per pixel that the screen is capable of.

       @return
       the depth or number of bits per pixel.
     */
    PDIMENSION GetScreenDepth() const;

   /**Get the maximum size of a cursor pixmap in screen pixels.

       @return
       width & height of a cursor.
     */
    const PDim & GetCursorSize() const;

   /**Get the maximum size of an icon pixmap in screen pixels.

       @return
       width & height of an icon.
     */
    const PDim & GetIconSize() const;

   /**Get the height of the caption part of a titled window or descendent.
       This may also be used on \Ref{PDialog} descendents on some platforms.

       @return
       height in pixels of caption.
     */
    PDIMENSION GetTitleHeight() const;

   /**Get the height of the menu bar in \Ref{PTopLevelWindow} descendent
       classes.

       @return
       height in pixels of the menu bar.
     */
    PDIMENSION GetMenuHeight() const;

   /**Get the size of the border for a titled window ie one that may be
       moved & resized.

       @return
       width & height in pixels of the border.
     */
    const PDim & GetTitledBorderSize() const;

   /**Get the size of the border for a modal dialog box.

       @return
       width & height in pixels of the border.
     */
    const PDim & GetDlgBorderSize() const;

   /**Get the size of the border for interactors with borders other than modal
       dialogs and resizable windows.

       @return
       width & height in pixels of the border.
     */
    const PDim & GetBorderSize() const;

   /**Get the default size of a main (top level) window.

       @return
       width & height in pixels of the window.
     */
    const PDim & GetMainWindowSize() const;

   /**Get the default size of all titled windows other than top level windows.

       @return
       width & height in pixels of the window.
     */
    const PDim & GetTitledWindowSize() const;

   /**Get the size of the horizontal scroll bar.

       @return
       height in pixels of the scroll bar.
     */
    PDIMENSION GetHScrollHeight() const;

   /**Get the size of the vertical scroll bar.

       @return
       width in pixels of the scroll bar.
     */
    PDIMENSION GetVScrollWidth() const;

   /**Get the system font which is the default basis for interactor
       coordinate systems. This is also the initial font used in interactors
       which will be active when drawing into canvases.

       @return
       specification of the system font.
     */
    const PFont & GetSystemFont() const;

   /**Get the font which is the default basis for balloon help windows.

       @return
       specification of the font.
     */
    const PFont & GetBalloonFont() const;

   /**Get the rectangle around a mouse click point that the second click must
       be within to be detected as a double click. Typically you would do a
       PtInRect of the second click position within this rectangle that has
       been offset by the position of the first click.

       @return
       rectangle for double click bounds.
     */
    const PRect & GetDoubleClickRect() const;

   /**Get the amount of milliseconds that must not have elapsed for the two
       mouse clicks to called a double click.

       @return
       time interval for double click.
     */
    const PTimeInterval & GetDoubleClickTime() const;

   /**Get the default colour of all foreground items in interactors.

       @return
       colour specification.
     */
    const PColour & GetWindowFgColour() const;

   /**Get the default colour of all background items in interactors.

       @return
       colour specification.
     */
    const PColour & GetWindowBkColour() const;

   /**Get the default colour of active titled window border.

       @return
       colour specification.
     */
    const PColour & GetActiveBorderColour() const;

   /**Get the default colour of inactive titled window border.

       @return
       colour specification.
     */
    const PColour & GetInactiveBorderColour() const;

   /**Get the default colour of the window title text in an active window.

       @return
       colour specification.
     */
    const PColour & GetActiveTitleFgColour() const;

   /**Get the default colour of the window title bar in an active window.

       @return
       colour specification.
     */
    const PColour & GetActiveTitleBkColour() const;

   /**Get the default colour of the window title text in an inactive window.

       @return
       colour specification.
     */
    const PColour & GetInactiveTitleFgColour() const;

   /**Get the default colour of the window title bar in an inactive window.

       @return
       colour specification.
     */
    const PColour & GetInactiveTitleBkColour() const;

   /**Get the default colour of the text in menus or menu bar.

       @return
       colour specification.
     */
    const PColour & GetMenuFgColour() const;

   /**Get the default colour of the background in menus or menu bar.

       @return
       colour specification.
     */
    const PColour & GetMenuBkColour() const;

   /**Get the default colour of the text in balloon help windows.

       @return
       colour specification.
     */
    const PColour & GetBalloonFgColour() const;

   /**Get the default colour of the background in balloon help windows.

       @return
       colour specification.
     */
    const PColour & GetBalloonBkColour() const;

   /**Get the default colour of the foreground (text) in a standard
       3 dimensional push button.

       @return
       colour specification.
     */
    const PColour & GetButtonFgColour() const;

   /**Get the default colour of the background (face) in a standard
       3 dimensional push button.

       @return
       colour specification.
     */
    const PColour & GetButtonBkColour() const;

   /**Get the default colour of the lighted edge in a standard 3 dimensional
       push button.

       @return
       colour specification.
     */
    const PColour & GetButtonLightingColour() const;

   /**Get the default colour of the shadowed edge in a standard 3 dimensional
       push button.

       @return
       colour specification.
     */
    const PColour & GetButtonShadowColour() const;

   /**Get the default colour of the slider section of a scroll bar. The
       arrows and thumb use the colours of the standard pushbutton.

       @return
       colour specification.
     */
    const PColour & GetScrollBarColour() const;

   /**Get the default colour of text that is highlighted. Used in the menus
       menu bars and edit text controls.

       @return
       colour specification.
     */
    const PColour & GetHighlightFgColour() const;

   /**Get the default colour of the background for text that is highlighted.
       Used in the menus, menu bars and edit text controls.

       @return
       colour specification.
     */
    const PColour & GetHighlightBkColour() const;

   /**Get the default colour of text that is disabled ("dimmed" or "grayed
       out"). Used in the menus, menu bars and all controls.

       @return
       colour specification.
     */
    const PColour & GetGrayTextColour() const;


   /**Add the interactor to the list for delayed delete operation on close
       of interactor from within a callback member function. This avoids the
       problem of an interactor object having its memory freed (via delete)
       while executing member functions of that object. The actual delete
       operation is delayed until the system returns to the main event loop.

       This function is primarily for internal use by PWLib and is used by
       the Close() function in the PTitledWindow and PDialog classes.
     */
    void DelayedCloseInteractor(
      PInteractor * interactor  /// Interactor to close
    );

   /*Internal initialisation function called directly from
       #main()#. The user should never call this function.
     */
    virtual int _main(void * arg = NULL);


  protected:
      /** The main, top level window for the application. */
    PTopLevelWindow * mainWindow;

      /** The type of the parameter list. */
    ParameterTypes parameterType;

  private:
    void Construct();

    // System values
    PString aboutMenuItemString;
    PRESOURCE_ID aboutDialogID;
    PFilePath defaultHelpFile;
    PDim primaryScreenSize, screenResImperial, screenResMetric, cursorSize, iconSize;
    PDim titledBorder, dlgBorder, border, defMainWindow, defTitledWindow;
    long screenColours;
    PDIMENSION screenDepth, heightTitle, heightMenu;
    PDIMENSION heightHScroll, widthVScroll;
    PRect screenRect, dblClkRect;
    PFont systemFont, balloonFont;
    PTimeInterval doubleClick;
    PColour windowFg, windowBk, highlightFg, highlightBk;
    PColour menuFg, menuBk, balloonFg, balloonBk;
    PColour grayText, buttonFg, buttonBk, buttonLighting, buttonShadow;
    PColour scrollBar, activeTitleFg, activeTitleBk, inactiveTitleFg;
    PColour inactiveTitleBk, activeBorder, inactiveBorder;

    PInteractorList delayedCloseInteractors;
      // List of interactors that require deletion at end of main loop.

    PCommandManager commandManager;
      // Manager for the command communication mechanism.

    PInteractor * balloonee;
    PBalloon * balloon;
    PTimer blowUpTimer;
    PTimeInterval blowUpTimeout;
    PDECLARE_NOTIFIER(PTimer, PApplication, BlowUpBalloon);

  friend class PTopLevelWindow;
  friend PCommandSink::PCommandSink(const char *, const char *);
  friend void PCommandSource::Call(PObject &, INT) const;


// Include platform dependent part of class
#include <pwlib/applicat.h>
};


// End Of File ///////////////////////////////////////////////////////////////