path: root/kviewshell/pageSize.h

// -*- C++ -*-
//
// pageSize.h
//
// Part of KVIEWSHELL - A framework for multipage text/gfx viewers
//
// (C) 2002-2005 Stefan Kebekus
// Distributed under the GPL

// Add header files alphabetically

#ifndef PAGESIZE_H
#define PAGESIZE_H

#include "simplePageSize.h"

#include <qobject.h>

class QString;
class QStringList;


/* \brief This class represents physical page sizes.

The main difference to the SimplePageSize class are the following.

- This class knows about standard page sizes and accepts page sizes in
  various formats, e.g. as a string "DIN A4", or by specifiying the
  page width and height. Several units (inch, millimeters,
  centimeters) are possible.

- It is made sure that page width an hight are always in a resonable
  range, which is currently set to 5cm .. 50cm

- The default constructor provides a locale-depending default.

@author Stefan Kebekus <kebekus@kde.org>
@version 1.0.0
*/

class pageSize : public QObject, public SimplePageSize
{
Q_OBJECT

public:
  /** \brief Default constructor, initializes the pageSize with a
      reasonable default

      The default chosen depends on the locale. At the moment, A4 size
      is chosen for countries with metric measurement system, and US
      letter otherwise.      
  */
  pageSize();

  /** \brief Initializes the pageSize with a SimplePageSize. */
  pageSize(const SimplePageSize&);

  /** \brief List of standard pageSizes

  This method returns the names of standard pageSizes,
  e.g. "A4". These can be used, e.g., by a QComboBox to let the user
  choose known sizes. The returned list is also a list of all possible
  return values of the formatName() method explained below. If you
  call pageSizeNames() more than once, it is guaranteed that the
  same list of strings will be returned.

  @returns QStringList that contains 
  */
  QStringList pageSizeNames();
  
  /** \brief Set page size by name.

  Acceptable strings are
      
  (1) a name from the list retured by pageSizeNames(), such as "DIN
      A4"
  
  (2) a string like "500x300", which describes a page of width 500mm
      and height 300mm.

  (3) a string like "3in, 4 cm". A number of different units,
      including "in", "mm" and "cm", and a few typographical units are
      recognized
	  
  If the name is not of these types, and error message is printed to
  stderr using kdError() and a default value, which depends on the
  locale, is set. 

  In any case, the values will be trimmed so as not to exceed the
  minima/maxima of 5cm and 50cm, respectively. If the page size found
  matches one of the standard sizes by an error of no more than 2mm,
  the standard page size will be set. The signal sizeChanged() will
  always be emitted.

  @param name string that represents the page size

  @returns 'True', if the parameter could be parsed, and 'false'
  otherwise.
  */
  bool        setPageSize(const QString& name);
  
  /** \brief Set page size from width and height strings

  Sets the page size to "width" and "height", given in the associated
  units. Currently, "mm", "cm" and "in" are supported. If a unit is
  not recognized, "mm" is siliently assumed, and error message is
  printed to stderr using kdError(). If the page size set matches one
  of the standard sizes by an error of no more than 2mm, the standard
  page size will be set.  If width or height does not contain a
  number, the result is an undefined value. However, it is guaranteed
  in any case that both width and height are between the minimal and
  maximal possible values, i.e. in the range 5..50 cm. If the newly
  set value differs from the old value by more that 2mm for width or
  height, the signal sizeChanged() will be emitted

  @param width string that represents the page width as a number,
  e.g., " 300 "

  @param widthUnits units for the width string. Currently "mm", "cm"
  and "in" are allowed.

  @param height string that represents the page height as a number,
  e.g., " 300 "

  @param heightUnits units for the height string. Currently "mm", "cm"
  and "in" are allowed.
  */
  void        setPageSize(const QString& width, const QString& widthUnits, const QString& height, const QString& heightUnits);

  /** \brief Set page size

  Sets the page size to "width" and "height", given in millimeter.  If
  the page size set matches one of the standard sizes by an error of
  no more than 2mm, the standard page size will be set.  Values are
  trimmed so that both width and height are between the minimal and
  maximal possible values, i.e. in the range 5..50 cm. If the newly
  set value differs from the old value by more that 2mm for width or
  height, the signal sizeChanged() will be emitted

  @param width_in_mm page width in mm
  
  @param height_in_mm page height in mm
  */
  virtual void setPageSize(double width_in_mm, double height_in_mm);

