Toolbar

FastGrid documentation

Toolbar

Toolbar identification unique in the whole, among all toolbars.
If not set, it is set as ToolbarIdPrefix + ToolbarId++.
It can be used by GetToolbar to get the Toolbar object for API usage.
Prefix added before auto generated Toolbar id.
Starting number for auto generating Toolbar id.
Default toolbar to read all unset attributes from.
See predefined default toolbars.
If the toolbars can be hidden.
If set to 2 it also shows all hidden toolbars that can be shown.
If set to 3 it also shows / hides the toolbars on single click.
It is automatically set by SetDraggingToolbars.
If set, the toolbar is not displayed at all.
If set, the toolbar cell cannot be hidden or shown. Toolbar name that is shown as in menus and messages. If not set, toolbar id is used.
Returns toolbar according to its id.
Returns toolbar the cell belongs to.
Returns true if the toolbar is Toolbar object.
Returns id of part that the row, column, toolbar or toolbar cell belongs to.
Returns grid that the row, column, toolbar or toolbar cell belongs to.
Called when generating id for any row, column, toolbar or toolbar cell in grid.
It is not called if the item has set its unique id.
type is item kind: 0 - row, 1 - column, 2 - group row, 3 - goup column, 4 - toolbar, 5 - toolbar cell.
Called to get row / column / toolbar Name.
Adds or moves (copy = 0) or copies (copy = 1) toolbar.
It moves or copies also from another grid if the src is toolbar in another grid.
If set all, it moves / copies also all next toolbars with Pos >= 3 together.

src specifies the toolbar that is added / copied / moved.
It can be Toolbar object as existing toolbar to copy / move.
Or it can be an object to add new toolbar.
Or it can be string to add new toolbar with given D and / or id.
Or it can be null to add new empty toolbar.

The new toolbar is added left to the next toolbar.
Or the next can be part id to add the toolbar to the end of the part.
If next is null, the cell is added to the end of first Toolbars part.

Returns added / moved / copied toolbar. Or returns null if nothing was modified.
Removes given toolbar from its part.
Returns true for success and false for error.
Called before the toolbar added / moved / copied left to the next toolbar. Called from AddToolbar method.
copy is set to source toolbar if it is copied.
all is array of all source toolbars that will be added / moved / copied. It should not be modified.
Return true to cancel the action. Or modify the toolbar object and return false.
Called after the toolbar added / moved / copied left to the next toolbar. Called from AddToolbar method.
Called before the toolbar removed from its part. Called from RemoveToolbar method.
It is not called when moving the toolbar to another part or grid.
Return true to cancel the action.
Called after the toolbar removed from its toolbar. Called from RemoveToolbar method.
It is not called when moving the toolbar to another part or grid.
Hides actual toolbar.
Hides or shows the toolbar. hide = null - change visibility, 1 - show, 0 - hide.
Returns true for change, false without change and null for incorrect toolbar.
Called before the toolbar is hidden / shown. Called from HideToolbar method.
hide = 0 - show, 1 - hide.
test is true if just testing possibility of showing / hiding, e.g. to display the action in popup menu.
Return true to cancel the action.

Cells

