diff options
Diffstat (limited to 'kviewshell/pageSize.h')
| -rw-r--r-- | kviewshell/pageSize.h | 280 |
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 |