A simple list box widget. More...

#include <pawslistbox.h>

Public Member Functions
void	AddRow (pawsListBoxRow *row)
void	AutoScrollUpdate (bool v)
void	CalculateDrawPositions ()
void	Clear ()
bool	ConvertFromAutoID (int id, int &row, int &col)
	Convert from an automatic ID to col/row.
void	CreateTitleRow ()
	Creates the title row.
pawsListBoxRow *	GetRow (size_t x)
	Get a particular row.
size_t	GetRowCount ()
	Get number of rows in listboz.
pawsListBoxRow *	GetSelectedRow ()
	Get selected row.
int	GetSelectedRowNum ()
	Returns number of selected row (-1 if none is selected)
const char *	GetSelectedText (size_t columnId)
	Get text from specified column in the selected row.
int	GetSelection ()
	Get the row that is currently selected.
int	GetSortedColumn ()
	Gets and sets the column that the listbox is sorted by.
bool	GetSortOrder ()
pawsTextBox *	GetTextCell (int rowNum, int colNum)
	Returns listbox cell of type pawsTextBox or NULL (when the cell does not exist or it is another type).
csString	GetTextCellValue (int rowNum, int colNum)
	Returns value of cell of type pawsTextBox.
int	GetTotalColumns ()
bool	IsAutoID ()
	Is this an autoID listbox.
bool	IsSelectable ()
void	MoveRow (int rownr, int dest)
void	MoveSelectBar (bool direction)
	Moves the select bar up (direction=true) or down (direction=false).
pawsListBoxRow *	NewRow (size_t position=(size_t)-1)
	Creates a new row ( default at the end ) and returns a pointer to it.
pawsListBoxRow *	NewTextBoxRow (csList< csString > &rowEntry, size_t position=(size_t)-1)
	Creates a new row ( default at the end ) filled by values from rowEntry and returns a pointer to it.
bool	OnKeyDown (utf32_char keyCode, utf32_char keyChar, int modifiers)
	When enter is pressed the highlighted row will be selected and the widget will be notified.
bool	OnMouseDown (int button, int modifiers, int x, int y)
	Manage mouse down event to test for and apply window changes.
virtual bool	OnScroll (int direction, pawsScrollBar *widget)
	Called whenever a window is scrolled.
	pawsListBox (const pawsListBox &origin)
	pawsListBox ()
bool	PostSetup ()
	This is called after the widget and all of it's children have been created.
void	Remove (int id)
	Remove based on widget id. Note this also deletes the row.
void	Remove (pawsListBoxRow *rowToRemove)
	Remove based on row pointer.
pawsListBoxRow *	RemoveSelected ()
	Remove selected row.
void	Resize ()
	Resize a widget based on it's parent's size.
bool	Select (pawsListBoxRow *row, bool notify=true)
	Highlights the selected row.
bool	SelectByIndex (int index, bool notify=true)
	Highlights the selected row (by index)
virtual bool	SelfPopulate (iDocumentNode *node)
	Override the general self populate to handle creation of new rows.
void	SendOnListAction (int status)
	Notifies (parent/notifyTarget) widget that a row has been selected.
void	SetColumnDef (int col, int width, int height, const char *widgetDesc)
	Set how a column should be constructed.
void	SetNotify (pawsWidget *target)
	Sets the widget that will be notified when a row is selected.
void	SetScrollBarMaxValue ()
void	SetSortedColumn (int colNum)
void	SetSortingFunc (int colNum, listBoxSortingFunc sortFunc)
	Sets the function that compares listbox rows when sorting by given column.
void	SetSortOrder (bool ascOrder)
void	SetTextCellValue (int rowNum, int colNum, const csString &value)
	Sets value of cell of type pawsTextBox.
void	SetTotalColumns (int numCols)
	Set how many columns this list box will have.
bool	Setup (iDocumentNode *node)
	Setup this widget.
void	SortRows ()
	Sort rows according to current sort column and sort order.
