Toolbar"

From Documentation
m
m (correct highlight (via JWB))
 
(24 intermediate revisions by 4 users not shown)
Line 1: Line 1:
{{Template:UnderConstruction}}
+
{{ZKSpreadsheetEssentialsPageHeader}}
 +
 
 +
 
 +
{{Deprecated|url=http://books.zkoss.org/wiki/ZK_Spreadsheet_Essentials}}
  
{{ZKSpreadsheetEssentialsPageHeader}}
 
  
 
__TOC__
 
__TOC__
  
 
===Purpose===
 
===Purpose===
ZK Spreadsheet supports various toolbar buttons for user to perform actions.
+
ZK Spreadsheet supports various toolbar buttons to perform actions.
  
 
===Show toolbar===
 
===Show toolbar===
Line 12: Line 14:
  
 
===Action Handler===
 
===Action Handler===
The Spreadsheet use a default <javadoc directory="zss" >org.zkoss.zss.ui.sys.ActionHandler</javadoc> to perform toolbar button's action. Developer could use customized ActionHandler by API <javadoc directory="zss"  method="setActionHandler">org.zkoss.zss.ui.Spreadsheet</javadoc> or by library property org.zkoss.zss.ui.ActionHandler.class, refer to [http://code.google.com/p/zkbooks/source/browse/trunk/zssessentials/examples/WebContent/WEB-INF/zk.xml sample zk.xml]
+
ZK Spreadsheet uses a default <javadoc directory="zss" >org.zkoss.zss.ui.sys.ActionHandler</javadoc> to perform toolbar button's actions. Developers are able to set customized <b>ActionHandler</b> by API <javadoc directory="zss"  method="setActionHandler">org.zkoss.zss.ui.Spreadsheet</javadoc> or by library property <b>org.zkoss.zss.ui.ActionHandler.class</b>, please refer to [http://code.google.com/p/zkbooks/source/browse/trunk/zssessentials/examples/WebContent/WEB-INF/zk.xml sample zk.xml]
  
Each toolbar's button represent a action, the ActionHandler process action when user click it.  
+
Each spreadsheet instance uses it own <b>ActionHandler</b> which cannot be shared across different spreadsheet instances.
  
<br/>For example, the paste toolbarbutton and menuitem represent <javadoc directory="zss"  method="PASTE">org.zkoss.zss.ui.Action</javadoc>, deveoper could override  
+
 
default behavior by override <javadoc directory="zss"  method="doPaste">org.zkoss.zss.ui.sys.ActionHandler</javadoc>
+
Each toolbar's button represents an action, the <b>ActionHandler</b> processes the action when clicked by a user.
 +
<br/>For example, the 'paste' toolbarbutton and menuitem are represented by <javadoc directory="zss"  method="PASTE">org.zkoss.zss.ui.Action</javadoc>, developers are able to override  
 +
default behavior by using <javadoc directory="zss"  method="doPaste">org.zkoss.zss.ui.sys.ActionHandler</javadoc>
 
<br/>[[File:ZKSsEss_Spreadsheet_Toolbar_paste.png]]
 
<br/>[[File:ZKSsEss_Spreadsheet_Toolbar_paste.png]]
  
Line 23: Line 27:
  
 
[[File:ZKSsEss_Spreadsheet_Toolbar_newBook.png]]
 
[[File:ZKSsEss_Spreadsheet_Toolbar_newBook.png]]
<br/>The default ActionHandler does nothing when user click the button, developer could override <javadoc directory="zss"  method="doNewBook">org.zkoss.zss.ui.sys.ActionHandler</javadoc>
+
<br/>The default <b>ActionHandler</b> does nothing when users clicks the button, developers are able to override <javadoc directory="zss"  method="doNewBook">org.zkoss.zss.ui.sys.ActionHandler</javadoc>
  
<source lang="java" high="2">
+
<source lang="java" highlight="2">
 
@Override
 
@Override
 
public void doNewBook() {
 
public void doNewBook() {
Line 37: Line 41:
  
 
[[File:ZKSsEss_Spreadsheet_Toolbar_saveBook.png]]
 
[[File:ZKSsEss_Spreadsheet_Toolbar_saveBook.png]]
<br/>The default ActionHandler does nothing when user click the button, developer could override <javadoc directory="zss"  method="doSaveBook">org.zkoss.zss.ui.sys.ActionHandler</javadoc>
+
<br/>The default <b>ActionHandler</b> does nothing when users clicks the button, developers are able to override <javadoc directory="zss"  method="doSaveBook">org.zkoss.zss.ui.sys.ActionHandler</javadoc>
  
<source lang="java" high="2,7,11">
+
<source lang="java" highlight="2,7,11">
 
@Override
 
@Override
 
public void doSaveBook() {
 
public void doSaveBook() {
Line 77: Line 81:
  
 
[[File:ZKSsEss_Spreadsheet_Toolbar_exportPDF.png]]
 
[[File:ZKSsEss_Spreadsheet_Toolbar_exportPDF.png]]
<br/>The default ActionHandler does nothing when user click the button, developer could override <javadoc directory="zss"  method="doExportPDF">org.zkoss.zss.ui.sys.ActionHandler</javadoc>
+
<br/>The default <b>ActionHandler</b> does nothing when users clicks the button, developers are able to override <javadoc directory="zss"  method="doExportPDF">org.zkoss.zss.ui.sys.ActionHandler</javadoc>
  
<source lang="java" high="2">
+
<source lang="java" highlight="2">
 
@Override
 
@Override
 
public void doExportPDF(Rect selection) {
 
public void doExportPDF(Rect selection) {
 
Spreadsheet spreadsheet = getSpreadsheet();
 
Spreadsheet spreadsheet = getSpreadsheet();
if (spreadsheet.getBook() != null && validSelection(selection)) {
+
if (spreadsheet.getBook() != null && isValidSelection(selection)) {
 
ExportPDFDialog dialog = new ExportPDFDialog(selection);
 
ExportPDFDialog dialog = new ExportPDFDialog(selection);
 
//omit
 
//omit
Line 90: Line 94:
 
</source>
 
</source>
  
Refer to [http://books.zkoss.org/wiki/ZK_Spreadsheet_Essentials/Working_with_ZK_Spreadsheet/Export_to_Different_File_Format/Export_to_PDF Export to PDF] and  sample code [http://code.google.com/p/zkbooks/source/browse/trunk/zssessentials/examples/src/org/zkoss/zssessentials/config/CustomizedActionHandler.java CustomizedActionHandler.java]
+
Refer to [http://books.zkoss.org/wiki/ZK_Spreadsheet_Essentials/Working_with_ZK_Spreadsheet/Export_to_Different_File_Format/Export_to_PDF Export to PDF] and  sample code [http://code.google.com/p/zkbooks/source/browse/trunk/zssessentials/examples/WebContent/config/exportPDFDialog.zul exportPDFDialog.zul][http://code.google.com/p/zkbooks/source/browse/trunk/zssessentials/examples/src/org/zkoss/zssessentials/config/CustomizedActionHandler.java CustomizedActionHandler.java]
  
 
====Paste Special====
 
====Paste Special====
 
[[File:ZKSsEss_Spreadsheet_Toolbar_pasteSpecial.png]]
 
[[File:ZKSsEss_Spreadsheet_Toolbar_pasteSpecial.png]]
<br/> The default ActionHandler does nothing when user click the button, developer could override <javadoc directory="zss"  method="doPasteSpecial">org.zkoss.zss.ui.sys.ActionHandler</javadoc>
+
<br/> By default, <b>ActionHandler</b> does nothing when users clicks the button, developers are able to override <javadoc directory="zss"  method="doPasteSpecial">org.zkoss.zss.ui.sys.ActionHandler</javadoc>
  
<source lang="java" high="2">
+
<source lang="java" highlight="2">
 
@Override
 
@Override
 
public void doPasteSpecial(Rect selection) {
 
public void doPasteSpecial(Rect selection) {
 
Spreadsheet spreadsheet = getSpreadsheet();
 
Spreadsheet spreadsheet = getSpreadsheet();
if (spreadsheet.getBook() != null && validSelection(selection)) {
+
if (spreadsheet.getBook() != null && isValidSelection(selection)) {
 
PasteSpecialDialog dialog = new PasteSpecialDialog(selection);
 
PasteSpecialDialog dialog = new PasteSpecialDialog(selection);
 
//omit
 
//omit
Line 111: Line 115:
 
====Custom Sort====
 
====Custom Sort====
 
[[File:ZKSsEss_Spreadsheet_Toolbar_customSort.png]]
 
[[File:ZKSsEss_Spreadsheet_Toolbar_customSort.png]]
<br/> The default ActionHandler does nothing when user click the button, developer could override <javadoc directory="zss"  method="doCustomSort">org.zkoss.zss.ui.sys.ActionHandler</javadoc>
+
<br/> By default, <b>ActionHandler</b> does nothing when users clicks the button, developers are able to override <javadoc directory="zss"  method="doCustomSort">org.zkoss.zss.ui.sys.ActionHandler</javadoc>
  
<source lang="java" high="2">
+
<source lang="java" highlight="2">
 
@Override
 
@Override
 
public void doCustomSort(Rect selection) {
 
public void doCustomSort(Rect selection) {
 
Spreadsheet spreadsheet = getSpreadsheet();
 
Spreadsheet spreadsheet = getSpreadsheet();
if (spreadsheet.getBook() != null && validSelection(selection)) {
+
if (spreadsheet.getBook() != null && isValidSelection(selection)) {
 
CustomSortDialog dialog = new CustomSortDialog(selection);
 
CustomSortDialog dialog = new CustomSortDialog(selection);
 
//omit
 
//omit
Line 128: Line 132:
 
====Hyperlink====
 
====Hyperlink====
 
[[File:ZKSsEss_Spreadsheet_Toolbar_hyperlink.png]]
 
[[File:ZKSsEss_Spreadsheet_Toolbar_hyperlink.png]]
<br/> The default ActionHandler does nothing when user click the button, developer could override <javadoc directory="zss"  method="doHyperlink">org.zkoss.zss.ui.sys.ActionHandler</javadoc>
+
<br/> By default, <b>ActionHandler</b> does nothing when users clicks the button, developers are able to override <javadoc directory="zss"  method="doHyperlink">org.zkoss.zss.ui.sys.ActionHandler</javadoc>
  
<source lang="java" high="2">
+
<source lang="java" highlight="2">
 
@Override
 
@Override
 
public void doHyperlink(Rect selection) {
 
public void doHyperlink(Rect selection) {
 
Spreadsheet spreadsheet = getSpreadsheet();
 
Spreadsheet spreadsheet = getSpreadsheet();
if (spreadsheet.getBook() != null && validSelection(selection)) {
+
if (spreadsheet.getBook() != null && isValidSelection(selection)) {
 
InsertHyperlinkDialog dialog = new InsertHyperlinkDialog(selection);
 
InsertHyperlinkDialog dialog = new InsertHyperlinkDialog(selection);
 
//omit
 
//omit
Line 140: Line 144:
 
}
 
}
 
</source>
 
</source>
 +
 +
====Close Book====
 +
 +
[[File:ZKSsEss_Spreadsheet_Toolbar_closeBookButton.png]]<br/>
 +
The default <javadoc directory="zss"  method="doCloseBook">org.zkoss.zss.ui.sys.ActionHandler</javadoc> will invoke <javadoc directory="zss"  method="toggleActionOnBookClosed">org.zkoss.zss.ui.sys.ActionHandler</javadoc>, developers can override it to disable or enable action by <javadoc directory="zss"  method="setActionDisabled">org.zkoss.zss.ui.Spreadsheet</javadoc>.
 +
 +
[[File:ZKSsEss_Spreadsheet_Toolbar_bookClosed.png]]<br/>
 +
 +
All those actions(toolbar buttons) are disabled when the book is closed and can be enabled by <javadoc directory="zss"  method="doSheetSelect">org.zkoss.zss.ui.sys.ActionHandler</javadoc>. It will invoke <javadoc directory="zss"  method="toggleActionOnSheetSelected">org.zkoss.zss.ui.sys.ActionHandler</javadoc> and developers  can override the method to enable or disable those actions.
 +
 +
====I18N====
 +
Each button/menuitem map to a key, developers can browse all I18 keys by <javadoc directory="zss"  method="getLabelKeys">org.zkoss.zss.ui.Action</javadoc>
 +
 +
Here are partial keys for the toolbar
 +
{| border="1"
 +
|-
 +
! Action  || I18 Key
 +
|-
 +
|| Paste || zss.paste
 +
|-
 +
|| Paste Formula || zss.pasteFormula
 +
|-
 +
|| Paste Value || zss.pasteValue
 +
|-
 +
|| Paste All Except Border || zss.pasteAllExceptBorder
 +
|-
 +
|| Paste Transpose || zss.pasteTranspose
 +
|-
 +
|| Paste Special || zss.pasteSpecial
 +
|-
 +
|| Merge And Center || zss.mergeAndCenter
 +
|-
 +
|| Merge Across || zss.mergeAcross
 +
|-
 +
|| Merge Cell|| zss.mergeCell
 +
|-
 +
|| Unmerge Cell || zss.unmergeCell
 +
|-
 +
|| Insert Cell|| zss.insertCell
 +
|-
 +
|| Shift Cell Right || zss.shiftCellRight
 +
|-
 +
|| Shift Cell Down || zss.shiftCellDown
 +
|-
 +
|| Insert Sheet Row || zss.insertSheetRow
 +
|-
 +
|| Insert Sheet Column || zss.insertSheetColumn
 +
|-
 +
|| Delete Cell || zss.deleteCell
 +
|-
 +
|| Shift Cell Left || zss.shiftCellLeft
 +
|-
 +
|| Shift Cell Up || zss.shiftCellUp
 +
|-
 +
|| Clear || zss.clear
 +
|-
 +
|| Clear Context || zss.clearContent
 +
|-
 +
|| Clear Style || zss.clearStyle
 +
|-
 +
|| Clear All || zss.clearAll
 +
|-
 +
|| sort || zss.sort
 +
|-
 +
|| Sort And Filter || zss.sortAndFilter
 +
|-
 +
|| Sort Ascending || zss.sortAscending
 +
|-
 +
|| Sort Descending || zss.sortDescending
 +
|-
 +
|| Custom Sort || zss.customSort
 +
|-
 +
|| Filter || zss.filter
 +
|-
 +
|| Clear Filter || zss.clearFilter
 +
|-
 +
|| Reapply Filter || zss.reapplyFilter
 +
|-
 +
|| Column Chart || zss.columnChart
 +
|-
 +
|| Column Chart 3D || zss.columnChart3D
 +
|-
 +
|| Line Chart || zss.lineChart
 +
|-
 +
|| Line Chart 3D|| zss.lineChart3D
 +
|-
 +
|| Pie Chart || zss.pieChart
 +
|-
 +
|| Bar Chart || zss.barChart
 +
|-
 +
|| Bar Chart 3D || zss.barChart3D
 +
|-
 +
|| Scatter Chart || zss.scatterChart
 +
|-
 +
|| Doughnut Chart || zss.doughnutChart
 +
|-
 +
|| Hyperlink || zss.hyperlink
 +
|}
 +
 +
Refer to sample [http://code.google.com/p/zkbooks/source/browse/trunk/zssessentials/examples/WebContent/WEB-INF/i3-label.properties i3-label.properties]
  
 
===ZUML===
 
===ZUML===
 
Here is a sample example ZUL file
 
Here is a sample example ZUL file
<source lang="xml" high="4">
+
<source lang="xml" highlight="4">
 
<zk>
 
<zk>
 
<window vflex="1" width="100%" apply="org.zkoss.zssessentials.config.ToolbarComposer">
 
<window vflex="1" width="100%" apply="org.zkoss.zssessentials.config.ToolbarComposer">
 
<button id="toggleToolbar" label="Toggle toolbar"/>
 
<button id="toggleToolbar" label="Toggle toolbar"/>
 
<spreadsheet showToolbar="true"
 
<spreadsheet showToolbar="true"
id="ss" vflex="true" width="100%"
+
id="spreadsheet" vflex="true" width="100%"
 
src="/WEB-INF/excel/config/ZSS-demo_sample.xlsx" maxcolumns="40" maxrows="200"
 
src="/WEB-INF/excel/config/ZSS-demo_sample.xlsx" maxcolumns="40" maxrows="200"
 
></spreadsheet>
 
></spreadsheet>
Line 156: Line 260:
  
 
===Composer===
 
===Composer===
The composer use <javadoc directory="zss"  method="setShowToolbar">org.zkoss.zss.ui.Spreadsheet</javadoc> to show or hide toolbar.
+
The composer uses <javadoc directory="zss"  method="setShowToolbar">org.zkoss.zss.ui.Spreadsheet</javadoc> to show or hide toolbar.
<source lang="java" high="3">
+
<source lang="java" highlight="3">
 
public void onClick$toggleToolbar() {
 
public void onClick$toggleToolbar() {
 
boolean isShowToolbar = spreadsheet.isShowToolbar();
 
boolean isShowToolbar = spreadsheet.isShowToolbar();

Latest revision as of 12:56, 19 January 2022



Stop.png This article is out of date, please refer to http://books.zkoss.org/wiki/ZK_Spreadsheet_Essentials for more up to date information.


Purpose

ZK Spreadsheet supports various toolbar buttons to perform actions.

Show toolbar

Use Spreadsheet.setShowToolbar to show toolbar.

Action Handler

ZK Spreadsheet uses a default ActionHandler to perform toolbar button's actions. Developers are able to set customized ActionHandler by API Spreadsheet.setActionHandler or by library property org.zkoss.zss.ui.ActionHandler.class, please refer to sample zk.xml

Each spreadsheet instance uses it own ActionHandler which cannot be shared across different spreadsheet instances.


Each toolbar's button represents an action, the ActionHandler processes the action when clicked by a user.
For example, the 'paste' toolbarbutton and menuitem are represented by Action.PASTE, developers are able to override default behavior by using ActionHandler.doPaste
ZKSsEss Spreadsheet Toolbar paste.png

New Book

ZKSsEss Spreadsheet Toolbar newBook.png
The default ActionHandler does nothing when users clicks the button, developers are able to override ActionHandler.doNewBook

	@Override
	public void doNewBook() {
		getSpreadsheet().setSrc("/WEB-INF/excel/config/blank.xlsx");
	}

Refer to sample code CustomizedActionHandler.java

Save Book

ZKSsEss Spreadsheet Toolbar saveBook.png
The default ActionHandler does nothing when users clicks the button, developers are able to override ActionHandler.doSaveBook

	@Override
	public void doSaveBook() {
		Spreadsheet spreadsheet = getSpreadsheet();
		if (spreadsheet.getBook() != null) {
			final String filePath = Executions.getCurrent().getDesktop().getWebApp().getRealPath(spreadsheet.getSrc());
			
			Exporter exporter = Exporters.getExporter("excel");
			FileOutputStream outputStream = null;
			try {
				outputStream = new FileOutputStream(new File(filePath));
				exporter.export(spreadsheet.getBook(), outputStream);
				try {
					Messagebox.show("Saved");
				} catch (InterruptedException e) {
				}
			} catch (FileNotFoundException e) {
				try {
					Messagebox.show("Save excel failed");
				} catch (InterruptedException e1) {
				}
			} finally {
				if (outputStream != null) {
					try {
						outputStream.close();
					} catch (IOException e) {
					}
				}
			}
		}			
	}

Refer to Export to Excel sample code CustomizedActionHandler.java

Export PDF

ZKSsEss Spreadsheet Toolbar exportPDF.png
The default ActionHandler does nothing when users clicks the button, developers are able to override ActionHandler.doExportPDF

	@Override
	public void doExportPDF(Rect selection) {
		Spreadsheet spreadsheet = getSpreadsheet();
		if (spreadsheet.getBook() != null && isValidSelection(selection)) {
			ExportPDFDialog dialog = new ExportPDFDialog(selection);
			//omit
		}
	}

Refer to Export to PDF and sample code exportPDFDialog.zulCustomizedActionHandler.java

Paste Special

ZKSsEss Spreadsheet Toolbar pasteSpecial.png
By default, ActionHandler does nothing when users clicks the button, developers are able to override ActionHandler.doPasteSpecial

	@Override
	public void doPasteSpecial(Rect selection) {
		Spreadsheet spreadsheet = getSpreadsheet();
		if (spreadsheet.getBook() != null && isValidSelection(selection)) {
			PasteSpecialDialog dialog = new PasteSpecialDialog(selection);
			//omit
		}
	}

Refer to sample code pasteSpecialDialog.zul and CustomizedActionHandler.java

Custom Sort

ZKSsEss Spreadsheet Toolbar customSort.png
By default, ActionHandler does nothing when users clicks the button, developers are able to override ActionHandler.doCustomSort

	@Override
	public void doCustomSort(Rect selection) {
		Spreadsheet spreadsheet = getSpreadsheet();
		if (spreadsheet.getBook() != null && isValidSelection(selection)) {
			CustomSortDialog dialog = new CustomSortDialog(selection);
			//omit	
		}
	}

Refer to sample code customSortDialog.zul and CustomizedActionHandler.java

Hyperlink

ZKSsEss Spreadsheet Toolbar hyperlink.png
By default, ActionHandler does nothing when users clicks the button, developers are able to override ActionHandler.doHyperlink

	@Override
	public void doHyperlink(Rect selection) {
		Spreadsheet spreadsheet = getSpreadsheet();
		if (spreadsheet.getBook() != null && isValidSelection(selection)) {
			InsertHyperlinkDialog dialog = new InsertHyperlinkDialog(selection);
			//omit	
		}
	}

Close Book

ZKSsEss Spreadsheet Toolbar closeBookButton.png
The default ActionHandler.doCloseBook will invoke ActionHandler.toggleActionOnBookClosed, developers can override it to disable or enable action by Spreadsheet.setActionDisabled.

ZKSsEss Spreadsheet Toolbar bookClosed.png

All those actions(toolbar buttons) are disabled when the book is closed and can be enabled by ActionHandler.doSheetSelect. It will invoke ActionHandler.toggleActionOnSheetSelected and developers can override the method to enable or disable those actions.

I18N

Each button/menuitem map to a key, developers can browse all I18 keys by Action.getLabelKeys

Here are partial keys for the toolbar

Action I18 Key
Paste zss.paste
Paste Formula zss.pasteFormula
Paste Value zss.pasteValue
Paste All Except Border zss.pasteAllExceptBorder
Paste Transpose zss.pasteTranspose
Paste Special zss.pasteSpecial
Merge And Center zss.mergeAndCenter
Merge Across zss.mergeAcross
Merge Cell zss.mergeCell
Unmerge Cell zss.unmergeCell
Insert Cell zss.insertCell
Shift Cell Right zss.shiftCellRight
Shift Cell Down zss.shiftCellDown
Insert Sheet Row zss.insertSheetRow
Insert Sheet Column zss.insertSheetColumn
Delete Cell zss.deleteCell
Shift Cell Left zss.shiftCellLeft
Shift Cell Up zss.shiftCellUp
Clear zss.clear
Clear Context zss.clearContent
Clear Style zss.clearStyle
Clear All zss.clearAll
sort zss.sort
Sort And Filter zss.sortAndFilter
Sort Ascending zss.sortAscending
Sort Descending zss.sortDescending
Custom Sort zss.customSort
Filter zss.filter
Clear Filter zss.clearFilter
Reapply Filter zss.reapplyFilter
Column Chart zss.columnChart
Column Chart 3D zss.columnChart3D
Line Chart zss.lineChart
Line Chart 3D zss.lineChart3D
Pie Chart zss.pieChart
Bar Chart zss.barChart
Bar Chart 3D zss.barChart3D
Scatter Chart zss.scatterChart
Doughnut Chart zss.doughnutChart
Hyperlink zss.hyperlink

Refer to sample i3-label.properties

ZUML

Here is a sample example ZUL file

<zk>
	<window vflex="1" width="100%" apply="org.zkoss.zssessentials.config.ToolbarComposer">
		<button id="toggleToolbar" label="Toggle toolbar"/>
		<spreadsheet showToolbar="true"
			id="spreadsheet" vflex="true" width="100%"
			src="/WEB-INF/excel/config/ZSS-demo_sample.xlsx" maxcolumns="40" maxrows="200"
			></spreadsheet>
	</window>
</zk>

Composer

The composer uses Spreadsheet.setShowToolbar to show or hide toolbar.

	public void onClick$toggleToolbar() {
		boolean isShowToolbar = spreadsheet.isShowToolbar();
		spreadsheet.setShowToolbar(!isShowToolbar);
	}

See the full source code for Composer here

Version History

Last Update : 2022/01/19


Version Date Content
2.3.0 April, 2012 Toolbar
     


All source code listed in this book is at Github.


Last Update : 2022/01/19

Copyright © Potix Corporation. This article is licensed under GNU Free Documentation License.