Action button - Button

TreeGrid documentation

Introduction

Button type can display various action button types:

clickable button	Clickable button, after click there is called predefined action.
switch button	Button with two states on / off. After click it switches to the other state and is called predefined action.
radio / tab button	Group of switch buttons - after click to one button in group the other buttons are automatically switched off.
menu button	After click to button is displayed popup menu and user selects one action from the list.
combo switch button	A user selects button state from its popup menu, for the selected state is called assigned action.
combo radio / tab button	A group of combo switch buttons, after change some button state, the other buttons are reset to its predefined empty value.

Button type is intended to use especially in Space rows as control or tool buttons or tabs.
In normal non space rows is often better to use Panel type to show one or more clickable buttons in one cell.

Basic clickable action button

To define Button type, set column or cell attribute Type to "Button".
The Button Type is default type in Toolbar and Tabber rows.
Button content / text, can be:

0 or ""	The content will be read from ButtonText. To display "0" use value as "0 "
1	The content will be read from ButtonTextChecked or if not set, from ButtonText. To display "1" use value as "1 "
string	HTML code for Button type Html.
	HTML caption for TreeGrid Button type Button, if set UseButton = 0.
	<BUTTON> caption for Button type Button, if set UseButton = 1.
	HTML code for Button type Class, used only if set ShowButtons!

Type of button display. Default is "Html" except for Tabber row that is "Tab".

Button	Shows TreeGrid styled button with HTML text and / or side icon if set UseButton = 0.
	Or shows HTML <BUTTON> tag with HTML text if set UseButton = 1.
Html	Shows HTML text displayed as is and / or side icon.
	It can be also <button>, <img>, <a> tag or any other HTML code.
	It can contain also any predefined JavaScript onclick code.
Class	(new 11.0) Similar to Html, but the button icon is usually shown by CSS class.
	To the button div tag is assigned CSS class TxToolXXX, where Tx is the style prefix like TS for Standard style and XXX is the cell (column) name or ButtonClass .
	If set IconAlign, to the button div tag is added also CSS class TxToolXXXAAA, where AAA is the IconAlign value like "Top" or "Right".
Tab	Similar to Html, but with different look - visually separated tab page. Can be used only on Space row.
TabSep	No button, tab separator only. Set the space cell Width attribute to the separator size (since 7.0).
	If the TabSep cell has not set its Width, it has automatically set RelWidth='1' and aligns the next cells right side.

Width of < BUTTON > tag for Button="Button", in pixels. Set -1 for auto width according to the content.
Icon file to show the icon inside the button on given side.
It can be also standard left / right side icon, see Left side icon.
It is used only for Button="Html", "Tab", "Class" and Button="Button" if set UseButton = 0.
Position of the button side Icon. By default the Icon is placed left side of the button text.
Supported values are "Left", "Right" and since 11.0 also "Top", "Bottom".
It is used also for Button="Class" to more specify the CSS class, usually also for the icon side.
It can be overwritten globally by ShowButtons value, set <Cfg ShowButtons='3'/> to use IconAlign for all Button values. Width in pixels of the Icon. Used only for IconAlign="Left" or "Right"
The icon should not be wider than the IconWidth, otherwise it is overwritten by the cell text.
The IconWidth can be also set to 0 to use the Icon as background image of the cell.
What will be shown in buttons with both text and side icon. Affects also Button="Class".
To cookies are saved only values 1, 2 and 3. Changing the value via configuration menu refreshes only Space rows.

0	For backward compatibility, for Button="Html" and Button="Tab" shows both, but for Button="Class" shows only the icon (=class).
1	Shows only icons
2	Shows only texts
3	Shows both text and icons
4	Shows both text and icons, icon always on left
5	Shows both text and icons, icon always on right
6	Shows both text and icons, icon always on top
7	Shows both text and icons, icon always on bottom

