Ticket #791: mythstroke.2.h

File mythstroke.2.h, 5.2 KB (added by mfgalizi@…, 14 years ago)

Support for held gestures

Line 
1/* -*- myth -*- */
2/**
3 * @file mythstroke.h
4 * @author Micah F. Galizia <mfgalizi@csd.uwo.ca>
5 * @brief A C++ ripoff of the stroke library for MythTV.
6 *
7 * Copyright (C) 2005 Micah Galizia
8 *
9 * This program is free software; you can redistribute it and/or
10 * modify it under the terms of the GNU General Public License as
11 * published by the Free Software Foundation; either version 2, or (at
12 * your option) any later version.
13 *
14 * This program is distributed in the hope that it will be useful, but
15 * WITHOUT ANY WARRANTY; without even the implied warranty of
16 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
17 * General Public License for more details.
18 *
19 * You should have received a copy of the GNU General Public License
20 * along with this program; if not, write to the Free Software
21 * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA
22 * 02111-1307, USA
23 */
24#ifndef MYTHSTROKE_H
25#define MYTHSTROKE_H
26
27#include <sys/types.h>
28
29#include <qpoint.h>
30#include <qvaluelist.h>
31#include <qevent.h>
32
33const int MythGestureEventType = 24427;
34
35
36
37/**
38 * @class MythGestureEvent
39 * @brief A custom event that represents a mouse gesture.
40 */
41class MythGestureEvent : public QCustomEvent
42{
43
44public:
45
46    /**
47     * @brief The types of gestures supported by myth
48     */
49    enum Gesture {
50
51        /* Horizontal and vertical lines */
52        Up,
53        Down,
54        Left,
55        Right,
56
57        /* Diagonal lines */
58        UpLeft,
59        UpRight,
60        DownLeft,
61        DownRight,
62
63        /* Two Lines */
64        UpThenLeft,
65        UpThenRight,
66        DownThenLeft,
67        DownThenRight,
68        LeftThenUp,
69        LeftThenDown,
70        RightThenUp,
71        RightThenDown,
72
73        /* A click */
74        Click,
75
76        /* This isn't real */
77        MaxGesture
78    };
79
80    /**
81     * @brief Create a myth gesture.
82     * @param type The gesture type, as per the Type enumeration.
83     * @sa Type
84     */
85    inline MythGestureEvent(size_t gesture):QCustomEvent(MythGestureEventType)
86    {
87        (gesture >= MaxGesture) ? _gesture = MaxGesture : _gesture = gesture;
88    }
89
90    /**
91     * @brief Get the gesture type.
92     * @return The gesture value corresponding to the Gesture
93     * enumeration.
94     */
95    inline int gesture(void) const { return this->_gesture; }
96
97    /**
98     * @brief Get the symbolic name of the gesture.
99     * @return A string containing the symbolic name of the gesture.
100     */
101    operator QString() const;
102
103 private:
104
105    size_t _gesture;
106};
107
108
109
110/* forward declaration of private information */
111class MythStrokePrivate;
112
113
114
115/**
116 * @class MythStroke
117 * @brief Contains the points in a stroke, and translates them into
118 * gestures.
119 *
120 * Becase the indended use of the stop method is to be called by
121 * either the expiration of a timer or when an event is called (or
122 * both at the same time) it must have a mutex.
123 */
124class MythStroke
125{
126public:
127
128    /**
129     * @brief Create a new stroke, specifying tuning values
130     * @param max_points The maximum number of points to record.
131     * @param min_points The minimum number of points to record.
132     * @param max_sequence The maximum producible sequence size.
133     * @param scale_ratio The stroke scale ratio
134     * @param bin_percent The bin count percentage required
135     * to add to the sequence.
136     * @param timeout The milliseconds that pass before a timout will
137     * occur.
138     */
139    MythStroke(size_t max_points = 10000, size_t min_points = 50,
140               size_t max_sequence = 20, size_t scale_ratio = 4,
141               float bin_percent = 0.07);
142
143    /**
144     * @brief Start recording.
145     */
146    void start(void);
147
148    /**
149     * @brief Stop recording.
150     *
151     * This method stores the gesture, as it is, and resets all
152     * information.
153     */
154    void stop(void);
155
156    /**
157     * @brief Determine if the stroke is being recorded.
158     * @return True if recording is in progress, otherwise, false.
159     */
160    bool recording(void) const;
161
162    /**
163     * @brief Complete the gesture event of the last completed stroke.
164     * @return A new gesture event, or NULL on error.
165     */
166    MythGestureEvent *gesture(void) const;
167
168    /**
169     * @brief Record a point.
170     * @param p The point to record.
171     * @return True if the point was recorded, otherwise, false.
172     */
173    bool record(const QPoint &p);
174
175    /**
176     * @brief Determine if the stroke has the minimum required points.
177     * @return true if the gesture can be translated, otherwise, false.
178     */
179    bool hasMinimumPoints(void) const { return points.size() >= min_points; }
180
181protected:
182
183    /**
184     * @brief Translate the stroke into a sequence.
185     * @return The sequence string made by the mouse.
186     *
187     * @note The points will be removed during this method.
188     */
189    QString translate(void);
190
191    /**
192     * @brief Adjust horizontal and vertical extremes.
193     * @param x The new horizontal extreme.
194     * @param y The new vertical extreme
195     */
196    void adjustExtremes(int x, int y);
197
198private:
199
200    bool m_recording;
201    int min_x;
202    int max_x;
203    int min_y;
204    int max_y;
205    size_t max_points;
206    size_t min_points;
207    size_t max_sequence;
208    int scale_ratio;
209    float bin_percent;
210    size_t last_gesture;   
211    QValueList <QPoint> points;
212
213    MythStrokePrivate *p;
214};
215
216#endif /* MYTHSTROKE_H */