1QHeader(3qt)                                                      QHeader(3qt)
2
3
4

NAME

6       QHeader - Header row or column, e.g. for tables and listviews
7

SYNOPSIS

9       #include <qheader.h>
10
11       Inherits QWidget.
12
13   Public Members
14       QHeader ( QWidget * parent = 0, const char * name = 0 )
15       QHeader ( int n, QWidget * parent = 0, const char * name = 0 )
16       ~QHeader ()
17       int addLabel ( const QString & s, int size = -1 )
18       int addLabel ( const QIconSet & iconset, const QString & s, int size =
19           -1 )
20       void removeLabel ( int section )
21       virtual void setLabel ( int section, const QString & s, int size = -1 )
22       virtual void setLabel ( int section, const QIconSet & iconset, const
23           QString & s, int size = -1 )
24       QString label ( int section ) const
25       QIconSet * iconSet ( int section ) const
26       virtual void setOrientation ( Orientation )
27       Orientation orientation () const
28       virtual void setTracking ( bool enable )
29       bool tracking () const
30       virtual void setClickEnabled ( bool enable, int section = -1 )
31       virtual void setResizeEnabled ( bool enable, int section = -1 )
32       virtual void setMovingEnabled ( bool )
33       virtual void setStretchEnabled ( bool b, int section )
34       void setStretchEnabled ( bool b )
35       bool isClickEnabled ( int section = -1 ) const
36       bool isResizeEnabled ( int section = -1 ) const
37       bool isMovingEnabled () const
38       bool isStretchEnabled () const
39       bool isStretchEnabled ( int section ) const
40       void resizeSection ( int section, int s )
41       int sectionSize ( int section ) const
42       int sectionPos ( int section ) const
43       int sectionAt ( int pos ) const
44       int count () const
45       int headerWidth () const
46       QRect sectionRect ( int section ) const
47       virtual void setCellSize ( int section, int s )  (obsolete)
48       int cellSize ( int i ) const  (obsolete)
49       int cellPos ( int i ) const  (obsolete)
50       int cellAt ( int pos ) const  (obsolete)
51       int offset () const
52       int mapToSection ( int index ) const
53       int mapToIndex ( int section ) const
54       int mapToLogical ( int a ) const  (obsolete)
55       int mapToActual ( int l ) const  (obsolete)
56       void moveSection ( int section, int toIndex )
57       virtual void moveCell ( int fromIdx, int toIdx )  (obsolete)
58       void setSortIndicator ( int section, bool ascending = TRUE )
59           (obsolete)
60       void setSortIndicator ( int section, SortOrder order )
61       int sortIndicatorSection () const
62       SortOrder sortIndicatorOrder () const
63       void adjustHeaderSize ()
64
65   Public Slots
66       virtual void setOffset ( int pos )
67
68   Signals
69       void clicked ( int section )
70       void pressed ( int section )
71       void released ( int section )
72       void sizeChange ( int section, int oldSize, int newSize )
73       void indexChange ( int section, int fromIndex, int toIndex )
74       void sectionClicked ( int index )  (obsolete)
75       void moved ( int fromIndex, int toIndex )  (obsolete)
76       void sectionHandleDoubleClicked ( int section )
77
78   Properties
79       int count - the number of sections in the header  (read only)
80       bool moving - whether the header sections can be moved
81       int offset - the header's left-most (or top-most) visible pixel
82       Orientation orientation - the header's orientation
83       bool stretching - whether the header sections always take up the full
84           width (or height) of the header
85       bool tracking - whether the sizeChange() signal is emitted continuously
86
87   Protected Members
88       QRect sRect ( int index )
89       virtual void paintSection ( QPainter * p, int index, const QRect & fr )
90       virtual void paintSectionLabel ( QPainter * p, int index, const QRect &
91           fr )
92

DESCRIPTION

