1QWidget(3qt) QWidget(3qt)
2
6 QWidget - The base class of all user interface objects
7
9 #include <qwidget.h>
10 Inherits QObject and QPaintDevice.
12 Inherited by QAxWidget, QButton, QFrame, QDialog, QComboBox,
14 QDataBrowser, QDataView, QDateTimeEditBase, QDateTimeEdit,
15 QDesktopWidget, QDial, QDockArea, QGLWidget, QHeader, QMainWindow,
16 QMotifWidget, QNPWidget, QScrollBar, QSizeGrip, QSlider, QSpinBox,
17 QSplashScreen, QStatusBar, QTabBar, QTabWidget, QWorkspace, and
18 QXtWidget.
19 Public Members
21 explicit QWidget ( QWidget * parent = 0, const char * name = 0, WFlags
22 f = 0 )
23 ~QWidget ()
24 WId winId () const
25 QStyle & style () const
26 void setStyle ( QStyle * style )
27 QStyle * setStyle ( const QString & style )
28 bool isTopLevel () const
29 bool isDialog () const
30 bool isPopup () const
31 bool isDesktop () const
32 bool isModal () const
33 bool isEnabled () const
34 bool isEnabledTo ( QWidget * ancestor ) const
35 bool isEnabledToTLW () const (obsolete)
36 QRect frameGeometry () const
37 const QRect & geometry () const
38 int x () const
39 int y () const
40 QPoint pos () const
41 QSize frameSize () const
42 QSize size () const
43 int width () const
44 int height () const
45 QRect rect () const
46 QRect childrenRect () const
47 QRegion childrenRegion () const
48 QSize minimumSize () const
49 QSize maximumSize () const
50 int minimumWidth () const
51 int minimumHeight () const
52 int maximumWidth () const
53 int maximumHeight () const
54 void setMinimumSize ( const QSize & )
55 virtual void setMinimumSize ( int minw, int minh )
56 void setMaximumSize ( const QSize & )
57 virtual void setMaximumSize ( int maxw, int maxh )
58 void setMinimumWidth ( int minw )
59 void setMinimumHeight ( int minh )
60 void setMaximumWidth ( int maxw )
61 void setMaximumHeight ( int maxh )
62 QSize sizeIncrement () const
63 void setSizeIncrement ( const QSize & )
64 virtual void setSizeIncrement ( int w, int h )
65 QSize baseSize () const
66 void setBaseSize ( const QSize & )
67 void setBaseSize ( int basew, int baseh )
68 void setFixedSize ( const QSize & s )
69 void setFixedSize ( int w, int h )
70 void setFixedWidth ( int w )
71 void setFixedHeight ( int h )
72 QPoint mapToGlobal ( const QPoint & pos ) const
73 QPoint mapFromGlobal ( const QPoint & pos ) const
74 QPoint mapToParent ( const QPoint & pos ) const
75 QPoint mapFromParent ( const QPoint & pos ) const
76 QPoint mapTo ( QWidget * parent, const QPoint & pos ) const
77 QPoint mapFrom ( QWidget * parent, const QPoint & pos ) const
78 QWidget * topLevelWidget () const
79 BackgroundMode backgroundMode () const
80 virtual void setBackgroundMode ( BackgroundMode )
81 void setBackgroundMode ( BackgroundMode m, BackgroundMode visual )
82 const QColor & foregroundColor () const
83 const QColor & eraseColor () const
84 virtual void setEraseColor ( const QColor & color )
85 const QPixmap * erasePixmap () const
86 virtual void setErasePixmap ( const QPixmap & pixmap )
87 const QColorGroup & colorGroup () const
88 const QPalette & palette () const
89 bool ownPalette () const
90 virtual void setPalette ( const QPalette & )
91 void unsetPalette ()
92 const QColor & paletteForegroundColor () const
93 void setPaletteForegroundColor ( const QColor & )
94 const QColor & paletteBackgroundColor () const
95 virtual void setPaletteBackgroundColor ( const QColor & )
96 const QPixmap * paletteBackgroundPixmap () const
97 virtual void setPaletteBackgroundPixmap ( const QPixmap & )
98 const QBrush & backgroundBrush () const
99 QFont font () const
100 bool ownFont () const
101 virtual void setFont ( const QFont & )
102 void unsetFont ()
103 QFontMetrics fontMetrics () const
104 QFontInfo fontInfo () const
105 const QCursor & cursor () const
106 bool ownCursor () const
107 virtual void setCursor ( const QCursor & )
108 virtual void unsetCursor ()
109 QString caption () const
110 const QPixmap * icon () const
111 QString iconText () const
112 bool hasMouseTracking () const
113 bool hasMouse () const
114 virtual void setMask ( const QBitmap & bitmap )
115 virtual void setMask ( const QRegion & region )
116 void clearMask ()
117 const QColor & backgroundColor () const (obsolete)
118 virtual void setBackgroundColor ( const QColor & c ) (obsolete)
119 const QPixmap * backgroundPixmap () const (obsolete)
120 virtual void setBackgroundPixmap ( const QPixmap & pm ) (obsolete)
121 enum FocusPolicy { NoFocus = 0, TabFocus = 0x1, ClickFocus = 0x2,
122 StrongFocus = TabFocus | ClickFocus | 0x8, WheelFocus = StrongFocus
123 | 0x4 }
124 bool isActiveWindow () const
125 virtual void setActiveWindow ()
126 bool isFocusEnabled () const
127 FocusPolicy focusPolicy () const
128 virtual void setFocusPolicy ( FocusPolicy )
129 bool hasFocus () const
130 virtual void setFocusProxy ( QWidget * w )
131 QWidget * focusProxy () const
132 void setInputMethodEnabled ( bool b )
133 bool isInputMethodEnabled () const
134 void grabMouse ()
135 void grabMouse ( const QCursor & cursor )
136 void releaseMouse ()
137 void grabKeyboard ()
138 void releaseKeyboard ()
139 bool isUpdatesEnabled () const
140 virtual bool close ( bool alsoDelete )
141 bool isVisible () const
142 bool isVisibleTo ( QWidget * ancestor ) const
143 bool isVisibleToTLW () const (obsolete)
144 QRect visibleRect () const (obsolete)
145 bool isHidden () const
146 bool isShown () const
147 bool isMinimized () const
148 bool isMaximized () const
149 bool isFullScreen () const
150 uint windowState () const
151 void setWindowState ( uint windowState )
152 virtual QSize sizeHint () const
153 virtual QSize minimumSizeHint () const
154 virtual QSizePolicy sizePolicy () const
155 virtual void setSizePolicy ( QSizePolicy )
156 void setSizePolicy ( QSizePolicy::SizeType hor, QSizePolicy::SizeType
157 ver, bool hfw = FALSE )
158 virtual int heightForWidth ( int w ) const
159 QRegion clipRegion () const
160 QLayout * layout () const
161 void updateGeometry ()
162 virtual void reparent ( QWidget * parent, WFlags f, const QPoint & p,
163 bool showIt = FALSE )
164 void reparent ( QWidget * parent, const QPoint & p, bool showIt = FALSE
165 )
166 void recreate ( QWidget * parent, WFlags f, const QPoint & p, bool
167 showIt = FALSE ) (obsolete)
168 void erase ()
169 void erase ( int x, int y, int w, int h )
170 void erase ( const QRect & r )
171 void erase ( const QRegion & reg )
172 void scroll ( int dx, int dy )
173 void scroll ( int dx, int dy, const QRect & r )
174 void drawText ( int x, int y, const QString & str )
175 void drawText ( const QPoint & pos, const QString & str )
176 QWidget * focusWidget () const
177 QRect microFocusHint () const
178 bool acceptDrops () const
179 virtual void setAcceptDrops ( bool on )
180 virtual void setAutoMask ( bool )
181 bool autoMask () const
182 enum BackgroundOrigin { WidgetOrigin, ParentOrigin, WindowOrigin,
183 AncestorOrigin }
184 virtual void setBackgroundOrigin ( BackgroundOrigin )
185 BackgroundOrigin backgroundOrigin () const
186 virtual bool customWhatsThis () const
187 QWidget * parentWidget ( bool sameWindow = FALSE ) const
188 WFlags testWFlags ( WFlags f ) const
189 QWidget * childAt ( int x, int y, bool includeThis = FALSE ) const
190 QWidget * childAt ( const QPoint & p, bool includeThis = FALSE ) const
191 void setWindowOpacity ( double level )
192 double windowOpacity () const
193 void setPalette ( const QPalette & p, bool ) (obsolete)
194 void setFont ( const QFont & f, bool ) (obsolete)
195 Public Slots
197 virtual void setEnabled ( bool )
198 void setDisabled ( bool disable )
199 virtual void setCaption ( const QString & )
200 virtual void setIcon ( const QPixmap & )
201 virtual void setIconText ( const QString & )
202 virtual void setMouseTracking ( bool enable )
203 virtual void setFocus ()
204 void clearFocus ()
205 virtual void setUpdatesEnabled ( bool enable )
206 void update ()
207 void update ( int x, int y, int w, int h )
208 void update ( const QRect & r )
209 void repaint ()
210 void repaint ( bool erase )
211 void repaint ( int x, int y, int w, int h, bool erase = TRUE )
212 void repaint ( const QRect & r, bool erase = TRUE )
213 void repaint ( const QRegion & reg, bool erase = TRUE )
214 virtual void show ()
215 virtual void hide ()
216 void setShown ( bool show )
217 void setHidden ( bool hide )
218 void iconify () (obsolete)
219 virtual void showMinimized ()
220 virtual void showMaximized ()
221 void showFullScreen ()
222 virtual void showNormal ()
223 virtual void polish ()
224 void constPolish () const
225 bool close ()
226 void raise ()
227 void lower ()
228 void stackUnder ( QWidget * w )
229 virtual void move ( int x, int y )
230 void move ( const QPoint & )
231 virtual void resize ( int w, int h )
232 void resize ( const QSize & )
233 virtual void setGeometry ( int x, int y, int w, int h )
234 virtual void setGeometry ( const QRect & )
235 virtual void adjustSize ()
236 Static Public Members
238 void setTabOrder ( QWidget * first, QWidget * second )
239 QWidget * mouseGrabber ()
240 QWidget * keyboardGrabber ()
241 QWidget * find ( WId id )
242 Properties
244 bool acceptDrops - whether drop events are enabled for this widget
245 bool autoMask - whether the auto mask feature is enabled for the widget
246 QBrush backgroundBrush - the widget's background brush (read only)
247 BackgroundMode backgroundMode - the color role used for painting the
248 background of the widget
249 BackgroundOrigin backgroundOrigin - the origin of the widget's
250 background
251 QSize baseSize - the base size of the widget
252 QString caption - the window caption (title)
253 QRect childrenRect - the bounding rectangle of the widget's children
254 (read only)
255 QRegion childrenRegion - the combined region occupied by the widget's
256 children (read only)
257 QColorGroup colorGroup - the current color group of the widget palette
258 (read only)
259 QCursor cursor - the cursor shape for this widget
260 bool customWhatsThis - whether the widget wants to handle What's This
261 help manually (read only)
262 bool enabled - whether the widget is enabled
263 bool focus - whether this widget (or its focus proxy) has the keyboard
264 input focus (read only)
265 bool focusEnabled - whether the widget accepts keyboard focus (read
266 only)
267 FocusPolicy focusPolicy - the way the widget accepts keyboard focus
268 QFont font - the font currently set for the widget
269 QRect frameGeometry - geometry of the widget relative to its parent
270 including any window frame (read only)
271 QSize frameSize - the size of the widget including any window frame
272 (read only)
273 bool fullScreen - whether the widget is full screen (read only)
274 QRect geometry - the geometry of the widget relative to its parent and
275 excluding the window frame
276 int height - the height of the widget excluding any window frame (read
277 only)
278 bool hidden - whether the widget is explicitly hidden
279 QPixmap icon - the widget's icon
280 QString iconText - the widget's icon text
281 bool inputMethodEnabled - enables or disables the use of input methods
282 for this widget
283 bool isActiveWindow - whether this widget is the active window (read
284 only)
285 bool isDesktop - whether the widget is a desktop widget, i.e.
286 represents the desktop (read only)
287 bool isDialog - whether the widget is a dialog widget (read only)
288 bool isModal - whether the widget is a modal widget (read only)
289 bool isPopup - whether the widget is a popup widget (read only)
290 bool isTopLevel - whether the widget is a top-level widget (read only)
291 bool maximized - whether this widget is maximized (read only)
292 int maximumHeight - the widget's maximum height
293 QSize maximumSize - the widget's maximum size
294 int maximumWidth - the widget's maximum width
295 QRect microFocusHint - the currently set micro focus hint for this
296 widget (read only)
297 bool minimized - whether this widget is minimized (iconified) (read
298 only)
299 int minimumHeight - the widget's minimum height
300 QSize minimumSize - the widget's minimum size
301 QSize minimumSizeHint - the recommended minimum size for the widget
302 (read only)
303 int minimumWidth - the widget's minimum width
304 bool mouseTracking - whether mouse tracking is enabled for the widget
305 bool ownCursor - whether the widget uses its own cursor (read only)
306 bool ownFont - whether the widget uses its own font (read only)
307 bool ownPalette - whether the widget uses its own palette (read only)
308 QPalette palette - the widget's palette
309 QColor paletteBackgroundColor - the background color of the widget
310 QPixmap paletteBackgroundPixmap - the background pixmap of the widget
311 QColor paletteForegroundColor - the foreground color of the widget
312 QPoint pos - the position of the widget within its parent widget
313 QRect rect - the internal geometry of the widget excluding any window
314 frame (read only)
315 bool shown - whether the widget is shown
316 QSize size - the size of the widget excluding any window frame
317 QSize sizeHint - the recommended size for the widget (read only)
318 QSize sizeIncrement - the size increment of the widget
319 QSizePolicy sizePolicy - the default layout behavior of the widget
320 bool underMouse - whether the widget is under the mouse cursor (read
321 only)
322 bool updatesEnabled - whether updates are enabled
323 bool visible - whether the widget is visible (read only)
324 QRect visibleRect - the visible rectangle (read only) (obsolete)
325 int width - the width of the widget excluding any window frame (read
326 only)
327 double windowOpacity - the level of opacity for the window
328 int x - the x coordinate of the widget relative to its parent including
329 any window frame (read only)
330 int y - the y coordinate of the widget relative to its parent and
331 including any window frame (read only)
332 Protected Members
334 virtual bool event ( QEvent * e )
335 virtual void mousePressEvent ( QMouseEvent * e )
336 virtual void mouseReleaseEvent ( QMouseEvent * e )
337 virtual void mouseDoubleClickEvent ( QMouseEvent * e )
338 virtual void mouseMoveEvent ( QMouseEvent * e )
339 virtual void wheelEvent ( QWheelEvent * e )
340 virtual void keyPressEvent ( QKeyEvent * e )
341 virtual void keyReleaseEvent ( QKeyEvent * e )
342 virtual void focusInEvent ( QFocusEvent * )
343 virtual void focusOutEvent ( QFocusEvent * )
344 virtual void enterEvent ( QEvent * )
345 virtual void leaveEvent ( QEvent * )
346 virtual void paintEvent ( QPaintEvent * )
347 virtual void moveEvent ( QMoveEvent * )
348 virtual void resizeEvent ( QResizeEvent * )
349 virtual void closeEvent ( QCloseEvent * e )
350 virtual void contextMenuEvent ( QContextMenuEvent * e )
351 virtual void imStartEvent ( QIMEvent * e )
352 virtual void imComposeEvent ( QIMEvent * e )
353 virtual void imEndEvent ( QIMEvent * e )
354 virtual void tabletEvent ( QTabletEvent * e )
355 virtual void dragEnterEvent ( QDragEnterEvent * )
356 virtual void dragMoveEvent ( QDragMoveEvent * )
357 virtual void dragLeaveEvent ( QDragLeaveEvent * )
358 virtual void dropEvent ( QDropEvent * )
359 virtual void showEvent ( QShowEvent * )
360 virtual void hideEvent ( QHideEvent * )
361 virtual bool macEvent ( MSG * )
362 virtual bool winEvent ( MSG * )
363 virtual bool x11Event ( XEvent * )
364 virtual bool qwsEvent ( QWSEvent * )
365 virtual void updateMask ()
366 virtual void styleChange ( QStyle & oldStyle )
367 virtual void enabledChange ( bool oldEnabled )
368 virtual void paletteChange ( const QPalette & oldPalette )
369 virtual void fontChange ( const QFont & oldFont )
370 virtual void windowActivationChange ( bool oldActive )
371 virtual int metric ( int m ) const
372 void resetInputContext ()
373 virtual void create ( WId window = 0, bool initializeWindow = TRUE,
374 bool destroyOldWindow = TRUE )
375 virtual void destroy ( bool destroyWindow = TRUE, bool
376 destroySubWindows = TRUE )
377 WFlags getWFlags () const
378 virtual void setWFlags ( WFlags f )
379 void clearWFlags ( WFlags f )
380 virtual bool focusNextPrevChild ( bool next )
381 QFocusData * focusData ()
382 virtual void setKeyCompression ( bool compress )
383 virtual void setMicroFocusHint ( int x, int y, int width, int height,
384 bool text = TRUE, QFont * f = 0 )
385
387 The QWidget class is the base class of all user interface objects.
388 The widget is the atom of the user interface: it receives mouse,
390 keyboard and other events from the window system, and paints a
391 representation of itself on the screen. Every widget is rectangular,
392 and they are sorted in a Z-order. A widget is clipped by its parent and
393 by the widgets in front of it.
394 A widget that isn't embedded in a parent widget is called a top-level
396 widget. Usually, top-level widgets are windows with a frame and a title
397 bar (although it is also possible to create top-level widgets without
398 such decoration if suitable widget flags are used). In Qt, QMainWindow
399 and the various subclasses of QDialog are the most common top-level
400 windows.
401 A widget without a parent widget is always a top-level widget.
403 Non-top-level widgets are child widgets. These are child windows in
405 their parent widgets. You cannot usually distinguish a child widget
406 from its parent visually. Most other widgets in Qt are useful only as
407 child widgets. (It is possible to make, say, a button into a top-level
408 widget, but most people prefer to put their buttons inside other
409 widgets, e.g. QDialog.)
410 If you want to use a QWidget to hold child widgets you will probably
412 want to add a layout to the parent QWidget. (See Layouts.)
413 QWidget has many member functions, but some of them have little direct
415 functionality: for example, QWidget has a font property, but never uses
416 this itself. There are many subclasses which provide real
417 functionality, such as QPushButton, QListBox and QTabDialog, etc.
418
420 <center>.nf
421 </center>
423 Every widget's constructor accepts two or three standard arguments: <ol
425 type=1>
426 1 QWidget *parent = 0 is the parent of the new widget. If it is 0
428 (the default), the new widget will be a top-level window. If
429 not, it will be a child of parent, and be constrained by
430 parent's geometry (unless you specify WType_TopLevel as widget
431 flag).
432 2 const char *name = 0 is the widget name of the new widget. You
434 can access it using name(). The widget name is little used by
435 programmers but is quite useful with GUI builders such as Qt
436 Designer (you can name a widget in Qt Designer, and connect() to
437 it using the name in your code). The dumpObjectTree() debugging
438 function also uses it.
439 3 WFlags f = 0 (where available) sets the widget flags; the
441 default is suitable for almost all widgets, but to get, for
442 example, a top-level widget without a window system frame, you
443 must use special flags.
444 The tictac/tictac.cpp example program is good example of a simple
446 widget. It contains a few event handlers (as all widgets must), a few
447 custom routines that are specific to it (as all useful widgets do), and
448 has a few children and connections. Everything it does is done in
449 response to an event: this is by far the most common way to design GUI
450 applications.
451 You will need to supply the content for your widgets yourself, but here
453 is a brief run-down of the events, starting with the most common ones:
454 paintEvent() - called whenever the widget needs to be repainted. Every
456 widget which displays output must implement it, and it is wise not to
457 paint on the screen outside paintEvent().
458 resizeEvent() - called when the widget has been resized.
460 mousePressEvent() - called when a mouse button is pressed. There are
462 six mouse-related events, but the mouse press and mouse release events
463 are by far the most important. A widget receives mouse press events
464 when the mouse is inside it, or when it has grabbed the mouse using
465 grabMouse().
466 mouseReleaseEvent() - called when a mouse button is released. A widget
468 receives mouse release events when it has received the corresponding
469 mouse press event. This means that if the user presses the mouse inside
470 your widget, then drags the mouse to somewhere else, then releases,
471 your widget receives the release event. There is one exception: if a
472 popup menu appears while the mouse button is held down, this popup
473 immediately steals the mouse events.
474 mouseDoubleClickEvent() - not quite as obvious as it might seem. If the
476 user double-clicks, the widget receives a mouse press event (perhaps a
477 mouse move event or two if they don't hold the mouse quite steady), a
478 mouse release event and finally this event. It is not possible to
479 distinguish a click from a double click until you've seen whether the
480 second click arrives. (This is one reason why most GUI books recommend
481 that double clicks be an extension of single clicks, rather than
482 trigger a different action.)
483 If your widget only contains child widgets, you probably do not need to
485 implement any event handlers. If you want to detect a mouse click in a
486 child widget call the child's hasMouse() function inside the parent
487 widget's mousePressEvent().
488 Widgets that accept keyboard input need to reimplement a few more event
490 handlers:
491 keyPressEvent() - called whenever a key is pressed, and again when a
493 key has been held down long enough for it to auto-repeat. Note that the
494 Tab and Shift+Tab keys are only passed to the widget if they are not
495 used by the focus-change mechanisms. To force those keys to be
496 processed by your widget, you must reimplement QWidget::event().
497 focusInEvent() - called when the widget gains keyboard focus (assuming
499 you have called setFocusPolicy()). Well written widgets indicate that
500 they own the keyboard focus in a clear but discreet way.
501 focusOutEvent() - called when the widget loses keyboard focus.
503 Some widgets will also need to reimplement some of the less common
505 event handlers:
506 mouseMoveEvent() - called whenever the mouse moves while a button is
508 held down. This is useful for, for example, dragging. If you call
509 setMouseTracking(TRUE), you get mouse move events even when no buttons
510 are held down. (Note that applications which make use of mouse tracking
511 are often not very useful on low-bandwidth X connections.) (See also
512 the drag and drop information.)
513 keyReleaseEvent() - called whenever a key is released, and also while
515 it is held down if the key is auto-repeating. In that case the widget
516 receives a key release event and immediately a key press event for
517 every repeat. Note that the Tab and Shift+Tab keys are only passed to
518 the widget if they are not used by the focus-change mechanisms. To
519 force those keys to be processed by your widget, you must reimplement
520 QWidget::event().
521 wheelEvent() -- called whenever the user turns the mouse wheel while
523 the widget has the focus.
524 enterEvent() - called when the mouse enters the widget's screen space.
526 (This excludes screen space owned by any children of the widget.)
527 leaveEvent() - called when the mouse leaves the widget's screen space.
529 moveEvent() - called when the widget has been moved relative to its
531 parent.
532 closeEvent() - called when the user closes the widget (or when close()
534 is called).
535 There are also some rather obscure events. They are listed in qevent.h
537 and you need to reimplement event() to handle them. The default
538 implementation of event() handles Tab and Shift+Tab (to move the
539 keyboard focus), and passes on most other events to one of the more
540 specialized handlers above.
541 When implementing a widget, there are a few more things to consider.
543 In the constructor, be sure to set up your member variables early on,
545 before there's any chance that you might receive an event.
546 It is almost always useful to reimplement sizeHint() and to set the
548 correct size policy with setSizePolicy(), so users of your class can
549 set up layout management more easily. A size policy lets you supply
550 good defaults for the layout management handling, so that other widgets
551 can contain and manage yours easily. sizeHint() indicates a "good" size
552 for the widget.
553 If your widget is a top-level window, setCaption() and setIcon() set
555 the title bar and icon respectively.
556 See also QEvent, QPainter, QGridLayout, QBoxLayout, and Abstract Widget
558 Classes.
559 Member Type Documentation
562 This enum defines the origin used to draw a widget's background pixmap.
563 The pixmap is drawn using the:
565 QWidget::WidgetOrigin - widget's coordinate system.
567 QWidget::ParentOrigin - parent's coordinate system.
569 QWidget::WindowOrigin - top-level window's coordinate system.
571 QWidget::AncestorOrigin - same origin as the parent uses.
573
575 This enum type defines the various policies a widget can have with
576 respect to acquiring keyboard focus.
577 QWidget::TabFocus - the widget accepts focus by tabbing.
579 QWidget::ClickFocus - the widget accepts focus by clicking.
581 QWidget::StrongFocus - the widget accepts focus by both tabbing and
583 clicking. On Mac OS X this will also be indicate that the widget
584 accepts tab focus when in 'Text/List focus mode'.
585 QWidget::WheelFocus - like StrongFocus plus the widget accepts focus by
587 using the mouse wheel.
588 QWidget::NoFocus - the widget does not accept focus.
590
593 WFlags f = 0 )
594 Constructs a widget which is a child of parent, with the name name and
595 widget flags set to f.
596 If parent is 0, the new widget becomes a top-level window. If parent is
598 another widget, this widget becomes a child window inside parent. The
599 new widget is deleted when its parent is deleted.
600 The name is sent to the QObject constructor.
602 The widget flags argument, f, is normally 0, but it can be set to
604 customize the window frame of a top-level widget (i.e. parent must be
605 0). To customize the frame, set the WStyle_Customize flag OR'ed with
606 any of the Qt::WidgetFlags.
607 If you add a child widget to an already visible widget you must
609 explicitly show the child to make it visible.
610 Note that the X11 version of Qt may not be able to deliver all
612 combinations of style flags on all systems. This is because on X11, Qt
613 can only ask the window manager, and the window manager can override
614 the application's settings. On Windows, Qt can set whatever flags you
615 want.
616 Example:
618 QLabel *splashScreen = new QLabel( 0, "mySplashScreen",
620 WStyle_Customize | WStyle_Splash );
621
623 Destroys the widget.
624 All this widget's children are deleted first. The application exits if
626 this widget is the main widget.
627
629 Returns TRUE if drop events are enabled for this widget; otherwise
630 returns FALSE. See the "acceptDrops" property for details.
631
633 Adjusts the size of the widget to fit the contents.
634 Uses sizeHint() if valid (i.e if the size hint's width and height are
636 >= 0), otherwise sets the size to the children rectangle (the union of
637 all child widget geometries).
638 See also sizeHint and childrenRect.
640 Example: xform/xform.cpp.
642 Reimplemented in QMessageBox.
644
646 Returns TRUE if the auto mask feature is enabled for the widget;
647 otherwise returns FALSE. See the "autoMask" property for details.
648
650 Returns the widget's background brush. See the "backgroundBrush"
651 property for details.
652
654 This function is obsolete. It is provided to keep old source working.
655 We strongly advise against using it in new code. Use
656 paletteBackgroundColor() or eraseColor() instead.
657
659 Returns the color role used for painting the background of the widget.
660 See the "backgroundMode" property for details.
661
663 Returns the origin of the widget's background. See the
664 "backgroundOrigin" property for details.
665
667 This function is obsolete. It is provided to keep old source working.
668 We strongly advise against using it in new code. Use
669 paletteBackgroundPixmap() or erasePixmap() instead.
670 Examples:
672
674 Returns the base size of the widget. See the "baseSize" property for
675 details.
676
678 Returns the window caption (title). See the "caption" property for
679 details.
680
682 Returns the visible child widget at pixel position (x, y) in the
683 widget's own coordinate system.
684 If includeThis is TRUE, and there is no child visible at (x, y), the
686 widget itself is returned.
687
689 const
690 This is an overloaded member function, provided for convenience. It
691 behaves essentially like the above function.
692 Returns the visible child widget at point p in the widget's own
694 coordinate system.
695 If includeThis is TRUE, and there is no child visible at p, the widget
697 itself is returned.
698
700 Returns the bounding rectangle of the widget's children. See the
701 "childrenRect" property for details.
702
704 Returns the combined region occupied by the widget's children. See the
705 "childrenRegion" property for details.
706
708 Takes keyboard input focus from the widget.
709 If the widget has active focus, a focus out event is sent to this
711 widget to tell it that it is about to lose the focus.
712 This widget must enable focus setting in order to get the keyboard
714 input focus, i.e. it must call setFocusPolicy().
715 See also focus, setFocus(), focusInEvent(), focusOutEvent(),
717 focusPolicy, and QApplication::focusWidget().
718
720 Removes any mask set by setMask().
721 See also setMask().
723
725 Clears the widget flags f.
726 Widget flags are a combination of Qt::WidgetFlags.
728 See also testWFlags(), getWFlags(), and setWFlags().
730
732 Returns the unobscured region where paint events can occur.
733 For visible widgets, this is an approximation of the area not covered
735 by other widgets; otherwise, this is an empty region.
736 The repaint() function calls this function if necessary, so in general
738 you do not need to call it.
739
741 Closes this widget. Returns TRUE if the widget was closed; otherwise
742 returns FALSE.
743 First it sends the widget a QCloseEvent. The widget is hidden if it
745 accepts the close event. The default implementation of
746 QWidget::closeEvent() accepts the close event.
747 The QApplication::lastWindowClosed() signal is emitted when the last
749 visible top level widget is closed.
750 Examples:
752
754 This is an overloaded member function, provided for convenience. It
755 behaves essentially like the above function.
756 Closes this widget. Returns TRUE if the widget was closed; otherwise
758 returns FALSE.
759 If alsoDelete is TRUE or the widget has the WDestructiveClose widget
761 flag, the widget is also deleted. The widget can prevent itself from
762 being closed by rejecting the QCloseEvent it gets. A close events is
763 delivered to the widget no matter if the widget is visible or not.
764 The QApplication::lastWindowClosed() signal is emitted when the last
766 visible top level widget is closed.
767 Note that closing the QApplication::mainWidget() terminates the
769 application.
770 See also closeEvent(), QCloseEvent, hide(), QApplication::quit(),
772 QApplication::setMainWidget(), and QApplication::lastWindowClosed().
773
775 This event handler, for event e, can be reimplemented in a subclass to
776 receive widget close events.
777 The default implementation calls e->accept(), which hides this widget.
779 See the QCloseEvent documentation for more details.
780 See also event(), hide(), close(), and QCloseEvent.
782 Examples:
784
786 Returns the current color group of the widget palette. See the
787 "colorGroup" property for details.
788
790 Ensures that the widget is properly initialized by calling polish().
791 Call constPolish() from functions like sizeHint() that depends on the
793 widget being initialized, and that may be called before show().
794 Warning: Do not call constPolish() on a widget from inside that
796 widget's constructor.
797 See also polish().
799
801 This event handler, for event e, can be reimplemented in a subclass to
802 receive widget context menu events.
803 The default implementation calls e->ignore(), which rejects the context
805 event. See the QContextMenuEvent documentation for more details.
806 See also event() and QContextMenuEvent.
808 Example: menu/menu.cpp.
810
812 destroyOldWindow = TRUE ) [virtual protected]
813 Creates a new widget window if window is 0, otherwise sets the widget's
814 window to window.
815 Initializes the window (sets the geometry etc.) if initializeWindow is
817 TRUE. If initializeWindow is FALSE, no initialization is performed.
818 This parameter only makes sense if window is a valid window.
819 Destroys the old window if destroyOldWindow is TRUE. If
821 destroyOldWindow is FALSE, you are responsible for destroying the
822 window yourself (using platform native code).
823 The QWidget constructor calls create(0,TRUE,TRUE) to create a window
825 for this widget.
826
828 Returns the cursor shape for this widget. See the "cursor" property for
829 details.
830
832 Returns TRUE if the widget wants to handle What's This help manually;
833 otherwise returns FALSE. See the "customWhatsThis" property for
834 details.
835
837 TRUE ) [virtual protected]
838 Frees up window system resources. Destroys the widget window if
839 destroyWindow is TRUE.
840 destroy() calls itself recursively for all the child widgets, passing
842 destroySubWindows for the destroyWindow parameter. To have more control
843 over destruction of subwidgets, destroy subwidgets selectively first.
844 This function is usually called from the QWidget destructor.
846
848 This event handler is called when a drag is in progress and the mouse
849 enters this widget.
850 See the Drag-and-drop documentation for an overview of how to provide
852 drag-and-drop in your application.
853 See also QTextDrag, QImageDrag, and QDragEnterEvent.
855 Example: iconview/simple_dd/main.cpp.
857
859 This event handler is called when a drag is in progress and the mouse
860 leaves this widget.
861 See the Drag-and-drop documentation for an overview of how to provide
863 drag-and-drop in your application.
864 See also QTextDrag, QImageDrag, and QDragLeaveEvent.
866
868 This event handler is called when a drag is in progress and the mouse
869 enters this widget, and whenever it moves within the widget.
870 See the Drag-and-drop documentation for an overview of how to provide
872 drag-and-drop in your application.
873 See also QTextDrag, QImageDrag, and QDragMoveEvent.
875
877 Draws the string str at position (x, y).
878 The y position is the base line position of the text. The text is drawn
880 using the default font and the default foreground color.
881 This function is provided for convenience. You will generally get more
883 flexible results and often higher speed by using a a painter instead.
884 See also font, foregroundColor(), and QPainter::drawText().
886
888 This is an overloaded member function, provided for convenience. It
889 behaves essentially like the above function.
890 Draws the string str at position pos.
892
894 This event handler is called when the drag is dropped on this widget.
895 See the Drag-and-drop documentation for an overview of how to provide
897 drag-and-drop in your application.
898 See also QTextDrag, QImageDrag, and QDropEvent.
900 Example: iconview/simple_dd/main.cpp.
902
904 This virtual function is called from setEnabled(). oldEnabled is the
905 previous setting; you can get the new setting from isEnabled().
906 Reimplement this function if your widget needs to know when it becomes
908 enabled or disabled. You will almost certainly need to update the
909 widget using update().
910 The default implementation repaints the visible part of the widget.
912 See also enabled, enabled, repaint(), update(), and clipRegion().
914
916 This event handler can be reimplemented in a subclass to receive widget
917 enter events.
918 An event is sent to the widget when the mouse cursor enters the widget.
920 See also leaveEvent(), mouseMoveEvent(), and event().
922
924 Erases the specified area (x, y, w, h) in the widget without generating
925 a paint event.
926 If w is negative, it is replaced with width() - x. If h is negative, it
928 is replaced width height() - y.
929 Child widgets are not affected.
931 See also repaint().
933
935 This is an overloaded member function, provided for convenience. It
936 behaves essentially like the above function.
937 This version erases the entire widget.
939
941 This is an overloaded member function, provided for convenience. It
942 behaves essentially like the above function.
943 Erases the specified area r in the widget without generating a paint
945 event.
946
948 This is an overloaded member function, provided for convenience. It
949 behaves essentially like the above function.
950 Erases the area defined by reg, without generating a paint event.
952 Child widgets are not affected.
954
956 Returns the erase color of the widget.
957 See also setEraseColor(), setErasePixmap(), and backgroundColor().
959
961 Returns the widget's erase pixmap.
962 See also setErasePixmap() and eraseColor().
964
966 This is the main event handler; it handles event e. You can reimplement
967 this function in a subclass, but we recommend using one of the
968 specialized event handlers instead.
969 The main event handler first passes an event through all event filters
971 that have been installed. If none of the filters intercept the event,
972 it calls one of the specialized event handlers.
973 Key press and release events are treated differently from other events.
975 event() checks for Tab and Shift+Tab and tries to move the focus
976 appropriately. If there is no widget to move the focus to (or the key
977 press is not Tab or Shift+Tab), event() calls keyPressEvent().
978 This function returns TRUE if it is able to pass the event over to
980 someone (i.e. someone wanted the event); otherwise returns FALSE.
981 See also closeEvent(), focusInEvent(), focusOutEvent(), enterEvent(),
983 keyPressEvent(), keyReleaseEvent(), leaveEvent(),
984 mouseDoubleClickEvent(), mouseMoveEvent(), mousePressEvent(),
985 mouseReleaseEvent(), moveEvent(), paintEvent(), resizeEvent(),
986 QObject::event(), and QObject::timerEvent().
987 Reimplemented from QObject.
989
991 Returns a pointer to the widget with window identifer/handle id.
992 The window identifier type depends on the underlying window system, see
994 qwindowdefs.h for the actual definition. If there is no widget with
995 this identifier, 0 is returned.
996
998 Returns the focus data for this widget's top-level widget.
999 Focus data always belongs to the top-level widget. The focus data list
1001 contains all the widgets in this top-level widget that can accept
1002 focus, in tab order. An iterator points to the current focus widget
1003 (focusWidget() returns a pointer to this widget).
1004 This information is useful for implementing advanced versions of
1006 focusNextPrevChild().
1007
1009 This event handler can be reimplemented in a subclass to receive
1010 keyboard focus events (focus received) for the widget.
1011 A widget normally must setFocusPolicy() to something other than NoFocus
1013 in order to receive focus events. (Note that the application programmer
1014 can call setFocus() on any widget, even those that do not normally
1015 accept focus.)
1016 The default implementation updates the widget (except for toplevel
1018 widgets that do not specify a focusPolicy() ). It also calls
1019 setMicroFocusHint(), hinting any system-specific input tools about the
1020 focus of the user's attention.
1021 See also focusOutEvent(), focusPolicy, keyPressEvent(),
1023 keyReleaseEvent(), event(), and QFocusEvent.
1024
1026 Finds a new widget to give the keyboard focus to, as appropriate for
1027 Tab and Shift+Tab, and returns TRUE if is can find a new widget and
1028 FALSE if it can't,
1029 If next is TRUE, this function searches "forwards", if next is FALSE,
1031 it searches "backwards".
1032 Sometimes, you will want to reimplement this function. For example, a
1034 web browser might reimplement it to move its "current active link"
1035 forwards or backwards, and call QWidget::focusNextPrevChild() only when
1036 it reaches the last or first link on the "page".
1037 Child widgets call focusNextPrevChild() on their parent widgets, but
1039 only the top-level widget decides where to redirect focus. By
1040 overriding this method for an object, you thus gain control of focus
1041 traversal for all child widgets.
1042 Warning: QScrollView uses it own logic for this function, which does
1044 the right thing in most cases. But if you are using a QScrollView and
1045 want complete control of the focus chain you'll need to override
1046 QScrollView::focusNextPrevChild() and your top-level widgets'
1047 focusNextPrevChild() functions.
1048 See also focusData().
1050
1052 This event handler can be reimplemented in a subclass to receive
1053 keyboard focus events (focus lost) for the widget.
1054 A widget normally must setFocusPolicy() to something other than NoFocus
1056 in order to receive focus events. (Note that the application programmer
1057 can call setFocus() on any widget, even those that do not normally
1058 accept focus.)
1059 The default implementation updates the widget (except for toplevel
1061 widgets that do not specify a focusPolicy() ). It also calls
1062 setMicroFocusHint(), hinting any system-specific input tools about the
1063 focus of the user's attention.
1064 See also focusInEvent(), focusPolicy, keyPressEvent(),
1066 keyReleaseEvent(), event(), and QFocusEvent.
1067 Example: qmag/qmag.cpp.
1069
1071 Returns the way the widget accepts keyboard focus. See the
1072 "focusPolicy" property for details.
1073
1075 Returns the focus proxy, or 0 if there is no focus proxy.
1076 See also setFocusProxy().
1078
1080 Returns the focus widget in this widget's window. This is not the same
1081 as QApplication::focusWidget(), which returns the focus widget in the
1082 currently active window.
1083
1085 Returns the font currently set for the widget. See the "font" property
1086 for details.
1087
1089 This virtual function is called from setFont(). oldFont is the previous
1090 font; you can get the new font from font().
1091 Reimplement this function if your widget needs to know when its font
1093 changes. You will almost certainly need to update the widget using
1094 update().
1095 The default implementation updates the widget including its geometry.
1097 See also font, font, update(), and updateGeometry().
1099
1101 Returns the font info for the widget's current font. Equivalent to
1102 QFontInto(widget->font()).
1103 See also font, fontMetrics(), and font.
1105
1107 Returns the font metrics for the widget's current font. Equivalent to
1108 QFontMetrics(widget->font()).
1109 See also font, fontInfo(), and font.
1111 Examples:
1113
1115 Same as paletteForegroundColor()
1116
1118 Returns geometry of the widget relative to its parent including any
1119 window frame. See the "frameGeometry" property for details.
1120
1122 Returns the size of the widget including any window frame. See the
1123 "frameSize" property for details.
1124
1126 Returns the geometry of the widget relative to its parent and excluding
1127 the window frame. See the "geometry" property for details.
1128
1130 Returns the widget flags for this this widget.
1131 Widget flags are a combination of Qt::WidgetFlags.
1133 See also testWFlags(), setWFlags(), and clearWFlags().
1135
1137 Grabs the keyboard input.
1138 This widget reveives all keyboard events until releaseKeyboard() is
1140 called; other widgets get no keyboard events at all. Mouse events are
1141 not affected. Use grabMouse() if you want to grab that.
1142 The focus widget is not affected, except that it doesn't receive any
1144 keyboard events. setFocus() moves the focus as usual, but the new focus
1145 widget receives keyboard events only after releaseKeyboard() is called.
1146 If a different widget is currently grabbing keyboard input, that
1148 widget's grab is released first.
1149 See also releaseKeyboard(), grabMouse(), releaseMouse(), and
1151 focusWidget().
1152
1154 Grabs the mouse input.
1155 This widget receives all mouse events until releaseMouse() is called;
1157 other widgets get no mouse events at all. Keyboard events are not
1158 affected. Use grabKeyboard() if you want to grab that.
1159 Warning: Bugs in mouse-grabbing applications very often lock the
1161 terminal. Use this function with extreme caution, and consider using
1162 the -nograb command line option while debugging.
1163 It is almost never necessary to grab the mouse when using Qt, as Qt
1165 grabs and releases it sensibly. In particular, Qt grabs the mouse when
1166 a mouse button is pressed and keeps it until the last button is
1167 released.
1168 Note that only visible widgets can grab mouse input. If isVisible()
1170 returns FALSE for a widget, that widget cannot call grabMouse().
1171 See also releaseMouse(), grabKeyboard(), releaseKeyboard(),
1173 grabKeyboard(), and focusWidget().
1174
1176 This is an overloaded member function, provided for convenience. It
1177 behaves essentially like the above function.
1178 Grabs the mouse input and changes the cursor shape.
1180 The cursor will assume shape cursor (for as long as the mouse focus is
1182 grabbed) and this widget will be the only one to receive mouse events
1183 until releaseMouse() is called().
1184 Warning: Grabbing the mouse might lock the terminal.
1186 See also releaseMouse(), grabKeyboard(), releaseKeyboard(), and cursor.
1188
1190 Returns TRUE if this widget (or its focus proxy) has the keyboard input
1191 focus; otherwise returns FALSE. See the "focus" property for details.
1192
1194 Returns TRUE if the widget is under the mouse cursor; otherwise returns
1195 FALSE. See the "underMouse" property for details.
1196
1198 Returns TRUE if mouse tracking is enabled for the widget; otherwise
1199 returns FALSE. See the "mouseTracking" property for details.
1200
1202 Returns the height of the widget excluding any window frame. See the
1203 "height" property for details.
1204
1206 Returns the preferred height for this widget, given the width w. The
1207 default implementation returns 0, indicating that the preferred height
1208 does not depend on the width.
1209 Warning: Does not look at the widget's layout.
1211 Reimplemented in QMenuBar and QTextEdit.
1213
1215 Hides the widget.
1216 You almost never have to reimplement this function. If you need to do
1218 something after a widget is hidden, use hideEvent() instead.
1219 See also hideEvent(), hidden, show(), showMinimized(), visible, and
1221 close().
1222 Examples:
1224 Reimplemented in QMenuBar.
1226
1228 This event handler can be reimplemented in a subclass to receive widget
1229 hide events.
1230 Hide events are sent to widgets immediately after they have been
1232 hidden.
1233 See also event() and QHideEvent.
1235 Reimplemented in QScrollBar.
1237
1239 Returns the widget's icon. See the "icon" property for details.
1240
1242 Returns the widget's icon text. See the "iconText" property for
1243 details.
1244
1246 This function is obsolete. It is provided to keep old source working.
1247 We strongly advise against using it in new code.
1248
1250 This event handler, for event e, can be reimplemented in a subclass to
1251 receive Input Method composition events. This handler is called when
1252 the user has entered some text using an Input Method.
1253 The default implementation calls e->ignore(), which rejects the Input
1255 Method event. See the QIMEvent documentation for more details.
1256 See also event() and QIMEvent.
1258
1260 This event handler, for event e, can be reimplemented in a subclass to
1261 receive Input Method composition events. This handler is called when
1262 the user has finished inputting text via an Input Method.
1263 The default implementation calls e->ignore(), which rejects the Input
1265 Method event. See the QIMEvent documentation for more details.
1266 See also event() and QIMEvent.
1268
1270 This event handler, for event e, can be reimplemented in a subclass to
1271 receive Input Method composition events. This handler is called when
1272 the user begins entering text using an Input Method.
1273 The default implementation calls e->ignore(), which rejects the Input
1275 Method event. See the QIMEvent documentation for more details.
1276 See also event() and QIMEvent.
1278
1280 Returns TRUE if this widget is the active window; otherwise returns
1281 FALSE. See the "isActiveWindow" property for details.
1282
1284 Returns TRUE if the widget is a desktop widget, i.e. represents the
1285 desktop; otherwise returns FALSE. See the "isDesktop" property for
1286 details.
1287
1289 Returns TRUE if the widget is a dialog widget; otherwise returns FALSE.
1290 See the "isDialog" property for details.
1291
1293 Returns TRUE if the widget is enabled; otherwise returns FALSE. See the
1294 "enabled" property for details.
1295
1297 Returns TRUE if this widget would become enabled if ancestor is
1298 enabled; otherwise returns FALSE.
1299 This is the case if neither the widget itself nor every parent up to
1301 but excluding ancestor has been explicitly disabled.
1302 isEnabledTo(0) is equivalent to isEnabled().
1304 See also enabled and enabled.
1306
1308 This function is obsolete. It is provided to keep old source working.
1309 We strongly advise against using it in new code.
1310 This function is deprecated. It is equivalent to isEnabled()
1312
1314 Returns TRUE if the widget accepts keyboard focus; otherwise returns
1315 FALSE. See the "focusEnabled" property for details.
1316
1318 Returns TRUE if the widget is full screen; otherwise returns FALSE. See
1319 the "fullScreen" property for details.
1320
1322 Returns TRUE if the widget is explicitly hidden; otherwise returns
1323 FALSE. See the "hidden" property for details.
1324
1326 Returns enables or disables the use of input methods for this widget.
1327 See the "inputMethodEnabled" property for details.
1328
1330 Returns TRUE if this widget is maximized; otherwise returns FALSE. See
1331 the "maximized" property for details.
1332
1334 Returns TRUE if this widget is minimized (iconified); otherwise returns
1335 FALSE. See the "minimized" property for details.
1336
1338 Returns TRUE if the widget is a modal widget; otherwise returns FALSE.
1339 See the "isModal" property for details.
1340
1342 Returns TRUE if the widget is a popup widget; otherwise returns FALSE.
1343 See the "isPopup" property for details.
1344
1346 Returns TRUE if the widget is shown; otherwise returns FALSE. See the
1347 "shown" property for details.
1348
1350 Returns TRUE if the widget is a top-level widget; otherwise returns
1351 FALSE. See the "isTopLevel" property for details.
1352
1354 Returns TRUE if updates are enabled; otherwise returns FALSE. See the
1355 "updatesEnabled" property for details.
1356
1358 Returns TRUE if the widget is visible; otherwise returns FALSE. See the
1359 "visible" property for details.
1360
1362 Returns TRUE if this widget would become visible if ancestor is shown;
1363 otherwise returns FALSE.
1364 The TRUE case occurs if neither the widget itself nor any parent up to
1366 but excluding ancestor has been explicitly hidden.
1367 This function will still return TRUE if the widget is obscured by other
1369 windows on the screen, but could be physically visible if it or they
1370 were to be moved.
1371 isVisibleTo(0) is identical to isVisible().
1373 See also show(), hide(), and visible.
1375
1377 This function is obsolete. It is provided to keep old source working.
1378 We strongly advise against using it in new code.
1379 This function is deprecated. It is equivalent to isVisible()
1381
1383 This event handler, for event e, can be reimplemented in a subclass to
1384 receive key press events for the widget.
1385 A widget must call setFocusPolicy() to accept focus initially and have
1387 focus in order to receive a key press event.
1388 If you reimplement this handler, it is very important that you
1390 explicitly ignore the event if you do not understand it, so that the
1391 widget's parent can interpret it; otherwise, the event will be
1392 implicitly accepted. Although top-level widgets are able to choose
1393 whether to accept or ignore unknown events because they have no parent
1394 widgets that could otherwise handle them, it is good practice to
1395 explicitly ignore events to make widgets as reusable as possible.
1396 The default implementation closes popup widgets if the user presses
1398 Esc. Otherwise the event is ignored.
1399 See also keyReleaseEvent(), QKeyEvent::ignore(), focusPolicy,
1401 focusInEvent(), focusOutEvent(), event(), and QKeyEvent.
1402 Example: picture/picture.cpp.
1404 Reimplemented in QLineEdit and QTextEdit.
1406
1408 This event handler, for event e, can be reimplemented in a subclass to
1409 receive key release events for the widget.
1410 A widget must accept focus initially and have focus in order to receive
1412 a key release event.
1413 If you reimplement this handler, it is very important that you ignore()
1415 the release if you do not understand it, so that the widget's parent
1416 can interpret it.
1417 The default implementation ignores the event.
1419 See also keyPressEvent(), QKeyEvent::ignore(), focusPolicy,
1421 focusInEvent(), focusOutEvent(), event(), and QKeyEvent.
1422
1424 Returns the widget that is currently grabbing the keyboard input.
1425 If no widget in this application is currently grabbing the keyboard, 0
1427 is returned.
1428 See also grabMouse() and mouseGrabber().
1430
1432 Returns the layout engine that manages the geometry of this widget's
1433 children.
1434 If the widget does not have a layout, layout() returns 0.
1436 See also sizePolicy.
1438 Examples:
1440
1442 This event handler can be reimplemented in a subclass to receive widget
1443 leave events.
1444 A leave event is sent to the widget when the mouse cursor leaves the
1446 widget.
1447 See also enterEvent(), mouseMoveEvent(), and event().
1449
1451 Lowers the widget to the bottom of the parent widget's stack.
1452 After this call the widget will be visually behind (and therefore
1454 obscured by) any overlapping sibling widgets.
1455 See also raise() and stackUnder().
1457
1459 This special event handler can be reimplemented in a subclass to
1460 receive native Macintosh events.
1461 In your reimplementation of this function, if you want to stop the
1463 event being handled by Qt, return TRUE. If you return FALSE, this
1464 native event is passed back to Qt, which translates the event into a Qt
1465 event and sends it to the widget.
1466 Warning: This function is not portable.
1468 See also QApplication::macEventFilter().
1470
1472 Translates the widget coordinate pos from the coordinate system of
1473 parent to this widget's coordinate system. The parent must not be 0 and
1474 must be a parent of the calling widget.
1475 See also mapTo(), mapFromParent(), mapFromGlobal(), and underMouse.
1477
1479 Translates the global screen coordinate pos to widget coordinates.
1480 See also mapToGlobal(), mapFrom(), and mapFromParent().
1482
1484 Translates the parent widget coordinate pos to widget coordinates.
1485 Same as mapFromGlobal() if the widget has no parent.
1487 See also mapToParent(), mapFrom(), mapFromGlobal(), and underMouse.
1489
1491 Translates the widget coordinate pos to the coordinate system of
1492 parent. The parent must not be 0 and must be a parent of the calling
1493 widget.
1494 See also mapFrom(), mapToParent(), mapToGlobal(), and underMouse.
1496
1498 Translates the widget coordinate pos to global screen coordinates. For
1499 example, mapToGlobal(QPoint(0,0)) would give the global coordinates of
1500 the top-left pixel of the widget.
1501 See also mapFromGlobal(), mapTo(), and mapToParent().
1503 Example: scribble/scribble.cpp.
1505
1507 Translates the widget coordinate pos to a coordinate in the parent
1508 widget.
1509 Same as mapToGlobal() if the widget has no parent.
1511 See also mapFromParent(), mapTo(), mapToGlobal(), and underMouse.
1513
1515 Returns the widget's maximum height. See the "maximumHeight" property
1516 for details.
1517
1519 Returns the widget's maximum size. See the "maximumSize" property for
1520 details.
1521
1523 Returns the widget's maximum width. See the "maximumWidth" property for
1524 details.
1525
1527 Internal implementation of the virtual QPaintDevice::metric() function.
1528 Use the QPaintDeviceMetrics class instead.
1530 m is the metric to get.
1532
1534 Returns the currently set micro focus hint for this widget. See the
1535 "microFocusHint" property for details.
1536
1538 Returns the widget's minimum height. See the "minimumHeight" property
1539 for details.
1540
1542 Returns the widget's minimum size. See the "minimumSize" property for
1543 details.
1544
1546 Returns the recommended minimum size for the widget. See the
1547 "minimumSizeHint" property for details.
1548 Reimplemented in QLineEdit.
1550
1552 Returns the widget's minimum width. See the "minimumWidth" property for
1553 details.
1554
1556 This event handler, for event e, can be reimplemented in a subclass to
1557 receive mouse double click events for the widget.
1558 The default implementation generates a normal mouse press event.
1560 Note that the widgets gets a mousePressEvent() and a
1562 mouseReleaseEvent() before the mouseDoubleClickEvent().
1563 See also mousePressEvent(), mouseReleaseEvent(), mouseMoveEvent(),
1565 event(), and QMouseEvent.
1566
1568 Returns the widget that is currently grabbing the mouse input.
1569 If no widget in this application is currently grabbing the mouse, 0 is
1571 returned.
1572 See also grabMouse() and keyboardGrabber().
1574
1576 This event handler, for event e, can be reimplemented in a subclass to
1577 receive mouse move events for the widget.
1578 If mouse tracking is switched off, mouse move events only occur if a
1580 mouse button is pressed while the mouse is being moved. If mouse
1581 tracking is switched on, mouse move events occur even if no mouse
1582 button is pressed.
1583 QMouseEvent::pos() reports the position of the mouse cursor, relative
1585 to this widget. For press and release events, the position is usually
1586 the same as the position of the last mouse move event, but it might be
1587 different if the user's hand shakes. This is a feature of the
1588 underlying window system, not Qt.
1589 See also mouseTracking, mousePressEvent(), mouseReleaseEvent(),
1591 mouseDoubleClickEvent(), event(), and QMouseEvent.
1592 Examples:
1594 Reimplemented in QSizeGrip.
1596
1598 This event handler, for event e, can be reimplemented in a subclass to
1599 receive mouse press events for the widget.
1600 If you create new widgets in the mousePressEvent() the
1602 mouseReleaseEvent() may not end up where you expect, depending on the
1603 underlying window system (or X11 window manager), the widgets' location
1604 and maybe more.
1605 The default implementation implements the closing of popup widgets when
1607 you click outside the window. For other widget types it does nothing.
1608 See also mouseReleaseEvent(), mouseDoubleClickEvent(),
1610 mouseMoveEvent(), event(), and QMouseEvent.
1611 Examples:
1613 Reimplemented in QSizeGrip.
1615
1617 This event handler, for event e, can be reimplemented in a subclass to
1618 receive mouse release events for the widget.
1619 See also mouseDoubleClickEvent(), mouseMoveEvent(), event(), and
1621 QMouseEvent.
1622 Examples:
1624
1626 Sets the position of the widget within its parent widget. See the "pos"
1627 property for details.
1628
1630 This is an overloaded member function, provided for convenience. It
1631 behaves essentially like the above function.
1632 This corresponds to move( QPoint(x, y) ).
1634
1636 This event handler can be reimplemented in a subclass to receive widget
1637 move events. When the widget receives this event, it is already at the
1638 new position.
1639 The old position is accessible through QMoveEvent::oldPos().
1641 See also resizeEvent(), event(), pos, and QMoveEvent.
1643
1645 Returns TRUE if the widget uses its own cursor; otherwise returns
1646 FALSE. See the "ownCursor" property for details.
1647
1649 Returns TRUE if the widget uses its own font; otherwise returns FALSE.
1650 See the "ownFont" property for details.
1651
1653 Returns TRUE if the widget uses its own palette; otherwise returns
1654 FALSE. See the "ownPalette" property for details.
1655
1657 This event handler can be reimplemented in a subclass to receive paint
1658 events.
1659 A paint event is a request to repaint all or part of the widget. It can
1661 happen as a result of repaint() or update(), or because the widget was
1662 obscured and has now been uncovered, or for many other reasons.
1663 Many widgets can simply repaint their entire surface when asked to, but
1665 some slow widgets need to optimize by painting only the requested
1666 region: QPaintEvent::region(). This speed optimization does not change
1667 the result, as painting is clipped to that region during event
1668 processing. QListView and QCanvas do this, for example.
1669 Qt also tries to speed up painting by merging multiple paint events
1671 into one. When update() is called several times or the window system
1672 sends several paint events, Qt merges these events into one event with
1673 a larger region (see QRegion::unite()). repaint() does not permit this
1674 optimization, so we suggest using update() when possible.
1675 When the paint event occurs, the update region has normally been
1677 erased, so that you're painting on the widget's background. There are a
1678 couple of exceptions and QPaintEvent::erased() tells you whether the
1679 widget has been erased or not.
1680 The background can be set using setBackgroundMode(),
1682 setPaletteBackgroundColor() or setBackgroundPixmap(). The documentation
1683 for setBackgroundMode() elaborates on the background; we recommend
1684 reading it.
1685 See also event(), repaint(), update(), QPainter, QPixmap, and
1687 QPaintEvent.
1688 Examples:
1690 Reimplemented in QButton, QFrame, QGLWidget, QSizeGrip, QStatusBar, and
1692 QTabBar.
1693
1695 Returns the widget's palette. See the "palette" property for details.
1696
1698 Returns the background color of the widget. See the
1699 "paletteBackgroundColor" property for details.
1700
1702 Returns the background pixmap of the widget. See the
1703 "paletteBackgroundPixmap" property for details.
1704
1706 protected]
1707 This virtual function is called from setPalette(). oldPalette is the
1708 previous palette; you can get the new palette from palette().
1709 Reimplement this function if your widget needs to know when its palette
1711 changes.
1712 See also palette and palette.
1714
1716 Returns the foreground color of the widget. See the
1717 "paletteForegroundColor" property for details.
1718
1720 Returns the parent of this widget, or 0 if it does not have any parent
1721 widget. If sameWindow is TRUE and the widget is top level returns 0;
1722 otherwise returns the widget's parent.
1723 Example: mdi/application.cpp.
1725
1727 Delayed initialization of a widget.
1728 This function will be called after a widget has been fully created and
1730 before it is shown the very first time.
1731 Polishing is useful for final initialization which depends on having an
1733 instantiated widget. This is something a constructor cannot guarantee
1734 since the initialization of the subclasses might not be finished.
1735 After this function, the widget has a proper font and palette and
1737 QApplication::polish() has been called.
1738 Remember to call QWidget's implementation first when reimplementing
1740 this function to ensure that your program does not end up in infinite
1741 recursion.
1742 See also constPolish() and QApplication::polish().
1744 Example: menu/menu.cpp.
1746
1748 Returns the position of the widget within its parent widget. See the
1749 "pos" property for details.
1750
1752 This special event handler can be reimplemented in a subclass to
1753 receive native Qt/Embedded events.
1754 In your reimplementation of this function, if you want to stop the
1756 event being handled by Qt, return TRUE. If you return FALSE, this
1757 native event is passed back to Qt, which translates the event into a Qt
1758 event and sends it to the widget.
1759 Warning: This function is not portable.
1761 See also QApplication::qwsEventFilter().
1763
1765 Raises this widget to the top of the parent widget's stack.
1766 After this call the widget will be visually in front of any overlapping
1768 sibling widgets.
1769 See also lower() and stackUnder().
1771 Example: showimg/showimg.cpp.
1773
1775 showIt = FALSE )
1776 This function is obsolete. It is provided to keep old source working.
1777 We strongly advise against using it in new code.
1778 This method is provided to aid porting from Qt 1.0 to 2.0. It has been
1780 renamed reparent() in Qt 2.0.
1781
1783 Returns the internal geometry of the widget excluding any window frame.
1784 See the "rect" property for details.
1785
1787 Releases the keyboard grab.
1788 See also grabKeyboard(), grabMouse(), and releaseMouse().
1790
1792 Releases the mouse grab.
1793 See also grabMouse(), grabKeyboard(), and releaseKeyboard().
1795
1797 Repaints the widget directly by calling paintEvent() immediately,
1799 unless updates are disabled or the widget is hidden.
1800 If erase is TRUE, Qt erases the area (x, y, w, h) before the
1802 paintEvent() call.
1803 If w is negative, it is replaced with width() - x, and if h is
1805 negative, it is replaced width height() - y.
1806 We suggest only using repaint() if you need an immediate repaint, for
1808 example during animation. In almost all circumstances update() is
1809 better, as it permits Qt to optimize for speed and minimize flicker.
1810 Warning: If you call repaint() in a function which may itself be called
1812 from paintEvent(), you may get infinite recursion. The update()
1813 function never causes recursion.
1814 See also update(), paintEvent(), updatesEnabled, and erase().
1816 Example: qwerty/qwerty.cpp.
1818
1820 This is an overloaded member function, provided for convenience. It
1821 behaves essentially like the above function.
1822 This version erases and repaints the entire widget.
1824
1826 This is an overloaded member function, provided for convenience. It
1827 behaves essentially like the above function.
1828 This version repaints the entire widget.
1830
1832 This is an overloaded member function, provided for convenience. It
1833 behaves essentially like the above function.
1834 Repaints the widget directly by calling paintEvent() directly, unless
1836 updates are disabled or the widget is hidden.
1837 Erases the widget region r if erase is TRUE.
1839
1841 This is an overloaded member function, provided for convenience. It
1842 behaves essentially like the above function.
1843 Repaints the widget directly by calling paintEvent() directly, unless
1845 updates are disabled or the widget is hidden.
1846 Erases the widget region reg if erase is TRUE.
1848 Only use repaint if your widget needs to be repainted immediately, for
1850 example when doing some animation. In all other cases, use update().
1851 Calling update() many times in a row will generate a single paint
1852 event.
1853 Warning: If you call repaint() in a function which may itself be called
1855 from paintEvent(), you may get infinite recursion. The update()
1856 function never causes recursion.
1857 See also update(), paintEvent(), updatesEnabled, and erase().
1859
1861 showIt = FALSE ) [virtual]
1862 Reparents the widget. The widget gets a new parent, new widget flags
1863 (f, but as usual, use 0) at a new position in its new parent (p).
1864 If showIt is TRUE, show() is called once the widget has been
1866 reparented.
1867 If the new parent widget is in a different top-level widget, the
1869 reparented widget and its children are appended to the end of the tab
1870 chain of the new parent widget, in the same internal order as before.
1871 If one of the moved widgets had keyboard focus, reparent() calls
1872 clearFocus() for that widget.
1873 If the new parent widget is in the same top-level widget as the old
1875 parent, reparent doesn't change the tab order or keyboard focus.
1876 Warning: It is extremely unlikely that you will ever need this
1878 function. If you have a widget that changes its content dynamically, it
1879 is far easier to use QWidgetStack or QWizard.
1880 See also getWFlags().
1882 Example: toplevel/options.ui.h.
1884
1886 FALSE )
1887 This is an overloaded member function, provided for convenience. It
1888 behaves essentially like the above function.
1889 A convenience version of reparent that does not take widget flags as
1891 argument.
1892 Calls reparent(parent, getWFlags() & ~WType_Mask, p, showIt).
1894
1896 This function is called when the user finishes input composition, e.g.
1897 changes focus to another widget, moves the cursor, etc.
1898
1900 Sets the size of the widget excluding any window frame. See the "size"
1901 property for details.
1902
1904 This is an overloaded member function, provided for convenience. It
1905 behaves essentially like the above function.
1906 This corresponds to resize( QSize(w, h) ).
1908
1910 This event handler can be reimplemented in a subclass to receive widget
1911 resize events. When resizeEvent() is called, the widget already has its
1912 new geometry. The old size is accessible through
1913 QResizeEvent::oldSize().
1914 The widget will be erased and receive a paint event immediately after
1916 processing the resize event. No drawing need be (or should be) done
1917 inside this handler.
1918 Widgets that have been created with the WNoAutoErase flag will not be
1920 erased. Nevertheless, they will receive a paint event for their entire
1921 area afterwards. Again, no drawing needs to be done inside this
1922 handler.
1923 The default implementation calls updateMask() if the widget has
1925 automatic masking enabled.
1926 See also moveEvent(), event(), size, QResizeEvent, and paintEvent().
1928 Examples:
1930 Reimplemented in QFrame and QGLWidget.
1932
1934 Scrolls the widget including its children dx pixels to the right and dy
1935 downwards. Both dx and dy may be negative.
1936 After scrolling, scroll() sends a paint event for the the part that is
1938 read but not written. For example, when scrolling 10 pixels rightwards,
1939 the leftmost ten pixels of the widget need repainting. The paint event
1940 may be delivered immediately or later, depending on some heuristics
1941 (note that you might have to force processing of paint events using
1942 QApplication::sendPostedEvents() when using scroll() and move() in
1943 combination).
1944 See also QScrollView, erase(), and bitBlt().
1946
1948 This is an overloaded member function, provided for convenience. It
1949 behaves essentially like the above function.
1950 This version only scrolls r and does not move the children of the
1952 widget.
1953 If r is empty or invalid, the result is undefined.
1955 See also QScrollView, erase(), and bitBlt().
1957
1959 Sets whether drop events are enabled for this widget to on. See the
1960 "acceptDrops" property for details.
1961
1963 Sets the top-level widget containing this widget to be the active
1964 window.
1965 An active window is a visible top-level window that has the keyboard
1967 input focus.
1968 This function performs the same operation as clicking the mouse on the
1970 title bar of a top-level window. On X11, the result depends on the
1971 Window Manager. If you want to ensure that the window is stacked on top
1972 as well you should also call raise(). Note that the window must be
1973 visible, otherwise setActiveWindow() has no effect.
1974 On Windows, if you are calling this when the application is not
1976 currently the active one then it will not make it the active window. It
1977 will flash the task bar entry blue to indicate that the window has done
1978 something. This is because Microsoft do not allow an application to
1979 interrupt what the user is currently doing in another application.
1980 See also isActiveWindow, topLevelWidget(), and show().
1982 Reimplemented in QXtWidget.
1984
1986 Sets whether the auto mask feature is enabled for the widget. See the
1987 "autoMask" property for details.
1988
1990 This function is obsolete. It is provided to keep old source working.
1991 We strongly advise against using it in new code. Use
1992 setPaletteBackgroundColor() or setEraseColor() instead.
1993 Examples:
1995
1997 Sets the color role used for painting the background of the widget. See
1998 the "backgroundMode" property for details.
1999
2001 This is an overloaded member function, provided for convenience. It
2002 behaves essentially like the above function.
2003 Sets the widget's own background mode to m and the visual background
2005 mode to visual. The visual background mode is used with the designable
2006 properties backgroundColor, foregroundColor and backgroundPixmap.
2007 For complex controls, the logical background mode sometimes differs
2009 from a widget's own background mode. A spinbox for example has
2010 PaletteBackground as background mode (typically dark gray), while it's
2011 embedded lineedit control uses PaletteBase (typically white). Since the
2012 lineedit covers most of the visual area of a spinbox, it defines
2013 PaletteBase to be its visual background mode. Changing the
2014 backgroundColor property thus changes the lineedit control's
2015 background, which is exactly what the user expects in Qt Designer.
2016
2018 Sets the origin of the widget's background. See the "backgroundOrigin"
2019 property for details.
2020
2022 This function is obsolete. It is provided to keep old source working.
2023 We strongly advise against using it in new code. Use
2024 setPaletteBackgroundPixmap() or setErasePixmap() instead.
2025 Example: desktop/desktop.cpp.
2027
2029 Sets the base size of the widget. See the "baseSize" property for
2030 details.
2031
2033 This is an overloaded member function, provided for convenience. It
2034 behaves essentially like the above function.
2035 This corresponds to setBaseSize( QSize(basew, baseh) ). Sets the
2037 widgets base size to width basew and height baseh.
2038
2040 Sets the window caption (title). See the "caption" property for
2041 details.
2042
2044 Sets the cursor shape for this widget. See the "cursor" property for
2045 details.
2046
2048 Disables widget input events if disable is TRUE; otherwise enables
2049 input events.
2050 See the enabled documentation for more information.
2052 See also isEnabledTo(), QKeyEvent, QMouseEvent, and enabledChange().
2054
2056 Sets whether the widget is enabled. See the "enabled" property for
2057 details.
2058
2060 Sets the erase color of the widget to color.
2061 The erase color is the color the widget is to be cleared to before
2063 paintEvent() is called. If there is an erase pixmap (set using
2064 setErasePixmap()), then this property has an indeterminate value.
2065 See also erasePixmap(), backgroundColor(), backgroundMode, and palette.
2067
2069 Sets the widget's erase pixmap to pixmap.
2070 This pixmap is used to clear the widget before paintEvent() is called.
2072
2074 Sets both the minimum and maximum heights of the widget to h without
2075 changing the widths. Provided for convenience.
2076 See also sizeHint, minimumSize, maximumSize, and setFixedSize().
2078 Examples:
2080
2082 Sets both the minimum and maximum sizes of the widget to s, thereby
2083 preventing it from ever growing or shrinking.
2084 See also maximumSize and minimumSize.
2086
2088 This is an overloaded member function, provided for convenience. It
2089 behaves essentially like the above function.
2090 Sets the width of the widget to w and the height to h.
2092
2094 Sets both the minimum and maximum width of the widget to w without
2095 changing the heights. Provided for convenience.
2096 See also sizeHint, minimumSize, maximumSize, and setFixedSize().
2098 Examples:
2100
2102 Gives the keyboard input focus to this widget (or its focus proxy) if
2103 this widget or one of its parents is the active window.
2104 First, a focus out event is sent to the focus widget (if any) to tell
2106 it that it is about to lose the focus. Then a focus in event is sent to
2107 this widget to tell it that it just received the focus. (Nothing
2108 happens if the focus in and focus out widgets are the same.)
2109 setFocus() gives focus to a widget regardless of its focus policy, but
2111 does not clear any keyboard grab (see grabKeyboard()).
2112 Be aware that if the widget is hidden, it will not accept focus.
2114 Warning: If you call setFocus() in a function which may itself be
2116 called from focusOutEvent() or focusInEvent(), you may get an infinite
2117 recursion.
2118 See also focus, clearFocus(), focusInEvent(), focusOutEvent(),
2120 focusPolicy, QApplication::focusWidget(), grabKeyboard(), and
2121 grabMouse().
2122 Examples:
2124
2126 Sets the way the widget accepts keyboard focus. See the "focusPolicy"
2127 property for details.
2128
2130 Sets the widget's focus proxy to widget w. If w is 0, the function
2131 resets this widget to have no focus proxy.
2132 Some widgets, such as QComboBox, can "have focus", but create a child
2134 widget to actually handle the focus. QComboBox, for example, creates a
2135 QLineEdit which handles the focus.
2136 setFocusProxy() sets the widget which will actually get focus when"
2138 this widget" gets it. If there is a focus proxy, focusPolicy(),
2139 setFocusPolicy(), setFocus() and hasFocus() all operate on the focus
2140 proxy.
2141 See also focusProxy().
2143
2145 Sets the font currently set for the widget. See the "font" property for
2146 details.
2147 Reimplemented in QComboBox, QLabel, and QTabDialog.
2149
2151 This function is obsolete. It is provided to keep old source working.
2152 We strongly advise against using it in new code.
2153 Use setFont(const QFont& font) instead.
2155
2157 Sets the geometry of the widget relative to its parent and excluding
2158 the window frame. See the "geometry" property for details.
2159
2161 This is an overloaded member function, provided for convenience. It
2162 behaves essentially like the above function.
2163 This corresponds to setGeometry( QRect(x, y, w, h) ).
2165
2167 Sets whether the widget is explicitly hidden to hide. See the "hidden"
2168 property for details.
2169
2171 Sets the widget's icon. See the "icon" property for details.
2172
2174 Sets the widget's icon text. See the "iconText" property for details.
2175
2177 Sets enables or disables the use of input methods for this widget to b.
2178 See the "inputMethodEnabled" property for details.
2179
2181 Enables key event compression, if compress is TRUE, and disables it if
2182 compress is FALSE.
2183 Key compression is off by default (except for QLineEdit and QTextEdit),
2185 so widgets receive one key press event for each key press (or more,
2186 since autorepeat is usually on). If you turn it on and your program
2187 doesn't keep up with key input, Qt may try to compress key events so
2188 that more than one character can be processed in each event.
2189 For example, a word processor widget might receive 2, 3 or more
2191 characters in each QKeyEvent::text(), if the layout recalculation takes
2192 too long for the CPU.
2193 If a widget supports multiple character unicode input, it is always
2195 safe to turn the compression on.
2196 Qt performs key event compression only for printable characters.
2198 Modifier keys, cursor movement keys, function keys and miscellaneous
2199 action keys (e.g. Escape, Enter, Backspace, PrintScreen) will stop key
2200 event compression, even if there are more compressible key events
2201 available.
2202 Not all platforms support this compression, in which case turning it on
2204 will have no effect.
2205 See also QKeyEvent::text().
2207
2209 Causes only the pixels of the widget for which bitmap has a
2210 corresponding 1 bit to be visible. Use Qt::color0 to draw transparent
2211 regions and Qt::color1 to draw opaque regions of the bitmap.
2212 If the region includes pixels outside the rect() of the widget, window
2214 system controls in that area may or may not be visible, depending on
2215 the platform.
2216 Note that this effect can be slow if the region is particularly
2218 complex.
2219 See examples/tux for an example of masking for transparency.
2221 See also clearMask().
2223
2225 This is an overloaded member function, provided for convenience. It
2226 behaves essentially like the above function.
2227 Causes only the parts of the widget which overlap region to be visible.
2229 If the region includes pixels outside the rect() of the widget, window
2230 system controls in that area may or may not be visible, depending on
2231 the platform.
2232 Note that this effect can be slow if the region is particularly
2234 complex.
2235 See also clearMask().
2237
2239 Sets the widget's maximum height to maxh. See the "maximumHeight"
2240 property for details.
2241
2243 Sets the widget's maximum size. See the "maximumSize" property for
2244 details.
2245
2247 This is an overloaded member function, provided for convenience. It
2248 behaves essentially like the above function.
2249 This function corresponds to setMaximumSize( QSize(maxw, maxh) ). Sets
2251 the maximum width to maxw and the maximum height to maxh.
2252
2254 Sets the widget's maximum width to maxw. See the "maximumWidth"
2255 property for details.
2256
2258 text = TRUE, QFont * f = 0 ) [virtual protected]
2259 When a widget gets focus, it should call setMicroFocusHint() with some
2260 appropriate position and size, x, y, width and height. This has no
2261 visual effect, it just provides hints to any system-specific input
2262 handling tools.
2263 The text argument should be TRUE if this is a position for text input.
2265 In the Windows version of Qt, this method sets the system caret, which
2267 is used for user Accessibility focus handling. If text is TRUE, it also
2268 sets the IME composition window in Far East Asian language input
2269 systems.
2270 In the X11 version of Qt, if text is TRUE, this method sets the XIM
2272 "spot" point for complex language input handling.
2273 The font f is a rendering hint to the currently active input method. If
2275 f is 0 the widget's font is used.
2276 See also microFocusHint.
2278
2280 Sets the widget's minimum height to minh. See the "minimumHeight"
2281 property for details.
2282
2284 Sets the widget's minimum size. See the "minimumSize" property for
2285 details.
2286
2288 This is an overloaded member function, provided for convenience. It
2289 behaves essentially like the above function.
2290 This function corresponds to setMinimumSize( QSize(minw, minh) ). Sets
2292 the minimum width to minw and the minimum height to minh.
2293
2295 Sets the widget's minimum width to minw. See the "minimumWidth"
2296 property for details.
2297
2299 Sets whether mouse tracking is enabled for the widget to enable. See
2300 the "mouseTracking" property for details.
2301
2303 Sets the widget's palette. See the "palette" property for details.
2304 Reimplemented in QComboBox, QScrollBar, and QSlider.
2306
2308 This function is obsolete. It is provided to keep old source working.
2309 We strongly advise against using it in new code.
2310 Use setPalette( const QPalette& p ) instead.
2312
2314 Sets the background color of the widget. See the
2315 "paletteBackgroundColor" property for details.
2316
2318 Sets the background pixmap of the widget. See the
2319 "paletteBackgroundPixmap" property for details.
2320
2322 Sets the foreground color of the widget. See the
2323 "paletteForegroundColor" property for details.
2324
2326 Sets whether the widget is shown to show. See the "shown" property for
2327 details.
2328
2330 Sets the size increment of the widget. See the "sizeIncrement" property
2331 for details.
2332
2334 This is an overloaded member function, provided for convenience. It
2335 behaves essentially like the above function.
2336 Sets the x (width) size increment to w and the y (height) size
2338 increment to h.
2339
2341 Sets the default layout behavior of the widget. See the "sizePolicy"
2342 property for details.
2343
2345 ver, bool hfw = FALSE )
2346 This is an overloaded member function, provided for convenience. It
2347 behaves essentially like the above function.
2348 Sets the size policy of the widget to hor, ver and hfw (height for
2350 width).
2351 See also QSizePolicy::QSizePolicy().
2353
2355 Sets the widget's GUI style to style. Ownership of the style object is
2356 not transferred.
2357 If no style is set, the widget uses the application's style,
2359 QApplication::style() instead.
2360 Setting a widget's style has no effect on existing or future child
2362 widgets.
2363 Warning: This function is particularly useful for demonstration
2365 purposes, where you want to show Qt's styling capabilities. Real
2366 applications should avoid it and use one consistent GUI style instead.
2367 See also style(), QStyle, QApplication::style(), and
2369 QApplication::setStyle().
2370 Examples:
2372
2374 This is an overloaded member function, provided for convenience. It
2375 behaves essentially like the above function.
2376 Sets the widget's GUI style to style using the QStyleFactory.
2378
2380 Moves the second widget around the ring of focus widgets so that
2381 keyboard focus moves from the first widget to the second widget when
2382 the Tab key is pressed.
2383 Note that since the tab order of the second widget is changed, you
2385 should order a chain like this:
2386 setTabOrder( a, b ); // a to b
2388 setTabOrder( b, c ); // a to b to c
2389 setTabOrder( c, d ); // a to b to c to d
2390 not like this:
2392 setTabOrder( c, d ); // c to d WRONG
2394 setTabOrder( a, b ); // a to b AND c to d
2395 setTabOrder( b, c ); // a to b to c, but not c to d
2396 If first or second has a focus proxy, setTabOrder() correctly
2398 substitutes the proxy.
2399 See also focusPolicy and setFocusProxy().
2401 Example: customlayout/main.cpp.
2403
2405 Sets whether updates are enabled to enable. See the "updatesEnabled"
2406 property for details.
2407
2409 Sets the widget flags f.
2410 Widget flags are a combination of Qt::WidgetFlags.
2412 See also testWFlags(), getWFlags(), and clearWFlags().
2414
2416 Sets the level of opacity for the window to level. See the
2417 "windowOpacity" property for details.
2418
2420 Sets the window state to windowState. The window state is a OR'ed
2421 combination of Qt::WindowState: WindowMinimized, WindowMaximized,
2422 WindowFullScreen and WindowActive.
2423 If the window is not visible (i.e. isVisible() returns FALSE), the
2425 window state will take effect when show() is called. For visible
2426 windows, the change is immediate. For example, to toggle between full-
2427 screen and mormal mode, use the following code:
2428 w->setWindowState(w->windowState() ^ WindowFullScreen);
2430 In order to restore and activate a minimized window (while preserving
2432 its maximized and/or full-screen state), use the following:
2433 w->setWindowState(w->windowState() & ~WindowMinimized | WindowActive);
2435 Note: On some window systems WindowActive is not immediate, and may be
2437 ignored in certain cases.
2438 See also Qt::WindowState and windowState().
2440
2442 Shows the widget and its child widgets.
2443 If its size or position has changed, Qt guarantees that a widget gets
2445 move and resize events just before it is shown.
2446 You almost never have to reimplement this function. If you need to
2448 change some settings before a widget is shown, use showEvent() instead.
2449 If you need to do some delayed initialization use polish().
2450 See also showEvent(), hide(), showMinimized(), showMaximized(),
2452 showNormal(), visible, and polish().
2453 Examples:
2455 Reimplemented in QDialog and QMenuBar.
2457
2459 This event handler can be reimplemented in a subclass to receive widget
2460 show events.
2461 Non-spontaneous show events are sent to widgets immediately before they
2463 are shown. The spontaneous show events of top-level widgets are
2464 delivered afterwards.
2465 See also event() and QShowEvent.
2467 Example: qdir/qdir.cpp.
2469
2471 Shows the widget in full-screen mode.
2472 Calling this function only affects top-level widgets.
2474 To return from full-screen mode, call showNormal().
2476 Full-screen mode works fine under Windows, but has certain problems
2478 under X. These problems are due to limitations of the ICCCM protocol
2479 that specifies the communication between X11 clients and the window
2480 manager. ICCCM simply does not understand the concept of non-decorated
2481 full-screen windows. Therefore, the best we can do is to request a
2482 borderless window and place and resize it to fill the entire screen.
2483 Depending on the window manager, this may or may not work. The
2484 borderless window is requested using MOTIF hints, which are at least
2485 partially supported by virtually all modern window managers.
2486 An alternative would be to bypass the window manager entirely and
2488 create a window with the WX11BypassWM flag. This has other severe
2489 problems though, like totally broken keyboard focus and very strange
2490 effects on desktop changes or when the user raises other windows.
2491 X11 window managers that follow modern post-ICCCM specifications
2493 support full-screen mode properly.
2494 See also showNormal(), showMaximized(), show(), hide(), and visible.
2496
2498 Shows the widget maximized.
2499 Calling this function only affects top-level widgets.
2501 On X11, this function may not work properly with certain window
2503 managers. See the Window Geometry documentation for an explanation.
2504 See also setWindowState(), showNormal(), showMinimized(), show(),
2506 hide(), and visible.
2507 Examples:
2509
2511 Shows the widget minimized, as an icon.
2512 Calling this function only affects top-level widgets.
2514 See also showNormal(), showMaximized(), show(), hide(), visible, and
2516 minimized.
2517
2519 Restores the widget after it has been maximized or minimized.
2520 Calling this function only affects top-level widgets.
2522 See also setWindowState(), showMinimized(), showMaximized(), show(),
2524 hide(), and visible.
2525 Example: mdi/application.cpp.
2527
2529 Returns the size of the widget excluding any window frame. See the
2530 "size" property for details.
2531
2533 Returns the recommended size for the widget. See the "sizeHint"
2534 property for details.
2535 Reimplemented in QSizeGrip.
2537
2539 Returns the size increment of the widget. See the "sizeIncrement"
2540 property for details.
2541
2543 Returns the default layout behavior of the widget. See the "sizePolicy"
2544 property for details.
2545
2547 Places the widget under w in the parent widget's stack.
2548 To make this work, the widget itself and w must be siblings.
2550 See also raise() and lower().
2552
2554 Returns the GUI style for this widget
2555 See also QWidget::setStyle(), QApplication::setStyle(), and
2557 QApplication::style().
2558
2560 This virtual function is called when the style of the widgets changes.
2561 oldStyle is the previous GUI style; you can get the new style from
2562 style().
2563 Reimplement this function if your widget needs to know when its GUI
2565 style changes. You will almost certainly need to update the widget
2566 using update().
2567 The default implementation updates the widget including its geometry.
2569 See also QApplication::setStyle(), style(), update(), and
2571 updateGeometry().
2572
2574 This event handler, for event e, can be reimplemented in a subclass to
2575 receive tablet events for the widget.
2576 If you reimplement this handler, it is very important that you ignore()
2578 the event if you do not handle it, so that the widget's parent can
2579 interpret it.
2580 The default implementation ignores the event.
2582 See also QTabletEvent::ignore(), QTabletEvent::accept(), event(), and
2584 QTabletEvent.
2585
2587 Returns the bitwise AND of the widget flags and f.
2588 Widget flags are a combination of Qt::WidgetFlags.
2590 If you want to test for the presence of multiple flags (or composite
2592 flags such as WStyle_Splash), test the return value for equality
2593 against the argument. For example:
2594 int flags = WStyle_Tool | WStyle_NoBorder;
2596 if ( testWFlags(flags) )
2597 ... // WStyle_Tool or WStyle_NoBorder or both are set
2598 if ( testWFlags(flags) == flags )
2599 ... // both WStyle_Tool and WStyle_NoBorder are set
2600 See also getWFlags(), setWFlags(), and clearWFlags().
2602
2604 Returns the top-level widget for this widget, i.e. the next ancestor
2605 widget that has (or could have) a window-system frame.
2606 If the widget is a top-level, the widget itself is returned.
2608 Typical usage is changing the window caption:
2610 aWidget->topLevelWidget()->setCaption( "New Caption" );
2612 See also isTopLevel.
2614
2616 Resets the cursor shape for this widget. See the "cursor" property for
2617 details.
2618
2620 Resets the font currently set for the widget. See the "font" property
2621 for details.
2622
2624 Resets the widget's palette. See the "palette" property for details.
2625
2627 Updates the widget unless updates are disabled or the widget is hidden.
2628 This function does not cause an immediate repaint; instead it schedules
2630 a paint event for processing when Qt returns to the main event loop.
2631 This permits Qt to optimize for more speed and less flicker than a call
2632 to repaint() does.
2633 Calling update() several times normally results in just one
2635 paintEvent() call.
2636 Qt normally erases the widget's area before the paintEvent() call. If
2638 the WRepaintNoErase widget flag is set, the widget is responsible for
2639 painting all its pixels itself.
2640 See also repaint(), paintEvent(), updatesEnabled, erase(), and
2642 setWFlags().
2643 Examples:
2645
2647 This is an overloaded member function, provided for convenience. It
2648 behaves essentially like the above function.
2649 Updates a rectangle (x, y, w, h) inside the widget unless updates are
2651 disabled or the widget is hidden.
2652 This function does not cause an immediate repaint; instead it schedules
2654 a paint event for processing when Qt returns to the main event loop.
2655 This permits Qt to optimize for more speed and less flicker and a call
2656 to repaint() does.
2657 Calling update() several times normally results in just one
2659 paintEvent() call.
2660 If w is negative, it is replaced with width() - x. If h is negative, it
2662 is replaced width height() - y.
2663 Qt normally erases the specified area before the paintEvent() call. If
2665 the WRepaintNoErase widget flag is set, the widget is responsible for
2666 painting all its pixels itself.
2667 See also repaint(), paintEvent(), updatesEnabled, and erase().
2669
2671 This is an overloaded member function, provided for convenience. It
2672 behaves essentially like the above function.
2673 Updates a rectangle r inside the widget unless updates are disabled or
2675 the widget is hidden.
2676 This function does not cause an immediate repaint; instead it schedules
2678 a paint event for processing when Qt returns to the main event loop.
2679 This permits Qt to optimize for more speed and less flicker and a call
2680 to repaint() does.
2681 Calling update() several times normally results in just one
2683 paintEvent() call.
2684
2686 Notifies the layout system that this widget has changed and may need to
2687 change geometry.
2688 Call this function if the sizeHint() or sizePolicy() have changed.
2690 For explicitly hidden widgets, updateGeometry() is a no-op. The layout
2692 system will be notified as soon as the widget is shown.
2693
2695 This function can be reimplemented in a subclass to support transparent
2696 widgets. It should be called whenever a widget changes state in a way
2697 that means that the shape mask must be recalculated.
2698 See also autoMask, setMask(), and clearMask().
2700
2702 Returns the visible rectangle. See the "visibleRect" property for
2703 details.
2704
2706 This event handler, for event e, can be reimplemented in a subclass to
2707 receive wheel events for the widget.
2708 If you reimplement this handler, it is very important that you ignore()
2710 the event if you do not handle it, so that the widget's parent can
2711 interpret it.
2712 The default implementation ignores the event.
2714 See also QWheelEvent::ignore(), QWheelEvent::accept(), event(), and
2716 QWheelEvent.
2717
2719 Returns the width of the widget excluding any window frame. See the
2720 "width" property for details.
2721
2723 This special event handler can be reimplemented in a subclass to
2724 receive native Windows events.
2725 In your reimplementation of this function, if you want to stop the
2727 event being handled by Qt, return TRUE. If you return FALSE, this
2728 native event is passed back to Qt, which translates the event into a Qt
2729 event and sends it to the widget.
2730 Warning: This function is not portable.
2732 See also QApplication::winEventFilter().
2734
2736 Returns the window system identifier of the widget.
2737 Portable in principle, but if you use it you are probably about to do
2739 something non-portable. Be careful.
2740 See also find().
2742
2744 This virtual function is called for a widget when its window is
2745 activated or deactivated by the window system. oldActive is the
2746 previous state; you can get the new setting from isActiveWindow().
2747 Reimplement this function if your widget needs to know when its window
2749 becomes activated or deactivated.
2750 The default implementation updates the visible part of the widget if
2752 the inactive and the active colorgroup are different for colors other
2753 than the highlight and link colors.
2754 See also setActiveWindow(), isActiveWindow, update(), and palette.
2756
2758 Returns the level of opacity for the window. See the "windowOpacity"
2759 property for details.
2760
2762 Returns the current window state. The window state is a OR'ed
2763 combination of Qt::WindowState: WindowMinimized, WindowMaximized,
2764 WindowFullScreen and WindowActive.
2765 See also Qt::WindowState and setWindowState().
2767
2769 Returns the x coordinate of the widget relative to its parent including
2770 any window frame. See the "x" property for details.
2771
2773 This special event handler can be reimplemented in a subclass to
2774 receive native X11 events.
2775 In your reimplementation of this function, if you want to stop the
2777 event being handled by Qt, return TRUE. If you return FALSE, this
2778 native event is passed back to Qt, which translates the event into a Qt
2779 event and sends it to the widget.
2780 Warning: This function is not portable.
2782 See also QApplication::x11EventFilter().
2784 Reimplemented in QXtWidget.
2786
2788 Returns the y coordinate of the widget relative to its parent and
2789 including any window frame. See the "y" property for details.
2790 Property Documentation
2793 This property holds whether drop events are enabled for this widget.
2794 Setting this property to TRUE announces to the system that this widget
2796 may be able to accept drop events.
2797 If the widget is the desktop (QWidget::isDesktop()), this may fail if
2799 another application is using the desktop; you can call acceptDrops() to
2800 test if this occurs.
2801 Warning: Do not modify this property in a Drag&Drop event handler.
2803 Set this property's value with setAcceptDrops() and get this property's
2805 value with acceptDrops().
2806
2808 This property holds whether the auto mask feature is enabled for the
2809 widget.
2810 Transparent widgets use a mask to define their visible region. QWidget
2812 has some built-in support to make the task of recalculating the mask
2813 easier. When setting auto mask to TRUE, updateMask() will be called
2814 whenever the widget is resized or changes its focus state. Note that
2815 you must reimplement updateMask() (which should include a call to
2816 setMask()) or nothing will happen.
2817 Note: when you re-implement resizeEvent(), focusInEvent() or
2819 focusOutEvent() in your custom widgets and still want to ensure that
2820 the auto mask calculation works, you should add:
2821 if ( autoMask() )
2823 updateMask();
2824 at the end of your event handlers. This is true for all member
2826 functions that change the appearance of the widget in a way that
2827 requires a recalculation of the mask.
2828 While being a technically appealing concept, masks have a big drawback:
2830 when using complex masks that cannot be expressed easily with
2831 relatively simple regions, they can be very slow on some window
2832 systems. The classic example is a transparent label. The complex shape
2833 of its contents makes it necessary to represent its mask by a bitmap,
2834 which consumes both memory and time. If all you want is to blend the
2835 background of several neighboring widgets together seamlessly, you will
2836 probably want to use setBackgroundOrigin() rather than a mask.
2837 See also updateMask(), setMask(), clearMask(), and backgroundOrigin.
2839 Set this property's value with setAutoMask() and get this property's
2841 value with autoMask().
2842
2844 This property holds the widget's background brush.
2845 The background brush depends on a widget's palette and its background
2847 mode.
2848 See also backgroundColor(), backgroundPixmap(), eraseColor(), palette,
2850 and QApplication::setPalette().
2851 Get this property's value with backgroundBrush().
2853
2855 This property holds the color role used for painting the background of
2856 the widget.
2857 setPaletteBackgroundColor() reads this property to determine which
2859 entry of the palette to set.
2860 For most widgets the default suffices (PaletteBackground, typically
2862 gray), but some need to use PaletteBase (the background color for text
2863 output, typically white) or another role.
2864 QListBox, which is "sunken" and uses the base color to contrast with
2866 its environment, does this in its constructor:
2867 setBackgroundMode( PaletteBase );
2869 You will never need to set the background mode of a built-in widget in
2871 Qt, but you might consider setting it in your custom widgets, so that
2872 setPaletteBackgroundColor() works as expected.
2873 Note that two of the BackgroundMode values make no sense for
2875 setBackgroundMode(), namely FixedPixmap and FixedColor. You must call
2876 setBackgroundPixmap() and setPaletteBackgroundColor() instead.
2877 Set this property's value with setBackgroundMode() and get this
2879 property's value with backgroundMode().
2880
2882 This property holds the origin of the widget's background.
2883 The origin is either WidgetOrigin (the default), ParentOrigin,
2885 WindowOrigin or AncestorOrigin.
2886 This only makes a difference if the widget has a background pixmap, in
2888 which case positioning matters. Using WindowOrigin for several
2889 neighboring widgets makes the background blend together seamlessly.
2890 AncestorOrigin allows blending backgrounds seamlessly when an ancestor
2891 of the widget has an origin other than WindowOrigin.
2892 See also backgroundPixmap() and backgroundMode.
2894 Set this property's value with setBackgroundOrigin() and get this
2896 property's value with backgroundOrigin().
2897
2899 This property holds the base size of the widget.
2900 The base size is used to calculate a proper widget size if the widget
2902 defines sizeIncrement().
2903 See also sizeIncrement.
2905 Set this property's value with setBaseSize() and get this property's
2907 value with baseSize().
2908
2910 This property holds the window caption (title).
2911 This property only makes sense for top-level widgets. If no caption has
2913 been set, the caption is QString::null.
2914 See also icon and iconText.
2916 Set this property's value with setCaption() and get this property's
2918 value with caption().
2919
2921 This property holds the bounding rectangle of the widget's children.
2922 Hidden children are excluded.
2924 See also childrenRegion and geometry.
2926 Get this property's value with childrenRect().
2928
2930 This property holds the combined region occupied by the widget's
2931 children.
2932 Hidden children are excluded.
2934 See also childrenRect and geometry.
2936 Get this property's value with childrenRegion().
2938
2940 This property holds the current color group of the widget palette.
2941 The color group is determined by the state of the widget. A disabled
2943 widget has the QPalette::disabled() color group, a widget with keyboard
2944 focus has the QPalette::active() color group, and an inactive widget
2945 has the QPalette::inactive() color group.
2946 See also palette.
2948 Get this property's value with colorGroup().
2950
2952 This property holds the cursor shape for this widget.
2953 The mouse cursor will assume this shape when it's over this widget. See
2955 the list of predefined cursor objects for a range of useful shapes.
2956 An editor widget might use an I-beam cursor:
2958 setCursor( IbeamCursor );
2960 If no cursor has been set, or after a call to unsetCursor(), the
2962 parent's cursor is used. The function unsetCursor() has no effect on
2963 top-level widgets.
2964 See also QApplication::setOverrideCursor().
2966 Set this property's value with setCursor(), get this property's value
2968 with cursor(), and reset this property's value with unsetCursor().
2969
2971 This property holds whether the widget wants to handle What's This help
2972 manually.
2973 The default implementation of customWhatsThis() returns FALSE, which
2975 means the widget will not receive any events in Whats This mode.
2976 The widget may leave What's This mode by calling
2978 QWhatsThis::leaveWhatsThisMode(), with or without actually displaying
2979 any help text.
2980 You can also reimplement customWhatsThis() if your widget is a" passive
2982 interactor" supposed to work under all circumstances. Simply don't call
2983 QWhatsThis::leaveWhatsThisMode() in that case.
2984 See also QWhatsThis::inWhatsThisMode() and
2986 QWhatsThis::leaveWhatsThisMode().
2987 Get this property's value with customWhatsThis().
2989
2991 This property holds whether the widget is enabled.
2992 An enabled widget receives keyboard and mouse events; a disabled widget
2994 does not. In fact, an enabled widget only receives keyboard events when
2995 it is in focus.
2996 Some widgets display themselves differently when they are disabled. For
2998 example a button might draw its label grayed out. If your widget needs
2999 to know when it becomes enabled or disabled, you can reimplement the
3000 enabledChange() function.
3001 Disabling a widget implicitly disables all its children. Enabling
3003 respectively enables all child widgets unless they have been explicitly
3004 disabled.
3005 See also enabled, isEnabledTo(), QKeyEvent, QMouseEvent, and
3007 enabledChange().
3008 Set this property's value with setEnabled() and get this property's
3010 value with isEnabled().
3011
3013 This property holds whether this widget (or its focus proxy) has the
3014 keyboard input focus.
3015 Effectively equivalent to qApp->focusWidget() == this.
3017 See also setFocus(), clearFocus(), focusPolicy, and
3019 QApplication::focusWidget().
3020 Get this property's value with hasFocus().
3022
3024 This property holds whether the widget accepts keyboard focus.
3025 Keyboard focus is initially disabled (i.e. focusPolicy() ==
3027 QWidget::NoFocus).
3028 You must enable keyboard focus for a widget if it processes keyboard
3030 events. This is normally done from the widget's constructor. For
3031 instance, the QLineEdit constructor calls
3032 setFocusPolicy(QWidget::StrongFocus).
3033 See also focusPolicy, focusInEvent(), focusOutEvent(), keyPressEvent(),
3035 keyReleaseEvent(), and enabled.
3036 Get this property's value with isFocusEnabled().
3038
3040 This property holds the way the widget accepts keyboard focus.
3041 The policy is QWidget::TabFocus if the widget accepts keyboard focus by
3043 tabbing, QWidget::ClickFocus if the widget accepts focus by clicking,
3044 QWidget::StrongFocus if it accepts both, and QWidget::NoFocus (the
3045 default) if it does not accept focus at all.
3046 You must enable keyboard focus for a widget if it processes keyboard
3048 events. This is normally done from the widget's constructor. For
3049 instance, the QLineEdit constructor calls
3050 setFocusPolicy(QWidget::StrongFocus).
3051 See also focusEnabled, focusInEvent(), focusOutEvent(),
3053 keyPressEvent(), keyReleaseEvent(), and enabled.
3054 Set this property's value with setFocusPolicy() and get this property's
3056 value with focusPolicy().
3057
3059 This property holds the font currently set for the widget.
3060 The fontInfo() function reports the actual font that is being used by
3062 the widget.
3063 As long as no special font has been set, or after unsetFont() is
3065 called, this is either a special font for the widget class, the
3066 parent's font or (if this widget is a top level widget), the default
3067 application font.
3068 This code fragment sets a 12 point helvetica bold font:
3070 QFont f( "Helvetica", 12, QFont::Bold );
3072 setFont( f );
3073 In addition to setting the font, setFont() informs all children about
3075 the change.
3076 See also fontChange(), fontInfo(), fontMetrics(), and ownFont.
3078 Set this property's value with setFont(), get this property's value
3080 with font(), and reset this property's value with unsetFont().
3081
3083 This property holds geometry of the widget relative to its parent
3084 including any window frame.
3085 See the Window Geometry documentation for an overview of geometry
3087 issues with top-level widgets.
3088 See also geometry, x, y, and pos.
3090 Get this property's value with frameGeometry().
3092
3094 This property holds the size of the widget including any window frame.
3095 Get this property's value with frameSize().
3097
3099 This property holds whether the widget is full screen.
3100 Get this property's value with isFullScreen().
3102 See also windowState(), minimized, and maximized.
3104
3106 This property holds the geometry of the widget relative to its parent
3107 and excluding the window frame.
3108 When changing the geometry, the widget, if visible, receives a move
3110 event (moveEvent()) and/or a resize event (resizeEvent()) immediately.
3111 If the widget is not currently visible, it is guaranteed to receive
3112 appropriate events before it is shown.
3113 The size component is adjusted if it lies outside the range defined by
3115 minimumSize() and maximumSize().
3116 setGeometry() is virtual, and all other overloaded setGeometry()
3118 implementations in Qt call it.
3119 Warning: Calling setGeometry() inside resizeEvent() or moveEvent() can
3121 lead to infinite recursion.
3122 See the Window Geometry documentation for an overview of top-level
3124 widget geometry.
3125 See also frameGeometry, rect, pos, size, moveEvent(), resizeEvent(),
3127 minimumSize, and maximumSize.
3128 Set this property's value with setGeometry() and get this property's
3130 value with geometry().
3131
3133 This property holds the height of the widget excluding any window
3134 frame.
3135 See the Window Geometry documentation for an overview of top-level
3137 widget geometry.
3138 See also geometry, width, and size.
3140 Get this property's value with height().
3142
3144 This property holds whether the widget is explicitly hidden.
3145 If FALSE, the widget is visible or would become visible if all its
3147 ancestors became visible.
3148 See also hide(), show(), visible, isVisibleTo(), and shown.
3150 Set this property's value with setHidden() and get this property's
3152 value with isHidden().
3153
3155 This property holds the widget's icon.
3156 This property only makes sense for top-level widgets. If no icon has
3158 been set, icon() returns 0.
3159 See also iconText, caption, and Setting the Application Icon.
3161 Set this property's value with setIcon() and get this property's value
3163 with icon().
3164
3166 This property holds the widget's icon text.
3167 This property only makes sense for top-level widgets. If no icon text
3169 has been set, this functions returns QString::null.
3170 See also icon and caption.
3172 Set this property's value with setIconText() and get this property's
3174 value with iconText().
3175
3177 This property holds enables or disables the use of input methods for
3178 this widget.
3179 Most Widgets (as eg. buttons) that do not handle text input should have
3181 the input method disabled if they have focus. This is the default.
3182 If a widget handles text input it should set this property to TRUE.
3184 Set this property's value with setInputMethodEnabled() and get this
3186 property's value with isInputMethodEnabled().
3187
3189 This property holds whether this widget is the active window.
3190 The active window is the window that contains the widget that has
3192 keyboard focus.
3193 When popup windows are visible, this property is TRUE for both the
3195 active window and for the popup.
3196 See also setActiveWindow() and QApplication::activeWindow().
3198 Get this property's value with isActiveWindow().
3200
3202 This property holds whether the widget is a desktop widget, i.e.
3203 represents the desktop.
3204 A desktop widget is also a top-level widget.
3206 See also isTopLevel and QApplication::desktop().
3208 Get this property's value with isDesktop().
3210
3212 This property holds whether the widget is a dialog widget.
3213 A dialog widget is a secondary top-level widget, i.e. a top-level
3215 widget with a parent.
3216 See also isTopLevel and QDialog.
3218 Get this property's value with isDialog().
3220
3222 This property holds whether the widget is a modal widget.
3223 This property only makes sense for top-level widgets. A modal widget
3225 prevents widgets in all other top-level widgets from getting any input.
3226 See also isTopLevel, isDialog, and QDialog.
3228 Get this property's value with isModal().
3230
3232 This property holds whether the widget is a popup widget.
3233 A popup widget is created by specifying the widget flag WType_Popup to
3235 the widget constructor. A popup widget is also a top-level widget.
3236 See also isTopLevel.
3238 Get this property's value with isPopup().
3240
3242 This property holds whether the widget is a top-level widget.
3243 A top-level widget is a widget which usually has a frame and a caption
3245 (title). Popup and desktop widgets are also top-level widgets.
3246 A top-level widget can have a parent widget. It will then be grouped
3248 with its parent and deleted when the parent is deleted, minimized when
3249 the parent is minimized etc. If supported by the window manager, it
3250 will also have a common taskbar entry with its parent.
3251 QDialog and QMainWindow widgets are by default top-level, even if a
3253 parent widget is specified in the constructor. This behavior is
3254 specified by the WType_TopLevel widget flag.
3255 See also topLevelWidget(), isDialog, isModal, isPopup, isDesktop, and
3257 parentWidget().
3258 Get this property's value with isTopLevel().
3260
3262 This property holds whether this widget is maximized.
3263 This property is only relevant for top-level widgets.
3265 Note that due to limitations in some window-systems, this does not
3267 always report the expected results (e.g. if the user on X11 maximizes
3268 the window via the window manager, Qt has no way of distinguishing this
3269 from any other resize). This is expected to improve as window manager
3270 protocols evolve.
3271 See also windowState(), showMaximized(), visible, show(), hide(),
3273 showNormal(), and minimized.
3274 Get this property's value with isMaximized().
3276
3278 This property holds the widget's maximum height.
3279 This property corresponds to maximumSize().height().
3281 See also maximumSize and maximumWidth.
3283 Set this property's value with setMaximumHeight() and get this
3285 property's value with maximumHeight().
3286
3288 This property holds the widget's maximum size.
3289 The widget cannot be resized to a larger size than the maximum widget
3291 size.
3292 See also maximumWidth, maximumHeight, maximumSize, minimumSize, and
3294 sizeIncrement.
3295 Set this property's value with setMaximumSize() and get this property's
3297 value with maximumSize().
3298
3300 This property holds the widget's maximum width.
3301 This property corresponds to maximumSize().width().
3303 See also maximumSize and maximumHeight.
3305 Set this property's value with setMaximumWidth() and get this
3307 property's value with maximumWidth().
3308
3310 This property holds the currently set micro focus hint for this widget.
3311 See the documentation of setMicroFocusHint() for more information.
3313 Get this property's value with microFocusHint().
3315
3317 This property holds whether this widget is minimized (iconified).
3318 This property is only relevant for top-level widgets.
3320 See also showMinimized(), visible, show(), hide(), showNormal(), and
3322 maximized.
3323 Get this property's value with isMinimized().
3325
3327 This property holds the widget's minimum height.
3328 This property corresponds to minimumSize().height().
3330 See also minimumSize and minimumWidth.
3332 Set this property's value with setMinimumHeight() and get this
3334 property's value with minimumHeight().
3335
3337 This property holds the widget's minimum size.
3338 The widget cannot be resized to a smaller size than the minimum widget
3340 size. The widget's size is forced to the minimum size if the current
3341 size is smaller.
3342 If you use a layout inside the widget, the minimum size will be set by
3344 the layout and not by setMinimumSize(), unless you set the layout's
3345 resize mode to QLayout::FreeResize.
3346 See also minimumWidth, minimumHeight, maximumSize, sizeIncrement, and
3348 QLayout::resizeMode.
3349 Set this property's value with setMinimumSize() and get this property's
3351 value with minimumSize().
3352
3354 This property holds the recommended minimum size for the widget.
3355 If the value of this property is an invalid size, no minimum size is
3357 recommended.
3358 The default implementation of minimumSizeHint() returns an invalid size
3360 if there is no layout for this widget, and returns the layout's minimum
3361 size otherwise. Most built-in widgets reimplement minimumSizeHint().
3362 QLayout will never resize a widget to a size smaller than
3364 minimumSizeHint.
3365 See also QSize::isValid(), size, minimumSize, and sizePolicy.
3367 Get this property's value with minimumSizeHint().
3369
3371 This property holds the widget's minimum width.
3372 This property corresponds to minimumSize().width().
3374 See also minimumSize and minimumHeight.
3376 Set this property's value with setMinimumWidth() and get this
3378 property's value with minimumWidth().
3379
3381 This property holds whether mouse tracking is enabled for the widget.
3382 If mouse tracking is disabled (the default), the widget only receives
3384 mouse move events when at least one mouse button is pressed while the
3385 mouse is being moved.
3386 If mouse tracking is enabled, the widget receives mouse move events
3388 even if no buttons are pressed.
3389 See also mouseMoveEvent() and QApplication::setGlobalMouseTracking().
3391 Set this property's value with setMouseTracking() and get this
3393 property's value with hasMouseTracking().
3394
3396 This property holds whether the widget uses its own cursor.
3397 If FALSE, the widget uses its parent widget's cursor.
3399 See also cursor.
3401 Get this property's value with ownCursor().
3403
3405 This property holds whether the widget uses its own font.
3406 If FALSE, the widget uses its parent widget's font.
3408 See also font.
3410 Get this property's value with ownFont().
3412
3414 This property holds whether the widget uses its own palette.
3415 If FALSE, the widget uses its parent widget's palette.
3417 See also palette.
3419 Get this property's value with ownPalette().
3421
3423 This property holds the widget's palette.
3424 As long as no special palette has been set, or after unsetPalette() has
3426 been called, this is either a special palette for the widget class, the
3427 parent's palette or (if this widget is a top level widget), the default
3428 application palette.
3429 Instead of defining an entirely new palette, you can also use the
3431 paletteBackgroundColor, paletteBackgroundPixmap and
3432 paletteForegroundColor convenience properties to change a widget's
3433 background and foreground appearance only.
3434 See also ownPalette, colorGroup, and QApplication::palette().
3436 Set this property's value with setPalette(), get this property's value
3438 with palette(), and reset this property's value with unsetPalette().
3439
3441 This property holds the background color of the widget.
3442 The palette background color is usually set implicitly by
3444 setBackgroundMode(), although it can also be set explicitly by
3445 setPaletteBackgroundColor(). setPaletteBackgroundColor() is a
3446 convenience function that creates and sets a modified QPalette with
3447 setPalette(). The palette is modified according to the widget's
3448 background mode. For example, if the background mode is PaletteButton
3449 the color used for the palette's QColorGroup::Button color entry is
3450 set.
3451 If there is a background pixmap (set using
3453 setPaletteBackgroundPixmap()), then the return value of this function
3454 is indeterminate.
3455 See also paletteBackgroundPixmap, paletteForegroundColor, palette, and
3457 colorGroup.
3458 Set this property's value with setPaletteBackgroundColor(), get this
3460 property's value with paletteBackgroundColor(), and reset this
3461 property's value with unsetPalette().
3462
3464 This property holds the background pixmap of the widget.
3465 The palette background pixmap is usually set implicitly by
3467 setBackgroundMode(), although it can also be set explicitly by
3468 setPaletteBackgroundPixmap(). setPaletteBackgroundPixmap() is a
3469 convenience function that creates and sets a modified QPalette with
3470 setPalette(). The palette is modified according to the widget's
3471 background mode. For example, if the background mode is PaletteButton
3472 the pixmap used for the palette's QColorGroup::Button color entry is
3473 set.
3474 If there is a plain background color (set using
3476 setPaletteBackgroundColor()), then this function returns 0.
3477 See also paletteBackgroundColor, paletteForegroundColor, palette, and
3479 colorGroup.
3480 Set this property's value with setPaletteBackgroundPixmap(), get this
3482 property's value with paletteBackgroundPixmap(), and reset this
3483 property's value with unsetPalette().
3484
3486 This property holds the foreground color of the widget.
3487 setPaletteForegroundColor() is a convenience function that creates and
3489 sets a modified QPalette with setPalette(). The palette is modified
3490 according to the widget's background mode. For example, if the
3491 background mode is PaletteButton the palette entry
3492 QColorGroup::ButtonText is set to color.
3493 See also palette, QApplication::setPalette(), backgroundMode,
3495 foregroundColor(), backgroundMode, and setEraseColor().
3496 Set this property's value with setPaletteForegroundColor(), get this
3498 property's value with paletteForegroundColor(), and reset this
3499 property's value with unsetPalette().
3500
3502 This property holds the position of the widget within its parent
3503 widget.
3504 If the widget is a top-level widget, the position is that of the widget
3506 on the desktop, including its frame.
3507 When changing the position, the widget, if visible, receives a move
3509 event (moveEvent()) immediately. If the widget is not currently
3510 visible, it is guaranteed to receive an event before it is shown.
3511 move() is virtual, and all other overloaded move() implementations in
3513 Qt call it.
3514 Warning: Calling move() or setGeometry() inside moveEvent() can lead to
3516 infinite recursion.
3517 See the Window Geometry documentation for an overview of top-level
3519 widget geometry.
3520 See also frameGeometry, size, x, and y.
3522 Set this property's value with move() and get this property's value
3524 with pos().
3525
3527 This property holds the internal geometry of the widget excluding any
3528 window frame.
3529 The rect property equals QRect(0, 0, width(), height()).
3531 See the Window Geometry documentation for an overview of top-level
3533 widget geometry.
3534 See also size.
3536 Get this property's value with rect().
3538
3540 This property holds whether the widget is shown.
3541 If TRUE, the widget is visible or would become visible if all its
3543 ancestors became visible.
3544 See also hide(), show(), visible, isVisibleTo(), and hidden.
3546 Set this property's value with setShown() and get this property's value
3548 with isShown().
3549
3551 This property holds the size of the widget excluding any window frame.
3552 When resizing, the widget, if visible, receives a resize event
3554 (resizeEvent()) immediately. If the widget is not currently visible, it
3555 is guaranteed to receive an event before it is shown.
3556 The size is adjusted if it lies outside the range defined by
3558 minimumSize() and maximumSize(). Furthermore, the size is always at
3559 least QSize(1, 1). For toplevel widgets, the minimum size might be
3560 larger, depending on the window manager.
3561 If you want a top-level window to have a fixed size, call
3563 setResizeMode( QLayout::FreeResize ) on its layout.
3564 resize() is virtual, and all other overloaded resize() implementations
3566 in Qt call it.
3567 Warning: Calling resize() or setGeometry() inside resizeEvent() can
3569 lead to infinite recursion.
3570 See also pos, geometry, minimumSize, maximumSize, and resizeEvent().
3572 Set this property's value with resize() and get this property's value
3574 with size().
3575
3577 This property holds the recommended size for the widget.
3578 If the value of this property is an invalid size, no size is
3580 recommended.
3581 The default implementation of sizeHint() returns an invalid size if
3583 there is no layout for this widget, and returns the layout's preferred
3584 size otherwise.
3585 See also QSize::isValid(), minimumSizeHint, sizePolicy, minimumSize,
3587 and updateGeometry().
3588 Get this property's value with sizeHint().
3590
3592 This property holds the size increment of the widget.
3593 When the user resizes the window, the size will move in steps of
3595 sizeIncrement().width() pixels horizontally and sizeIncrement.height()
3596 pixels vertically, with baseSize() as the basis. Preferred widget sizes
3597 are for non-negative integers i and j:
3598 width = baseSize().width() + i * sizeIncrement().width();
3600 height = baseSize().height() + j * sizeIncrement().height();
3601 Note that while you can set the size increment for all widgets, it only
3603 affects top-level widgets.
3604 Warning: The size increment has no effect under Windows, and may be
3606 disregarded by the window manager on X.
3607 See also size, minimumSize, and maximumSize.
3609 Set this property's value with setSizeIncrement() and get this
3611 property's value with sizeIncrement().
3612
3614 This property holds the default layout behavior of the widget.
3615 If there is a QLayout that manages this widget's children, the size
3617 policy specified by that layout is used. If there is no such QLayout,
3618 the result of this function is used.
3619 The default policy is Preferred/Preferred, which means that the widget
3621 can be freely resized, but prefers to be the size sizeHint() returns.
3622 Button-like widgets set the size policy to specify that they may
3623 stretch horizontally, but are fixed vertically. The same applies to
3624 lineedit controls (such as QLineEdit, QSpinBox or an editable
3625 QComboBox) and other horizontally orientated widgets (such as
3626 QProgressBar). QToolButton's are normally square, so they allow growth
3627 in both directions. Widgets that support different directions (such as
3628 QSlider, QScrollBar or QHeader) specify stretching in the respective
3629 direction only. Widgets that can provide scrollbars (usually subclasses
3630 of QScrollView) tend to specify that they can use additional space, and
3631 that they can make do with less than sizeHint().
3632 See also sizeHint, QLayout, QSizePolicy, and updateGeometry().
3634 Set this property's value with setSizePolicy() and get this property's
3636 value with sizePolicy().
3637
3639 This property holds whether the widget is under the mouse cursor.
3640 This value is not updated properly during drag and drop operations.
3642 See also QEvent::Enter and QEvent::Leave.
3644 Get this property's value with hasMouse().
3646
3648 This property holds whether updates are enabled.
3649 Calling update() and repaint() has no effect if updates are disabled.
3651 Paint events from the window system are processed normally even if
3652 updates are disabled.
3653 setUpdatesEnabled() is normally used to disable updates for a short
3655 period of time, for instance to avoid screen flicker during large
3656 changes.
3657 Example:
3659 setUpdatesEnabled( FALSE );
3661 bigVisualChanges();
3662 setUpdatesEnabled( TRUE );
3663 repaint();
3664 See also update(), repaint(), and paintEvent().
3666 Set this property's value with setUpdatesEnabled() and get this
3668 property's value with isUpdatesEnabled().
3669
3671 This property holds whether the widget is visible.
3672 Calling show() sets the widget to visible status if all its parent
3674 widgets up to the top-level widget are visible. If an ancestor is not
3675 visible, the widget won't become visible until all its ancestors are
3676 shown.
3677 Calling hide() hides a widget explicitly. An explicitly hidden widget
3679 will never become visible, even if all its ancestors become visible,
3680 unless you show it.
3681 A widget receives show and hide events when its visibility status
3683 changes. Between a hide and a show event, there is no need to waste CPU
3684 cycles preparing or displaying information to the user. A video
3685 application, for example, might simply stop generating new frames.
3686 A widget that happens to be obscured by other windows on the screen is
3688 considered to be visible. The same applies to iconified top-level
3689 widgets and windows that exist on another virtual desktop (on platforms
3690 that support this concept). A widget receives spontaneous show and hide
3691 events when its mapping status is changed by the window system, e.g. a
3692 spontaneous hide event when the user minimizes the window, and a
3693 spontaneous show event when the window is restored again.
3694 See also show(), hide(), hidden, isVisibleTo(), minimized, showEvent(),
3696 and hideEvent().
3697 Get this property's value with isVisible().
3699
3701 This property holds the visible rectangle.
3702 This property is obsolete. It is provided to keep old source working.
3704 We strongly advise against using it in new code.
3705 No longer necessary, you can simply call repaint(). If you do not need
3707 the rectangle for repaint(), use clipRegion() instead.
3708 Get this property's value with visibleRect().
3710
3712 This property holds the width of the widget excluding any window frame.
3713 See the Window Geometry documentation for an overview of top-level
3715 widget geometry.
3716 See also geometry, height, and size.
3718 Get this property's value with width().
3720
3722 This property holds the level of opacity for the window.
3723 The valid range of opacity is from 1.0 (completely opaque) to 0.0
3725 (completely transparent).
3726 By default the value of this property is 1.0.
3728 This feature is only present on Mac OS X and Windows 2000 and up.
3730 Warning: Changing this property from opaque to transparent might issue
3732 a paint event that needs to be processed before the window is displayed
3733 correctly. This affects mainly the use of QPixmap::grabWindow(). Also
3734 note that semi-transparent windows update and resize significantely
3735 slower than opaque windows.
3736 Set this property's value with setWindowOpacity() and get this
3738 property's value with windowOpacity().
3739
3741 This property holds the x coordinate of the widget relative to its
3742 parent including any window frame.
3743 See the Window Geometry documentation for an overview of top-level
3745 widget geometry.
3746 See also frameGeometry, y, and pos.
3748 Get this property's value with x().
3750
3752 This property holds the y coordinate of the widget relative to its
3753 parent and including any window frame.
3754 See the Window Geometry documentation for an overview of top-level
3756 widget geometry.
3757 See also frameGeometry, x, and pos.
3759 Get this property's value with y().
3761
3764 http://doc.trolltech.com/qwidget.html
3765 http://www.trolltech.com/faq/tech.html
3766
3768 Copyright 1992-2007 Trolltech ASA, http://www.trolltech.com. See the
3769 license file included in the distribution for a complete license
3770 statement.
3771
3773 Generated automatically from the source code.
3774
3776 If you find a bug in Qt, please report it as described in
3777 http://doc.trolltech.com/bughowto.html. Good bug reports help us to
3778 help you. Thank you.
3779 The definitive Qt documentation is provided in HTML format; it is
3781 located at $QTDIR/doc/html and can be read using Qt Assistant or with a
3782 web browser. This man page is provided as a convenience for those users
3783 who prefer man pages, although this format is not officially supported
3784 by Trolltech.
3785 If you find errors in this manual page, please report them to qt-
3787 bugs@trolltech.com. Please include the name of the manual page
3788 (qwidget.3qt) and the Qt version (3.3.8).
3789Trolltech AS 2 February 2007 QWidget(3qt)