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

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

/*
 * interact.h
 *
 * Interactor ancestor 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.45  2003/03/17 07:34:58  robertj
 * Added Close() function for all interactors. Default behaviour closes the
 *   parent interactor till it gets to a PTitledWindow or PDialog.
 *
 * Revision 1.44  2001/05/22 12:49:33  robertj
 * Did some seriously wierd rewrite of platform headers to eliminate the
 *   stupid GNU compiler warning about braces not matching.
 *
 * Revision 1.43  2000/01/10 02:25:24  craigs
 * Added macro to allow multiple ancestors
 *
 * Revision 1.42  1999/07/18 15:07:12  robertj
 * Fixed missing return type
 *
 * Revision 1.41  1999/03/10 03:49:51  robertj
 * More documentation adjustments.
 *
 * Revision 1.40  1999/03/09 08:01:48  robertj
 * Changed comments for doc++ support (more to come).
 *
 * Revision 1.39  1999/02/16 08:08:45  robertj
 * MSVC 6.0 compatibility changes.
 *
 * Revision 1.38  1998/09/23 06:23:58  robertj
 * Added open source copyright license.
 *
 * Revision 1.37  1996/05/15 10:08:20  robertj
 * Added screen coordinate conversion functions with separate parameters.
 *
 * Revision 1.36  1996/04/30 12:33:33  robertj
 * Changed "inPixels" boolean to enum for three coordinate systems.
 *
 * Revision 1.35  1995/12/23 03:44:14  robertj
 * Added screen to local coordinate transforms.
 * Added FindWindow() function
 *
 * Revision 1.34  1995/10/14 14:56:33  robertj
 * Changed return values to references for efficency.
 *
 * Revision 1.33  1995/07/31 12:04:23  robertj
 * Drag track documentation and semantic adjustment.
 *
 * Revision 1.32  1995/07/02 01:17:41  robertj
 * Added drag tracking support.
 * Removed OnDoubleClick() and added BOOL to OnMouseDown() for double click.
 *
 * Revision 1.31  1995/06/17 11:08:00  robertj
 * Changed OnKeyDown to return BOOL indicating OnKeyInput is to be used.
 * Documentation update.
 *
 * Revision 1.30  1995/06/04 12:42:46  robertj
 * Redesign of caret driver functions (made a lot more common).
 *
 * Revision 1.29  1995/04/02 09:27:20  robertj
 * Added "balloon" help.
 *
 * Revision 1.28  1995/03/14 12:41:36  robertj
 * Updated documentation to use HTML codes.
 *
 * Revision 1.27  1995/02/19  04:19:09  robertj
 * Added dynamically linked command processing.
 *
 * Revision 1.26  1995/02/05  00:48:40  robertj
 * Documentation.
 *
 * Revision 1.25  1995/01/21  05:16:20  robertj
 * Modified ShowAll so PScrollable does not change show state of scroll bars..
 *
 * Revision 1.24  1995/01/16  13:02:24  robertj
 * Documentation.
 *
 * Revision 1.23  1995/01/15  04:54:51  robertj
 * Fixed global cursor set logic.
 *
 * Revision 1.22  1995/01/06  10:43:48  robertj
 * Changed PRealFont usage from pointer to reference.
 *
 * Revision 1.21  1995/01/02  12:24:58  robertj
 * Documentation.
 * Added global cursor setting for wait cursor.
 *
 * Revision 1.20  1994/12/21  11:53:10  robertj
 * Documentation and variable normalisation.
 *
 * Revision 1.19  1994/12/14  11:17:07  robertj
 * Changed PDIMENSION to be unsigned causing untold number of changes.
 *
 * Revision 1.18  1994/10/30  11:46:43  robertj
 * Changed mechanism for doing notification callback functions.
 *
 * Revision 1.17  1994/10/23  04:45:47  robertj
 * Added function to get the drawing bounds of an interactor.
 * Allowed cursor position to be obtained in pixels as well as font coords.
 *
 * Revision 1.16  1994/08/23  11:32:52  robertj
 * Oops
 *
 * Revision 1.15  1994/08/22  00:46:48  robertj
 * Added pragma fro GNU C++ compiler.
 *
 * Revision 1.14  1994/08/21  23:43:02  robertj
 * Added ability to get caret position in pixels.
 * Created global class for list of interactors.
 *
 * Revision 1.13  1994/06/25  11:55:15  robertj
 * Unix version synchronisation.
 *
 * Revision 1.12  1994/04/03  08:34:18  robertj
 * Added help and focus functionality.
 *
 * Revision 1.11  1994/03/07  07:38:19  robertj
 * Major enhancementsacross the board.
 *
 * Revision 1.10  1994/01/03  04:42:23  robertj
 * Mass changes to common container classes and interactors etc etc etc.
 *
 * Revision 1.9  1993/12/16  06:20:57  robertj
 * Changes to callback function definition due to GCC.
 *
 * Revision 1.8  1993/12/01  16:09:05  robertj
 * Windows NT port.
 *
 * Revision 1.7  1993/09/27  16:35:25  robertj
 * Removed special constructor for dialog resource loading.
 *
 * Revision 1.6  1993/08/27  18:17:47  robertj
 * Added background colour manipulation.
 *
 * Revision 1.5  1993/08/24  00:27:59  robertj
 * Added inPixels capability to validate/invalidate functions.
 *
 * Revision 1.4  1993/08/19  18:03:28  robertj
 * Made coordinate transform functions public.
 *
 * Revision 1.3  1993/07/14  12:49:16  robertj
 * Fixed RCS keywords.
 *
 */


#ifdef __GNUC__
#pragma interface
#endif


class PApplication;
class PInteractorCanvas;
class PControl;
class PBalloon;

PLIST(PInteractorList, PInteractor);

#ifndef PINTERACTOR_ANCESTOR
#define PINTERACTOR_ANCESTOR    public PObject
#endif


/**This class defines the common behaviour of all user interface interaction
   entity. This may or may not be a "Window" depending on the definition of
   that term in the target GUI.
 */
class PInteractor : PINTERACTOR_ANCESTOR

{
  PCLASSINFO(PInteractor, PObject);

  public:
    /** Create a a new interactor attaching it to the parent interactor.  */
    PInteractor(
      PInteractor * parent,  /// Interactor into which the interactor is placed.
      BOOL hiddenChild = FALSE
     /**Whether the "hidden" from the application. If this is TRUE then the
         interactor is not added to the parents child interactor list, thus it
         will not be visible as a "child" interactor of the parent and will
         not be automatically deleted when the parent is deleted.
       */
    );

    /** Destroy the interactor, and all its child interactors. */
    virtual ~PInteractor();


  /**@name Overrides from class PObject */
   /**Determine if the two interactors are the same. As two instances can
       never {\bf be} the same interactor, this can never be EqualTo.

       @return
       Always #GreaterThan#.
     */
    virtual Comparison Compare(
      const PObject & obj   /// Interactor to compare against.
    ) const;


  /**@name New functions for class */
   /**Get the interactor layout that this interactor is contained in.

       @return
       pointer to parent interactor.
     */
    PInteractor * GetParent() const;

   /**Determine if this interactor is a child or grandchild etc of the
       interactor layout specified.

       @return
       TRUE if interactor is a child of #parent#.
     */
    BOOL IsChild(
      PInteractor * parent    /// Interactor to check for parenthood.
    ) const;

