GG
Classes | Static Public Attributes | Friends

GG::ListBox Class Reference

A flexible control that can contain rows and columns of other controls, even other ListBoxes. More...

#include <ListBox.h>

Inheritance diagram for GG::ListBox:
GG::Control GG::Wnd

List of all members.

Classes

struct  DefaultRowCmp
 Sorts two Rows of a ListBox using operator<() on the Row::SortKeyType provided by the rows' SortKey() methods. More...
struct  Row
 A single item in a listbox. More...
struct  RowPtrIteratorLess
 Sorts iterators to ListBox::Row*s from a container of ListBox::Row*s. More...

Static Public Attributes

static const unsigned int BORDER_THICK

Friends

class DropDownList

Signal Types

typedef boost::signal< void()> ClearedSignalType
typedef boost::signal< void(const
SelectionSet &)> 
SelChangedSignalType
typedef boost::signal< void(iterator)> RowSignalType
typedef boost::signal< void(const_iterator)> ConstRowSignalType
typedef boost::signal< void(iterator,
const Pt &)> 
RowClickSignalType
typedef RowSignalType InsertedSignalType
typedef RowSignalType DroppedSignalType
typedef ConstRowSignalType DropAcceptableSignalType
typedef RowClickSignalType LeftClickedSignalType
typedef RowClickSignalType RightClickedSignalType
typedef RowSignalType DoubleClickedSignalType
typedef RowSignalType ErasedSignalType
typedef RowSignalType BrowsedSignalType

Structors

 ListBox (X x, Y y, X w, Y h, Clr color, Clr interior=CLR_ZERO, Flags< WndFlag > flags=INTERACTIVE)
virtual ~ListBox ()
 ListBox ()

Accessors

ClearedSignalType ClearedSignal
InsertedSignalType InsertedSignal
SelChangedSignalType SelChangedSignal
DroppedSignalType DroppedSignal
DropAcceptableSignalType DropAcceptableSignal
LeftClickedSignalType LeftClickedSignal
RightClickedSignalType RightClickedSignal
DoubleClickedSignalType DoubleClickedSignal
ErasedSignalType ErasedSignal
BrowsedSignalType BrowsedSignal
virtual void DropsAcceptable (DropsAcceptableIter first, DropsAcceptableIter last, const Pt &pt) const
virtual Pt MinUsableSize () const
virtual Pt ClientUpperLeft () const
virtual Pt ClientLowerRight () const
bool Empty () const
const_iterator begin () const
const_iterator end () const
const_reverse_iterator rbegin () const
const_reverse_iterator rend () const
const RowGetRow (std::size_t n) const
iterator Caret () const
const SelectionSet & Selections () const
bool Selected (iterator it) const
Clr InteriorColor () const
Clr HiliteColor () const
Flags< ListBoxStyle > Style () const
const RowColHeaders () const
iterator FirstRowShown () const
std::size_t FirstColShown () const
iterator LastVisibleRow () const
std::size_t LastVisibleCol () const
std::size_t NumRows () const
std::size_t NumCols () const
bool KeepColWidths () const
std::size_t SortCol () const
X ColWidth (std::size_t n) const
Alignment ColAlignment (std::size_t n) const
Alignment RowAlignment (iterator it) const
const std::set< std::string > & AllowedDropTypes () const
bool AutoScrollDuringDragDrops () const
unsigned int AutoScrollMargin () const
unsigned int AutoScrollInterval () const
X RightMargin () const
Y BottomMargin () const
unsigned int CellMargin () const
iterator RowUnderPt (const Pt &pt) const
iterator OldSelRow () const
iterator OldRDownRow () const
iterator LClickRow () const
iterator RClickRow () const
bool AutoScrollingUp () const
bool AutoScrollingDown () const
bool AutoScrollingLeft () const
bool AutoScrollingRight () const

Mutators

