GuiModernTextListCtrl

Overview

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.

Download

Current source code with example scripts:


Older releases:


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

Binary release above has been updated to include a fix for machines using Intel graphics adapters getting the following error message:
Failed to initialize Direct3D. Make sure you have DirectX 9 installed, and are running a graphics card that supports pixel shader 1.1

Documentation

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

Documentation is a work in progress as it will be updated as I have the free time to improve upon it. — Nathan Martin 2011/08/21 23:10

Features

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


Limitations

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


Properties

GuiControlProfileprofileThe control profile that determines fill styles, font settings, etc. for row items.
Syntax:%obj.headerProfile = ”Value”;
ValueProfile name to be used.


GuiControlProfileheaderProfileThe control profile that determines fill styles, font settings, etc. for column headers.
Syntax:%obj.headerProfile = ”Value”;
ValueProfile name to be used.


GuiControlProfilesortProfileThe control profile that determines the texture and color of the sort order indicator in sorted column headers.
Syntax:%obj.sortProfile = ”Value”;
ValueProfile name to be used.


Point2IheaderGlowOffsetNumber of pixels that will need to be offset when drawing a column header cell's texture
Syntax:%obj.headerGlowOffset = ”Horizontal Vertical”;
HorizontalNumber of pixels to offset the left and right boundaries of the texture.
VerticalNumber of pixels to offset the top and bottom boundaries of the texture.


Point2IrowGlowOffsetNumber of pixels that will need to be offset when drawing a row column's texture
Syntax:%obj.rowGlowOffset = ”Horizontal Vertical”;
HorizontalNumber of pixels to offset the left and right boundaries of the texture.
VerticalNumber of pixels to offset the top and bottom boundaries of the texture.


Point2IheaderTextPaddingNumber of additional pixels for padding text when drawing column header cells.
Syntax:%obj.headerTextPadding = ”Horizontal Vertical”;
HorizontalNumber of horizontal pixels added for text padding.
VerticalNumber of vertical pixels added for text padding.


Point2IrowTextPaddingNumber of additional pixels for padding text when drawing row column cells.
Syntax:%obj.rowTextPadding = ”Horizontal Vertical”;
HorizontalNumber of horizontal pixels added for text padding.
VerticalNumber of vertical pixels added for text padding.


BoolallowColumnResizeWhether or not user is allowed to resize columns using the mouse cursor.
Syntax:%obj.allowColumnResize = Value;
Valuetrue – User can resize columns using the mouse cursor
false – Column resizers are locked and user cannot change them.


BoolallowColumnMoveWhether or not user is allowed to move columns via drag and drop.
Syntax:%obj.allowColumnMove = Value;
Valuetrue – User can move columns using the mouse cursor via drag and drop
false – Column positions are locked and user cannot move them.


BooluseMarkupWhether the control should use or just ignore markup language within row contents.
Syntax:%obj.useMarkup = Value;
Valuetrue – Markup language tags will be parsed and processed for text draw manipulation.
false – Markup language tags will be ignored as if the control didn't support them and control will behave like GuiTextListCtrl in this regard.


BoolresizeOnChangeWhether or not to update the control size for the scroller parent control upon content changes such as using the Add[Row|Column]() methods.
Syntax:%obj.resizeOnChange = Value;
Valuetrue – The control will update its size upon any relevant row or column changes.
false – The control will not update its size upon any row or column changes.

This property is useful for cases when the scripter is going to be inserting a massive amount of rows such as 5,000 and want to reduce the time it takes to insert the rows by not having the control perform unnecessary maintenance that isn't required until after the scripter is done populating the control with content. Afterwards the scripter can then call the updateSize() method to make it possible for the user to scroll through the just added rows. Be sure to change this property back to true once done populating the control as to prevent any awkward useability problems when rows are dynamically added or removed later on.


Methods

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


addColumn()

