23.2.2.35 Implementing new TUI windows

New TUI (see TUI) windows can be implemented in Python.

Function: gdb.register_window_type (name, factory)

Because TUI windows are created and destroyed depending on the layout the user chooses, new window types are implemented by registering a factory function with GDB.

name is the name of the new window. It’s an error to try to replace one of the built-in windows, but other window types can be replaced.

function is a factory function that is called to create the TUI window. This is called with a single argument of type gdb.TuiWindow, described below. It should return an object that implements the TUI window protocol, also described below.

As mentioned above, when a factory function is called, it is passed a an object of type gdb.TuiWindow. This object has these methods and attributes:

Function: TuiWindow.is_valid ()

This method returns True when this window is valid. When the user changes the TUI layout, windows no longer visible in the new layout will be destroyed. At this point, the gdb.TuiWindow will no longer be valid, and methods (and attributes) other than is_valid will throw an exception.

Variable: TuiWindow.width

This attribute holds the width of the window. It is not writable.

Variable: TuiWindow.height

This attribute holds the height of the window. It is not writable.

Variable: TuiWindow.title

This attribute holds the window’s title, a string. This is normally displayed above the window. This attribute can be modified.

Function: TuiWindow.erase ()

Remove all the contents of the window.

Function: TuiWindow.write (string)

Write string to the window. string can contain ANSI terminal escape styling sequences; GDB will translate these as appropriate for the terminal.

The factory function that you supply should return an object conforming to the TUI window protocol. These are the method that can be called on this object, which is referred to below as the “window object”. The methods documented below are optional; if the object does not implement one of these methods, GDB will not attempt to call it. Additional new methods may be added to the window protocol in the future. GDB guarantees that they will begin with a lower-case letter, so you can start implementation methods with upper-case letters or underscore to avoid any future conflicts.

Function: Window.close ()

When the TUI window is closed, the gdb.TuiWindow object will be put into an invalid state. At this time, GDB will call close method on the window object.

After this method is called, GDB will discard any references it holds on this window object, and will no longer call methods on this object.

Function: Window.render ()

In some situations, a TUI window can change size. For example, this can happen if the user resizes the terminal, or changes the layout. When this happens, GDB will call the render method on the window object.

If your window is intended to update in response to changes in the inferior, you will probably also want to register event listeners and send output to the gdb.TuiWindow.

Function: Window.hscroll (num)

This is a request to scroll the window horizontally. num is the amount by which to scroll, with negative numbers meaning to scroll right. In the TUI model, it is the viewport that moves, not the contents. A positive argument should cause the viewport to move right, and so the content should appear to move to the left.

Function: Window.vscroll (num)

This is a request to scroll the window vertically. num is the amount by which to scroll, with negative numbers meaning to scroll backward. In the TUI model, it is the viewport that moves, not the contents. A positive argument should cause the viewport to move down, and so the content should appear to move up.