  /** \brief Copy operator. 

  This operator will emit the signal sizeChanged() if one of the
  dimensions of *this and src differ by more than two millimeters. 
  */
  pageSize &  operator= (const pageSize &src);

  /** \brief Preferred unit for the current page size

  @returns The name of the unit, one of "cm", "mm" or "in", which is
      most commonly used with the current page format. For instance,
      US Letter and US Legal are best given in inches, to avoid very
      odd numbers. If the page format is unknown, returns a guess
      based on the current locale. */
  QString     preferredUnit() const;

  /** \brief Returns the page width as a string

  @param unit The unit in which the page width shall be returned. This
  must be one of "cm", "mm" or "in".

  @returns a string containing a number, e.g. "3.1415", which gives the page
  width in the given unit.  If the unit is not recognized, the string "--" is returned.
  */
  QString     widthString(const QString& unit) const;

  /** \brief Returns the page height as a string

  @param unit The unit in height the page width shall be
  returned. This must be one of "cm", "mm" or "in".

  @returns a string containing a number which gives the page height in
  the given unit. If the unit is not recognized, the string "--" is
  returned.
  */
  QString     heightString(const QString& unit) const;

  /** \brief Returns a name for the page size, if this is a standard
      size
      
      @warning This method does not take care of orientation, e.g. it
      will return "DIN A4" if the page size is either 210x297 or
      297x210.
      
      @returns A name for the current page size, if the format has a
      name, or QString::null otherwise. If the result is not
      QString::null, it is guaranteed to be one of the strings
      returned by the pageSizeNames() method.
  */
  QString     formatName() const;

  /** \brief Returns an number for the page size, if this is a
      standard size
      
      @warning This method does not take care of orientation, e.g. it
      will return the same value if the page size is either 210x297 or
      297x210.
      
      @returns If the current format is one of the standard sizes, a
      non-negative integer is returned, which is an index to the
      QStringList returned by the pageSizeNames() method. If the
      current format is none of the standard sizes, -1 is returned.
  */
  int         formatNumber() const {return currentSize;}
  
  /** \brief Gets orientation for standard sizes

  If the pageSize is one of the standard sizes, i.e. formatNumber() !=
  -1, this method can be used to get the orientation. If the pageSize
  is not a standard size, this method prints an error message stderr
  using kdError().

  @returns 0 for 'portrait', or 1 for 'landscape'. If the size is none
  of the standard sizes, an undefined value is returned.
  */
  int         getOrientation() const;

  /** \brief Returns a string that can be read by setPageSize(QString)

  @returns This method returns a string like "210x297". The numbers
  are page width and height in millimeters. The setPageSize(QString)
  method will understand this output.
  */
  QString     serialize() const;

public slots:
  /** \brief Sets orientation

  If the pageSize is one of the standard sizes, i.e. formatNumber() !=
  -1, this method can be used to set the orientation. If the pageSize
  is not a standard size, this method prints an error message stderr
  using kdError() and does nothing.

  @param orient 0 sets 'portrait orientation', 1 sets 'landscape'
 */
  void        setOrientation(int orient);

signals:
  /** \brief Signal emitted when the page sizes changes

  emitted to indicate that the size changed. Not emitted immediately
  after construction, when the constructor sets the default
  size.

  @param t a pointer to this
  */
  void        sizeChanged(const SimplePageSize& t);

private:
  /** Makes sure that pageWidth and pageHeight are in the permissible
      range and not, e.g., negative. */
  void        rectifySizes();

  /** Tries to find one of the known sizes which matches pageWidth and
      pageHeight, with an error margin of 2 millimeters. If found, the
      value of 'currentsize' is set to point to the known size, and
      pageWidth and pageHeight are set to the correct values for that
      size. Otherwise, currentSize is set to -1 to indicate "custom
      size". Note: this method does not take care of orientation,
      e.g. the method will set 'currentsize' to point to "DIN A4" if
      either the page size is 210x297 or 297x210. */
  void        reconstructCurrentSize();

  /** Gives a default value for currentSize, which depends on the
      locale. In countries with metric system, this will be "DIN A4",
      in countries with the imperial system, "US Letter". */
  int         defaultPageSize();

  /** Permissible range: 0--#Size_of_array staticList, or -1 to
      indicate a "user defined setting". Other values may lead to a
      segfault. */
  int         currentSize;
};

#endif