// 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
Method Arguments
S32%keyKey associated with the column that is being installed.
string%nameText name to be displayed as the column header's label.
U32%widthWidth in pixels of the column and its header. Default is 50 pixels.
U32%minWidthMinimum width in pixels that the column is constrained to. Default is 10 pixels.
U32%maxWidthMaximum width in pixels that the column is constrained to. Default is 250 pixels.
string%flagsColumn flag attributes in textual keyword and space delimited format that will be applied to the column.
See the Column Flag Attributes table below for an explanation of the recognized keywords that are available for use.

Columns are automatically applied the following keyword string equivalent attributes before processing provided flags: left active show
U32ReturnsIndex position of the just installed column.
Column Flag Attributes
leftRow content within the column will be displayed left aligned. This is the default.
rightRow content within the column will be displayed right aligned.
centerRow content within the column will be displayed center aligned.
numericAlias for right keyword.
activeWhether the column will be in an active/enabled state or not. Default is active.
Use the ! prefix to invert the meaning of the keyword as an opposite result.
headericonSets the column header label to be an icon instead of text and the %name argument field will be the path and file name of the icon to be displayed.

Note: This feature as explained is not yet implemented and will be available in a future control version release.
headertextSets the column header label to be text displayed as specified in the %name argument field instead of an icon. This is the default.
showWhether the column will be shown/visible or hidden/invisible. Default is shown/visible.
Can use the ! prefix to invert the meaning of the keyword as an opposite result.
visibleAlias for show keyword.
invisibleInverted alias for show keyword.


addRow()

// insert a row into the list
%rowPos = %control.addRow(%key, %text, %index, %flags);
 
// %rowPos now holds the index position of the just inserted row
Method Arguments
S32%keyKey associated with the row that is being inserted.
string%textText content of the row that is tab delimited into columns. This content supports markup language as described in the Markup Language section.
U32%indexIndex position of where the row should be inserted into. Default is -1 which causes the row to be appended at the end of the list.
An invalid index position (index >= getRowCount()) will just append the row to end of the list instead of the requested insertion position.
string%flagsRow flag attributes in textual keyword and space delimited format that will be applied to the row.
See the Row Flag Attributes table below for an explanation of the recognized keywords that are available for use.

Rows are automatically applied the following keyword string equivalent attributes before processing provided flags: active selectable
U32ReturnsIndex position of just inserted or appended row.
Row Flag Attributes
activeWhether the row will be in an active/enabled state or not. Default is active.
Overall this just determines which colors to use for drawing the row text cells from the control's profile:
Active state – fillColor, borderColor, and fontColor.
Inactive state – fillColorNA, borderColorNA, and fontColorNA.
Use the ! prefix to invert the meaning of the keyword as an opposite result.
selectableWhether the row is user selectable in the list or not. Default is selectable.
Use the ! prefix to invert the meaning of the keyword as an opposite result.


removeRow()

// remove a specific row from the list control
%control.removeRow(%index);
Method Arguments
U32%indexIndex position of the row to be removed.
An invalid index position (index >= getRowCount()) will not cause any rows to be removed, but instead the procedure will be aborted.
voidReturnsNothing.


clearColumns()

// remove all columns from the list control
%control.clearColumns();
Method Arguments
This method does not take any arguments.
voidReturnsNothing.


clearRows()

// remove all rows from the list control
%control.clearRows();
Method Arguments
This method does not take any arguments.
voidReturnsNothing.


clearSortOrders()

// remove all column sort orders from the control
%control.clearSortOrders();
Method Arguments
This method does not take any arguments.
voidReturnsNothing.


getColumnFlags()

// get the column's textual flags
%colFlags = %control.getColumnFlags(%index);
 
// %colFlags now holds the requested column's textual flags
Method Arguments
U32%indexIndex position of the column.
stringReturnsColumn's textual flags on success. See Column Flag Attributes table in addColumn() method section for details.
Empty (””) string on invalid column index.


getColumnName()

// get the column's name
%colName = %control.getColumnName(%index);
 