Toolbar cells are Tool objects and have similar attributes like standard Row cells.
The Toolbar cell attributes are defined directly in the Tool object.
Full definition of the toolbar cells.
It is an array of objects as Tool items.
The item can be also string to be used as id and if exists default, also as D - "XXX" => { id:"XXX", D:"XXX" }.
The Cells Tool defined as objects support also attributes Next, Prev, Remove, Add to redefine existing cells or place the cell to specific position.
If the first item is object {Clear:1}, it clears all previously defined cells in this toolbar.
If the first item is empty string or null, it places all the next cells like with Next = "".
If defined toolbar with already existing id, the Cells are merged with the previous Toolbar Cells, except if defined Add attribute in the Toolbar.
If defined two cells with the same id in the same Cells array, the second id is changed to be unique.
Cell identification unique in its Toolbar.
If not set or already exists in the toolbar, it is set as ToolIdPrefix + ToolId++.
It can be used by GetTool to get the Tool object for API usage.
Prefix added before auto generated Tool id.
Starting number for auto generating Tool id.
Default toolbar cell to read all unset attributes from.
If not set, it is set to "Icon" if Type is not explicitly set, otherwise it is set to "Cell".
See predefined default toolbar cells.
If the toolbar cells can be hidden or shown.
If set to 2 it also shows all hidden toolbar cells that can be shown.
If set to 3 it also shows / hides the toolbar cells on single click instead of running action for the cell.
It is automatically set by SwitchDraggingToolbars.
If set, the cell is not displayed at all.
It is not read from the toolbar row!
If set, the toolbar cell cannot be hidden or shown.
It is not read from the toolbar row!
Text displayed on cell. If not set, Value is shown. If set neither Value, id is shown.
Useful when the cell Value is used for other purpose, e.g. on Bool type.
It can contain HTML code. Using incorrect HTML code can break down the grid completely!
Using many cells with HTML code remarkably slows down paint!
Left side label text for the cell.
It can contain HTML code. Using incorrect HTML code can break down the grid completely!
Using many labels with HTML code remarkably slows down paint!
The Label can have set the text style attributes: LabelTextColor, LabelTextLine, LabelTextLineColor, LabelTextShadow, LabelTextShadowColor, LabelTextStyle, LabelTextFont, LabelTextSize.
And also attributes LabelVertAlign, LabelLink and LabelTranslate.
Using the text style attributes in many labels can slow down paint! Right side label text for the cell.
It can contain HTML code. Using incorrect HTML code can break down the grid completely!
Using many labels with HTML code remarkably slows down paint!
The LabelRight can have set the text style attributes: LabelTextColor, LabelTextLine, LabelTextLineColor, LabelTextShadow, LabelTextShadowColor, LabelTextStyle, LabelTextFont, LabelTextSize.
And also attributes LabelVertAlign, LabelLink and LabelTranslate.
Using the text style attributes in many labels can slow down paint! If set in default toolbar cell, this default tool can be defined more times in one toolbar Cells by string, e.g. for Separator: Cells:["Add","Separator","Delete","Separator","Move"].
If toolbar is saved to cookies, ignores Next in Cookie Tools.
Returns toolbar cell according to its id.
toolbar can be Toolbar object or string as toolbar id.
Returns first toolbar cell that's id is id. Iterates all toolbars.
Returns true if the tool is Tool object as toolbar cell.
Hides actual toolbar cell.
Hides or shows the toolbar cell. hide = null - change visibility, 1 - show, 0 - hide.
Returns true for change, false without change and null for incorrect cell.
Called before the toolbar cell is hidden / shown. Called from HideTool method.
hide = 0 - show, 1 - hide.
test is true if just testing possibility of showing / hiding, e.g. to display the action in popup menu.
Return true to cancel the action.

Icon

Icon displayed on the toolbar cell.
The usable icons are defined in Icons tag, default FastGrid icons are defined in Styles.js.
If Icon is not set and Type is also not set (or used D: "Icon"), the Icon is set to cell id.
The Icon is ignored for Bool Type.

External image
The Icon can be set also to url to external image file or included image by "data:".
The relative urls are relative to the main page url, not to FastGrid url.
Size of the external image can be set by IconHeight. If not set, the image is shown on its original size. The external image is shrunk, if the image default or explicit height is higher than the toolbar height.
Using external images can slow down paint!
External images should be used only for development; in production they should be converted to internal images in Icons.
Action button for given Icon. If not set, it is the toolbar cell Button.
To this button events are assigned actions in Actions object or in Tool / Toolbar.
Icon position: 0 - left to the text, 1 - right to the text.
Reserved horizontal space for the Icon in pixels. If not set, the space is reserved by Cfg IconWidth.
If the icon is affected by IconZoom, the reserved space is multiplied by the IconZoom.
It neither resizes nor overflows the icon. Predefined reserved horizontal space for of all icons in grid. Affects both cell icons and toolbar icons.
It neither resizes nor overflows the icon. For internal Icon (defined in Icons), it specifies expected icon height in pixels for vertical alignment by VertAlign / IconVertAlign.
If set to -1, it is set to the whole row height. If not set, the Cfg IconHeight is used.
It neither resizes nor overflows the internal icons. It does not affect the toolbar height.

