[[GuiModernTextListCtrl]]
 
Trace:
no way to compare when less than two revisions

Differences

This shows you the differences between two versions of the page.


Previous revision
Last revision
—programming:tge:controls:guimoderntextlistctrl [2011/09/20 23:11] – [Methods] all methods are finally documented Nathan Martin
Line 1: Line 1:
 +====== 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 {{:wiki:tribes2_browser.png?linkonly|seen in Tribes 2}} for both the control behavior and torquescript side features.
 +
 +
 +{{:wiki:moderntextlistctrl_ss2b.png |}}
 +
 +{{:programming:tge:controls:moderntextlistctrl_ss3.png|}}
 +
 +===== Download =====
 +Current source code with example scripts:
 +  * v1.01 [[http://dottools.net/downloads/imgs/t3d/res/GuiModernTextListCtrl101.zip|GuiModernTextListCtrl101.zip]] (404KByte zip)
 +  * See [[programming/tge/controls/guimoderntextlistctrl/status#Changelog]] for details.
 +\\ 
 +
 +Older releases:
 +  * v1.00 [[http://dottools.net/downloads/imgs/t3d/res/GuiModernTextListCtrl100.zip|GuiModernTextListCtrl100.zip]] (393KByte zip)
 +\\ 
 +
 +[[http://dottools.net/downloads/imgs/t3d/res/playgnd.zip|Binary test release]] is available for v1.00 (8.5MByte zip).
 +<note tip>
 +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''"
 +</note>
 +
 +===== Documentation =====
 +The current project status, known bugs, and chanegelog of this control can be found at the [[programming/tge/controls/guimoderntextlistctrl/status]] page.
 +
 +
 +<note>
 +Documentation is a work in progress as it will be updated as I have the free time to improve upon it.
 + --- //[[nmartin@gmail.com|Nathan Martin]] 2011/08/21 23:10//
 +</note>
 +
 +==== 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 ====
 +
 +|//GuiControlProfile//^headerProfile|The control profile that determines fill styles, font settings, etc. for column headers.||
 +| ^  Syntax:|''//**%obj**//.headerProfile = "//**__Value__**//";''  ||
 +| |^  //Value//|Profile name to be used.|
 +
 +\\ 
 +
 +|//GuiControlProfile//^sortProfile|The control profile that determines the texture and color of the sort order indicator in sorted column headers.||
 +| ^  Syntax:|''//**%obj**//.sortProfile = "//**__Value__**//";''  ||
 +| |^  //Value//|Profile name to be used.|
 +
 +\\ 
 +
 +|//Point2I//^headerGlowOffset|Number of pixels that will need to be offset when drawing a column header cell's texture||
 +| ^  Syntax:|''//**%obj**//.headerGlowOffset = "//**__Horizontal__ __Vertical__**//";''||
 +| |^  //Horizontal//|Number of pixels to offset the left and right boundaries of the texture.|
 +|:::|^  //Vertical//|Number of pixels to offset the top and bottom boundaries of the texture.|
 +
 +\\ 
 +
 +|//Point2I//^rowGlowOffset|Number of pixels that will need to be offset when drawing a row column's texture||
 +| ^  Syntax:|''//**%obj**//.rowGlowOffset = "//**__Horizontal__ __Vertical__**//";''||
 +| |^  //Horizontal//|Number of pixels to offset the left and right boundaries of the texture.|
 +|:::|^  //Vertical//|Number of pixels to offset the top and bottom boundaries of the texture.|
 +
 +\\ 
 +
 +|//Point2I//^headerTextPadding|Number of additional pixels for padding text when drawing column header cells.||
 +| ^  Syntax:|''//**%obj**//.headerTextPadding = "//**__Horizontal__ __Vertical__**//";''||
 +| |^  //Horizontal//|Number of horizontal pixels added for text padding.|
 +|:::|^  //Vertical//|Number of vertical pixels added for text padding.|
 +
 +\\ 
 +
 +|//Point2I//^rowTextPadding|Number of additional pixels for padding text when drawing row column cells.||
 +| ^  Syntax:|''//**%obj**//.rowTextPadding = "//**__Horizontal__ __Vertical__**//";''||
 +| |^  //Horizontal//|Number of horizontal pixels added for text padding.|
 +|:::|^  //Vertical//|Number of vertical pixels added for text padding.|
 +
 +\\ 
 +
 +|//Bool//^allowColumnResize|Whether or not user is allowed to resize columns using the mouse cursor.||
 +| ^  Syntax:|''//**%obj**//.allowColumnResize = //**__Value__**//;''||
 +| |^  //Value//|**true** -- User can resize columns using the mouse cursor\\ **false** -- Column resizers are locked and user cannot change them.|
 +
 +\\ 
 +
 +|//Bool//^allowColumnMove|Whether or not user is allowed to move columns via drag and drop.||
 +| ^  Syntax:|''//**%obj**//.allowColumnMove = //**__Value__**//;''||
 +| |^  //Value//|**true** -- User can move columns using the mouse cursor via drag and drop\\ **false** -- Column positions are locked and user cannot move them.|
 +
 +\\ 
 +
 +|//Bool//^useMarkup|Whether the control should use or just ignore markup language within row contents.||
 +| ^  Syntax:|''//**%obj**//.useMarkup = //**__Value__**//;''||
 +| |^  //Value//|**true** -- 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.|
 +
 +\\ 
 +
 +|//Bool//^resizeOnChange|Whether 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__**//;''||
 +| |^  //Value//|**true** -- 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 ====
 +<code php>
 +%control = GuiModernTextListCtrl; // reference to an instance of GuiModernTextListCtrl control
 +</code>
 +\\ 
 +
 +
 +=== addColumn() ===
 +<code php>
 +// 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
 +</code>
 +^  Method Arguments  ^^^
 +|//S32//^//%key//|Key associated with the column that is being installed.|
 +|//string//^//%name//|Text name to be displayed as the column header's label.|
 +|//U32//^//%width//|Width in pixels of the column and its header. Default is 50 pixels.|
 +|//U32//^//%minWidth//|Minimum width in pixels that the column is constrained to. Default is 10 pixels.|
 +|//U32//^//%maxWidth//|Maximum width in pixels that the column is constrained to. Default is 250 pixels.|
 +|//string//^//%flags//|Column 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**"''|
 +| |||
 +|//U32//^Returns|Index position of the just installed column.|
 +
 +^  Column Flag Attributes  ^^
 +^//left//|Row content within the column will be displayed left aligned. This is the default.|
 +^//right//|Row content within the column will be displayed right aligned.|
 +^//center//|Row content within the column will be displayed center aligned.|
 +^//numeric//|Alias for //**right**// keyword.|
 +^//active//|Whether 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.|
 +^//headericon//|Sets 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.|
 +^//headertext//|Sets the column header label to be text displayed as specified in the //**%name**// argument field instead of an icon. This is the default.|
 +^//show//|Whether 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.|
 +^//visible//|Alias for //**show**// keyword.|
 +^//invisible//|Inverted alias for //**show**// keyword.|
 +\\ 
 +
 +
 +=== addRow() ===
 +<code php>
 +// insert a row into the list
 +%rowPos = %control.addRow(%key, %text, %index, %flags);
 +
 +// %rowPos now holds the index position of the just inserted row
 +</code>
 +^  Method Arguments  ^^^
 +|//S32//^//%key//|Key associated with the row that is being inserted.|
 +|//string//^//%text//|Text content of the row that is tab delimited into columns. This content supports markup language as described in the [[#Markup Language]] section.|
 +|//U32//^//%index//|Index 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//^//%flags//|Row 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**"''|
 +| |||
 +|//U32//^Returns|Index position of just inserted or appended row.|
 +
 +^  Row Flag Attributes  ^^
 +^//active//|Whether 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.|
 +^//selectable//|Whether 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() ===
 +<code php>
 +// remove a specific row from the list control
 +%control.removeRow(%index);
 +</code>
 +^  Method Arguments  ^^^
 +|//U32//^//%index//|Index 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.|
 +| |||
 +|//void//^Returns|Nothing.|
 +\\ 
 +
 +
 +=== clearColumns() ===
 +<code php>
 +// remove all columns from the list control
 +%control.clearColumns();
 +</code>
 +^  Method Arguments  ^^^
 +|This method does not take any arguments.|||
 +| |||
 +|//void//^Returns|Nothing.|
 +\\ 
 +
 +
 +=== clearRows() ===
 +<code php>
 +// remove all rows from the list control
 +%control.clearRows();
 +</code>
 +^  Method Arguments  ^^^
 +|This method does not take any arguments.|||
 +| |||
 +|//void//^Returns|Nothing.|
 +\\ 
 +
 +
 +=== clearSortOrders() ===
 +<code php>
 +// remove all column sort orders from the control
 +%control.clearSortOrders();
 +</code>
 +^  Method Arguments  ^^^
 +|This method does not take any arguments.|||
 +| |||
 +|//void//^Returns|Nothing.|
 +\\ 
 +
 +
 +=== getColumnFlags() ===
 +<code php>
 +// get the column's textual flags
 +%colFlags = %control.getColumnFlags(%index);
 +
 +// %colFlags now holds the requested column's textual flags
 +</code>
 +^  Method Arguments  ^^^
 +|//U32//^//%index//|Index position of the column.|
 +| |||
 +|//string//^Returns|Column's textual flags on success. See **Column Flag Attributes** table in [[#addColumn()]] method section for details.\\ Empty (''""'') string on invalid column index.|
 +\\ 
 +
 +
 +=== getColumnName() ===
 +<code php>
 +// get the column's name
 +%colName = %control.getColumnName(%index);
 +
 +// %colName now holds the requested column's name
 +</code>
 +^  Method Arguments  ^^^
 +|//U32//^//%index//|Index position of the column.|
 +| |||
 +|//string//^Returns|Column's name on success.\\ Empty (''""'') string on invalid column index.|
 +\\ 
 +
 +
 +=== getColumnKey() ===
 +<code php>
 +// get the key associated with the column
 +%colKey = %control.getColumnKey(%index);
 +
 +// %colKey now holds the requested column's associated key
 +</code>
 +^  Method Arguments  ^^^
 +|//U32//^//%index//|Index position of the column.|
 +| |||
 +|//S32//^Returns|Key associated with the specified column on success.\\ ''-1'' on invalid column index.|
 +\\ 
 +
 +
 +=== getColumnWidth() ===
 +<code php>
 +// get the column's width
 +%colWidth = %control.getColumnWidth(%index);
 +
 +// %colWidth now holds the requested column's width size
 +</code>
 +^  Method Arguments  ^^^
 +|//U32//^//%index//|Index position of the column.|
 +| |||
 +|//U32//^Returns|Column's current width in pixels on success.\\ ''-1'' on invalid column index.|
 +\\ 
 +
 +
 +=== getColumnIndex() ===
 +<code php>
 +// 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
 +</code>
 +^  Method Arguments  ^^^
 +|//S32//^//%key//|Key associated with the column.|
 +| |||
 +|//U32//^Returns|Column's index position on success.\\ ''-1'' on invalid column key.|
 +\\ 
 +
 +
 +=== getColumnCount() ===
 +<code php>
 +// get the number of columns currently installed
 +%colCount = %control.getColumnCount();
 +
 +// %colCount now holds the requested number of columns
 +</code>
 +^  Method Arguments  ^^^
 +|This method does not take any arguments.|||
 +| |||
 +|//U32//^Returns|Number of columns|
 +\\ 
 +
 +
 +=== getSortOrderCount() ===
 +<code php>
 +// get the number of column sort orders
 +%sortCount = %control.getSortOrderCount();
 +
 +// %sortCount now holds the requested number of column sort orders
 +</code>
 +^  Method Arguments  ^^^
 +|This method does not take any arguments.|||
 +| |||
 +|//U32//^Returns|Number of column sort orders.|
 +\\ 
 +
 +
 +=== getSortOrder() ===
 +<code php>
 +// get the column sort order specified by provided index position
 +%sortOrder = %control.getSortOrder(%index);
 +
 +// %sortOrder now holds the requested column sort order string
 +</code>
 +^  Method Arguments  ^^^
 +|//U32//^//%index//|Index position of the column sort order.|
 +| |||
 +|//string//^Returns|Column 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() ===
 +<code php>
 +// get the currently selected row
 +%rowPos = %control.getSelectedRow();
 +
 +// %rowPos now holds the index position of the currently selected row
 +</code>
 +^  Method Arguments  ^^^
 +|This method does not take any arguments.|||
 +| |||
 +|//S32//^Returns|Index position of the currently selected row.\\ ''-1'' when there is not a row selected.|
 +\\ 
 +
 +
 +=== getRowCount() ===
 +<code php>
 +// get the number of rows in the list
 +%rowCount = %control.getRowCount();
 +
 +// %rowCount now holds the requested number of rows in the list
 +</code>
 +^  Method Arguments  ^^^
 +|This method does not take any arguments.|||
 +| |||
 +|//U32//^Returns|Number of rows|
 +\\ 
 +
 +
 +=== getRowFlags() ===
 +<code php>
 +// get the row's textual flags
 +%rowFlags = %control.getRowFlags(%index);
 +
 +// %rowFlags now holds the requested row's textual flags
 +</code>
 +^  Method Arguments  ^^^
 +|//U32//^//%index//|Index position of the row.|
 +| |||
 +|//string//^Returns|Row's textual flags on success. See **Row Flag Attributes** table in [[#addRow()]] method section for details.\\ Empty (''""'') string on invalid row index.|
 +\\ 
 +
 +
 +=== getRowText() ===
 +<code php>
 +// get the entire row's content
 +%rowText = %control.getRowText(%index);
 +
 +// %rowText now holds the requested entire row's content
 +</code>
 +^  Method Arguments  ^^^
 +|//U32//^//%index//|Index position of the row.|
 +| |||
 +|//string//^Returns|Entire row's content on success.\\ Empty (''""'') string on invalid row index.|
 +\\ 
 +
 +
 +=== getRowKey() ===
 +<code php>
 +// get the key associated with the row
 +%rowKey = %control.getRowKey(%index);
 +
 +// %rowKey now holds the requested row's associated key
 +</code>
 +^  Method Arguments  ^^^
 +|//U32//^//%index//|Index position of the row.|
 +| |||
 +|//S32//^Returns|Key associated with the specified row on success.\\ ''-1'' on invalid row index.|
 +\\ 
 +
 +
 +=== getRowIndex() ===
 +<code php>
 +// 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
 +</code>
 +^  Method Arguments  ^^^
 +|//S32//^//%key//|Key associated with the row.|
 +| |||
 +|//U32//^Returns|Row's index position on success.\\ ''-1'' on invalid row key.|
 +\\ 
 +
 +
 +=== scrollVisible() ===
 +<code php>
 +// make the list control's parent scroll window scroll to the point where the
 +// requested row is visible in the list.
 +%control.scrollVisible(%index);
 +</code>
 +^  Method Arguments  ^^^
 +|//U32//^//%index//|Index position of the row.|
 +| |||
 +|//void//^Returns|Nothing.|
 +\\ 
 +
 +
 +=== setSelectedRow() ===
 +<code php>
 +// change the currently selected row to the requested row
 +%control.setSelectedRow(%index);
 +
 +// this will not generate a OnRowSelect() callback event.
 +</code>
 +^  Method Arguments  ^^^
 +|//U32//^//%index//|Index position of the row.\\ Valid range is ''-1'', for selecting none of the rows, to **''< [[#getRowCount()]]''**|
 +| |||
 +|//void//^Returns|Nothing.|
 +\\ 
 +
 +
 +=== setSortOrder() ===
 +<code php>
 +// add or update an existing column sort order
 +%control.setSortOrder(%sortOrder);
 +</code>
 +^  Method Arguments  ^^^
 +|//string//^//%sortOrder//|Sort 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.|
 +| |||
 +|//void//^Returns|Nothing.|
 +
 +^  Sort Orders  ^^
 +^//key//|Key associated with the column that this sort order will be tied to.|
 +^//order//|''0'' -- Column is to be sorted by Ascending order.\\ ''1'' -- Column is to be sorted by Descending order.\\ Any other values are undefined behavior.|
 +^//makeFirst//|Optional 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() ===
 +<code php>
 +// set the column's textual flags
 +%control.setColumnFlags(%index, %flags);
 +</code>
 +^  Method Arguments  ^^^
 +|//U32//^//%index//|Index position of the column.|
 +|//string//^//%flags//|Column 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.|
 +| |||
 +|//void//^Returns|Nothing.|
 +\\ 
 +
 +
 +=== setColumnSortOrder() ===
 +<code php>
 +// add or update an existing column sort order
 +%control.setColumnSortOrder(%key, %order, %makeFirst);
 +</code>
 +^  Method Arguments  ^^^
 +|//S32//^//%key//|Key associated with the column that this sort order will be tied to.|
 +|//S32//^//%order//|''0'' -- Column is to be sorted by Ascending order.\\ ''1'' -- Column is to be sorted by Descending order.\\ Any other values are undefined behavior.|
 +|//bool//^//%makeFirst//|Optional 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''**|
 +| |||
 +|//void//^Returns|Nothing.|
 +\\ 
 +
 +
 +=== setColumnWidth() ===
 +<code php>
 +// set the column's width
 +%control.setColumnWidth(%index, %width);
 +</code>
 +^  Method Arguments  ^^^
 +|//U32//^//%index//|Index position of the column.|
 +|//U32//^//%width//|Width 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.|
 +| |||
 +|//void//^Returns|Nothing.|
 +\\ 
 +
 +
 +=== setRowFlags() ===
 +<code php>
 +// set the row's textual flags
 +%control.setRowFlags(%index, %flags);
 +</code>
 +^  Method Arguments  ^^^
 +|//U32//^//%index//|Index position of the row.|
 +|//string//^//%flags//|Row 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.|
 +| |||
 +|//void//^Returns|Nothing.|
 +\\ 
 +
 +
 +=== setRowText() ===
 +<code php>
 +// set a row's text content
 +%control.setRowText(%index, %text);
 +</code>
 +^  Method Arguments  ^^^
 +|//U32//^//%index//|Index position of the row.|
 +|//string//^//%text//|Text 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.|
 +| |||
 +|//void//^Returns|Nothing.|
 +\\ 
 +
 +
 +=== setProfile() ===
 +<code php>
 +// set the GUI control profile for the row items
 +%control.setProfile(%profile);
 +</code>
 +^  Method Arguments  ^^^
 +|//GuiControlProfile//^//%profile//|Profile to be used for row items.\\ This is an alternative method to just setting the [[#Properties|profile]] property to the profile.|
 +| |||
 +|//void//^Returns|Nothing.|
 +\\ 
 +
 +
 +=== setHeaderProfile() ===
 +<code php>
 +// set the GUI control profile for the column headers
 +%control.setHeaderProfile(%profile);
 +</code>
 +^  Method Arguments  ^^^
 +|//GuiControlProfile//^//%profile//|Profile to be used for column headers.\\ This is an alternative method to just setting the [[#Properties|headerProfile]] property to the profile.|
 +| |||
 +|//void//^Returns|Nothing.|
 +\\ 
 +
 +
 +=== setSortProfile() ===
 +<code php>
 +// set the GUI control profile for the column header sort indicator
 +%control.setSortProfile(%profile);
 +</code>
 +^  Method Arguments  ^^^
 +|//GuiControlProfile//^//%profile//|Profile to be used for the column header sort indicator.\\ This is an alternative method to just setting the [[#Properties|sortProfile]] property to the profile.|
 +| |||
 +|//void//^Returns|Nothing.|
 +\\ 
 +
 +
 +=== sortColumns() ===
 +<code php>
 +// sort all columns governed by the sort order rules declared by
 +// using the setColumnSortOrder() and setSortOrder() methods.
 +%control.sortColumns();
 +</code>
 +^  Method Arguments  ^^^
 +|This method does not take any arguments.|||
 +| |||
 +|//void//^Returns|Nothing.|
 +\\ 
 +
 +
 +=== moveColumn() ===
 +<code php>
 +// move a column to another index position
 +%control.moveColumn(%key, %index);
 +</code>
 +^  Method Arguments  ^^^
 +|//S32//^//%key//|Key associated with the column.|
 +|//U32//^//%index//|Index 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.|
 +| |||
 +|//void//^Returns|Nothing.|
 +\\ 
 +
 +
 +=== moveRow() ===
 +<code php>
 +// move a row to another index position
 +%control.moveRow(%key, %index);
 +</code>
 +^  Method Arguments  ^^^
 +|//S32//^//%key//|Key associated with the row.|
 +|//U32//^//%index//|Index 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.|
 +| |||
 +|//void//^Returns|Nothing.|
 +\\ 
 +
 +
 +=== stripMarkup() ===
 +<code php>
 +// strip the markup tags off of the provided text
 +%cleaned = %control.stripMarkup(%text);
 +
 +// %cleaned now contains the text stripped of markup tags
 +</code>
 +^  Method Arguments  ^^^
 +|//string//^//%text//|Text string to be removed of all markup tags.|
 +| |||
 +|//string//^Returns|Text passed to the method stripped of markup tags.|
 +\\ 
 +
 +
 +=== updateSize() ===
 +<code php>
 +// update the control's dimensions as defined by the acculumative
 +// widths of all columns and heights of all rows.
 +%control.updateSize();
 +</code>
 +^  Method Arguments  ^^^
 +|This method does not take any arguments.|||
 +| |||
 +|//void//^Returns|Nothing.|
 +\\ 
 +
 +
 +==== Callbacks ====
 +
 +=== Documentation Format Explanation ===
 +<code php>
 +function ControlObjectName::CallbackName(Arguments)
 +{
 +   // Comment that explains why the callback event occurred.
 +}
 +</code>
 +^  Callback Arguments  ^^^
 +|//Source data type//^//%argVariableName//|//Description of the argument variable.//|
 +\\ 
 +
 +
 +=== OnColumnMoved() ===
 +<code php>
 +function GuiModernTextListCtrl::OnColumnMoved(%this, %colKey, %colOldPos, %colNewPos)
 +{
 +   // User has dragged and dropped a column to another position
 +}
 +</code>
 +^  Callback Arguments  ^^^
 +|//S32//^//%this//|Reference to the GuiModernTextList object instance.|
 +|//S32//^//%colKey//|Key associated with the column that was moved.|
 +|//U32//^//%colOldPos//|Column's previous index position in the header.|
 +|//U32//^//%colNewPos//|Column's new and current index position in the header.|
 +\\ 
 +
 +
 +=== OnColumnResized() ===
 +<code php>
 +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
 +}
 +</code>
 +^  Callback Arguments  ^^^
 +|//S32//^//%this//|Reference to the GuiModernTextList object instance.|
 +|//S32//^//%colKey//|Key associated with the column that was just resized.|
 +|//U32//^//%colPos//|Index position of the column within the list's header.|
 +|//U32//^//%width//|The new and current width of the column.|
 +\\ 
 +
 +
 +=== OnColumnSelect() ===
 +<code php>
 +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.
 +}
 +</code>
 +^  Callback Arguments  ^^^
 +|//S32//^//%this//|Reference to the GuiModernTextList object instance.|
 +|//S32//^//%colKey//|Key associated with the column that was just clicked.|
 +|//U32//^//%colPos//|Index position of the column that was just clicked.|
 +|//S32//^//%sortOrder//|Current sort order of the column that was just clicked.|
 +|//bool//^//%doubleClick//|Value of one or true when this a double-click event.|
 +\\ 
 +
 +
 +=== OnRowSelect() ===
 +<code php>
 +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
 +}
 +</code>
 +^  Callback Arguments  ^^^
 +|//S32//^//%this//|Reference to the GuiModernTextList object instance.|
 +|//S32//^//%rowKey//|Key associated with the new and currently selected row.|
 +|//U32//^//%rowPos//|Index position of the new and currently selected row.|
 +|//S32//^//%colKey//|Key associated with the clicked on column during row selection.|
 +|//U32//^//%colPos//|Index position of the clicked on column during row selection.|
 +|//bool//^//%doubleClick//|Value of one or true when this a double-click event.|
 +\\ 
 +
 +
 +=== OnRowUnselect() ===
 +<code php>
 +function GuiModernTextListCtrl::OnRowUnselect(%this)
 +{
 +   // User has deselected a text row item and no other items are selected
 +}
 +</code>
 +^  Callback Arguments  ^^^
 +|//S32//^//%this//|Reference to the GuiModernTextList object instance.|
 +\\ 
 +
 +
 +=== onDeleteKey() ===
 +<code php>
 +function GuiModernTextListCtrl::onDeleteKey(%this, %rowKey, %rowPos)
 +{
 +   // User has pressed the delete key while a row was selected
 +}
 +</code>
 +^  Callback Arguments  ^^^
 +|//S32//^//%this//|Reference to the GuiModernTextList object instance.|
 +|//S32//^//%rowKey//|Key associated with the currently selected row.|
 +|//U32//^//%rowPos//|Index 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:
 +<code>
 +<color:00FF00>
 +<bitmap:game/art/logo.png>
 +</code>
 +
 +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 ||
 +|:::^imageFilePath|Required 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 23:13 by Nathan Martin
 
Except where otherwise noted, content on this wiki is licensed under the following license: CC Attribution-Noncommercial-Share Alike 4.0 International
Recent changes RSS feed Donate Powered by PHP Valid XHTML 1.0 Valid CSS Driven by DokuWiki