Height of the cell in pixels.
Set it when the Icon in Space cell is not visible whole.
If the button is disabled.
Disabled button is inactive and is displayed with 30% opacity.
Disabled button does not call OnClickButton event, but still calls OnClick event.
Line in given color shown under the button. It can be any CSS color.
Style of the Underline line. If not set, it is 4px solid.
0 - none, 1 - 1px solid, 2 - 2px solid, 3 - 3px solid, 4 - 1px dotted, 5 - 2px dotted, 6 - 1px dashed, 7 - 2px dashed.
CSS class name part to be used instead of the column name for Button="Class".
Useful to display different icon based on some value, because the ButtonClass can be calculated by Formula.
Since 13.1 it can contain more class name parts separated by comma (not by space).
Standard column, row, cell or Actions attribute containing JavaScript code.
It is called on click to the cell of Type="Button".
It is standard TreeGrid mouse event, here is just mentioned to not forget its possibility when handling Button clicks.
Example: <I Col1OnClickButton='alert("clicked column "+Col);'/>
The difference between OnClick and OnClickButton is that OnClickButton is not called for disabled button, but OnClick is called always.
Standard column, row, cell or Actions attribute containing JavaScript code.
It is called on click to the cell.
It is standard TreeGrid mouse event, here is just mentioned to not forget its possibility when handling Button clicks.
Example: <I Col1OnClick='alert("clicked column "+Col);'/>
The difference between OnClick and OnClickButton is that OnClickButton is not called for disabled button, but OnClick is called always.
Provides action for the button
Simulates click to the given button, similarly to action Button.
Url or data to reload body from here when button is clicked.
It can be direct XML (starting with <) or tag id of existing tag (input) to use its value or URL.
It replaces Data_Url / Data_Tag / Data_Data and reloads body of TreeGrid.
The data must contain only <Body> tag and not layout definition.
If defined List, it contains first character separated list of the data to reload on the specific item click.
How the TreeGrid buttons are rendered.
Bit array: 1.bit for type Button with Button="Button", 2. bit for right side button with Button="Button", 3. bit for type Panel custom button.
0 - It renders the buttons as TreeGrid styled button done by <u> tag.
1 - It renders the buttons as HTML <button> tag. Set UseButton='7' for all three type buttons. Default behavior before version 11.0.
Simulates visual effect of clicking button with Button="Button" and UseButton='0'. Returns always 0.
Clears visual effect set by ButtonDown. Returns always 0.

Switch on / off button

If set to 1, the button will have two states 0 / 1 and can be switched by click.
Since 15.0 if set to 2 and the button value has number value, it will use ButtonTextX (e.g. ButtonText3 for value 3) instead of ButtonTextChecked and IconX instead of IconChecked.
Button value is 0 or "" as off and 1 as on
HTML code for Button type Html.
<;BUTTON> caption for Button type Button.
If set, it replaces ButtonText for checked Switch button (button with value > 0)
Standard left / right side button, see Left side icon.
If set, it replaces Icon for checked Switch button (button with value > 0)
Standard Formula attribute for Calculated row, here is stated just not forget its advantage for Switch buttons.
The Switch button can have set its Formula to calculate its state.
The formula must return 0 or 1 as button state.
Standard column, row, cell or Actions attribute containing JavaScript code.
It is called when the Switch or Radio Button value is changed. For Radio is called also for automatically unchecked buttons.
Attach the action or any JavaScript code to the cell to be run on cell value change, like <I ... Col1OnChange='alert("changed!")' ... />
The new state can be got by Get(Row,Col).
Special column, row, cell or Actions attribute containing JavaScript code.
It is called when the Switch or Radio Button value is checked.
Example: <I Col1OnCheck='alert("checked cell "+Col);'/>
Special column, row, cell or Actions attribute containing JavaScript code.
It is called when the Switch or Radio Button value is unchecked. For Radio is not called for automatically unchecked buttons.
Example: <I Col1OnCheck='alert("unchecked cell "+Col);'/>

Radio / tab button

A group of Switch buttons, a user switches among them - chooses only one.
It is possible also to add, delete, move or copy the tabs / radios if permitted by appropriate attributes.
All other attributes are the same as in Switch button, except the Switch attribute itself.
If set, all the Button cells (in the same row) with the same Radio value will be in one radio group.
It is an index of radio group of Button cells in row.
Only one cell in the group of cells (with the same Radio) can be checked.
When a user checks some Radio button, the previously checked button in the group is automatically unchecked.
If all the buttons with the same Radio can be empty - a user can uncheck the checked button.
Defines section, where the buttons can be dragged (moved and copied). By default the buttons cannot be dragged.
Comma separated of pairs of cell names as outside bounds where the inside buttons can be moved. If the item is empty, it is the last left or right bound.
For example <I Cells='A,B,C,D,E,F,G,H,I,J,K,L' DragTab=',D,F,K'/> - The buttons A,B,C can be moved among themselves (inside left and D) and buttons G,H,I,J can be moved among themselves (inside F and K).
If the button can be moved according to the DragTab settings.
If the button can be copied according to the DragTab settings.
If set to 2, the button copy gets CanDelete='1'.
If the button can be deleted.
If set to 2, it shows also close icon in top right corner.
If the button ButtonText can be edited.
Called before the button is dropped left to the tocol. tocol is empty string to drop as the last cell.
copy is set if the button will be copied instead of moved.
Return true to not drop it. Return new tocol to drop it somewhere else. Return null for default behavior.
Called before the button is deleted, return true to not delete it.
Starts dragging the button by mouse.
Starts dragging the button by mouse, the button will be copied.
Deletes the button.

