Copy the KDE 3.5 branch to branches/trinity for new KDE 3.5 features.

BUG:215923


git-svn-id: svn://anonsvn.kde.org/home/kde/branches/trinity/kdegraphics@1054174 283d02a7-25f6-0310-bc7c-ecb5cbfe19da

1 files changed, 280 insertions, 0 deletions

diff --git a/kviewshell/pageSize.h b/kviewshell/pageSize.h
new file mode 100644
index 00000000..5ba0194e
--- /dev/null
+++ b/kviewshell/pageSize.h
@@ -0,0 +1,280 @@
+// -*- 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