patch 8.0.0898: can't use the alternate screen in a terminal window

Problem:    Can't use the alternate screen in a terminal window.
Solution:   Initialze the alternate screen. (Yasuhiro Matsumoto, closes
            #1957)  Add term_getaltscreen().

runtime/doc/eval.txt

@@ -2369,6 +2369,7 @@ tagfiles()			List	tags files used
 tan({expr})			Float	tangent of {expr}
 tanh({expr})			Float	hyperbolic tangent of {expr}
 tempname()			String	name for a temporary file
+term_getaltscreen({buf})	Number	get the alternate screen flag
 term_getattr({attr}, {what})	Number	get the value of attribute {what}
 term_getcursor({buf})		List	get the cursor position of a terminal
 term_getjob({buf})		Job	get the job associated with a terminal
@@ -7914,6 +7915,12 @@ tempname()					*tempname()* *temp-file-name*
 		For MS-Windows forward slashes are used when the 'shellslash'
 		option is set or when 'shellcmdflag' starts with '-'.
 
+term_getaltscreen({buf})				*term_getaltscreen()*
+		Returns 1 if the terminal of {buf} is using the alternate
+		screen.
+		{buf} is used as with |term_getsize()|.
+		{only available when compiled with the |+terminal| feature}
+
 term_getattr({attr}, {what})				*term_getattr()*
 		Given {attr}, a value returned by term_scrape() in the "attr"
 		item, return whether {what} is on.  {what} can be one of:

src/evalfunc.c

@@ -831,6 +831,7 @@ static struct fst
 #endif
     {"tempname",	0, 0, f_tempname},
 #ifdef FEAT_TERMINAL
+    {"term_getaltscreen", 1, 1, f_term_getaltscreen},
     {"term_getattr",	2, 2, f_term_getattr},
     {"term_getcursor",	1, 1, f_term_getcursor},
     {"term_getjob",	1, 1, f_term_getjob},

src/libvterm/include/vterm.h

@@ -188,6 +188,8 @@ void vterm_keyboard_start_paste(VTerm *vt);
 void vterm_keyboard_end_paste(VTerm *vt);
 
 void vterm_mouse_move(VTerm *vt, int row, int col, VTermModifier mod);
+/* "button" is 1 for left, 2 for middle, 3 for right.
+ * Button 4 is scroll wheel down, button 5 is scroll wheel up. */
 void vterm_mouse_button(VTerm *vt, int button, int pressed, VTermModifier mod);
 
 /* ------------
@@ -302,6 +304,9 @@ typedef struct {
   int (*settermprop)(VTermProp prop, VTermValue *val, void *user);
   int (*bell)(void *user);
   int (*resize)(int rows, int cols, void *user);
+  /* A line was pushed off the top of the window.
+   * "cells[cols]" contains the cells of that line.
+   * Return value is unused. */
   int (*sb_pushline)(int cols, const VTermScreenCell *cells, void *user);
   int (*sb_popline)(int cols, VTermScreenCell *cells, void *user);
 } VTermScreenCallbacks;
@@ -320,6 +325,9 @@ void *vterm_screen_get_cbdata(VTermScreen *screen);
 void  vterm_screen_set_unrecognised_fallbacks(VTermScreen *screen, const VTermParserCallbacks *fallbacks, void *user);
 void *vterm_screen_get_unrecognised_fbdata(VTermScreen *screen);
 
+/* Enable support for using the alternate screen if "altscreen" is non-zero.
+ * Before that switching to the alternate screen won't work.
+ * Calling with "altscreen" zero has no effect. */
 void vterm_screen_enable_altscreen(VTermScreen *screen, int altscreen);
 
 typedef enum {

src/proto/terminal.pro

@@ -17,6 +17,7 @@ void term_change_in_curbuf(void);
 int term_get_attr(buf_T *buf, linenr_T lnum, int col);
 char_u *term_get_status_text(term_T *term);
 int set_ref_in_term(int copyID);
+void f_term_getaltscreen(typval_T *argvars, typval_T *rettv);
 void f_term_getattr(typval_T *argvars, typval_T *rettv);
 void f_term_getcursor(typval_T *argvars, typval_T *rettv);
 void f_term_getjob(typval_T *argvars, typval_T *rettv);

src/terminal.c

@@ -146,6 +146,8 @@ struct terminal_S {
 
     VTermPos	tl_cursor_pos;
     int		tl_cursor_visible;
+
+    int		tl_using_altscreen;
 };
 
 #define TMODE_ONCE 1	    /* CTRL-\ CTRL-N used */
@@ -1316,6 +1318,11 @@ handle_settermprop(
 	    out_flush();
 	    break;
 
+	case VTERM_PROP_ALTSCREEN:
+	    /* TODO: do anything else? */
+	    term->tl_using_altscreen = value->boolean;
+	    break;
+
 	default:
 	    break;
     }
@@ -1865,6 +1872,9 @@ create_vterm(term_T *term, int rows, int cols)
 
     /* Required to initialize most things. */
     vterm_screen_reset(screen, 1 /* hard */);
+
+    /* Allow using alternate screen. */
+    vterm_screen_enable_altscreen(screen, 1);
 }
 
 /*
@@ -1938,6 +1948,19 @@ term_get_buf(typval_T *argvars)
     return buf;
 }
 
+/*
+ * "term_getaltscreen(buf)" function
+ */
+    void
+f_term_getaltscreen(typval_T *argvars, typval_T *rettv)
+{
+    buf_T	*buf = term_get_buf(argvars);
+
+    if (buf == NULL)
+	return;
+    rettv->vval.v_number = buf->b_term->tl_using_altscreen;
+}
+
 /*
  * "term_getattr(attr, name)" function
  */

src/version.c

@@ -769,6 +769,8 @@ static char *(features[]) =
 
 static int included_patches[] =
 {   /* Add new patch number below this line */
+/**/
+    898,
 /**/
     897,
 /**/