void	UseTitleRow (bool yes)
virtual	~pawsListBox ()
Protected Member Functions
void	CheckSortingArrow (int colNum, bool ascOrder)
void	CreateSortingArrow (int colNum)
void	DeleteSortingArrow (int colNum)
pawsWidget *	GetColumnTitle (int colNum)
int	GetUnborderedHeight ()
	Gets height of widget after vertical borders are being excluded.
void	SetSortingArrow (int colNum, bool ascOrder)
Static Protected Member Functions
static int	sort_cmp (const void rowA, const void rowB)
	This is static function that is used as argument to qsort() and a few variables that influence how this function works.
Protected Attributes
csString	arrowDown
int	arrowSize
csString	arrowUp
bool	ascOrder
bool	autoID
bool	autoResize
bool	autoUpdateScroll
ColumnDef *	columnDef
int	columnHeight
unsigned int	highlightAlpha
csString	highlightImage
pawsScrollBar *	horzscrollBar
pawsWidget *	notifyTarget
	the widget that will be notified when a row is selected
csArray< pawsListBoxRow * >	rows
int	rowWidth
pawsScrollBar *	scrollBar
int	scrollbarHeightMod
int	scrollbarWidth
bool	selectable
int	selected
int	sortColNum
pawsListBoxRow *	titleRow
int	topRow
int	totalColumns
int	totalRows
bool	useBorder
bool	usingTitleRow
csString	xmlbinding_row
int	xMod
Static Protected Attributes
static const int	BORDER_SIZE = 5
	Defines border size around child widgets.
static bool	sort_ascOrder
static int	sort_sortColNum
static listBoxSortingFunc	sort_sortFunc

Detailed Description

A simple list box widget.

A list box is made up a list of another type of widgets called pawsListBoxRows. Each row is then made up of several widgets that constitue a 'row'. So a row may be a textbox, image, button.

This is how a list box is defined in XML. You define the basic layout of it and how each column in the rows should be constructed. If you use the autoid="yes" every widget in the listbox will have an id=ListBoxID+ row*numberOfColumns+coloum:

<widget name="PetitionList" factory="pawsListBox" xmlbinding="petition_list" id="0" autoid="yes" sortBy="2" sortOrder="asc" > Size of entire list box <frame x="4" y="34" width="592" height="288" border="yes"/>

Each row in the list box will be 32 high <columns height="32" xmlbinding="p">

define a column that is 140 wide. The first column of any row will be a textbox widget as defined by the <widget></widget> class <column width="140" xmlbinding="GM"> <widget name="GM" factory="pawsTextBox"></widget> </column>

define other columns: <column width="150" xmlbinding="stat"> <widget name="Status" factory="pawsWidget"> <bgimage resource="Funny" /> </widget> </column>

Definition at line 202 of file pawslistbox.h.

Constructor & Destructor Documentation

pawsListBox::pawsListBox ( )

pawsListBox::pawsListBox ( const pawsListBox & origin )

virtual pawsListBox::~pawsListBox ( ) [virtual]

Member Function Documentation

void pawsListBox::AddRow ( pawsListBoxRow * row )

void pawsListBox::AutoScrollUpdate ( bool v ) [inline]

Definition at line 383 of file pawslistbox.h.

void pawsListBox::CalculateDrawPositions ( )

void pawsListBox::CheckSortingArrow	(	int	colNum,
		bool	ascOrder
	)		`[protected]`

void pawsListBox::Clear ( )

bool pawsListBox::ConvertFromAutoID	(	int	id,
		int &	row,
		int &	col
	)

Convert from an automatic ID to col/row.

void pawsListBox::CreateSortingArrow ( int colNum ) [protected]

void pawsListBox::CreateTitleRow ( )

Creates the title row.

void pawsListBox::DeleteSortingArrow ( int colNum ) [protected]

pawsWidget* pawsListBox::GetColumnTitle ( int colNum ) [protected]

pawsListBoxRow* pawsListBox::GetRow ( size_t x )

Get a particular row.

size_t pawsListBox::GetRowCount ( )

Get number of rows in listboz.

