# CEGUI::ListHeader Class Reference

Base class for the multi column list header widget. More...

Inheritance diagram for CEGUI::ListHeader:

[legend]
Collaboration diagram for CEGUI::ListHeader:

[legend]
List of all members.

## Public Member Functions

uint | getColumnCount (void) const
| Return the number of columns or segments attached to the header.
ListHeaderSegment & | getSegmentFromColumn (uint column) const
| Return the ListHeaderSegment object for the specified column.
ListHeaderSegment & | getSegmentFromID (uint id) const
| Return the ListHeaderSegment object with the specified ID.
ListHeaderSegment & | getSortSegment (void) const
| Return the ListHeaderSegment that is marked as being the 'sort key' segment. There must be at least one segment to successfully call this method.
uint | getColumnFromSegment (const ListHeaderSegment &segment) const
| Return the zero based column index of the specified segment.
uint | getColumnFromID (uint id) const
| Return the zero based column index of the segment with the specified ID.
uint | getSortColumn (void) const
| Return the zero based index of the current sort column. There must be at least one segment/column to successfully call this method.
uint | getColumnWithText (const String &text) const
| Return the zero based column index of the segment with the specified text.
float | getPixelOffsetToSegment (const ListHeaderSegment &segment) const
| Return the pixel offset to the given ListHeaderSegment.
float | getPixelOffsetToColumn (uint column) const
| Return the pixel offset to the ListHeaderSegment at the given zero based column index.
float | getTotalSegmentsPixelExtent (void) const
| Return the total pixel width of all attached segments.
float | getColumnPixelWidth (uint column) const
| Return the pixel width of the specified column.
ListHeaderSegment::SortDirection | getSortDirection (void) const
| Return the currently set sort direction.
bool | isSortingEnabled (void) const
| Return whether user manipulation of the sort column & direction are enabled.
bool | isColumnSizingEnabled (void) const
| Return whether the user may size column segments.
bool | isColumnDraggingEnabled (void) const
| Return whether the user may modify the order of the segments.
float | getSegmentOffset (void) const
| Return the current segment offset value. This value is used to implement scrolling of the header segments within the ListHeader area.
void | setSortingEnabled (bool setting)
| Set whether user manipulation of the sort column and direction is enabled.
void | setSortDirection (ListHeaderSegment::SortDirection direction)
| Set the current sort direction.
void | setSortSegment (const ListHeaderSegment &segment)
| Set the column segment to be used as the sort column.
void | setSortColumn (uint column)
| Set the column to be used as the sort column.
void | setSortColumnFromID (uint id)
| Set the column to to be used for sorting via its ID code.
void | setColumnSizingEnabled (bool setting)
| Set whether columns may be sized by the user.
void | setColumnDraggingEnabled (bool setting)
| Set whether columns may be reordered by the user via drag and drop.
void | addColumn (const String &text, uint id, float width)
| Add a new column segment to the end of the header.
void | insertColumn (const String &text, uint id, float width, uint position)
| Insert a new column segment at the specified position.
void | insertColumn (const String &text, uint id, float width, const ListHeaderSegment &position)
| Insert a new column segment at the specified position.
void | removeColumn (uint column)
| Removes a column segment from the ListHeader.
void | removeSegment (const ListHeaderSegment &segment)
| Remove the specified segment from the ListHeader.
void | moveColumn (uint column, uint position)
| Moves a column segment into a new position.
void | moveColumn (uint column, const ListHeaderSegment &position)
| Move a column segment to a new position.
void | moveSegment (const ListHeaderSegment &segment, uint position)
| Moves a segment into a new position.
void | moveSegment (const ListHeaderSegment &segment, const ListHeaderSegment &position)
| Move a segment to a new position.
void | setSegmentOffset (float offset)
| Set the current base segment offset. (This implements scrolling of the header segments within the header area).
void | setColumnPixelWidth (uint column, float width)
| Set the pixel width of the specified column.
| ListHeader (const String &type, const String &name)
| Constructor for the list header base class.
virtual | ~ListHeader (void)
| Destructor for the list header base class.

## Static Public Attributes