   /**Get the number of children the interactor currently contains.

       @return
       number of child interactors.
     */
    PINDEX GetNumChildren();

   /**Get access to the child interactor at the specified index. The order in
       which child interactors are attached to a parent interactor is initially
       in their construction order.

       @return
       reference to child interactor.
     */
    PInteractor & operator[](
      PINDEX index    /// Ordinal position of the child interactor.
    );

   /**Update all command sources. This will go to the utimate parent, a
       \Ref{PTopLevelWindow}, and then recursively update every command
       source, menu item or control, for being enabled or disabled. This uses
       the \Ref{PNotifier} function for each source to get the new state.

       The \Ref{PCommandSource} and \Ref{PCommandSink} classes are usually
       used in conjunction with this function to control commands such as menu
       items and tool bars etc.
     */
    virtual void UpdateCommandSources();


   /**Set the font to be used by default by this interactor. A canvas created
       on this interactor will initially have this font selected.
       
       This also determines the coordinate system to be used for laying out
       child interactors via the \Ref{SetPosition()} and
       \Ref{SetDimensions()} functions. The coordinates used are 1/4 average
       font width and 1/8 the font height.
       
       If the #toChildren# parameter is TRUE then the font is
       propagated down to all child interactors and grandchild interactors etc.
     */
    virtual void SetFont(
      const PFont & newFont, /// New font specification fo rthe interactor.
      BOOL toChildren = TRUE
        /// Flag to recursively change all child interactors.
    );

   /**Get the font to be used by default in all child interactors. A canvas
       created on this interactor will initially have this font selected.
       
       This also determines the coordinate system to be used for laying out
       child interactors via the \Ref{SetPosition()} and
       \Ref{SetDimensions()} functions. The coordinates used are 1/4 average
       font width and 1/8 the font height.

       @return
       Pointer to a realised font on a canvas for this interactor.
     */
    const PRealFont & GetFont();

    /** Convert the layout X coordinate value to screen pixels. */
    PDIMENSION ToPixelsDX(
      PDIMENSION x    /// Horizontal dimension to convert.
    ) const;

    /** Convert the layout Y coordinate value to screen pixels. */
    PDIMENSION ToPixelsDY(
      PDIMENSION y    /// Vertical dimension to convert.
    ) const;

    /** Convert the layout X coordinate value to screen pixels. */
    PORDINATE ToPixelsX(
      PORDINATE x   /// Horizontal coordinate to convert.
    ) const;

    /** Convert the layout Y coordinate value to screen pixels. */
    PORDINATE ToPixelsY(
      PORDINATE y   /// Vertical coordinate to convert.
    ) const;

    /** Convert the layout dimension value to screen pixels. */
    PDim ToPixels(
      const PDim & dim    /// Dimensions to convert.
    ) const;

    /** Convert the layout point value to screen pixels. */
    PPoint ToPixels(
      const PPoint & pt   /// Position to convvert.
    ) const;

    /** Convert the layout rectange value to screen pixels. */
    PRect ToPixels(
      const PRect & r     /// Rectangle to convert.
    ) const;

    /** Convert the screen pixels to a layout X coordinate value. */
    PDIMENSION FromPixelsDX(
      PDIMENSION x    /// Horizontal dimension to convert.
    ) const;

    /** Convert the screen pixels to a layout Y coordinate value. */
    PDIMENSION FromPixelsDY(
      PDIMENSION y    /// Vertical dimension to convert.
    ) const;

    /** Convert the screen pixels to a layout X coordinate value. */
    PORDINATE FromPixelsX(
      PORDINATE x   /// Horizontal coordinate to convert.
    ) const;

    /** Convert the screen pixels to a layout Y coordinate value. */
    PORDINATE FromPixelsY(
      PORDINATE y   /// Vertical coordinate to convert.
    ) const;

    /** Convert the dimensions in screen pixels to layout coordinates. */
    PDim FromPixels(
      const PDim & dim    /// Dimensions to convert.
    ) const;

    /** Convert the point in screen pixels to layout coordinates. */
    PPoint FromPixels(
      const PPoint & pt   /// Position to convvert.
    ) const;

    /** Convert the rectangle in screen pixels to layout coordinates. */
    PRect FromPixels(
      const PRect & r     /// Rectangle to convert.
    ) const;


   /**Origin specification for the \Ref{SetPosition()} function. This
       determines how the horizontal and vertical position is interpreted to
       the final placement of the interactor.

       When scaling is used (eg #xOrigin = TopLeftParent#), the
       coordinates used are 1/4 average font width and 1/8 the font height.

       Note that some child interactors are clipped to be within their
       parent. For these interactors, setting relative to the screen may cause
       the interactor to become invisible.
     */
    enum PositionOrigin {
     /**Position the left of the interactor relative to the left of the
         screen and the top of the interactor relative to the top of the
         screen.
         
         No scaling factor will be applied and x and y offset will be applied
         in screen pixels. Offsets of zero will place the interactor in the
         top left corner of the screen. Negative offsets will start to move
         the interactor off the screen.
       */
      TopLeftScreen,
     /**Position the centre of the interactor relative to the centre of the
         screen in both the horizontal and vertical directions.

         No scaling factor will be applied and x and y offset will be applied
         in screen pixels. Offsets of zero will place the interactor in the
         centre of the screen.
       */
      CentreScreen,
     /**Position the right of the interactor relative to the right of the
         screen and the bottom of the interactor relative to the bottom of the
         screen.
         
         No scaling factor will be applied and x and y offset will be applied
         in screen pixels. Offsets of zero will place the interactor in the
         bottom right corner of the screen. Positive offsets will start to move
         the interactor off the screen.
       */
      BottomRightScreen,
     /**Position the left of the interactor relative to the left of the
         parent internal area and the top of the interactor relative to the
         top of the parents internal area.
         
         The coordinates are scaled according to the currently selected font
         for the interactor. Offsets of zero will place the interactor in the
         top left corner of the parent. Negative offsets will start to move
         the interactor off the parent interactor.
       */
      TopLeftParent,
     /**Position the centre of the interactor relative to the centre of the
         parent internal area in both the horizontal and vertical directions.
         
         The coordinates are scaled according to the currently selected font
         for the interactor. Offsets of zero will place the interactor in the
         centre of the parent.
       */
      CentreParent,
     /**Position the right of the interactor relative to the right of the
         parent internal area and the bottom of the interactor relative to the
         bottom of the parents internal area.
         
         The coordinates are scaled according to the currently selected font
         for the interactor. Offsets of zero will place the interactor in the
         bottom right corner of the parent. Positive offsets will start to move
         the interactor off the parent interactor.
       */
      BottomRightParent,
     /**Position the left of the interactor relative to the left of the
         parent internal area and the top of the interactor relative to the
         top of the parents internal area.
         
         No scaling factor will be applied and x and y offset will be applied
         in screen pixels. Offsets of zero will place the interactor in the
         top left corner of the parent. Negative offsets will start to move
         the interactor off the parent interactor.
       */
      TopLeftPixels,
     /**Position the centre of the interactor relative to the centre of the
         parent internal area in both the horizontal and vertical directions.
         
         No scaling factor will be applied and x and y offset will be applied
         in screen pixels. Offsets of zero will place the interactor in the
         centre of the parent.
       */
      CentrePixels,
     /**Position the right of the interactor relative to the right of the
         parent internal area and the bottom of the interactor relative to the
         bottom of the parents internal area.
         
         No scaling factor will be applied and x and y offset will be applied
         in screen pixels. Offsets of zero will place the interactor in the
         bottom right corner of the parent. Positive offsets will start to move
         the interactor off the parent interactor.
       */
      BottomRightPixels
    };

    void SetPosition(
      const PPoint & org,   /// Offset to apply to interactor.
      PositionOrigin xOrigin = TopLeftParent,  /// Origin for horizontal offset.
      PositionOrigin yOrigin = TopLeftParent   /// Origin for verical offset.
    );
   /**Set the position of the interactor. The #xOrigin# and
       #yOrigin# parameters indicate the coordinate system to be
       used for the offsets. If the font based layout coordinates are used
       they will use the font of the {\it parents} interactor. The
       interactors font is {\bf not} used.

       Note that this sets the position of the exterior of the interactor,
       including any decoration, eg title bars etc.

       When scaling is used (eg #xOrigin = TopLeftParent#), the
       coordinates used are 1/4 average font width and 1/8 the font height.

       The user should not override this function. If some form of action is
       required on changing the interactors position then the
       \Ref{_SetPosition()} function should be overridden.
     */
    void SetPosition(
      PORDINATE x,          /// Horizontal offset to apply to interactor.
      PORDINATE y,          /// Vertical offset to apply to interactor.
      PositionOrigin xOrigin = TopLeftParent,  /// Origin for horizontal offset.
      PositionOrigin yOrigin = TopLeftParent   /// Origin for verical offset.
    );

    /** Coordinate system used for position & dimensions */
    enum CoordinateSystem {
        /** Use interactor relative, font scaled coordinates. */
      LocalCoords,
        /** Use interactor relative coordinates in screen pixels. */
      PixelCoords,
        /** Use screen absolute coordinates */
      ScreenCoords
    };

   /**Get the position of the interactor relative to its parent. If the
       interactor has no parent, ie is a descendent of \Ref{PTopLevelWindow},
       then the position is always in absolute screen coordinates.
        
       If the #coords# parameter is #LocalCoords# then
       the return value is in the coordinate system based in the interactors
       current font. Otherwise it is returned in screen pixels.
       
       If the #coords# parameter is #PixelCoords# then
       the coordinates are still relative to its parent, while the
       #ScreenCoords# value will return realtive to the absolute
       screen origin.

       Note that this gets the position of the exterior of the interactor,
       including any decoration, eg title bars etc.

       When scaling is used (#coords == LocalCoords#), the
       coordinates used are 1/4 average font width and 1/8 the font height.

       @return
       point for the interactors current position.
     */
    PPoint GetPosition(
      CoordinateSystem coords   /// Coordinate system to use.
    ) const;

   /**Convert the point from the interactor relative coordinates to absolute
       screen coordinates.
        
       If the #coords# parameter is #LocalCoords# then
       the return value is in the coordinate system based in the interactors
       current font. Otherwise it is returned in screen pixels.
       
       If the #coords# parameter is #PixelCoords# then
       the coordinates are still relative to its parent, while the
       #ScreenCoords# value will return realtive to the absolute
       screen origin.

       When scaling is used (#coords == LocalCoords#), the
       coordinates used are 1/4 average font width and 1/8 the font height.

       @return
       point converted to absolute screen coordinates.
     */
    PPoint ToScreen(
      PORDINATE x,
      PORDINATE y,
      CoordinateSystem coords
    ) const;
    PPoint ToScreen(
      const PPoint & pt,        /// Coordinate to convert.
      CoordinateSystem coords   /// Coordinate system to use.
    ) const;

   /**Convert the point from the absolute screen coordinates to interactor
       relative coordinates.
        
       If the #coords# parameter is #LocalCoords# then
       the return value is in the coordinate system based in the interactors
       current font. Otherwise it is returned in screen pixels.
       
       If the #coords# parameter is #PixelCoords# then
       the coordinates are still relative to its parent, while the
       #ScreenCoords# value will return realtive to the absolute
       screen origin.

       When scaling is used (#coords == LocalCoords#), the
       coordinates used are 1/4 average font width and 1/8 the font height.

       @return
       point converted from absolute screen coordinates.
     */
    PPoint FromScreen(
      PORDINATE x,
      PORDINATE y,
      CoordinateSystem coords
    ) const;
    PPoint FromScreen(
      const PPoint & pt,        /// Coordinate to convert.
      CoordinateSystem coords   /// Coordinate system to use.
    ) const;


   /**Set the dimensions of the interactor. The new size is specified in
       either the font based layout coordinates or in screen pixels as
       specified by the #coords# parameter.

       Note that this sets the dimension of the interior of the interactor,
       excluding any decoration, eg title bars etc.
       
       When scaling is used (#coords == LocalCoords#), the
       coordinates used are 1/4 average font width and 1/8 the font height.

       The user should not override this function. If some form of action is
       required on changing the interactors size then the
       \Ref{#_SetDimensions()#} function should be overridden.
     */
    void SetDimensions(
      PDIMENSION width,         /// New width to apply to interactor.
      PDIMENSION height,        /// New height to apply to interactor.
      CoordinateSystem coords   /// Coordinate system to use.
    );
    void SetDimensions(
      const PDim & dim,         /// New dimensions to apply to interactor.
      CoordinateSystem coords   /// Coordinate system to use.
    );

   /**Get the dimensions of the interactor.

       If the #coords# parameter is #LocalCoords# then
       the return value is in the coordinate system based in the interactors
       current font. Otherwise it is returned in screen pixels.
       
       If the #coords# parameter is #PixelCoords# then
       the coordinates are still relative to its parent, while the
       #ScreenCoords# value will return realtive to the absolute
       screen origin.

       Note that this gets the dimension of the interior of the interactor,
       excluding any decoration, eg title bars etc.
       
       When scaling is used (#coords == LocalCoords#), the
       coordinates used are 1/4 average font width and 1/8 the font height.

       @return
       dimensions for the interactors current size.
     */
    PDim GetDimensions(
      CoordinateSystem coords   /// Coordinate system to use.
    ) const;

   /**Get the external bounds of the interactor. This includes things such as
       title bars and borders etc. For most interactors this will be identical
       to a rectangle formed from \Ref{GetPosition()} and
       \Ref{GetDimensions()} as there are no external decorations to the
       interactor.

       If the coordinate system used is in pixels
       (#coords == ScreenCoords#) then the position is in absolute
       screen coordinates. Otherwise it uses the interactors own coordinate
       system. This usually means negative values for the rectangles top left
       corner.

       When scaling is used (#coords == LocalCoords#), the
       coordinates used are 1/4 average font width and 1/8 the font height.

       @return
       bounds rectangle for the interactor.
     */
    PRect GetStructureBounds(
      CoordinateSystem coords   /// Coordinate system to use.
    ) const;

   /**Get the drawing bounds for the interactor. This is usually the internal
       dimensions of the interactor. But could be other sizes depending on the
       semantics of the interator. See \Ref{PScrollable} for an example of the
       drawing bounds being larger than the size of the interactor.

       This function is used by the \Ref{PInteractorCanvas} class to determine
       the drawing bounds for the canvas.

       When scaling is used (#coords == LocalCoords#), the
       coordinates used are 1/4 average font width and 1/8 the font height.

       @return
       drawing bounds rectangle for the interactor.
     */
    virtual PRect GetDrawingBounds(
      CoordinateSystem coords   /// Coordinate system to use.
    ) const;