For external image set by url in the Icon, it specifies the exact height of the image - the image is resized to the IconHeight.
If not set, the external image is shown in its implicit size, but for vertical alignment is used the Cfg IconHeight.
If the icon is affected by IconZoom, the icon is resized by the IconZoom ratio.
The external image is shrunk, if the image default or explicit height is higher than the toolbar height.
Predefined expected icon height in pixels for vertical alignment by VertAlign / IconVertAlign.
It neither resizes nor overflows the icon. It does not affect the toolbar height. Predefined reserved horizontal space for of Popup icons in toolbar cells.
Multiplies toolbar icons. To have icons on toolbar bigger than in grid cells.
It should be set with ToolbarHeight. For example IconZoom = 1.75 should increase default ToolbarHeight 30 to 42 ( = 30 / 1.25 * 1.75).
If the IconZoom is applied also for icons in cells with side text or with Width set. And is applied also for toolbar text vertical padding.
If the icon is scaled according to the IconZoom. If not set, it is 1 or according to TextIconZoom.
If set to 1, shows popup icon right to the Icon. On click shows List / ListMenu.
If set to 2, it does not show the popup icon, but still behaves like popup icon and on click shows List / ListMenu.

Height

Height of the toolbar in pixels. It includes PaddingTop and PaddingBottom.
If set to 0, it calculates the height according to the cell content plus vertical padding.
It should be changed accordignly with IconZoom.
Minimal height in pixels of the toolbar for resizing.
Maximal height in pixels of the toolbar when its Height is set to 0 and for resizing.
Default toolbar height if it has not set Height attribute.
Empty space above the toolbar in pixels.
Empty space below the toolbar in pixels.
Space from the cell top edge to the cell text or Icon in pixels. It is included in Height
Used for VertAlign = 0 (top). Used also partially if the content plus vertical padding is higher than Height.
Space from the cell bottom edge to the cell text or Icon in pixels. It is included in Height
Used for cell VertAlign = 1 (bottom). Used also partially if the content plus vertical padding is higher than Height.
Vertical space between icon top edge and text top edge, in pixels.
It is added to PaddingTop for Icon.
Vertical space between icon bottom edge and text bottom edge, in pixels.
It is added to PaddingBottom for Icon.
How the cell content (text and icon) is vertically aligned.
0 - align top, 1 - align bottom, 2 - align middle.
Cells are always overflown from bottom.
How the Icon is vertically aligned. If not set, the VertAlign
0 - align top, 1 - align bottom, 2 - align middle.
How the Label and LabelRight are vertically aligned. If not set, the VertAlign
0 - align top, 1 - align bottom, 2 - align middle.
1. bit, &1 = 1, dragging bottom edge of the cell will resize the toolbar height.
2. bit, &2 = 2, dragging right edge of the cell will resize the cell width.
3. bit, &4 = 4, dragging the bottom cell edge will resize the cell only if DraggingToolbars>=2 and dragging the right cell edge will resize the cell only if DraggingTools>=1.

Width