static const String | EventNamespace
| Namespace for global events.
static const String | EventSortColumnChanged
| Event fired when the current sort column changes.
static const String | EventSortDirectionChanged
| Event fired when the sort direction changes.
static const String | EventSegmentSized
| Event fired when a segment has been sized by the user (e.window is the segment).
static const String | EventSegmentClicked
| Event fired when a segment has been clicked by the user (e.window is the segment).
static const String | EventSplitterDoubleClicked
| Event fired when a segment splitter has been double-clicked. (e.window is the segment).
static const String | EventSegmentSequenceChanged
| Event fired when the order of the segments has changed. ('e' is a HeaderSequenceEventArgs&).
static const String | EventSegmentAdded
| Event fired when a segment is added to the header.
static const String | EventSegmentRemoved
| Event fired when a segment is removed from the header.
static const String | EventSortSettingChanged
| Event fired when setting that controls user modification to sort configuration changes.
static const String | EventDragMoveSettingChanged
| Event fired when setting that controls user drag & drop of segments changes.
static const String | EventDragSizeSettingChanged
| Event fired when setting that controls user sizing of segments changes.
static const String | EventSegmentRenderOffsetChanged
| Event fired when the rendering offset for the segments changes.
static const float | ScrollSpeed = 8.0f
| Speed to scroll at when dragging outside header.
static const float | MinimumSegmentPixelWidth = 20.0f
| Miniumum width of a segment in pixels.

## Protected Types

typedef std::vector< ListHeaderSegment * > | SegmentList

## Protected Member Functions

virtual ListHeaderSegment * | createNewSegment (const String &name) const =0
| Create and return a pointer to a new ListHeaderSegment based object.
virtual void | destroyListSegment (ListHeaderSegment *segment) const =0
| Cleanup and destroy the given ListHeaderSegment that was created via the createNewSegment method.
ListHeaderSegment * | createInitialisedSegment (const String &text, uint id, float width)
| Create initialise and return a ListHeaderSegment object, with all events subscribed and ready to use.
void | layoutSegments (void)
| Layout the attached segments.
void | addListHeaderEvents (void)
| Add ListHeader specific events.
virtual bool | testClassName_impl (const String &class_name) const
| Return whether this window was inherited from the given class name at some point in the inheritance heirarchy.
virtual void | onSortColumnChanged (WindowEventArgs &e)
| Handler called when the sort column is changed.
virtual void | onSortDirectionChanged (WindowEventArgs &e)
| Handler called when the sort direction is changed.
virtual void | onSegmentSized (WindowEventArgs &e)
| Handler called when a segment is sized by the user. e.window points to the segment.
virtual void | onSegmentClicked (WindowEventArgs &e)
| Handler called when a segment is clicked by the user. e.window points to the segment.
virtual void | onSplitterDoubleClicked (WindowEventArgs &e)
| Handler called when a segment splitter / sizer is double-clicked. e.window points to the segment.
virtual void | onSegmentSequenceChanged (WindowEventArgs &e)
| Handler called when the segment / column order changes.
virtual void | onSegmentAdded (WindowEventArgs &e)
| Handler called when a new segment is added to the header.
virtual void | onSegmentRemoved (WindowEventArgs &e)
| Handler called when a segment is removed from the header.
virtual void | onSortSettingChanged (WindowEventArgs &e)
| Handler called then setting that controls the users ability to modify the search column & direction changes.
virtual void | onDragMoveSettingChanged (WindowEventArgs &e)
| Handler called when the setting that controls the users ability to drag and drop segments changes.
virtual void | onDragSizeSettingChanged (WindowEventArgs &e)
| Handler called when the setting that controls the users ability to size segments changes.
virtual void | onSegmentOffsetChanged (WindowEventArgs &e)
| Handler called when the base rendering offset for the segments (scroll position) changes.
bool | segmentSizedHandler (const EventArgs &e)
bool | segmentMovedHandler (const EventArgs &e)
bool | segmentClickedHandler (const EventArgs &e)
bool | segmentDoubleClickHandler (const EventArgs &e)
bool | segmentDragHandler (const EventArgs &e)

## Protected Attributes

SegmentList | d_segments
| Attached segment windows in header order.
ListHeaderSegment * | d_sortSegment
| Pointer to the segment that is currently set as the sork-key,.
bool | d_sizingEnabled
| true if segments can be sized by the user.
bool | d_sortingEnabled
| true if the sort criteria modifications by user are enabled (no sorting is actuall done)
bool | d_movingEnabled
| true if drag & drop moving of columns / segments is enabled.
uint | d_uniqueIDNumber
| field used to create unique names.
float | d_segmentOffset
| Base offset used to layout the segments (allows scrolling within the window area).
ListHeaderSegment::SortDirection | d_sortDir
| Brief copy of the current sort direction.

## Detailed Description

Base class for the multi column list header widget.

## Member Function Documentation

void CEGUI::ListHeader::addColumn | ( | const String & | text,
|  | uint | id,
|  | float | width
| ) |