94       The QHeader class provides a header row or column, e.g. for tables and
95       listviews.
96
97       This class provides a header, e.g. a vertical header to display row
98       labels, or a horizontal header to display column labels. It is used by
99       QTable and QListView for example.
100
101       A header is composed of one or more sections, each of which can display
102       a text label and an iconset. A sort indicator (an arrow) can also be
103       displayed using setSortIndicator().
104
105       Sections are added with addLabel() and removed with removeLabel(). The
106       label and iconset are set in addLabel() and can be changed later with
107       setLabel(). Use count() to retrieve the number of sections in the
108       header.
109
110       The orientation of the header is set with setOrientation(). If
111       setStretchEnabled() is TRUE, the sections will expand to take up the
112       full width (height for vertical headers) of the header. The user can
113       resize the sections manually if setResizeEnabled() is TRUE. Call
114       adjustHeaderSize() to have the sections resize to occupy the full width
115       (or height).
116
117       A section can be moved with moveSection(). If setMovingEnabled() is
118       TRUE (the default)the user may drag a section from one position to
119       another. If a section is moved, the index positions at which sections
120       were added (with addLabel()), may not be the same after the move. You
121       don't have to worry about this in practice because the QHeader API
122       works in terms of section numbers, so it doesn't matter where a
123       particular section has been moved to.
124
125       If you want the current index position of a section call mapToIndex()
126       giving it the section number. (This is the number returned by the
127       addLabel() call which created the section.) If you want to get the
128       section number of a section at a particular index position call
129       mapToSection() giving it the index number.
130
131       Here's an example to clarify mapToSection() and mapToIndex():
132
133       <center>.nf
134
135       </center>
136
137       <center>.nf
138
139       </center>
140
141       In the example above, if we wanted to find out which section is at
142       index position 3 we'd call mapToSection(3) and get a section number of
143       1 since section 1 was moved. Similarly, if we wanted to know which
144       index position section 2 occupied we'd call mapToIndex(2) and get an
145       index of 1.
146
147       QHeader provides the clicked(), pressed() and released() signals. If
148       the user changes the size of a section, the sizeChange() signal is
149       emitted. If you want to have a sizeChange() signal emitted continuously
150       whilst the user is resizing (rather than just after the resizing is
151       finished), use setTracking(). If the user moves a section the
152       indexChange() signal is emitted.
153
154                                   [Image Omitted]
155
156                                   [Image Omitted]
157
158       See also QListView, QTable, and Advanced Widgets.
159

MEMBER FUNCTION DOCUMENTATION

QHeader::QHeader ( QWidget * parent = 0, const char * name = 0 )

162       Constructs a horizontal header called name, with parent parent.
163

QHeader::QHeader ( int n, QWidget * parent = 0, const char * name = 0 )

165       Constructs a horizontal header called name, with n sections and parent
166       parent.
167

QHeader::~QHeader ()

169       Destroys the header and all its sections.
170

int QHeader::addLabel ( const QString & s, int size = -1 )

172       Adds a new section with label text s. Returns the index position where
173       the section was added (at the right for horizontal headers, at the
174       bottom for vertical headers). The section's width is set to size. If
175       size < 0, an appropriate size for the text s is chosen.
176

int QHeader::addLabel ( const QIconSet & iconset, const QString & s, int size

178       = -1 )
179       This is an overloaded member function, provided for convenience. It
180       behaves essentially like the above function.
181
182       Adds a new section with iconset iconset and label text s. Returns the
183       index position where the section was added (at the right for horizontal
184       headers, at the bottom for vertical headers). The section's width is
185       set to size, unless size is negative in which case the size is
186       calculated taking account of the size of the text.
187

void QHeader::adjustHeaderSize ()

189       Adjusts the size of the sections to fit the size of the header as
190       completely as possible. Only sections for which isStretchEnabled() is
191       TRUE will be resized.
192

int QHeader::cellAt ( int pos ) const

194       This function is obsolete. It is provided to keep old source working.
195       We strongly advise against using it in new code.
196
197       Use sectionAt() instead.
198
199       Returns the index at which the section is displayed, which contains pos
200       in widget coordinates, or -1 if pos is outside the header sections.
201

int QHeader::cellPos ( int i ) const

203       This function is obsolete. It is provided to keep old source working.
204       We strongly advise against using it in new code.
205
206       Use sectionPos() instead.
207
208       Returns the position in pixels of the section that is displayed at the
209       index i. The position is measured from the start of the header.
210

int QHeader::cellSize ( int i ) const

212       This function is obsolete. It is provided to keep old source working.
213       We strongly advise against using it in new code.
214
215       Use sectionSize() instead.
216
217       Returns the size in pixels of the section that is displayed at the
218       index i.
219

void QHeader::clicked ( int section ) [signal]

221       If isClickEnabled() is TRUE, this signal is emitted when the user
222       clicks section section.
223
224       See also pressed() and released().
225

int QHeader::count () const

227       Returns the number of sections in the header. See the "count" property
228       for details.
229

int QHeader::headerWidth () const

231       Returns the total width of all the header columns.
232

QIconSet * QHeader::iconSet ( int section ) const

234       Returns the icon set for section section. If the section does not
235       exist, 0 is returned.
236

void QHeader::indexChange ( int section, int fromIndex, int toIndex ) [signal]

238
239       This signal is emitted when the user moves section section from index
240       position fromIndex, to index position toIndex.
241