Menu button

On click to button is displayed popup menu and user uses one action to be done.
Default icon setting is Icon="Popup" IconAlign="Right". You can hide the icon by setting Icon=""
A first character separated list of values to select to the button value. A user can choose one value from combo.

Or it can be in standard TreeGrid menu format as complex menu with sub levels, sub menus, columns and so on.
The individual menu items can have set attributes Icon, Action and ReloadData to be used instead of Icons / Actions / ReloadData lists.
A first character separated list of icons displayed for individual menu items in List.
For combo button is the chosen menu item icon also set to the button Icon attribute.
Height in pixels of the icons in Icons.
A first character separated list of OnClick actions called after specific item in menu List is clicked.
The action can contain any JavaScript or TreeGrid action like standard XML event, see OnClick.
A first character separated list of ReloadData urls.
Called after some event in Button List menu is clicked. item is item name from List, index is item position in List or menu item Value if set. Called before displaying menu List to get the list dynamically.
Returns original or modified button list.
Or return null to not show the list.
Called before displaying menu List to update the menu dynamically.
It can be used to do any modification in Menu, for example to sort or change position in Menu.Items array. See Menu documentation.

Combo switch button

If you set both Switch and List, the button behaves as combo box - a user chooses one button value from the popup menu.
All other attributes are the same as in Popup menu button.
If set, the button will get the value chosen in List.
Initial Button value or value chosen from List.
Standard Formula attribute for Calculated row, here is stated just not forget its advantage for Switch buttons.
The Switch button can have set its Formula to calculate its state.
The formula must return the button text to display.
Standard column, row, cell or Actions attribute containing JavaScript code.
It is called when the Switch or Radio Button value is changed. For Radio is called also for automatically unchecked buttons.
Attach the action or any JavaScript code to the cell to be run on cell value change, like <I ... Col1OnChange='alert("changed!")' ... />
The new state can be got by Get(Row,Col).

Combo radio / tab button

If you set both Radio and List, the button behaves as radio combo box - a user chooses one button value from the popup menu.
A group of Switch buttons, a user switches among them - chooses only one.
In the group can be combined the combo and normal Switch buttons.

All other attributes are the same as in Combo switch button and Radio tab button, except the Switch attribute itself.
The value set to the button text when the button is automatically unchecked, because of checking another button in the radio group.
Remember, its functionality differs from EmptyValue attribute for other cell types.
The icon set to the button Icon attribute when the button is automatically unchecked, because of checking another button in the radio group.
If the right side popup icon will be displayed.
0 - never, 1 - only for EmptyValue, 2 - always. 3 - new 12.0 always and show the menu only on click to the icon, not to the button itself.

Special Space rows with buttons

Special Space row to use especially with Button type cells.
It has predefined some different default settings:
Space="4" NoUpload="1"
cellType="Button"
(since 7.0) The Toolbar1 and Toolbar2 kinds can be used when there are defined two bottom toolbars, just to better style them. (Since 11.0) the Toolbar3 to place between them for third and more toolbars.

Every grid has defined one default Toolbar in Defaults.xml. See Default Toolbar.
Special Space row to use especially with Button type cells.
It has predefined some different default settings:
Space="0" NoUpload="1"
cellType="Button"
The Topbar1, Topbar2 kinds can be used when there are defined two top toolbars, just to better style them. (Since 11.0) The Topbar3 to place between them for third and more toolbars.
Special Space row to use especially with Button Tab type cells.
It has predefined some different default settings:
Space="-1" NoUpload="1"
cellType="Button" cellButton="Tab" cellRadio="1"
(Since 10.0) The Tabber2 does not show background for other cells than tabs.