Add a new column segment to the end of the header.

Parameters:

  | text | String object holding the initial text for the new segment
  | id | Client specified ID code to be assigned to the new segment.
  | width | Initial width of the new segment using the relative metrics system

Returns:
  Nothing.

virtual ListHeaderSegment* CEGUI::ListHeader::createNewSegment | ( | const String & | name | ) | const`[protected, pure virtual]`

Create and return a pointer to a new ListHeaderSegment based object.

Parameters:

  | name | String object holding the name that should be given to the new Window.

Returns:
  Pointer to an ListHeaderSegment based object of whatever type is appropriate for this ListHeader.

virtual void CEGUI::ListHeader::destroyListSegment | ( | ListHeaderSegment * | segment | ) | const`[protected, pure virtual]`

Cleanup and destroy the given ListHeaderSegment that was created via the createNewSegment method.

Parameters:

  | segment | Pointer to a ListHeaderSegment based object to be destroyed.

Returns:
  Nothing.

uint CEGUI::ListHeader::getColumnCount | ( | void |  | ) | const

Return the number of columns or segments attached to the header.

Returns:
  uint value equal to the number of columns / segments currently in the header.

uint CEGUI::ListHeader::getColumnFromID | ( | uint | id | ) | const

Return the zero based column index of the segment with the specified ID.

Parameters:

  | id | ID code of the segment whos column index is to be returned.

Returns:
  Zero based column index of the first ListHeaderSegment whos ID matches id.

Exceptions:

  | InvalidRequestException | thrown if no attached segment has the requested ID.

uint CEGUI::ListHeader::getColumnFromSegment | ( | const ListHeaderSegment & | segment | ) | const

Return the zero based column index of the specified segment.

Parameters:

  | segment | ListHeaderSegment whos zero based index is to be returned.

Returns:
  Zero based column index of the ListHeaderSegment segment.

Exceptions:

  | InvalidRequestException | thrown if segment is not attached to this ListHeader.

float CEGUI::ListHeader::getColumnPixelWidth | ( | uint | column | ) | const

Return the pixel width of the specified column.

Parameters:

  | column | Zero based column index of the segment whos pixel width is to be returned.

Returns:
  Pixel width of the ListHeaderSegment at the zero based column index specified by column.

Exceptions:

  | InvalidRequestException | thrown if column is out of range.

uint CEGUI::ListHeader::getColumnWithText | ( | const String & | text | ) | const

Return the zero based column index of the segment with the specified text.

Parameters:

  | text | String object containing the text to be searched for.

Returns:
  Zero based column index of the segment with the specified text.

Exceptions:

  | InvalidRequestException | thrown if no attached segments have the requested text.

float CEGUI::ListHeader::getPixelOffsetToColumn | ( | uint | column | ) | const

Return the pixel offset to the ListHeaderSegment at the given zero based column index.

Parameters:

  | column | Zero based column index of the ListHeaderSegment whos pixel offset it to be returned.

Returns:
  The number of pixels up-to the begining of the ListHeaderSegment located at zero based column index column.

Exceptions:

  | InvalidRequestException | thrown if column is out of range.

float CEGUI::ListHeader::getPixelOffsetToSegment | ( | const ListHeaderSegment & | segment | ) | const

Return the pixel offset to the given ListHeaderSegment.

Parameters:

  | segment | ListHeaderSegment object that the offset to is to be returned.

Returns:
  The number of pixels up-to the begining of the ListHeaderSegment described by segment.

Exceptions:

  | InvalidRequestException | thrown if segment is not attached to the ListHeader.

ListHeaderSegment & CEGUI::ListHeader::getSegmentFromColumn | ( | uint | column | ) | const

Return the ListHeaderSegment object for the specified column.

Parameters:

  | column | zero based column index of the ListHeaderSegment to be returned.

Returns:
  ListHeaderSegment object at the requested index.

Exceptions:

  | InvalidRequestException | thrown if column is out of range.

ListHeaderSegment & CEGUI::ListHeader::getSegmentFromID | ( | uint | id | ) | const

Return the ListHeaderSegment object with the specified ID.

Parameters:

  | id | id code of the ListHeaderSegment to be returned.

Returns:
  ListHeaderSegment object with the ID id. If more than one segment has the same ID, only the first one will ever be returned.

Exceptions:

  | InvalidRequestException | thrown if no segment with the requested ID is attached.

float CEGUI::ListHeader::getSegmentOffset | ( | void |  | ) | const`[inline]`

Return the current segment offset value. This value is used to implement scrolling of the header segments within the ListHeader area.

