GuiModernTextListCtrl

Custom text list GUI control for the Torque 3D game engine that looks similar to the Microsoft ListView control in Report mode as seen in Visual Studio for C++, C#, and VB. The GuiModernTextListCtrl is designed based off of the ShellFancyTextList control seen in Tribes 2 for both the control behavior and torquescript side features.

Current source code with example scripts:

• v1.01 GuiModernTextListCtrl101.zip (404KByte zip)
• See Changelog for details.

Older releases:

• v1.00 GuiModernTextListCtrl100.zip (393KByte zip)

Binary test release is available for v1.00 (8.5MByte zip).

The current project status, known bugs, and chanegelog of this control can be found at the GuiModernTextListCtrl Status page.

• Column headers:
  • Text horizontal alignments: Left, Right, and Center.
  • Attributes: Can be hidden or shown, and be in an active or disabled state.
  • Skinnable and separately themed by the dedicated profile set to be the Header Profile.
  • Each column can be sorted separately via sort order methods setSortOrder(), setColumnSortOrder(), etc..
  • Each column can be moved to a different position via moveColumn() method or by user dragging and dropping the column.
  • Resizable via setColumnSize() method or live by user mouse cursor.
  • Callback OnColumnSelect() upon user clicking of a column header.

• Rows:
  • Markup language: Row contents can be modified for text foreground color and/or insertion of bitmaps via <color> and <bitmap> tags.
  • Skinnable and themed by the profile set to be the Control Profile.
  • Are tab delimited into columns. Therefore, the entire row content for all columns is a single string.

• Column headers:
  • Cannot be removed/deleted but instead requires the scripter to use clearAllColumns() method and then addColumn() only the columns they want. This is due to the way the columns internally keep track of the tab delimited row contents whenever they're hidden or moved to prevent further upkeep of the scripter during such events. The only workaround is to simply install all columns the scripter wants to ever have available and then hide the columns that aren't necessary at the time.
  • Text vertical alignment is fixed to center.
  • Text cannot be multi-lined, single line only.
  • Fixed to a single font size and style for all column headers as set in the Header Profile.
  • Text currently cannot be manipulated using markup language.

• Rows:
  • Text vertical alignment is fixed to center.
  • Text cannot be multi-lined, single line only.
  • Fixed to a single font size and style for all rows as set in the Control Profile.
  • Text font, style, or size cannot be set via markup language at this time.
  • Multiple row selection is not supported, single row select only.

%control = GuiModernTextListCtrl; // reference to an instance of GuiModernTextListCtrl control

// install a column along with its header
%colPos = %control.addColumn(%key, %name, %width, %minWidth, %maxWidth, %flags);
 
// %colPos now holds the index position of the just installed column

// insert a row into the list
%rowPos = %control.addRow(%key, %text, %index, %flags);
 
// %rowPos now holds the index position of the just inserted row

// remove a specific row from the list control
%control.removeRow(%index);

// remove all columns from the list control
%control.clearColumns();

// remove all rows from the list control
%control.clearRows();

// remove all column sort orders from the control
%control.clearSortOrders();

// get the column's textual flags
%colFlags = %control.getColumnFlags(%index);
 
// %colFlags now holds the requested column's textual flags

// get the column's name
%colName = %control.getColumnName(%index);
 
// %colName now holds the requested column's name

// get the key associated with the column
%colKey = %control.getColumnKey(%index);
 
// %colKey now holds the requested column's associated key

// get the column's width
%colWidth = %control.getColumnWidth(%index);
 
// %colWidth now holds the requested column's width size

// get the column's index by providing the key associated with the column
%colPos = %control.getColumnIndex(%key);
 
// %colPos now holds the requested column's index position

// get the number of columns currently installed
%colCount = %control.getColumnCount();
 
// %colCount now holds the requested number of columns

// get the number of column sort orders
%sortCount = %control.getSortOrderCount();
 
// %sortCount now holds the requested number of column sort orders

// get the column sort order specified by provided index position
%sortOrder = %control.getSortOrder(%index);
 
// %sortOrder now holds the requested column sort order string

