\cocoascreenfonts1{\fonttbl\f0\fnil\fcharset0 LucidaGrande;}

{\colortbl;\red255\green255\blue255;\red0\green0\blue127;\red127\green127\blue0;\red127\green0\blue127;

\red0\green127\blue127;\red0\green127\blue0;\red255\green0\blue0;}

{\title modTableField}

{\author Bernd Niggemann}

{\*\copyright Bernd Niggemann}}\paperw11900\paperh16840\margl1440\margr1440\vieww30360\viewh20560\viewkind0

\f0\fs30 \cf0 \

\fs40 modTableField

\fs36 \

version 0_3_3 beta\

\fs30 \'a9 Bernd Niggemann 2010-2015\

\cf0 \

\fs26 \cf0 modTableField evolved from the Basic Table Field provided by LiveCode. It is an attempt to provide a straightforward means for displaying tabular data without having to resort to the DataGrid. Which of course is a lot more powerful.\

It displays tabular data, includes a header, sorting, alternating line colors. Column width can be set automatically to fit the content of the data. Vertical dividers can be dragged manually to change column width.\

It does not provide alignment of columns in versions of Livecode < 7.0, i.e. all columns are left aligned to the vertical dividers. (a LIveCode limit). Since Livecode 7.0 supports text alignment for columns this has been added to modTableField.\

It uses plain LiveCode and is supposed to be self-contained. Meaning you can have 2 or more of modTableFields (with different names for the widget) on one card. No front or back script. Has been developed tested against 6.6.2 and later. As of version 0_2_9 support for pre Livecode version 6.6.2 has been dropped and support for LC 7.0 has been added. Earlier versions of modTablefield do not support LC 7.0 but work in LC version < 6.6.2 Recommended is version 6.6.X or 6.7.X or 7.0.x or higher if you want to use the hidden column feature. Earlier versions work but have display problems with vertical divider after last column.\

As of version 0_3_3 minimum version is LC 6.5 due to use of image resolve for Icons\

Data and Headers are expected to be tab-delimited, a return is end of line.\

Tabs determine the columns a return end of a record. Data is "sanitized" on import, missing tabs are added.\

\cf0 Once loaded with data you have some options for display.\

You can

\b0 into header or data field with the control-key down adjusts the column sizes to the width of the content for all columns. Currently the maximum width of a column is set to 150 pixel, the min width to 30 pixel. You can still manually adjust the column width by dragging the vertical dividers individually once the cursor changes over a divider.\

Click-dragging on the leftmost divider with the option-key or alt-key down sets the column width of all columns to the width of the first column.\

Manually changing column width can be turned off with mtfAllowColumnResizing pBool, see below. This also turns off automatic column adjustment to content width by control-clicking into the data field.\

Sorting\

clicking into a header column sorts the data by that column. Currently the code looks at the first line of data and tries to test the data of the column to decide if it is a number a date or text. If inconclusive sorting defaults to text. The triangle displays the current sort state: pointing up means the column was sorted ascending. Clicking again into the header reverses sort order: triangle pointing down means the data has been sorted by that column descending.\

If you provide a comma-delimited list of the appropriate type of sort, sorting will use that list.\

The sort types are those provided by LiveCode:\

\cf2 text,numeric,dateTime,systemDate,international\cf0 \

additionally \cf2 custom,none\cf0 \

\b0 sorting ASCII text ignoring international ACII character like accented chars and umlaute.\

\b0 sorts text taking into account accented chars\

\b0 sorts numbers\

\b0 sort english dateTime\

\b0 sorts according to the date format of the computer it is run on. \

\b0 if custom is set for a column header clicking on it will dispatch a "mtfCustomSort" message, you provide the sorting, allows for fancy sorting\

\b0 if none is set the column can not be sorted\

Sorting by clicking in the header columns is enabled/disabled by issuing mtfAllowSorting pBool\

see below for example\

mtfSortList lets you sort a column in the order of the items of a provided list, see "mtfSortList"\

Changing existing Data manually\

Double-Clicking on a cell opens a field for manual change of data. Return key, tab key, enter key or click outside of input field saves changes to data. A mtfDataWasChangedByUser message is sent when changed data is changed. See below for example. \

Tab goes to next cell, shift- tab goes to previous cell, alt-arrow keys navigate the Editor field, Shift-arrow keys do the same as Alt-arrow keys. Changing the positon of the Editor-Field saves changes of the text to the cell and triggers mtfDataWasChangedByUser. If nothing is changed nothing is saved. \

In Livecode 6.7.x and up a column can be hidden (except first column which shows rest because of vertical divider). Navigation of the Editor for manual cell editing skips columns with widths 0.\