Returns:
  float value specifying the current segment offset value in whatever metrics system is active for the ListHeader.

uint CEGUI::ListHeader::getSortColumn | ( | void |  | ) | const

Return the zero based index of the current sort column. There must be at least one segment/column to successfully call this method.

Returns:
  Zero based column index that is the current sort column.

Exceptions:

  | InvalidRequestException | thrown if there are no segments / columns in this ListHeader.

ListHeaderSegment::SortDirection CEGUI::ListHeader::getSortDirection | ( | void |  | ) | const

Return the currently set sort direction.

Returns:
  One of the ListHeaderSegment::SortDirection enumerated values specifying the current sort direction.

ListHeaderSegment & CEGUI::ListHeader::getSortSegment | ( | void |  | ) | const

Return the ListHeaderSegment that is marked as being the 'sort key' segment. There must be at least one segment to successfully call this method.

Returns:
  ListHeaderSegment object which is the sort-key segment.

Exceptions:

  | InvalidRequestException | thrown if no segments are attached to the ListHeader.

float CEGUI::ListHeader::getTotalSegmentsPixelExtent | ( | void |  | ) | const

Return the total pixel width of all attached segments.

Returns:
  Sum of the pixel widths of all attached ListHeaderSegment objects.

void CEGUI::ListHeader::insertColumn | ( | const String & | text,
|  | uint | id,
|  | float | width,
|  | const ListHeaderSegment & | position
| ) |

Insert a new column segment at the specified position.

Parameters:

  | text | String object holding the initial text for the new segment
  | id | Client specified ID code to be assigned to the new segment.
  | width | Initial width of the new segment using the relative metrics system
  | position | ListHeaderSegment object indicating the insert position for the new segment. The new segment will be inserted before the segment indicated by position.

Returns:
  Nothing.

Exceptions:

  | InvalidRequestException | thrown if ListHeaderSegment position is not attached to the ListHeader.

void CEGUI::ListHeader::insertColumn | ( | const String & | text,
|  | uint | id,
|  | float | width,
|  | uint | position
| ) |

Insert a new column segment at the specified position.

Parameters:

  | text | String object holding the initial text for the new segment
  | id | Client specified ID code to be assigned to the new segment.
  | width | Initial width of the new segment using the relative metrics system
  | position | Zero based column index indicating the desired position for the new column. If this is greater than the current number of columns, the new segment is added to the end if the header.

Returns:
  Nothing.

bool CEGUI::ListHeader::isColumnDraggingEnabled | ( | void |  | ) | const

Return whether the user may modify the order of the segments.

Returns:
  true if the user may interactively modify the order of the column segments, false if they may not.

bool CEGUI::ListHeader::isColumnSizingEnabled | ( | void |  | ) | const

Return whether the user may size column segments.

Returns:
  true if the user may interactively modify the width of column segments, false if they may not.

bool CEGUI::ListHeader::isSortingEnabled | ( | void |  | ) | const

Return whether user manipulation of the sort column & direction are enabled.

Returns:
  true if the user may interactively modify the sort column and direction. false if the user may not modify the sort column and direction (these can still be set programmatically).

void CEGUI::ListHeader::moveColumn | ( | uint | column,
|  | const ListHeaderSegment & | position
| ) |

Move a column segment to a new position.

Parameters:

  | column | Zero based column index indicating the column segment to be moved.
  | position | ListHeaderSegment object indicating the new position for the segment. The segment at column will be moved behind segment position (that is, segment column will appear to the right of segment position).

Returns:
  Nothing.

Exceptions:

  | InvalidRequestException | thrown if column is out of range for this ListHeader, or if position is not attached to this ListHeader.

void CEGUI::ListHeader::moveColumn | ( | uint | column,
|  | uint | position
| ) |

Moves a column segment into a new position.

Parameters:

  | column | Zero based column index indicating the column segment to be moved.
  | position | Zero based column index indicating the new position for the segment. If this is greater than the current number of segments, the segment is moved to the end of the header.

Returns:
  Nothing.

Exceptions:

  | InvalidRequestException | thrown if column is out of range for this ListHeader.

void CEGUI::ListHeader::moveSegment | ( | const ListHeaderSegment & | segment,
|  | const ListHeaderSegment & | position
| ) |

Move a segment to a new position.

Parameters:

  | segment | ListHeaderSegment object that is to be moved.
  | position | ListHeaderSegment object indicating the new position for the segment. The segment segment will be moved behind segment position (that is, segment segment will appear to the right of segment position).

Returns:
  Nothing.

