Print grid
TreeGrid documentation
User can print grid by clicking to Print button on toolbar.
TreeGrid opens new window and renders here the grid again and calls standard window.
print method to show printing dialog and print the grid. The printing process itself cannot be controlled by JavaScript at all.
In TreeGrid print menu it is possible to choose which columns or rows to print and set various printing options.
See
Configuration menu for basic settings or
Print menu for special settings.
The grid rendered for printing does not show scrollbars, but displays the whole grid. It does not show right side pager. All other parts visibility can be controlled by
CanPrint attributes.
More changes for printing can be done by <
Media><M
Media='
Print' ... /><Media>.
Because TreeGrid uses background images, a user must have permitted "Printing background images" in his browser to successfully print the grid.
new 7.1 chg 12.1 upd 13.2 <Cfg> int
PrintLocation
[3/0]
Where the printable grid will be shown
0 - new window with PrintWindowProp properties
1 - new window with the same properties as the main window, ignores PrintWindowProp
2 - into the main tag instead of actual grid, like with NoVScroll / NoHScroll settings, ignores PrintCSS, PrintHead and PrintWindowProp
3 - into the same page, instead of the page content, ignores PrintCSS, PrintHead and PrintWindowProp
4 -
(new 13.2) into the same page, but hides page content. Similar to 3, but more safe. Cannot be used if the page contains absolutely positioned content.
Since 12.1 default value changed to 3 in top window or to 0 in frame / iframe.
To modify other page content for printing use
OnPrintFinish and restore the original in
OnPrintClose.
new 7.1 <Cfg> int
PrintPrint
[1]
How the grid will be printed
0 - nothing will be shown
1 - print dialog will be shown
2 - alert for manual printing will be shown, remember to permit printing icons in the browser by
PrintLocation.
3, 4 - reserved
5 - print preview in IE will be shown if permitted the ActiveX, otherwise like 1
6 - print preview in IE will be shown if permitted the ActiveX, otherwise like 2
new 7.1 <Cfg> string[ ]
PrintGrids
To print more grids at once.
A list of grid ids, comma separated, to print them all in one print job, at the same page.
Set individual PrintPrefix / PrintPostfix to separate or structure the grids on page.
The PrintLocation, PrintPrint, PrintCSS, PrintHead and PrintWindowProp are read from the actual grid, the other printing properties from the individual grids.
If set
PrintLocation = 2, all grids are replaced inside their main tags, for other options are printed in the listed order.
If you use
PrintPageHeight to split the grid vertically, you should permit it only in the main grid (with PrintGrids attribute) and the other grid(s) should have constant height.
In this case this constant height set to the
PrintPaddingHeightFirst or
PrintPaddingHeightLast attribute of the main grid to preserve space for the other grid(s).
new 6.0 upd 6.7 <Cfg> int
PrintCols
[2]
If and which menu will be shown before printing.
0 - no menu
1 - menu with columns to select which columns will be printed. Only columns with
CanPrint='1' and
'2' are listed.
2 -
(new 6.7) menu with column and also with printing options
See
Configuration menu for basic settings or
Print menu for special settings.
upd 6.7 <Cfg> int
PrintRows
[50] Saved to cookies, to not load it, set PrintLap='1'
For how many rows will be displayed and updated progress bar. Displaying progress bar suppresses also message about slow script.
0 never shows progress bar.
Too small value can slow down the printing.
It is used also as page length for
PrintPageBreaks.
Since 6.7 it can be changed via print menu and is saved to cookies.
new 7.1 <Cfg> int
PrintCount
Expected count of rows to print to show it in progress dialog.
Usable especially when set
PrintLoad = 1.
Can be set dynamically in
OnPrintInit API event.
<Cfg> string
PrintPrefix
HTML code added in front of TreeGrid when printing, only before the first page.
<Cfg> string
PrintPostfix
HTML code added behind TreeGrid when printing, only after the last page.
new 7.1 <Cfg> string
PrintHead
HTML code added into the print page <head> tag. Useful for adding meta tags to the page.
Only for
PrintLocation = 0 or
1
<Cfg> string
PrintCSS
Url of CSS style sheet for printing used instead of default CSS style sheet
Only for
PrintLocation = 0 or
1
new 10.0 <Cfg> string
PrintAddCSS
Url of CSS style sheet added for printing. Used with
PrintCSS or with default CSS styles. Can be used also to add Gantt style if required.
Only for
PrintLocation = 0 or
1
<Cfg> string
PrintWindowProp
Properties of printing window (the third attribute to window.open)
Only for
PrintLocation = 0
Choosing items to print
Shared for printing and printing to PDF.
new 6.0 upd 9.0 <I> int
CanPrint
[0/1/2]
If the row will be printed.
0 - never,
1 - once if visible,
2 - on every page (only for fixed and space rows) if visible,
3 -
(new 7.1) once always,
4 -
(new 7.1) on every page (only for fixed and space rows) always
5 -
(new 9.0) on every col page (only for space rows) if visible,
6 -
(new 9.0) on every page and col page (only for space rows) if visible,
7 -
(new 9.0) on every col page (only for space rows) always,
8 -
(new 9.0) on every page and col page (only for space rows) always,
By default
Toolbar and
Panel have
0,
Header has
2 and all other rows have
1.
new 6.0 upd 9.0 <C> int
CanPrint
[0/1]
If the column will be printed.
0 - never,
1 - once if visible,
2 -
(new 9.0) on every page if visible,
3 -
(new 9.0) once always,
4 -
(new 9.0) on every page always
By default
Panel has
0 and other columns
1.
More changes for printing can be done by <
Media><M
Media='
Print' ... /><Media>.
new 7.1 <cell> int
CanPrint
[1]
If the cell will be printed. Useful especially for Space cells.
0 - never,
1 - if visible,
2 - always.
new 9.0 <cell> int
PrintHPage
[0]
Only for Space rows with CanPrint>=5.
To which horizontal page will be the cell printed.
0 means every page,
1 the first page,
2 the second page, ...
If there are fewer pages than the value, the cell will be printed at the last page.
new 9.0 <I> int
PrintHeight
Minimal height of the row when printed. In pixels. If not set, actual row height is used.
Useful especially variable height rows or rows with nested grid.
new 9.0 <Cfg> int
PrintVarHeight
[1]
0 - All columns are printed as they are, without external height calculation. It can lead to higher pages than expected, if rows contain multiline cells.
1 - If there is printed at least one column with
VarHeight>=1, it recalculates height of all rows for printing. It can slow down printing and print dialog recalculating, but preserves page height.
2 - Like
1 and also ignores row
MaxHeight attribute to print the whole content of all multiline cells.
new 7.0 <C> int
VarHeight
[0]
Set it to
1 (or
2) to columns containing multiline cells to let their height to calculate dynamically to preserve page height. Only with
PrintVarHeight>=1.
The VarHeight attribute also controls shrinking cell height when column width is increased, see
VarHeight.
new 9.0 <C> int
PrintWidth
Width of the column when printed. In pixels. If not set, actual column width is used.
Useful especially for relative width columns.
renamed 9.2 <C> int
Block
[0]
Controls splitting columns among horizontal pages, it is useful especially if there are some cells spanned to or from other columns.
If set to > 0, it is the group the column belongs to. Create groups that contain the spanned cells. The groups must be continuous.
The group of columns is divided to more pages only if it is wider than the page width.
If spanned cell is split between printed pages, its content is printed to every page!
This attribute controls also dragging columns, see
Block.
Since 9.2 it was renamed from Group.
renamed 6.0 upd 6.7 <Cfg> bool
PrintExpanded
[0] Saved to cookies, to not load it, set PrintLap='1'
If prints all rows expanded.
If set to 0, only actually expanded rows prints their children.
Since 6.7 it can be changed via print menu and is saved to cookies.
new 6.7 <Cfg> bool
PrintFiltered
[0] Saved to cookies, to not load it, set PrintLap='1'
If prints all rows, including the hidden.
It can be changed via print menu and is saved to cookies.
new 9.0 <Cfg> bool
PrintSelected
[0] Saved to cookies, to not load it, set PrintLap='1'
If prints only selected rows, columns or cells.
Even if set, it always prints all rows and columns that cannot be selected.
new 7.1 upd 13.1 <Cfg> int
PrintLoad
[0]
Set to
1 in server paging or child paging to download all rows to be printed.
Since 13.1 if set to
2 it downloads all rows also if set
PrintSelected - useful if row selection is saved on server.
Be careful permitting this option, it will download all pages and optionally child pages, when set
PrintExpanded.
The count of rows is not known, so the progress dialog does not show correct values except set
PrintCount.
new 6.7 <Cfg> bool
PrintCheckboxes
[0]
For
1 it prints all checkboxes and radio buttons as standard HTML checkbox and radio button inputs instead of style images.
Useful when expected printing without background images.
new 7.1 upd 8.1 <Cfg> int
PrintIcons
[1]
For
0 it does not print cell side icons Calendar, Enum and Defaults. It still prints Sort, Filter, Expand and custom icons.
(Since 8.1) For -
1 it does not print Calendar, Enum and Defaults and custom icons. It still prints Sort, Filter, Expand.
new 9.0 <Cfg> bool
NoPrintTreeLines
[ ]
If set to
1, it does not show connecting lines in tree when printing, shows only expand / collapse buttons.
If empty, uses value of
NoTreeLines.
new 8.0 <Cfg> bool
PrintVisible
[0] Saved to cookies, to not load it, set PrintLap='1'
Only for Gantt chart. If set, it prints only visible part of the actually scrolled / zoomed Gantt chart (horizontally).
It can be changed via print menu and is saved to cookies.
new 8.0 chg 13.2 <Cfg> int
PrintGanttBackground
[1]
If prints global Gantt background, shown for attributes GanttBackground, GanttExclude, GanttBase, GanttFinish.
Since 13.0 if set to
2 or to
4, it prints background in <svg> to speed up the rendering.
It can cause problems for some PDF exporters.
Since 13.2 if set to
1 or
2 it prints the global background once on the grid background,
if set to
3 or
4 it prints the global background in every row background - more compatible but remarkably slower.
Since 13.2 the default value was set back to
1 because 2 has problems with PDF exporters.
new 13.2 <Cfg> int
PrintGanttRowHeight
[50]
Default height in pixels of all Gantt objects in grid when printing.
Default height of Gantt objects is 5000px when rendering, but in PDF it slows down the PDF, so it is reduced to row height.
Increase this value to maximal expected row height if exporting to PDF a Gantt with variable row heights (e.g. with type Lines).
Page size
Shared for printing and printing to PDF.
It is possible to split the printed grid horizontally and vertically to more pages.
The maximal size of page is set by PrintPageWidth - PrintPaddingWidth x PrintPageHeight - PrintPaddingHeight. If the grid is bigger, it is split to more pages.
Note, nested grid is never split to pages.
These settings do not affect the paper size, orientation and margins selected by a user in his printing dialog! JavaScript cannot control or even read these settings!
So a user must always select the same values twice, in TreeGrid print dialog and browser/system print dialog.
If there are printed empty pages between normal pages, it often helps increasing PrintPaddingHeight.
new 9.0 <Cfg> int
PrintPageWidth
[643] Saved to cookies, to not load it, set PrintLap='1'
Width of page for printing, in pixels.
If the printed chart is wider than this value, it is split to more pages horizontally.
The grid is always split between columns, only Gantt type column can be divided to more parts if set
PrintGanttSplit = 1.
Every page contains all columns with
CanPrint = 2 and next set of columns with
CanPrint = 1.
If the place for the next columns is less than 100 pixels, the grid is not split horizontally.
If set to
0, the printed chart is not split to pages horizontally. Also items for page width are hidden from print columns menu.
To only hide the Page width option from print columns menu, add <Lang><Text PrintWidth=""/></Lang>.
Value 643 corresponds with page A4 portrait, 96 DPI and 40mm margin.
Remember, this attribute cannot control the final printing page chosen by user in printing dialog!
new 9.0 <Cfg> int
PrintPageHeight
[971] Saved to cookies, to not load it, set PrintLap='1'
Height of page for printing, in pixels.
If the printed chart is higher than this value, it is split to more pages vertically.
The grid is always split between rows.
Every page contains all rows with
CanPrint = 2 and next set of rows with
CanPrint = 1.
If set to
0, the printed chart is not split to pages horizontally, except set
PrintPageBreaks. Also items for page height are hidden from print columns menu.
To only hide the Page height option from print columns menu, add <Lang><Text PrintHeight=""/></Lang>.
Value 971 corresponds with page A4 portrait, 96 DPI and 40mm margin.
new 9.0 <Cfg> int
PrintPageSize
[8] Saved to cookies, to not load it, set PrintLap='1'
Affects only TreeGrid print dialog (shown by PrintCols=2).
Selected item in Page sizes list, defined by <Lang><Text PrintPageSizes/></Lang>, by default in Text.xml
The PrintPageSizes attribute contains first character separated list as
"|name1|width1|height1|name2|width2|height2|name3|..."
The name is page size name shown in the list, width and height is the page size in millimeters. pixels = mm / 25.4 x DPI
When changed by a user in the print dialog, it recalculates
PrintPageWidth and
PrintPageHeight attributes accordingly.
PrintPageWidth = (PrintPageSize[width] - PrintMarginWidth) / 25.4 * PrintDPI
PrintPageHeight = (PrintPageSize[height] - PrintMarginHeight) / 25.4 * PrintDPI
If set PrintPageOrientation to
1 (landscape) it just swaps the width and height in PrintPageSize.
new 9.0 <Cfg> int
PrintPageOrientation
[0] Saved to cookies, to not load it, set PrintLap='1'
Affects only TreeGrid print dialog (shown by PrintCols=2).
The print page orientation - portrait or landscape.
If set to
1 (landscape), it just swaps width and height in
PrintPageSize.
new 9.0 <Cfg> int
PrintDPI
[96] Saved to cookies, to not load it, set PrintLap='1'
Affects only TreeGrid print dialog (shown by PrintCols=2).
DPI (PPI) ratio - pixels per inch.
Default value for most browsers is 96. Changing this value zooms the printed page, higher value = bigger page.
When changed by a user in the print dialog, it recalculates
PrintPageWidth and
PrintPageHeight attributes accordingly.
new 9.0 <Cfg> int
PrintDefaultDPI
[96]
Affects only TreeGrid PDF print dialog (shown by PrintCols=2 in PDF export).
Default PrintDPI value, used when PDFFitPage is changed to 0.
new 9.0 <Cfg> int
PrintMinDPI
[96]
Affects only TreeGrid PDF print dialog (shown by PrintCols=2 in PDF export).
Minimal PrintDPI value, used when PDFFitPage is changed to >0. If the value is less than 96, it permits stretching the grid width to fit the page. It should not be higher than 96.
new 9.0 <Cfg> int
PrintMarginWidth
[40]
Affects only TreeGrid print dialog (shown by PrintCols=2).
Left + right margin of the page, in millimeters. (pixels = mm / 25.4 x DPI)
When changed by a user in the print dialog, it recalculates
PrintPageWidth attribute accordingly. It is subtracted from page width.
new 9.0 <Cfg> int
PrintMarginHeight
[40]
Affects only TreeGrid print dialog (shown by PrintCols=2).
Top + bottom margin of the page, in millimeters. (pixels = mm / 25.4 x DPI)
When changed by a user in the print dialog, it recalculates
PrintPageHeight attribute accordingly. It is subtracted from page height.
new 12.0 <Cfg> float
PrintMarginDiv
[1]
Shows the PrintMarginHeight and PrintMarginWidth in Print columns menu divided by this value.
Set PrintMarginDiv='25.4' to display the margin values in inches.
new 9.0 <Cfg> int
PrintPaddingWidth
[0]
Reserved width on page (in pixels), for other content on page, e.g. for
PrintPagePrefix /
PrintPagePostfix or HTML body margin / border / padding
It is subtracted from
PrintPageWidth when printing, not in the print menu.
new 9.0 <Cfg> int
PrintPaddingHeight
[0]
Reserved height on page (in pixels), for other content on page, e.g. for
PrintPagePrefix /
PrintPagePostfix or HTML body margin / border / padding
It is subtracted from
PrintPageHeight when printing, not in the print menu.
new 9.0 <Cfg> int
PrintPaddingHeightFirst
[0]
Reserved height on the first page, for other content on the first page, e.g. for
PrintPrefix
It is subtracted from
PrintPageHeight when printing, not in the print menu.
For grid split horizontally, it is added to every first page (to preserve the horizontal page synchronization).
new 9.0 <Cfg> int
PrintPaddingHeightLast
[0]
Reserved height on the last page, for other content on last first page, e.g. for
PrintPostfix
It is subtracted from
PrintPageHeight when printing, not in the print menu.
For grid split horizontally, it is added to every last page (to preserve the horizontal page synchronization).
new 9.0 <Cfg> bool
PrintConstWidth
[0]
If set to
1, all pages will get the same, maximal, width. By adding right empty column.
Useful to preserve width of space rows.
new 9.0 <Cfg> bool
PrintGanttSplit
[1]
If Gantt chart column can be split if it is wider than selected page by
PrintPageWidth.
The individual Gantt pages dates will be rounded to
GanttPrintRound or if not set, to
GanttUnits.
new 9.0 <Cfg> int
PrintGanttSplitMin
[100]
Minimal size in pixels of printed part of Gantt when split by
PrintGanttSplit.
It affects the first and last page part of the printed Gantt.
renamed 6.0 upd 6.7 <Cfg> bool
PrintPageBreaks
[0] Saved to cookies, to not load it, set PrintLap='1'
Prints page break after every
PrintRows variable rows.
For every page it prints new table with all fixed and space rows that have
CanPrint='2'
Since 6.7 it can be changed via print menu and is saved to cookies.
It does
not affect
PrintPageHeight, both these attributes can be used separately or together.
new 9.0 <I> bool
NoPageBreak
[0]
If set to
1, grid does not break page before the row, except it would lead to higher page.
new 7.1 upd 9.0 <Cfg> bool
PrintPageRoot
[0] Saved to cookies, to not load it, set PrintLap='1'
For
1 it prints page break only between root rows (preserves printing children with their parent).
It breaks children only the parent children are higher than page height or PrintRows, in this case
(since 9.0) it tries to preserve at least sub children on next tree levels, if any.
Since 9.0 it can be changed via print menu and is saved to cookies and also never creates higher page than PrintRow.
new 9.1 <Cfg> int
PrintPageRootMin
[10]
Minimal count of rows on page when applied PrintPageRoot, to avoid pages with only few rows.
new 9.0 <Cfg> string
PrintPagePrefix
HTML code added in front of every TreeGrid page when printing.
If it contains these strings, they are replaced by:
%1 horizontal page index,
%2 vertical page index,
%3 page index,
%4 horizontal page count,
%5 vertical page count,
%6 page count,
%7 page width in pixels,
%8 page height in pixels.
The page counts (%3,%4,%5) should not be used with
PrintLoad.
new 9.0 <Cfg> string
PrintPagePostfix
HTML code added behind every TreeGrid page when printing.
If it contains these strings, they are replaced by:
%1 horizontal page index,
%2 vertical page index,
%3 page index,
%4 horizontal page count,
%5 vertical page count,
%6 page count,
%7 page width in pixels,
%8 page height in pixels.
The page counts (%3,%4,%5) should not be used with
PrintLoad.
new 12.0 chg 12.1 <Cfg> int
PrintZoomFit
[1]
If set to
1, it shrinks the printed grid pages to be always printed whole regardless on page size, orientation and margin chosen in system / browser print dialog.
If set to
2, it works as
1 and also resizes too small grid pages to fill at least one direction of the printed page.
Using this attributes cancels the requirement to choose the same pages size, orientation and margins in TreeGrid print dialog and system / browser print dialog.
If the attribute is set, it also uses
PDFFitPage and shows this option in print menu.
This attribute is ignored if set PrintLocation=2. This attribute is ignored in IE8 and older.
Since 12.1 default value changed from 0 to 1.
It is fully supported in IE9+ and Chrome. It has small problems in Safari. In Firefox it requires setting the same page margins in TreeGrid print dialog and system print dialog. Edge cannot be used for printing because it does not print background images.
new 6.7 chg 12.0 <Cfg> int
PDFFitPage
[0] Saved to cookies, to not load it, set PrintLap='1'
Shrinks or resizes the printed grid to be printed in one page in given or both directions.
0 = Real size,
1 = Width,
2 = Height,
3 = Single page.
Since 12.0 this attribute is used not only for PDF export, but also for normal printing to printer if set PrintZoomFit.
Print API
<Actions>
Print
Attached to event OnClickButtonPrint
Shows printable version or grid and displays dialog for printing.
new 6.0 API event bool
OnPrintStart
(TGrid grid)
Called before the print report is generated.
Return true to cancel printing.
new 7.1 upd 12.1 API event void
OnPrintInit
(TGrid grid, string[Name] Cols, string[id] Rows)
Called after users selected columns to print and before the print report is generated.
Cols is array of all columns to print, by column name. If the column is not listed, it is
not printed.
Rows (new 12.1) is array of rows to print, by row id. If the row is not listed, it is printed according to its
CanPrint value.
It is possible to modify these arrays. They are null when set
PrintCols = 0.
Other settings like rows per page are already read from configuration and can be modified in the grid attributes.
Here is possible to modify also
PrintCount attribute when printing in server paging.
chg 6.0 API event string
OnPrint
(TGrid grid, Window window, string report)
Called after the print report has been generated, but before it was written to the print window and printed.
Return true to cancel printing or own print.
Or return new or updated report to print.
window is new window created for printing and should be closed when OnPrint returns true.
report is the generated grid HTML that will be printed.
API event bool
OnPrintFinish
(TGrid grid, Window window)
Called after print report is written to the window and before the printing dialog is displayed.
window is browser's window that contains the report.
You can also use this event to get back changes you done in
OnPrintStart event, if any.
Return true to suppress default action. You can call here window.print() in this event and do some action after, for example to close the window.
new 7.1 API event void
OnPrintClose
(TGrid grid, Window window)
Called when the print window is being closed or the print report is to be deleted and the original grid restored (depends on
PrintLocation settings).
window is browser's window that contains the report.
Here you can take back changes you done in page in OnPrintFinish, especially for
PrintLocation >= 2.
API event string
OnGetHtmlValue
(TGrid grid, TRow row, string col, type val)
Called to get formatted cell value to display. val is unformatted cell value.
Returns formatted value. If returned value is
not null, it is used instead of internal formatting by Format or Enum attributes.
Return null to use default formatting behavior.
It can be used also for printing, to print different value than cells show, for example:
Grids.OnPrintStart = function(G){ Grids.OnGetHtmlValueTmp = Grids.OnGetHtmlValue; Grids.OnGetHtmlValue = function(G,row,col,val){ /* here modify and return the values for printing */ } }
Grids.OnPrint = function(G){ Grids.OnGetHtmlValue = Grids.OnGetHtmlValueTmp; }
chg 6.0 API method string
GetPrintable
(function func)
Generates print report for the grid.
If
func is
not set, it generates the report synchronously without displaying message and returns the generated report.
If
func is set, it generates the report asynchronously, shows and updates progress message and after finish calls
func (
report).