New Document's Element API: .destroyNoRedraw() ; ColumnMenu (and Base…

…Menu): improved key navigation ; Dependencies upgraded

.npmignore

@@ -60,3 +60,4 @@ test
 log
 sample
 wfm.json
+builder

CHANGELOG

@@ -1,4 +1,12 @@
 
+v3.0.2
+------
+
+New Document's Element API: .destroyNoRedraw()
+ColumnMenu (and BaseMenu): improved key navigation
+Dependencies upgraded
+
+
 v3.0.1
 ------
 

doc/Element.md

@@ -20,6 +20,8 @@
  * [new Element()](#ref.Element.new)
 
 * Methods:
+ * [.destroy()](#ref.Element.destroy)
+ * [.destroyNoRedraw()](#ref.Element.destroyNoRedraw)
  * [.updateZ() / .updateZIndex()](#ref.Element.updateZ)
  * [.topZ()](#ref.Element.topZ)
  * [.bottomZ()](#ref.Element.bottomZ)
@@ -88,6 +90,23 @@ This contains all `options` that are common across all/many widgets.
 
 
 
+<a name="ref.Element.destroy"></a>
+### .destroy()
+
+It destroys the *element* immediately, and triggers all draw/redraw necessary to remove it from the screen now.
+
+
+
+<a name="ref.Element.destroyNoRedraw"></a>
+### .destroyNoRedraw()
+
+It destroys the *element* immediately, but nothing is redrawn, so the *element* is still visible until the next redraw.
+
+It is usually done when there is a lot of *elements* to remove at once, to avoid redrawing the screen for each one, which would dramatically slow down the app.
+Instead of `.destroy()`, it's best to use `.destroyNoRedraw()` each *element*, and then to call `document.draw()` once done.
+
+
+
 <a name="ref.Element.updateZ"></a>
 ### .updateZ( z ) / .updateZIndex( z )
 

lib/document/BaseMenu.js

@@ -154,14 +154,28 @@ BaseMenu.prototype.destroy = function( isSubDestroy , noDraw = false ) {
 
 
 
-BaseMenu.prototype.previousPage = function( focusType ) {
- var focusAware ;
+BaseMenu.prototype.focusFirstPageItem = function( focusType ) {
+ this.focusChild = this.children[ this.page ? 1 : 0 ] ;
+ var focusAware = this.document.giveFocusTo_( this.focusChild , focusType ) ;
+ if ( ! focusAware ) { this.document.focusNext() ; }
+} ;
+
 
+
+BaseMenu.prototype.focusLastPageItem = function( focusType ) {
+ this.focusChild = this.children[ this.page === this.maxPage ? this.children.length - 1 : this.children.length - 2 ] ;
+ var focusAware = this.document.giveFocusTo_( this.focusChild , focusType ) ;
+ if ( ! focusAware ) { this.document.focusNext() ; }
+} ;
+
+
+
+BaseMenu.prototype.previousPage = function( focusType ) {
  if ( this.maxPage && this.page > 0 ) {
  this.page -- ;
  this.initPage() ;
  this.focusChild = this.children[ this.children.length - 2 ] ;
- focusAware = this.document.giveFocusTo_( this.focusChild , focusType ) ;
+ let focusAware = this.document.giveFocusTo_( this.focusChild , focusType ) ;
  if ( ! focusAware ) { this.document.focusPrevious() ; }
  this.updateDraw() ;
  this.emit( 'previousPage' , this.page , this ) ;
@@ -171,13 +185,11 @@ BaseMenu.prototype.previousPage = function( focusType ) {
 
 
 BaseMenu.prototype.nextPage = function( focusType ) {
- var focusAware ;
-
  if ( this.maxPage && this.page < this.maxPage ) {
  this.page ++ ;
  this.initPage() ;
  this.focusChild = this.children[ 1 ] ;
- focusAware = this.document.giveFocusTo_( this.focusChild , focusType ) ;
+ let focusAware = this.document.giveFocusTo_( this.focusChild , focusType ) ;
  if ( ! focusAware ) { this.document.focusNext() ; }
  this.updateDraw() ;
  this.emit( 'nextPage' , this.page , this ) ;
@@ -187,13 +199,11 @@ BaseMenu.prototype.nextPage = function( focusType ) {
 
 
 BaseMenu.prototype.toPage = function( page , focusType ) {
- var focusAware ;
-
  if ( this.maxPage && page !== this.page ) {
  this.page = page ;
  this.initPage() ;
  this.focusChild = this.children[ this.page ? 1 : 0 ] ;
- focusAware = this.document.giveFocusTo_( this.focusChild , focusType ) ;
+ let focusAware = this.document.giveFocusTo_( this.focusChild , focusType ) ;
  if ( ! focusAware ) { this.document.focusNext() ; }
  this.updateDraw() ;
  }
@@ -477,24 +487,44 @@ userActions.previousPage = function() {
  if ( this.maxPage && this.page > 0 ) {
  this.previousPage( 'backCycle' ) ;
  }
+ else {
+ this.focusFirstPageItem( 'backCycle' ) ;
+ }
 } ;
 
 userActions.nextPage = function() {
  if ( this.maxPage && this.page < this.maxPage ) {
  this.nextPage( 'cycle' ) ;
  }
+ else {
+ this.focusLastPageItem( 'cycle' ) ;
+ }
 } ;
 
 userActions.firstPage = function() {
  if ( this.maxPage && this.page !== 0 ) {
  this.toPage( 0 , 'backCycle' ) ;
  }
+ else {
+ this.focusFirstPageItem( 'backCycle' ) ;
+ }
 } ;
 
 userActions.lastPage = function() {
  if ( this.maxPage && this.page !== this.maxPage ) {
  this.toPage( this.maxPage , 'cycle' ) ;
  }
+ else {
+ this.focusLastPageItem( 'cycle' ) ;
+ }
+} ;
+
+userActions.firstPageItem = function() {
+ this.focusFirstPageItem( 'backCycle' ) ;
+} ;
+
+userActions.lastPageItem = function() {
+ this.focusLastPageItem( 'cycle' ) ;
 } ;
 
 userActions.parentMenu = function() {

lib/document/ColumnMenu.js

@@ -317,6 +317,7 @@ ColumnMenu.prototype.initPage = function( page = this.page ) {
 
  this.buttons.forEach( button => button.destroy( false , true ) ) ;
  this.buttons.length = 0 ;
+ this.hotkeyToButtonIndex.clear() ;
 
  this.pageItemsDef[ page ].forEach( ( def , index ) => {
  var ButtonConstructor , isToggle , key , value , blurAttr ;
@@ -407,6 +408,15 @@ ColumnMenu.prototype.initPage = function( page = this.page ) {
  this.buttons[ index ].on( 'blinked' , this.onButtonBlinked ) ;
  this.buttons[ index ].on( 'focus' , this.onButtonFocus ) ;
 
+ if ( def.hotkey ) {
+ if ( Array.isArray( def.hotkey ) ) {
+ def.hotkey.forEach( hotkey => this.hotkeyToButtonIndex.set( hotkey , index ) ) ;
+ }
+ else {
+ this.hotkeyToButtonIndex.set( def.hotkey , index ) ;
+ }
+ }
+
  if ( isToggle ) {
  this.buttons[ index ].on( 'toggle' , this.onButtonToggle ) ;
  }

lib/document/Element.js

@@ -170,6 +170,9 @@ Element.prototype.destroy = function( isSubDestroy = false , noDraw = false ) {
  this.destroyed = true ;
 } ;
 
+// User API
+Element.prototype.destroyNoRedraw = function() { return this.destroy( undefined , true ) ; } ;
+
 
 
 Element.inherit = function( Class , FromClass = Element ) {

package.json

@@ -1,6 +1,6 @@
 {
  "name": "terminal-kit",
- "version": "3.0.1",
+ "version": "3.0.2",
  "description": "256 colors, keys and mouse, input field, progress bars, screen buffer (including 32-bit composition and image loading), text buffer, and many more... Whether you just need colors and styles, build a simple interactive command line tool or a complexe terminal app: this is the absolute terminal lib for Node.js!",
  "main": "lib/termkit.js",
  "directories": {

sample/document/object-viewer.js

@@ -92,7 +92,8 @@ function exploreSubObject( document , stack ) {
  if ( stack.length > 1 ) {
  menuItems.push( {
  content: '..' ,
- internalRole: 'parent'
+ internalRole: 'parent' ,
+ hotkey: [ 'BACKSPACE' ]
  } ) ;
  }
 
@@ -142,7 +143,7 @@ function exploreSubObject( document , stack ) {
 
 
  function onPageInit( page ) {
- for ( let text of textFields ) { text.destroy() ; }
+ for ( let text of textFields ) { text.destroyNoRedraw() ; }
  textFields.length = 0 ;
 
  for ( let button of columnMenu.buttons ) {
@@ -205,11 +206,14 @@ function exploreSubObject( document , stack ) {
  x: button.outputX + button.outputWidth + 2 ,
  y: button.outputY ,
  attr: textAttr ,
- content: textContent
+ content: textContent ,
+ noDraw: true
  } ) ;
 
  textFields.push( text ) ;
  }
+
+ document.draw() ;
  }
 
 
@@ -232,10 +236,11 @@ function exploreSubObject( document , stack ) {
 
 
  function close() {
- for ( let text of textFields ) { text.destroy() ; }
+ for ( let text of textFields ) { text.destroyNoRedraw() ; }
  textFields.length = 0 ;
- columnMenu.destroy() ;
- breadCrumbText.destroy() ;
+ columnMenu.destroyNoRedraw() ;
+ breadCrumbText.destroyNoRedraw() ;
+ document.draw() ;
  promise.resolve() ;
  }