Width of the cell text in pixels. If set to 0 (by default), it is calculated as the text width.
If set Rel and the Width = -1, it never resizes the cell above its text width; if the Width = -2, it never resizes the cell below its text width; other Width values are ignored if set Rel.
Final cell width is calculated as:
Text only: PaddingLeft + Width + PaddingRight.
Text + Icon on the right: PaddingLeft + Width + PaddingText + IconWidth*IconZoom + PaddingRight.
Text + Icon on the left: PaddingLeft + IconWidth*IconZoom + PaddingText + Width + PaddingRight.
Text + CellBorder: PaddingLeft + CellBorderSpace + Width + CellBorderSpace + PaddingRight.
Text + CellBorder + Icon on the right: PaddingLeft + CellBorderSpace + Width + CellBorderSpace + PaddingText + IconWidth*IconZoom + PaddingRight.
Text + CellBorder + Icon on the left: PaddingLeft + IconWidth*IconZoom + PaddingText + CellBorderSpace + Width + CellBorderSpace + PaddingRight.
Icon only or with CellBorder: PaddingLeft + IconWidth*IconZoom + PaddingRight.
Minimal width in pixels used for Rel cell or if the Width = 0 or for resizing.
Maximal width in pixels for Rel cell or if the Width = 0 or for resizing.
If set, maximizes the cell width to fill the whole space for toolbar - to be no empty space right to the toolbar.
If more cells on one line have Rel attribute set, their width is increased in their Rel values ratio.
When there can be more toolbars on one line, their Rel cells are first set to MinWidth and after placing all toolbars, the Rel cells are maximized.
What can be shrunk if the toolbar with Rel cells is wider than grid.
1. bit &1 - MinWidth is set to 1 pixel.
2. bit &2 - PaddingLeft and PaddingRight is set to 0 pixels.
3. bit &4 - if set CellBorder, its Left and Right is set to 0 pixels.
4. bit &8 - Icon is set to "".
5. bit &16 - The text is displayed as html to not be overflowed to whole characters.
6. bit &32 - Sets Rel attribute to cell without it.
Empty space left to the toolbar in pixels.
Empty space right to the toolbar in pixels.
Empty space between the cell and previous cell in pixels. It is added before left Label if any. Multiplied by IconZoom
It is not read from the Toolbar row. Empty space between the cell and next cell in pixels. It is added after right LabelRight if any. Multiplied by IconZoom
It is not read from the Toolbar row. Empty space between the cell label and previous or next cell in pixels.
It is added to MarginLeft before left Label and to MarginRight after right LabelRight if any. Multiplied by IconZoom
Empty space between the cell and its label in pixels.
It is added to PaddingLeft after left Label and to PaddingRight before right LabelRight if any. Multiplied by IconZoom
Space inside cell between the cell left edge and Icon or text in pixels.
Space inside cell between the cell right edge and Icon or text in pixels.
Space inside cell between the cell text and Icon in pixels, only if both are present.

Toolbar position

Toolbar position relative to the previous toolbar on the same line.
0 - next to direct previous toolbar, always on the top of the line. Using with other Pos values can lead to toolbar overlay.
1 - next to utmost right toolbar on all levels; placed on top of the line.
2 - next to the previous toolbar on top of the line.
3 - next to direct previous toolbar on the same level (the same Y position).
4 - below direct previous toolbar, next to previous toolbar on this level.
5 - below the previous toolbar, aligned to its left (the same X position).
6 - below the previous toolbar without Pos = 3, aligned to its left (the same X position).
The Pos >= 3 cannot be dragged separatelly, it is dragged only with the previous toolbar.
1. bit &1 - new line before - the toolbar always starts on new line from the grid left edge.
2. bit &2 - new line after - the next toolbar always starts on new line from the grid left edge.
If set, restricts wrapping toolbars vertically in the "Toolbars" row part.
1. bit &1 - restricts automatic wrapping.
2. bit &2 - restricts wrapping by NewLine.
If wrapping is restricted, the toolbars can be hidden because of placing beyond the grid right edge.
Toolbar cannot be wrapped inside itself, so if it is too wide, it can be overflowed by grid right edge.

Dragging and manipulating cells

During toolbar cells dragging are called standard dragging events:
OnStartDrag, OnDragging, OnDrop, OnEndDrag.