pawsListBoxRow* pawsListBox::GetSelectedRow ( )

Get selected row.

int pawsListBox::GetSelectedRowNum ( )

Returns number of selected row (-1 if none is selected)

const char* pawsListBox::GetSelectedText ( size_t columnId )

Get text from specified column in the selected row.

int pawsListBox::GetSelection ( ) [inline]

Get the row that is currently selected.

Returns:: A pointer to the selected row or NULL.

Definition at line 216 of file pawslistbox.h.

int pawsListBox::GetSortedColumn ( )

Gets and sets the column that the listbox is sorted by.

Number -1 means no sorting, in both cases.

bool pawsListBox::GetSortOrder ( )

pawsTextBox* pawsListBox::GetTextCell	(	int	rowNum,
		int	colNum
	)

Returns listbox cell of type pawsTextBox or NULL (when the cell does not exist or it is another type).

csString pawsListBox::GetTextCellValue	(	int	rowNum,
		int	colNum
	)

Returns value of cell of type pawsTextBox.

int pawsListBox::GetTotalColumns ( ) [inline]

Definition at line 270 of file pawslistbox.h.

int pawsListBox::GetUnborderedHeight ( ) [protected]

Gets height of widget after vertical borders are being excluded.

Returns:: Height of widget after subtracting vertical borders height

bool pawsListBox::IsAutoID ( ) [inline]

Is this an autoID listbox.

Definition at line 310 of file pawslistbox.h.

bool pawsListBox::IsSelectable ( ) [inline]

Definition at line 302 of file pawslistbox.h.

void pawsListBox::MoveRow	(	int	rownr,
		int	dest
	)

void pawsListBox::MoveSelectBar ( bool direction )

Moves the select bar up (direction=true) or down (direction=false).

pawsListBoxRow* pawsListBox::NewRow ( size_t position = (size_t)-1 )

Creates a new row ( default at the end ) and returns a pointer to it.

pawsListBoxRow* pawsListBox::NewTextBoxRow	(	csList< csString > &	rowEntry,
		size_t	position = `(size_t)-1`
	)

Creates a new row ( default at the end ) filled by values from rowEntry and returns a pointer to it.

bool pawsListBox::OnKeyDown	(	utf32_char	keyCode,
		utf32_char	keyChar,
		int	modifiers
	)		`[virtual]`

When enter is pressed the highlighted row will be selected and the widget will be notified.

Reimplemented from pawsWidget.

bool pawsListBox::OnMouseDown	(	int	button,
		int	modifiers,
		int	x,
		int	y
	)		`[virtual]`

Manage mouse down event to test for and apply window changes.

Parameters:

button	Type of button: 1 resizable or movable, 2 context menu or config window.
modifiers	Used with PAWS_CONSTRUCTION.
x	Used to test for resize.
y	Used to test for resize.

Returns:: bool TRUE if movable or resizable.

Remarks:: calls OnMouseDown on it's parent.

Reimplemented from pawsWidget.

virtual bool pawsListBox::OnScroll	(	int	scrollDirection,
		pawsScrollBar *	widget
	)		`[virtual]`

Called whenever a window is scrolled.

Parameters:

scrollDirection	The direction to move.
widget	The scrollbar widget being manipulated.

Returns:: bool Parent's result or FALSE if no parent.

Reimplemented from pawsWidget.

bool pawsListBox::PostSetup ( ) [virtual]

This is called after the widget and all of it's children have been created.

Remarks:: This can be useful for widgets that want to get pointers to some of it's children for quick access.

Reimplemented from pawsWidget.

void pawsListBox::Remove ( int id )

Remove based on widget id. Note this also deletes the row.

void pawsListBox::Remove ( pawsListBoxRow * rowToRemove )

Remove based on row pointer.

pawsListBoxRow* pawsListBox::RemoveSelected ( )

Remove selected row.

void pawsListBox::Resize ( ) [virtual]

Resize a widget based on it's parent's size.

Reimplemented from pawsWidget.