Using the arrow keys without modifier key navigates the text of the Editor field.\

Currently it is not possible to extend the number of rows or columns using the Editor-Field.\

When editing a cell and a typo occured in editing mode escape key or command-z restores original content of cell.\

Manual data entry is enabled/diabled globaly by issuing mtfAllowCellEditing pBool. Manual data editing is also governed on a column basis by "mtfSetExcludedFromEditing" See below.\

There is also an option to display a popUp list for a column. The user can choose from a list of values. Manual data editing and popUp lists can be set for individual columns.\

If mtfAllowCellEditing is true and "mtfSetPopUpList pColumn, pList" has been set for a column a popUp list instead of an input field opens. Navigation in list as usual: arrowKeys, scrollwheel, trackpad, etc.\

Typing when the popUp list is up will find matches and hilite the found string in red and the displayed items are reduced to the ones that have a partial match. Backspace deletes characters from the searchstring and shows the list of partial matches (expanding the list if more matches are found). Escape-key clears the search string and restores initial list in popUp display.\

A line has to be selected in order to change the cell upon leaving the cell. Selection of a line can be done by clicking a line or using the arrow keys. \

Double-clicking a line selects the line and closes editing mode.\

Hitting the return key will apply changes to the cell and leave edit mode. In popUp-list mode a line has to be selected to be applied upon return.\

Performance\

modTableField has been tested with 9 columns 5000 rows with good response\

150 columns and 1000 rows with a bit of slugginess. Depending on your hardware your mileage may vary.\

currently modTableField is for use on desktop systems. Not mobile.\

Livecode 7.x.x is slower for some operations, as of 7.0.2 rc 1 for 9 columns 2500 rows still give a decent experience.\

Precaution\

the group modTableField is locked since the sort button with the triangle moves around and changes the size of the group.\

If you manually change size and location of the modTableField unlock it, make your changes and lock it again.\

In case something goes wrong send "resizeControl" to group "modTableField 1" via e.g. the message box.\

If you change size and location by script a resizeControl script takes care of proper alignment/positioning. ModTableField has it's own resizeControl handler.\

Works well with the geometry manager.\

How it is set up\

modTableField consists basically of two fields: "fData" and "fLabels". Much of the API is just to hide some of the complexities of mTF.\

This means you can access data directly in modTableField by addressing field "fData" of group "modTableField 1" or the same with field "fLabels". Just remember it is tab delimited data in both fields. The usual things that work for fields work for these fields too.\

ModTableField tries its best to keep data and headers synchronized and consistent. But if you bypass it's API you are on your own.\

That said you could easily set up a script and e.g. colorize certain cells in defined rows depending on the values of other cells in that row.\

Colorization is maintained in sorting but is lost when data is overwritten. Custom sorts using Livecode's advanced sorting options are also easily done this way, see also mtrCustomSort message. \

modTableField_Helper \

is a substack. It opens in palette mode. You can use it to configure many settings of modTableField, you could also use the API-calls.\

License\

modTableField is currently free for personal and commercial use. If you use modTableField commercially I would ask you to inform me of the product(s) you use it for. The code is not locked and free for inspection. If you modify the code you have to put a notice that it is a modified version of modTableField. A notice at the top of the script of the main group is ok.\

Feel free to mail me regarding modTableField\

[email protected]\page \

\fs36 \cf0 Application Programming Interface (API)

\fs22 \

Commands you can direct to the modTableField group to change it.\

All examples reference group "modTableField 1". If you have only 1 modTableField on a card you can just copy\

the whole group and paste it onto the card. If you use two modTableFields on one card you have to give them unique names. \

\b0\fs26 \

\b0\fs24 \

mtfHeaderItemClicked will be sent when the user clicks into the header/label field.\

3 parameters are send along: the number of the column the user clicked on, the content of the item and the long name of the group.\

Currently these messages are use in the group script to show how they work. You can either use the handlers for your own \

use or delete the handlers from the group script and intercept the messages e.g. at the card level.\

example\

in e.g. card script:\

\b0 mtfHeaderItemClicked pColumnClicked, pItemContent, pGroupName\

\b0 \cf0 \cf2 "you clicked at column"\cf0 && pColumnClicked && \cf2 "which contains"\cf0 && pItemContent\

\b0\fs24 mtfHeaderItemClicked\

\b0\fs24 \

mtfDataItemClicked is send when the user clicks into a data cell.\

6 parameters are sent: the number of the column, the number of the line, the content of the cell and the long name of the group, pButtonNo is the number of the button, 1 = left button, 3 = right button, pRect is the rect of the cell where the click occurred.\ul \

