diff --git a/Scribus/scribus/units.cpp b/Scribus/scribus/units.cpp index 4817eee..5c8f40a 100644 --- a/Scribus/scribus/units.cpp +++ b/Scribus/scribus/units.cpp @@ -24,24 +24,35 @@ for which a new license (GPL+exception) is in place. #include "units.h" /*! - * @brief Returns the ratio to points for the selected unit of measure. Ratios are for: PT, MM, IN, P, CM, C. DEG and PCT return 1.0 as they will never convert + * \brief Get ratio from unit to points. + * + * \param unit see #ScUnit for valid unit + * \return 0 if unvalid unit, + * 1 if for %Points, %Degrees and %Percent unit, + * ratio for other unit */ -double unitGetRatioFromIndex(const int index) +double unitGetRatioFromIndex(const int unit) { //PT, MM, IN, P, CM, C (Cicero) //NOTE: Calling functions that divide by this value will crash on divide by 0. They shouldnt be getting - // a zero value if they are accessing here with a correct index. - if (indexUNITMAX) + // a zero value if they are accessing here with a correct unit. + if (unitUNITMAX) return 0; // PT, MM, IN, P, CM, C, °, % double ratio[] = { 1.0, 25.4/72.0, 1.0/72.0, 1.0, 2.54/72.0, 25.4/72.0/4.512, 1.0, 1.0 }; // double ratio[] = { 1.0, 25.4/72.0, 1.0/72.0, 1.0/12.0, 2.54/72.0, 25.4/72.0/4.512, 1.0, 1.0 }; - return ratio[index]; + return ratio[unit]; } -int SCRIBUS_API unitGetBaseFromIndex(const int index) +/*! + * \brief Get unit base. + * + * \param unit see #ScUnit for valid unit + * \return unit base + */ +int SCRIBUS_API unitGetBaseFromIndex(const int unit) { - if (index==SC_P) + if (unit==SC_P) return 12; return 10; } @@ -89,7 +100,10 @@ double unitValueFromString(const QString& value) } /*! - * @brief Strip the text from a value and return the Unit index for the value + * \brief Get unit from string. + * + * \param value string to consider + * \return unit, see #ScUnit for valid unit */ scUnit unitIndexFromString(const QString& value) { @@ -133,73 +147,95 @@ scUnit unitIndexFromString(const QString& value) } /*! - * @brief Returns the suffix used in GUI widgets + * \brief Get GUI suffix for unit. + * + * GUI suffix have a whitespace prepended. + * See unitGetStrFromIndex() for general suffix. + * \param unit see #ScUnit for valid unit + * \return a translated GUI suffix */ -const QString unitGetSuffixFromIndex(const int index) +const QString unitGetSuffixFromIndex(const int unit) { - if (index==SC_P) + if (unit==SC_P) { return ""; } - return QString(" %1").arg(unitGetStrFromIndex(index)); + return QString(" %1").arg(unitGetStrFromIndex(unit)); } /*! - * @brief Returns a general suffix for each of the units + * \brief Get general suffix for unit. + * + * See unitGetSuffixFromIndex() for GUI suffix. + * \param unit see #ScUnit for valid unit + * \return a translated general suffix */ -const QString unitGetStrFromIndex(const int index) +const QString unitGetStrFromIndex(const int unit) { - if (indexUNITMAX) + if (unitUNITMAX) return ""; QString suffix[] = { - QObject::tr("pt"), - QObject::tr("mm"), - QObject::tr("in"), - QObject::tr("p"), - QObject::tr("cm"), - QObject::tr("c"), - QObject::tr("\xB0", "degrees, unicode 0xB0"), //degree - QObject::tr("%") - }; - return suffix[index]; + QObject::tr("pt"), + QObject::tr("mm"), + QObject::tr("in"), + QObject::tr("p"), + QObject::tr("cm"), + QObject::tr("c"), + QObject::tr("\xB0", "degrees, unicode 0xB0"), //degree + QObject::tr("%") + }; + return suffix[unit]; } /*! - * @brief Returns a general untranslated suffix for each of the units + * \brief Get unstanslated general suffix for unit + * + * See unitGetStrFromIndex() for translated one. + * \param unit see #ScUnit for valid unit + * \return an unstranslated general suffix */ -const QString unitGetUntranslatedStrFromIndex(const int index) +const QString unitGetUntranslatedStrFromIndex(const int unit) { - if (indexUNITMAX) + if (unitUNITMAX) return ""; QString suffix[] = { "pt", "mm", "in", "p", "cm", "c", "\xB0", "%" }; - return suffix[index]; + return suffix[unit]; } /*! - * @brief Returns the decimals for the units + * \brief Get decimals for unit. + * + * \param unit see #ScUnit for valid unit + * \return decimals */ -int unitGetDecimalsFromIndex(const int index) +int unitGetDecimalsFromIndex(const int unit) { - if (indexUNITMAX) + if (unitUNITMAX) return 0; // PT, MM, IN, P, CM, C, °, % int decimalPoints[] = {100, 1000, 10000, 100, 10000, 10000, 100, 100}; - return decimalPoints[index]; + return decimalPoints[unit]; } /*! - * @brief Returns the precision for the units + * \brief Get precision for unit. + * + * \param unit see #ScUnit for valid unit + * \return number of decimal digit */ -int unitGetPrecisionFromIndex(const int index) +int unitGetPrecisionFromIndex(const int unit) { - if (indexUNITMAX) + if (unitUNITMAX) return 0; // PT,MM,IN, P,CM, C, °, % int precision[] = {2, 3, 4, 2, 4, 4, 2, 2}; - return precision[index]; + return precision[unit]; } /*! - * @brief Returns a QStringList of the units for use in QComboBoxes etc + * \brief Get a list of length units (to use in GUI) + * + * See unitValidForDocUnit() for length units. + * \return an QStringList of length units */ const QStringList unitGetTextUnitList() { @@ -217,7 +253,9 @@ const QStringList unitGetTextUnitList() } /*! - * @brief Returns the maximum index of the units we have now + * Get the maximum index allowed for unit. + * + * See #ScUnit for valid unit. */ int unitGetMaxIndex() { @@ -225,7 +263,10 @@ int unitGetMaxIndex() } /*! - * @brief Returns the pts value from the mm value supplied + * \brief Converts %Millimeters to %Points. + * + * \param mm value in %Millimeters + * \return value in %Points */ double mm2pts(double mm) { @@ -233,7 +274,10 @@ double mm2pts(double mm) } /*! - * @brief Returns the pts value from the in value supplied + * \brief Converts %Inches to %Points. + * + * \param in value in %Inches + * \return value in %Points */ double in2pts(double in) { @@ -241,7 +285,10 @@ double in2pts(double in) } /*! - * @brief Returns the pts value from the pica value supplied + * \brief Converts %Picas to %Points + * + * \param p value in %Picas + * \return value in %Points */ double p2pts(double p) { @@ -249,7 +296,10 @@ double p2pts(double p) } /*! - * @brief Returns the pts value from the cm value supplied + * \brief Converts %Centimeters to %Points + * + * \param cm value in %Centimetes + * \return value in %Points */ double cm2pts(double cm) { @@ -257,7 +307,10 @@ double cm2pts(double cm) } /*! - * @brief Returns the pts value from the cm value supplied + * \brief Converts %Cicero to %Points + * + * \param c value in %Cicero + * \return value in %Points */ double c2pts(double c) { @@ -265,7 +318,10 @@ double c2pts(double c) } /*! - * @brief Returns the mm value from the pt value supplied + * \brief Converts %Points to %Millimeters + * + * \param pts value in %Points + * \return value in %Millimeters */ double pts2mm(double pts) { @@ -273,7 +329,10 @@ double pts2mm(double pts) } /*! - * @brief Returns the in value from the pt value supplied + * \brief Converts %Points to %Inches. + * + * \param pts value in %Points + * \return value in %Inches */ double pts2in(double pts) { @@ -281,7 +340,10 @@ double pts2in(double pts) } /*! - * @brief Returns the pica value from the pt value supplied + * \brief Converts %Points to %Picas. + * + * \param pts value in %Points + * \return value in %Picas */ double pts2p(double pts) { @@ -289,7 +351,10 @@ double pts2p(double pts) } /*! - * @brief Returns the cm value from the pt value supplied + * \brief Converts %Points to %Centimeters + * + * \param pts value in %Points + * \return value in %Centimeters */ double pts2cm(double pts) { @@ -297,7 +362,10 @@ double pts2cm(double pts) } /*! - * @brief Returns the c value from the pt value supplied + * \brief Converts %Points to %Cicero + * + * \param pts value in %Points + * \return value in %Cicero */ double pts2c(double pts) { @@ -305,103 +373,152 @@ double pts2c(double pts) } /*! - * @brief Returns the value from the pt value supplied based on unit index + * \brief Converts %Points to specified unit + * + * \param pts value in %Points + * \param unit see #ScUnit for valid unit + * \return value in specified unit */ -double pts2value(double unitValue, int unit) +double pts2value(double pts, int unit) { double ret = 0.0; switch (unit) { - case 0: - case 3: - case 6: - case 7: - ret = unitValue; //dont multiply by 1 + case SC_POINTS: + case SC_PICAS: + case SC_DEGREES: + case SC_PERCENT: + ret = pts; //dont multiply by 1 break; default: - ret = unitValue * unitGetRatioFromIndex(unit); + ret = pts * unitGetRatioFromIndex(unit); break; } return ret; } /*! - * @brief Returns the pt value from the value supplied based on unit index + * \brief Converts specified value in %Points + * + * \param value value in unit + * \param unit see #ScUnit for valid unit + * \return value in %Points */ -double value2pts(double unitValue, int unit) +double value2pts(double value, int unit) { double ret = 0.0; switch (unit) { - case 0: - case 3: - case 6: - case 7: - ret = unitValue; // dont divide by 1 + case SC_POINTS: + case SC_PICAS: + case SC_DEGREES: + case SC_PERCENT: + ret = value; // dont divide by 1 break; - default: - ret = unitValue / unitGetRatioFromIndex(unit); + default: // others + ret = value / unitGetRatioFromIndex(unit); break; } return ret; } /*! - * @brief Returns the secondary unit value from the value supplied based on primary unit + * \brief Converts unit to unit + * + * \param value value in fromUnit unit + * \param fromUnit value unit, see #ScUnit for valid unit + * \param toUnit return unit, see #ScUnit for valid unit + * \return value in toUnit unit */ -double value2value(double unitValue, int primaryUnit, int secondaryUnit) +double value2value(double value, int fromUnit, int toUnit) { - if (primaryUnit==secondaryUnit) - return unitValue; + if (fromUnit==toUnit) + return value; double pts = 0.0, ret = 0.0; //Can make this not convert to points at a later stage, for now, the function exists and works. - pts= primaryUnit==0 ? unitValue : unitValue / unitGetRatioFromIndex(primaryUnit); - ret= secondaryUnit==0 ? pts : pts * unitGetRatioFromIndex(secondaryUnit); + pts= fromUnit==0 ? value : value / unitGetRatioFromIndex(fromUnit); + ret= toUnit==0 ? pts : pts * unitGetRatioFromIndex(toUnit); return ret; } -QString value2String(double unitValue, int unitIndex, bool round2Precision, bool appendSuffix) +/*! + * \brief Get a string of value converted in unit. + * + * \param pts value in %Points + * \param unit see #ScUnit for valid unit + * \param round has I have to round the converted value to unit precision, see unitGetPrecisionFromIndex() ? + * \param suffix has I have to append suffix ? + */ +QString value2String(double pts, int unit, bool round, bool suffix) { +//ivro: Is toString not better as number see Qt documentation ? QString s; - if (round2Precision) - s=QString::number(pts2value(unitValue, unitIndex), 'f', unitGetPrecisionFromIndex(unitIndex)); + if (round) + s=QString::number(pts2value(pts, unit), 'f', unitGetPrecisionFromIndex(unit)); else - s=QString::number(pts2value(unitValue, unitIndex)); - if (appendSuffix) - s += unitGetStrFromIndex(unitIndex); + s=QString::number(pts2value(pts, unit)); + if (suffix) + s += unitGetStrFromIndex(unit); return s; } /*! - * @brief Sets up iteration value 1 for vruler, hruler and tabruler + * \brief Get iteration value 1 for vruler, hruler and tabruler. + * + * \param unit see #ScUnit for valid unit + * \return iteration value + * + * \todo Documents use cases */ -double unitRulerGetIter1FromIndex(const int index) +double unitRulerGetIter1FromIndex(const int unit) { - if (!unitValidForDocUnit(index)) + if (!unitValidForDocUnit(unit)) return 0; // PT, MM, IN, P, CM, C °, % double iter[] = {10.0, 720.0/25.4, 18.0, 12.0, 72.0/25.4, 72.0/25.4*4.512, 10.0, 10.0}; - return iter[index]; + return iter[unit]; } /*! - * @brief Sets up iteration value 2 for vruler, hruler and tabruler + * \brief Get iteration value 2 for vruler, hruler, tabruler + * + * \param unit see #ScUnit for valid unit + * \return iteration value + * + * \todo Documents use cases */ -double unitRulerGetIter2FromIndex(const int index) +double unitRulerGetIter2FromIndex(const int unit) { - if (!unitValidForDocUnit(index)) + if (!unitValidForDocUnit(unit)) return 0; // PT, MM, IN, P, CM, C, °, % double iter[] = {100.0, 7200.0/25.4, 72.0, 120.0, 720.0/25.4, 720.0/25.4*4.512, 100.0, 100.0}; - return iter[index]; + return iter[unit]; } -bool unitValidForDocUnit(const int index) +/*! + * \brief Is unit can be used as length unit ? + * + * Valid length unit are + * - %Points, + * - %Millimeters, + * - %Inches, + * - %Picas, + * - %Centimeters, + * - %Cicero. + * Invalid unit are + * - %Degress, + * - %Percent. + * + * \param unit see #ScUnit for valid unit + * \return true if length unit, false otherwise + */ +bool unitValidForDocUnit(const int unit) { - if (indexUNITMAX) + if (unitUNITMAX) return false; - if (index==6 || index==7) + if (unit==6 || unit==7) return false; return true; } diff --git a/Scribus/scribus/units.h b/Scribus/scribus/units.h index 9ed5f4b..1d15951 100644 --- a/Scribus/scribus/units.h +++ b/Scribus/scribus/units.h @@ -29,32 +29,36 @@ for which a new license (GPL+exception) is in place. #define UNITMIN 0 #define UNITMAX 7 +/*! + * \brief Enumeration of valid unit in Scribus. + */ enum scUnit { - SC_POINTS = 0, - SC_PT = 0, - SC_MILLIMETERS = 1, - SC_MM = 1, - SC_INCHES = 2, - SC_IN = 2, - SC_PICAS = 3, - SC_P = 3, - SC_CENTIMETERS = 4, - SC_CM = 4, - SC_CICERO = 5, - SC_C = 5, - SC_DEGREES = 6, - SC_DEG = 6, - SC_PERCENT = 7, - SC_PCT = 7 + SC_POINTS = 0, /*!< %Points */ + SC_MILLIMETERS = 1, /*!< %Millimeters */ + SC_INCHES = 2, /*!< %Inches */ + SC_PICAS = 3, /*!< %Picas */ + SC_CENTIMETERS = 4, /*!< %Centimeters */ + SC_CICERO = 5, /*!< %Cicero */ + SC_DEGREES = 6, /*!< %Degrees */ + SC_PERCENT = 7, /*!< %Pervent */ + + SC_PT = 0, /*!< %Points abbrev */ + SC_MM = 1, /*!< %Millimeters abbrev */ + SC_IN = 2, /*!< %Inches abbrev */ + SC_P = 3, /*!< %Picas abbrev */ + SC_CM = 4, /*!< %Centimeters abbrev */ + SC_C = 5, /*!< %Cicero abbrev */ + SC_DEG = 6, /*!< %Degrees abbrev */ + SC_PCT = 7 /*!< %Percent abbrev */ }; -double SCRIBUS_API unitGetRatioFromIndex(const int index); -int SCRIBUS_API unitGetBaseFromIndex(const int index); -const QString SCRIBUS_API unitGetStrFromIndex(const int index); -const QString SCRIBUS_API unitGetUntranslatedStrFromIndex(const int index); -const QString SCRIBUS_API unitGetSuffixFromIndex(const int index); -int SCRIBUS_API unitGetDecimalsFromIndex(const int index); -int SCRIBUS_API unitGetPrecisionFromIndex(const int index); +double SCRIBUS_API unitGetRatioFromIndex(const int unit); +int SCRIBUS_API unitGetBaseFromIndex(const int unit); +const QString SCRIBUS_API unitGetStrFromIndex(const int unit); +const QString SCRIBUS_API unitGetUntranslatedStrFromIndex(const int unit); +const QString SCRIBUS_API unitGetSuffixFromIndex(const int unit); +int SCRIBUS_API unitGetDecimalsFromIndex(const int unit); +int SCRIBUS_API unitGetPrecisionFromIndex(const int unit); double SCRIBUS_API unitValueFromString(const QString& value); scUnit SCRIBUS_API unitIndexFromString(const QString& value); const QStringList SCRIBUS_API unitGetTextUnitList(); @@ -69,14 +73,14 @@ double SCRIBUS_API pts2in(double pts); double SCRIBUS_API pts2p(double pts); double SCRIBUS_API pts2cm(double pts); double SCRIBUS_API pts2c(double pts); -double SCRIBUS_API pts2value(double Val, int unit); -double SCRIBUS_API value2pts(double unitValue, int unit); -double SCRIBUS_API value2value(double unitValue, int primaryUnit, int secondaryUnit); -QString SCRIBUS_API value2String(double unitValue, int unitIndex, bool round2Precision, bool appendSuffix); +double SCRIBUS_API pts2value(double value, int unit); +double SCRIBUS_API value2pts(double value, int unit); +double SCRIBUS_API value2value(double value, int fromUnit, int toUnit); +QString SCRIBUS_API value2String(double value, int unit, bool round, bool suffix); //Ruler specific functions -double SCRIBUS_API unitRulerGetIter1FromIndex(const int index); -double SCRIBUS_API unitRulerGetIter2FromIndex(const int index); -bool SCRIBUS_API unitValidForDocUnit(const int index); +double SCRIBUS_API unitRulerGetIter1FromIndex(const int unit); +double SCRIBUS_API unitRulerGetIter2FromIndex(const int unit); +bool SCRIBUS_API unitValidForDocUnit(const int unit); #endif // UNITS_H