bool pawsListBox::Select	(	pawsListBoxRow *	row,
		bool	notify = `true`
	)

Highlights the selected row.

bool pawsListBox::SelectByIndex	(	int	index,
		bool	notify = `true`
	)

Highlights the selected row (by index)

virtual bool pawsListBox::SelfPopulate ( iDocumentNode * node ) [virtual]

Override the general self populate to handle creation of new rows.

Reimplemented from pawsWidget.

void pawsListBox::SendOnListAction ( int status )

Notifies (parent/notifyTarget) widget that a row has been selected.

void pawsListBox::SetColumnDef	(	int	col,
		int	width,
		int	height,
		const char *	widgetDesc
	)

Set how a column should be constructed.

This is usuall used for code constructed list boxes.

Parameters:

col	The column number
width	The width of that column.
height	The height of what rows should be.
widgetDesc	This is an XML description of the widget. Much the same as you would find in the .xml files.

void pawsListBox::SetNotify ( pawsWidget * target ) [inline]

Sets the widget that will be notified when a row is selected.

When nothing is set the OnListAction messages will be sent to the parent widget

Definition at line 340 of file pawslistbox.h.

void pawsListBox::SetScrollBarMaxValue ( )

void pawsListBox::SetSortedColumn ( int colNum )

void pawsListBox::SetSortingArrow	(	int	colNum,
		bool	ascOrder
	)		`[protected]`

void pawsListBox::SetSortingFunc	(	int	colNum,
		listBoxSortingFunc	sortFunc
	)

Sets the function that compares listbox rows when sorting by given column.

This makes the column sortable.

void pawsListBox::SetSortOrder ( bool ascOrder )

void pawsListBox::SetTextCellValue	(	int	rowNum,
		int	colNum,
		const csString &	value
	)

Sets value of cell of type pawsTextBox.

void pawsListBox::SetTotalColumns ( int numCols )

Set how many columns this list box will have.

This is usually for code constructed list boxes and creates a new set of column definitions.

bool pawsListBox::Setup ( iDocumentNode * ) [virtual]

Setup this widget.

Reimplemented from pawsWidget.

static int pawsListBox::sort_cmp	(	const void *	rowA,
		const void *	rowB
	)		`[static, protected]`

This is static function that is used as argument to qsort() and a few variables that influence how this function works.

void pawsListBox::SortRows ( )

Sort rows according to current sort column and sort order.

You can use this after you added new rows to listbox;

void pawsListBox::UseTitleRow ( bool yes )

Member Data Documentation

csString pawsListBox::arrowDown [protected]

Definition at line 461 of file pawslistbox.h.

int pawsListBox::arrowSize [protected]

Definition at line 455 of file pawslistbox.h.

csString pawsListBox::arrowUp [protected]

Definition at line 460 of file pawslistbox.h.

bool pawsListBox::ascOrder [protected]

Definition at line 441 of file pawslistbox.h.

bool pawsListBox::autoID [protected]

Definition at line 427 of file pawslistbox.h.

bool pawsListBox::autoResize [protected]

Definition at line 428 of file pawslistbox.h.

bool pawsListBox::autoUpdateScroll [protected]

Definition at line 429 of file pawslistbox.h.

const int pawsListBox::BORDER_SIZE = 5 [static, protected]

Defines border size around child widgets.

If borders are used by this widget, it offsets position of each child widget and total space designed for child widgets is also increased (by twice size of border)

Definition at line 399 of file pawslistbox.h.

ColumnDef* pawsListBox::columnDef [protected]

Definition at line 431 of file pawslistbox.h.

int pawsListBox::columnHeight [protected]

Definition at line 422 of file pawslistbox.h.

unsigned int pawsListBox::highlightAlpha [protected]

Definition at line 453 of file pawslistbox.h.

csString pawsListBox::highlightImage [protected]

Definition at line 452 of file pawslistbox.h.

pawsScrollBar* pawsListBox::horzscrollBar [protected]

Definition at line 418 of file pawslistbox.h.

pawsWidget* pawsListBox::notifyTarget [protected]