\ulnone Content of course can be empty if the cell is empty. pButtonNo can be used to display a menu on right click, pRect helps to place the menu.\

example\

in e.g. card script\

\b0 mtfDataItemClicked pColumnClicked, pLineClicked, pItemContent\

\b0 \cf0 \cf2 "you clicked at column"\cf0 && pColumnClicked && \cf2 "and line number"\cf0 && pLineClicked && \cf2 "which contains"\cf0 && pItemContent\

\b0\fs22 mtfDataItemClicked\

\b0\fs24 \

mtfUserChangedHilitedLine is sent when the user changes the selected line of the data field by arrowkey navigation. pLIne is the hilitedLine after arrowKey presses, also the mtfMoveHilitedLine command will trigger the mtfUserChangedHilitedLine message to be sent.\

NOTE: the data field must have focus for the arrowKey to work. Even if a line is hilited that does not mean the field has focus. Then the user must click into the field to give it focus.\

example\

in e.g. card script\

\b0 mtfUserChangedHilitedLine pLine\

\b0 \cf0 \cf2 "User changed hilitedLine "\cf0 & pLine && \cf4 the\cf0 \cf4 milliseconds\cf0 \cf4 into\cf0 \cf4 field\cf0 \cf2 "fRes"\

\cf0

\b0 \cf0 \cf2 "mtfGetLine"\cf0 \cf4 to\cf0

\b0 \cf0 \cf2 "modtablefield 1"\cf0 \cf4 with\cf0 pLine\

\b0 \cf4 not\cf0 (\cf4 the\cf0 \cf4 result\cf0 \cf4 contains\cf0 \cf2 "error"\cf0 )

\b0

\b0 \cf0 cr & \cf4 the\cf0 \cf4 result\cf0 \cf4 after\cf0 \cf4 field\cf0 \cf2 "fRes"\cf0 \

\b0\fs22 mtfUserChangedHilitedLine\

\b0\fs22 \

mtfIconChanged is sent when the user has double-clicked an icon = image set as imageSource in a cell.\

pColumn is the number of the column, pRow is the number of the row = line, pCellContent is the content of the cell

\b0 changes were made to the content due to user action, pGroupLongID is the long name of the group from which this message originated. Useful if you want to customize mtf. Icons currently use the first byte of a cell. If the first byte = char is neither 0 or 1 then 0 or 1 will be prepended to the text of the cell. Here data is changed when using Icons. If the cell is empty its value will be set to 0 or 1.\

Note: If allowEditing for the data field is false (not the individual exclusion of columns) Icons are not accessible to the user by double-clicking, the developer can provide a toggle mechanisme with the mtfDataItemDoubleClicked message\

example \

e.g. in card script\

\b0 mtfIconChanged pColumn, pRow, pCellContent, pGroupLongName\

\b0 \cf0 \cf2 "a mouseDoubleUp occurred in column"\cf0 && pColumn && \cf2 "in row"\cf0 && pRow && \\\

\cf2 "the cell content is:"\cf0 && pCellContent && \cf2 "sent by group"\cf0 && pGroupLongName\

\b0\fs22 mtfIconChanged\

\b0\fs22 \

mtfCustomSort is sent when user clicks in column header whose sorting has been set to "custom". This allows to access the versatile custom sort of LIvecode.\

pColumn is the column that is clicked, pFieldShortID is the short id of the field to sort (fData), pGroupShortID is the short id of the group that owns the data field, pWhichWay indicates the sort order that is given by the sort triangle in the header field. It is the way the custom sort should be carried out to be in sync with the triangle. The sort is on the lines of the data field. What you sort is up to you. Remember it is a tab-delimited field. Of course this also gives you the power to sort all kind of unwanted sorts. Here you are on your own. If you stick to sorting lines you can always restore the sort by e.g. your record number which is recommended that you always provide. But sorting data within a line will probably break your data.\

If there is no handler to handle mtfCustomSort the sort icon will not change and the data of the column is not sorted, if there is a handler but the sort does not affect the column (keywords not contained in column) the sort triangle will toggle although nothing is sorted.\

example\

e.g in card script of button script, see example how to forward the message in card script\

this assumes there is low, normal or high in column 6 (priority). No easy way to sort by severity other than by a custom sort.\

\b0 mtfCustomSort pColumn, pFieldShortID, pGroupShortID, pWhichWay\

\b0 pColumn = \cf2 6\cf0

\b0

\b0 pWhichWay = \cf2 "ascending"\cf0

\b0

\b0 \cf0 \cf4 lines\cf0 \cf4 of\cf0 \cf4 field\cf0 \cf5 id\cf0 pFieldShortID \cf4 of\cf0