bool QHeader::isClickEnabled ( int section = -1 ) const

243       Returns TRUE if section section is clickable; otherwise returns FALSE.
244
245       If section is out of range (negative or larger than count() - 1):
246       returns TRUE if all sections are clickable; otherwise returns FALSE.
247
248       See also setClickEnabled().
249

bool QHeader::isMovingEnabled () const

251       Returns TRUE if the header sections can be moved; otherwise returns
252       FALSE. See the "moving" property for details.
253

bool QHeader::isResizeEnabled ( int section = -1 ) const

255       Returns TRUE if section section is resizeable; otherwise returns FALSE.
256
257       If section is -1 then this function applies to all sections, i.e.
258       returns TRUE if all sections are resizeable; otherwise returns FALSE.
259
260       See also setResizeEnabled().
261

bool QHeader::isStretchEnabled () const

263       Returns TRUE if the header sections always take up the full width (or
264       height) of the header; otherwise returns FALSE. See the "stretching"
265       property for details.
266

bool QHeader::isStretchEnabled ( int section ) const

268       This is an overloaded member function, provided for convenience. It
269       behaves essentially like the above function.
270
271       Returns TRUE if section section will resize to take up the full width
272       (or height) of the header; otherwise returns FALSE. If at least one
273       section has stretch enabled the sections will always take up the full
274       width of the header.
275
276       See also setStretchEnabled().
277

QString QHeader::label ( int section ) const

279       Returns the text for section section. If the section does not exist, a
280       QString::null is returned.
281
282       Example: helpsystem/tooltip.cpp.
283

int QHeader::mapToActual ( int l ) const

285       This function is obsolete. It is provided to keep old source working.
286       We strongly advise against using it in new code.
287
288       Use mapToIndex() instead.
289
290       Translates from logical index l to actual index (index at which the
291       section l is displayed) . Returns -1 if l is outside the legal range.
292
293       See also mapToLogical().
294

int QHeader::mapToIndex ( int section ) const

296       Returns the index position corresponding to the specified section
297       number.
298
299       Warning: If QTable is used to move header sections as a result of user
300       interaction, the mapping exposed by this function will not reflect the
301       order of the headers in the table; i.e., QTable does not call
302       moveSection() to move sections but handles move operations internally.
303
304       See also mapToSection().
305

int QHeader::mapToLogical ( int a ) const

307       This function is obsolete. It is provided to keep old source working.
308       We strongly advise against using it in new code.
309
310       Use mapToSection() instead.
311
312       Translates from actual index a (index at which the section is
313       displayed) to logical index of the section. Returns -1 if a is outside
314       the legal range.
315
316       See also mapToActual().
317

int QHeader::mapToSection ( int index ) const

319       Returns the number of the section that corresponds to the specified
320       index.
321
322       Warning: If QTable is used to move header sections as a result of user
323       interaction, the mapping exposed by this function will not reflect the
324       order of the headers in the table; i.e., QTable does not call
325       moveSection() to move sections but handles move operations internally.
326
327       See also mapToIndex().
328

void QHeader::moveCell ( int fromIdx, int toIdx ) [virtual]

330       This function is obsolete. It is provided to keep old source working.
331       We strongly advise against using it in new code.
332
333       Use moveSection() instead.
334
335       Moves the section that is currently displayed at index fromIdx to index
336       toIdx.
337

void QHeader::moveSection ( int section, int toIndex )

339       Moves section section to index position toIndex.
340

void QHeader::moved ( int fromIndex, int toIndex ) [signal]

342       This function is obsolete. It is provided to keep old source working.
343       We strongly advise against using it in new code.
344
345       Use indexChange() instead.
346
347       This signal is emitted when the user has moved the section which is
348       displayed at the index fromIndex to the index toIndex.
349

int QHeader::offset () const

351       Returns the header's left-most (or top-most) visible pixel. See the
352       "offset" property for details.
353

Orientation QHeader::orientation () const

355       Returns the header's orientation. See the "orientation" property for
356       details.
357

void QHeader::paintSection ( QPainter * p, int index, const QRect & fr )

359       [virtual protected]
360       Paints the section at position index, inside rectangle fr (which uses
361       widget coordinates) using painter p.
362
363       Calls paintSectionLabel().
364

void QHeader::paintSectionLabel ( QPainter * p, int index, const QRect & fr )

366       [virtual protected]
367       Paints the label of the section at position index, inside rectangle fr
368       (which uses widget coordinates) using painter p.
369
370       Called by paintSection()
371

void QHeader::pressed ( int section ) [signal]

373       This signal is emitted when the user presses section section down.
374
375       See also released().
376

void QHeader::released ( int section ) [signal]