// %colName now holds the requested column's name
Method Arguments
U32%indexIndex position of the column.
stringReturnsColumn's name on success.
Empty (””) string on invalid column index.


getColumnKey()

// get the key associated with the column
%colKey = %control.getColumnKey(%index);
 
// %colKey now holds the requested column's associated key
Method Arguments
U32%indexIndex position of the column.
S32ReturnsKey associated with the specified column on success.
-1 on invalid column index.


getColumnWidth()

// get the column's width
%colWidth = %control.getColumnWidth(%index);
 
// %colWidth now holds the requested column's width size
Method Arguments
U32%indexIndex position of the column.
U32ReturnsColumn's current width in pixels on success.
-1 on invalid column index.


getColumnIndex()

// 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
Method Arguments
S32%keyKey associated with the column.
U32ReturnsColumn's index position on success.
-1 on invalid column key.


getColumnCount()

// get the number of columns currently installed
%colCount = %control.getColumnCount();
 
// %colCount now holds the requested number of columns
Method Arguments
This method does not take any arguments.
U32ReturnsNumber of columns


getSortOrderCount()

// get the number of column sort orders
%sortCount = %control.getSortOrderCount();
 
// %sortCount now holds the requested number of column sort orders
Method Arguments
This method does not take any arguments.
U32ReturnsNumber of column sort orders.


getSortOrder()

// get the column sort order specified by provided index position
%sortOrder = %control.getSortOrder(%index);
 
// %sortOrder now holds the requested column sort order string
Method Arguments
U32%indexIndex position of the column sort order.
stringReturnsColumn sort order string in the format of key order on success. See setSortOrder() method for details.
Empty (””) string on invalid column sort order index.


getSelectedRow()

// get the currently selected row
%rowPos = %control.getSelectedRow();
 
// %rowPos now holds the index position of the currently selected row
Method Arguments
This method does not take any arguments.
S32ReturnsIndex position of the currently selected row.
-1 when there is not a row selected.


getRowCount()

// get the number of rows in the list
%rowCount = %control.getRowCount();
 
// %rowCount now holds the requested number of rows in the list
Method Arguments
This method does not take any arguments.
U32ReturnsNumber of rows


getRowFlags()

// get the row's textual flags
%rowFlags = %control.getRowFlags(%index);
 
// %rowFlags now holds the requested row's textual flags
Method Arguments
U32%indexIndex position of the row.
stringReturnsRow's textual flags on success. See Row Flag Attributes table in addRow() method section for details.
Empty (””) string on invalid row index.


getRowText()

// get the entire row's content
%rowText = %control.getRowText(%index);
 
// %rowText now holds the requested entire row's content
Method Arguments
U32%indexIndex position of the row.
stringReturnsEntire row's content on success.
Empty (””) string on invalid row index.


getRowKey()

// get the key associated with the row
%rowKey = %control.getRowKey(%index);
 
// %rowKey now holds the requested row's associated key
Method Arguments
U32%indexIndex position of the row.
S32ReturnsKey associated with the specified row on success.
-1 on invalid row index.


getRowIndex()

// 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
Method Arguments
S32%keyKey associated with the row.
U32ReturnsRow's index position on success.
-1 on invalid row key.


scrollVisible()

// make the list control's parent scroll window scroll to the point where the
// requested row is visible in the list.
%control.scrollVisible(%index);
Method Arguments
U32%indexIndex position of the row.
voidReturnsNothing.


setSelectedRow()

// change the currently selected row to the requested row
%control.setSelectedRow(%index);
 
// this will not generate a OnRowSelect() callback event.
Method Arguments
U32%indexIndex position of the row.
Valid range is -1, for selecting none of the rows, to < getRowCount()
voidReturnsNothing.


setSortOrder()