\b0 \cf0 \cf5 id\cf0 pGroupShortID \cf4 ascending\cf0 \cf4 numeric\cf0 \cf4 by\cf0 sortPriority(\cf4 each\cf0 ,pColumn)\

\b0

\b0 \cf0 \cf4 lines\cf0 \cf4 of\cf0 \cf4 field\cf0 \cf5 id\cf0 pFieldShortID \cf4 of\cf0

\b0 \cf0 \cf5 id\cf0 pGroupShortID \cf4 descending\cf0 \cf4 numeric\cf0 \cf4 by\cf0 sortPriority(\cf4 each\cf0 ,pColumn)\

\b0

\b0

\b0

\b0\fs20 mtfCustomSort\

\b0

\b0 sortPriority pLIne, pCol\

\cf0

\b0 \cf0 \cf4 the\cf0 \cf5 itemDelimiter\cf0 \cf4 to\cf0 \cf4 tab\

\cf0

\b0 \cf0 \cf4 item\cf0 pCol \cf4 of\cf0 pLIne \cf4 into\cf0 tPriority\

\b0 tPriority\

\b0 \cf2 "Low"\

\cf0

\b0 \cf0 \cf2 1\

\cf0

\b0 \cf0

\b0 \cf2 "Normal"\

\cf0

\b0 \cf0 \cf2 2\

\cf0

\b0 \cf0

\b0 \cf2 "High"\

\cf0

\b0 \cf0 \cf2 3\

\cf0

\b0 \cf0

\b0

\b0 \cf0 \cf2 0\

\cf0

\b0

\b0 sortPriority\

\cf0 \

\b0\fs22 \

sent when allowEditing is set to false. Sent when user doubleClicks over a cell. pColumnClicked is column number. pLineClicked is rowNumber. pCellContent is content of cell. pGroupLongName is the long name from where the message originated.\

Usefull if the developer does not want to allow direct editing of data but wants to provide a means to selectively present a subset of the data for further processing.\

If allowEditing is false icons are not accessible to the user by double-clicking, the developer can provide a toggle mechanisme with this message\

example\

\b0 mtfDataItemDoubleClicked pColumnClicked, pLineClicked, pCellContent, pGroupLongName\

\b0 \cf0 \cf2 "doubleClick in "\cf0 & \cf2 "column"\cf0 && pColumnClicked & \cf2 " row "\cf0 & pLineClicked & \cf4 cr\cf0 & \\\

\cf2 "cell content "\cf0 & pCellContent & \cf4 cr\cf0 & \cf2 "long name of group "\cf0 & pGroupLongName \cf4 into\cf0 \cf4 field\cf0 \cf2 "fRes"\

\b0 mtfDataItemDoubleClicked\

\b0\fs22 \

sent when allowEditing is set to false. Sent when user doubleClicks over a line. pColumnClicked is column number. pLineClicked is rowNumber. pLineContent is content of the line in tab delimited format. pGroupLongName is the long name from where the message originated.\

Usefull if the developer does not want to allow direct editing of data but wants to provide a means to selectively present a subset of the data for further processing.\

example\

\b0 mtfDataLineDoubleClicked pColumnClicked, pLineClicked, tLineContent, pGroupLongName\

\b0 \cf0 \cf2 "doubleClick in "\cf0 & \cf2 "column"\cf0 && pColumnClicked & \cf2 " row "\cf0 & pLineClicked & \cf4 cr\cf0 & \\\

\cf2 "line content "\cf0 & tLineContent & \cf4 cr\cf0 & \cf2 "long name of group "\cf0 & pGroupLongName \cf4 into\cf0 \cf4 field\cf0 \cf2 "fRes"\

\b0 mtfDataLineDoubleClicked\

\b0\fs22 \

sent when the user double-clicks into an editable cell before the editing field opens. Useful to set e.g. a popUp-list depending on other data to let user choose from for data entry. pShortGroupName is the short name of the mtf-Group\

If you use it to set a popUp list on the fly the new popUp list is persistent. I.e. you set a popUp-list for a column that had no popUp-list before.\

example\

\b0 mtfDoubleClickInEditableCell pColumnClicked, pLineClicked, pItemContent, tOwnerName\

\b0 \cf0

\b0 pColumnClicked = \cf2 1\cf0

\b0

\b0 \cf0 \cf2 "one,two,three,four"\cf0 \cf4 into\cf0 tPopUpOnTheFly\

\b0 \cf0 \cf4 comma\cf0 \cf4 with\cf0 \cf4 cr\cf0 \cf4 in\cf0 tPopUpOnTheFly\