// get the currently selected row
%rowPos = %control.getSelectedRow();
 
// %rowPos now holds the index position of the currently selected row

// get the number of rows in the list
%rowCount = %control.getRowCount();
 
// %rowCount now holds the requested number of rows in the list

// get the row's textual flags
%rowFlags = %control.getRowFlags(%index);
 
// %rowFlags now holds the requested row's textual flags

// get the entire row's content
%rowText = %control.getRowText(%index);
 
// %rowText now holds the requested entire row's content

// get the key associated with the row
%rowKey = %control.getRowKey(%index);
 
// %rowKey now holds the requested row's associated key

// get the row's index by providing the key associated with the row
%rowPos = %control.getRowIndex(%key);
 
// %rowPos now holds the requested row's index position

// make the list control's parent scroll window scroll to the point where the
// requested row is visible in the list.
%control.scrollVisible(%index);

// change the currently selected row to the requested row
%control.setSelectedRow(%index);
 
// this will not generate a OnRowSelect() callback event.

// add or update an existing column sort order
%control.setSortOrder(%sortOrder);

// set the column's textual flags
%control.setColumnFlags(%index, %flags);

// add or update an existing column sort order
%control.setColumnSortOrder(%key, %order, %makeFirst);

// set the column's width
%control.setColumnWidth(%index, %width);

// set the row's textual flags
%control.setRowFlags(%index, %flags);

// set a row's text content
%control.setRowText(%index, %text);

// set the GUI control profile for the row items
%control.setProfile(%profile);

// set the GUI control profile for the column headers
%control.setHeaderProfile(%profile);

// set the GUI control profile for the column header sort indicator
%control.setSortProfile(%profile);

// sort all columns governed by the sort order rules declared by
// using the setColumnSortOrder() and setSortOrder() methods.
%control.sortColumns();

// move a column to another index position
%control.moveColumn(%key, %index);

// move a row to another index position
%control.moveRow(%key, %index);

// strip the markup tags off of the provided text
%cleaned = %control.stripMarkup(%text);
 
// %cleaned now contains the text stripped of markup tags

// update the control's dimensions as defined by the acculumative
// widths of all columns and heights of all rows.
%control.updateSize();

function ControlObjectName::CallbackName(Arguments)
{
   // Comment that explains why the callback event occurred.
}

function GuiModernTextListCtrl::OnColumnMoved(%this, %colKey, %colOldPos, %colNewPos)
{
   // User has dragged and dropped a column to another position
}

function GuiModernTextListCtrl::OnColumnResized(%this, %colKey, %colPos, %width)
{
   // User has resized the column in the list's header and just now let go of the resizer
}

function GuiModernTextListCtrl::OnColumnSelect(%this, %colKey, %colPos, %sortOrder, %doubleClick)
{
   // User has clicked on the column header and it's up to this function to decide on the response action to this event.
   // Such as the column's sort order rule could be changed to resort the column or do nothing to not allow the the user
   // to resort the column.
}

function GuiModernTextListCtrl::OnRowSelect(%this, %rowKey, %rowPos, %colKey, %colPos, %doubleClick)
{
   // User has clicked on a text row item and this event still fires even though the selection may not have changed
}

function GuiModernTextListCtrl::OnRowUnselect(%this)
{
   // User has deselected a text row item and no other items are selected
}

function GuiModernTextListCtrl::onDeleteKey(%this, %rowKey, %rowPos)
{
   // User has pressed the delete key while a row was selected
}

GuiModernTextListCtrl has a limited support for torque markup in order to be as simple as possible and constrained to single line text cells.

The explanation of tags use various symbols to indicate whether a field is optional or not. An optional field has the square brackets [] enclosed around them, while required fields do not. Similar to HTML tags Torque Markup uses the inequality sign brackets <> enclosed around the tag name and its fields. The tags look like these:

<color:00FF00>
<bitmap:game/art/logo.png>

First one is the color tag and it would normally set the text foreground color to green, and the second is the bitmap tag which would draw a logo image into the same cell that the text is being drawn into.

This is the list of supported markup tags:

…