Gdb/TUI-Windows-In-Python
Previous: Registers In Python, Up: Python API [Contents][Index]
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 typegdb.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, thegdb.TuiWindow
will no longer be valid, and methods (and attributes) other thanis_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 callclose
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.
Previous: Registers In Python, Up: Python API [Contents][Index]