Exceptions:

  | InvalidRequestException | thrown if either segment or position are not attached to this ListHeader.

void CEGUI::ListHeader::moveSegment | ( | const ListHeaderSegment & | segment,
|  | uint | position
| ) |

Moves a segment into a new position.

Parameters:

  | segment | ListHeaderSegment object that is to be moved.
  | position | Zero based column index indicating the new position for the segment. If this is greater than the current number of segments, the segment is moved to the end of the header.

Returns:
  Nothing.

Exceptions:

  | InvalidRequestException | thrown if segment is not attached to this ListHeader.

void CEGUI::ListHeader::removeColumn | ( | uint | column | ) |

Removes a column segment from the ListHeader.

Parameters:

  | column | Zero based column index indicating the segment to be removed.

Returns:
  Nothing.

Exceptions:

  | InvalidRequestException | thrown if column is out of range.

void CEGUI::ListHeader::removeSegment | ( | const ListHeaderSegment & | segment | ) |

Remove the specified segment from the ListHeader.

Parameters:

  | segment | ListHeaderSegment object that is to be removed from the ListHeader.

Returns:
  Nothing.

Exceptions:

  | InvalidRequestException | thrown if segment is not attached to this ListHeader.

void CEGUI::ListHeader::setColumnDraggingEnabled | ( | bool | setting | ) |

Set whether columns may be reordered by the user via drag and drop.

Parameters:

  setting

  - true to indicate the user may change the order of the column segments via drag and drop.
  - false to indicate the user may not change the column segment order.

Returns:
  Nothing.

void CEGUI::ListHeader::setColumnPixelWidth | ( | uint | column,
|  | float | width
| ) |

Set the pixel width of the specified column.

Parameters:

  | column | Zero based column index of the segment whos pixel width is to be set.
  | width | float value specifying the new pixel width to set for the ListHeaderSegment at the zero based column index specified by column.

Returns:
  Nothing

Exceptions:

  | InvalidRequestException | thrown if column is out of range.

void CEGUI::ListHeader::setColumnSizingEnabled | ( | bool | setting | ) |

Set whether columns may be sized by the user.

Parameters:

  setting

  - true to indicate that the user may interactively size segments.
  - false to indicate that the user may not interactively size segments.

Returns:
  Nothing.

void CEGUI::ListHeader::setSegmentOffset | ( | float | offset | ) |

Set the current base segment offset. (This implements scrolling of the header segments within the header area).

Parameters:

  | offset | New base offset for the first segment. The segments will of offset to the left by the amount specified. offset should be specified using the active metrics system for the ListHeader.

Returns:
  Nothing.

void CEGUI::ListHeader::setSortColumn | ( | uint | column | ) |

Set the column to be used as the sort column.

Parameters:

  | column | Zero based column index indicating the column to be sorted.

Returns:
  Nothing.

Exceptions:

  | InvalidRequestException | thrown if column is out of range for this ListHeader.

void CEGUI::ListHeader::setSortColumnFromID | ( | uint | id | ) |

Set the column to to be used for sorting via its ID code.

Parameters:

  | id | ID code of the column segment that is to be used as the sort column.

Returns:
  Nothing.

Exceptions:

  | InvalidRequestException | thrown if no segment with ID id is attached to the ListHeader.

void CEGUI::ListHeader::setSortDirection | ( | ListHeaderSegment::SortDirection | direction | ) |

Set the current sort direction.

Parameters:

  | direction | One of the ListHeaderSegment::SortDirection enumerated values indicating the sort direction to be used.

Returns:
  Nothing.

void CEGUI::ListHeader::setSortingEnabled | ( | bool | setting | ) |

Set whether user manipulation of the sort column and direction is enabled.

Parameters:

  setting

  - true to allow interactive user manipulation of the sort column and direction.
  - false to disallow interactive user manipulation of the sort column and direction.

Returns:
  Nothing.

void CEGUI::ListHeader::setSortSegment | ( | const ListHeaderSegment & | segment | ) |

Set the column segment to be used as the sort column.

Parameters:

  | segment | ListHeaderSegment object indicating the column to be sorted.

Returns:
  Nothing.

Exceptions:

  | InvalidRequestException | thrown if segment is not attached to this ListHeader.

virtual bool CEGUI::ListHeader::testClassName_impl | ( | const String & | class_name | ) | const`[inline, protected, virtual]`

Return whether this window was inherited from the given class name at some point in the inheritance heirarchy.

Parameters:

  | class_name | The class name that is to be checked.

Returns:
  true if this window was inherited from class_name. false if not.

Reimplemented from CEGUI::Window.