virtual void StartingChildDragDrop (const Wnd *wnd, const GG::Pt &offset)
virtual void AcceptDrops (const std::vector< Wnd * > &wnds, const Pt &pt)
virtual void ChildrenDraggedAway (const std::vector< Wnd * > &wnds, const Wnd *destination)
virtual void Render ()
virtual void SizeMove (const Pt &ul, const Pt &lr)
virtual void Disable (bool b=true)
virtual void SetColor (Clr c)
iterator Insert (Row *row, iterator it)
iterator Insert (Row *row)
RowErase (iterator it)
void Clear ()
void SelectRow (iterator it)
void DeselectRow (iterator it)
void SelectAll ()
void DeselectAll ()
iterator begin ()
iterator end ()
reverse_iterator rbegin ()
reverse_iterator rend ()
RowGetRow (std::size_t n)
void SetSelections (const SelectionSet &s)
void SetCaret (iterator it)
void BringRowIntoView (iterator it)
void SetInteriorColor (Clr c)
void SetHiliteColor (Clr c)
void SetStyle (Flags< ListBoxStyle > s)
void SetColHeaders (Row *r)
void RemoveColHeaders ()
void SetColWidth (std::size_t n, X w)
void SetNumCols (std::size_t n)
void SetSortCol (std::size_t n)
void SetSortCmp (const boost::function< bool(const Row &, const Row &, std::size_t)> &sort_cmp)
void LockColWidths ()
void UnLockColWidths ()
void SetColAlignment (std::size_t n, Alignment align)
void SetRowAlignment (iterator it, Alignment align)
void AllowDropType (const std::string &str)
void DisallowDropType (const std::string &str)
void AutoScrollDuringDragDrops (bool auto_scroll)
void SetAutoScrollMargin (unsigned int margin)
void SetAutoScrollInterval (unsigned int interval)
virtual void DefineAttributes (WndEditor *editor)
virtual void KeyPress (Key key, boost::uint32_t key_code_point, Flags< ModKey > mod_keys)
virtual void MouseWheel (const Pt &pt, int move, Flags< ModKey > mod_keys)
virtual void DragDropEnter (const Pt &pt, const std::map< Wnd *, Pt > &drag_drop_wnds, Flags< ModKey > mod_keys)
virtual void DragDropHere (const Pt &pt, const std::map< Wnd *, Pt > &drag_drop_wnds, Flags< ModKey > mod_keys)
virtual void DragDropLeave ()
virtual void TimerFiring (unsigned int ticks, Timer *timer)
virtual bool EventFilter (Wnd *w, const WndEvent &event)
iterator Insert (Row *row, iterator it, bool dropped)
RowErase (iterator it, bool removing_duplicate, bool signal)
void BringCaretIntoView ()
void RecreateScrolls ()
void ResetAutoScrollVars ()
void Resort ()

Exceptions

 GG_ABSTRACT_EXCEPTION (Exception)
 GG_CONCRETE_EXCEPTION (DontAcceptDrop, GG::ListBox, Exception)

Detailed Description

A flexible control that can contain rows and columns of other controls, even other ListBoxes.

A ListBox consists of rows of controls, usually text or graphics. Each row represents one item; rows can be added or removed, but not columns or individual controls (though the individual controls can be removed from a row by accessing it directly). Each Row in a ListBox must have the same number of cells and the same cell widths as all the others. If you add a row that has fewer cells than the ListBox you are adding it to, it will be padded with empty cells; likewise, if it has too many cells to fit into the Listbox, it will have cells removed. ListBoxes are designed to be easy to use in common cases, and useful in uncommon cases with only a little work. Adding a row to an empty ListBox will cause the ListBox to take on the number of columns that the row has cells, and each column will have an equal portion of the ListBox's width (any remainder is placed in the last column). This allows you to just add rows to a ListBox without worrying about setting up the ListBox in any way ahead of time. Use LockColWidths() to prevent empty ListBoxes from taking on a new row's number of columns. To create a ListBox with user-defined widths, use the ctor designed for that, or call SetNumCols(), set individual widths with SetColWidth(), and lock the column widths with LockColWidths().


Note that Rows are stored by pointer. If you want to move a Row from one ListBox to another, use GetRow() and Insert().