\b0 \cf0 \cf2 "mtfSetPopUpList"\cf0 \cf4 to\cf0

\b0 \cf0 \cf2 "modTableField 1"\cf0 \cf4 with\cf0 pColumnClicked, tPopUpOnTheFly\

\b0

\b0 mtfDoubleClickInEditableCell\

\b0\fs24 sent when user right-clicks in data. Parameters indicate the column, the row, cell content, long name of mtf group and the rect of the cell where the click occured. This can be useful to show a popUp on right-click.\

\b0\fs24 \

sent when user has dragged manually a line and reordered the data. pFromWhere is a number indicating the line number of the line dragged, pToWhere is the new line number of the dragged line. pLongGroupName is the long name of the mtf group\

\b0\fs22 \cf0 \ulnone \

\b0\fs24 \

moves hiliteLIne to next or previous line. pDirection is either prev or next. Useful when giving the user the option to move the hilitedLine by e.g a button.\

This will resut in the mtfUserChangedHilitedLine pLine message to be dispatched.\

When the hilitedLIne is empty = no line is hilited the first line will be selected and a mtfArrowKeyChangedLine message will be triggered.\

example\

\b0 \cf0 \cf2 "mtfMoveHilitedLIne"\cf0 \cf4 to\cf0

\b0\fs22 \cf0 \cf2 "modTableField 1"\cf0 \cf4 with\cf0 \cf2 "next"\cf0 \

if there is a parameter error the result will contain \cf2 "error, wrong parameter. Next or Prev"\cf0 \

\b0\fs22 \ulnone \

\b0 \cf0 mtfDataWasChangedByUser is sent when the user changed the text of the text input field.\

5 parameters are sent: the changed text that is saved into the cell, the original text of the cell, the number of the column clicked, the number of the line clicked and the name of the group in the form of: group "theLongNameOfGroup"\

example\

in e.g. card script\

\b0 mtfDataWasChangedByUser pNewText, pOldText, pColumnClicked, pLineClicked, pGroupName\

\b0 \cf0 \cf2 "User changed data in column "\cf0 & pColumnClicked & \cf2 " and line "\cf0 & pLIneClicked & \cf4 cr\cf0 & \cf2 "new text is "\cf0 & \cf4 quote\cf0 & pNewText \\\

& \cf4 quote\cf0 & \cf2 " old text was "\cf0 & \cf4 quote\cf0 & pOldText & \cf4 quote\cf0 & \cf4 cr\cf0 & \cf4 cr\cf0 & \cf2 "in data of "\cf0 & pGroupName \cf4 into\cf0 \cf4 field\cf0 \cf2 "fRes"\cf0 \

\b0 mtfDataWasChangedByUser\

\b0 \

\fs24 \cf0 \ulnone \

Hint:\

after changing data with one of the following commands you may want to adjust the widths of the columns to their content\

by issuing\

\b0 \cf0 \cf2 "mtfAdjustToWidthOfContent"\cf0 \cf4 to\cf0

\b0\fs22 \cf0 \cf2 "modTableField 1"\cf0 \

Note: LC 7.x.x is a lot slower to adjust to width of columns. Data sets with > 2500 rows will be noticeable slower to respond to mtfAdjustToWidthOfContent\

\b0\fs24 \

loads header and data. It is assumed that the first line of the variable pData contains in tab delimited\

format the header you choose. Line 2 to the end of pData is expected to also be tab delimited and is \

put into the data part of the modifield table field.\

Header and data are probed for consistency: if header has more columns than data data will get columns appended. If data has more columns than header header will get columns appended\

example:\

\b0 \cf0 \cf2 "mtfLoadHeaderAndData"\cf0 \cf4 to\cf0

\b0\fs22 \cf0 \cf2 "modTableField 1"\cf0 \cf4 with\cf0 myVar\

\b0\fs22 \

loads header names. It is assumed that the first and only line of the variable pData contains in tab delimited\

format the header names you choose. It is put into the header field. This is what will be displayed in the header field. \

example:\

\b0 \cf0 \cf2 "mtfLoadHeader"\cf0 \cf4 to\cf0

\b0 \cf0 \cf2 "modTableField 1"\cf0 \cf4 with\cf0 myVar\

\b0\fs24 \

assigns a label to a column. A label is not visible but only an internal reference to the column. It has to be set explicitly with this command.\

pLabels is a comma delimited list of labels for the columns in the order of the columns.\

Useful if you want to address a column by an internal name, e.g. equal to the column name in a database, but you want to display a more user friendly name for the column in the header.\

example:\

