1<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> 2<html> 3<!-- Copyright (C) 1988-2021 Free Software Foundation, Inc. 4 5Permission is granted to copy, distribute and/or modify this document 6under the terms of the GNU Free Documentation License, Version 1.3 or 7any later version published by the Free Software Foundation; with the 8Invariant Sections being "Free Software" and "Free Software Needs 9Free Documentation", with the Front-Cover Texts being "A GNU Manual," 10and with the Back-Cover Texts as in (a) below. 11 12(a) The FSF's Back-Cover Text is: "You are free to copy and modify 13this GNU Manual. Buying copies from GNU Press supports the FSF in 14developing GNU and promoting software freedom." --> 15<!-- Created by GNU Texinfo 5.1, http://www.gnu.org/software/texinfo/ --> 16<head> 17<title>Debugging with GDB: TUI Windows In Python</title> 18 19<meta name="description" content="Debugging with GDB: TUI Windows In Python"> 20<meta name="keywords" content="Debugging with GDB: TUI Windows In Python"> 21<meta name="resource-type" content="document"> 22<meta name="distribution" content="global"> 23<meta name="Generator" content="makeinfo"> 24<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> 25<link href="index.html#Top" rel="start" title="Top"> 26<link href="Concept-Index.html#Concept-Index" rel="index" title="Concept Index"> 27<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents"> 28<link href="Python-API.html#Python-API" rel="up" title="Python API"> 29<link href="Python-Auto_002dloading.html#Python-Auto_002dloading" rel="next" title="Python Auto-loading"> 30<link href="Registers-In-Python.html#Registers-In-Python" rel="previous" title="Registers In Python"> 31<style type="text/css"> 32<!-- 33a.summary-letter {text-decoration: none} 34blockquote.smallquotation {font-size: smaller} 35div.display {margin-left: 3.2em} 36div.example {margin-left: 3.2em} 37div.indentedblock {margin-left: 3.2em} 38div.lisp {margin-left: 3.2em} 39div.smalldisplay {margin-left: 3.2em} 40div.smallexample {margin-left: 3.2em} 41div.smallindentedblock {margin-left: 3.2em; font-size: smaller} 42div.smalllisp {margin-left: 3.2em} 43kbd {font-style:oblique} 44pre.display {font-family: inherit} 45pre.format {font-family: inherit} 46pre.menu-comment {font-family: serif} 47pre.menu-preformatted {font-family: serif} 48pre.smalldisplay {font-family: inherit; font-size: smaller} 49pre.smallexample {font-size: smaller} 50pre.smallformat {font-family: inherit; font-size: smaller} 51pre.smalllisp {font-size: smaller} 52span.nocodebreak {white-space:nowrap} 53span.nolinebreak {white-space:nowrap} 54span.roman {font-family:serif; font-weight:normal} 55span.sansserif {font-family:sans-serif; font-weight:normal} 56ul.no-bullet {list-style: none} 57--> 58</style> 59 60 61</head> 62 63<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000"> 64<a name="TUI-Windows-In-Python"></a> 65<div class="header"> 66<p> 67Previous: <a href="Registers-In-Python.html#Registers-In-Python" accesskey="p" rel="previous">Registers In Python</a>, Up: <a href="Python-API.html#Python-API" accesskey="u" rel="up">Python API</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Concept-Index.html#Concept-Index" title="Index" rel="index">Index</a>]</p> 68</div> 69<hr> 70<a name="Implementing-new-TUI-windows"></a> 71<h4 class="subsubsection">23.2.2.35 Implementing new TUI windows</h4> 72<a name="index-Python-TUI-Windows"></a> 73 74<p>New TUI (see <a href="TUI.html#TUI">TUI</a>) windows can be implemented in Python. 75</p> 76<a name="index-gdb_002eregister_005fwindow_005ftype"></a> 77<dl> 78<dt><a name="index-gdb_002eregister_005fwindow_005ftype-1"></a>Function: <strong>gdb.register_window_type</strong> <em>(<var>name</var>, <var>factory</var>)</em></dt> 79<dd><p>Because TUI windows are created and destroyed depending on the layout 80the user chooses, new window types are implemented by registering a 81factory function with <small>GDB</small>. 82</p> 83<p><var>name</var> is the name of the new window. It’s an error to try to 84replace one of the built-in windows, but other window types can be 85replaced. 86</p> 87<p><var>function</var> is a factory function that is called to create the TUI 88window. This is called with a single argument of type 89<code>gdb.TuiWindow</code>, described below. It should return an object 90that implements the TUI window protocol, also described below. 91</p></dd></dl> 92 93<p>As mentioned above, when a factory function is called, it is passed a 94an object of type <code>gdb.TuiWindow</code>. This object has these 95methods and attributes: 96</p> 97<dl> 98<dt><a name="index-TuiWindow_002eis_005fvalid"></a>Function: <strong>TuiWindow.is_valid</strong> <em>()</em></dt> 99<dd><p>This method returns <code>True</code> when this window is valid. When the 100user changes the TUI layout, windows no longer visible in the new 101layout will be destroyed. At this point, the <code>gdb.TuiWindow</code> 102will no longer be valid, and methods (and attributes) other than 103<code>is_valid</code> will throw an exception. 104</p></dd></dl> 105 106<dl> 107<dt><a name="index-TuiWindow_002ewidth"></a>Variable: <strong>TuiWindow.width</strong></dt> 108<dd><p>This attribute holds the width of the window. It is not writable. 109</p></dd></dl> 110 111<dl> 112<dt><a name="index-TuiWindow_002eheight"></a>Variable: <strong>TuiWindow.height</strong></dt> 113<dd><p>This attribute holds the height of the window. It is not writable. 114</p></dd></dl> 115 116<dl> 117<dt><a name="index-TuiWindow_002etitle"></a>Variable: <strong>TuiWindow.title</strong></dt> 118<dd><p>This attribute holds the window’s title, a string. This is normally 119displayed above the window. This attribute can be modified. 120</p></dd></dl> 121 122<dl> 123<dt><a name="index-TuiWindow_002eerase"></a>Function: <strong>TuiWindow.erase</strong> <em>()</em></dt> 124<dd><p>Remove all the contents of the window. 125</p></dd></dl> 126 127<dl> 128<dt><a name="index-TuiWindow_002ewrite"></a>Function: <strong>TuiWindow.write</strong> <em>(<var>string</var>)</em></dt> 129<dd><p>Write <var>string</var> to the window. <var>string</var> can contain ANSI 130terminal escape styling sequences; <small>GDB</small> will translate these 131as appropriate for the terminal. 132</p></dd></dl> 133 134<p>The factory function that you supply should return an object 135conforming to the TUI window protocol. These are the method that can 136be called on this object, which is referred to below as the “window 137object”. The methods documented below are optional; if the object 138does not implement one of these methods, <small>GDB</small> will not attempt 139to call it. Additional new methods may be added to the window 140protocol in the future. <small>GDB</small> guarantees that they will begin 141with a lower-case letter, so you can start implementation methods with 142upper-case letters or underscore to avoid any future conflicts. 143</p> 144<dl> 145<dt><a name="index-Window_002eclose"></a>Function: <strong>Window.close</strong> <em>()</em></dt> 146<dd><p>When the TUI window is closed, the <code>gdb.TuiWindow</code> object will be 147put into an invalid state. At this time, <small>GDB</small> will call 148<code>close</code> method on the window object. 149</p> 150<p>After this method is called, <small>GDB</small> will discard any references 151it holds on this window object, and will no longer call methods on 152this object. 153</p></dd></dl> 154 155<dl> 156<dt><a name="index-Window_002erender"></a>Function: <strong>Window.render</strong> <em>()</em></dt> 157<dd><p>In some situations, a TUI window can change size. For example, this 158can happen if the user resizes the terminal, or changes the layout. 159When this happens, <small>GDB</small> will call the <code>render</code> method on 160the window object. 161</p> 162<p>If your window is intended to update in response to changes in the 163inferior, you will probably also want to register event listeners and 164send output to the <code>gdb.TuiWindow</code>. 165</p></dd></dl> 166 167<dl> 168<dt><a name="index-Window_002ehscroll"></a>Function: <strong>Window.hscroll</strong> <em>(<var>num</var>)</em></dt> 169<dd><p>This is a request to scroll the window horizontally. <var>num</var> is the 170amount by which to scroll, with negative numbers meaning to scroll 171right. In the TUI model, it is the viewport that moves, not the 172contents. A positive argument should cause the viewport to move 173right, and so the content should appear to move to the left. 174</p></dd></dl> 175 176<dl> 177<dt><a name="index-Window_002evscroll"></a>Function: <strong>Window.vscroll</strong> <em>(<var>num</var>)</em></dt> 178<dd><p>This is a request to scroll the window vertically. <var>num</var> is the 179amount by which to scroll, with negative numbers meaning to scroll 180backward. In the TUI model, it is the viewport that moves, not the 181contents. A positive argument should cause the viewport to move down, 182and so the content should appear to move up. 183</p></dd></dl> 184 185<hr> 186<div class="header"> 187<p> 188Previous: <a href="Registers-In-Python.html#Registers-In-Python" accesskey="p" rel="previous">Registers In Python</a>, Up: <a href="Python-API.html#Python-API" accesskey="u" rel="up">Python API</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Concept-Index.html#Concept-Index" title="Index" rel="index">Index</a>]</p> 189</div> 190 191 192 193</body> 194</html> 195