378       This signal is emitted when section section is released.
379
380       See also pressed().
381

void QHeader::removeLabel ( int section )

383       Removes section section. If the section does not exist, nothing
384       happens.
385

void QHeader::resizeSection ( int section, int s )

387       Resizes section section to s pixels wide (or high).
388

QRect QHeader::sRect ( int index ) [protected]

390       Returns the rectangle covered by the section at index index.
391

int QHeader::sectionAt ( int pos ) const

393       Returns the index of the section which contains the position pos given
394       in pixels from the left (or top).
395
396       See also offset.
397
398       Example: helpsystem/tooltip.cpp.
399

void QHeader::sectionClicked ( int index ) [signal]

401       This function is obsolete. It is provided to keep old source working.
402       We strongly advise against using it in new code.
403
404       Use clicked() instead.
405
406       This signal is emitted when a part of the header is clicked. index is
407       the index at which the section is displayed.
408
409       In a list view this signal would typically be connected to a slot that
410       sorts the specified column (or row).
411

void QHeader::sectionHandleDoubleClicked ( int section ) [signal]

413       This signal is emitted when the user doubleclicks on the edge (handle)
414       of section section.
415

int QHeader::sectionPos ( int section ) const

417       Returns the position (in pixels) at which the section starts.
418
419       See also offset.
420

QRect QHeader::sectionRect ( int section ) const

422       Returns the rectangle covered by section section.
423
424       Example: helpsystem/tooltip.cpp.
425

int QHeader::sectionSize ( int section ) const

427       Returns the width (or height) of the section in pixels.
428

void QHeader::setCellSize ( int section, int s ) [virtual]

430       This function is obsolete. It is provided to keep old source working.
431       We strongly advise against using it in new code.
432
433       Use resizeSection() instead.
434
435       Sets the size of the section section to s pixels.
436
437       Warning: does not repaint or send out signals
438

void QHeader::setClickEnabled ( bool enable, int section = -1 ) [virtual]

440       If enable is TRUE, any clicks on section section will result in
441       clicked() signals being emitted; otherwise the section will ignore
442       clicks.
443
444       If section is -1 (the default) then the enable value is set for all
445       existing sections and will be applied to any new sections that are
446       added.
447
448       See also moving and setResizeEnabled().
449

void QHeader::setLabel ( int section, const QString & s, int size = -1 )

451       [virtual]
452       Sets the text of section section to s. The section's width is set to
453       size if size >= 0; otherwise it is left unchanged. Any icon set that
454       has been set for this section remains unchanged.
455
456       If the section does not exist, nothing happens.
457
458       Examples:
459

void QHeader::setLabel ( int section, const QIconSet & iconset, const QString

461       & s, int size = -1 ) [virtual]
462       This is an overloaded member function, provided for convenience. It
463       behaves essentially like the above function.
464
465       Sets the icon for section section to iconset and the text to s. The
466       section's width is set to size if size >= 0; otherwise it is left
467       unchanged.
468
469       If the section does not exist, nothing happens.
470

void QHeader::setMovingEnabled ( bool ) [virtual]

472       Sets whether the header sections can be moved. See the "moving"
473       property for details.
474

void QHeader::setOffset ( int pos ) [virtual slot]

476       Sets the header's left-most (or top-most) visible pixel to pos. See the
477       "offset" property for details.
478

void QHeader::setOrientation ( Orientation ) [virtual]

480       Sets the header's orientation. See the "orientation" property for
481       details.
482

void QHeader::setResizeEnabled ( bool enable, int section = -1 ) [virtual]

484       If enable is TRUE the user may resize section section; otherwise the
485       section may not be manually resized.
486
487       If section is negative (the default) then the enable value is set for
488       all existing sections and will be applied to any new sections that are
489       added. Example:
490
491           // Allow resizing of all current and future sections
492           header->setResizeEnabled(TRUE);
493           // Disable resizing of section 3, (the fourth section added)
494           header->setResizeEnabled(FALSE, 3);
495
496       If the user resizes a section, a sizeChange() signal is emitted.
497
498       See also moving, setClickEnabled(), and tracking.
499

void QHeader::setSortIndicator ( int section, SortOrder order )

501       Sets a sort indicator onto the specified section. The indicator's order
502       is either Ascending or Descending.
503
504       Only one section can show a sort indicator at any one time. If you
505       don't want any section to show a sort indicator pass a section number
506       of -1.
507
508       See also sortIndicatorSection() and sortIndicatorOrder().
509

void QHeader::setSortIndicator ( int section, bool ascending = TRUE )