\b0 \cf0 \cf2 "mtfLoadHeaderLabels"\cf0 \cf4 to\cf0

\b0\fs22 \cf0 \cf2 "modTableField 1"\cf0 \cf4 with\cf0 myVar\

\b0\fs22 \

loads data. It is assumed that variable pData contains in tab delimited\

format the data you choose, lines are return delimited. All the data of the variable is put into the data field.\

When importing data is analysed to determine the maximum number of tabs in any line and fills up tabs in lines that have less than maximum.\

example:\

\b0 \cf0 \cf2 "mtfLoadData"\cf0 \cf4 to\cf0

\b0 \cf0 \cf2 "modTableField 1"\cf0 \cf4 with\cf0 myVar\

\b0\fs22 \

loads pData without "sanitizing" it. That means data is dumped as is into the the data field. If data is not correctly formatted with regards to number of columns and tabbed data bad things can happen.\

Mainly introduced to increase loading speed for large data sets in LC 7.x.x. You are on your own. Don't complain. If you do this on an modTableField without headers set (e.g. after reset) you may want to load headers first.\

example\

\b0 \cf0 allMyCorrectlyFormattedData \cf4 into\cf0 tData\

\b0 \cf0 \cf2 "mtfLoadRawData"\cf0 \cf4 to\cf0

\b0 \cf0 \cf2 "modTableField 1"\cf0 \cf4 with\cf0 tData\

\b0\fs22 \

appends data to the the end of the data field. pData is assumed to be tab delimited within the line and lines\

are return delimited. Obviously pData should not contain more columns than previously loaded data. Missing tabs are added to match previous data if needed.\

example:\

\b0 \cf0 \cf2 "mtfAppendData"\cf0 \cf4 to\cf0

\b0 \cf0 \cf2 "modTableField 1"\cf0 \cf4 with\cf0 myVar\

\b0\fs22 \

appends pData without "sanitizing" it. That means data is dumped as is into the the data field. If data is not correctly formatted with regards to number of columns and tabbed data bad things can happen.\

Mainly introduced to increase loading speed for large data sets in LC 7.x.x. You are on your own. Don't complain.\

example\

\b0 \cf0 allMyCorrectlyFormattedData \cf4 into\cf0 tData\

\b0 \cf0 \cf2 "mtfAppendRawData"\cf0 \cf4 to\cf0

\b0 \cf0 tTarget \cf4 with\cf0 tData\

\b0\fs22 \

adds an empty line to existing data. Missing tabs are added to match previous data.\

example\

\b0 \cf0 \cf2 "mtfAddEmptyLine"\cf0 \cf4 to\cf0

\b0 \cf0 \cf2 "modTableField 1"\cf0 \

\b0\fs22 \

puts pData into column pColumn of line pLine, put empty into pData if you want an empty cell.\

pData is one line of data without tabs. If the cell is filled mTFsetCell will overwrite it. pColumn can be the name of a column, the number of a column or the label of a colum. pLine is the line number of the cell.\

example\

\b0 \cf0 \cf2 4\cf0 \cf4 into\cf0 tColumn\

\b0 \cf0 \cf2 1\cf0 \cf4 into\cf0 tLIne\

\b0 \cf0 \cf4 the\cf0 \cf4 milliseconds\cf0 \cf4 into\cf0 tData\

\b0 \cf0 \cf2 "mtfSetCell"\cf0 \cf4 to\cf0

\b0 \cf0 \cf2 "modTableField 1"\cf0 \cf4 with\cf0 tData, tColumn, tLine\

\b0 \cf0 \cf4 the\cf0 \cf4 result\cf0 \cf4 into\cf0 \cf4 field\cf0 \cf2 1\cf0 \

the result contains "error, xxx" if pLine or pColumn are not correctly indicated, you might want to check the result for "error".\

pLine is the currently displayed line, possibly sorted.\

\b0\fs22 \

where pData is a comma delimited list of \

\cf2 text,numeric,dateTime,systemDate,international,custom,none\cf0 . One per column.\

\b0 sorting ASCII text ignoring international ACII character like accented chars and umlaute.\

\b0 sorts text taking into account accented chars\

\b0 sorts numbers\

\b0 sort english dateTime\

\b0 sorts according to the date format of the computer it is run on\

\b0 sends a mtfCustomSort message and the developer takes care of sorting, see mtfCustomSort\

\b0 excludes the column from sorting by clicking in the column header\

example\

\b0 \cf0 \cf2 "mtfSetSortType"\cf0 \cf4 to\cf0

\b0 \cf0 \cf2 "modTableField 1"\cf0 \cf4 with\cf0 tSortTypes\