Note that drag-and-drop support is a key part of ListBox's functionality. As such, special effort has been made to make its use as natural and flexible as possible. This includes allowing arbitrary reordering of ListBox rows when the LIST_NOSORT is in effect, and includes the use of the DontAcceptDrop exception. The DontAcceptDrop exception can be thrown by any client of the ListBox in response to its DropAcceptableSignal. Such a throw will cause the drop to be refused. Note that a DropAcceptableSignal is emitted for each row dropped into the ListBox, so individual rows may be accepted or rejected from a single multi-row drop.

Definition at line 102 of file ListBox.h.


Constructor & Destructor Documentation

GG::ListBox::ListBox ( X  x,
Y  y,
X  w,
Y  h,
Clr  color,
Clr  interior = CLR_ZERO,
Flags< WndFlag >  flags = INTERACTIVE 
)

basic ctor


Member Function Documentation

virtual void GG::ListBox::DropsAcceptable ( DropsAcceptableIter  first,
DropsAcceptableIter  last,
const Pt pt 
) const [virtual]

Sets the second member of each iterator to true or false, indicating whether the Wnd in the first member would be accepted if dropped on this Wnd at pt.

Reimplemented from GG::Control.

virtual Pt GG::ListBox::MinUsableSize ( ) const [virtual]

Returns the size of the minimum bounding box that can enclose the Wnd and still show all of its elements, plus enough room for interaction with those elements (if applicable). For example, a TextControl's MinUsableSize() is just the area of its text, and a Scroll's MinUsableSize() is the combined sizes of its up-button, down-button, and tab (plus a bit of room in which to drag the tab).

Reimplemented from GG::Wnd.

virtual Pt GG::ListBox::ClientUpperLeft ( ) const [virtual]

Returns upper-left corner of window's client area in screen coordinates (or of the entire area, if no client area is specified). Virtual because different windows have different shapes (and so ways of calculating client area).

Reimplemented from GG::Wnd.

virtual Pt GG::ListBox::ClientLowerRight ( ) const [virtual]

Returns (one pixel past) lower-right corner of window's client area in screen coordinates (or of the entire area, if no client area is specified). Virtual because different windows have different shapes (and so ways of calculating client area).

Reimplemented from GG::Wnd.

const Row& GG::ListBox::GetRow ( std::size_t  n) const

returns a const reference to the row at index n; not range-checked.

Note:
This function is O(n).
Flags<ListBoxStyle> GG::ListBox::Style ( ) const

Returns the style flags of the listbox

See also:
GG::ListBoxStyle
bool GG::ListBox::KeepColWidths ( ) const

Returns true iff column widths are fixed

See also:
LockColWidths()
std::size_t GG::ListBox::SortCol ( ) const

Returns the index of the column used to sort rows, when sorting is enabled.

Note:
The sort column is not range checked when it is set by the user; it may be < 0 or >= NumCols().
const std::set<std::string>& GG::ListBox::AllowedDropTypes ( ) const

Returns the set of data types allowed to be dropped over this ListBox when drag-and-drop is enabled.

Note:
If this set contains "", all drop types are allowed.
bool GG::ListBox::AutoScrollDuringDragDrops ( ) const

Whether the list should autoscroll when the user is attempting to drop an item into a location that is not currently visible.

unsigned int GG::ListBox::AutoScrollMargin ( ) const

The thickness of the area around the border of the client area that will provoke an auto-scroll, if AutoScrollDuringDragDrops() returns true.

unsigned int GG::ListBox::AutoScrollInterval ( ) const

The number of milliseconds that elapse between row/column scrolls when auto-scrolling.

virtual void GG::ListBox::StartingChildDragDrop ( const Wnd wnd,
const GG::Pt offset 
) [virtual]

Indicates to the Wnd that a child Wnd wnd is being dragged in a drag-and-drop operation, which gives it the opportunity to add other associated drag-and-drop Wnds (see GUI::RegisterDragDropWnd()). offset indicates the position of the mouse relative to wnd's UpperLeft().