Toolbars can be dragged by DragToolbar cell that is shown when set DraggingToolbars.
If set to 0, toolbar cells can be moved according to their NoMove settings.
If set to 1, permits moving all toolbar cells inside their toolbar. Except cells with NoMove&8
If set to 2, permits moving all toolbar cells inside and between toolbars. Except cells with NoMove&8
If set to 3, permits moving all toolbar cells between grids (tested in source grid). Except cells with NoMove&8
It is automatically set by SwitchDraggingToolbars.
If set to 0, the toolbars cannot be moved by users and DragToolbar cell is not shown.
If set to 1, shows all toolbars with DragToolbar cell on beginning, but still cannot drag the toolbars.
If set to 2, permits moving toolbars by dragging the DragToolbar cell.
If set to 3, permits moving toolbars by dragging the DragToolbar cell also between grids (tested in source grid).
The toolbars with Pos >= 3 are dragged together with previous toolbar.
For correct dragging the toolbar NewLine should be set only to 0 / 1 and wrapping toolbars should be permitted by the NoWrap = 0.
If set DraggingToolbars = 1, shifts all toolbars to the left by this amount of pixels. To hide the most left DragToolbar icon.
1.bit &1 - Toolbar cell cannot be moved inside its toolbar.
2.bit &2 - Toolbar cell cannot be moved to another toolbar.
3.bit &4 - Special toolbar cell with Kind cannot be moved to rows / columns.
4.bit &8 - Toolbar cell cannot be moved on DraggingTools.
If not set, the toolbar cell can be moved according to destination toolbar Accept attribute.
By default it is set to 3 except: in Drag (Group / Hide) toolbar is set to 8 and in Drop cell is set to 15.
1.bit &1 - Toolbar cell cannot be copied inside its toolbar.
2.bit &2 - Toolbar cell cannot be copied to another toolbar.
3.bit &4 - Special toolbar cell with Kind cannot be copied to rows / columns.
If not set, the toolbar cell can be copied according to destination toolbar Accept attribute.
If set, the toolbar cell cannot be deleted by mouse dragging outside the toolbar.
If set, dragging the toolbar cell will move the whole toolbar instead of the cell itself.
By default it is set to 1 in DragToolbar cell and 0 in all other cells.
If set, the tollbar cell is fixed to some edge and no cell can be dropped next to it:
1. bit &1 - fixed left, no cell can be dropped left to it.
2. bit &2 - fixed right, no cell can be dropped right to it.
If set, the toolbar cell can be moved by mouse dragging to another position in the same toolbar or to another toolbar, depending on toolbar Accept attribute.
Comma separated string or array of strings.
The toolbar accepts as children dropped items only if their DragId is listed here.
To toolbar there can be dropped rows, columns or toolbar cells.
More control of dropping is done also by toolbar Kind.
Toolbar cell identification to accept dropping to toolbar by Accept attribute.
Sets value to DraggingToolbars and updates all affected toolbars.
Starts or ends dragging toolbars, sets all required attributes.
For all updates all toolbars in other sheets in book to show the changes.
Adds or moves (copy = 0) or copies (copy = 1) toolbar cells inside / into toolbar par.
It moves or copies also from another grid if the src is toolbar cell in another grid.

src specifies the toolbar cell that is added / copied / moved.
It can be Tool object as existing toolbar cell to copy / move.
Or it can be an object to add new cell.
Or it can be string to add new cell with given D and / or id.
Or it can be null to add new empty cell.

par is Toolbar where to add the cell, the cell is added left to the next cell.
If next is null, the cell is added to the end of the par.
At least par or next must be set.

Returns added / moved / copied toolbar cell. Or returns null if nothing was modified.
Removes given toolbar cell from its toolbar.
Returns true for success and false for error.
Called before the toolbar cell added / moved / copied in the toolbar left to the next cell. Called from AddTool method.
copy is set to source cell if it is copied.
Return true to cancel the action. Or modify the cell object and return false.
Called after the toolbar cell added / moved / copied in the toolbar left to the next cell. Called from AddTool method.
Called before the toolbar cell removed from its toolbar. Called from RemoveTool method.
It is not called when moving the cell to another toolbar or grid.
Return true to cancel the action.
Called after the toolbar cell removed from its toolbar. Called from RemoveTool method.
It is not called when moving the cell to another toolbar or grid.

Special toolbars

If set, the toolbar has special behavior. It generates its cells according to the specified feature or by OnToolbarCells event. And after drop the cell in or out the toolbar provides specific action.

Hide	Shows hidden rows / columns from given Part that are accepted by Accept. After dragging toolbar cells the rows / columns are hidden / shown in grid.
Group	Shows rows / columns listed in Group from given Part that are accepted by Accept. If the Part contains more parts with different Group attribute, one of them is used randomly. After dragging toolbar cells the columns / rows are grouped accordingly and the parts' Group attribute is changed.
PivotRows	Shows rows / columns listed in PivotRows from given Part that are accepted by Accept.
PivotCols	Shows rows / columns listed in PivotCols from given Part that are accepted by Accept.
PivotData	Shows rows / columns listed in PivotData from given Part that are accepted by Accept.
Sheets	Shows visible sheets from the grid Book.
any_other	Custom feature controlled by event OnToolbarCells and dragging events OnStartDrag, OnDragging, OnDrop, OnEndDrag.

Comma separated string or array of parts that are affected by toolbar Kind feature.
If not set, all rows and columns that fulfill Accept condition are affected.
Called to update cells in toolbar with Kind attribute set.
Use AddTool and RemoveTool methods to manipulate cells.
Return true to not update the cells by standard feature Kind like "Hide" or "Group".