example for a list with 9 columns. Column 1 is numeric data, column 2 to 8 system dateTime and column 9 is international text\

\b0 \cf0 \cf2 "numeric,systemDate,systemDate,systemDate,systemDate,systemDate,systemDate,systemDate,international"\cf0 \cf4 into\cf0 tSortTypes\

you could also provide a list with just the columns specified that should not sort text\

\b0 \cf0 \cf2 "numeric"\cf0 \cf4 into\cf0 tSortTypes\

will only sort on the first column numeric, the rest is sorted text\

\b0 if you don't provide mtfSetSortType modTableField looks at the column in the first line of the data to try to determine the sort type. If it fails to detect a non-text format it defaults to text type sorting.\

\b0\fs22 \cf0 returns a comma separated list of sort types of all columns. I no sort type has been set it will return just commas = empty items\

\cf0 \

example\

\b0 \cf0 \cf2 "mtfGetSortType"\cf0 \cf4 to\cf0

\b0 \cf0 \cf2 "modTableField 1"\

\b0 \cf0 \cf4 the\cf0 \cf4 result\

\cf0 \

\b0\fs22 sorts a column by script. Works also if manual sorting by clicking into the header is disabled.\

pColumn is either a number, a Header or a label for the column. pColumn must be indicated\

pSortType is optional and one of: \

\b0 sorting ASCII text ignoring international ACII character like accented chars and umlaute.\

\b0 sorts text taking into account accented chars\

\b0 sorts numbers\

\b0 sort english dateTime\

\b0 sorts according to the date format of the computer it is run on. \

\b0 clicking on a header column with sort type "custom" will send a mtfCustomSort messages, see above\

\b0 will prevent sorting on that column\

if pSortType is not provided modTableField first looks if mftSortType has been set for the column and uses that. Otherwise modTableField tries to determine the sortType as date, numeric or text from the first line of data, it defaults to text.\

pUpDown is optional and either "ascending" or "descending". If not provided it defaults to "ascending"\

If you want to use the sortTypes set by mtfSetSortTypes but want to do a descending sort provide an empty pSortType\

example\

\b0 \cf0 \cf2 "1"\cf0 \cf4 into\cf0 pColumn\

\b0 \cf0 \cf2 "numeric"\cf0 \cf4 into\cf0 pSortType\

\b0 \cf0 \cf2 "ascending"\cf0 \cf4 into\cf0 pUpDown\

\b0 \cf0 \cf2 "mtfSortColumn"\cf0 \cf4 to\cf0

\b0 \cf0 \cf2 "modTableField 1"\cf0 \cf4 with\cf0 pColumn, pSortType, pUpDown\

\b0 \cf0 \cf4 the\cf0 \cf4 result\

\cf0 \

the result indicates possible errors.\

\b0\fs24 \

sorts a colum pColumn in the sort order of items provided in pList in ascending or descending way (indicated in pWichWay). This overrides any sort settings for the column, but will not change those settings e.g. allowSort or sortType. pColumn can be number, name or label of column. Internally a custom sort is used. It is intended to provide an easy way of performing a custom sort.\

If a cell of pColumn is empty or not contained in pList it will be sorted after the items of pList when sorting ascending. Inversely when sorting descending it will be at top. The example assumes that in column 6 each record is classified according to "High,Norma,Low". A text sort would sort alphabetically ascending: High Low Normal. To get the sort order as: Normal High Low use a list.\

example\

\b0 \cf0 \cf2 6\cf0 \cf4 into\cf0 tColumn\

\b0 \cf0 \cf2 "Normal,High,Low"\cf0 \cf4 into\cf0 tList\

\b0 \cf0 \cf2 "ascending"\cf0 \cf4 into\cf0 tWhichWay\

\b0 \cf0 \cf2 "mtfSortList"\cf0 \cf4 to\cf0

\b0 \cf0 \cf2 "modTableField 1"\cf0 \cf4 with\cf0 tColumn, tLIst, tWhichWay\

\b0 \cf0 \cf4 the\cf0 \cf4 result\cf0 \

the result indicates possible errors.\

\b0\fs22

\b0\fs22 \

s

\fs24 et Icons for a column that are images used as imageSource of text. These Icons come in pairs so the user can click on them and toggle the icons. Icons use the first char of a cell to indicate its state. If a cell is empty 1 or 0 will be filled. If a cell has content 0 or 1 will be prepended to the text. This is the only time actual data is changed. You provide the short image name i.e. just the name of the image as parameter. pNullName is the name of the image used for 0 or false state, pOneName is the name of the image that signals the 1 or true state.\