Reimplemented from GG::Wnd.

virtual void GG::ListBox::AcceptDrops ( const std::vector< Wnd * > &  wnds,
const Pt pt 
) [virtual]

When the user drops Wnds onto this Wnd, DropsAcceptable() is passed the list of dropped Wnds. The Wnds marked acceptable by DropsAcceptable() are then passed to AcceptDrops(), which handles the receipt of one or more drag-and-drop wnds into this Wnd.

Reimplemented from GG::Control.

virtual void GG::ListBox::ChildrenDraggedAway ( const std::vector< Wnd * > &  wnds,
const Wnd destination 
) [virtual]

Handles the removal of one or more child windows that have been dropped onto another window which has accepted them as drops via DropsAcceptable(). The accepting window retains ownership, so this function must not delete the children.

Note:
CancellingChildDragDrop() and ChildrenDraggedAway() are always called in that order, and are always called at the end of any drag-and-drop sequence performed on a child of this Wnd, whether the drag-and-drop is successful or not.

Reimplemented from GG::Wnd.

virtual void GG::ListBox::Render ( ) [virtual]

Draws this Wnd. Note that Wnds being dragged for a drag-and-drop operation are rendered twice -- once in-place as normal, once in the location of the drag operation, attached to the cursor. Such Wnds may wish to render themselves differently in those two cases. To determine which render is being performed, they can call GUI::GetGUI()->RenderingDragDropWnds().

Implements GG::Control.

iterator GG::ListBox::Insert ( Row row,
iterator  it 
)

Insertion sorts row into the ListBox if sorted, or inserts into an unsorted ListBox before it; returns insertion point. This Row becomes the property of the ListBox.

iterator GG::ListBox::Insert ( Row row)

Insertion sorts row into the ListBox if sorted, or inserts into an unsorted ListBox at the end of the list; returns insertion point. This Row becomes the property of the ListBox.

Row& GG::ListBox::GetRow ( std::size_t  n)

returns a reference to the Row at row index n; not range-checked.

Note:
This function is O(n).
void GG::ListBox::SetStyle ( Flags< ListBoxStyle >  s)

sets the style flags for the ListBox to s.

See also:
GG::ListBoxStyle
void GG::ListBox::SetSortCmp ( const boost::function< bool(const Row &, const Row &, std::size_t)> &  sort_cmp)

Sets the comparison function used to sort a given pair of Rows during row sorting. Note that sort_cmp is assumed to produce an ascending order when used to sort; setting the LIST_SORTDESCENDING style can be used to produce a reverse sort.

void GG::ListBox::LockColWidths ( )

Fixes the column widths; by default, an empty ListBox will take on the number of columns of its first added row.

Note:
The number of columns and their widths may still be set via SetNumCols() and SetColWidth() after this function has been called.
void GG::ListBox::UnLockColWidths ( )

Allows the number of columns to be determined by the first row added to an empty ListBox

void GG::ListBox::SetColAlignment ( std::size_t  n,
Alignment  align 
)

Sets the alignment of column n to align; not range-checked

void GG::ListBox::SetRowAlignment ( iterator  it,
Alignment  align 
)

Sets the alignment of row it to align; not range-checked

void GG::ListBox::AllowDropType ( const std::string &  str)

Allows Rows with data type str to be dropped over this ListBox when drag-and-drop is enabled.

Note:
Passing "" enables all drop types.
void GG::ListBox::DisallowDropType ( const std::string &  str)

Disallows Rows with data type str to be dropped over this ListBox when drag-and-drop is enabled.

Note:
If "" is still an allowed drop type, drops of type str will still be allowed, even after disallowed with a call to this function.
void GG::ListBox::AutoScrollDuringDragDrops ( bool  auto_scroll)

Set this to determine whether the list should autoscroll when the user is attempting to drop an item into a location that is not currently visible.

void GG::ListBox::SetAutoScrollMargin ( unsigned int  margin)

Sets the thickness of the area around the border of the client area that will provoke an auto-scroll, if AutoScrollDuringDragDrops() returns true.

