1 /****************************************************************************
2 **
3 ** Copyright (C) 2015 The Qt Company Ltd.
4 ** Contact: http://www.qt.io/licensing/
5 **
6 ** This file is part of the QtGui module of the Qt Toolkit.
7 **
8 ** $QT_BEGIN_LICENSE:LGPL$
9 ** Commercial License Usage
10 ** Licensees holding valid commercial Qt licenses may use this file in
11 ** accordance with the commercial license agreement provided with the
12 ** Software or, alternatively, in accordance with the terms contained in
13 ** a written agreement between you and The Qt Company. For licensing terms
14 ** and conditions see http://www.qt.io/terms-conditions. For further
15 ** information use the contact form at http://www.qt.io/contact-us.
16 **
17 ** GNU Lesser General Public License Usage
18 ** Alternatively, this file may be used under the terms of the GNU Lesser
19 ** General Public License version 2.1 or version 3 as published by the Free
20 ** Software Foundation and appearing in the file LICENSE.LGPLv21 and
21 ** LICENSE.LGPLv3 included in the packaging of this file. Please review the
22 ** following information to ensure the GNU Lesser General Public License
23 ** requirements will be met: https://www.gnu.org/licenses/lgpl.html and
24 ** http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
25 **
26 ** As a special exception, The Qt Company gives you certain additional
27 ** rights. These rights are described in The Qt Company LGPL Exception
28 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
29 **
30 ** GNU General Public License Usage
31 ** Alternatively, this file may be used under the terms of the GNU
32 ** General Public License version 3.0 as published by the Free Software
33 ** Foundation and appearing in the file LICENSE.GPL included in the
34 ** packaging of this file. Please review the following information to
35 ** ensure the GNU General Public License version 3.0 requirements will be
36 ** met: http://www.gnu.org/copyleft/gpl.html.
37 **
38 ** $QT_END_LICENSE$
39 **
40 ****************************************************************************/
41
42 #include "qevent.h"
43 #include "qcursor.h"
44 #include "qapplication.h"
45 #include "private/qapplication_p.h"
46 #include "private/qevent_p.h"
47 #include "private/qkeysequence_p.h"
48 #include "qwidget.h"
49 #include "qgraphicsview.h"
50 #include "qdebug.h"
51 #include "qmime.h"
52 #include "qdnd_p.h"
53 #include "qevent_p.h"
54 #include "qgesture.h"
55 #include "qgesture_p.h"
56
57 #ifdef Q_OS_SYMBIAN
58 #include "private/qcore_symbian_p.h"
59 #endif
60
61 QT_BEGIN_NAMESPACE
62
63 /*!
64 \class QInputEvent
65 \ingroup events
66
67 \brief The QInputEvent class is the base class for events that
68 describe user input.
69 */
70
71 /*!
72 \internal
73 */
QInputEvent(Type type,Qt::KeyboardModifiers modifiers)74 QInputEvent::QInputEvent(Type type, Qt::KeyboardModifiers modifiers)
75 : QEvent(type), modState(modifiers)
76 {}
77
78 /*!
79 \internal
80 */
~QInputEvent()81 QInputEvent::~QInputEvent()
82 {
83 }
84
85 /*!
86 \fn Qt::KeyboardModifiers QInputEvent::modifiers() const
87
88 Returns the keyboard modifier flags that existed immediately
89 before the event occurred.
90
91 \sa QApplication::keyboardModifiers()
92 */
93
94 /*! \fn void QInputEvent::setModifiers(Qt::KeyboardModifiers modifiers)
95
96 \internal
97
98 Sets the keyboard modifiers flags for this event.
99 */
100
101 /*!
102 \class QMouseEvent
103 \ingroup events
104
105 \brief The QMouseEvent class contains parameters that describe a mouse event.
106
107 Mouse events occur when a mouse button is pressed or released
108 inside a widget, or when the mouse cursor is moved.
109
110 Mouse move events will occur only when a mouse button is pressed
111 down, unless mouse tracking has been enabled with
112 QWidget::setMouseTracking().
113
114 Qt automatically grabs the mouse when a mouse button is pressed
115 inside a widget; the widget will continue to receive mouse events
116 until the last mouse button is released.
117
118 A mouse event contains a special accept flag that indicates
119 whether the receiver wants the event. You should call ignore() if
120 the mouse event is not handled by your widget. A mouse event is
121 propagated up the parent widget chain until a widget accepts it
122 with accept(), or an event filter consumes it.
123
124 \note If a mouse event is propagated to a \l{QWidget}{widget} for
125 which Qt::WA_NoMousePropagation has been set, that mouse event
126 will not be propagated further up the parent widget chain.
127
128 The state of the keyboard modifier keys can be found by calling the
129 \l{QInputEvent::modifiers()}{modifiers()} function, inherited from
130 QInputEvent.
131
132 The functions pos(), x(), and y() give the cursor position
133 relative to the widget that receives the mouse event. If you
134 move the widget as a result of the mouse event, use the global
135 position returned by globalPos() to avoid a shaking motion.
136
137 The QWidget::setEnabled() function can be used to enable or
138 disable mouse and keyboard events for a widget.
139
140 Reimplement the QWidget event handlers, QWidget::mousePressEvent(),
141 QWidget::mouseReleaseEvent(), QWidget::mouseDoubleClickEvent(),
142 and QWidget::mouseMoveEvent() to receive mouse events in your own
143 widgets.
144
145 \sa QWidget::setMouseTracking() QWidget::grabMouse() QCursor::pos()
146 */
147
148 /*!
149 Constructs a mouse event object.
150
151 The \a type parameter must be one of QEvent::MouseButtonPress,
152 QEvent::MouseButtonRelease, QEvent::MouseButtonDblClick,
153 or QEvent::MouseMove.
154
155 The \a position is the mouse cursor's position relative to the
156 receiving widget.
157 The \a button that caused the event is given as a value from
158 the Qt::MouseButton enum. If the event \a type is
159 \l MouseMove, the appropriate button for this event is Qt::NoButton.
160 The mouse and keyboard states at the time of the event are specified by
161 \a buttons and \a modifiers.
162
163 The globalPos() is initialized to QCursor::pos(), which may not
164 be appropriate. Use the other constructor to specify the global
165 position explicitly.
166 */
167
QMouseEvent(Type type,const QPoint & position,Qt::MouseButton button,Qt::MouseButtons buttons,Qt::KeyboardModifiers modifiers)168 QMouseEvent::QMouseEvent(Type type, const QPoint &position, Qt::MouseButton button,
169 Qt::MouseButtons buttons, Qt::KeyboardModifiers modifiers)
170 : QInputEvent(type, modifiers), p(position), b(button), mouseState(buttons)
171 {
172 g = QCursor::pos();
173 }
174
175 /*!
176 \internal
177 */
~QMouseEvent()178 QMouseEvent::~QMouseEvent()
179 {
180 }
181
182 #ifdef QT3_SUPPORT
183 /*!
184 Use QMouseEvent(\a type, \a pos, \a button, \c buttons, \c
185 modifiers) instead, where \c buttons is \a state &
186 Qt::MouseButtonMask and \c modifiers is \a state &
187 Qt::KeyButtonMask.
188 */
QMouseEvent(Type type,const QPoint & pos,Qt::ButtonState button,int state)189 QMouseEvent::QMouseEvent(Type type, const QPoint &pos, Qt::ButtonState button, int state)
190 : QInputEvent(type), p(pos), b((Qt::MouseButton)button)
191 {
192 g = QCursor::pos();
193 mouseState = Qt::MouseButtons((state ^ b) & Qt::MouseButtonMask);
194 modState = Qt::KeyboardModifiers(state & (int)Qt::KeyButtonMask);
195 }
196
197 /*!
198 Use QMouseEvent(\a type, \a pos, \a globalPos, \a button,
199 \c buttons, \c modifiers) instead, where
200 \c buttons is \a state & Qt::MouseButtonMask and
201 \c modifiers is \a state & Qt::KeyButtonMask.
202 */
QMouseEvent(Type type,const QPoint & pos,const QPoint & globalPos,Qt::ButtonState button,int state)203 QMouseEvent::QMouseEvent(Type type, const QPoint &pos, const QPoint &globalPos,
204 Qt::ButtonState button, int state)
205 : QInputEvent(type), p(pos), g(globalPos), b((Qt::MouseButton)button)
206 {
207 mouseState = Qt::MouseButtons((state ^ b) & Qt::MouseButtonMask);
208 modState = Qt::KeyboardModifiers(state & (int)Qt::KeyButtonMask);
209 }
210 #endif
211
212
213 /*!
214 Constructs a mouse event object.
215
216 The \a type parameter must be QEvent::MouseButtonPress,
217 QEvent::MouseButtonRelease, QEvent::MouseButtonDblClick,
218 or QEvent::MouseMove.
219
220 The \a pos is the mouse cursor's position relative to the
221 receiving widget. The cursor's position in global coordinates is
222 specified by \a globalPos. The \a button that caused the event is
223 given as a value from the \l Qt::MouseButton enum. If the event \a
224 type is \l MouseMove, the appropriate button for this event is
225 Qt::NoButton. \a buttons is the state of all buttons at the
226 time of the event, \a modifiers the state of all keyboard
227 modifiers.
228
229 */
QMouseEvent(Type type,const QPoint & pos,const QPoint & globalPos,Qt::MouseButton button,Qt::MouseButtons buttons,Qt::KeyboardModifiers modifiers)230 QMouseEvent::QMouseEvent(Type type, const QPoint &pos, const QPoint &globalPos,
231 Qt::MouseButton button, Qt::MouseButtons buttons,
232 Qt::KeyboardModifiers modifiers)
233 : QInputEvent(type, modifiers), p(pos), g(globalPos), b(button), mouseState(buttons)
234 {}
235
236 /*!
237 \internal
238 */
createExtendedMouseEvent(Type type,const QPointF & pos,const QPoint & globalPos,Qt::MouseButton button,Qt::MouseButtons buttons,Qt::KeyboardModifiers modifiers)239 QMouseEvent *QMouseEvent::createExtendedMouseEvent(Type type, const QPointF &pos,
240 const QPoint &globalPos, Qt::MouseButton button,
241 Qt::MouseButtons buttons, Qt::KeyboardModifiers modifiers)
242 {
243 return new QMouseEventEx(type, pos, globalPos, button, buttons, modifiers);
244 }
245
246 /*!
247 \fn bool QMouseEvent::hasExtendedInfo() const
248 \internal
249 */
250
251 /*!
252 \since 4.4
253
254 Returns the position of the mouse cursor as a QPointF, relative to the
255 widget that received the event.
256
257 If you move the widget as a result of the mouse event, use the
258 global position returned by globalPos() to avoid a shaking
259 motion.
260
261 \sa x() y() pos() globalPos()
262 */
posF() const263 QPointF QMouseEvent::posF() const
264 {
265 return hasExtendedInfo() ? reinterpret_cast<const QMouseEventEx *>(this)->posF : QPointF(pos());
266 }
267
268 /*!
269 \internal
270 */
QMouseEventEx(Type type,const QPointF & pos,const QPoint & globalPos,Qt::MouseButton button,Qt::MouseButtons buttons,Qt::KeyboardModifiers modifiers)271 QMouseEventEx::QMouseEventEx(Type type, const QPointF &pos, const QPoint &globalPos,
272 Qt::MouseButton button, Qt::MouseButtons buttons,
273 Qt::KeyboardModifiers modifiers)
274 : QMouseEvent(type, pos.toPoint(), globalPos, button, buttons, modifiers), posF(pos)
275 {
276 d = reinterpret_cast<QEventPrivate *>(this);
277 }
278
279 /*!
280 \internal
281 */
~QMouseEventEx()282 QMouseEventEx::~QMouseEventEx()
283 {
284 }
285
286 /*!
287 \fn const QPoint &QMouseEvent::pos() const
288
289 Returns the position of the mouse cursor, relative to the widget
290 that received the event.
291
292 If you move the widget as a result of the mouse event, use the
293 global position returned by globalPos() to avoid a shaking
294 motion.
295
296 \sa x() y() globalPos()
297 */
298
299 /*!
300 \fn const QPoint &QMouseEvent::globalPos() const
301
302 Returns the global position of the mouse cursor \e{at the time
303 of the event}. This is important on asynchronous window systems
304 like X11. Whenever you move your widgets around in response to
305 mouse events, globalPos() may differ a lot from the current
306 pointer position QCursor::pos(), and from
307 QWidget::mapToGlobal(pos()).
308
309 \sa globalX() globalY()
310 */
311
312 /*!
313 \fn int QMouseEvent::x() const
314
315 Returns the x position of the mouse cursor, relative to the
316 widget that received the event.
317
318 \sa y() pos()
319 */
320
321 /*!
322 \fn int QMouseEvent::y() const
323
324 Returns the y position of the mouse cursor, relative to the
325 widget that received the event.
326
327 \sa x() pos()
328 */
329
330 /*!
331 \fn int QMouseEvent::globalX() const
332
333 Returns the global x position of the mouse cursor at the time of
334 the event.
335
336 \sa globalY() globalPos()
337 */
338
339 /*!
340 \fn int QMouseEvent::globalY() const
341
342 Returns the global y position of the mouse cursor at the time of
343 the event.
344
345 \sa globalX() globalPos()
346 */
347
348 /*!
349 \fn Qt::MouseButton QMouseEvent::button() const
350
351 Returns the button that caused the event.
352
353 Note that the returned value is always Qt::NoButton for mouse
354 move events.
355
356 \sa buttons() Qt::MouseButton
357 */
358
359 /*!
360 \fn Qt::MouseButton QMouseEvent::buttons() const
361
362 Returns the button state when the event was generated. The button
363 state is a combination of Qt::LeftButton, Qt::RightButton,
364 Qt::MidButton using the OR operator. For mouse move events,
365 this is all buttons that are pressed down. For mouse press and
366 double click events this includes the button that caused the
367 event. For mouse release events this excludes the button that
368 caused the event.
369
370 \sa button() Qt::MouseButton
371 */
372
373
374 /*!
375 \fn Qt::ButtonState QMouseEvent::state() const
376
377 Returns the button state immediately before the event was
378 generated. The button state is a combination of mouse buttons
379 (see Qt::ButtonState) and keyboard modifiers (Qt::MouseButtons).
380
381 Use buttons() and/or modifiers() instead. Be aware that buttons()
382 return the state immediately \e after the event was generated.
383 */
384
385 /*!
386 \fn Qt::ButtonState QMouseEvent::stateAfter() const
387
388 Returns the button state immediately after the event was
389 generated. The button state is a combination of mouse buttons
390 (see Qt::ButtonState) and keyboard modifiers (Qt::MouseButtons).
391
392 Use buttons() and/or modifiers() instead.
393 */
394
395 /*!
396 \class QHoverEvent
397 \ingroup events
398
399 \brief The QHoverEvent class contains parameters that describe a mouse event.
400
401 Mouse events occur when a mouse cursor is moved into, out of, or within a
402 widget, and if the widget has the Qt::WA_Hover attribute.
403
404 The function pos() gives the current cursor position, while oldPos() gives
405 the old mouse position.
406
407 There are a few similarities between the events QEvent::HoverEnter
408 and QEvent::HoverLeave, and the events QEvent::Enter and QEvent::Leave.
409 However, they are slightly different because we do an update() in the event
410 handler of HoverEnter and HoverLeave.
411
412 QEvent::HoverMove is also slightly different from QEvent::MouseMove. Let us
413 consider a top-level window A containing a child B which in turn contains a
414 child C (all with mouse tracking enabled):
415
416 \image hoverevents.png
417
418 Now, if you move the cursor from the top to the bottom in the middle of A,
419 you will get the following QEvent::MouseMove events:
420
421 \list 1
422 \o A::MouseMove
423 \o B::MouseMove
424 \o C::MouseMove
425 \endlist
426
427 You will get the same events for QEvent::HoverMove, except that the event
428 always propagates to the top-level regardless whether the event is accepted
429 or not. It will only stop propagating with the Qt::WA_NoMousePropagation
430 attribute.
431
432 In this case the events will occur in the following way:
433
434 \list 1
435 \o A::HoverMove
436 \o A::HoverMove, B::HoverMove
437 \o A::HoverMove, B::HoverMove, C::HoverMove
438 \endlist
439
440 */
441
442 /*!
443 \fn const QPoint &QHoverEvent::pos() const
444
445 Returns the position of the mouse cursor, relative to the widget
446 that received the event.
447
448 On QEvent::HoverLeave events, this position will always be
449 QPoint(-1, -1).
450
451 \sa oldPos()
452 */
453
454 /*!
455 \fn const QPoint &QHoverEvent::oldPos() const
456
457 Returns the previous position of the mouse cursor, relative to the widget
458 that received the event. If there is no previous position, oldPos() will
459 return the same position as pos().
460
461 On QEvent::HoverEnter events, this position will always be
462 QPoint(-1, -1).
463
464 \sa pos()
465 */
466
467 /*!
468 Constructs a hover event object.
469
470 The \a type parameter must be QEvent::HoverEnter,
471 QEvent::HoverLeave, or QEvent::HoverMove.
472
473 The \a pos is the current mouse cursor's position relative to the
474 receiving widget, while \a oldPos is the previous mouse cursor's
475 position relative to the receiving widget.
476 */
QHoverEvent(Type type,const QPoint & pos,const QPoint & oldPos)477 QHoverEvent::QHoverEvent(Type type, const QPoint &pos, const QPoint &oldPos)
478 : QEvent(type), p(pos), op(oldPos)
479 {
480 }
481
482 /*!
483 \internal
484 */
~QHoverEvent()485 QHoverEvent::~QHoverEvent()
486 {
487 }
488
489
490 /*!
491 \class QWheelEvent
492 \brief The QWheelEvent class contains parameters that describe a wheel event.
493
494 \ingroup events
495
496 Wheel events are sent to the widget under the mouse cursor, but
497 if that widget does not handle the event they are sent to the
498 focus widget. The rotation distance is provided by delta().
499 The functions pos() and globalPos() return the mouse cursor's
500 location at the time of the event.
501
502 A wheel event contains a special accept flag that indicates
503 whether the receiver wants the event. You should call ignore() if
504 you do not handle the wheel event; this ensures that it will be
505 sent to the parent widget.
506
507 The QWidget::setEnabled() function can be used to enable or
508 disable mouse and keyboard events for a widget.
509
510 The event handler QWidget::wheelEvent() receives wheel events.
511
512 \sa QMouseEvent QWidget::grabMouse()
513 */
514
515 /*!
516 \fn Qt::MouseButtons QWheelEvent::buttons() const
517
518 Returns the mouse state when the event occurred.
519 */
520
521 /*!
522 \fn Qt::Orientation QWheelEvent::orientation() const
523
524 Returns the wheel's orientation.
525 */
526
527 /*!
528 Constructs a wheel event object.
529
530 The position, \a pos, is the location of the mouse cursor within
531 the widget. The globalPos() is initialized to QCursor::pos()
532 which is usually, but not always, correct.
533 Use the other constructor if you need to specify the global
534 position explicitly.
535
536 The \a buttons describe the state of the mouse buttons at the time
537 of the event, \a delta contains the rotation distance,
538 \a modifiers holds the keyboard modifier flags at the time of the
539 event, and \a orient holds the wheel's orientation.
540
541 \sa pos() delta() state()
542 */
543 #ifndef QT_NO_WHEELEVENT
QWheelEvent(const QPoint & pos,int delta,Qt::MouseButtons buttons,Qt::KeyboardModifiers modifiers,Qt::Orientation orient)544 QWheelEvent::QWheelEvent(const QPoint &pos, int delta,
545 Qt::MouseButtons buttons, Qt::KeyboardModifiers modifiers,
546 Qt::Orientation orient)
547 : QInputEvent(Wheel, modifiers), p(pos), d(delta), mouseState(buttons), o(orient)
548 {
549 g = QCursor::pos();
550 }
551
552 /*!
553 \internal
554 */
~QWheelEvent()555 QWheelEvent::~QWheelEvent()
556 {
557 }
558
559 #ifdef QT3_SUPPORT
560 /*!
561 Use one of the other constructors instead.
562 */
QWheelEvent(const QPoint & pos,int delta,int state,Qt::Orientation orient)563 QWheelEvent::QWheelEvent(const QPoint &pos, int delta, int state, Qt::Orientation orient)
564 : QInputEvent(Wheel), p(pos), d(delta), o(orient)
565 {
566 g = QCursor::pos();
567 mouseState = Qt::MouseButtons(state & Qt::MouseButtonMask);
568 modState = Qt::KeyboardModifiers(state & (int)Qt::KeyButtonMask);
569 }
570 #endif
571
572 /*!
573 Constructs a wheel event object.
574
575 The \a pos provides the location of the mouse cursor
576 within the widget. The position in global coordinates is specified
577 by \a globalPos. \a delta contains the rotation distance, \a modifiers
578 holds the keyboard modifier flags at the time of the event, and
579 \a orient holds the wheel's orientation.
580
581 \sa pos() globalPos() delta() state()
582 */
QWheelEvent(const QPoint & pos,const QPoint & globalPos,int delta,Qt::MouseButtons buttons,Qt::KeyboardModifiers modifiers,Qt::Orientation orient)583 QWheelEvent::QWheelEvent(const QPoint &pos, const QPoint& globalPos, int delta,
584 Qt::MouseButtons buttons, Qt::KeyboardModifiers modifiers,
585 Qt::Orientation orient)
586 : QInputEvent(Wheel, modifiers), p(pos), g(globalPos), d(delta), mouseState(buttons), o(orient)
587 {}
588
589 #ifdef QT3_SUPPORT
590 /*!
591 Use one of the other constructors instead.
592 */
QWheelEvent(const QPoint & pos,const QPoint & globalPos,int delta,int state,Qt::Orientation orient)593 QWheelEvent::QWheelEvent(const QPoint &pos, const QPoint& globalPos, int delta, int state,
594 Qt::Orientation orient)
595 : QInputEvent(Wheel), p(pos), g(globalPos), d(delta), o(orient)
596 {
597 mouseState = Qt::MouseButtons(state & Qt::MouseButtonMask);
598 modState = Qt::KeyboardModifiers(state & (int) Qt::KeyButtonMask);
599 }
600 #endif
601 #endif // QT_NO_WHEELEVENT
602
603 /*!
604 \fn int QWheelEvent::delta() const
605
606 Returns the distance that the wheel is rotated, in eighths of a
607 degree. A positive value indicates that the wheel was rotated
608 forwards away from the user; a negative value indicates that the
609 wheel was rotated backwards toward the user.
610
611 Most mouse types work in steps of 15 degrees, in which case the
612 delta value is a multiple of 120; i.e., 120 units * 1/8 = 15 degrees.
613
614 However, some mice have finer-resolution wheels and send delta values
615 that are less than 120 units (less than 15 degrees). To support this
616 possibility, you can either cumulatively add the delta values from events
617 until the value of 120 is reached, then scroll the widget, or you can
618 partially scroll the widget in response to each wheel event.
619
620 Example:
621
622 \snippet doc/src/snippets/code/src_gui_kernel_qevent.cpp 0
623 */
624
625 /*!
626 \fn const QPoint &QWheelEvent::pos() const
627
628 Returns the position of the mouse cursor relative to the widget
629 that received the event.
630
631 If you move your widgets around in response to mouse events,
632 use globalPos() instead of this function.
633
634 \sa x() y() globalPos()
635 */
636
637 /*!
638 \fn int QWheelEvent::x() const
639
640 Returns the x position of the mouse cursor, relative to the
641 widget that received the event.
642
643 \sa y() pos()
644 */
645
646 /*!
647 \fn int QWheelEvent::y() const
648
649 Returns the y position of the mouse cursor, relative to the
650 widget that received the event.
651
652 \sa x() pos()
653 */
654
655
656 /*!
657 \fn const QPoint &QWheelEvent::globalPos() const
658
659 Returns the global position of the mouse pointer \e{at the time
660 of the event}. This is important on asynchronous window systems
661 such as X11; whenever you move your widgets around in response to
662 mouse events, globalPos() can differ a lot from the current
663 cursor position returned by QCursor::pos().
664
665 \sa globalX() globalY()
666 */
667
668 /*!
669 \fn int QWheelEvent::globalX() const
670
671 Returns the global x position of the mouse cursor at the time of
672 the event.
673
674 \sa globalY() globalPos()
675 */
676
677 /*!
678 \fn int QWheelEvent::globalY() const
679
680 Returns the global y position of the mouse cursor at the time of
681 the event.
682
683 \sa globalX() globalPos()
684 */
685
686
687 /*! \obsolete
688 \fn Qt::ButtonState QWheelEvent::state() const
689
690 Returns the keyboard modifier flags at the time of the event.
691
692 The returned value is a selection of the following values,
693 combined using the OR operator: Qt::ShiftButton,
694 Qt::ControlButton, and Qt::AltButton.
695 */
696
697
698 /*!
699 \class QKeyEvent
700 \brief The QKeyEvent class describes a key event.
701
702 \ingroup events
703
704 Key events are sent to the widget with keyboard input focus
705 when keys are pressed or released.
706
707 A key event contains a special accept flag that indicates whether
708 the receiver will handle the key event. You should call ignore()
709 if the key press or release event is not handled by your widget.
710 A key event is propagated up the parent widget chain until a
711 widget accepts it with accept() or an event filter consumes it.
712 Key events for multimedia keys are ignored by default. You should
713 call accept() if your widget handles those events.
714
715 The QWidget::setEnable() function can be used to enable or disable
716 mouse and keyboard events for a widget.
717
718 The event handlers QWidget::keyPressEvent(), QWidget::keyReleaseEvent(),
719 QGraphicsItem::keyPressEvent() and QGraphicsItem::keyReleaseEvent()
720 receive key events.
721
722 \sa QFocusEvent, QWidget::grabKeyboard()
723 */
724
725 /*!
726 Constructs a key event object.
727
728 The \a type parameter must be QEvent::KeyPress, QEvent::KeyRelease,
729 or QEvent::ShortcutOverride.
730
731 Int \a key is the code for the Qt::Key that the event loop should listen
732 for. If \a key is 0, the event is not a result of a known key; for
733 example, it may be the result of a compose sequence or keyboard macro.
734 The \a modifiers holds the keyboard modifiers, and the given \a text
735 is the Unicode text that the key generated. If \a autorep is true,
736 isAutoRepeat() will be true. \a count is the number of keys involved
737 in the event.
738 */
QKeyEvent(Type type,int key,Qt::KeyboardModifiers modifiers,const QString & text,bool autorep,ushort count)739 QKeyEvent::QKeyEvent(Type type, int key, Qt::KeyboardModifiers modifiers, const QString& text,
740 bool autorep, ushort count)
741 : QInputEvent(type, modifiers), txt(text), k(key), c(count), autor(autorep)
742 {
743 }
744
745 /*!
746 \internal
747 */
~QKeyEvent()748 QKeyEvent::~QKeyEvent()
749 {
750 }
751
752 /*!
753 \internal
754 */
createExtendedKeyEvent(Type type,int key,Qt::KeyboardModifiers modifiers,quint32 nativeScanCode,quint32 nativeVirtualKey,quint32 nativeModifiers,const QString & text,bool autorep,ushort count)755 QKeyEvent *QKeyEvent::createExtendedKeyEvent(Type type, int key, Qt::KeyboardModifiers modifiers,
756 quint32 nativeScanCode, quint32 nativeVirtualKey,
757 quint32 nativeModifiers,
758 const QString& text, bool autorep, ushort count)
759 {
760 return new QKeyEventEx(type, key, modifiers, text, autorep, count,
761 nativeScanCode, nativeVirtualKey, nativeModifiers);
762 }
763
764 /*!
765 \fn bool QKeyEvent::hasExtendedInfo() const
766 \internal
767 */
768
769 /*!
770 \since 4.2
771
772 Returns the native scan code of the key event. If the key event
773 does not contain this data 0 is returned.
774
775 Note: The native scan code may be 0, even if the key event contains
776 extended information.
777
778 Note: On Mac OS/X, this function is not useful, because there is no
779 way to get the scan code from Carbon or Cocoa. The function always
780 returns 1 (or 0 in the case explained above).
781 */
nativeScanCode() const782 quint32 QKeyEvent::nativeScanCode() const
783 {
784 return (reinterpret_cast<const QKeyEvent*>(d) != this
785 ? 0 : reinterpret_cast<const QKeyEventEx*>(this)->nScanCode);
786 }
787
788 /*!
789 \since 4.2
790
791 Returns the native virtual key, or key sym of the key event.
792 If the key event does not contain this data 0 is returned.
793
794 Note: The native virtual key may be 0, even if the key event contains extended information.
795 */
nativeVirtualKey() const796 quint32 QKeyEvent::nativeVirtualKey() const
797 {
798 return (reinterpret_cast<const QKeyEvent*>(d) != this
799 ? 0 : reinterpret_cast<const QKeyEventEx*>(this)->nVirtualKey);
800 }
801
802 /*!
803 \since 4.2
804
805 Returns the native modifiers of a key event.
806 If the key event does not contain this data 0 is returned.
807
808 Note: The native modifiers may be 0, even if the key event contains extended information.
809 */
nativeModifiers() const810 quint32 QKeyEvent::nativeModifiers() const
811 {
812 return (reinterpret_cast<const QKeyEvent*>(d) != this
813 ? 0 : reinterpret_cast<const QKeyEventEx*>(this)->nModifiers);
814 }
815
816 /*!
817 \internal
818 Creates an extended key event object, which in addition to the normal key event data, also
819 contains the native scan code, virtual key and modifiers. This extra data is used by the
820 shortcut system, to determine which shortcuts to trigger.
821 */
QKeyEventEx(Type type,int key,Qt::KeyboardModifiers modifiers,const QString & text,bool autorep,ushort count,quint32 nativeScanCode,quint32 nativeVirtualKey,quint32 nativeModifiers)822 QKeyEventEx::QKeyEventEx(Type type, int key, Qt::KeyboardModifiers modifiers,
823 const QString &text, bool autorep, ushort count,
824 quint32 nativeScanCode, quint32 nativeVirtualKey, quint32 nativeModifiers)
825 : QKeyEvent(type, key, modifiers, text, autorep, count),
826 nScanCode(nativeScanCode), nVirtualKey(nativeVirtualKey), nModifiers(nativeModifiers)
827 {
828 d = reinterpret_cast<QEventPrivate*>(this);
829 }
830
831 /*!
832 \internal
833 Creates a copy of an other extended key event.
834 */
QKeyEventEx(const QKeyEventEx & other)835 QKeyEventEx::QKeyEventEx(const QKeyEventEx &other)
836 : QKeyEvent(QEvent::Type(other.t), other.k, other.modState, other.txt, other.autor, other.c),
837 nScanCode(other.nScanCode), nVirtualKey(other.nVirtualKey), nModifiers(other.nModifiers)
838 {
839 d = reinterpret_cast<QEventPrivate*>(this);
840 }
841
842 /*!
843 \internal
844 */
~QKeyEventEx()845 QKeyEventEx::~QKeyEventEx()
846 {
847 }
848
849 /*!
850 \fn int QKeyEvent::key() const
851
852 Returns the code of the key that was pressed or released.
853
854 See \l Qt::Key for the list of keyboard codes. These codes are
855 independent of the underlying window system. Note that this
856 function does not distinguish between capital and non-capital
857 letters, use the text() function (returning the Unicode text the
858 key generated) for this purpose.
859
860 A value of either 0 or Qt::Key_unknown means that the event is not
861 the result of a known key; for example, it may be the result of
862 a compose sequence, a keyboard macro, or due to key event
863 compression.
864
865 \sa Qt::WA_KeyCompression
866 */
867
868 /*!
869 \fn QString QKeyEvent::text() const
870
871 Returns the Unicode text that this key generated. The text
872 returned can be an empty string in cases
873 where modifier keys, such as Shift, Control, Alt, and Meta,
874 are being pressed or released. In such cases key() will contain
875 a valid value.
876
877 \sa Qt::WA_KeyCompression
878 */
879
880 /*!
881 Returns the keyboard modifier flags that existed immediately
882 after the event occurred.
883
884 \warning This function cannot always be trusted. The user can
885 confuse it by pressing both \key{Shift} keys simultaneously and
886 releasing one of them, for example.
887
888 \sa QApplication::keyboardModifiers()
889 */
890 //###### We must check with XGetModifierMapping
modifiers() const891 Qt::KeyboardModifiers QKeyEvent::modifiers() const
892 {
893 if (key() == Qt::Key_Shift)
894 return Qt::KeyboardModifiers(QInputEvent::modifiers()^Qt::ShiftModifier);
895 if (key() == Qt::Key_Control)
896 return Qt::KeyboardModifiers(QInputEvent::modifiers()^Qt::ControlModifier);
897 if (key() == Qt::Key_Alt)
898 return Qt::KeyboardModifiers(QInputEvent::modifiers()^Qt::AltModifier);
899 if (key() == Qt::Key_Meta)
900 return Qt::KeyboardModifiers(QInputEvent::modifiers()^Qt::MetaModifier);
901 return QInputEvent::modifiers();
902 }
903
904 #ifndef QT_NO_SHORTCUT
905 /*!
906 \fn bool QKeyEvent::matches(QKeySequence::StandardKey key) const
907 \since 4.2
908
909 Returns true if the key event matches the given standard \a key;
910 otherwise returns false.
911 */
matches(QKeySequence::StandardKey matchKey) const912 bool QKeyEvent::matches(QKeySequence::StandardKey matchKey) const
913 {
914 uint searchkey = (modifiers() | key()) & ~(Qt::KeypadModifier); //The keypad modifier should not make a difference
915 uint platform = QApplicationPrivate::currentPlatform();
916
917 #ifdef Q_WS_MAC
918 if (qApp->testAttribute(Qt::AA_MacDontSwapCtrlAndMeta)) {
919 uint oldSearchKey = searchkey;
920 searchkey &= ~(Qt::ControlModifier | Qt::MetaModifier);
921 if (oldSearchKey & Qt::ControlModifier)
922 searchkey |= Qt::MetaModifier;
923 if (oldSearchKey & Qt::MetaModifier)
924 searchkey |= Qt::ControlModifier;
925 }
926 #endif
927
928 uint N = QKeySequencePrivate::numberOfKeyBindings;
929 int first = 0;
930 int last = N - 1;
931
932 while (first <= last) {
933 int mid = (first + last) / 2;
934 QKeyBinding midVal = QKeySequencePrivate::keyBindings[mid];
935
936 if (searchkey > midVal.shortcut){
937 first = mid + 1; // Search in top half
938 }
939 else if (searchkey < midVal.shortcut){
940 last = mid - 1; // Search in bottom half
941 }
942 else {
943 //found correct shortcut value, now we must check for platform match
944 if ((midVal.platform & platform) && (midVal.standardKey == matchKey)) {
945 return true;
946 } else { //We may have several equal values for different platforms, so we must search in both directions
947
948 //search forward
949 for ( unsigned int i = mid + 1 ; i < N - 1 ; ++i) {
950 QKeyBinding current = QKeySequencePrivate::keyBindings[i];
951 if (current.shortcut != searchkey)
952 break;
953 else if (current.platform & platform && current.standardKey == matchKey)
954 return true;
955 }
956
957 //search back
958 for ( int i = mid - 1 ; i >= 0 ; --i) {
959 QKeyBinding current = QKeySequencePrivate::keyBindings[i];
960 if (current.shortcut != searchkey)
961 break;
962 else if (current.platform & platform && current.standardKey == matchKey)
963 return true;
964 }
965 return false; //we could not find it among the matching keySequences
966 }
967 }
968 }
969 return false; //we could not find matching keySequences at all
970 }
971 #endif // QT_NO_SHORTCUT
972
973
974 /*!
975 \fn bool QKeyEvent::isAutoRepeat() const
976
977 Returns true if this event comes from an auto-repeating key;
978 returns false if it comes from an initial key press.
979
980 Note that if the event is a multiple-key compressed event that is
981 partly due to auto-repeat, this function could return either true
982 or false indeterminately.
983 */
984
985 /*!
986 \fn int QKeyEvent::count() const
987
988 Returns the number of keys involved in this event. If text()
989 is not empty, this is simply the length of the string.
990
991 \sa Qt::WA_KeyCompression
992 */
993
994 #ifdef QT3_SUPPORT
995 /*!
996 \fn QKeyEvent::QKeyEvent(Type type, int key, int ascii,
997 int modifiers, const QString &text,
998 bool autorep, ushort count)
999
1000 Use one of the other constructors instead.
1001 */
1002
1003 /*!
1004 \fn int QKeyEvent::ascii() const
1005
1006 Use text() instead.
1007 */
1008
1009 /*!
1010 \fn Qt::ButtonState QKeyEvent::state() const
1011
1012 Use QInputEvent::modifiers() instead.
1013 */
1014
1015 /*!
1016 \fn Qt::ButtonState QKeyEvent::stateAfter() const
1017
1018 Use modifiers() instead.
1019 */
1020 #endif
1021
1022 /*!
1023 \class QFocusEvent
1024 \brief The QFocusEvent class contains event parameters for widget focus
1025 events.
1026
1027 \ingroup events
1028
1029 Focus events are sent to widgets when the keyboard input focus
1030 changes. Focus events occur due to mouse actions, key presses
1031 (such as \gui{Tab} or \gui{Backtab}), the window system, popup
1032 menus, keyboard shortcuts, or other application-specific reasons.
1033 The reason for a particular focus event is returned by reason()
1034 in the appropriate event handler.
1035
1036 The event handlers QWidget::focusInEvent(),
1037 QWidget::focusOutEvent(), QGraphicsItem::focusInEvent and
1038 QGraphicsItem::focusOutEvent() receive focus events.
1039
1040 \sa QWidget::setFocus(), QWidget::setFocusPolicy(), {Keyboard Focus}
1041 */
1042
1043 /*!
1044 Constructs a focus event object.
1045
1046 The \a type parameter must be either QEvent::FocusIn or
1047 QEvent::FocusOut. The \a reason describes the cause of the change
1048 in focus.
1049 */
QFocusEvent(Type type,Qt::FocusReason reason)1050 QFocusEvent::QFocusEvent(Type type, Qt::FocusReason reason)
1051 : QEvent(type), m_reason(reason)
1052 {}
1053
1054 /*!
1055 \internal
1056 */
~QFocusEvent()1057 QFocusEvent::~QFocusEvent()
1058 {
1059 }
1060
1061 // ### Qt 5: remove
1062 /*!
1063 \internal
1064 */
reason()1065 Qt::FocusReason QFocusEvent::reason()
1066 {
1067 return m_reason;
1068 }
1069
1070 /*!
1071 Returns the reason for this focus event.
1072 */
reason() const1073 Qt::FocusReason QFocusEvent::reason() const
1074 {
1075 return m_reason;
1076 }
1077
1078 /*!
1079 \fn bool QFocusEvent::gotFocus() const
1080
1081 Returns true if type() is QEvent::FocusIn; otherwise returns
1082 false.
1083 */
1084
1085 /*!
1086 \fn bool QFocusEvent::lostFocus() const
1087
1088 Returns true if type() is QEvent::FocusOut; otherwise returns
1089 false.
1090 */
1091
1092 #ifdef QT3_SUPPORT
1093 /*!
1094 \enum QFocusEvent::Reason
1095 \compat
1096
1097 Use Qt::FocusReason instead.
1098
1099 \value Mouse Same as Qt::MouseFocusReason.
1100 \value Tab Same as Qt::TabFocusReason.
1101 \value Backtab Same as Qt::BacktabFocusReason.
1102 \value MenuBar Same as Qt::MenuBarFocusReason.
1103 \value ActiveWindow Same as Qt::ActiveWindowFocusReason
1104 \value Other Same as Qt::OtherFocusReason
1105 \value Popup Same as Qt::PopupFocusReason
1106 \value Shortcut Same as Qt::ShortcutFocusReason
1107 */
1108 #endif
1109
1110 /*!
1111 \class QPaintEvent
1112 \brief The QPaintEvent class contains event parameters for paint events.
1113
1114 \ingroup events
1115
1116 Paint events are sent to widgets that need to update themselves,
1117 for instance when part of a widget is exposed because a covering
1118 widget was moved.
1119
1120 The event contains a region() that needs to be updated, and a
1121 rect() that is the bounding rectangle of that region. Both are
1122 provided because many widgets can't make much use of region(),
1123 and rect() can be much faster than region().boundingRect().
1124
1125 \section1 Automatic Clipping
1126
1127 Painting is clipped to region() during the processing of a paint
1128 event. This clipping is performed by Qt's paint system and is
1129 independent of any clipping that may be applied to a QPainter used to
1130 draw on the paint device.
1131
1132 As a result, the value returned by QPainter::clipRegion() on
1133 a newly-constructed QPainter will not reflect the clip region that is
1134 used by the paint system.
1135
1136 \sa QPainter, QWidget::update(), QWidget::repaint(),
1137 QWidget::paintEvent()
1138 */
1139
1140 /*!
1141 \fn bool QPaintEvent::erased() const
1142 \compat
1143
1144 Returns true if the paint event region (or rectangle) has been
1145 erased with the widget's background; otherwise returns false.
1146
1147 Qt 4 \e always erases regions that require painting. The exception
1148 to this rule is if the widget sets the Qt::WA_OpaquePaintEvent or
1149 Qt::WA_NoSystemBackground attributes. If either one of those
1150 attributes is set \e and the window system does not make use of
1151 subwidget alpha composition (currently X11 and Windows, but this
1152 may change), then the region is not erased.
1153 */
1154
1155 /*!
1156 \fn void QPaintEvent::setErased(bool b) { m_erased = b; }
1157 \internal
1158 */
1159
1160 /*!
1161 Constructs a paint event object with the region that needs to
1162 be updated. The region is specified by \a paintRegion.
1163 */
QPaintEvent(const QRegion & paintRegion)1164 QPaintEvent::QPaintEvent(const QRegion& paintRegion)
1165 : QEvent(Paint), m_rect(paintRegion.boundingRect()), m_region(paintRegion), m_erased(false)
1166 {}
1167
1168 /*!
1169 Constructs a paint event object with the rectangle that needs
1170 to be updated. The region is specified by \a paintRect.
1171 */
QPaintEvent(const QRect & paintRect)1172 QPaintEvent::QPaintEvent(const QRect &paintRect)
1173 : QEvent(Paint), m_rect(paintRect),m_region(paintRect), m_erased(false)
1174 {}
1175
1176
1177 #ifdef QT3_SUPPORT
1178 /*!
1179 Constructs a paint event object with both a \a paintRegion and a
1180 \a paintRect, both of which represent the area of the widget that
1181 needs to be updated.
1182
1183 */
QPaintEvent(const QRegion & paintRegion,const QRect & paintRect)1184 QPaintEvent::QPaintEvent(const QRegion &paintRegion, const QRect &paintRect)
1185 : QEvent(Paint), m_rect(paintRect), m_region(paintRegion), m_erased(false)
1186 {}
1187 #endif
1188
1189 /*!
1190 \internal
1191 */
~QPaintEvent()1192 QPaintEvent::~QPaintEvent()
1193 {
1194 }
1195
1196 /*!
1197 \fn const QRect &QPaintEvent::rect() const
1198
1199 Returns the rectangle that needs to be updated.
1200
1201 \sa region() QPainter::setClipRect()
1202 */
1203
1204 /*!
1205 \fn const QRegion &QPaintEvent::region() const
1206
1207 Returns the region that needs to be updated.
1208
1209 \sa rect() QPainter::setClipRegion()
1210 */
1211
1212
QUpdateLaterEvent(const QRegion & paintRegion)1213 QUpdateLaterEvent::QUpdateLaterEvent(const QRegion& paintRegion)
1214 : QEvent(UpdateLater), m_region(paintRegion)
1215 {
1216 }
1217
~QUpdateLaterEvent()1218 QUpdateLaterEvent::~QUpdateLaterEvent()
1219 {
1220 }
1221
1222 /*!
1223 \class QMoveEvent
1224 \brief The QMoveEvent class contains event parameters for move events.
1225
1226 \ingroup events
1227
1228 Move events are sent to widgets that have been moved to a new
1229 position relative to their parent.
1230
1231 The event handler QWidget::moveEvent() receives move events.
1232
1233 \sa QWidget::move(), QWidget::setGeometry()
1234 */
1235
1236 /*!
1237 Constructs a move event with the new and old widget positions,
1238 \a pos and \a oldPos respectively.
1239 */
QMoveEvent(const QPoint & pos,const QPoint & oldPos)1240 QMoveEvent::QMoveEvent(const QPoint &pos, const QPoint &oldPos)
1241 : QEvent(Move), p(pos), oldp(oldPos)
1242 {}
1243
1244 /*!
1245 \internal
1246 */
~QMoveEvent()1247 QMoveEvent::~QMoveEvent()
1248 {
1249 }
1250
1251 /*!
1252 \fn const QPoint &QMoveEvent::pos() const
1253
1254 Returns the new position of the widget. This excludes the window
1255 frame for top level widgets.
1256 */
1257
1258 /*!
1259 \fn const QPoint &QMoveEvent::oldPos() const
1260
1261 Returns the old position of the widget.
1262 */
1263
1264
1265 /*!
1266 \class QResizeEvent
1267 \brief The QResizeEvent class contains event parameters for resize events.
1268
1269 \ingroup events
1270
1271 Resize events are sent to widgets that have been resized.
1272
1273 The event handler QWidget::resizeEvent() receives resize events.
1274
1275 \sa QWidget::resize() QWidget::setGeometry()
1276 */
1277
1278 /*!
1279 Constructs a resize event with the new and old widget sizes, \a
1280 size and \a oldSize respectively.
1281 */
QResizeEvent(const QSize & size,const QSize & oldSize)1282 QResizeEvent::QResizeEvent(const QSize &size, const QSize &oldSize)
1283 : QEvent(Resize), s(size), olds(oldSize)
1284 {}
1285
1286 /*!
1287 \internal
1288 */
~QResizeEvent()1289 QResizeEvent::~QResizeEvent()
1290 {
1291 }
1292
1293 /*!
1294 \fn const QSize &QResizeEvent::size() const
1295
1296 Returns the new size of the widget. This is the same as
1297 QWidget::size().
1298 */
1299
1300 /*!
1301 \fn const QSize &QResizeEvent::oldSize() const
1302
1303 Returns the old size of the widget.
1304 */
1305
1306
1307 /*!
1308 \class QCloseEvent
1309 \brief The QCloseEvent class contains parameters that describe a close event.
1310
1311 \ingroup events
1312
1313 Close events are sent to widgets that the user wants to close,
1314 usually by choosing "Close" from the window menu, or by clicking
1315 the \gui{X} title bar button. They are also sent when you call
1316 QWidget::close() to close a widget programmatically.
1317
1318 Close events contain a flag that indicates whether the receiver
1319 wants the widget to be closed or not. When a widget accepts the
1320 close event, it is hidden (and destroyed if it was created with
1321 the Qt::WA_DeleteOnClose flag). If it refuses to accept the close
1322 event nothing happens. (Under X11 it is possible that the window
1323 manager will forcibly close the window; but at the time of writing
1324 we are not aware of any window manager that does this.)
1325
1326 The event handler QWidget::closeEvent() receives close events. The
1327 default implementation of this event handler accepts the close
1328 event. If you do not want your widget to be hidden, or want some
1329 special handing, you should reimplement the event handler and
1330 ignore() the event.
1331
1332 The \l{mainwindows/application#close event handler}{closeEvent() in the
1333 Application example} shows a close event handler that
1334 asks whether to save a document before closing.
1335
1336 If you want the widget to be deleted when it is closed, create it
1337 with the Qt::WA_DeleteOnClose flag. This is very useful for
1338 independent top-level windows in a multi-window application.
1339
1340 \l{QObject}s emits the \l{QObject::destroyed()}{destroyed()}
1341 signal when they are deleted.
1342
1343 If the last top-level window is closed, the
1344 QApplication::lastWindowClosed() signal is emitted.
1345
1346 The isAccepted() function returns true if the event's receiver has
1347 agreed to close the widget; call accept() to agree to close the
1348 widget and call ignore() if the receiver of this event does not
1349 want the widget to be closed.
1350
1351 \sa QWidget::close(), QWidget::hide(), QObject::destroyed(),
1352 QCoreApplication::exec(), QCoreApplication::quit(),
1353 QApplication::lastWindowClosed()
1354 */
1355
1356 /*!
1357 Constructs a close event object.
1358
1359 \sa accept()
1360 */
QCloseEvent()1361 QCloseEvent::QCloseEvent()
1362 : QEvent(Close)
1363 {}
1364
1365 /*! \internal
1366 */
~QCloseEvent()1367 QCloseEvent::~QCloseEvent()
1368 {
1369 }
1370
1371 /*!
1372 \class QIconDragEvent
1373 \brief The QIconDragEvent class indicates that a main icon drag has begun.
1374
1375 \ingroup events
1376
1377 Icon drag events are sent to widgets when the main icon of a window
1378 has been dragged away. On Mac OS X, this happens when the proxy
1379 icon of a window is dragged off the title bar.
1380
1381 It is normal to begin using drag and drop in response to this
1382 event.
1383
1384 \sa {Drag and Drop}, QMimeData, QDrag
1385 */
1386
1387 /*!
1388 Constructs an icon drag event object with the accept flag set to
1389 false.
1390
1391 \sa accept()
1392 */
QIconDragEvent()1393 QIconDragEvent::QIconDragEvent()
1394 : QEvent(IconDrag)
1395 { ignore(); }
1396
1397 /*! \internal */
~QIconDragEvent()1398 QIconDragEvent::~QIconDragEvent()
1399 {
1400 }
1401
1402 /*!
1403 \class QContextMenuEvent
1404 \brief The QContextMenuEvent class contains parameters that describe a context menu event.
1405
1406 \ingroup events
1407
1408 Context menu events are sent to widgets when a user performs
1409 an action associated with opening a context menu.
1410 The actions required to open context menus vary between platforms;
1411 for example, on Windows, pressing the menu button or clicking the
1412 right mouse button will cause this event to be sent.
1413
1414 When this event occurs it is customary to show a QMenu with a
1415 context menu, if this is relevant to the context.
1416
1417 Context menu events contain a special accept flag that indicates
1418 whether the receiver accepted the event. If the event handler does
1419 not accept the event then, if possible, whatever triggered the event will be
1420 handled as a regular input event.
1421 */
1422
1423 #ifndef QT_NO_CONTEXTMENU
1424 /*!
1425 Constructs a context menu event object with the accept parameter
1426 flag set to false.
1427
1428 The \a reason parameter must be QContextMenuEvent::Mouse or
1429 QContextMenuEvent::Keyboard.
1430
1431 The \a pos parameter specifies the mouse position relative to the
1432 receiving widget. \a globalPos is the mouse position in absolute
1433 coordinates.
1434 */
QContextMenuEvent(Reason reason,const QPoint & pos,const QPoint & globalPos)1435 QContextMenuEvent::QContextMenuEvent(Reason reason, const QPoint &pos, const QPoint &globalPos)
1436 : QInputEvent(ContextMenu), p(pos), gp(globalPos), reas(reason)
1437 {}
1438
1439 /*!
1440 Constructs a context menu event object with the accept parameter
1441 flag set to false.
1442
1443 The \a reason parameter must be QContextMenuEvent::Mouse or
1444 QContextMenuEvent::Keyboard.
1445
1446 The \a pos parameter specifies the mouse position relative to the
1447 receiving widget. \a globalPos is the mouse position in absolute
1448 coordinates. The \a modifiers holds the keyboard modifiers.
1449 */
QContextMenuEvent(Reason reason,const QPoint & pos,const QPoint & globalPos,Qt::KeyboardModifiers modifiers)1450 QContextMenuEvent::QContextMenuEvent(Reason reason, const QPoint &pos, const QPoint &globalPos,
1451 Qt::KeyboardModifiers modifiers)
1452 : QInputEvent(ContextMenu, modifiers), p(pos), gp(globalPos), reas(reason)
1453 {}
1454
1455 #ifdef QT3_SUPPORT
1456 /*!
1457 Constructs a context menu event with the given \a reason for the
1458 position specified by \a pos in widget coordinates and \a globalPos
1459 in global screen coordinates. \a dummy is ignored.
1460 */
QContextMenuEvent(Reason reason,const QPoint & pos,const QPoint & globalPos,int)1461 QContextMenuEvent::QContextMenuEvent(Reason reason, const QPoint &pos, const QPoint &globalPos,
1462 int /* dummy */)
1463 : QInputEvent(ContextMenu), p(pos), gp(globalPos), reas(reason)
1464 {}
1465 #endif
1466
1467 /*! \internal */
~QContextMenuEvent()1468 QContextMenuEvent::~QContextMenuEvent()
1469 {
1470 }
1471 /*!
1472 Constructs a context menu event object with the accept parameter
1473 flag set to false.
1474
1475 The \a reason parameter must be QContextMenuEvent::Mouse or
1476 QContextMenuEvent::Keyboard.
1477
1478 The \a pos parameter specifies the mouse position relative to the
1479 receiving widget.
1480
1481 The globalPos() is initialized to QCursor::pos(), which may not be
1482 appropriate. Use the other constructor to specify the global
1483 position explicitly.
1484 */
QContextMenuEvent(Reason reason,const QPoint & pos)1485 QContextMenuEvent::QContextMenuEvent(Reason reason, const QPoint &pos)
1486 : QInputEvent(ContextMenu), p(pos), reas(reason)
1487 {
1488 gp = QCursor::pos();
1489 }
1490
1491 #ifdef QT3_SUPPORT
1492 /*!
1493 Constructs a context menu event with the given \a reason for the
1494 position specified by \a pos in widget coordinates. \a dummy is
1495 ignored.
1496 */
QContextMenuEvent(Reason reason,const QPoint & pos,int)1497 QContextMenuEvent::QContextMenuEvent(Reason reason, const QPoint &pos, int /* dummy */)
1498 : QInputEvent(ContextMenu), p(pos), reas(reason)
1499 {
1500 gp = QCursor::pos();
1501 }
1502
state() const1503 Qt::ButtonState QContextMenuEvent::state() const
1504 {
1505 return Qt::ButtonState(int(QApplication::keyboardModifiers())|QApplication::mouseButtons());
1506 }
1507 #endif
1508
1509 /*!
1510 \fn const QPoint &QContextMenuEvent::pos() const
1511
1512 Returns the position of the mouse pointer relative to the widget
1513 that received the event.
1514
1515 \sa x(), y(), globalPos()
1516 */
1517
1518 /*!
1519 \fn int QContextMenuEvent::x() const
1520
1521 Returns the x position of the mouse pointer, relative to the
1522 widget that received the event.
1523
1524 \sa y(), pos()
1525 */
1526
1527 /*!
1528 \fn int QContextMenuEvent::y() const
1529
1530 Returns the y position of the mouse pointer, relative to the
1531 widget that received the event.
1532
1533 \sa x(), pos()
1534 */
1535
1536 /*!
1537 \fn const QPoint &QContextMenuEvent::globalPos() const
1538
1539 Returns the global position of the mouse pointer at the time of
1540 the event.
1541
1542 \sa x(), y(), pos()
1543 */
1544
1545 /*!
1546 \fn int QContextMenuEvent::globalX() const
1547
1548 Returns the global x position of the mouse pointer at the time of
1549 the event.
1550
1551 \sa globalY(), globalPos()
1552 */
1553
1554 /*!
1555 \fn int QContextMenuEvent::globalY() const
1556
1557 Returns the global y position of the mouse pointer at the time of
1558 the event.
1559
1560 \sa globalX(), globalPos()
1561 */
1562 #endif // QT_NO_CONTEXTMENU
1563
1564 /*!
1565 \fn Qt::ButtonState QContextMenuEvent::state() const
1566
1567 Returns the button state (a combination of mouse buttons
1568 and keyboard modifiers) immediately before the event was
1569 generated.
1570
1571 The returned value is a selection of the following values,
1572 combined with the OR operator:
1573 Qt::LeftButton, Qt::RightButton, Qt::MidButton,
1574 Qt::ShiftButton, Qt::ControlButton, and Qt::AltButton.
1575 */
1576
1577 /*!
1578 \enum QContextMenuEvent::Reason
1579
1580 This enum describes the reason why the event was sent.
1581
1582 \value Mouse The mouse caused the event to be sent. Normally this
1583 means the right mouse button was clicked, but this is platform
1584 dependent.
1585
1586 \value Keyboard The keyboard caused this event to be sent. On
1587 Windows, this means the menu button was pressed.
1588
1589 \value Other The event was sent by some other means (i.e. not by
1590 the mouse or keyboard).
1591 */
1592
1593
1594 /*!
1595 \fn QContextMenuEvent::Reason QContextMenuEvent::reason() const
1596
1597 Returns the reason for this context event.
1598 */
1599
1600
1601 /*!
1602 \class QInputMethodEvent
1603 \brief The QInputMethodEvent class provides parameters for input method events.
1604
1605 \ingroup events
1606
1607 Input method events are sent to widgets when an input method is
1608 used to enter text into a widget. Input methods are widely used
1609 to enter text for languages with non-Latin alphabets.
1610
1611 Note that when creating custom text editing widgets, the
1612 Qt::WA_InputMethodEnabled window attribute must be set explicitly
1613 (using the QWidget::setAttribute() function) in order to receive
1614 input method events.
1615
1616 The events are of interest to authors of keyboard entry widgets
1617 who want to be able to correctly handle languages with complex
1618 character input. Text input in such languages is usually a three
1619 step process:
1620
1621 \list 1
1622 \o \bold{Starting to Compose}
1623
1624 When the user presses the first key on a keyboard, an input
1625 context is created. This input context will contain a string
1626 of the typed characters.
1627
1628 \o \bold{Composing}
1629
1630 With every new key pressed, the input method will try to create a
1631 matching string for the text typed so far called preedit
1632 string. While the input context is active, the user can only move
1633 the cursor inside the string belonging to this input context.
1634
1635 \o \bold{Completing}
1636
1637 At some point, the user will activate a user interface component
1638 (perhaps using a particular key) where they can choose from a
1639 number of strings matching the text they have typed so far. The
1640 user can either confirm their choice cancel the input; in either
1641 case the input context will be closed.
1642 \endlist
1643
1644 QInputMethodEvent models these three stages, and transfers the
1645 information needed to correctly render the intermediate result. A
1646 QInputMethodEvent has two main parameters: preeditString() and
1647 commitString(). The preeditString() parameter gives the currently
1648 active preedit string. The commitString() parameter gives a text
1649 that should get added to (or replace parts of) the text of the
1650 editor widget. It usually is a result of the input operations and
1651 has to be inserted to the widgets text directly before the preedit
1652 string.
1653
1654 If the commitString() should replace parts of the of the text in
1655 the editor, replacementLength() will contain the number of
1656 characters to be replaced. replacementStart() contains the position
1657 at which characters are to be replaced relative from the start of
1658 the preedit string.
1659
1660 A number of attributes control the visual appearance of the
1661 preedit string (the visual appearance of text outside the preedit
1662 string is controlled by the widget only). The AttributeType enum
1663 describes the different attributes that can be set.
1664
1665 A class implementing QWidget::inputMethodEvent() or
1666 QGraphicsItem::inputMethodEvent() should at least understand and
1667 honor the \l TextFormat and \l Cursor attributes.
1668
1669 Since input methods need to be able to query certain properties
1670 from the widget or graphics item, subclasses must also implement
1671 QWidget::inputMethodQuery() and QGraphicsItem::inputMethodQuery(),
1672 respectively.
1673
1674 When receiving an input method event, the text widget has to performs the
1675 following steps:
1676
1677 \list 1
1678 \o If the widget has selected text, the selected text should get
1679 removed.
1680
1681 \o Remove the text starting at replacementStart() with length
1682 replacementLength() and replace it by the commitString(). If
1683 replacementLength() is 0, replacementStart() gives the insertion
1684 position for the commitString().
1685
1686 When doing replacement the area of the preedit
1687 string is ignored, thus a replacement starting at -1 with a length
1688 of 2 will remove the last character before the preedit string and
1689 the first character afterwards, and insert the commit string
1690 directly before the preedit string.
1691
1692 If the widget implements undo/redo, this operation gets added to
1693 the undo stack.
1694
1695 \o If there is no current preedit string, insert the
1696 preeditString() at the current cursor position; otherwise replace
1697 the previous preeditString with the one received from this event.
1698
1699 If the widget implements undo/redo, the preeditString() should not
1700 influence the undo/redo stack in any way.
1701
1702 The widget should examine the list of attributes to apply to the
1703 preedit string. It has to understand at least the TextFormat and
1704 Cursor attributes and render them as specified.
1705 \endlist
1706
1707 \sa QInputContext
1708 */
1709
1710 /*!
1711 \enum QInputMethodEvent::AttributeType
1712
1713 \value TextFormat
1714 A QTextCharFormat for the part of the preedit string specified by
1715 start and length. value contains a QVariant of type QTextFormat
1716 specifying rendering of this part of the preedit string. There
1717 should be at most one format for every part of the preedit
1718 string. If several are specified for any character in the string the
1719 behaviour is undefined. A conforming implementation has to at least
1720 honor the backgroundColor, textColor and fontUnderline properties
1721 of the format.
1722
1723 \value Cursor If set, a cursor should be shown inside the preedit
1724 string at position start. The length variable determines whether
1725 the cursor is visible or not. If the length is 0 the cursor is
1726 invisible. If value is a QVariant of type QColor this color will
1727 be used for rendering the cursor, otherwise the color of the
1728 surrounding text will be used. There should be at most one Cursor
1729 attribute per event. If several are specified the behaviour is
1730 undefined.
1731
1732 \value Language
1733 The variant contains a QLocale object specifying the language of a
1734 certain part of the preedit string. There should be at most one
1735 language set for every part of the preedit string. If several are
1736 specified for any character in the string the behavior is undefined.
1737
1738 \value Ruby
1739 The ruby text for a part of the preedit string. There should be at
1740 most one ruby text set for every part of the preedit string. If
1741 several are specified for any character in the string the behaviour
1742 is undefined.
1743
1744 \value Selection
1745 If set, the edit cursor should be moved to the specified position
1746 in the editor text contents. In contrast with \c Cursor, this
1747 attribute does not work on the preedit text, but on the surrounding
1748 text. The cursor will be moved after the commit string has been
1749 committed, and the preedit string will be located at the new edit
1750 position.
1751 The start position specifies the new position and the length
1752 variable can be used to set a selection starting from that point.
1753 The value is unused.
1754
1755 \sa Attribute
1756 */
1757
1758 /*!
1759 \class QInputMethodEvent::Attribute
1760 \brief The QInputMethodEvent::Attribute class stores an input method attribute.
1761 */
1762
1763 /*!
1764 \fn QInputMethodEvent::Attribute::Attribute(AttributeType type, int start, int length, QVariant value)
1765
1766 Constructs an input method attribute. \a type specifies the type
1767 of attribute, \a start and \a length the position of the
1768 attribute, and \a value the value of the attribute.
1769 */
1770
1771 /*!
1772 Constructs an event of type QEvent::InputMethod. The
1773 attributes(), preeditString(), commitString(), replacementStart(),
1774 and replacementLength() are initialized to default values.
1775
1776 \sa setCommitString()
1777 */
QInputMethodEvent()1778 QInputMethodEvent::QInputMethodEvent()
1779 : QEvent(QEvent::InputMethod), replace_from(0), replace_length(0)
1780 {
1781 }
1782
1783 /*!
1784 Construcs an event of type QEvent::InputMethod. The
1785 preedit text is set to \a preeditText, the attributes to
1786 \a attributes.
1787
1788 The commitString(), replacementStart(), and replacementLength()
1789 values can be set using setCommitString().
1790
1791 \sa preeditString(), attributes()
1792 */
QInputMethodEvent(const QString & preeditText,const QList<Attribute> & attributes)1793 QInputMethodEvent::QInputMethodEvent(const QString &preeditText, const QList<Attribute> &attributes)
1794 : QEvent(QEvent::InputMethod), preedit(preeditText), attrs(attributes),
1795 replace_from(0), replace_length(0)
1796 {
1797 }
1798
1799 /*!
1800 Constructs a copy of \a other.
1801 */
QInputMethodEvent(const QInputMethodEvent & other)1802 QInputMethodEvent::QInputMethodEvent(const QInputMethodEvent &other)
1803 : QEvent(QEvent::InputMethod), preedit(other.preedit), attrs(other.attrs),
1804 commit(other.commit), replace_from(other.replace_from), replace_length(other.replace_length)
1805 {
1806 }
1807
1808 /*!
1809 Sets the commit string to \a commitString.
1810
1811 The commit string is the text that should get added to (or
1812 replace parts of) the text of the editor widget. It usually is a
1813 result of the input operations and has to be inserted to the
1814 widgets text directly before the preedit string.
1815
1816 If the commit string should replace parts of the of the text in
1817 the editor, \a replaceLength specifies the number of
1818 characters to be replaced. \a replaceFrom specifies the position
1819 at which characters are to be replaced relative from the start of
1820 the preedit string.
1821
1822 \sa commitString(), replacementStart(), replacementLength()
1823 */
setCommitString(const QString & commitString,int replaceFrom,int replaceLength)1824 void QInputMethodEvent::setCommitString(const QString &commitString, int replaceFrom, int replaceLength)
1825 {
1826 commit = commitString;
1827 replace_from = replaceFrom;
1828 replace_length = replaceLength;
1829 }
1830
1831 /*!
1832 \fn const QList<Attribute> &QInputMethodEvent::attributes() const
1833
1834 Returns the list of attributes passed to the QInputMethodEvent
1835 constructor. The attributes control the visual appearance of the
1836 preedit string (the visual appearance of text outside the preedit
1837 string is controlled by the widget only).
1838
1839 \sa preeditString(), Attribute
1840 */
1841
1842 /*!
1843 \fn const QString &QInputMethodEvent::preeditString() const
1844
1845 Returns the preedit text, i.e. the text before the user started
1846 editing it.
1847
1848 \sa commitString(), attributes()
1849 */
1850
1851 /*!
1852 \fn const QString &QInputMethodEvent::commitString() const
1853
1854 Returns the text that should get added to (or replace parts of)
1855 the text of the editor widget. It usually is a result of the
1856 input operations and has to be inserted to the widgets text
1857 directly before the preedit string.
1858
1859 \sa setCommitString(), preeditString(), replacementStart(), replacementLength()
1860 */
1861
1862 /*!
1863 \fn int QInputMethodEvent::replacementStart() const
1864
1865 Returns the position at which characters are to be replaced relative
1866 from the start of the preedit string.
1867
1868 \sa replacementLength(), setCommitString()
1869 */
1870
1871 /*!
1872 \fn int QInputMethodEvent::replacementLength() const
1873
1874 Returns the number of characters to be replaced in the preedit
1875 string.
1876
1877 \sa replacementStart(), setCommitString()
1878 */
1879
1880 #ifndef QT_NO_TABLETEVENT
1881
1882 /*!
1883 \class QTabletEvent
1884 \brief The QTabletEvent class contains parameters that describe a Tablet event.
1885
1886 \ingroup events
1887
1888 Tablet Events are generated from a Wacom tablet. Most of the time you will
1889 want to deal with events from the tablet as if they were events from a
1890 mouse; for example, you would retrieve the cursor position with x(), y(),
1891 pos(), globalX(), globalY(), and globalPos(). In some situations you may
1892 wish to retrieve the extra information provided by the tablet device
1893 driver; for example, you might want to do subpixeling with higher
1894 resolution coordinates or you may want to adjust color brightness based on
1895 pressure. QTabletEvent allows you to read the pressure(), the xTilt(), and
1896 yTilt(), as well as the type of device being used with device() (see
1897 \l{TabletDevice}). It can also give you the minimum and maximum values for
1898 each device's pressure and high resolution coordinates.
1899
1900 A tablet event contains a special accept flag that indicates whether the
1901 receiver wants the event. You should call QTabletEvent::accept() if you
1902 handle the tablet event; otherwise it will be sent to the parent widget.
1903 The exception are TabletEnterProximity and TabletLeaveProximity events,
1904 these are only sent to QApplication and don't check whether or not they are
1905 accepted.
1906
1907 The QWidget::setEnabled() function can be used to enable or
1908 disable mouse and keyboard events for a widget.
1909
1910 The event handler QWidget::tabletEvent() receives all three types of
1911 tablet events. Qt will first send a tabletEvent then, if it is not
1912 accepted, it will send a mouse event. This allows applications that
1913 don't utilize tablets to use a tablet like a mouse, while also
1914 enabling those who want to use both tablets and mouses differently.
1915
1916 \section1 Notes for X11 Users
1917
1918 Qt uses the following hard-coded names to identify tablet
1919 devices from the xorg.conf file on X11 (apart from IRIX):
1920 'stylus', 'pen', and 'eraser'. If the devices have other names,
1921 they will not be picked up Qt.
1922 */
1923
1924 /*!
1925 \enum QTabletEvent::TabletDevice
1926
1927 This enum defines what type of device is generating the event.
1928
1929 \value NoDevice No device, or an unknown device.
1930 \value Puck A Puck (a device that is similar to a flat mouse with
1931 a transparent circle with cross-hairs).
1932 \value Stylus A Stylus.
1933 \value Airbrush An airbrush
1934 \value FourDMouse A 4D Mouse.
1935 \value RotationStylus A special stylus that also knows about rotation
1936 (a 6D stylus). \since 4.1
1937 \omitvalue XFreeEraser
1938 */
1939
1940 /*!
1941 \enum QTabletEvent::PointerType
1942
1943 This enum defines what type of point is generating the event.
1944
1945 \value UnknownPointer An unknown device.
1946 \value Pen Tip end of a stylus-like device (the narrow end of the pen).
1947 \value Cursor Any puck-like device.
1948 \value Eraser Eraser end of a stylus-like device (the broad end of the pen).
1949
1950 \sa pointerType()
1951 */
1952
1953 /*!
1954 Construct a tablet event of the given \a type.
1955
1956 The \a pos parameter indicates where the event occurred in the
1957 widget; \a globalPos is the corresponding position in absolute
1958 coordinates. The \a hiResGlobalPos contains a high resolution
1959 measurement of the position.
1960
1961 \a pressure contains the pressure exerted on the \a device.
1962
1963 \a pointerType describes the type of pen that is being used.
1964
1965 \a xTilt and \a yTilt contain the device's degree of tilt from the
1966 x and y axes respectively.
1967
1968 \a keyState specifies which keyboard modifiers are pressed (e.g.,
1969 \key{Ctrl}).
1970
1971 The \a uniqueID parameter contains the unique ID for the current device.
1972
1973 The \a z parameter contains the coordinate of the device on the tablet, this
1974 is usually given by a wheel on 4D mouse. If the device does not support a
1975 Z-axis, pass zero here.
1976
1977 The \a tangentialPressure parameter contins the tangential pressure of an air
1978 brush. If the device does not support tangential pressure, pass 0 here.
1979
1980 \a rotation contains the device's rotation in degrees. 4D mice support
1981 rotation. If the device does not support rotation, pass 0 here.
1982
1983 \sa pos() globalPos() device() pressure() xTilt() yTilt() uniqueId(), rotation(), tangentialPressure(), z()
1984 */
1985
QTabletEvent(Type type,const QPoint & pos,const QPoint & globalPos,const QPointF & hiResGlobalPos,int device,int pointerType,qreal pressure,int xTilt,int yTilt,qreal tangentialPressure,qreal rotation,int z,Qt::KeyboardModifiers keyState,qint64 uniqueID)1986 QTabletEvent::QTabletEvent(Type type, const QPoint &pos, const QPoint &globalPos,
1987 const QPointF &hiResGlobalPos, int device, int pointerType,
1988 qreal pressure, int xTilt, int yTilt, qreal tangentialPressure,
1989 qreal rotation, int z, Qt::KeyboardModifiers keyState, qint64 uniqueID)
1990 : QInputEvent(type, keyState),
1991 mPos(pos),
1992 mGPos(globalPos),
1993 mHiResGlobalPos(hiResGlobalPos),
1994 mDev(device),
1995 mPointerType(pointerType),
1996 mXT(xTilt),
1997 mYT(yTilt),
1998 mZ(z),
1999 mPress(pressure),
2000 mTangential(tangentialPressure),
2001 mRot(rotation),
2002 mUnique(uniqueID),
2003 mExtra(0)
2004 {
2005 }
2006
2007 /*!
2008 \internal
2009 */
~QTabletEvent()2010 QTabletEvent::~QTabletEvent()
2011 {
2012 }
2013
2014 /*!
2015 \fn TabletDevices QTabletEvent::device() const
2016
2017 Returns the type of device that generated the event.
2018
2019 \sa TabletDevice
2020 */
2021
2022 /*!
2023 \fn PointerType QTabletEvent::pointerType() const
2024
2025 Returns the type of point that generated the event.
2026 */
2027
2028 /*!
2029 \fn qreal QTabletEvent::tangentialPressure() const
2030
2031 Returns the tangential pressure for the device. This is typically given by a finger
2032 wheel on an airbrush tool. The range is from -1.0 to 1.0. 0.0 indicates a
2033 neutral position. Current airbrushes can only move in the positive
2034 direction from the neutrual position. If the device does not support
2035 tangential pressure, this value is always 0.0.
2036
2037 \sa pressure()
2038 */
2039
2040 /*!
2041 \fn qreal QTabletEvent::rotation() const
2042
2043 Returns the rotation of the current device in degress. This is usually
2044 given by a 4D Mouse. If the device doesn't support rotation this value is
2045 always 0.0.
2046
2047 */
2048
2049 /*!
2050 \fn qreal QTabletEvent::pressure() const
2051
2052 Returns the pressure for the device. 0.0 indicates that the stylus is not
2053 on the tablet, 1.0 indicates the maximum amount of pressure for the stylus.
2054
2055 \sa tangentialPressure()
2056 */
2057
2058 /*!
2059 \fn int QTabletEvent::xTilt() const
2060
2061 Returns the angle between the device (a pen, for example) and the
2062 perpendicular in the direction of the x axis.
2063 Positive values are towards the tablet's physical right. The angle
2064 is in the range -60 to +60 degrees.
2065
2066 \img qtabletevent-tilt.png
2067
2068 \sa yTilt()
2069 */
2070
2071 /*!
2072 \fn int QTabletEvent::yTilt() const
2073
2074 Returns the angle between the device (a pen, for example) and the
2075 perpendicular in the direction of the y axis.
2076 Positive values are towards the bottom of the tablet. The angle is
2077 within the range -60 to +60 degrees.
2078
2079 \sa xTilt()
2080 */
2081
2082 /*!
2083 \fn const QPoint &QTabletEvent::pos() const
2084
2085 Returns the position of the device, relative to the widget that
2086 received the event.
2087
2088 If you move widgets around in response to mouse events, use
2089 globalPos() instead of this function.
2090
2091 \sa x() y() globalPos()
2092 */
2093
2094 /*!
2095 \fn int QTabletEvent::x() const
2096
2097 Returns the x position of the device, relative to the widget that
2098 received the event.
2099
2100 \sa y() pos()
2101 */
2102
2103 /*!
2104 \fn int QTabletEvent::y() const
2105
2106 Returns the y position of the device, relative to the widget that
2107 received the event.
2108
2109 \sa x() pos()
2110 */
2111
2112 /*!
2113 \fn int QTabletEvent::z() const
2114
2115 Returns the z position of the device. Typically this is represented by a
2116 wheel on a 4D Mouse. If the device does not support a Z-axis, this value is
2117 always zero. This is \bold not the same as pressure.
2118
2119 \sa pressure()
2120 */
2121
2122 /*!
2123 \fn const QPoint &QTabletEvent::globalPos() const
2124
2125 Returns the global position of the device \e{at the time of the
2126 event}. This is important on asynchronous windows systems like X11;
2127 whenever you move your widgets around in response to mouse events,
2128 globalPos() can differ significantly from the current position
2129 QCursor::pos().
2130
2131 \sa globalX() globalY() hiResGlobalPos()
2132 */
2133
2134 /*!
2135 \fn int QTabletEvent::globalX() const
2136
2137 Returns the global x position of the mouse pointer at the time of
2138 the event.
2139
2140 \sa globalY() globalPos() hiResGlobalX()
2141 */
2142
2143 /*!
2144 \fn int QTabletEvent::globalY() const
2145
2146 Returns the global y position of the tablet device at the time of
2147 the event.
2148
2149 \sa globalX() globalPos() hiResGlobalY()
2150 */
2151
2152 /*!
2153 \fn qint64 QTabletEvent::uniqueId() const
2154
2155 Returns a unique ID for the current device, making it possible
2156 to differentiate between multiple devices being used at the same
2157 time on the tablet.
2158
2159 Support of this feature is dependent on the tablet.
2160
2161 Values for the same device may vary from OS to OS.
2162
2163 Later versions of the Wacom driver for Linux will now report
2164 the ID information. If you have a tablet that supports unique ID
2165 and are not getting the information on Linux, consider upgrading
2166 your driver.
2167
2168 As of Qt 4.2, the unique ID is the same regardless of the orientation
2169 of the pen. Earlier versions would report a different value when using
2170 the eraser-end versus the pen-end of the stylus on some OS's.
2171
2172 \sa pointerType()
2173 */
2174
2175 /*!
2176 \fn const QPointF &QTabletEvent::hiResGlobalPos() const
2177
2178 The high precision coordinates delivered from the tablet expressed.
2179 Sub pixeling information is in the fractional part of the QPointF.
2180
2181 \sa globalPos() hiResGlobalX() hiResGlobalY()
2182 */
2183
2184 /*!
2185 \fn qreal &QTabletEvent::hiResGlobalX() const
2186
2187 The high precision x position of the tablet device.
2188 */
2189
2190 /*!
2191 \fn qreal &QTabletEvent::hiResGlobalY() const
2192
2193 The high precision y position of the tablet device.
2194 */
2195
2196 #endif // QT_NO_TABLETEVENT
2197
2198 #ifndef QT_NO_DRAGANDDROP
2199 /*!
2200 Creates a QDragMoveEvent of the required \a type indicating
2201 that the mouse is at position \a pos given within a widget.
2202
2203 The mouse and keyboard states are specified by \a buttons and
2204 \a modifiers, and the \a actions describe the types of drag
2205 and drop operation that are possible.
2206 The drag data is passed as MIME-encoded information in \a data.
2207
2208 \warning Do not attempt to create a QDragMoveEvent yourself.
2209 These objects rely on Qt's internal state.
2210 */
QDragMoveEvent(const QPoint & pos,Qt::DropActions actions,const QMimeData * data,Qt::MouseButtons buttons,Qt::KeyboardModifiers modifiers,Type type)2211 QDragMoveEvent::QDragMoveEvent(const QPoint& pos, Qt::DropActions actions, const QMimeData *data,
2212 Qt::MouseButtons buttons, Qt::KeyboardModifiers modifiers, Type type)
2213 : QDropEvent(pos, actions, data, buttons, modifiers, type)
2214 , rect(pos, QSize(1, 1))
2215 {}
2216
2217 /*!
2218 Destroys the event.
2219 */
~QDragMoveEvent()2220 QDragMoveEvent::~QDragMoveEvent()
2221 {
2222 }
2223
2224 /*!
2225 \fn void QDragMoveEvent::accept(bool y)
2226
2227 Calls setAccepted(\a y) instead.
2228 */
2229
2230 /*!
2231 \fn void QDragMoveEvent::accept(const QRect &rectangle)
2232
2233 The same as accept(), but also notifies that future moves will
2234 also be acceptable if they remain within the \a rectangle
2235 given on the widget. This can improve performance, but may
2236 also be ignored by the underlying system.
2237
2238 If the rectangle is empty, drag move events will be sent
2239 continuously. This is useful if the source is scrolling in a
2240 timer event.
2241 */
2242
2243 /*!
2244 \fn void QDragMoveEvent::accept()
2245
2246 \overload
2247
2248 Calls QDropEvent::accept().
2249 */
2250
2251 /*!
2252 \fn void QDragMoveEvent::ignore()
2253
2254 \overload
2255
2256 Calls QDropEvent::ignore().
2257 */
2258
2259 /*!
2260 \fn void QDragMoveEvent::ignore(const QRect &rectangle)
2261
2262 The opposite of the accept(const QRect&) function.
2263 Moves within the \a rectangle are not acceptable, and will be
2264 ignored.
2265 */
2266
2267 /*!
2268 \fn QRect QDragMoveEvent::answerRect() const
2269
2270 Returns the rectangle in the widget where the drop will occur if accepted.
2271 You can use this information to restrict drops to certain places on the
2272 widget.
2273 */
2274
2275
2276 /*!
2277 \class QDropEvent
2278 \ingroup events
2279 \ingroup draganddrop
2280
2281 \brief The QDropEvent class provides an event which is sent when a
2282 drag and drop action is completed.
2283
2284 When a widget \l{QWidget::setAcceptDrops()}{accepts drop events}, it will
2285 receive this event if it has accepted the most recent QDragEnterEvent or
2286 QDragMoveEvent sent to it.
2287
2288 The drop event contains a proposed action, available from proposedAction(), for
2289 the widget to either accept or ignore. If the action can be handled by the
2290 widget, you should call the acceptProposedAction() function. Since the
2291 proposed action can be a combination of \l Qt::DropAction values, it may be
2292 useful to either select one of these values as a default action or ask
2293 the user to select their preferred action.
2294
2295 If the proposed drop action is not suitable, perhaps because your custom
2296 widget does not support that action, you can replace it with any of the
2297 \l{possibleActions()}{possible drop actions} by calling setDropAction()
2298 with your preferred action. If you set a value that is not present in the
2299 bitwise OR combination of values returned by possibleActions(), the default
2300 copy action will be used. Once a replacement drop action has been set, call
2301 accept() instead of acceptProposedAction() to complete the drop operation.
2302
2303 The mimeData() function provides the data dropped on the widget in a QMimeData
2304 object. This contains information about the MIME type of the data in addition to
2305 the data itself.
2306
2307 \sa QMimeData, QDrag, {Drag and Drop}
2308 */
2309
2310 /*!
2311 \fn const QMimeData *QDropEvent::mimeData() const
2312
2313 Returns the data that was dropped on the widget and its associated MIME
2314 type information.
2315 */
2316
2317 /*!
2318 Constructs a drop event of a certain \a type corresponding to a
2319 drop at the point specified by \a pos in the destination widget's
2320 coordinate system.
2321
2322 The \a actions indicate which types of drag and drop operation can
2323 be performed, and the drag data is stored as MIME-encoded data in \a data.
2324
2325 The states of the mouse buttons and keyboard modifiers at the time of
2326 the drop are specified by \a buttons and \a modifiers.
2327 */ // ### pos is in which coordinate system?
QDropEvent(const QPoint & pos,Qt::DropActions actions,const QMimeData * data,Qt::MouseButtons buttons,Qt::KeyboardModifiers modifiers,Type type)2328 QDropEvent::QDropEvent(const QPoint& pos, Qt::DropActions actions, const QMimeData *data,
2329 Qt::MouseButtons buttons, Qt::KeyboardModifiers modifiers, Type type)
2330 : QEvent(type), p(pos), mouseState(buttons),
2331 modState(modifiers), act(actions),
2332 mdata(data)
2333 {
2334 default_action = QDragManager::self()->defaultAction(act, modifiers);
2335 drop_action = default_action;
2336 ignore();
2337 }
2338
2339 /*! \internal */
~QDropEvent()2340 QDropEvent::~QDropEvent()
2341 {
2342 }
2343
2344 /*!
2345 \compat
2346 Returns a byte array containing the drag's data, in \a format.
2347
2348 data() normally needs to get the data from the drag source, which
2349 is potentially very slow, so it's advisable to call this function
2350 only if you're sure that you will need the data in that
2351 particular \a format.
2352
2353 The resulting data will have a size of 0 if the format was not
2354 available.
2355
2356 \sa format() QByteArray::size()
2357 */
2358
encodedData(const char * format) const2359 QByteArray QDropEvent::encodedData(const char *format) const
2360 {
2361 return mdata->data(QLatin1String(format));
2362 }
2363
2364 /*!
2365 \compat
2366 Returns a string describing one of the available data types for
2367 this drag. Common examples are "text/plain" and "image/gif".
2368 If \a n is less than zero or greater than the number of available
2369 data types, format() returns 0.
2370
2371 This function is provided mainly for debugging. Most drop targets
2372 will use provides().
2373
2374 \sa data() provides()
2375 */
2376
format(int n) const2377 const char* QDropEvent::format(int n) const
2378 {
2379 if (fmts.isEmpty()) {
2380 QStringList formats = mdata->formats();
2381 for (int i = 0; i < formats.size(); ++i)
2382 fmts.append(formats.at(i).toLatin1());
2383 }
2384 if (n < 0 || n >= fmts.size())
2385 return 0;
2386 return fmts.at(n).constData();
2387 }
2388
2389 /*!
2390 \compat
2391 Returns true if this event provides format \a mimeType; otherwise
2392 returns false.
2393
2394 \sa data()
2395 */
2396
provides(const char * mimeType) const2397 bool QDropEvent::provides(const char *mimeType) const
2398 {
2399 return mdata->formats().contains(QLatin1String(mimeType));
2400 }
2401
2402 /*!
2403 If the source of the drag operation is a widget in this
2404 application, this function returns that source; otherwise it
2405 returns 0. The source of the operation is the first parameter to
2406 the QDrag object used instantiate the drag.
2407
2408 This is useful if your widget needs special behavior when dragging
2409 to itself.
2410
2411 \sa QDrag::QDrag()
2412 */
source() const2413 QWidget* QDropEvent::source() const
2414 {
2415 QDragManager *manager = QDragManager::self();
2416 return manager ? manager->source() : 0;
2417 }
2418
2419
setDropAction(Qt::DropAction action)2420 void QDropEvent::setDropAction(Qt::DropAction action)
2421 {
2422 if (!(action & act) && action != Qt::IgnoreAction)
2423 action = default_action;
2424 drop_action = action;
2425 }
2426
2427 /*!
2428 \fn const QPoint& QDropEvent::pos() const
2429
2430 Returns the position where the drop was made.
2431 */
2432
2433 /*!
2434 \fn Qt::MouseButtons QDropEvent::mouseButtons() const
2435
2436 Returns the mouse buttons that are pressed..
2437 */
2438
2439 /*!
2440 \fn Qt::KeyboardModifiers QDropEvent::keyboardModifiers() const
2441
2442 Returns the modifier keys that are pressed.
2443 */
2444
2445 /*!
2446 \fn void QDropEvent::accept()
2447 \internal
2448 */
2449
2450 /*!
2451 \fn void QDropEvent::accept(bool accept)
2452
2453 Call setAccepted(\a accept) instead.
2454 */
2455
2456 /*!
2457 \fn void QDropEvent::acceptAction(bool accept = true)
2458
2459 Call this to indicate that the action described by action() is
2460 accepted (i.e. if \a accept is true, which is the default), not merely
2461 the default copy action. If you call acceptAction(true), there is
2462 no need to also call accept(true).
2463 */
2464
2465 /*!
2466 \enum QDropEvent::Action
2467 \compat
2468
2469 When a drag and drop action is completed, the target is expected
2470 to perform an action on the data provided by the source. This
2471 will be one of the following:
2472
2473 \value Copy The default action. The source simply uses the data
2474 provided in the operation.
2475 \value Link The source should somehow create a link to the
2476 location specified by the data.
2477 \value Move The source should somehow move the object from the
2478 location specified by the data to a new location.
2479 \value Private The target has special knowledge of the MIME type,
2480 which the source should respond to in a similar way to
2481 a Copy.
2482 \value UserAction The source and target can co-operate using
2483 special actions. This feature is not currently
2484 supported.
2485
2486 The Link and Move actions only makes sense if the data is a
2487 reference, for example, text/uri-list file lists (see QUriDrag).
2488 */
2489
2490 /*!
2491 \fn void QDropEvent::setDropAction(Qt::DropAction action)
2492
2493 Sets the \a action to be performed on the data by the target.
2494 Use this to override the \l{proposedAction()}{proposed action}
2495 with one of the \l{possibleActions()}{possible actions}.
2496
2497 If you set a drop action that is not one of the possible actions, the
2498 drag and drop operation will default to a copy operation.
2499
2500 Once you have supplied a replacement drop action, call accept()
2501 instead of acceptProposedAction().
2502
2503 \sa dropAction()
2504 */
2505
2506 /*!
2507 \fn Qt::DropAction QDropEvent::dropAction() const
2508
2509 Returns the action to be performed on the data by the target. This may be
2510 different from the action supplied in proposedAction() if you have called
2511 setDropAction() to explicitly choose a drop action.
2512
2513 \sa setDropAction()
2514 */
2515
2516 /*!
2517 \fn Qt::DropActions QDropEvent::possibleActions() const
2518
2519 Returns an OR-combination of possible drop actions.
2520
2521 \sa dropAction()
2522 */
2523
2524 /*!
2525 \fn Qt::DropAction QDropEvent::proposedAction() const
2526
2527 Returns the proposed drop action.
2528
2529 \sa dropAction()
2530 */
2531
2532 /*!
2533 \fn void QDropEvent::acceptProposedAction()
2534
2535 Sets the drop action to be the proposed action.
2536
2537 \sa setDropAction(), proposedAction(), {QEvent::accept()}{accept()}
2538 */
2539
2540 #ifdef QT3_SUPPORT
2541 /*!
2542 Use dropAction() instead.
2543
2544 The table below shows the correspondance between the return type
2545 of action() and the return type of dropAction().
2546
2547 \table
2548 \header \i Old enum value \i New enum value
2549 \row \i QDropEvent::Copy \i Qt::CopyAction
2550 \row \i QDropEvent::Move \i Qt::MoveAction
2551 \row \i QDropEvent::Link \i Qt::LinkAction
2552 \row \i other \i Qt::CopyAction
2553 \endtable
2554 */
2555
action() const2556 QT3_SUPPORT QDropEvent::Action QDropEvent::action() const
2557 {
2558 switch(drop_action) {
2559 case Qt::CopyAction:
2560 return Copy;
2561 case Qt::MoveAction:
2562 return Move;
2563 case Qt::LinkAction:
2564 return Link;
2565 default:
2566 return Copy;
2567 }
2568 }
2569 #endif
2570
2571 /*!
2572 \fn void QDropEvent::setPoint(const QPoint &point)
2573 \compat
2574
2575 Sets the drop to happen at the given \a point. You do not normally
2576 need to use this as it will be set internally before your widget
2577 receives the drop event.
2578 */ // ### here too - what coordinate system?
2579
2580
2581 /*!
2582 \class QDragEnterEvent
2583 \brief The QDragEnterEvent class provides an event which is sent
2584 to a widget when a drag and drop action enters it.
2585
2586 \ingroup events
2587 \ingroup draganddrop
2588
2589 A widget must accept this event in order to receive the \l
2590 {QDragMoveEvent}{drag move events} that are sent while the drag
2591 and drop action is in progress. The drag enter event is always
2592 immediately followed by a drag move event.
2593
2594 QDragEnterEvent inherits most of its functionality from
2595 QDragMoveEvent, which in turn inherits most of its functionality
2596 from QDropEvent.
2597
2598 \sa QDragLeaveEvent, QDragMoveEvent, QDropEvent
2599 */
2600
2601 /*!
2602 Constructs a QDragEnterEvent that represents a drag entering a
2603 widget at the given \a point with mouse and keyboard states specified by
2604 \a buttons and \a modifiers.
2605
2606 The drag data is passed as MIME-encoded information in \a data, and the
2607 specified \a actions describe the possible types of drag and drop
2608 operation that can be performed.
2609
2610 \warning Do not create a QDragEnterEvent yourself since these
2611 objects rely on Qt's internal state.
2612 */
QDragEnterEvent(const QPoint & point,Qt::DropActions actions,const QMimeData * data,Qt::MouseButtons buttons,Qt::KeyboardModifiers modifiers)2613 QDragEnterEvent::QDragEnterEvent(const QPoint& point, Qt::DropActions actions, const QMimeData *data,
2614 Qt::MouseButtons buttons, Qt::KeyboardModifiers modifiers)
2615 : QDragMoveEvent(point, actions, data, buttons, modifiers, DragEnter)
2616 {}
2617
2618 /*! \internal
2619 */
~QDragEnterEvent()2620 QDragEnterEvent::~QDragEnterEvent()
2621 {
2622 }
2623
2624 /*!
2625 Constructs a drag response event containing the \a accepted value,
2626 indicating whether the drag and drop operation was accepted by the
2627 recipient.
2628 */
QDragResponseEvent(bool accepted)2629 QDragResponseEvent::QDragResponseEvent(bool accepted)
2630 : QEvent(DragResponse), a(accepted)
2631 {}
2632
2633 /*! \internal
2634 */
~QDragResponseEvent()2635 QDragResponseEvent::~QDragResponseEvent()
2636 {
2637 }
2638
2639 /*!
2640 \class QDragMoveEvent
2641 \brief The QDragMoveEvent class provides an event which is sent while a drag and drop action is in progress.
2642
2643 \ingroup events
2644 \ingroup draganddrop
2645
2646 A widget will receive drag move events repeatedly while the drag
2647 is within its boundaries, if it accepts
2648 \l{QWidget::setAcceptDrops()}{drop events} and \l
2649 {QWidget::dragEnterEvent()}{enter events}. The widget should
2650 examine the event to see what kind of data it
2651 \l{QDragMoveEvent::provides()}{provides}, and call the accept()
2652 function to accept the drop if appropriate.
2653
2654 The rectangle supplied by the answerRect() function can be used to restrict
2655 drops to certain parts of the widget. For example, we can check whether the
2656 rectangle intersects with the geometry of a certain child widget and only
2657 call \l{QDropEvent::acceptProposedAction()}{acceptProposedAction()} if that
2658 is the case.
2659
2660 Note that this class inherits most of its functionality from
2661 QDropEvent.
2662
2663 \sa QDragEnterEvent, QDragLeaveEvent, QDropEvent
2664 */
2665
2666 /*!
2667 \class QDragLeaveEvent
2668 \brief The QDragLeaveEvent class provides an event that is sent to a widget when a drag and drop action leaves it.
2669
2670 \ingroup events
2671 \ingroup draganddrop
2672
2673 This event is always preceded by a QDragEnterEvent and a series
2674 of \l{QDragMoveEvent}s. It is not sent if a QDropEvent is sent
2675 instead.
2676
2677 \sa QDragEnterEvent, QDragMoveEvent, QDropEvent
2678 */
2679
2680 /*!
2681 Constructs a QDragLeaveEvent.
2682
2683 \warning Do not create a QDragLeaveEvent yourself since these
2684 objects rely on Qt's internal state.
2685 */
QDragLeaveEvent()2686 QDragLeaveEvent::QDragLeaveEvent()
2687 : QEvent(DragLeave)
2688 {}
2689
2690 /*! \internal
2691 */
~QDragLeaveEvent()2692 QDragLeaveEvent::~QDragLeaveEvent()
2693 {
2694 }
2695 #endif // QT_NO_DRAGANDDROP
2696
2697 /*!
2698 \class QHelpEvent
2699 \brief The QHelpEvent class provides an event that is used to request helpful information
2700 about a particular point in a widget.
2701
2702 \ingroup events
2703 \ingroup helpsystem
2704
2705 This event can be intercepted in applications to provide tooltips
2706 or "What's This?" help for custom widgets. The type() can be
2707 either QEvent::ToolTip or QEvent::WhatsThis.
2708
2709 \sa QToolTip, QWhatsThis, QStatusTipEvent, QWhatsThisClickedEvent
2710 */
2711
2712 /*!
2713 Constructs a help event with the given \a type corresponding to the
2714 widget-relative position specified by \a pos and the global position
2715 specified by \a globalPos.
2716
2717 \a type must be either QEvent::ToolTip or QEvent::WhatsThis.
2718
2719 \sa pos(), globalPos()
2720 */
QHelpEvent(Type type,const QPoint & pos,const QPoint & globalPos)2721 QHelpEvent::QHelpEvent(Type type, const QPoint &pos, const QPoint &globalPos)
2722 : QEvent(type), p(pos), gp(globalPos)
2723 {}
2724
2725 /*!
2726 \fn int QHelpEvent::x() const
2727
2728 Same as pos().x().
2729
2730 \sa y(), pos(), globalPos()
2731 */
2732
2733 /*!
2734 \fn int QHelpEvent::y() const
2735
2736 Same as pos().y().
2737
2738 \sa x(), pos(), globalPos()
2739 */
2740
2741 /*!
2742 \fn int QHelpEvent::globalX() const
2743
2744 Same as globalPos().x().
2745
2746 \sa x(), globalY(), globalPos()
2747 */
2748
2749 /*!
2750 \fn int QHelpEvent::globalY() const
2751
2752 Same as globalPos().y().
2753
2754 \sa y(), globalX(), globalPos()
2755 */
2756
2757 /*!
2758 \fn const QPoint &QHelpEvent::pos() const
2759
2760 Returns the mouse cursor position when the event was generated,
2761 relative to the widget to which the event is dispatched.
2762
2763 \sa globalPos(), x(), y()
2764 */
2765
2766 /*!
2767 \fn const QPoint &QHelpEvent::globalPos() const
2768
2769 Returns the mouse cursor position when the event was generated
2770 in global coordinates.
2771
2772 \sa pos(), globalX(), globalY()
2773 */
2774
2775 /*! \internal
2776 */
~QHelpEvent()2777 QHelpEvent::~QHelpEvent()
2778 {
2779 }
2780
2781 #ifndef QT_NO_STATUSTIP
2782
2783 /*!
2784 \class QStatusTipEvent
2785 \brief The QStatusTipEvent class provides an event that is used to show messages in a status bar.
2786
2787 \ingroup events
2788 \ingroup helpsystem
2789
2790 Status tips can be set on a widget using the
2791 QWidget::setStatusTip() function. They are shown in the status
2792 bar when the mouse cursor enters the widget. For example:
2793
2794 \table 100%
2795 \row
2796 \o
2797 \snippet doc/src/snippets/qstatustipevent/main.cpp 1
2798 \dots
2799 \snippet doc/src/snippets/qstatustipevent/main.cpp 3
2800 \o
2801 \image qstatustipevent-widget.png Widget with status tip.
2802 \endtable
2803
2804 Status tips can also be set on actions using the
2805 QAction::setStatusTip() function:
2806
2807 \table 100%
2808 \row
2809 \o
2810 \snippet doc/src/snippets/qstatustipevent/main.cpp 0
2811 \snippet doc/src/snippets/qstatustipevent/main.cpp 2
2812 \dots
2813 \snippet doc/src/snippets/qstatustipevent/main.cpp 3
2814 \o
2815 \image qstatustipevent-action.png Action with status tip.
2816 \endtable
2817
2818 Finally, status tips are supported for the item view classes
2819 through the Qt::StatusTipRole enum value.
2820
2821 \sa QStatusBar, QHelpEvent, QWhatsThisClickedEvent
2822 */
2823
2824 /*!
2825 Constructs a status tip event with the text specified by \a tip.
2826
2827 \sa tip()
2828 */
QStatusTipEvent(const QString & tip)2829 QStatusTipEvent::QStatusTipEvent(const QString &tip)
2830 : QEvent(StatusTip), s(tip)
2831 {}
2832
2833 /*! \internal
2834 */
~QStatusTipEvent()2835 QStatusTipEvent::~QStatusTipEvent()
2836 {
2837 }
2838
2839 /*!
2840 \fn QString QStatusTipEvent::tip() const
2841
2842 Returns the message to show in the status bar.
2843
2844 \sa QStatusBar::showMessage()
2845 */
2846
2847 #endif // QT_NO_STATUSTIP
2848
2849 #ifndef QT_NO_WHATSTHIS
2850
2851 /*!
2852 \class QWhatsThisClickedEvent
2853 \brief The QWhatsThisClickedEvent class provides an event that
2854 can be used to handle hyperlinks in a "What's This?" text.
2855
2856 \ingroup events
2857 \ingroup helpsystem
2858
2859 \sa QWhatsThis, QHelpEvent, QStatusTipEvent
2860 */
2861
2862 /*!
2863 Constructs an event containing a URL specified by \a href when a link
2864 is clicked in a "What's This?" message.
2865
2866 \sa href()
2867 */
QWhatsThisClickedEvent(const QString & href)2868 QWhatsThisClickedEvent::QWhatsThisClickedEvent(const QString &href)
2869 : QEvent(WhatsThisClicked), s(href)
2870 {}
2871
2872 /*! \internal
2873 */
~QWhatsThisClickedEvent()2874 QWhatsThisClickedEvent::~QWhatsThisClickedEvent()
2875 {
2876 }
2877
2878 /*!
2879 \fn QString QWhatsThisClickedEvent::href() const
2880
2881 Returns the URL that was clicked by the user in the "What's
2882 This?" text.
2883 */
2884
2885 #endif // QT_NO_WHATSTHIS
2886
2887 #ifndef QT_NO_ACTION
2888
2889 /*!
2890 \class QActionEvent
2891 \brief The QActionEvent class provides an event that is generated
2892 when a QAction is added, removed, or changed.
2893
2894 \ingroup events
2895
2896 Actions can be added to widgets using QWidget::addAction(). This
2897 generates an \l ActionAdded event, which you can handle to provide
2898 custom behavior. For example, QToolBar reimplements
2899 QWidget::actionEvent() to create \l{QToolButton}s for the
2900 actions.
2901
2902 \sa QAction, QWidget::addAction(), QWidget::removeAction(), QWidget::actions()
2903 */
2904
2905 /*!
2906 Constructs an action event. The \a type can be \l ActionChanged,
2907 \l ActionAdded, or \l ActionRemoved.
2908
2909 \a action is the action that is changed, added, or removed. If \a
2910 type is ActionAdded, the action is to be inserted before the
2911 action \a before. If \a before is 0, the action is appended.
2912 */
QActionEvent(int type,QAction * action,QAction * before)2913 QActionEvent::QActionEvent(int type, QAction *action, QAction *before)
2914 : QEvent(static_cast<QEvent::Type>(type)), act(action), bef(before)
2915 {}
2916
2917 /*! \internal
2918 */
~QActionEvent()2919 QActionEvent::~QActionEvent()
2920 {
2921 }
2922
2923 /*!
2924 \fn QAction *QActionEvent::action() const
2925
2926 Returns the action that is changed, added, or removed.
2927
2928 \sa before()
2929 */
2930
2931 /*!
2932 \fn QAction *QActionEvent::before() const
2933
2934 If type() is \l ActionAdded, returns the action that should
2935 appear before action(). If this function returns 0, the action
2936 should be appended to already existing actions on the same
2937 widget.
2938
2939 \sa action(), QWidget::actions()
2940 */
2941
2942 #endif // QT_NO_ACTION
2943
2944 /*!
2945 \class QHideEvent
2946 \brief The QHideEvent class provides an event which is sent after a widget is hidden.
2947
2948 \ingroup events
2949
2950 This event is sent just before QWidget::hide() returns, and also
2951 when a top-level window has been hidden (iconified) by the user.
2952
2953 If spontaneous() is true, the event originated outside the
2954 application. In this case, the user hid the window using the
2955 window manager controls, either by iconifying the window or by
2956 switching to another virtual desktop where the window isn't
2957 visible. The window will become hidden but not withdrawn. If the
2958 window was iconified, QWidget::isMinimized() returns true.
2959
2960 \sa QShowEvent
2961 */
2962
2963 /*!
2964 Constructs a QHideEvent.
2965 */
QHideEvent()2966 QHideEvent::QHideEvent()
2967 : QEvent(Hide)
2968 {}
2969
2970 /*! \internal
2971 */
~QHideEvent()2972 QHideEvent::~QHideEvent()
2973 {
2974 }
2975
2976 /*!
2977 \class QShowEvent
2978 \brief The QShowEvent class provides an event that is sent when a widget is shown.
2979
2980 \ingroup events
2981
2982 There are two kinds of show events: show events caused by the
2983 window system (spontaneous), and internal show events. Spontaneous (QEvent::spontaneous())
2984 show events are sent just after the window system shows the
2985 window; they are also sent when a top-level window is redisplayed
2986 after being iconified. Internal show events are delivered just
2987 before the widget becomes visible.
2988
2989 \sa QHideEvent
2990 */
2991
2992 /*!
2993 Constructs a QShowEvent.
2994 */
QShowEvent()2995 QShowEvent::QShowEvent()
2996 : QEvent(Show)
2997 {}
2998
2999 /*! \internal
3000 */
~QShowEvent()3001 QShowEvent::~QShowEvent()
3002 {
3003 }
3004
3005 /*!
3006 \fn QByteArray QDropEvent::data(const char* f) const
3007
3008 \obsolete
3009
3010 The encoded data is in \a f.
3011 Use QDropEvent::encodedData().
3012 */
3013
3014 /*!
3015 \class QFileOpenEvent
3016 \brief The QFileOpenEvent class provides an event that will be
3017 sent when there is a request to open a file or a URL.
3018
3019 \ingroup events
3020
3021 File open events will be sent to the QApplication::instance()
3022 when the operating system requests that a file or URL should be opened.
3023 This is a high-level event that can be caused by different user actions
3024 depending on the user's desktop environment; for example, double
3025 clicking on an file icon in the Finder on Mac OS X.
3026
3027 This event is only used to notify the application of a request.
3028 It may be safely ignored.
3029
3030 \note This class is currently supported for Mac OS X and Symbian only.
3031 */
3032
~QFileOpenEventPrivate()3033 QFileOpenEventPrivate::~QFileOpenEventPrivate()
3034 {
3035 #ifdef Q_OS_SYMBIAN
3036 file.Close();
3037 #endif
3038 }
3039
3040 /*!
3041 \internal
3042
3043 Constructs a file open event for the given \a file.
3044 */
QFileOpenEvent(const QString & file)3045 QFileOpenEvent::QFileOpenEvent(const QString &file)
3046 : QEvent(FileOpen), f(file)
3047 {
3048 d = reinterpret_cast<QEventPrivate *>(new QFileOpenEventPrivate(QUrl::fromLocalFile(file)));
3049 }
3050
3051 /*!
3052 \internal
3053
3054 Constructs a file open event for the given \a url.
3055 */
QFileOpenEvent(const QUrl & url)3056 QFileOpenEvent::QFileOpenEvent(const QUrl &url)
3057 : QEvent(FileOpen)
3058 {
3059 d = reinterpret_cast<QEventPrivate *>(new QFileOpenEventPrivate(url));
3060 f = url.toLocalFile();
3061 }
3062
3063 #ifdef Q_OS_SYMBIAN
3064 /*! \internal
3065 */
QFileOpenEvent(const RFile & fileHandle)3066 QFileOpenEvent::QFileOpenEvent(const RFile &fileHandle)
3067 : QEvent(FileOpen)
3068 {
3069 TFileName fullName;
3070 fileHandle.FullName(fullName);
3071 f = qt_TDesC2QString(fullName);
3072 QScopedPointer<QFileOpenEventPrivate> priv(new QFileOpenEventPrivate(QUrl::fromLocalFile(f)));
3073 // Duplicate here allows the file handle to be valid after S60 app construction is complete.
3074 qt_symbian_throwIfError(priv->file.Duplicate(fileHandle));
3075 d = reinterpret_cast<QEventPrivate *>(priv.take());
3076 }
3077 #endif
3078
3079 /*! \internal
3080 */
~QFileOpenEvent()3081 QFileOpenEvent::~QFileOpenEvent()
3082 {
3083 delete reinterpret_cast<QFileOpenEventPrivate *>(d);
3084 }
3085
3086 /*!
3087 \fn QString QFileOpenEvent::file() const
3088
3089 Returns the file that is being opened.
3090 */
3091
3092 /*!
3093 \fn QUrl QFileOpenEvent::url() const
3094
3095 Returns the url that is being opened.
3096
3097 \since 4.6
3098 */
url() const3099 QUrl QFileOpenEvent::url() const
3100 {
3101 return reinterpret_cast<const QFileOpenEventPrivate *>(d)->url;
3102 }
3103
3104 /*!
3105 \fn bool QFileOpenEvent::openFile(QFile &file, QIODevice::OpenMode flags) const
3106
3107 Opens a QFile on the \a file referenced by this event in the mode specified
3108 by \a flags. Returns true if successful; otherwise returns false.
3109
3110 This is necessary as some files cannot be opened by name, but require specific
3111 information stored in this event.
3112 For example, if this QFileOpenEvent contains a request to open a Symbian data caged file,
3113 the QFile could only be opened from the Symbian RFile used in the construction of this event.
3114
3115 \since 4.8
3116 */
openFile(QFile & file,QIODevice::OpenMode flags) const3117 bool QFileOpenEvent::openFile(QFile &file, QIODevice::OpenMode flags) const
3118 {
3119 file.setFileName(f);
3120 #ifdef Q_OS_SYMBIAN
3121 const QFileOpenEventPrivate *priv = reinterpret_cast<const QFileOpenEventPrivate *>(d);
3122 if (priv->file.SubSessionHandle()) {
3123 RFile dup;
3124 // Duplicate here means that the opened QFile will continue to be valid beyond the lifetime of this QFileOpenEvent.
3125 // It also allows openFile to be used in threads other than the thread in which the QFileOpenEvent was created.
3126 if (dup.Duplicate(priv->file) == KErrNone) {
3127 QScopedPointer<RFile, QScopedPointerRCloser<RFile> > dupCloser(&dup);
3128 bool open = file.open(dup, flags, QFile::AutoCloseHandle);
3129 dupCloser.take();
3130 return open;
3131 }
3132 }
3133 #endif
3134 return file.open(flags);
3135 }
3136
3137 #ifndef QT_NO_TOOLBAR
3138 /*!
3139 \internal
3140 \class QToolBarChangeEvent
3141 \brief The QToolBarChangeEvent class provides an event that is
3142 sent whenever a the toolbar button is clicked on Mac OS X.
3143
3144 \ingroup events
3145
3146 The QToolBarChangeEvent is sent when the toolbar button is clicked. On Mac
3147 OS X, this is the long oblong button on the right side of the window
3148 title bar. The default implementation is to toggle the appearance (hidden or
3149 shown) of the associated toolbars for the window.
3150 */
3151
3152 /*!
3153 \internal
3154
3155 Construct a QToolBarChangeEvent given the current button state in \a state.
3156 */
QToolBarChangeEvent(bool t)3157 QToolBarChangeEvent::QToolBarChangeEvent(bool t)
3158 : QEvent(ToolBarChange), tog(t)
3159 {}
3160
3161 /*! \internal
3162 */
~QToolBarChangeEvent()3163 QToolBarChangeEvent::~QToolBarChangeEvent()
3164 {
3165 }
3166
3167 /*!
3168 \fn bool QToolBarChangeEvent::toggle() const
3169 \internal
3170 */
3171
3172 /*
3173 \fn Qt::ButtonState QToolBarChangeEvent::state() const
3174
3175 Returns the keyboard modifier flags at the time of the event.
3176
3177 The returned value is a selection of the following values,
3178 combined using the OR operator:
3179 Qt::ShiftButton, Qt::ControlButton, Qt::MetaButton, and Qt::AltButton.
3180 */
3181
3182 #endif // QT_NO_TOOLBAR
3183
3184 #ifndef QT_NO_SHORTCUT
3185
3186 /*!
3187 Constructs a shortcut event for the given \a key press,
3188 associated with the QShortcut ID \a id.
3189
3190 \a ambiguous specifies whether there is more than one QShortcut
3191 for the same key sequence.
3192 */
QShortcutEvent(const QKeySequence & key,int id,bool ambiguous)3193 QShortcutEvent::QShortcutEvent(const QKeySequence &key, int id, bool ambiguous)
3194 : QEvent(Shortcut), sequence(key), ambig(ambiguous), sid(id)
3195 {
3196 }
3197
3198 /*!
3199 Destroys the event object.
3200 */
~QShortcutEvent()3201 QShortcutEvent::~QShortcutEvent()
3202 {
3203 }
3204
3205 #endif // QT_NO_SHORTCUT
3206
3207 #ifndef QT_NO_DEBUG_STREAM
3208
3209 QDebug operator<<(QDebug, const QTouchEvent::TouchPoint &);
3210
formatTouchPoint(QDebug d,const QTouchEvent::TouchPoint & tp)3211 static inline void formatTouchPoint(QDebug d, const QTouchEvent::TouchPoint &tp)
3212 {
3213 d << "TouchPoint(" << tp.id() << ' ' << tp.rect();
3214 switch (tp.state()) {
3215 case Qt::TouchPointPressed:
3216 d << " pressed";
3217 break;
3218 case Qt::TouchPointReleased:
3219 d << " released";
3220 break;
3221 case Qt::TouchPointMoved:
3222 d << " moved";
3223 break;
3224 case Qt::TouchPointStationary:
3225 d << " stationary";
3226 break;
3227 case Qt::TouchPointStateMask: // Qt 4 only
3228 d << " stateMask";
3229 case Qt::TouchPointPrimary:
3230 d << " primary";
3231 break;
3232 }
3233 d << ')';
3234 }
3235
formatTouchEvent(QDebug d,const char * name,const QTouchEvent & t)3236 static inline void formatTouchEvent(QDebug d, const char *name, const QTouchEvent &t)
3237 {
3238 d << "QTouchEvent(" << name << " states: " << t.touchPointStates();
3239 d << ", " << t.touchPoints().size() << " points: " << t.touchPoints() << ')';
3240 }
3241
formatUnicodeString(QDebug d,const QString & s)3242 static void formatUnicodeString(QDebug d, const QString &s)
3243 {
3244 d << '"' << hex;
3245 for (int i = 0; i < s.size(); ++i) {
3246 if (i)
3247 d << ',';
3248 d << "U+" << s.at(i).unicode();
3249 }
3250 d << dec << '"';
3251 }
3252
formatInputMethodEvent(QDebug d,const QInputMethodEvent * e)3253 static inline void formatInputMethodEvent(QDebug d, const QInputMethodEvent *e)
3254 {
3255 d << "QInputMethodEvent(";
3256 if (!e->preeditString().isEmpty()) {
3257 d << "preedit=";
3258 formatUnicodeString(d, e->preeditString());
3259 }
3260 if (!e->commitString().isEmpty()) {
3261 d << ", commit=";
3262 formatUnicodeString(d, e->commitString());
3263 }
3264 if (e->replacementLength()) {
3265 d << ", replacementStart=" << e->replacementStart() << ", replacementLength="
3266 << e->replacementLength();
3267 }
3268 if (const int attributeCount = e->attributes().size()) {
3269 d << ", attributes= {";
3270 for (int a = 0; a < attributeCount; ++a) {
3271 const QInputMethodEvent::Attribute &at = e->attributes().at(a);
3272 if (a)
3273 d << ',';
3274 d << "[type= " << at.type << ", start=" << at.start << ", length=" << at.length
3275 << ", value=" << at.value << ']';
3276 }
3277 d << '}';
3278 }
3279 d << ')';
3280 }
3281
eventTypeName(QEvent::Type t)3282 static const char *eventTypeName(QEvent::Type t)
3283 {
3284 static const int enumIdx = QEvent::staticMetaObject.indexOfEnumerator("Type");
3285 return t <= QEvent::User
3286 ? QEvent::staticMetaObject.enumerator(enumIdx).valueToKey(t)
3287 : "User";
3288 }
3289
eventClassName(QEvent::Type t)3290 static const char *eventClassName(QEvent::Type t)
3291 {
3292 switch (t) {
3293 case QEvent::ActionAdded:
3294 case QEvent::ActionRemoved:
3295 case QEvent::ActionChanged:
3296 return "QActionEvent";
3297 case QEvent::MouseButtonPress:
3298 case QEvent::MouseButtonRelease:
3299 case QEvent::MouseButtonDblClick:
3300 case QEvent::MouseMove:
3301 case QEvent::NonClientAreaMouseMove:
3302 case QEvent::NonClientAreaMouseButtonPress:
3303 case QEvent::NonClientAreaMouseButtonRelease:
3304 case QEvent::NonClientAreaMouseButtonDblClick:
3305 return "QMouseEvent";
3306 case QEvent::DragEnter:
3307 return "QDragEnterEvent";
3308 case QEvent::DragMove:
3309 return "QDragMoveEvent";
3310 case QEvent::Drop:
3311 return "QDropEvent";
3312 case QEvent::KeyPress:
3313 case QEvent::KeyRelease:
3314 case QEvent::ShortcutOverride:
3315 return "QKeyEvent";
3316 case QEvent::FocusIn:
3317 case QEvent::FocusOut:
3318 return "QFocusEvent";
3319 case QEvent::ChildAdded:
3320 case QEvent::ChildPolished:
3321 case QEvent::ChildRemoved:
3322 #ifdef QT3_SUPPORT
3323 case QEvent::ChildInsertedRequest:
3324 case QEvent::ChildInserted:
3325 #endif
3326 return "QChildEvent";
3327 case QEvent::Paint:
3328 return "QPaintEvent";
3329 case QEvent::Move:
3330 return "QMoveEvent";
3331 case QEvent::Resize:
3332 return "QResizeEvent";
3333 case QEvent::Show:
3334 return "QShowEvent";
3335 case QEvent::Hide:
3336 return "QHideEvent";
3337 case QEvent::Enter:
3338 return "QEnterEvent";
3339 case QEvent::Close:
3340 return "QCloseEvent";
3341 case QEvent::FileOpen:
3342 return "QFileOpenEvent";
3343 #ifndef QT_NO_GESTURES
3344 case QEvent::NativeGesture:
3345 return "QNativeGestureEvent";
3346 case QEvent::Gesture:
3347 case QEvent::GestureOverride:
3348 return "QGestureEvent";
3349 #endif
3350 case QEvent::HoverEnter:
3351 case QEvent::HoverLeave:
3352 case QEvent::HoverMove:
3353 return "QHoverEvent";
3354 case QEvent::TabletEnterProximity:
3355 case QEvent::TabletLeaveProximity:
3356 case QEvent::TabletPress:
3357 case QEvent::TabletMove:
3358 case QEvent::TabletRelease:
3359 return "QTabletEvent";
3360 case QEvent::StatusTip:
3361 return "QStatusTipEvent";
3362 case QEvent::ToolTip:
3363 return "QHelpEvent";
3364 case QEvent::WindowStateChange:
3365 return "QWindowStateChangeEvent";
3366 case QEvent::Wheel:
3367 return "QWheelEvent";
3368 case QEvent::TouchBegin:
3369 case QEvent::TouchUpdate:
3370 case QEvent::TouchEnd:
3371 return "QTouchEvent";
3372 case QEvent::Shortcut:
3373 return "QShortcutEvent";
3374 case QEvent::InputMethod:
3375 return "QInputMethodEvent";
3376 case QEvent::GraphicsSceneMouseMove:
3377 case QEvent::GraphicsSceneMousePress:
3378 case QEvent::GraphicsSceneMouseRelease:
3379 case QEvent::GraphicsSceneMouseDoubleClick:
3380 return "QGraphicsSceneMouseEvent";
3381 case QEvent::GraphicsSceneContextMenu:
3382 case QEvent::GraphicsSceneHoverEnter:
3383 case QEvent::GraphicsSceneHoverMove:
3384 case QEvent::GraphicsSceneHoverLeave:
3385 case QEvent::GraphicsSceneHelp:
3386 case QEvent::GraphicsSceneDragEnter:
3387 case QEvent::GraphicsSceneDragMove:
3388 case QEvent::GraphicsSceneDragLeave:
3389 case QEvent::GraphicsSceneDrop:
3390 case QEvent::GraphicsSceneWheel:
3391 return "QGraphicsSceneEvent";
3392 case QEvent::Timer:
3393 return "QTimerEvent";
3394 default:
3395 break;
3396 }
3397 return "QEvent";
3398 }
3399
3400 namespace {
3401 // Make protected QObject::staticQtMetaObject accessible for formatting enums.
3402 class DebugHelper : public QObject {
3403 public:
mouseButtonToString(Qt::MouseButton button)3404 static const char *mouseButtonToString(Qt::MouseButton button)
3405 {
3406 static const int enumIdx = QObject::staticQtMetaObject.indexOfEnumerator("MouseButtons");
3407 return QObject::staticQtMetaObject.enumerator(enumIdx).valueToKey(button);
3408 }
3409
mouseButtonsToString(Qt::MouseButtons buttons)3410 static QByteArray mouseButtonsToString(Qt::MouseButtons buttons)
3411 {
3412 QByteArray result;
3413 for (int i = 0; (uint)(1 << i) <= Qt::MouseButtonMask; ++i) {
3414 const Qt::MouseButton button = static_cast<Qt::MouseButton>(1 << i);
3415 if (buttons.testFlag(button)) {
3416 if (!result.isEmpty())
3417 result.append('|');
3418 result.append(mouseButtonToString(button));
3419 }
3420 }
3421 if (result.isEmpty())
3422 result.append("NoButton");
3423 return result;
3424 }
3425 };
3426 } // namespace
3427
3428 # ifndef QT_NO_DRAGANDDROP
3429
formatDropEvent(QDebug d,const QDropEvent * e)3430 static void formatDropEvent(QDebug d, const QDropEvent *e)
3431 {
3432 const QEvent::Type type = e->type();
3433 d << eventClassName(type) << "(dropAction=" << e->dropAction() << ", proposedAction="
3434 << e->proposedAction() << ", possibleActions=" << e->possibleActions();
3435 if (type == QEvent::DragMove || type == QEvent::DragEnter)
3436 d << ", answerRect=" << static_cast<const QDragMoveEvent *>(e)->answerRect();
3437 d << ", formats=" << e->mimeData()->formats();
3438 if (const Qt::KeyboardModifiers mods = e->keyboardModifiers())
3439 d << ", keyboardModifiers=" << mods;
3440 d << ", " << DebugHelper::mouseButtonsToString(e->mouseButtons()).constData();
3441 }
3442
3443 # endif // !QT_NO_DRAGANDDROP
3444
3445 # ifndef QT_NO_TABLETEVENT
3446
formatTabletEvent(QDebug d,const QTabletEvent * e)3447 static void formatTabletEvent(QDebug d, const QTabletEvent *e)
3448 {
3449 const QEvent::Type type = e->type();
3450
3451 static const int deviceEnumIdx = QTabletEvent::staticMetaObject.indexOfEnumerator("TabletDevice");
3452 static const int pointerTypeEnumIdx = QTabletEvent::staticMetaObject.indexOfEnumerator("PointerType");
3453 const char* device = QTabletEvent::staticMetaObject.enumerator(deviceEnumIdx).valueToKey(e->device());
3454 const char* pointerType = QTabletEvent::staticMetaObject.enumerator(pointerTypeEnumIdx).valueToKey(e->pointerType());
3455
3456 d << eventClassName(type) << '(' << eventTypeName(type)
3457 << ", device=" << device
3458 << ", pointerType=" << pointerType
3459 << ", uniqueId=" << e->uniqueId()
3460 << ", z=" << e->z()
3461 << ", xTilt=" << e->xTilt()
3462 << ", yTilt=" << e->yTilt();
3463 if (type == QEvent::TabletPress || type == QEvent::TabletMove)
3464 d << ", pressure=" << e->pressure();
3465 if (e->device() == QTabletEvent::RotationStylus || e->device() == QTabletEvent::FourDMouse)
3466 d << ", rotation=" << e->rotation();
3467 if (e->device() == QTabletEvent::Airbrush)
3468 d << ", tangentialPressure=" << e->tangentialPressure();
3469 }
3470
3471 # endif // !QT_NO_TABLETEVENT
3472
operator <<(QDebug dbg,const QTouchEvent::TouchPoint & tp)3473 QDebug operator<<(QDebug dbg, const QTouchEvent::TouchPoint &tp)
3474 {
3475 formatTouchPoint(dbg, tp);
3476 return dbg;
3477 }
3478
operator <<(QDebug dbg,const QEvent * e)3479 QDebug operator<<(QDebug dbg, const QEvent *e) {
3480 #ifndef Q_BROKEN_DEBUG_STREAM
3481 dbg.nospace();
3482 if (!e) {
3483 dbg << "QEvent(this = 0x0)";
3484 dbg.space();
3485 return dbg;
3486 }
3487 // More useful event output could be added here
3488 const QEvent::Type type = e->type();
3489 switch (type) {
3490 case QEvent::MouseButtonPress:
3491 case QEvent::MouseMove:
3492 case QEvent::MouseButtonRelease:
3493 case QEvent::MouseButtonDblClick:
3494 case QEvent::NonClientAreaMouseButtonPress:
3495 case QEvent::NonClientAreaMouseMove:
3496 case QEvent::NonClientAreaMouseButtonRelease:
3497 case QEvent::NonClientAreaMouseButtonDblClick:
3498 {
3499 const QMouseEvent *me = static_cast<const QMouseEvent*>(e);
3500 const Qt::MouseButton button = me->button();
3501 const Qt::MouseButtons buttons = me->buttons();
3502 dbg << "QMouseEvent(" << eventTypeName(type);
3503 if (type != QEvent::MouseMove && type != QEvent::NonClientAreaMouseMove)
3504 dbg << ", " << DebugHelper::mouseButtonToString(button);
3505 if (buttons && button != buttons)
3506 dbg << ", buttons=" << DebugHelper::mouseButtonsToString(buttons).constData();
3507 if (const int mods = int(me->modifiers()))
3508 dbg << ", modifiers=0x" << hex << mods << dec;
3509 dbg << ')';
3510 }
3511 break;
3512 # ifndef QT_NO_WHEELEVENT
3513 case QEvent::Wheel: {
3514 const QWheelEvent *we = static_cast<const QWheelEvent *>(e);
3515 dbg << "QWheelEvent(" << "delta=" << we->delta() << ", pos=" << we->pos()
3516 << ", orientation=" << we->orientation() << ')';
3517 }
3518 break;
3519 # endif // !QT_NO_WHEELEVENT
3520 case QEvent::KeyPress:
3521 case QEvent::KeyRelease:
3522 case QEvent::ShortcutOverride:
3523 {
3524 const QKeyEvent *ke = static_cast<const QKeyEvent *>(e);
3525 dbg << "QKeyEvent(" << eventTypeName(type)
3526 << ", key=0x" << hex << ke->key() << dec;
3527 if (const int mods = ke->modifiers())
3528 dbg << ", modifiers=0x" << hex << mods << dec;
3529 if (!ke->text().isEmpty())
3530 dbg << ", text=" << ke->text();
3531 if (ke->isAutoRepeat())
3532 dbg << ", autorepeat, count=" << ke->count();
3533 dbg << ')';
3534 }
3535 break;
3536 case QEvent::Shortcut: {
3537 const QShortcutEvent *se = static_cast<const QShortcutEvent *>(e);
3538 dbg << "QShortcutEvent(" << se->key().toString() << ", id=" << se->shortcutId();
3539 if (se->isAmbiguous())
3540 dbg << ", ambiguous";
3541 dbg << ')';
3542 }
3543 break;
3544 case QEvent::FocusIn:
3545 case QEvent::FocusOut:
3546 dbg << "QFocusEvent(" << eventTypeName(type) << ", "
3547 << static_cast<const QFocusEvent *>(e)->reason() << ')';
3548 break;
3549 case QEvent::Move: {
3550 const QMoveEvent *me = static_cast<const QMoveEvent *>(e);
3551 dbg << "QMoveEvent(" << me->pos();
3552 if (!me->spontaneous())
3553 dbg << ", non-spontaneous";
3554 dbg << ')';
3555 }
3556 break;
3557 case QEvent::Resize: {
3558 const QResizeEvent *re = static_cast<const QResizeEvent *>(e);
3559 dbg << "QResizeEvent(" << re->size();
3560 if (!re->spontaneous())
3561 dbg << ", non-spontaneous";
3562 dbg << ')';
3563 }
3564 break;
3565 # ifndef QT_NO_DRAGANDDROP
3566 case QEvent::DragEnter:
3567 case QEvent::DragMove:
3568 case QEvent::Drop:
3569 formatDropEvent(dbg, static_cast<const QDropEvent *>(e));
3570 break;
3571 # endif // !QT_NO_DRAGANDDROP
3572 case QEvent::InputMethod:
3573 formatInputMethodEvent(dbg, static_cast<const QInputMethodEvent *>(e));
3574 break;
3575 case QEvent::TouchBegin:
3576 case QEvent::TouchUpdate:
3577 case QEvent::TouchEnd:
3578 formatTouchEvent(dbg, eventTypeName(type), *static_cast<const QTouchEvent*>(e));
3579 break;
3580 case QEvent::ChildAdded:
3581 case QEvent::ChildPolished:
3582 case QEvent::ChildRemoved:
3583 dbg << "QChildEvent(" << eventTypeName(type) << ", " << (static_cast<const QChildEvent*>(e))->child() << ')';
3584 break;
3585 # ifndef QT_NO_GESTURES
3586 case QEvent::NativeGesture: {
3587 const QNativeGestureEvent *ne = static_cast<const QNativeGestureEvent *>(e);
3588 dbg << "QNativeGestureEvent(type=" << ne->type() << ", percentage=" << ne->percentage
3589 << "position=" << ne->position << ", angle=" << ne->angle << ')';
3590 }
3591 break;
3592 # endif // !QT_NO_GESTURES
3593 case QEvent::ContextMenu:
3594 dbg << "QContextMenuEvent(" << static_cast<const QContextMenuEvent *>(e)->pos() << ')';
3595 break;
3596 # ifndef QT_NO_TABLETEVENT
3597 case QEvent::TabletEnterProximity:
3598 case QEvent::TabletLeaveProximity:
3599 case QEvent::TabletPress:
3600 case QEvent::TabletMove:
3601 case QEvent::TabletRelease:
3602 formatTabletEvent(dbg, static_cast<const QTabletEvent *>(e));
3603 break;
3604 # endif // !QT_NO_TABLETEVENT
3605 case QEvent::Timer:
3606 dbg << "QTimerEvent(id=" << static_cast<const QTimerEvent *>(e)->timerId() << ')';
3607 break;
3608 default:
3609 dbg << eventClassName(type) << '(' << eventTypeName(type) << ", "
3610 << (const void *)e << ", type = " << e->type() << ')';
3611 break;
3612 }
3613 dbg.maybeSpace();
3614 return dbg;
3615 #else // !Q_BROKEN_DEBUG_STREAM
3616 qWarning("This compiler doesn't support streaming QEvent to QDebug");
3617 return dbg;
3618 Q_UNUSED(e);
3619 #endif
3620 }
3621 #endif
3622
3623 #ifndef QT_NO_CLIPBOARD
3624 /*!
3625 \class QClipboardEvent
3626 \ingroup events
3627 \internal
3628
3629 \brief The QClipboardEvent class provides the parameters used in a clipboard event.
3630
3631 This class is for internal use only, and exists to aid the clipboard on various
3632 platforms to get all the information it needs. Use QEvent::Clipboard instead.
3633
3634 \sa QClipboard
3635 */
3636
QClipboardEvent(QEventPrivate * data)3637 QClipboardEvent::QClipboardEvent(QEventPrivate *data)
3638 : QEvent(QEvent::Clipboard)
3639 {
3640 d = data;
3641 }
3642
~QClipboardEvent()3643 QClipboardEvent::~QClipboardEvent()
3644 {
3645 }
3646 #endif // QT_NO_CLIPBOARD
3647
3648 /*!
3649 \class QShortcutEvent
3650 \brief The QShortcutEvent class provides an event which is generated when
3651 the user presses a key combination.
3652
3653 \ingroup events
3654
3655 Normally you don't need to use this class directly; QShortcut
3656 provides a higher-level interface to handle shortcut keys.
3657
3658 \sa QShortcut
3659 */
3660
3661 /*!
3662 \fn const QKeySequence &QShortcutEvent::key() const
3663
3664 Returns the key sequence that triggered the event.
3665 */
3666
3667 // ### Qt 5: remove
3668 /*!
3669 \fn const QKeySequence &QShortcutEvent::key()
3670
3671 \internal
3672 */
3673
3674 /*!
3675 \fn int QShortcutEvent::shortcutId() const
3676
3677 Returns the ID of the QShortcut object for which this event was
3678 generated.
3679
3680 \sa QShortcut::id()
3681 */
3682
3683 // ### Qt 5: remove
3684 /*!
3685 \fn int QShortcutEvent::shortcutId()
3686 \overload
3687
3688 \internal
3689 */
3690
3691 /*!
3692 \fn bool QShortcutEvent::isAmbiguous() const
3693
3694 Returns true if the key sequence that triggered the event is
3695 ambiguous.
3696
3697 \sa QShortcut::activatedAmbiguously()
3698 */
3699
3700 // ### Qt 5: remove
3701 /*!
3702 \fn bool QShortcutEvent::isAmbiguous()
3703
3704 \internal
3705 */
3706
3707 /*!
3708 \class QWindowStateChangeEvent
3709 \ingroup events
3710
3711 \brief The QWindowStateChangeEvent class provides the window state before a
3712 window state change.
3713 */
3714
3715 /*! \fn Qt::WindowStates QWindowStateChangeEvent::oldState() const
3716
3717 Returns the state of the window before the change.
3718 */
3719
3720 /*! \internal
3721 */
QWindowStateChangeEvent(Qt::WindowStates s)3722 QWindowStateChangeEvent::QWindowStateChangeEvent(Qt::WindowStates s)
3723 : QEvent(WindowStateChange), ostate(s)
3724 {
3725 }
3726
3727 /*! \internal
3728 */
QWindowStateChangeEvent(Qt::WindowStates s,bool isOverride)3729 QWindowStateChangeEvent::QWindowStateChangeEvent(Qt::WindowStates s, bool isOverride)
3730 : QEvent(WindowStateChange), ostate(s)
3731 {
3732 if (isOverride)
3733 d = (QEventPrivate*)(this);
3734 }
3735
3736 /*! \internal
3737 */
isOverride() const3738 bool QWindowStateChangeEvent::isOverride() const
3739 {
3740 return (d != 0);
3741 }
3742
3743 /*! \internal
3744 */
~QWindowStateChangeEvent()3745 QWindowStateChangeEvent::~QWindowStateChangeEvent()
3746 {
3747 }
3748
3749 #ifdef QT3_SUPPORT
3750
3751 /*!
3752 \class QMenubarUpdatedEvent
3753 \internal
3754 Event sent by QMenuBar to tell Q3Workspace to update itself.
3755 */
3756
3757 /*! \internal
3758
3759 */
QMenubarUpdatedEvent(QMenuBar * const menuBar)3760 QMenubarUpdatedEvent::QMenubarUpdatedEvent(QMenuBar * const menuBar)
3761 :QEvent(QEvent::MenubarUpdated), m_menuBar(menuBar) {}
3762
3763 /*!
3764 \fn QMenuBar *QMenubarUpdatedEvent::menuBar()
3765 \internal
3766 */
3767
3768 /*!
3769 \fn bool operator==(QKeyEvent *e, QKeySequence::StandardKey key)
3770
3771 \relates QKeyEvent
3772
3773 Returns true if \a key is currently bound to the key combination
3774 specified by \a e.
3775
3776 Equivalent to \c {e->matches(key)}.
3777 */
3778
3779 /*!
3780 \fn bool operator==(QKeySequence::StandardKey key, QKeyEvent *e)
3781
3782 \relates QKeyEvent
3783
3784 Returns true if \a key is currently bound to the key combination
3785 specified by \a e.
3786
3787 Equivalent to \c {e->matches(key)}.
3788 */
3789
3790 /*!
3791 \internal
3792
3793 \class QKeyEventEx
3794 \ingroup events
3795
3796 \brief The QKeyEventEx class provides more extended information about a keyevent.
3797
3798 This class is for internal use only, and exists to aid the shortcut system on
3799 various platforms to get all the information it needs.
3800 */
3801
3802 #endif
3803
3804 /*!
3805 \class QTouchEvent
3806 \brief The QTouchEvent class contains parameters that describe a touch event.
3807 \since 4.6
3808 \ingroup events
3809 \ingroup touch
3810
3811 \section1 Enabling Touch Events
3812
3813 Touch events occur when pressing, releasing, or moving one or more touch points on a touch
3814 device (such as a touch-screen or track-pad). To receive touch events, widgets have to have the
3815 Qt::WA_AcceptTouchEvents attribute set and graphics items need to have the
3816 \l{QGraphicsItem::setAcceptTouchEvents()}{acceptTouchEvents} attribute set to true.
3817
3818 When using QAbstractScrollArea based widgets, you should enable the Qt::WA_AcceptTouchEvents
3819 attribute on the scroll area's \l{QAbstractScrollArea::viewport()}{viewport}.
3820
3821 Similarly to QMouseEvent, Qt automatically grabs each touch point on the first press inside a
3822 widget, and the widget will receive all updates for the touch point until it is released.
3823 Note that it is possible for a widget to receive events for numerous touch points, and that
3824 multiple widgets may be receiving touch events at the same time.
3825
3826 \section1 Event Handling
3827
3828 All touch events are of type QEvent::TouchBegin, QEvent::TouchUpdate, or QEvent::TouchEnd.
3829 Reimplement QWidget::event() or QAbstractScrollArea::viewportEvent() for widgets and
3830 QGraphicsItem::sceneEvent() for items in a graphics view to receive touch events.
3831
3832 The QEvent::TouchUpdate and QEvent::TouchEnd events are sent to the widget or item that
3833 accepted the QEvent::TouchBegin event. If the QEvent::TouchBegin event is not accepted and not
3834 filtered by an event filter, then no further touch events are sent until the next
3835 QEvent::TouchBegin.
3836
3837 The touchPoints() function returns a list of all touch points contained in the event.
3838 Information about each touch point can be retrieved using the QTouchEvent::TouchPoint class.
3839 The Qt::TouchPointState enum describes the different states that a touch point may have.
3840
3841 \section1 Event Delivery and Propagation
3842
3843 By default, QWidget::event() translates the first non-primary touch point in a QTouchEvent into
3844 a QMouseEvent. This makes it possible to enable touch events on existing widgets that do not
3845 normally handle QTouchEvent. See below for information on some special considerations needed
3846 when doing this.
3847
3848 QEvent::TouchBegin is the first touch event sent to a widget. The QEvent::TouchBegin event
3849 contains a special accept flag that indicates whether the receiver wants the event. By default,
3850 the event is accepted. You should call ignore() if the touch event is not handled by your
3851 widget. The QEvent::TouchBegin event is propagated up the parent widget chain until a widget
3852 accepts it with accept(), or an event filter consumes it. For QGraphicsItems, the
3853 QEvent::TouchBegin event is propagated to items under the mouse (similar to mouse event
3854 propagation for QGraphicsItems).
3855
3856 \section1 Touch Point Grouping
3857
3858 As mentioned above, it is possible that several widgets can be receiving QTouchEvents at the
3859 same time. However, Qt makes sure to never send duplicate QEvent::TouchBegin events to the same
3860 widget, which could theoretically happen during propagation if, for example, the user touched 2
3861 separate widgets in a QGroupBox and both widgets ignored the QEvent::TouchBegin event.
3862
3863 To avoid this, Qt will group new touch points together using the following rules:
3864
3865 \list
3866
3867 \i When the first touch point is detected, the destination widget is determined firstly by the
3868 location on screen and secondly by the propagation rules.
3869
3870 \i When additional touch points are detected, Qt first looks to see if there are any active
3871 touch points on any ancestor or descendent of the widget under the new touch point. If there
3872 are, the new touch point is grouped with the first, and the new touch point will be sent in a
3873 single QTouchEvent to the widget that handled the first touch point. (The widget under the new
3874 touch point will not receive an event).
3875
3876 \endlist
3877
3878 This makes it possible for sibling widgets to handle touch events independently while making
3879 sure that the sequence of QTouchEvents is always correct.
3880
3881 \section1 Mouse Events and the Primary Touch Point
3882
3883 QTouchEvent delivery is independent from that of QMouseEvent. On some windowing systems, mouse
3884 events are also sent for the \l{QTouchEvent::TouchPoint::isPrimary()}{primary touch point}.
3885 This means it is possible for your widget to receive both QTouchEvent and QMouseEvent for the
3886 same user interaction point. You can use the QTouchEvent::TouchPoint::isPrimary() function to
3887 identify the primary touch point.
3888
3889 Note that on some systems, it is possible to receive touch events without a primary touch
3890 point. All this means is that there will be no mouse event generated for the touch points in
3891 the QTouchEvent.
3892
3893 \section1 Caveats
3894
3895 \list
3896
3897 \i As mentioned above, enabling touch events means multiple widgets can be receiving touch
3898 events simultaneously. Combined with the default QWidget::event() handling for QTouchEvents,
3899 this gives you great flexibility in designing touch user interfaces. Be aware of the
3900 implications. For example, it is possible that the user is moving a QSlider with one finger and
3901 pressing a QPushButton with another. The signals emitted by these widgets will be
3902 interleaved.
3903
3904 \i Recursion into the event loop using one of the exec() methods (e.g., QDialog::exec() or
3905 QMenu::exec()) in a QTouchEvent event handler is not supported. Since there are multiple event
3906 recipients, recursion may cause problems, including but not limited to lost events
3907 and unexpected infinite recursion.
3908
3909 \i QTouchEvents are not affected by a \l{QWidget::grabMouse()}{mouse grab} or an
3910 \l{QApplication::activePopupWidget()}{active pop-up widget}. The behavior of QTouchEvents is
3911 undefined when opening a pop-up or grabbing the mouse while there are more than one active touch
3912 points.
3913
3914 \endlist
3915
3916 \sa QTouchEvent::TouchPoint, Qt::TouchPointState, Qt::WA_AcceptTouchEvents,
3917 QGraphicsItem::acceptTouchEvents()
3918 */
3919
3920 /*! \enum Qt::TouchPointState
3921 \since 4.6
3922
3923 This enum represents the state of a touch point at the time the
3924 QTouchEvent occurred.
3925
3926 \value TouchPointPressed The touch point is now pressed.
3927 \value TouchPointMoved The touch point moved.
3928 \value TouchPointStationary The touch point did not move.
3929 \value TouchPointReleased The touch point was released.
3930
3931 \omitvalue TouchPointStateMask
3932 \omitvalue TouchPointPrimary
3933 */
3934
3935 /*! \enum QTouchEvent::DeviceType
3936
3937 This enum represents the type of device that generated a QTouchEvent.
3938
3939 \value TouchScreen In this type of device, the touch surface and display are integrated. This
3940 means the surface and display typically have the same size, such that there
3941 is a direct relationship between the touch points' physical positions and the
3942 coordinate reported by QTouchEvent::TouchPoint. As a result, Qt allows the
3943 user to interact directly with multiple QWidgets and QGraphicsItems at the
3944 same time.
3945
3946 \value TouchPad In this type of device, the touch surface is separate from the display. There
3947 is not a direct relationship between the physical touch location and the
3948 on-screen coordinates. Instead, they are calculated relative to the current
3949 mouse position, and the user must use the touch-pad to move this reference
3950 point. Unlike touch-screens, Qt allows users to only interact with a single
3951 QWidget or QGraphicsItem at a time.
3952 */
3953
3954 /*!
3955 Constructs a QTouchEvent with the given \a eventType, \a deviceType, and \a touchPoints.
3956 The \a touchPointStates and \a modifiers are the current touch point states and keyboard
3957 modifiers at the time of the event.
3958 */
QTouchEvent(QEvent::Type eventType,QTouchEvent::DeviceType deviceType,Qt::KeyboardModifiers modifiers,Qt::TouchPointStates touchPointStates,const QList<QTouchEvent::TouchPoint> & touchPoints)3959 QTouchEvent::QTouchEvent(QEvent::Type eventType,
3960 QTouchEvent::DeviceType deviceType,
3961 Qt::KeyboardModifiers modifiers,
3962 Qt::TouchPointStates touchPointStates,
3963 const QList<QTouchEvent::TouchPoint> &touchPoints)
3964 : QInputEvent(eventType, modifiers),
3965 _widget(0),
3966 _deviceType(deviceType),
3967 _touchPointStates(touchPointStates),
3968 _touchPoints(touchPoints)
3969 { }
3970
3971 /*!
3972 Destroys the QTouchEvent.
3973 */
~QTouchEvent()3974 QTouchEvent::~QTouchEvent()
3975 { }
3976
3977 /*! \fn QWidget *QTouchEvent::widget() const
3978
3979 Returns the widget on which the event occurred.
3980 */
3981
3982
3983 /*! \fn Qt::TouchPointStates QTouchEvent::touchPointStates() const
3984
3985 Returns a bitwise OR of all the touch point states for this event.
3986 */
3987
3988 /*! \fn const QList<QTouchEvent::TouchPoint> &QTouchEvent::touchPoints() const
3989
3990 Returns the list of touch points contained in the touch event.
3991 */
3992
3993 /*! \fn QTouchEvent::DeviceType QTouchEvent::deviceType() const
3994
3995 Returns the touch device Type, which is of type \l {QTouchEvent::DeviceType} {DeviceType}.
3996 */
3997
3998 /*! \fn void QTouchEvent::setWidget(QWidget *widget)
3999
4000 \internal
4001
4002 Sets the widget for this event.
4003 */
4004
4005 /*! \fn void QTouchEvent::setTouchPointStates(Qt::TouchPointStates touchPointStates)
4006
4007 \internal
4008
4009 Sets a bitwise OR of all the touch point states for this event.
4010 */
4011
4012 /*! \fn void QTouchEvent::setTouchPoints(const QList<QTouchEvent::TouchPoint> &touchPoints)
4013
4014 \internal
4015
4016 Sets the list of touch points for this event.
4017 */
4018
4019 /*! \fn void QTouchEvent::setDeviceType(DeviceType deviceType)
4020
4021 \internal
4022
4023 Sets the device type to \a deviceType, which is of type \l {QTouchEvent::DeviceType}
4024 {DeviceType}.
4025 */
4026
4027 /*! \class QTouchEvent::TouchPoint
4028 \brief The TouchPoint class provides information about a touch point in a QTouchEvent.
4029 \since 4.6
4030 */
4031
4032 /*! \internal
4033
4034 Constructs a QTouchEvent::TouchPoint for use in a QTouchEvent.
4035 */
TouchPoint(int id)4036 QTouchEvent::TouchPoint::TouchPoint(int id)
4037 : d(new QTouchEventTouchPointPrivate(id))
4038 { }
4039
4040 /*! \internal
4041
4042 Constructs a copy of \a other.
4043 */
TouchPoint(const QTouchEvent::TouchPoint & other)4044 QTouchEvent::TouchPoint::TouchPoint(const QTouchEvent::TouchPoint &other)
4045 : d(other.d)
4046 {
4047 d->ref.ref();
4048 }
4049
4050 /*! \internal
4051
4052 Destroys the QTouchEvent::TouchPoint.
4053 */
~TouchPoint()4054 QTouchEvent::TouchPoint::~TouchPoint()
4055 {
4056 if (!d->ref.deref())
4057 delete d;
4058 }
4059
4060 /*!
4061 Returns the id number of this touch point.
4062
4063 Id numbers are globally sequential, starting at zero, meaning the
4064 first touch point in the application has id 0, the second has id 1,
4065 and so on.
4066 */
id() const4067 int QTouchEvent::TouchPoint::id() const
4068 {
4069 return d->id;
4070 }
4071
4072 /*!
4073 Returns the current state of this touch point.
4074 */
state() const4075 Qt::TouchPointState QTouchEvent::TouchPoint::state() const
4076 {
4077 return Qt::TouchPointState(int(d->state) & Qt::TouchPointStateMask);
4078 }
4079
4080 /*!
4081 Returns true if this touch point is the primary touch point. The primary touch point is the
4082 point for which the windowing system generates mouse events.
4083 */
isPrimary() const4084 bool QTouchEvent::TouchPoint::isPrimary() const
4085 {
4086 return (d->state & Qt::TouchPointPrimary) != 0;
4087 }
4088
4089 /*!
4090 Returns the position of this touch point, relative to the widget
4091 or QGraphicsItem that received the event.
4092
4093 \sa startPos(), lastPos(), screenPos(), scenePos(), normalizedPos()
4094 */
pos() const4095 QPointF QTouchEvent::TouchPoint::pos() const
4096 {
4097 return d->rect.center();
4098 }
4099
4100 /*!
4101 Returns the scene position of this touch point.
4102
4103 The scene position is the position in QGraphicsScene coordinates
4104 if the QTouchEvent is handled by a QGraphicsItem::touchEvent()
4105 reimplementation, and identical to the screen position for
4106 widgets.
4107
4108 \sa startScenePos(), lastScenePos(), pos()
4109 */
scenePos() const4110 QPointF QTouchEvent::TouchPoint::scenePos() const
4111 {
4112 return d->sceneRect.center();
4113 }
4114
4115 /*!
4116 Returns the screen position of this touch point.
4117
4118 \sa startScreenPos(), lastScreenPos(), pos()
4119 */
screenPos() const4120 QPointF QTouchEvent::TouchPoint::screenPos() const
4121 {
4122 return d->screenRect.center();
4123 }
4124
4125 /*!
4126 Returns the normalized position of this touch point.
4127
4128 The coordinates are normalized to the size of the touch device,
4129 i.e. (0,0) is the top-left corner and (1,1) is the bottom-right corner.
4130
4131 \sa startNormalizedPos(), lastNormalizedPos(), pos()
4132 */
normalizedPos() const4133 QPointF QTouchEvent::TouchPoint::normalizedPos() const
4134 {
4135 return d->normalizedPos;
4136 }
4137
4138 /*!
4139 Returns the starting position of this touch point, relative to the
4140 widget or QGraphicsItem that received the event.
4141
4142 \sa pos(), lastPos()
4143 */
startPos() const4144 QPointF QTouchEvent::TouchPoint::startPos() const
4145 {
4146 return d->startPos;
4147 }
4148
4149 /*!
4150 Returns the starting scene position of this touch point.
4151
4152 The scene position is the position in QGraphicsScene coordinates
4153 if the QTouchEvent is handled by a QGraphicsItem::touchEvent()
4154 reimplementation, and identical to the screen position for
4155 widgets.
4156
4157 \sa scenePos(), lastScenePos()
4158 */
startScenePos() const4159 QPointF QTouchEvent::TouchPoint::startScenePos() const
4160 {
4161 return d->startScenePos;
4162 }
4163
4164 /*!
4165 Returns the starting screen position of this touch point.
4166
4167 \sa screenPos(), lastScreenPos()
4168 */
startScreenPos() const4169 QPointF QTouchEvent::TouchPoint::startScreenPos() const
4170 {
4171 return d->startScreenPos;
4172 }
4173
4174 /*!
4175 Returns the normalized starting position of this touch point.
4176
4177 The coordinates are normalized to the size of the touch device,
4178 i.e. (0,0) is the top-left corner and (1,1) is the bottom-right corner.
4179
4180 \sa normalizedPos(), lastNormalizedPos()
4181 */
startNormalizedPos() const4182 QPointF QTouchEvent::TouchPoint::startNormalizedPos() const
4183 {
4184 return d->startNormalizedPos;
4185 }
4186
4187 /*!
4188 Returns the position of this touch point from the previous touch
4189 event, relative to the widget or QGraphicsItem that received the event.
4190
4191 \sa pos(), startPos()
4192 */
lastPos() const4193 QPointF QTouchEvent::TouchPoint::lastPos() const
4194 {
4195 return d->lastPos;
4196 }
4197
4198 /*!
4199 Returns the scene position of this touch point from the previous
4200 touch event.
4201
4202 The scene position is the position in QGraphicsScene coordinates
4203 if the QTouchEvent is handled by a QGraphicsItem::touchEvent()
4204 reimplementation, and identical to the screen position for
4205 widgets.
4206
4207 \sa scenePos(), startScenePos()
4208 */
lastScenePos() const4209 QPointF QTouchEvent::TouchPoint::lastScenePos() const
4210 {
4211 return d->lastScenePos;
4212 }
4213
4214 /*!
4215 Returns the screen position of this touch point from the previous
4216 touch event.
4217
4218 \sa screenPos(), startScreenPos()
4219 */
lastScreenPos() const4220 QPointF QTouchEvent::TouchPoint::lastScreenPos() const
4221 {
4222 return d->lastScreenPos;
4223 }
4224
4225 /*!
4226 Returns the normalized position of this touch point from the
4227 previous touch event.
4228
4229 The coordinates are normalized to the size of the touch device,
4230 i.e. (0,0) is the top-left corner and (1,1) is the bottom-right corner.
4231
4232 \sa normalizedPos(), startNormalizedPos()
4233 */
lastNormalizedPos() const4234 QPointF QTouchEvent::TouchPoint::lastNormalizedPos() const
4235 {
4236 return d->lastNormalizedPos;
4237 }
4238
4239 /*!
4240 Returns the rect for this touch point, relative to the widget
4241 or QGraphicsItem that received the event. The rect is centered
4242 around the point returned by pos().
4243
4244 \note This function returns an empty rect if the device does not report touch point sizes.
4245 */
rect() const4246 QRectF QTouchEvent::TouchPoint::rect() const
4247 {
4248 return d->rect;
4249 }
4250
4251 /*!
4252 Returns the rect for this touch point in scene coordinates.
4253
4254 \note This function returns an empty rect if the device does not report touch point sizes.
4255
4256 \sa scenePos(), rect()
4257 */
sceneRect() const4258 QRectF QTouchEvent::TouchPoint::sceneRect() const
4259 {
4260 return d->sceneRect;
4261 }
4262
4263 /*!
4264 Returns the rect for this touch point in screen coordinates.
4265
4266 \note This function returns an empty rect if the device does not report touch point sizes.
4267
4268 \sa screenPos(), rect()
4269 */
screenRect() const4270 QRectF QTouchEvent::TouchPoint::screenRect() const
4271 {
4272 return d->screenRect;
4273 }
4274
4275 /*!
4276 Returns the pressure of this touch point. The return value is in
4277 the range 0.0 to 1.0.
4278 */
pressure() const4279 qreal QTouchEvent::TouchPoint::pressure() const
4280 {
4281 return d->pressure;
4282 }
4283
4284 /*! \internal */
setId(int id)4285 void QTouchEvent::TouchPoint::setId(int id)
4286 {
4287 if (d->ref != 1)
4288 d = d->detach();
4289 d->id = id;
4290 }
4291
4292 /*! \internal */
setState(Qt::TouchPointStates state)4293 void QTouchEvent::TouchPoint::setState(Qt::TouchPointStates state)
4294 {
4295 if (d->ref != 1)
4296 d = d->detach();
4297 d->state = state;
4298 }
4299
4300 /*! \internal */
setPos(const QPointF & pos)4301 void QTouchEvent::TouchPoint::setPos(const QPointF &pos)
4302 {
4303 if (d->ref != 1)
4304 d = d->detach();
4305 d->rect.moveCenter(pos);
4306 }
4307
4308 /*! \internal */
setScenePos(const QPointF & scenePos)4309 void QTouchEvent::TouchPoint::setScenePos(const QPointF &scenePos)
4310 {
4311 if (d->ref != 1)
4312 d = d->detach();
4313 d->sceneRect.moveCenter(scenePos);
4314 }
4315
4316 /*! \internal */
setScreenPos(const QPointF & screenPos)4317 void QTouchEvent::TouchPoint::setScreenPos(const QPointF &screenPos)
4318 {
4319 if (d->ref != 1)
4320 d = d->detach();
4321 d->screenRect.moveCenter(screenPos);
4322 }
4323
4324 /*! \internal */
setNormalizedPos(const QPointF & normalizedPos)4325 void QTouchEvent::TouchPoint::setNormalizedPos(const QPointF &normalizedPos)
4326 {
4327 if (d->ref != 1)
4328 d = d->detach();
4329 d->normalizedPos = normalizedPos;
4330 }
4331
4332 /*! \internal */
setStartPos(const QPointF & startPos)4333 void QTouchEvent::TouchPoint::setStartPos(const QPointF &startPos)
4334 {
4335 if (d->ref != 1)
4336 d = d->detach();
4337 d->startPos = startPos;
4338 }
4339
4340 /*! \internal */
setStartScenePos(const QPointF & startScenePos)4341 void QTouchEvent::TouchPoint::setStartScenePos(const QPointF &startScenePos)
4342 {
4343 if (d->ref != 1)
4344 d = d->detach();
4345 d->startScenePos = startScenePos;
4346 }
4347
4348 /*! \internal */
setStartScreenPos(const QPointF & startScreenPos)4349 void QTouchEvent::TouchPoint::setStartScreenPos(const QPointF &startScreenPos)
4350 {
4351 if (d->ref != 1)
4352 d = d->detach();
4353 d->startScreenPos = startScreenPos;
4354 }
4355
4356 /*! \internal */
setStartNormalizedPos(const QPointF & startNormalizedPos)4357 void QTouchEvent::TouchPoint::setStartNormalizedPos(const QPointF &startNormalizedPos)
4358 {
4359 if (d->ref != 1)
4360 d = d->detach();
4361 d->startNormalizedPos = startNormalizedPos;
4362 }
4363
4364 /*! \internal */
setLastPos(const QPointF & lastPos)4365 void QTouchEvent::TouchPoint::setLastPos(const QPointF &lastPos)
4366 {
4367 if (d->ref != 1)
4368 d = d->detach();
4369 d->lastPos = lastPos;
4370 }
4371
4372 /*! \internal */
setLastScenePos(const QPointF & lastScenePos)4373 void QTouchEvent::TouchPoint::setLastScenePos(const QPointF &lastScenePos)
4374 {
4375 if (d->ref != 1)
4376 d = d->detach();
4377 d->lastScenePos = lastScenePos;
4378 }
4379
4380 /*! \internal */
setLastScreenPos(const QPointF & lastScreenPos)4381 void QTouchEvent::TouchPoint::setLastScreenPos(const QPointF &lastScreenPos)
4382 {
4383 if (d->ref != 1)
4384 d = d->detach();
4385 d->lastScreenPos = lastScreenPos;
4386 }
4387
4388 /*! \internal */
setLastNormalizedPos(const QPointF & lastNormalizedPos)4389 void QTouchEvent::TouchPoint::setLastNormalizedPos(const QPointF &lastNormalizedPos)
4390 {
4391 if (d->ref != 1)
4392 d = d->detach();
4393 d->lastNormalizedPos = lastNormalizedPos;
4394 }
4395
4396 /*! \internal */
setRect(const QRectF & rect)4397 void QTouchEvent::TouchPoint::setRect(const QRectF &rect)
4398 {
4399 if (d->ref != 1)
4400 d = d->detach();
4401 d->rect = rect;
4402 }
4403
4404 /*! \internal */
setSceneRect(const QRectF & sceneRect)4405 void QTouchEvent::TouchPoint::setSceneRect(const QRectF &sceneRect)
4406 {
4407 if (d->ref != 1)
4408 d = d->detach();
4409 d->sceneRect = sceneRect;
4410 }
4411
4412 /*! \internal */
setScreenRect(const QRectF & screenRect)4413 void QTouchEvent::TouchPoint::setScreenRect(const QRectF &screenRect)
4414 {
4415 if (d->ref != 1)
4416 d = d->detach();
4417 d->screenRect = screenRect;
4418 }
4419
4420 /*! \internal */
setPressure(qreal pressure)4421 void QTouchEvent::TouchPoint::setPressure(qreal pressure)
4422 {
4423 if (d->ref != 1)
4424 d = d->detach();
4425 d->pressure = pressure;
4426 }
4427
4428 /*! \internal */
operator =(const QTouchEvent::TouchPoint & other)4429 QTouchEvent::TouchPoint &QTouchEvent::TouchPoint::operator=(const QTouchEvent::TouchPoint &other)
4430 {
4431 other.d->ref.ref();
4432 if (!d->ref.deref())
4433 delete d;
4434 d = other.d;
4435 return *this;
4436 }
4437
4438 #ifndef QT_NO_GESTURES
4439 /*!
4440 \class QGestureEvent
4441 \since 4.6
4442 \ingroup events
4443 \ingroup gestures
4444
4445 \brief The QGestureEvent class provides the description of triggered gestures.
4446
4447 The QGestureEvent class contains a list of gestures, which can be obtained using the
4448 gestures() function.
4449
4450 The gestures are either active or canceled. A list of those that are currently being
4451 executed can be obtained using the activeGestures() function. A list of those which
4452 were previously active and have been canceled can be accessed using the
4453 canceledGestures() function. A gesture might be canceled if the current window loses
4454 focus, for example, or because of a timeout, or for other reasons.
4455
4456 If the event handler does not accept the event by calling the generic
4457 QEvent::accept() function, all individual QGesture object that were not
4458 accepted and in the Qt::GestureStarted state will be propagated up the
4459 parent widget chain until a widget accepts them individually, by calling
4460 QGestureEvent::accept() for each of them, or an event filter consumes the
4461 event.
4462
4463 \section1 Further Reading
4464
4465 For an overview of gesture handling in Qt and information on using gestures
4466 in your applications, see the \l{Gestures Programming} document.
4467
4468 \sa QGesture, QGestureRecognizer,
4469 QWidget::grabGesture(), QGraphicsObject::grabGesture()
4470 */
4471
4472 /*!
4473 Creates new QGestureEvent containing a list of \a gestures.
4474 */
QGestureEvent(const QList<QGesture * > & gestures)4475 QGestureEvent::QGestureEvent(const QList<QGesture *> &gestures)
4476 : QEvent(QEvent::Gesture)
4477 {
4478 d = reinterpret_cast<QEventPrivate *>(new QGestureEventPrivate(gestures));
4479 }
4480
4481 /*!
4482 Destroys QGestureEvent.
4483 */
~QGestureEvent()4484 QGestureEvent::~QGestureEvent()
4485 {
4486 delete reinterpret_cast<QGestureEventPrivate *>(d);
4487 }
4488
4489 /*!
4490 Returns all gestures that are delivered in the event.
4491 */
gestures() const4492 QList<QGesture *> QGestureEvent::gestures() const
4493 {
4494 return d_func()->gestures;
4495 }
4496
4497 /*!
4498 Returns a gesture object by \a type.
4499 */
gesture(Qt::GestureType type) const4500 QGesture *QGestureEvent::gesture(Qt::GestureType type) const
4501 {
4502 const QGestureEventPrivate *d = d_func();
4503 for(int i = 0; i < d->gestures.size(); ++i)
4504 if (d->gestures.at(i)->gestureType() == type)
4505 return d->gestures.at(i);
4506 return 0;
4507 }
4508
4509 /*!
4510 Returns a list of active (not canceled) gestures.
4511 */
activeGestures() const4512 QList<QGesture *> QGestureEvent::activeGestures() const
4513 {
4514 QList<QGesture *> gestures;
4515 foreach (QGesture *gesture, d_func()->gestures) {
4516 if (gesture->state() != Qt::GestureCanceled)
4517 gestures.append(gesture);
4518 }
4519 return gestures;
4520 }
4521
4522 /*!
4523 Returns a list of canceled gestures.
4524 */
canceledGestures() const4525 QList<QGesture *> QGestureEvent::canceledGestures() const
4526 {
4527 QList<QGesture *> gestures;
4528 foreach (QGesture *gesture, d_func()->gestures) {
4529 if (gesture->state() == Qt::GestureCanceled)
4530 gestures.append(gesture);
4531 }
4532 return gestures;
4533 }
4534
4535 /*!
4536 Sets the accept flag of the given \a gesture object to the specified \a value.
4537
4538 Setting the accept flag indicates that the event receiver wants the \a gesture.
4539 Unwanted gestures may be propagated to the parent widget.
4540
4541 By default, gestures in events of type QEvent::Gesture are accepted, and
4542 gestures in QEvent::GestureOverride events are ignored.
4543
4544 For convenience, the accept flag can also be set with
4545 \l{QGestureEvent::accept()}{accept(gesture)}, and cleared with
4546 \l{QGestureEvent::ignore()}{ignore(gesture)}.
4547 */
setAccepted(QGesture * gesture,bool value)4548 void QGestureEvent::setAccepted(QGesture *gesture, bool value)
4549 {
4550 if (gesture)
4551 setAccepted(gesture->gestureType(), value);
4552 }
4553
4554 /*!
4555 Sets the accept flag of the given \a gesture object, the equivalent of calling
4556 \l{QGestureEvent::setAccepted()}{setAccepted(gesture, true)}.
4557
4558 Setting the accept flag indicates that the event receiver wants the
4559 gesture. Unwanted gestures may be propagated to the parent widget.
4560
4561 \sa QGestureEvent::ignore()
4562 */
accept(QGesture * gesture)4563 void QGestureEvent::accept(QGesture *gesture)
4564 {
4565 if (gesture)
4566 setAccepted(gesture->gestureType(), true);
4567 }
4568
4569 /*!
4570 Clears the accept flag parameter of the given \a gesture object, the equivalent
4571 of calling \l{QGestureEvent::setAccepted()}{setAccepted(gesture, false)}.
4572
4573 Clearing the accept flag indicates that the event receiver does not
4574 want the gesture. Unwanted gestures may be propagated to the parent widget.
4575
4576 \sa QGestureEvent::accept()
4577 */
ignore(QGesture * gesture)4578 void QGestureEvent::ignore(QGesture *gesture)
4579 {
4580 if (gesture)
4581 setAccepted(gesture->gestureType(), false);
4582 }
4583
4584 /*!
4585 Returns true if the \a gesture is accepted; otherwise returns false.
4586 */
isAccepted(QGesture * gesture) const4587 bool QGestureEvent::isAccepted(QGesture *gesture) const
4588 {
4589 return gesture ? isAccepted(gesture->gestureType()) : false;
4590 }
4591
4592 /*!
4593 Sets the accept flag of the given \a gestureType object to the specified
4594 \a value.
4595
4596 Setting the accept flag indicates that the event receiver wants to receive
4597 gestures of the specified type, \a gestureType. Unwanted gestures may be
4598 propagated to the parent widget.
4599
4600 By default, gestures in events of type QEvent::Gesture are accepted, and
4601 gestures in QEvent::GestureOverride events are ignored.
4602
4603 For convenience, the accept flag can also be set with
4604 \l{QGestureEvent::accept()}{accept(gestureType)}, and cleared with
4605 \l{QGestureEvent::ignore()}{ignore(gestureType)}.
4606 */
setAccepted(Qt::GestureType gestureType,bool value)4607 void QGestureEvent::setAccepted(Qt::GestureType gestureType, bool value)
4608 {
4609 setAccepted(false);
4610 d_func()->accepted[gestureType] = value;
4611 }
4612
4613 /*!
4614 Sets the accept flag of the given \a gestureType, the equivalent of calling
4615 \l{QGestureEvent::setAccepted()}{setAccepted(gestureType, true)}.
4616
4617 Setting the accept flag indicates that the event receiver wants the
4618 gesture. Unwanted gestures may be propagated to the parent widget.
4619
4620 \sa QGestureEvent::ignore()
4621 */
accept(Qt::GestureType gestureType)4622 void QGestureEvent::accept(Qt::GestureType gestureType)
4623 {
4624 setAccepted(gestureType, true);
4625 }
4626
4627 /*!
4628 Clears the accept flag parameter of the given \a gestureType, the equivalent
4629 of calling \l{QGestureEvent::setAccepted()}{setAccepted(gesture, false)}.
4630
4631 Clearing the accept flag indicates that the event receiver does not
4632 want the gesture. Unwanted gestures may be propgated to the parent widget.
4633
4634 \sa QGestureEvent::accept()
4635 */
ignore(Qt::GestureType gestureType)4636 void QGestureEvent::ignore(Qt::GestureType gestureType)
4637 {
4638 setAccepted(gestureType, false);
4639 }
4640
4641 /*!
4642 Returns true if the gesture of type \a gestureType is accepted; otherwise
4643 returns false.
4644 */
isAccepted(Qt::GestureType gestureType) const4645 bool QGestureEvent::isAccepted(Qt::GestureType gestureType) const
4646 {
4647 return d_func()->accepted.value(gestureType, true);
4648 }
4649
4650 /*!
4651 \internal
4652
4653 Sets the widget for this event to the \a widget specified.
4654 */
setWidget(QWidget * widget)4655 void QGestureEvent::setWidget(QWidget *widget)
4656 {
4657 d_func()->widget = widget;
4658 }
4659
4660 /*!
4661 Returns the widget on which the event occurred.
4662 */
widget() const4663 QWidget *QGestureEvent::widget() const
4664 {
4665 return d_func()->widget;
4666 }
4667
4668 #ifndef QT_NO_GRAPHICSVIEW
4669 /*!
4670 Returns the scene-local coordinates if the \a gesturePoint is inside a
4671 graphics view.
4672
4673 This functional might be useful when the gesture event is delivered to a
4674 QGraphicsObject to translate a point in screen coordinates to scene-local
4675 coordinates.
4676
4677 \sa QPointF::isNull().
4678 */
mapToGraphicsScene(const QPointF & gesturePoint) const4679 QPointF QGestureEvent::mapToGraphicsScene(const QPointF &gesturePoint) const
4680 {
4681 QWidget *w = widget();
4682 if (w) // we get the viewport as widget, not the graphics view
4683 w = w->parentWidget();
4684 QGraphicsView *view = qobject_cast<QGraphicsView*>(w);
4685 if (view) {
4686 return view->mapToScene(view->mapFromGlobal(gesturePoint.toPoint()));
4687 }
4688 return QPointF();
4689 }
4690 #endif //QT_NO_GRAPHICSVIEW
4691
4692 /*!
4693 \internal
4694 */
d_func()4695 QGestureEventPrivate *QGestureEvent::d_func()
4696 {
4697 return reinterpret_cast<QGestureEventPrivate *>(d);
4698 }
4699
4700 /*!
4701 \internal
4702 */
d_func() const4703 const QGestureEventPrivate *QGestureEvent::d_func() const
4704 {
4705 return reinterpret_cast<const QGestureEventPrivate *>(d);
4706 }
4707
4708 #ifdef Q_NO_USING_KEYWORD
4709 /*!
4710 \fn void QGestureEvent::setAccepted(bool accepted)
4711
4712 Sets or clears the event's internal flag that determines whether it should
4713 be delivered to other objects.
4714
4715 Calling this function with a value of true for \a accepted indicates that the
4716 caller has accepted the event and that it should not be propagated further.
4717 Calling this function with a value of false indicates that the caller has
4718 ignored the event and that it should be delivered to other objects.
4719
4720 For convenience, the accept flag can also be set with accept(), and cleared
4721 with ignore().
4722
4723 \sa QEvent::accepted
4724 */
4725 /*!
4726 \fn bool QGestureEvent::isAccepted() const
4727
4728 Returns true is the event has been accepted; otherwise returns false.
4729
4730 \sa QEvent::accepted
4731 */
4732 /*!
4733 \fn void QGestureEvent::accept()
4734
4735 Accepts the event, the equivalent of calling setAccepted(true).
4736
4737 \sa QEvent::accept()
4738 */
4739 /*!
4740 \fn void QGestureEvent::ignore()
4741
4742 Ignores the event, the equivalent of calling setAccepted(false).
4743
4744 \sa QEvent::ignore()
4745 */
4746 #endif
4747
4748 #endif // QT_NO_GESTURES
4749
4750 QT_END_NAMESPACE
4751