Icons will be set on all cells of a column. At the same time the "editable" of the column will be set to false to allow double-clicks to toggle state of icon. When the user changed the state of an icon a "mtfIconChanged" message is sent. It is probably wise to use one dedicated column for an Icon, though not necessary. Please note that if you assign images as icons these images have to be around when you copy your modTableField to another stack. You might want to copy those images into group "modTableField" to be sure. Or copy them into a substack of the stack where you use modTableField.

\b0 This will explain how Livecode resolves Icon ids when looking for images used as icons or imageSource.\

\fs22 example\

\b0 \cf0 \cf2 6\cf0 \cf4 into\cf0 pColumn\

\b0 \cf0 \cf2 "iRed"\cf0 \cf4 into\cf0 pNullName\

\b0 \cf0 \cf2 "iGreen"\cf0 \cf4 into\cf0 pOneName\

\b0 \cf0 \cf2 "mtfSetIcons"\cf0 \cf4 to\cf0

\b0 \cf0 \cf2 "modTableField 1"\cf0 \cf4 with\cf0 pColumn, pNullName, pOneName\

the result contains possible errors (not two images referenced, images can not be found)\

\b0\fs24 sets the icon for one cell in a column that has icons set. Useful if you have an empty cell that is filled afterwards and should display the icon of the rest of the column\

example\

\b0 \cf0 \cf2 8\cf0 \cf4 into\cf0 pColumn\

\b0 \cf0 \cf2 3\cf0 \cf4 into\cf0 pRow\

\b0 \cf0 \cf2 "mtfSetOneIcon"\cf0 \cf4 to\cf0

\b0 \cf0 \cf2 "modTableField 1"\cf0 \cf4 with\cf0 pColumn, pRow\

\b0 \cf0 \cf4 the\cf0 \cf4 result\cf0 \

\b0\fs22 removes icons from column pColumn, in columns set up for just icons by either only containing false or true or 0 or 1 mtfSetIconToEmpty will leave 0 or 1 in the cells. In columns where there is more text the prepended char and space will be removed and the cellls will be restored to their original content.\

example\

\b0 \cf0 \cf2 8\cf0 \cf4 into\cf0 pColumn\

\b0 \cf0 \cf2 "mtfSetIconToEmpty"\cf0 \cf4 to\cf0

\b0 \cf0 \cf2 "modTableField 1"\cf0 \cf4 with\cf0 pColumn\

\b0\fs22 \cf2 \

\fs24 \cf0 Set state of an icon of a cell by script. The column has to have Icons set for this to work, Error otherwise. pColumn is the column number, pRow is the row number = line number, pState is one of false or true or 0 or 1. Otherwise error. If pState is the current state of the icon then no change is made. No mtfIconChanged message is sent if icon was changed by script. To get the state of the icon issue a mtfGetIconState command and check the result, either 0 or 1.\

\fs22 example\

\b0 \cf0 \cf2 8\cf0 \cf4 into\cf0 pColumn\

\b0 \cf0 \cf2 1\cf0 \cf4 into\cf0 pRow\

\b0 \cf0 \cf2 1\cf0 \cf4 into\cf0 pState\

\b0 \cf0 \cf2 "mtfsetIconToState"\cf0 \cf4 to\cf0

\b0 \cf0 \cf2 "modTableField 1"\cf0 \cf4 with\cf0 pColumn, pRow, pState\

check result for errors\

\b0\fs24 \

get state of Icon for a cell. Returns 0 or 1. The result contains either "error" and a description or the value of the state.\

example\

\b0 \cf0 \cf2 8\cf0 \cf4 into\cf0 pColumn\

\b0 \cf0 \cf2 1\cf0 \cf4 into\cf0 pRow\

\b0 \cf0 \cf2 "mtfGetIconState"\cf0 \cf4 to\cf0

\b0 \cf0 \cf2 "modTableField 1"\cf0 \cf4 with\cf0 pColumn, pRow, pState\

\b0 \cf0 \cf4 the\cf0 \cf4 result\cf0 \cf4 into\cf0 \cf4 myState\cf0 \

\b0\fs24 \

Excludes a column in pList from user double-Click into Icon cell to toggle Icon. You can pass multiple columns in pList as in "2,8" disabling user-switchable for column 2 and 8. You may also pass header-names or labels as literals in pList.\

If cell editing is set to false (mtfAllowCellEditing) for the whole data field then a user double-click will not toggle the icon regardless of mtfSetDisableIconSwitch and a mtfDataItemDoubleClicked message will be sent.\

mtfSetIconToState is not affected by mtfSetDisabledIconSwitch i.e. you can still set the state of the icon by script.\