void GG::ListBox::SetAutoScrollInterval ( unsigned int  interval)

Sets the number of milliseconds that elapse between row/column scrolls when auto-scrolling.

virtual void GG::ListBox::DefineAttributes ( WndEditor *  editor) [virtual]

Provides the attributes of this object that are appropriate for a user to edit in a WndEditor; see WndEditor for details.

Reimplemented from GG::Control.

GG::ListBox::GG_ABSTRACT_EXCEPTION ( Exception  )

The base class for ListBox exceptions.

Reimplemented from GG::Wnd.

GG::ListBox::GG_CONCRETE_EXCEPTION ( DontAcceptDrop  ,
GG::ListBox  ,
Exception   
)

Thrown by a ListBox that does not wish to accept a potential drop, for whatever reason. This may be throw by anyone -- even in client code activated by a DropAcceptableSignal.

virtual void GG::ListBox::KeyPress ( Key  key,
boost::uint32_t  key_code_point,
Flags< ModKey >  mod_keys 
) [protected, virtual]

Respond to down-keystrokes (focus window only). A window may receive KeyPress() messages passed up to it from its children. For instance, Control-derived classes pass KeyPress() messages to their Parent() windows by default.

Note:
Though mouse clicks consist of a press and a release, all Control classes by default respond immediately to KeyPress(), not KeyRelease(); in fact, by default no Wnd class does anything at all on a KeyRelease event.
key_code_point will be zero if Unicode support is unavailable.

Reimplemented from GG::Control.

virtual void GG::ListBox::MouseWheel ( const Pt pt,
int  move,
Flags< ModKey >  mod_keys 
) [protected, virtual]

Respond to movement of the mouse wheel (move > 0 indicates the wheel is rolled up, < 0 indicates down)

Reimplemented from GG::Control.

virtual void GG::ListBox::DragDropEnter ( const Pt pt,
const std::map< Wnd *, Pt > &  drag_drop_wnds,
Flags< ModKey >  mod_keys 
) [protected, virtual]

Respond to the cursor entering the Wnd's coords while dragging drag-and-drop Wnds. The Pts in drag_drop_wnds are the Wnds' offsets from pt.

Reimplemented from GG::Wnd.

virtual void GG::ListBox::DragDropHere ( const Pt pt,
const std::map< Wnd *, Pt > &  drag_drop_wnds,
Flags< ModKey >  mod_keys 
) [protected, virtual]

Respond to cursor moving about within the Wnd, or to cursor lingering within the Wnd for a long period of time, while dragging drag-and-drop Wnds. A DragDropHere() message will not be generated the first time the cursor enters the window's area. In that case, a DragDropEnter() message is generated The Pts in drag_drop_wnds are the Wnds' offsets from pt.

Reimplemented from GG::Wnd.

virtual void GG::ListBox::DragDropLeave ( ) [protected, virtual]

Respond to cursor leaving the Wnd's bounds while dragging drag-and-drop Wnds.

Reimplemented from GG::Wnd.

virtual void GG::ListBox::TimerFiring ( unsigned int  ticks,
Timer timer 
) [protected, virtual]

Respond to Timer timer firing at time ticks.

Reimplemented from GG::Wnd.

virtual bool GG::ListBox::EventFilter ( Wnd w,
const WndEvent event 
) [protected, virtual]

Handles an WndEvent destined for Wnd w, but which this Wnd is allowed to handle first. Returns true if this filter processed the message.

Reimplemented from GG::Wnd.


Member Data Documentation

The cleared signal object for this ListBox. Note that this signal is never emitted by the ListBox. It is provided here for convenience, to provide users of a ListBox with a canonical signal with which to communicate about ListBox clears.

Definition at line 328 of file ListBox.h.

The inserted signal object for this ListBox. Note that this signal is never emitted by the ListBox. It is provided here for convenience, to provide users of a ListBox with a canonical signal with which to communicate about ListBox insertions.

Definition at line 334 of file ListBox.h.


The documentation for this class was generated from the following file: