Navigation

SpreadJS supports navigation actions defined in GC.Spread.Sheets.Commands. These actions allow you to navigate the Spread instance in script code without needing to have the user do it.

<p>This can be useful when you have business logic that may depend on navigating in the Spread instance.</p> <ul> <li><strong>moveToNextCell: Moves to next cell (default action of Tab).</strong></li> <li><strong>moveToPreviousCell: Moves to previous cell (default action of Shift + Tab).</strong></li> <li><strong>selectNextControl: Selects spread.nextControl specified element or auto detected one if not set.</strong></li> <li><strong>selectPreviousControl: Selects spread.previousControl specified element or auto detected one if not set.</strong></li> <li><strong>moveToNextCellThenControl: Moves to next cell if the active cell is the last visible cell, then selects next control.</strong></li> <li><strong>moveToPreviousCellThenControl: Moves to previous cell if the active cell is the first visible cell, then selects previous control.</strong></li> </ul> <p>Set the selected control using the <strong>nextControl</strong> and <strong>previousControl</strong> methods. For example:</p> <pre><code class="hljs js language-js"> <span class="hljs-comment">// set next &amp; previous control</span> spread.nextControl(<span class="hljs-built_in">document</span>.getElementById(<span class="hljs-string">'myNextControl'</span>)); spread.previousControl(<span class="hljs-built_in">document</span>.getElementById(<span class="hljs-string">'myPreviousControl'</span>)); <span class="hljs-comment">// set the value to undefined without using auto detect</span> spread.nextControl(<span class="hljs-literal">undefined</span>); </code></pre> <p>Use the <strong>register</strong> method to set navigation keys and the corresponding actions. For example:</p> <pre><code class="hljs js language-js"> <span class="hljs-comment">// set Tab to select next control</span> spread.commandManager().register(<span class="hljs-string">'selectNextControl'</span>, GC.Spread.Sheets.Commands.selectNextControl, GC.Spread.Commands.Key.tab, <span class="hljs-literal">false</span>, <span class="hljs-literal">false</span>, <span class="hljs-literal">false</span>, <span class="hljs-literal">false</span>); <span class="hljs-comment">// set Shift + Tab to select previous control</span> spread.commandManager().register(<span class="hljs-string">'selectPreviousControl'</span>, GC.Spread.Sheets.Commands.selectPreviousControl, GC.Spread.Commands.Key.tab, <span class="hljs-literal">false</span>, <span class="hljs-literal">true</span>, <span class="hljs-literal">false</span>, <span class="hljs-literal">false</span>); </code></pre> <p>The arguments of <strong>register</strong> in order are:</p> <ul> <li><strong>name: The name of the command.</strong></li> <li><strong>execute: The execution function of the command.</strong></li> <li><strong>key: The unicode for the key.</strong></li> <li><strong>ctrl: True if the action uses the Ctrl key; otherwise, false.</strong></li> <li><strong>shift: True if the action uses the Shift key; otherwise, false.</strong></li> <li><strong>alt: True if the action uses the Alt key; otherwise, false.</strong></li> <li><strong>meta: True if the action uses the Command key on the Macintosh or the Windows key on Microsoft Windows; otherwise, false.</strong></li> </ul> <p>Use the <strong>hideSelection</strong> option to hide the selection when Spread loses the focus. For example:</p> <pre><code class="hljs js language-js"> spread.options.hideSelection = <span class="hljs-literal">true</span>; </code></pre>
window.onload = function () { var spread = new GC.Spread.Sheets.Workbook(document.getElementById("ss"), { sheetCount: 1 }); initSpread(spread); }; function initSpread(spread) { var sheet = spread.getSheet(0); sheet.setRowCount(20); sheet.setColumnCount(10); sheet.addSpan(0, 0, 1, 7); sheet.setValue(0, 0, "press the \'Tab\' or \'Shift + Tab\' key, the selction will move in accordance."); _getElementById("preButton").addEventListener('click',_alertHandle); _getElementById("nextButton").addEventListener('click',_alertHandle); function _alertHandle(){ alert(this.value); } _getElementById("tabAction").addEventListener('change',_moveHandle); _getElementById("shiftTabAction").addEventListener('change',_moveHandle); function _moveHandle(){ var id = this.id, isShift = id.indexOf("shift") === 0, value = parseInt(this.value, 10), actions = GC.Spread.Sheets.Commands, action; switch (value) { case 0: action = isShift ? actions.moveToPreviousCell : actions.moveToNextCell; break; case 1: action = isShift ? actions.selectPreviousControl : actions.selectNextControl; break; case 2: action = isShift ? actions.moveToPreviousCellThenControl : actions.moveToNextCellThenControl; break; } if (action) { spread.commandManager().register("customCommand"+ new Date().valueOf(), action, GC.Spread.Commands.Key.tab, false, isShift, false, false); } } _getElementById("nextControl").addEventListener('change',_handle); _getElementById("preControl").addEventListener('change',_handle); function _handle(){ var id = this.id, isPre = id.indexOf("pre") === 0, value = this.value, control = value ? document.getElementById(value) : undefined; if (isPre) { spread.previousControl(control); } else { spread.nextControl(control); } } _getElementById("hideSelection").addEventListener('click',function () { spread.options.hideSelection = this.checked; }); }; function _getElementById(id){ return document.getElementById(id); }
<!doctype html> <html style="height:100%;font-size:14px;"> <head> <meta charset="utf-8" /> <meta name="viewport" content="width=device-width, initial-scale=1.0" /> <link rel="stylesheet" type="text/css" href="$DEMOROOT$/en/purejs/node_modules/@grapecity/spread-sheets/styles/gc.spread.sheets.excel2013white.css"> <script src="$DEMOROOT$/en/purejs/node_modules/@grapecity/spread-sheets/dist/gc.spread.sheets.all.min.js" type="text/javascript"></script> <script src="$DEMOROOT$/spread/source/js/license.js" type="text/javascript"></script> <script src="app.js" type="text/javascript"></script> <link rel="stylesheet" type="text/css" href="styles.css"> </head> <body> <div class="sample-tutorial"> <div id="ss" class="sample-spreadsheets"></div> <div class="options-container"> <p>Change the “Tab for:” field to “Next Control” then click the Spread instance to give it focus.</p> <p>Hit the Tab key and observe that the focus moves to the “Previous Edit” text box on this page.</p> <p>You can utilize this functionality to change what specific navigation keys do in Spread.</p> <div class="option-row" style="margin-bottom: 10px;"> <input type="text" id="preEdit" placeholder="Previous Edit" title="Candidate previous control" /> <input type="button" id="preButton" title="Candidate previous control too" value="Previous Button" /> </div> <div class="option-row"> <input type="text" id="nextEdit" placeholder="Next Edit" title="Candidate next control" /> <input type="button" id="nextButton" title="Candidate next control too" value="Next Button" /> </div> <div class="option-row"> <label>Tab for:</label> <select id="tabAction"> <option value="0" selected="selected">Next cell</option> <option value="1">Next control</option> <option value="2">Next cell then control</option> </select> <label class="colorLabel">This controls which navigation action happens when the user presses Tab.</label> </div> <div class="option-row"> <label>Shift + Tab for:</label> <select id="shiftTabAction"> <option value="0" selected="selected">Previous cell</option> <option value="1">Previous control</option> <option value="2">Previous cell then control</option> </select> <label class="colorLabel">This controls which navigation action happens when the user presses Shift+Tab.</label> </div> <div class="option-row"> <label>Next control:</label> <select id="nextControl"> <option value="" selected="selected">Not set (auto detect)</option> <option value="nextEdit">Next Edit</option> <option value="nextButton">Next Button</option> </select> <label class="colorLabel">This defines which control is the next control in relation to the Spread instance.</label> </div> <div class="option-row"> <label>Previous control:</label> <select id="preControl"> <option value="" selected="selected">Not set (auto detect)</option> <option value="preEdit">Previous Edit</option> <option value="preButton">Previous Button</option> </select> <label class="colorLabel">This defines which control is the previous control in relation to the Spread instance.</label> </div> <div class="option-row"> <input type="checkbox" id="hideSelection" /> <label for="hideSelection">Hide Selection</label> <label class="colorLabel">Checking this box will hide the selection in the Spread instance.</label> </div> </div> </div> </body> </html>
.sample-tutorial { position: relative; height: 100%; overflow: hidden; } .sample-spreadsheets { width: calc(100% - 280px); height: 100%; overflow: hidden; float: left; } .options-container { float: right; width: 280px; padding: 12px; height: 100%; box-sizing: border-box; background: #fbfbfb; overflow: auto; } .option-row { font-size: 14px; padding: 5px; margin-top: 10px; } .options-toggle { display: none; } input, select { padding: 4px 6px; margin: 4px 0; width: 100%; box-sizing: border-box; } input[type=checkbox] { width: auto; } .colorLabel { width: auto; color: #606060; display: block; } .demo-options { margin-top: 5px; } p{ padding:2px 10px; background-color:lavender; } body { position: absolute; top: 0; bottom: 0; left: 0; right: 0; }