// add or update an existing column sort order
%control.setSortOrder(%sortOrder);
Method Arguments
string%sortOrderSort order string in the format of key order [makeFirst]. See the Sort Orders table below for details about the space delimited fields.
Note: The square brackets [] in the format string above means an optional field and those brackets are not supposed actually exist in the string.
voidReturnsNothing.
Sort Orders
keyKey associated with the column that this sort order will be tied to.
order0 – Column is to be sorted by Ascending order.
1 – Column is to be sorted by Descending order.
Any other values are undefined behavior.
makeFirstOptional field that when it is a numerical value of other than zero (0) to indicate that the sort order will become the highest priority or most significant column sort order.


setColumnFlags()

// set the column's textual flags
%control.setColumnFlags(%index, %flags);
Method Arguments
U32%indexIndex position of the column.
string%flagsColumn flag attributes in textual keyword and space delimited format that will be applied to the column.
See the Column Flag Attributes table in addColumn() method section for an explanation of the recognized keywords that are available for use.
voidReturnsNothing.


setColumnSortOrder()

// add or update an existing column sort order
%control.setColumnSortOrder(%key, %order, %makeFirst);
Method Arguments
S32%keyKey associated with the column that this sort order will be tied to.
S32%order0 – Column is to be sorted by Ascending order.
1 – Column is to be sorted by Descending order.
Any other values are undefined behavior.
bool%makeFirstOptional field when true this sort order will become the highest priority or most significant column sort order, else the sort order is just appended or updated if it already exists.
Default is false
voidReturnsNothing.


setColumnWidth()

// set the column's width
%control.setColumnWidth(%index, %width);
Method Arguments
U32%indexIndex position of the column.
U32%widthWidth in pixels of the column and its header.
This value is validated against the column's minimum and maximum width size constraints as set in the addColumn() method.
voidReturnsNothing.


setRowFlags()

// set the row's textual flags
%control.setRowFlags(%index, %flags);
Method Arguments
U32%indexIndex position of the row.
string%flagsRow flag attributes in textual keyword and space delimited format that will be applied to the row.
See the Row Flag Attributes table in addRow() method section for an explanation of the recognized keywords that are available for use.
voidReturnsNothing.


setRowText()

// set a row's text content
%control.setRowText(%index, %text);
Method Arguments
U32%indexIndex position of the row.
string%textText content to be set as the entire row's content that is tab delimited into columns. This content supports markup language as described in the Markup Language section.
voidReturnsNothing.


setProfile()

// set the GUI control profile for the row items
%control.setProfile(%profile);
Method Arguments
GuiControlProfile%profileProfile to be used for row items.
This is an alternative method to just setting the profile property to the profile.
voidReturnsNothing.


setHeaderProfile()

// set the GUI control profile for the column headers
%control.setHeaderProfile(%profile);
Method Arguments
GuiControlProfile%profileProfile to be used for column headers.
This is an alternative method to just setting the headerProfile property to the profile.
voidReturnsNothing.


setSortProfile()

// set the GUI control profile for the column header sort indicator
%control.setSortProfile(%profile);
Method Arguments
GuiControlProfile%profileProfile to be used for the column header sort indicator.
This is an alternative method to just setting the sortProfile property to the profile.
voidReturnsNothing.


sortColumns()

// sort all columns governed by the sort order rules declared by
// using the setColumnSortOrder() and setSortOrder() methods.
%control.sortColumns();
Method Arguments
This method does not take any arguments.
voidReturnsNothing.


moveColumn()

// move a column to another index position
%control.moveColumn(%key, %index);
Method Arguments
S32%keyKey associated with the column.
U32%indexIndex position to move the column to.
Valid range is < getColumnCount() else the column will be moved to the end as the last column header in the list.
voidReturnsNothing.


moveRow()

// move a row to another index position
%control.moveRow(%key, %index);
Method Arguments
S32%keyKey associated with the row.
U32%indexIndex position to move the row to.
Valid range is < getRowCount() else the row will be moved to the end as the last list item in the list.
voidReturnsNothing.


stripMarkup()

// strip the markup tags off of the provided text
%cleaned = %control.stripMarkup(%text);
 
