ktouch/src/ktouchslideline.h

   1 /***************************************************************************
   2  *   ktouchslideline.h                                                     *
   3  *   -----------------                                                     *
   4  *   Copyright (C) 2000 by H�ard Friland, 2003 by Andreas Nicolai        *
   5  *   haavard@users.sourceforge.net                                         *
   6  *                                                                         *
   7  *   This program is free software; you can redistribute it and/or modify  *
   8  *   it under the terms of the GNU General Public License as published by  *
   9  *   the Free Software Foundation; either version 2 of the License, or     *
  10  *   (at your option) any later version.                                   *
  11  ***************************************************************************/
  12
  13 #ifndef KTOUCHSLIDELINE_H
  14 #define KTOUCHSLIDELINE_H
  15
  16 #include <qwidget.h>
  17 #include <qtimer.h>
  18 class QPixmap;
  19 class QPainter;
  20
  21 /// This widget just displays the sliding text.
  22 ///
  23 /// KTouchSlideLine is a fire-and-forget widget, so you don't have to care about any
  24 /// drawing details. After the initial setup (setting the font, colours etc.) you simple
  25 /// need to call setTeacherText() or setStudentText() and everything else (including the
  26 /// choice of the background colour) is done by the widget.<p>
  27 /// So, how does the sliding work. The basic idea is that when the teachers and the
  28 /// students text won't fit in the widgets width only part of the text is shown. Depending
  29 /// on the amount of text that has been already typed, both lines
  30 /// (the teachers and the students line) will move. However, if the student
  31 /// had entered a wrong text than the lines shouldn't move before he did not
  32 /// correct his mistake. This ensures that you will always start at the left side
  33 /// of the screen and end up at the right side.<p>
  34 /// The calculation is very simple. Both the teachers and the students line are drawn
  35 /// in pixmaps. Then you only need to calculate the parts of that pixmaps that have to be
  36 /// copied on the screen and you're done! ??? Well, not quite so simple....<P>
  37 /// The calculation is actually the tricky bit but here's the principle (
  38 /// If you really want to understand the code, better draw a sketch - I needed several
  39 /// sketches :-).<br>
  40 /// After drawing the text into the pixmaps (easy) we calculate the ratio between
  41 /// "typed text" and "total text per line" and multiply it with the horizontal space available.
  42 /// This has to be done three times: For the global widget coordinates, for the teacher line
  43 /// and for the student line. Then we simply convert from local to global coordinates and
  44 /// store the new coordinates.
  45 /// The timed function slide() will then slide the widgets into position.<p>
  46 /// The calculation and the drawing are made in the updateLines() member function. Since
  47 /// the teachers pixmap won't change when the students string changes it will only be renewed
  48 /// when it's size changes (or the teacher text changes). This is done in the resizeEvent().<br>
  49 /// The properties for the slide line: correctColor, errorColor, font can be manipulated
  50 /// using the usual access functions.
  51 class KTouchSlideLine : public QWidget {
  52     Q_OBJECT
  53   private:
  54     bool m_rightJustify; // do we right align the widget-for langauges like hebrew which is written from right to left.
  55   public:
  56     /// Constructor
  57     KTouchSlideLine(QWidget *parent);
  58     /// Destructor, free memory allocated for the line pixmap.
  59     ~KTouchSlideLine();
  60     /// Applies the preferences (font and colours).
  61     void applyPreferences();
  62     /// Sets the teacher and student text (usually called when a new line is started).
  63     void setNewText(const QString& teacherText, const QString& studentText);
  64     /// Sets the student text (called whenever the student string changes).
  65     void setStudentText(const QString& text);
  66         /// Change the font of the slide line widget.
  67         void setFont(const QFont& font);
  68
  69   public slots:
  70     /// Starts or stops the cursor blinking timer.
  71     void setCursorTimerEnabled(bool on);
  72
  73   private slots:
  74     /// Turns the cursor on or off and triggers an update (this function triggered by the cursor timer).
  75     void toggleCursor();
  76     /// Slides the lines into position (this function is triggered by the sliding timer).
  77     void slide();
  78
  79   protected:
  80     /// Simply updates the widget: calls updateLines() and slide()
  81     void paintEvent( QPaintEvent * );
  82     /// Will be called when the widget is resized.
  83     /// This event will first recalculate the font size. Then the teachers and the students widget
  84     /// will be created and the teachers text will be drawn on the teachers pixmap. Finally update()
  85     /// is called.
  86     void resizeEvent ( QResizeEvent * );
  87
  88   private:
  89     /// Will recalculate the font size depending on the height of the widget.
  90     void resizeFont();
  91     /// Just draws the cursor (if visible)
  92     void drawCursor();
  93     /// Draws the "enter" character at the given position (y is the y-position of the arrow).
  94     void drawEnterChar(QPainter *painter, int cursorPos, int y, int enterWidth);
  95     /// Calculates the correct text length taking trailing spaces into account
  96     int  textWidth(const QFontMetrics& fontMetrics, const QString& text);
  97     /// Redraws the student pixmaps and updates the frame x positions
  98     void updateLines();
  99
 100     QFont       m_font;             ///< The font for the sliding lines.
 101     QString     m_teacherText;      ///< The teachers text.
 102     QString     m_studentText;      ///< The students text.
 103     QPixmap    *m_teacherPixmap;    ///< Pixmap used to draw the teacher sliding line.
 104     QPixmap    *m_studentPixmap;    ///< Pixmap used to draw the student sliding line.
 105
 106     QTimer      m_slideTimer;       ///< This is the timer for the sliding of the lines.
 107     int         m_shift;            ///< The horizontal shift of the slide lines (used for centering)
 108     int         m_enterCharWidth;   ///< The width of the enter character (including the small gap).
 109     int         m_spaceCharWidth;   ///< The width of a space char - this is different to QFontMetrics::width(' ').
 110     int         m_frameWidth;       ///< The width of the frame that is copied from the pixmaps onto the widget.
 111     int         m_teacherTextWidth; ///< The length of the teacher line (in pixel) WITHOUT enter character.
 112     double      m_teacherFrameX;    ///< The current X-position in the teachers pixmap (local coordinates).
 113     int         m_teacherFrameXEnd; ///< The final X-position in the teachers pixmap (local coordinates).
 114     double      m_studentFrameX;    ///< The current X-position in the students pixmap (local coordinates).
 115     int         m_studentFrameXEnd; ///< The final X-position in the student pixmap (local coordinates).
 116
 117     bool        m_cursorVisible;    ///< Flag which indicates the current state of the cursor.
 118     QTimer      m_cursorTimer;      ///< This is the cursor on/off timer.
 119     int         m_cursorXPos;       ///< The global X-coordinate of the cursor.
 120     int         m_cursorYPos;       ///< The global Y-coordinate of the cursor (student line).
 121     int         m_cursorHeight;     ///< The height of the cursor.
 122     QColor      m_cursorColor;      ///< Defines the colour of the cursor (when turned on).
 123     QColor      m_cursorBackground; ///< Defines the background colour of the cursor (when turned off).
 124 };
 125
 126 #endif  // KTOUCHSLIDELINE_H