GG
Classes | Static Public Attributes | Friends | List of all members
GG::ListBox Class Reference

#include <ListBox.h>

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

Classes

struct  DefaultRowCmp
 
struct  Row
 
struct  RowPtrIteratorLess
 

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 SetFirstRowShown (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 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)
 

Additional Inherited Members

- Public Types inherited from GG::Wnd
enum  ChildClippingMode {
  DontClip,
  ClipToClient,
  ClipToWindow,
  ClipToClientAndWindowSeparately
}
 
typedef std::map< const Wnd
*, bool >::iterator 
DropsAcceptableIter
 
- Public Member Functions inherited from GG::Control
Clr Color () const
 
bool Disabled () const
 
- Public Member Functions inherited from GG::Wnd
virtual ~Wnd ()
 
bool Interactive () const
 
bool RepeatButtonDown () const
 
bool Dragable () const
 
bool Resizable () const
 
bool OnTop () const
 
bool Modal () const
 
ChildClippingMode GetChildClippingMode () const
 
bool NonClientChild () const
 
bool Visible () const
 
const std::string & Name () const
 
const std::string & DragDropDataType () const
 
Pt UpperLeft () const
 
Pt LowerRight () const
 
Pt RelativeUpperLeft () const
 
Pt RelativeLowerRight () const
 
X Width () const
 
Y Height () const
 
int ZOrder () const
 
Pt Size () const
 
Pt MinSize () const
 
Pt MaxSize () const
 
Pt ClientSize () const
 
X ClientWidth () const
 
Y ClientHeight () const
 
Pt ScreenToWindow (const Pt &pt) const
 
Pt ScreenToClient (const Pt &pt) const
 
virtual bool InWindow (const Pt &pt) const
 
virtual bool InClient (const Pt &pt) const
 
const std::list< Wnd * > & Children () const
 
WndParent () const
 
WndRootParent () const
 
LayoutGetLayout () const
 
LayoutContainingLayout () const
 
const std::vector
< BrowseInfoMode > & 
BrowseModes () const
 
const std::string & BrowseInfoText (std::size_t mode) const
 
const boost::shared_ptr
< StyleFactory > & 
GetStyleFactory () const
 
virtual WndRegion WindowRegion (const Pt &pt) const
 
void SetDragDropDataType (const std::string &data_type)
 
virtual void CancellingChildDragDrop (const std::vector< const Wnd * > &wnds)
 
void SetName (const std::string &name)
 
void Hide (bool children=true)
 
void Show (bool children=true)
 
virtual void ModalInit ()
 
void SetChildClippingMode (ChildClippingMode mode)
 
void NonClientChild (bool b)
 
void MoveTo (const Pt &pt)
 
void OffsetMove (const Pt &pt)
 
void Resize (const Pt &sz)
 
void SetMinSize (const Pt &sz)
 
void SetMaxSize (const Pt &sz)
 
void AttachChild (Wnd *wnd)
 
void MoveChildUp (Wnd *wnd)
 
void MoveChildDown (Wnd *wnd)
 
void DetachChild (Wnd *wnd)
 
void DetachChildren ()
 
void DeleteChild (Wnd *wnd)
 
void DeleteChildren ()
 
void InstallEventFilter (Wnd *wnd)
 
void RemoveEventFilter (Wnd *wnd)
 
void HorizontalLayout ()
 
void VerticalLayout ()
 
void GridLayout ()
 
void SetLayout (Layout *layout)
 
void RemoveLayout ()
 
LayoutDetachLayout ()
 
void SetLayoutBorderMargin (unsigned int margin)
 
void SetLayoutCellMargin (unsigned int margin)
 
virtual bool Run ()
 
void EndRun ()
 
void SetBrowseModeTime (unsigned int time, std::size_t mode=0)
 
void SetBrowseInfoWnd (const boost::shared_ptr< BrowseInfoWnd > &wnd, std::size_t mode=0)
 
void ClearBrowseInfoWnd (std::size_t mode=0)
 
void SetBrowseText (const std::string &text, std::size_t mode=0)
 
void SetBrowseModes (const std::vector< BrowseInfoMode > &modes)
 
void SetStyleFactory (const boost::shared_ptr< StyleFactory > &factory)
 
 GG_ABSTRACT_EXCEPTION (Exception)
 
 GG_CONCRETE_EXCEPTION (BadLayout, GG::Wnd, Exception)
 
- Static Public Member Functions inherited from GG::Wnd
static unsigned int DefaultBrowseTime ()
 
static void SetDefaultBrowseTime (unsigned int time)
 
static const boost::shared_ptr
< BrowseInfoWnd > & 
DefaultBrowseInfoWnd ()
 
static void SetDefaultBrowseInfoWnd (const boost::shared_ptr< BrowseInfoWnd > &browse_info_wnd)
 
- Protected Types inherited from GG::Wnd
enum  DragDropRenderingState {
  NOT_DRAGGED,
  IN_PLACE_COPY,
  DRAGGED_OVER_UNACCEPTING_DROP_TARGET,
  DRAGGED_OVER_ACCEPTING_DROP_TARGET
}
 
- Protected Member Functions inherited from GG::Control
virtual void KeyRelease (Key key, boost::uint32_t key_code_point, Flags< ModKey > mod_keys)
 
 Control ()
 
 Control (X x, Y y, X w, Y h, Flags< WndFlag > flags=INTERACTIVE)
 
- Protected Attributes inherited from GG::Control
Clr m_color
 
bool m_disabled
 

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 100 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.

GG::ListBox::GG_ABSTRACT_EXCEPTION ( Exception  )

The base class for ListBox exceptions.

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 
)
protectedvirtual

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 
)
protectedvirtual

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 
)
protectedvirtual

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 
)
protectedvirtual

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 ( )
protectedvirtual

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 
)
protectedvirtual

Respond to Timer timer firing at time ticks.

Reimplemented from GG::Wnd.

virtual bool GG::ListBox::EventFilter ( Wnd w,
const WndEvent event 
)
protectedvirtual

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

ClearedSignalType GG::ListBox::ClearedSignal
mutable

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 322 of file ListBox.h.

InsertedSignalType GG::ListBox::InsertedSignal
mutable

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 328 of file ListBox.h.


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