Fixed bug in using relative times eg "1 month ago".

[pwlib.git] / include / pwclib / toolbars.h

/*
 * toolbars.h
 *
 * Tool Bar Interactor GUI classes.
 *
 * 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.22  1999/03/09 08:01:47  robertj
 * Changed comments for doc++ support (more to come).
 *
 * Revision 1.21  1999/02/16 08:08:28  robertj
 * MSVC 6.0 compatibility changes.
 *
 * Revision 1.20  1998/09/23 06:20:09  robertj
 * Added open source copyright license.
 *
 * Revision 1.19  1996/04/30 12:34:10  robertj
 * Changed "inPixels" boolean to enum for three coordinate systems.
 *
 * Revision 1.18  1995/10/14 15:11:59  robertj
 * Fixed bug in changing fonts on status bar.
 *
 * Revision 1.17  1995/07/31 12:13:03  robertj
 * Added balloon help string to toolbar button codes.
 *
 * Revision 1.16  1995/06/17 11:13:39  robertj
 * Documentation update.
 *
 * Revision 1.15  1995/06/04 12:38:26  robertj
 * Redesign to add vertical tool bars and control wrapping.
 *
 * Revision 1.14  1995/04/02 09:27:35  robertj
 * Added "balloon" help.
 *
 * Revision 1.13  1995/03/22 13:51:17  robertj
 * Split SetText() to separate function for SetSectionText() to guarentee that
 *     the parameters can be resolved.
 *
 * Revision 1.12  1995/03/14  12:42:54  robertj
 * Updated documentation to use HTML codes.
 *
 * Revision 1.11  1995/02/19  04:19:23  robertj
 * Added dynamically linked command processing.
 *
 * Revision 1.10  1995/01/18  09:04:12  robertj
 * Added initialiser arrays for button bar and status bar.
 * Documentation.
 *
 * Revision 1.9  1995/01/15  04:53:11  robertj
 * Fixed problems with stdarg and PString parameter on GNU compiler.
 *
 * Revision 1.8  1995/01/10  11:44:36  robertj
 * Removed PString parameter in stdarg function for GNU C++ compatibility.
 *
 * Revision 1.7  1994/10/30  11:47:26  robertj
 * Changed mechanism for doing notification callback functions.
 *
 * Revision 1.6  1994/08/23  11:32:52  robertj
 * Oops
 *
 * Revision 1.5  1994/08/22  00:46:48  robertj
 * Added pragma fro GNU C++ compiler.
 *
 * Revision 1.4  1994/08/21  23:43:02  robertj
 * Changed parameter before variable argument list to NOT be a reference.
 *
 * Revision 1.3  1994/08/04  01:43:48  robertj
 * Removed comments.
 *
 * Revision 1.2  1994/07/27  05:58:07  robertj
 * Synchronisation.
 *
 * Revision 1.1  1994/04/01  14:25:36  robertj
 * Initial revision
 */


#ifndef _PTOOLBARS
#define _PTOOLBARS

#ifdef __GNUC__
#pragma interface
#endif


/**A class representing a tool bar. This is an interactor layout containing
   a series of controls and having a "chiselled" 3-d boundary. The controls
   added to the tool bar are automatically positioned according to some
   simple rules.
   
   The bar may be horizontal or vertical. The actual positioning of the bar
   is usually determined by the parent interactor positioning it using the
   \ref{PInteractor::AutoAdjustBounds()} function.

   A horizontal bar positions controls added across a row with optional
   wrapping to the next row when passed the end of the bar. A vertical bar
   positions controls down in a column optionally wrapping to a new column
   when beyond the bottom of the bar.

   Functionaly, this is very similar to a non-modal dialog but has a different
   "look", that is does not have a title bar and cannot be moved under user
   control.

   A tool bar is mainly used as the ancestor to the standard classes
   \ref{PButtonBar} and \ref{PStatusBar}.
 */
class PToolBar : public PInteractorLayout
{
  PCLASSINFO(PToolBar, PInteractorLayout);

  public:
  /**@name Construction */
  //@{
    /**Create a new empty tool bar. The #vertical# parameter
       indicates that the controls are positioned down the bar. The
       #autoWrap# parameter indicates that controls added beyond
       the right (or bottom) of the bar are repositioned to the left (or top)
       and below (or next to) the previous row (or column).
     */
    PToolBar(
      PInteractor * parent,    /// Parent interactor for the tool bar.
      BOOL vertical = FALSE,   /// Tool bar is vertical.
      BOOL autoWrap = FALSE    /// Wrap controls at end of bar.
    );
  //@}


  /**@name New functions for class */
  //@{
    /**Add a control to the tool bar. The new control is placed next to the
       last control added adjusting its position.
     */
    void AddControl(
      PControl * control,   /// Control to add to the list of automatically.
      PDIMENSION gapSize = 0,
        /// Amount "gap units" to leave between this control and the next one.
      PDIMENSION elasticity = 0
        /**Elasticity of control, 0 is may not be resized. A non-zero value
           is the ratio of all elastic controls to be resized when the size of
           the bar is changed.
         */
    );
  //@}

  protected:
  /**@name Overrides from class PInteractor */
  //@{
    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.
    );
    /* Set the dimensions of the status bar. The new size is specified in
       either the font based layout coordinates or in screen pixels as
       specified by the #coords# parameter.

       All static text sections within the status bar are resized according
       to their relative and absolute widths.

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

    virtual void OnRedraw(
      PCanvas & canvas   // Canvas to use when drawing the interactor contents.
    );
    /* The system calls this whenever it requires that the interactors usable
       area needs to be updated and redrawn.

       The behaviour here is to draw the "chiselled" 3-d look of a tool bar.
     */


    virtual PBalloon * OnBalloonHelp();
    /* This function is called whenever a balloon help function for the
       interactor is required.

       @return
       Pointer to balloon window containing balloon help text.
     */
  //@}

  /**@name New functions for class */
  //@{
    void DoControlGeometry();
    // Do the geometry calculations for the controls in the bar.
  //@}


  // Member variables
    class BarItem : public PObject
    {
      PCLASSINFO(BarItem, PObject);
      public:
        BarItem(PControl * c, PDIMENSION g, PDIMENSION e)
          : control(c), gapSize(g), elasticity(e) { }
        PControl * control;
        PDIMENSION gapSize;
        PDIMENSION elasticity;
    };
    PLIST(BarItems, BarItem);
    BarItems   item;
    PDim       margin;
    BOOL       positionDown;
    BOOL       wrapControls;
};


/**A class representing a tool bar consisting of a series of picture button
   controls. The picture for the button is loaded from a resource with the
   specified number in the array pass to the constructor. This number is
   then used as the control ID for thge picture button. When one of these
   buttons is pressed the specified ID is again used in determining which
   main menu item to simulate.
 */
class PButtonBar : public PToolBar
{
  PCLASSINFO(PButtonBar, PToolBar);

  public:
  /**@name Construction */
  //@{
    /** Initialisation structure for static array of button definitions
     */
    struct ButtonID {
      /**Resource ID of the "linked" menu item. Pressing the button will be
         equivalent to selecting this menu item.
       */
      PRESOURCE_ID menuItem;
      /**The name of the \ref{PCommandSink} that will be executed when the
         button is pressed. This is also used to enable/disable the button.
       */
      const char * commandName;
      /**Resource ID of the image when the button is enabled. If this is zero
         then the #menuItem# field is used.
       */
      PRESOURCE_ID enabledImage;
      /**Resource ID of the image when the button is disabled. If this is zero
         then the #enabledImage# field is used. If that field is
         also zero then the #menuItem# field is used.
       */
      PRESOURCE_ID disabledImage;
      /**Resource ID of the string to be used as the balloon help. If this is
         zero then the #menuItem# field is used.
       */
      PRESOURCE_ID balloonHelp;
    };

    /** Create a new button bar.
     */
    PButtonBar(
      PInteractor * parent,   /// Parent interactor for button bar.
      const ButtonID * IDs,   /// Array of button identifier structures.
      PINDEX numIDs,          /// Number of button identifier structures.
      BOOL vertical = FALSE,  /// Tool bar is vertical.
      BOOL autoWrap = FALSE   /// Wrap controls at end of bar.
    );
  //@}

  /**@name New functions for class */
  //@{
    /**Add a list of image buttons to the button bar.
     */
    void AddButtons(
      const ButtonID * IDs,   /// Array of button identifier structures.
      PINDEX numIDs           /// Number of button identifier structures.
    );
  //@}


  protected:
  /**@name Overrides from PInteractor */
  //@{
    virtual void OnControlNotify(
      PControl & control,     // Control that provides the notification.
      int option              // Options for the type of notification.
    );
    /* This function is called whenever a control needs to notify its parent
       interactor that somthing has happened to it.
       
       The behaviour here is to call the
       \ref{PTopLevelWindow::OnMenuItemSelect()} function for the menu item if
       the ID specified for the image button.
     */
  //@}
};


/**A class representing a tool bar consisting of a series of static text
   controls with 3-D borders. The static text sections may be optionaly of
   a fixed width or dynamically resized when the status bar has its size
   changed.

   This is typically used at the bottom of a window to indicate status and
   short message displays.
 */
class PStatusBar : public PToolBar
{
  PCLASSINFO(PStatusBar, PToolBar);

  public:
  /**@name Construction */
  //@{
    /**Create a new status bar with the specified number of static text
       descendent controls as sections of the bar.
     */
    PStatusBar(
      PInteractor * parent, // Parent interactor for the status bar.
      PINDEX numSections    // Number of sections in the status bar.
    );
  //@}

  /**@name Overrides from PInteractor */
  //@{
    /**Set the font to be used by default by this interactor. A canvas created
       on this interactor will initially have this font selected.
     */
    virtual void SetFont(
      const PFont & newFont, /// New font specification fo rthe interactor.
      BOOL toChildren = TRUE
        /// Flag to recursively change all child interactors.
    );
  //@}

  /**@name New functions for class */
  //@{
    /**Set the text in the first section. */
    void SetText(
      const PString & str /// New text string for section
    );
    /**Set the text in the first section. */
    void SetText(
      PRESOURCE_ID resId,
                 /// Printf style format resource string for variable arguments.
      ...
    );
    /**Set the text in the first section.
       
       The text may be set using printf style variable arguments. If this is
       done then the format string cannot be a \ref{PString} instance due to
       limitations in some compilers.

       If no section number is specified then the first section is set.
     */
    void SetText(
      const char * fmt,   /// Printf style format string for variable arguments.
      ...
    );

    /**Set the text in the section number specified. */
    void SetSectionText(
      PINDEX section,     /// Number of static text section to change.
      const PString & str /// New text string for section
    );
    /**Set the text in the section number specified. */
    void SetSectionText(
      PINDEX section,     /// Number of static text section to change.
      PRESOURCE_ID resId,
                 /// Printf style format resource string for variable arguments.
      ...
    );
    /**Set the text in the section number specified. The first section is
       numbered zero.
       
       The text may be set using printf style variable arguments. If this is
       done then the format string cannot be a \ref{PString} instance due to
       limitations in some compilers.

       If no section number is specified then the first section is set.
     */
    void SetSectionText(
      PINDEX section,     /// Number of static text section to change.
      const char * fmt,   /// Printf style format string for variable arguments.
      ...
    );

    /**Set the width of each section in the status bar. */
    void SetSectionWidth(
      PINDEX section,     /// Number of static text section to change.
      const PString & str /// Longest text string to put into section.
    );
    /**Set the width of each section in the status bar. */
    void SetSectionWidth(
      PINDEX section,     /// Number of static text section to change.
      const PRESOURCE_ID * strIDs,  /// Array of string resource identifiers.
      PINDEX nStrings               /// Number of string resource identifiers.
    );
    /**Set the width of each section in the status bar.
    
       The first form will set the width to sufficient to contain the string
       specified, in the status bars currently selected font.
       
       The second form sets the width to the widest string in the specified
       array of resource strings.
       
       The final form sets the width directly. A positive value specifies the
       fixed width if the section in the interactors font based coordinate
       system.

       A negative width here will specify a ratio to be used when dividing the
       total remaining bar width amongst all sections with negative widths.

       If a section has its width changed after the status bar is shown then
       an explicit call to the \ref{PInteractor::SetDimensions()} function
       must be made to resize all of the sections.

       The default width for a section is -1.
     */
    void SetSectionWidth(
      PINDEX section,     /// Number of static text section to change.
      int width           /// Width of the section.
    );

    /**Set the text alignement options for the specified section. */
    void SetSectionAlignment(
      PINDEX section,     /// Number of static text section to change.
      PCanvas::DrawStringOptions align    /// text alignment for section.
    );
  //@}

  protected:
    class Section : public PStaticText
    {
      PCLASSINFO(Section, PStaticText);
      public:
        Section(PInteractor * parent);
      protected:
        virtual void OnRedraw(PCanvas & canvas);
      friend class PStatusBar;
    };


    /**Get the specified section of the status bar. This will assert if the
       section does not exist or is not a descendent of the
       #PStatusBar::Section# class.

       @return
       a reference to the section.
     */
    Section & GetSection(
      PINDEX section    /// Number of section to get.
    ) const;
};


#endif

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