document docstring abuse for symbol font code points

git-svn-id: svn://svn.lyx.org/lyx/lyx-devel/trunk@15791 a592a061-630c-0410-9148-cb99ea01b6c8

diff --git a/src/frontends/FontMetrics.h b/src/frontends/FontMetrics.h
index 0d62aed126ef45702c889fce0d6b8e4864927e31..829b5cec1f156230b89210de0c067835e6779782 100644 (file)
--- a/src/frontends/FontMetrics.h
+++ b/src/frontends/FontMetrics.h
@@ -38,6 +38,11 @@
  *               <-  width ->
  * --------------+----------+-------<maxDescent
  *
+ * Caution: All char_type and docstring arguments of any method of this class
+ * are no UCS4 chars or strings if the font is a symbol font. They simply
+ * denote the code points of the font instead. You have to keep this in mind
+ * when you implement the methods in a frontend. You must not pass these
+ * parameters to a unicode conversion function in particular.
  */
 
 namespace lyx {

diff --git a/src/frontends/Painter.h b/src/frontends/Painter.h
index ceb6724ce96abf5169f5972e0e254e8ab460538d..309dae3f15c269afc4d8510468ba32f11d736ff3 100644 (file)
--- a/src/frontends/Painter.h
+++ b/src/frontends/Painter.h
@@ -43,6 +43,13 @@ namespace frontend {
  * management.
  *
  * Note that the methods return *this for convenience.
+ *
+ * Caution: All char_type and docstring arguments of the text drawing
+ * methods of this class are no UCS4 chars or strings if the font is a
+ * symbol font. They simply denote the code points of the font instead.
+ * You have to keep this in mind when you implement the methods in a
+ * frontend. You must not pass these parameters to a unicode conversion
+ * function in particular.
  */
 class Painter {
 public:

diff --git a/src/frontends/qt4/GuiFontMetrics.C b/src/frontends/qt4/GuiFontMetrics.C
index a313c253cab7453371d0e6c0f79aa3bffe44319a..0a1138bfb563de3402f7c3b856868a610cbd67b3 100644 (file)
--- a/src/frontends/qt4/GuiFontMetrics.C
+++ b/src/frontends/qt4/GuiFontMetrics.C
@@ -105,6 +105,10 @@ int GuiFontMetrics::smallcapsWidth(QString const & s) const
 
 int GuiFontMetrics::width(char_type const * s, size_t ls) const
 {
+       // Caution: The following ucs4_to_something conversions work for
+       // symbol fonts only because they are no real conversions but simple
+       // casts in reality.
+
        if (ls == 1 && !smallcaps_shape_) {
                QChar const c = ucs4_to_qchar(s[0]);
                return width(c.unicode());

diff --git a/src/frontends/qt4/QLPainter.C b/src/frontends/qt4/QLPainter.C
index 4ac6a84c7065e6a88ed0c4bf6c939966665b86e9..df9b279a48a395a8559b69263a74e2933fa1378a 100644 (file)
--- a/src/frontends/qt4/QLPainter.C
+++ b/src/frontends/qt4/QLPainter.C
@@ -211,6 +211,10 @@ int QLPainter::smallCapsText(int x, int y,
 int QLPainter::text(int x, int y, char_type const * s, size_t ls,
        LyXFont const & f)
 {
+       // Caution: The following ucs4_to_qstring conversion works for
+       // symbol fonts only because it is no real conversion but a simple
+       // cast in reality.
+
        QString str;
        ucs4_to_qstring(s, ls, str);
 

diff --git a/src/mathed/MathParser.h b/src/mathed/MathParser.h
index 1e4b7b7392a3d5f39173f6f45b6a6de0a2aafec1..a64b85d66e3f9f74046e739f70ac2b3220fd8a1e 100644 (file)
--- a/src/mathed/MathParser.h
+++ b/src/mathed/MathParser.h
@@ -35,11 +35,23 @@ public:
        docstring name;
        /// name of a inset that handles that macro
        docstring inset;
-       /// position of the thing in a font     
+       /**
+        * The string or symbol to draw.
+        * This is a string of length 1 if \p name is a known symbol, and
+        * the corresponding font is available. In this case it is
+        * NO UCS4 STRING! The only "character" of the string simply denotes
+        * the code point of the symbol in the font. Therefore you have to
+        * be very careful if you pass \c draw to any function that takes a
+        * docstring argument.
+        * If \p name is a known symbol, but the corresponding font is not
+        * available, or if it is a function name, then \c draw contains a
+        * regular UCS4 string (actuallay \c draw == \c name) that is painted
+        * on screen.
+        */
        docstring draw;
        /// operator/..., fontname e
        docstring extra;
-       /// how is this called as XML entity?
+       /// how is this called as XML entity in MathML?
        docstring xmlname;
        /// required LaTeXFeatures
        docstring requires;