   /**Options for the \Ref{AutoAdjustBounds()} function. This controls how
       the interactor will be repositioned and resized given a bounds
       rectangle.
         
       For all #AdjustBounds# option, the bounds rectangle is
       reduced by the size of the interactor just placed.
     */
    enum AutoAdjustType {
     /**Set the interactors position and dimensions to the value specified in
         the rectangle.
       */
      AdjustBounds,
     /**Set the interactors position to the top left of the specified bounds
         rectangle. The width of the interactor is set to the width of the
         bounds rectangle and the height remains unchanged.
       */
      AdjustTop,
     /**Set the interactors position to the bottom left of the specified
         bounds rectangle. The width of the interactor is set to the width of
         the bounds rectangle and the height remains unchanged.
       */
      AdjustBottom,
     /**Set the interactors position to the top left of the specified bounds
         rectangle. The height of the interactor is set to the height of the
         bounds rectangle and the width remains unchanged.
       */
      AdjustLeft,
     /**Set the interactors position to the bottom left of the specified
         bounds rectangle. The width of the interactor is set to the width of
         the bounds rectangle and the height remains unchanged.
       */
      AdjustRight,
     /**Set the interactors position to the top right of the specified bounds
         rectangle. The height of the interactor is set to the height of the
         bounds rectangle and the width is set to the standard width for a
         vertical scroll bar as defined by the
         \Ref{PApplication::GetVScrollWidth()} function.
       */
      AdjustVScrollOnly,
     /**Set the interactors position to the bottom left of the specified
         bounds rectangle. The width of the interactor is set to the width of
         the bounds rectangle and the height is set to the standard height for
         a horizontal scroll bar as defined by the
         \Ref{PApplication::GetHScrollHeight()} function.
       */
      AdjustHScrollOnly,
     /**Set the interactors position to the top right of the specified bounds
         rectangle. The height of the interactor is set to the height of the
         bounds rectangle minus the height of a horizontal scroll bar. The
         width is set to the standard width for a vertical scroll bar.
         
         This option is used when both scroll bars are to be used and they must
         be placed in the usual manner, with a small unused area in the bottom
         right corner of the parent interactor.
       */
      AdjustVScrollBeforeHScroll,
     /**Set the interactors position to the bottom left of the specified
         bounds rectangle. The width of the interactor is set to the width of
         the bounds rectangle minus the width of a vertical scroll bar. The
         height is set to the standard height for a horizontal scroll bar.

         This option is used when both scroll bars are to be used and they must
         be placed in the usual manner, with a small unused area in the bottom
         right corner of the parent interactor.
       */
      AdjustHScrollAfterVScroll
    };

   /**Adjust the interactor relative to the specified bounds rect. The bounds
       rectangle is the modified to remove the space that the interactor takes
       up in the bounds. In this way successive calls to AutoAdjustBounds() on
       child interactors by a parent can "tile" the interactors to correct
       positions. For example, if a parent has a scroll bar, a button bar and
       a status bar thes can be placed with three calls to AutoAdjustBounds()
       in the \Ref{PTitledWindow::OnResize()} function.
     */
    void AutoAdjustBounds(
      PRect & bounds,  /// Bounds rectangle in which the interactor is adjusted.
      AutoAdjustType type = AdjustBounds  /// Option for adjustment to be made.
    );

   /**Determine if the point specified is inside the interactors area. Note
       that the border or other decorations in a window are included in the
       area that consitutes the interactor

       The point is usually in absolute screen coordinates, ie when
       #coords# parameter is #ScreenCoords#, but may also
       be relative to the interactors origin or scaled to the interactors font
       based layout coordinates.

       When scaling is used (#coords == LocalCoords#), the
       coordinates used are 1/4 average font width and 1/8 the font height.

       @return
       TRUE if the point is within the interactor.
     */
    BOOL ContainsPoint(
      const PPoint & pt,        /// Point in to check.
      CoordinateSystem coords   /// Coordinate system to use.
    ) const;

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

       The point is usually in absolute screen coordinates, ie when
       #coords# parameter is #ScreenCoords#, but may also
       be relative to the interactors origin or scaled to the interactors font
       based layout coordinates.