// %cleaned now contains the text stripped of markup tags
Method Arguments
string%textText string to be removed of all markup tags.
stringReturnsText passed to the method stripped of markup tags.


updateSize()

// update the control's dimensions as defined by the acculumative
// widths of all columns and heights of all rows.
%control.updateSize();
Method Arguments
This method does not take any arguments.
voidReturnsNothing.


Callbacks

Documentation Format Explanation

function ControlObjectName::CallbackName(Arguments)
{
   // Comment that explains why the callback event occurred.
}
Callback Arguments
Source data type%argVariableNameDescription of the argument variable.


OnColumnMoved()

function GuiModernTextListCtrl::OnColumnMoved(%this, %colKey, %colOldPos, %colNewPos)
{
   // User has dragged and dropped a column to another position
}
Callback Arguments
S32%thisReference to the GuiModernTextList object instance.
S32%colKeyKey associated with the column that was moved.
U32%colOldPosColumn's previous index position in the header.
U32%colNewPosColumn's new and current index position in the header.


OnColumnResized()

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
}
Callback Arguments
S32%thisReference to the GuiModernTextList object instance.
S32%colKeyKey associated with the column that was just resized.
U32%colPosIndex position of the column within the list's header.
U32%widthThe new and current width of the column.


OnColumnSelect()

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.
}
Callback Arguments
S32%thisReference to the GuiModernTextList object instance.
S32%colKeyKey associated with the column that was just clicked.
U32%colPosIndex position of the column that was just clicked.
S32%sortOrderCurrent sort order of the column that was just clicked.
bool%doubleClickValue of one or true when this a double-click event.


OnRowSelect()

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
}
Callback Arguments
S32%thisReference to the GuiModernTextList object instance.
S32%rowKeyKey associated with the new and currently selected row.
U32%rowPosIndex position of the new and currently selected row.
S32%colKeyKey associated with the clicked on column during row selection.
U32%colPosIndex position of the clicked on column during row selection.
bool%doubleClickValue of one or true when this a double-click event.


OnRowUnselect()

function GuiModernTextListCtrl::OnRowUnselect(%this)
{
   // User has deselected a text row item and no other items are selected
}
Callback Arguments
S32%thisReference to the GuiModernTextList object instance.


onDeleteKey()

function GuiModernTextListCtrl::onDeleteKey(%this, %rowKey, %rowPos)
{
   // User has pressed the delete key while a row was selected
}
Callback Arguments
S32%thisReference to the GuiModernTextList object instance.
S32%rowKeyKey associated with the currently selected row.
U32%rowPosIndex position of the currently selected row.


Markup Language

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:

<color[:RRGGBB[AA]]>Foreground text color tag
RRGGBB[AA]Optional tag field that declares the foreground text color when specified in the Red Green Blue hexadecimal format just like HTML without the number sign # character. When the field is not set, which includes not providing the colon : tag field separator, then the foreground color stack is popped up to the color that is set in the Control Profile.

Additionally a sub-optional field is available to specify the color's alpha value, again in hexadecimal. 00 for completely transparent or FF for opaque.
<[!pv:]bitmap:imageFilePath>Bitmap image tag
imageFilePathRequired field that specifies the file path to the bitmap to be drawn.
[!pv:]Optional tag field is a unique attribute to GuiModernTextListCtrl that declares a primitive value for bitmap tags to specify the textual value when the markup tags are stripped for cases like row column sort order processing.

Example:
<!V12:bitmap:core/art/images/logo.png> will be replaced with “V12” during column sorting.


Control Profiles


Examples


programming/tge/controls/guimoderntextlistctrl.txt · Last modified: 2011/09/20 16:13 by Nathan Martin
 
Except where otherwise noted, content on this wiki is licensed under the following license: CC Attribution-Noncommercial-Share Alike 3.0 Unported
Recent changes RSS feed Donate Powered by PHP Valid XHTML 1.0 Valid CSS Driven by DokuWiki