511       This is an overloaded member function, provided for convenience. It
512       behaves essentially like the above function.
513
514       This function is obsolete. It is provided to keep old source working.
515       We strongly advise against using it in new code.
516
517       Use the other overload instead.
518

void QHeader::setStretchEnabled ( bool b, int section ) [virtual]

520       If b is TRUE, section section will be resized when the header is
521       resized, so that the sections take up the full width (or height for
522       vertical headers) of the header; otherwise section section will be set
523       to be unstretchable and will not resize when the header is resized.
524
525       If section is -1, and if b is TRUE, then all sections will be resized
526       equally when the header is resized so that they take up the full width
527       (or height for vertical headers) of the header; otherwise all the
528       sections will be set to be unstretchable and will not resize when the
529       header is resized.
530
531       See also adjustHeaderSize().
532

void QHeader::setStretchEnabled ( bool b )

534       Sets whether the header sections always take up the full width (or
535       height) of the header to b. See the "stretching" property for details.
536

void QHeader::setTracking ( bool enable ) [virtual]

538       Sets whether the sizeChange() signal is emitted continuously to enable.
539       See the "tracking" property for details.
540

void QHeader::sizeChange ( int section, int oldSize, int newSize ) [signal]

542       This signal is emitted when the user has changed the size of a section
543       from oldSize to newSize. This signal is typically connected to a slot
544       that repaints the table or list that contains the header.
545

SortOrder QHeader::sortIndicatorOrder () const

547       Returns the implied sort order of the QHeaders sort indicator.
548
549       See also setSortIndicator() and sortIndicatorSection().
550

int QHeader::sortIndicatorSection () const

552       Returns the section showing the sort indicator or -1 if there is no
553       sort indicator.
554
555       See also setSortIndicator() and sortIndicatorOrder().
556

bool QHeader::tracking () const

558       Returns TRUE if the sizeChange() signal is emitted continuously;
559       otherwise returns FALSE. See the "tracking" property for details.
560
561   Property Documentation

int count

563       This property holds the number of sections in the header.
564
565       Get this property's value with count().
566

bool moving

568       This property holds whether the header sections can be moved.
569
570       If this property is TRUE (the default) the user can move sections. If
571       the user moves a section the indexChange() signal is emitted.
572
573       See also setClickEnabled() and setResizeEnabled().
574
575       Set this property's value with setMovingEnabled() and get this
576       property's value with isMovingEnabled().
577

int offset

579       This property holds the header's left-most (or top-most) visible pixel.
580
581       Setting this property will scroll the header so that offset becomes the
582       left-most (or top-most for vertical headers) visible pixel.
583
584       Set this property's value with setOffset() and get this property's
585       value with offset().
586

Orientation orientation

588       This property holds the header's orientation.
589
590       The orientation is either Vertical or Horizontal (the default).
591
592       Call setOrientation() before adding labels if you don't provide a size
593       parameter otherwise the sizes will be incorrect.
594
595       Set this property's value with setOrientation() and get this property's
596       value with orientation().
597

bool stretching

599       This property holds whether the header sections always take up the full
600       width (or height) of the header.
601
602       Set this property's value with setStretchEnabled() and get this
603       property's value with isStretchEnabled().
604

bool tracking

606       This property holds whether the sizeChange() signal is emitted
607       continuously.
608
609       If tracking is on, the sizeChange() signal is emitted continuously
610       while the mouse is moved (i.e. when the header is resized), otherwise
611       it is only emitted when the mouse button is released at the end of
612       resizing.
613
614       Tracking defaults to FALSE.
615
616       Set this property's value with setTracking() and get this property's
617       value with tracking().
618
619

SEE ALSO

621       http://doc.trolltech.com/qheader.html
622       http://www.trolltech.com/faq/tech.html
623
625       Copyright 1992-2007 Trolltech ASA, http://www.trolltech.com.  See the
626       license file included in the distribution for a complete license
627       statement.
628

AUTHOR

630       Generated automatically from the source code.
631

BUGS

633       If you find a bug in Qt, please report it as described in
634       http://doc.trolltech.com/bughowto.html.  Good bug reports help us to
635       help you. Thank you.
636
637       The definitive Qt documentation is provided in HTML format; it is
638       located at $QTDIR/doc/html and can be read using Qt Assistant or with a
639       web browser. This man page is provided as a convenience for those users
640       who prefer man pages, although this format is not officially supported
641       by Trolltech.
642
643       If you find errors in this manual page, please report them to qt-
644       bugs@trolltech.com.  Please include the name of the manual page
645       (qheader.3qt) and the Qt version (3.3.8).
646
647
648
649Trolltech AS                    2 February 2007                   QHeader(3qt)
Impressum