Merge pull request livecode#1252 from jameshale/patch-3

peter-b · web-flow · commit 23bba8443d68 · 2016-06-30T14:02:17.000+01:00
[[ Bug 17895 ]] Make dgText[true] less ambiguous
diff --git a/Documentation/dictionary/datagrid.lcdoc b/Documentation/dictionary/datagrid.lcdoc
@@ -1650,31 +1650,41 @@ making life easier for some folks there is a dgText property. The dgText
 property always reflects the same value as the dgData but in tab
 delimited form. pText is assumed to be a collection of data where each
 row is delimited by the return character and each item is delimited by a
-tab. You can map each item of each line in pText to a particular key in
+tab. 
+
+You can map each item of each line in pText to a particular key in
 an array (and thus a table column) by passing in true for
 pFirstLineContainsHeaders. If true then the data grid will extract the
-first line of pText and use the values for the internal key/column
-names. The default value for pFirstLineContainsHeaders is false. If you
-set the dgText of a data grid table then all data will be imported and
-assigned to the appropriate column depending on the value of
+first line of pText and match the values for existing internal key/column
+names. 
+
+The default value for pFirstLineContainsHeaders is false. 
+
+If you set the dgText of a data grid table then all data will be imported 
+and assigned to the appropriate column depending on the value of
 pFirstLineContainsHeaders. Normally you should set this property to true
 and provide the header that maps each item of each line to a specific
-column. Note that if pFirstLineContainsHeaders is true then the columns
-must already exist in your data grid table in order to be displayed. If
-pFirstLineContainsHeaders is false then the columns property of the data
+column. 
+
+>*Note:* that if pFirstLineContainsHeaders is true then the columns
+>must already exist in your data grid table in order to be displayed. 
+>Setting pFirstLineContainsHeaders to true does not create the headers for you.
+
+If pFirstLineContainsHeaders is false then the columns property of the data
 grid is used for mapping. For Example, the first item of a line of pText
 would be assigned to the column that appears on the first line in the
 columns property of the data grid. If line 1 of pText contains more
 items than there are columns in the table then new columns are added.
-Any new columns are named "Col 1", "Col 2", etc. If you set the dgText
-property of a data grid form then the data will be imported but it is up
-to you to modify your Row Template Behavior to display the imported data
-correctly. If pFirstLineContainsHeaders is false then each item of each
-line in pText will be named "Label X" (where X is the item number) in
-the array that is passed to FillInData. When retrieving the dgText
-property you can include the column names in the first line by setting
-pIncludeColumnNames to true.
+Any new columns are named "Col 1", "Col 2", etc. 
+
+If you set the dgText property of a data grid form then the data will be 
+imported but it is up to you to modify your Row Template Behavior to 
+display the imported data correctly. If pFirstLineContainsHeaders is 
+false then each item of each line in pText will be named "Label X" 
+(where X is the item number) in the array that is passed to FillInData. 
 
+When retrieving the dgText property, setting the pIncludeColumnNames to true
+will cause the column names to be included in the first line.
 
 Name: dgHilitedIndexes synonyms: dgHilitedIndex type: property
 Associations: datagrid
diff --git a/notes/bugfix-17895.md b/notes/bugfix-17895.md
@@ -0,0 +1 @@
+# Documentation for setting dgText [TRUE] is ambiguous

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	`+# Documentation for setting dgText [TRUE] is ambiguous`