       When scaling is used (#coords == LocalCoords#), the
       coordinates used are 1/4 average font width and 1/8 the font height.

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


   /**Close the interactor.
       The default behavour calls the Close() function for the parent interactor.

       @return
       TRUE if close has been queued.
     */
    virtual BOOL Close();

   /**Enable or disable the interactor. This will prevent all input from being
       processed by the interactor. In some cases the visual appearance of the
       interactor may change depending on the individual semantics of the
       interactor. For example the text for a \Ref{PTextButton} would appear
       "greyed" out.
       
       Note if an PInteractor is disabled, all its children, grandchildren etc
       will be disabled.
     */
    virtual void Enable(
      BOOL enabled = TRUE   /// New state for input processing of interactor.
    );

   /**Disable the interactor, ignoring all input to it.

       This is identical to calling #Enable(FALSE)#.
     */
    void Disable();

   /**Determine if the interactor is enabled and input may be processed.

       @return
       TRUE if input processing enabled.
     */
    BOOL IsEnabled() const;


   /**Show the interactor and all child and grandchild etc interactors.

       This enabled the interactor tree in post order, ie all children have
       their ShowAll() function called and then the interactor itself is shown
       using the \Ref{Show()} function.
     */
    virtual void ShowAll();

   /**Show or hide the interactor. This will immediately remove the interactor
       from view. Showing an interactor will cause content update events to
       be queued for later call of the \Ref{OnRedraw()} function. The actual
       display may be delayed.
     */
    virtual void Show(
      BOOL visible = TRUE   /// New state for the visibility of the interactor.
    );

   /**Hide the interactor from view.

       This is identical to calling #Show(FALSE)#.
     */
    void Hide();

   /**Determine if interactor may be visible. Note that this does not mean
       that it is not obscured by another window on the screen. It simply means
       that the interactor has had #Show(TRUE)# called last.

       @return
       TRUE if the interactor is shown.
     */
    BOOL IsVisible() const;


   /**Bring the interactor to the top of any layering order for overlapping
       windows or interactors. This only affects sibling interactors at a
       particular level of the parent child hierarchy.

       If the interactor is a \Ref{PTopLevelWindow} then the "siblings" it
       uses are other applications top level windows. This is equivalent to the
       "activating" of an application that the user may do using mouse and
       keyboard in the platform dependent manner.
       
       Note that this does not change the order of child interactors as
       returned by the #\Ref{operator[]}# function, only the screen
       appearence is altered.
     */
    virtual void BringToTop();

   /**Determine if the interactor is currently on top of any layering order
       for overlapping windows or interactors. This compares against sibling
       interactors at a particular level of the parent child hierarchy.

       @return
       TRUE if this interactor is the 
     */
    virtual BOOL IsOnTop() const;


   /**Mark the area of the interactor as requiring a redraw. This adds the
       specified rectangular area to an {\it update region}. If this region
       is not empty then a request to redraw that area of the interactor is
       queued to be processed by the message handling system. At some time
       later the \Ref{OnRedraw()} function is called with its canvas clipping
       region set to the update region.

       The parameterless form will invalidate the entire interactor.

       When scaling is used (#coords == LocalCoords#), the
       coordinates used are 1/4 average font width and 1/8 the font height.

       The user should not override this function. If some form of action is
       required on changing the interactors update region then the
       \Ref{_Invalidate()} function should be overridden.
     */
    void Invalidate(
      PORDINATE x,
      /// X position of the top left corner of the rectangle to invalidate.
      PORDINATE y,
      /// Y position of the top left corner of the rectangle to invalidate.
      PDIMENSION width,       /// Width of the rectangle to invalidate.
      PDIMENSION height,      /// Height of the rectangle to invalidate.
      CoordinateSystem coords /// Coordinate system to use.
    );
    void Invalidate(
      const PPoint & topLeft,
      /// X & Y position of the top left corner of the rectangle to invalidate.
      const PDim & dim,
      /// The width & height of the rectangle to invalidate.
      CoordinateSystem coords   /// Coordinate system to use.
    );
    void Invalidate(
      const PPoint & topLeft,
      /// X & Y position of the top left corner of the rectangle to invalidate.
      const PPoint & botRight,
     /**X & Y position of the bottom right corner of the rectangle to
         invalidate.
       */
      CoordinateSystem coords   /// Coordinate system to use.
    );
    void Invalidate(
      const PRect & rect,       /// The rectangle to invalidate.
      CoordinateSystem coords   /// Coordinate system to use.
    );
    void Invalidate();

   /**Mark the area of the interactor as {\bf not} requiring a redraw. This
       subtracts the specified rectangular area from an {\it update region}.
       If this region is not empty then a request to redraw that area of the
       interactor is queued to be processed by the message handling system. At
       some time later the \Ref{OnRedraw()} function is called with its
       canvas clipping region set to the update region.

       The parameterless form will validate the entire interactor.

       When scaling is used (#coords == LocalCoords#), the
       coordinates used are 1/4 average font width and 1/8 the font height.

       The user should not override this function. If some form of action is
       required on changing the interactors update region then the
       \Ref{_Validate()} function should be overridden.
     */
    void Validate(
      PORDINATE x,
      /// X position of the top left corner of the rectangle to validate.
      PORDINATE y,
      /// Y position of the top left corner of the rectangle to validate.
      PDIMENSION width,       /// Width of the rectangle to validate.
      PDIMENSION height,      /// Height of the rectangle to validate.
      CoordinateSystem coords /// Coordinate system to use.
    );
    void Validate(
      const PPoint & topLeft,
      /// X & Y position of the top left corner of the rectangle  invalidate.
      const PDim & dim,
      /// The width & height of the rectangle to validate.
      CoordinateSystem coords   /// Coordinate system to use.
    );
    void Validate(
      const PPoint & topLeft,
      /// X & Y position of the top left corner of the rectangle to validate.
      const PPoint & botRight,
     /**X & Y position of the bottom right corner of the rectangle to
         invalidate.
       */
      CoordinateSystem coords   /// Coordinate system to use.
    );
    void Validate(
      const PRect & rect,       /// The rectangle to validate.
      CoordinateSystem coords   /// Coordinate system to use.
    );
    void Validate();

   /**Force an immediate update of the window. This is used in conjuction with
       the \Ref{Invalidate()} and \Ref{Validate()} functions. If the
       {\it update region} specified by these functions is empty then this
       function does nothing, otherwise an update of the interactor contents
       is made.

       This will do a synchronous \Ref{OnRedraw()} call and guarantees that
       the screen is updated before returning. It us used to speed up the
       interaction with the user by not waiting for the standard delayed
       screen update.
     */
    void Update();


   /**Grab the mouse for exclusive use by this interactor. All mouse input,
       clicks etc will be directed to this interactor only regardless of the
       position of the mouse cursor.
       
       Note that the cursor grab is a system wide resource and {\bf must} be
       released by the application or it is possible to lock up the user
       interface for {\bf all} applications!
     */
    void GrabMouse();

   /**Relenquish the exclusive use of the mouse after a \Ref{GrabMouse()}
       call.

       Note that the cursor grab is a system wide resource and {\bf must} be
       released by the application or it is possible to lock up the user
       interface for {\bf all} applications!
     */
    void ReleaseMouse();

   /**Determine if this interactor currently has exclusive use of the mouse
       pointer.

       @return
       TRUE if has currently grabbed the mouse pointer.
     */
    BOOL HasMouse() const;


   /**Make this interactor have the user keyboard input focus. All keyboard
       input will now be directed to this interactor.

       Appropriate messages are sent to interactors for the focus change. The
       previous interactor receives a call to \Ref{OnLostFocus()} and the new
       interactor receives a \Ref{OnGainFocus()} call.
     */
    void GrabFocus();

   /**Determine if this interactor currently has the keyboard focus.

       Return: TRUE if has the current focus.
     */
    BOOL HasFocus() const;


   /**Set the cursor to be used for this interactor. The cursor is
       automatically set to this shape while the mouse is anywhere over this
       interactors client area or while the mouse pointer has been "grabbed"
       by the \Ref{GrabMouse()} function.

       A call to this function will reset the cursor to parent flag that may
       be set by the \Ref{SetCursorToParent()} function.
     */
    virtual void SetCursor(
      const PCursor & newCursor   /// New shape for mouse cursor.
    );

   /**Get the current cursor shape that is being used whenever the mouse
       pointer is over this interactor. This will be the cursor last set by the
       \Ref{SetCursor()} function and is {\bf not} subject to the
       \Ref{SetCursorToParent()} mode.

       @return
       current cursor object for interactor.
     */
    PCursor GetCursor() const;

   /**Set the cursor to always be whatever the interactors parent is using as
       a cursor shape. If the parents cursor is subsequently changed then the
       child interactors cursor is also changed.

       This does not change the current cursor as last set by the
       \Ref{SetCursor()} function.
     */
    void SetCursorToParent(
      BOOL useParent = TRUE  /// Flag for interactor to use parents cursor.
    );

   /**Set the current cursor to the new shape and set all child interactors to
       temporarily use that cursor.

       Note that subsequent calls to the SetAllCursors() and
       \Ref{SetWaitCursor()} functions are ignored until the corresponding
       \Ref{RestoreAllCursors()} function is called. That it these functions
       may {\bf not} be nested.
     */
    void SetAllCursors(
      const PCursor & newCursor   /// New shape for mouse cursor.
    );

   /**Restore the current cursor and all child interactors cursor to parent
       flags to the state as of the previous call to \Ref{SetAllCursors()}.
     */
    void RestoreAllCursors();

   /**Set the cursor for this interactor and all child interactors to the
       platform dependent standard {\it wait} cursor. This may be a watch or
       and hourglass as determined by the platform.

       This function is equivalent to calling
       #SetAllCursors(PCursor(PSTD_ID_CURSOR_WAIT))#.
     */
    void SetWaitCursor();

   /**Set the position of the cursor. As there is only one cursor for the
       entire system this may affect other applications.
       
       The point is usually in absolute screen coordinates, ie when
       #coords# parameter is #ScreenCoords#, but may also
       be relative to the interactors origin or scaled to the interactors font
       based layout coordinates.

       Note, this may not be available on all platforms in which case it does
       nothing. For this and other reasons of user interfcace design, it is not
       recommended that this function be used.

       When scaling is used (#coords == LocalCoords#), the
       coordinates used are 1/4 average font width and 1/8 the font height.
    
       The user should not override this function. If some form of action is
       required on changing the cursor position then the
       \Ref{_SetCursorPos()} function should be overridden.
     */
    void SetCursorPos(
      PORDINATE x,              /// New X position of cursor.
      PORDINATE y,              /// New Y position of cursor.
      CoordinateSystem coords   /// Coordinate system to use.
    );
    void SetCursorPos(
      const PPoint & pt,        /// New X & Y position of cursor.
      CoordinateSystem coords   /// Coordinate system to use.
    );

   /**Get the current cursor position in the interactors coordinate system.

       The point is usually in absolute screen coordinates, ie when
       #coords# parameter is #ScreenCoords#, but may also
       be relative to the interactors origin or scaled to the interactors font
       based layout coordinates.

       When scaling is used (#coords == LocalCoords#), the
       coordinates used are 1/4 average font width and 1/8 the font height.
     */
    PPoint GetCursorPos(
      CoordinateSystem coords   /// Coordinate system to use.
    ) const;

   /**Show or hide the mouse cursor. To be able to nest calls to this function
       an internal count is used. Whenever #show# the display count
       is incremented otherwise it is decremented. The cursor is displayed only
       when the count is greater than or equal to zero. The count is initially
       zero.
     */
    virtual void ShowCursor(
      BOOL show = TRUE    /// Flag for showing or hiding the cursor.
    );

   /**Hide the mouse cursor, this is equivalent to
       #ShowCursor(FALSE)#.
     */
    void HideCursor();


   /**Set the text caret shape to be as specified.

       The text caret is a small rectangle used to indicate the current
       position for editing text strings. It should only be present in
       interactors that contain the current keyboard focus.
     */
    void SetCaret(
      const PCaret & newCaret   /// New shape for the caret.
    );

   /**Get the current text caret shape.

       The text caret is a small rectangle used to indicate the current
       position for editing text strings. It should only be present in
       interactors that contain the current keyboard focus.

       @return
       current caret object for interactor.
     */
    PCaret GetCaret() const;

   /**Set the position of the text caret within the interactor.

       When scaling is used (#coords == LocalCoords#), the
       coordinates used are 1/4 average font width and 1/8 the font height.
    
       The user should not override this function. If some form of action is
       required on changing the interactors caret position then the
       \Ref{_SetCaretPos()} function should be overridden.
     */
    void SetCaretPos(
      PORDINATE x,              /// New X position of caret.
      PORDINATE y,              /// New Y position of caret.
      CoordinateSystem coords   /// Coordinate system to use.
    );
    void SetCaretPos(
      const PPoint & pt,        /// New X & Y position of caret.
      CoordinateSystem coords   /// Coordinate system to use.
    );

   /**Get the position of the text caret within the interactor.

       When scaling is used (#coords == LocalCoords#), the
       coordinates used are 1/4 average font width and 1/8 the font height.

       @return
       current position of the text caret.
     */
    PPoint GetCaretPos(
      CoordinateSystem coords   /// Coordinate system to use.
    ) const;

   /**Show or hide the text caret. To be able to nest calls to this function
       an internal count is used. Whenever #show# the display count
       is incremented otherwise it is decremented. The caret is displayed only
       when the count is greater than or equal to zero. The count is initially
       zero.
     */
    virtual void ShowCaret(BOOL show = TRUE);

   /**Hide the text caret, this is equivalent to
       #ShowCaret(FALSE)#.
     */
    void HideCaret();

   /**Set the default foreground colour of the interactor.
    
       This will be the initial colour set in the \Ref{PInteractorCanvas}
       instance created via a \Ref{PDrawCanvas} creation or via
       \Ref{OnRedraw()} function call by the system providing a
       \Ref{PRedrawCanvas}.

       On creation of the interator this is set to the colour specified by the
       \Ref{PApplication::GetWindowFgColour()} function.
     */
    virtual void SetForegroundColour(
      const PColour & newColour  /// New foreground colour for interactor.
    );

   /**Get the default foreground colour of the interactor.
    
       This will be the initial colour set in the \Ref{PInteractorCanvas}
       instance created via a \Ref{PDrawCanvas} creation or via
       \Ref{OnRedraw()} function call by the system providing a
       \Ref{PRedrawCanvas}.

       On creation of the interator this is set to the colour specified by the
       \Ref{PApplication::GetWindowFgColour()} function.

       @return
       colour for foreground of interactor.
     */
    const PColour & GetForegroundColour() const;

   /**Set the default background colour of the interactor.
    
       This will be the initial colour set in the \Ref{PInteractorCanvas}
       instance created via a \Ref{PDrawCanvas} creation or via
       \Ref{OnRedraw()} function call by the system providing a
       \Ref{PRedrawCanvas}.

       On creation of the interator this is set to the colour specified by the
       \Ref{PApplication::GetWindowBkColour()} function.
     */
    virtual void SetBackgroundColour(
      const PColour & newColour  /// New background colour for interactor.
    );

   /**Get the default background colour of the interactor.
    
       This will be the initial colour set in the \Ref{PInteractorCanvas}
       instance created via a \Ref{PDrawCanvas} creation or via
       \Ref{OnRedraw()} function call by the system providing a
       \Ref{PRedrawCanvas}.

       On creation of the interator this is set to the colour specified by the
       \Ref{PApplication::GetWindowBkColour()} function.

       @return
       colour for background of interactor.
     */
    const PColour & GetBackgroundColour() const;

   /**Get the width of vertical border and height of horizontal border for
       this interactor.
       
       This may be one of several values depending on the type of the
       interactor. For example a \Ref{PTitledWindow} would return a value as
       in the \Ref{PApplication::GetTitledBorderSize()} function.

       If the interactor does not have a border then #PDim(0,0)# is
       returned.

       @return
       current width of borders on interactor.
     */
    PDim GetBorderSize() const;

   /**Get the colour of the interactors border.
    
       The actual colour returned is dependent on the type of interactor and
       the current mode of the interactor. For instance for a
       \Ref{PTitledWindow} that is active, the value returned would be as
       specified by the \Ref{PApplication::GetActiveBorderColour()} function.

       @return
       colour for the border of the interactor.
     */
    const PColour & GetBorderColour() const;


   /**Begin a mouse track operation, calling the \Ref{OnMouseTrack()}
       function for each mouse move. The #interactor# parameter is
       the object on which the \Ref{OnMouseTrack()} function is called.

       The first form will start to track a drag using the current interactor
       as the \Ref{OnMouseTrack()} functions target object.

       The mouse pointer is automatically grabbed (via \Ref{GrabMouse()})
       and released (via \Ref{ReleaseMouse()}). A canvas may also be
       automatically created and deleted, and is provided to the
       \Ref{OnMouseTrack()} function.

       @return
       Canvas created for the track operation.
     */
    PCanvas * StartMouseTrack(
      BOOL wantsCanvas = FALSE   /// Create a canvas for the track operation.
    );
    PCanvas * StartMouseTrack(
      PInteractor * interactor,  /// Interactor that is to be used for track.
      BOOL wantsCanvas = FALSE   /// Create a canvas for the track operation.
    );


    /**@name System callback functions. */
   /**The system calls this whenever the mouse moves over the interactors
       usable area.
     */
    virtual void OnMouseMove(
      PKeyCode button,
     /**This key code is used to determine the modifiers (eg shift, control
         etc) that were active while the mouse was moved over the interactor.
         The value part of the key code is irrelevent.
       */
      const PPoint & where
     /**The position of the mouse pointer provided in pixels with its origin
         at the top left of the interactor.
       */
    );

   /**The system calls this whenever a mouse button is pressed in the
       interactors usable area.

       The two system parameters \Ref{PApplication::GetDoubleClickRect()} and
       \Ref{PApplication::GetDoubleClickTime()} control what constitutes a
       double click.
     */
    virtual void OnMouseDown(
      PKeyCode button,
     /**This key code is used to determine which mouse button was pressed and
         what modifiers that were active at that time. The mouse button that
         caused this call back is in the value part of the key code. The
         modifiers may indicate other mouse buttons being down at the same
         time.
       */
      const PPoint & where,
     /**The position of the mouse pointer provided in pixels with its origin
         at the top left of the interactor.
       */
      BOOL doubleClick
      /// Is TRUE if the mouse down is the second click of a double click.
    );

   /**The system calls this whenever a mouse button is released in the
       interactors usable area.
     */
    virtual void OnMouseUp(
      PKeyCode button,
     /**This key code is used to determine which mouse button was pressed and
         what modifiers that were active at that time. The mouse button that
         caused this call back is in the value part of the key code. The
         modifiers may indicate other mouse buttons being down at the same
         time.
       */
      const PPoint & where
     /**The position of the mouse pointer provided in pixels with its origin
         at the top left of the interactor.
       */
    );

   /**The system calls this whenever a keyboard key was pressed and this
       interactor had the focus.

       The key code passed in this function is a platform independent
       representation of a key cap. No ASCII or ANSI translation is made.

       It may be assumed that the OnKeyDown() function occurs before the
       \Ref{OnKeyInput()} function, but it should {\bf not} be assumed
       that the \Ref{OnKeyUp()} function occurs after \Ref{OnKeyInput()}
       function.

       @return
       TRUE if the \Ref{OnKeyInput()} function is to be called with the
       translated key value.
     */
    virtual BOOL OnKeyDown(
      PKeyCode key,   /// Key code representation of key that was pressed.
      unsigned repeat /// Count for auto-repeat.
    );

   /**The system calls this whenever a keyboard key was released and this
       interactor had the focus.

       The key code passed in this function is a platform independent
       representation of a key cap. No ASCII or ANSI translation is made.

       It may be assumed that the OnKeyDown() function occurs before the
       \Ref{OnKeyInput()} function, but it should {\bf not} be assumed
       that the \Ref{OnKeyUp()} function occurs after \Ref{OnKeyInput()}
       function.
     */
    virtual void OnKeyUp(
      PKeyCode key    /// Key code representation of key that was released.
    );

   /**The system calls this whenever a keyboard key was pressed and this
       interactor had the focus. The string is the translated ANSI
       representation of the key combination.

       It may be assumed that the OnKeyDown() function occurs before the
       \Ref{OnKeyInput()} function, but it should {\bf not} be assumed
       that the \Ref{OnKeyUp()} function occurs after \Ref{OnKeyInput()}
       function.
     */
    virtual void OnKeyInput(
      const PString & str  /// ANSI string representation for the key press.
    );

   /**The system calls this whenever the interactor is given the focus from
       another window in the system.

       This function is typically used to change the appearance of the
       interactor to indicate that it has the focus, for example in a
       \Ref{PEditBox} control the text caret is shown.
     */
    virtual void OnGainFocus();

   /**The system calls this whenever the interactor had the focus and it has
       been changed to another window in the system.

       This function is typically used to change the appearance of the
       interactor to indicate that it no longer has the focus, for example in a
       \Ref{PEditBox} control the text caret is hidden.
     */
    virtual void OnLostFocus();

   /**The system calls this whenever the interactor is given the focus the
       first time for a given \Ref{PTitledWindow} or \Ref{PInteractorLayout}.
       
       The interactor may have focus changed to interactors in other titled
       windows or interactor layouts but not to another interactor in the same
       window or layout before being approved by a call to
       \Ref{OnEndInput()}.

       This is primarily used to do field level validation within dialogs etc.
     */
    virtual void OnStartInput();

   /**The system calls this whenever the system wishes to change focus to
       another interactor in a given \Ref{PTitledWindow} or
       \Ref{PInteractorLayout}.

       This function in conjunction with the keyboard focus changing and the
       \Ref{SetFocusInteractor()} function controls the transfer of focus
       from one interactor in a logical group (eg dialog) to another. It is
       primarily used for field level validation. For example, the
       \Ref{PIntegerEditBox} control uses this to prevent the user from
       exiting the control until a valid entry hash been made.

       Note that the focus {\bf does} actually change with appropriate calls
       to the \Ref{OnGainFocus()} and \Ref{OnLostFocus()} functions. The
       focus gets set back to the original interactor when this function
       disallows the focus change.

       @return
       FALSE will prevent the focus change from occurring and TRUE allows the
       change.
     */
    virtual BOOL OnEndInput();

   /**The system calls this whenever it requires that the interactors usable
       area needs to be updated and redrawn.

       The canvas is usually a \Ref{PRedrawCanvas} instance with its clip
       region set to the current update region as determined by the
       \Ref{Invalidate()} and \Ref{Validate()} functions as well as those
       areas that were obscured by overlapping windows.
     */
    virtual void OnRedraw(
      PCanvas & canvas   /// Canvas to use when drawing the interactor contents.
    );

   /**This function is called whenever a control needs to notify its parent
       interactor that somthing has happened to it. The default behaviour
       of this function is is to call the notify function contained in the
       control object itself.
     */
    virtual void OnControlNotify(
      PControl & control,     /// Control that provides the notification.
      int option              /// Options for the type of notification.
    );

   /**This function is called whenever a help select mode is activated and
       this interactor is selected.
     */
    virtual void OnSelectHelp();

   /**This function is called whenever a balloon help function for the
       interactor is required.

       @return
       Pointer to balloon window containing balloon help text.
     */
    virtual PBalloon * OnBalloonHelp();


   /**This function is called whenever a drag track is in progress. This is
       begun with a call to the \Ref{StartMouseTrack()} function, which is
       typically called from within the \Ref{OnMouseDown()} function.

       The #lastTrack# parameter can be used to for special action
       at the end of the track operation.

       The mouse pointer is automatically grabbed (via \Ref{GrabMouse()})
       and released (via \Ref{ReleaseMouse()}). The canvas provided is
       also automatically created and deleted.
     */
    virtual void OnMouseTrack(
      PCanvas * canvas,
      /// The canvas available while the drag operation is tracking.
      const PPoint & where,
     /**The position of the mouse pointer provided in pixels with its origin
         at the top left of the interactor.
       */
      BOOL lastTrack
      /// This is TRUE if the position is the last track of the drag operation.
    );


  protected:
    /** Special constructor used with PTopLevelWindow. */
    PInteractor();

  /**@name New functions for class */
   /**Set the position of the interactor. The #xOrigin# and
       #yOrigin# parameters indicate the coordinate system to be
       used for the offsets. If the font based layout coordinates are used
       they will use the font of the {\it parents} interactor. The
       interactors font is {\bf not} used.

       Note that this sets the position of the exterior of the interactor,
       including any decoration, eg title bars etc.

       When scaling is used (#coords == LocalCoords#), the
       coordinates used are 1/4 average font width and 1/8 the font height.
     */
    virtual void _SetPosition(
      PORDINATE x,             /// Horizontal offset to apply to interactor.
      PORDINATE y,             /// Vertical offset to apply to interactor.
      PositionOrigin xOrigin,  /// Origin for horizontal offset.
      PositionOrigin yOrigin   /// Origin for verical offset.
    );

   /**Set the dimensions of the interactor. The new size is specified in
       either the font based layout coordinates or in screen pixels as
       specified by the #coords# parameter.

       Note that this sets the dimension of the interior of the interactor,
       excluding any decoration, eg title bars etc.
       
       When scaling is used (#coords == LocalCoords#), the
       coordinates used are 1/4 average font width and 1/8 the font height.
     */
    virtual void _SetDimensions(
      PDIMENSION width,         /// New width to apply to interactor.
      PDIMENSION height,        /// New height to apply to interactor.
      CoordinateSystem coords   /// Coordinate system to use.
    );

   /**Mark the area of the interactor as requiring a redraw. This adds the
       specified rectangular area to an {\it update region}. If this region
       is not empty then a request to redraw that area of the interactor is
       queued to be processed by the message handling system. At some time
       later the \Ref{OnRedraw()} function is called with its canvas clipping
       region set to the update region.

       The parameterless form will invalidate the entire interactor.

       When scaling is used (#coords == LocalCoords#), the
       coordinates used are 1/4 average font width and 1/8 the font height.
     */
    virtual void _Invalidate(
      PORDINATE x,
      /// X position of the top left corner of the rectangle to invalidate.
      PORDINATE y,
      /// Y position of the top left corner of the rectangle to invalidate.
      PDIMENSION width,         /// Width of the rectangle to invalidate.
      PDIMENSION height,        /// Height of the rectangle to invalidate.
      CoordinateSystem coords   /// Coordinate system to use.
    );

   /**Mark the area of the interactor as {\bf not} requiring a redraw. This
       subtracts the specified rectangular area from an {\it update region}.
       If this region is not empty then a request to redraw that area of the
       interactor is queued to be processed by the message handling system. At
       some time later the \Ref{OnRedraw()} function is called with its
       canvas clipping region set to the update region.

       The parameterless form will validate the entire interactor.

       When scaling is used (#coords == LocalCoords#), the
       coordinates used are 1/4 average font width and 1/8 the font height.
     */
    virtual void _Validate(
      PORDINATE x,
      /// X position of the top left corner of the rectangle to validate.
      PORDINATE y,
      /// Y position of the top left corner of the rectangle to validate.
      PDIMENSION width,         /// Width of the rectangle to validate.
      PDIMENSION height,        /// Height of the rectangle to validate.
      CoordinateSystem coords   /// Coordinate system to use.
    );

   /**Set the position of the cursor. As there is only one cursor for the
       entire system this may affect other applications.
       
       The point is usually in absolute screen coordinates, ie when
       #coords# parameter is #ScreenCoords#, but may also
       be relative to the interactors origin or scaled to the interactors font
       based layout coordinates.

       Note, this may not be available on all platforms in which case it does
       nothing. For this and other reasons of user interfcace design, it is not
       recommended that this function be used.

       When scaling is used (#coords == LocalCoords#), the
       coordinates used are 1/4 average font width and 1/8 the font height.
     */
    virtual void _SetCursorPos(
      PORDINATE x,              /// New X position of cursor.
      PORDINATE y,              /// New Y position of cursor.
      CoordinateSystem coords   /// Coordinate system to use.
    );

   /**Set the position of the text caret within the interactor.

       When scaling is used (#coords == LocalCoords#), the
       coordinates used are 1/4 average font width and 1/8 the font height.
     */
    virtual void _SetCaretPos(
      PORDINATE x,              /// New X position of caret.
      PORDINATE y,              /// New Y position of caret.
      CoordinateSystem coords   /// Coordinate system to use.
    );


   /**Set the child interactor that has the focus in the \Ref{PTitledWindow}
       or \Ref{PInteractorLayout}.

       The interactor set here may not actually have the focus. It is the
       interactor that will be given the focus if the parent interactor,
       eg a dialog, is given the focus. The dialog itself never requires the
       focus directly.

       The default behaviour is to pass the interactor on to its parent
       using its \Ref{SetFocusInteractor()} function.
     */
    virtual void SetFocusInteractor(
      PInteractor * interactor    /// Interactor that received focus.
    );

   /**Get the child interactor that has the focus in the \Ref{PTitledWindow}
       or \Ref{PInteractorLayout}.

       The interactor returned here may not actually have the focus. It is
       the interactor that will be given the focus if the parent interactor,
       eg a dialog, is given the focus. The dialog itself never requires the
       focus directly.

       The default behaviour is to get the interactor from its parent
       using its \Ref{GetFocusInteractor()} function.

       @return
       pointer to child or grandchild interactor that has focus.
     */
    virtual PInteractor * GetFocusInteractor() const;

   /**Scan through all child interactors and if they are a command source,
       execute their notification function to enable or disable the item.

       The default behaviour is to call \Ref{UpdateCommandSources()} for all
       child interactors.

       This function is used internally by the library. It would normally not
       be called directly.
     */
    virtual void UpdateMyCommandSources();


    // Member variables
      /** The interactors owner application */
    PApplication * owner;

      /** The interactor layout that contains this interactor. */
    PInteractor * parent;

      /** The list of children in this interactor layout. */
    PInteractorList children;

      /** The font used by the interactor. */
    PRealFont font;
      
      /** Flag to indicate that the parent interactor layouts cursor should be
          used with this interactor. */
    enum {
      UseCurrentCursor, UseParentCursor, UseSetAllCursor, UseSetAllParentCursor
    } cursorMode;

      /** The normal mouse cursor to be used in this interactor. */
    PCursor cursor;

      /** The saved mouse cursor to be used in this interactor after a call to
          \Ref{RestoreAllCursors()}. */
    PCursor savedCursor;

      /** The text caret to be used in this interactor. */
    PCaret caret;

      /** The current location of the caret (in pixels). */
    PPoint caretPosition;

      /** The current count for visibility of caret in interactor. */
    int caretVisible;

      /** The foreground colour used in this interactor */
    PColour foregroundColour;

      /** The background colour used in this interactor */
    PColour backgroundColour;

      /** The interactor used in the dracking of a drag operation, if NULL no
          drag track is happening. */
    PInteractor * mouseTrackInteractor;

      /** The canvas used in the dracking of a drag operation, if NULL no drag
          track is happening. */
    PInteractorCanvas * mouseTrackCanvas;

    friend class PInteractorCanvas;
    

  private:
    PInteractor(const PInteractor & interactor);
    PInteractor & operator=(const PInteractor & interactor);
      // Cannot make copies of the interactor
      
    
    virtual void _OnMouseMove(PKeyCode button, const PPoint & where);
   /* Internal function for on a mouse move, calls \Ref{OnMouseMove()} or
       \Ref{OnMouseTrack()}.
     */

    virtual void _OnMouseUp(PKeyCode button, const PPoint & where);
   /* Internal function for on a mouse move, calls \Ref{OnMouseUp()} or
       \Ref{OnMouseTrack()}.
     */


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


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