Add the Element#show() and Element#hide() methods, fixing the missing…

… API (#151)

CHANGELOG

@@ -1,4 +1,10 @@
 
+v1.47.2
+-------
+
+Add the Element#show() and Element#hide() methods, fixing the missing API (#151)
+
+
 v1.47.1
 -------
 

doc/Element.md

@@ -24,6 +24,8 @@
 	* [.topZ()](#ref.Element.topZ)
 	* [.bottomZ()](#ref.Element.bottomZ)
 	* [.setContent()](#ref.Element.setContent)
+	* [.show()](#ref.Element.show)
+	* [.hide()](#ref.Element.hide)
 	* [.draw()](#ref.Element.draw)
 	* [.redraw()](#ref.Element.redraw)
 	* [.drawCursor()](#ref.Element.drawCursor)
@@ -122,6 +124,24 @@ Set the content of this *element*.
 
 
 
+<a name="ref.Element.show"></a>
+### .show( [dontDraw] )
+
+* dontDraw `boolean` when set (default: false) the element is not redrawn (it will be made visible the next time something trigger a *redraw*)
+
+Turn the element visibility **on** and redraw it immediately (unless the `dontDraw` option is on).
+
+
+
+<a name="ref.Element.show"></a>
+### .hide( [dontDraw] )
+
+* dontDraw `boolean` when set (default: false) the element is not redrawn (it will be hidden the next time something trigger a *redraw* on its parent)
+
+Turn the element visibility **off** and redraw its parent immediately (unless the `dontDraw` option is on).
+
+
+
 <a name="ref.Element.draw"></a>
 ### .draw()
 
@@ -132,7 +152,10 @@ It is called internally/automatically, userland code should not be bothered with
 
 
 <a name="ref.Element.redraw"></a>
-### .redraw()
+### .redraw( [force] )
+
+* force `boolean` **INTERNAL** when set (default: false) the element is *redrawn* even if it is hidden: i.e. the parent is redrawn,
+  it would effectively clear an hidden element from its parent
 
 Redraw the *element*.
 While `.draw()` is used when drawing the current *element* is enough (the *element* has not moved, and has not been resized),

lib/document/Element.js

@@ -156,6 +156,29 @@ Element.prototype.destroy = function( isSubDestroy = false , noDraw = false ) {
 
 
 
+Element.prototype.show = function( noDraw = false ) {
+	if ( ! this.hidden ) { return this ; }
+	this.hidden = false ;
+	if ( ! noDraw ) { this.redraw() ; }
+	return this ;
+} ;
+
+
+
+Element.prototype.hide = function( noDraw = false ) {
+	if ( this.hidden ) { return this ; }
+	this.hidden = true ;
+
+	if ( ! noDraw ) {
+		// .redraw() with the 'force' option on, because .redraw() does nothing if the element is hidden, but here we want to clear it from its parent
+		this.redraw( true ) ;
+	}
+
+	return this ;
+} ;
+
+
+
 // Clear the Element, destroy all children
 Element.prototype.clear = function() {
 	var i , iMax ;
@@ -617,8 +640,9 @@ Element.prototype.draw = function( isInitialInlineDraw = false ) {
 // If it has, then it is necessary to draw the closest ancestor which is a container.
 // /!\ THIS METHOD IS WRONG: it should draw the parent container, but don't redraw any children of its children Container
 // /!\ Maybe rename this .outerDraw() or .parentDraw()
-Element.prototype.redraw = function() {
-	if ( ! this.document || this.hidden ) { return this ; }
+// Option 'force' redraw even if the element is hidden, in fact it is used by the .hide() method to effectively hide the element on the parent container.
+Element.prototype.redraw = function( force = false ) {
+	if ( ! this.document || ( this.hidden && ! force ) ) { return this ; }
 
 	var container = this.getParentContainer() ;
 

lib/document/SelectList.js

@@ -62,16 +62,16 @@ function SelectList( options ) {
 
 	ColumnMenu.call( this , options ) ;
 
-	this.show = false ;
+	this.showMenu = false ;
 	this.zIndexRef = this.zIndex ;	// Back-up for zIndex
 
 	if ( options.value !== undefined && this.setValue( options.value , true ) ) {
 		// .initPage() is called by .setValue() only when a correct value was found
-		this.toggle( this.show , options.noDraw ) ;
+		this.toggle( this.showMenu , options.noDraw ) ;
 	}
 	else {
 		this.initPage() ;
-		this.toggle( this.show , options.noDraw ) ;
+		this.toggle( this.showMenu , options.noDraw ) ;
 	}
 
 
@@ -127,26 +127,26 @@ SelectList.prototype.destroy = function( isSubDestroy , noDraw = false ) {
 
 
 
-SelectList.prototype.toggle = function( show = null , noDraw = false ) {
+SelectList.prototype.toggle = function( showMenu = null , noDraw = false ) {
 	var i , iMax ;
 
-	if ( show === null ) { this.show = ! this.show ; }
-	else { this.show = !! show ; }
+	if ( showMenu === null ) { this.showMenu = ! this.showMenu ; }
+	else { this.showMenu = !! showMenu ; }
 
 	for ( i = 1 , iMax = this.buttons.length ; i < iMax ; i ++ ) {
-		this.buttons[ i ].hidden = ! this.show ;
+		this.buttons[ i ].hidden = ! this.showMenu ;
 	}
 
 	// Adjust outputHeight, to avoid the list to be clickable when reduced
-	this.outputHeight = this.show ? this.pageHeight : 1 ;
+	this.outputHeight = this.showMenu ? this.pageHeight : 1 ;
 
-	if ( this.show ) { this.topZ() ; }
+	if ( this.showMenu ) { this.topZ() ; }
 	else { this.restoreZ() ; }
 
 	// Return now if noDraw is set, bypassing both drawing and focus
 	if ( noDraw ) { return ; }
 
-	if ( show ) {
+	if ( showMenu ) {
 		for ( i = 1 , iMax = this.buttons.length ; i < iMax ; i ++ ) {
 			if ( this.buttons[ i ].value === this.value ) {
 				this.document.giveFocusTo( this.buttons[ i ] ) ;

lib/document/SelectListMulti.js

@@ -62,11 +62,11 @@ function SelectListMulti( options ) {
 
 	ColumnMenuMulti.call( this , options ) ;
 
-	this.show = false ;
+	this.showMenu = false ;
 	this.zIndexRef = this.zIndex ;	// Back-up for zIndex
 
 	this.initPage() ;
-	this.toggle( this.show , options.noDraw ) ;
+	this.toggle( this.showMenu , options.noDraw ) ;
 
 	this.onClickOut = this.onClickOut.bind( this ) ;
 
@@ -120,20 +120,20 @@ SelectListMulti.prototype.destroy = function( isSubDestroy , noDraw = false ) {
 
 
 
-SelectListMulti.prototype.toggle = function( show = null , noDraw = false ) {
+SelectListMulti.prototype.toggle = function( showMenu = null , noDraw = false ) {
 	var i , iMax ;
 
-	if ( show === null ) { this.show = ! this.show ; }
-	else { this.show = !! show ; }
+	if ( showMenu === null ) { this.showMenu = ! this.showMenu ; }
+	else { this.showMenu = !! showMenu ; }
 
 	for ( i = 1 , iMax = this.buttons.length ; i < iMax ; i ++ ) {
-		this.buttons[ i ].hidden = ! this.show ;
+		this.buttons[ i ].hidden = ! this.showMenu ;
 	}
 
 	// Adjust outputHeight, to avoid the list to be clickable when reduced
-	this.outputHeight = this.show ? this.pageHeight : 1 ;
+	this.outputHeight = this.showMenu ? this.pageHeight : 1 ;
 
-	if ( this.show ) { this.topZ() ; }
+	if ( this.showMenu ) { this.topZ() ; }
 	else { this.restoreZ() ; }
 
 	// Return now if noDraw is set, bypassing both drawing and focus
@@ -158,7 +158,7 @@ SelectListMulti.prototype.onButtonSubmit = function( buttonValue , action , butt
 			this.toggle() ;
 
 			// Submit when reducing
-			if ( ! this.show ) {
+			if ( ! this.showMenu ) {
 				this.emit( 'submit' , this.value , action , this ) ;
 			}
 			break ;
@@ -170,7 +170,7 @@ SelectListMulti.prototype.onButtonSubmit = function( buttonValue , action , butt
 
 
 SelectListMulti.prototype.onClickOut = function() {
-	if ( this.show ) {
+	if ( this.showMenu ) {
 		this.toggle( false ) ;
 		// We also submit when the menu is closed on click out
 		this.emit( 'submit' , this.value , undefined , this ) ;

package.json

@@ -1,6 +1,6 @@
 {
   "name": "terminal-kit",
-  "version": "1.47.1",
+  "version": "1.47.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/buttons-test.js

@@ -124,6 +124,7 @@ function onBlinked( value , action ) {
 function onToggle( value ) {
 	term.saveCursor() ;
 	term.moveTo.styleReset.eraseLine( 1 , 22 , 'Toggled #%i: %J\n' , counter ++ , value ) ;
+	//if ( value ) { button1.hide() ; } else { button1.show() ; }
 	term.restoreCursor() ;
 }