Module vpe.panels

Simple display and control panel framework.

This is still being developed. The API and behaviour is likely to change.

The basic idea is that the contents of a buffer is divided into a sequence of panels.:

|Panel 1 contents.                                                  |
|Panel 2 contents.                                                  |
|                                                                   |
|Panel 3 contents.                                                  |
|                                                                   |
:                                                                   :

The contents of each panel is managed by a Panel subclass. The panels are managed by a PanelViewBuffer.


class vpe.panels.Panel

Part of a PanelViewBuffer.


view: PanelViewBuffer

The parent PanelViewBuffer. This is set by PanelViewBuffer when a panel is added.

uid: int

A unique (within the PanelViewBuffer) for this panel. This is set by PanelViewBuffer when a panel is added.



The formatted content of this panel as a sequence of line. This should only be set by the format_contents method.


The buffer slice for previous content. This is set to None by the apply_updates method.

TODO: The reindex method must update this when it is not None.


The index of this panel’s first line within the buffer.


property buf_slice

A slice object to select this panel’s line range.

property end_lidx

The end index of the panel;s line range.

property syntax_prefix

A suitable prefix for syntax items in this panel.



Apply syntax highlighting for this panel.

This may be over-ridden in subclasses that need specialised syntax highlighting.

This is only called when the panel’s start_lidx is correctly set. Previous panel specific syntax must be deleted by this method.


Apply any changes since the last call to this method.

This is where modifications to the underlying Vim buffer contents are performed.

Return value

True if the buffer was updated.


Format this panel’s contents.

If the number of content lines changes then the parent view’s notify_size_change method is invoked. If this results in the formatted contents changing then the parent view’s notify_content_change method is invoked.

This invokes the on_format_contents method, which is responsible for filling the content list.


Format the content of this panel.

The content is stored as a sequence of lines in the content property. This needs to be over-ridden in concrete subclasses.

reindex(idx: int)int

Update the line index information for this panel.

This is invoked when a panel is first added to a PanelViewBuffer and when the PanelViewBuffer determines that the panel’s starting line may have changed.


idx: int

The start line index for this panel.

Return value

The start line index for any following panel.

set_view(view: PanelViewBuffer, uid: int)

Set the parent PanelViewBuffer.


view: PanelViewBuffer

The parent PanelViewBuffer.

uid: int

The PanelViewBuffer unique ID for this panel.


class vpe.panels.PanelViewBuffer(*args, **kwargs)

A ScratchBuffer organised as vertical sequence of panels.

This provides support for the content of panels to be independently updated. The PanelView is responsible for making the buffer correctly reflect the content of the constituent panels.

Each panel is responsible for notifying its parent PanelViewBuffer when significant changes have occurred, such as lines being added, removed or modified.


property data

The data store for this panel view.

property panels

The sequence of panels for this display buffer.


add_panel(panel: Panel)

Add a panel an the end of the panel list.

format_panel(panel: Panel)

Make a panel refresh itself.

insert_panel(panel: Panel, index: int)

Insert a panel into the panel list.

The new panel’s content must be empty.


panel: Panel

The panel to insert.

index: int

Where to insert the panel.

notify_content_change(panel: Panel)

Handle notification that a panel’s content has changed.


panel: Panel

The panel that has changed.


Handle notification that some panel’s size has changed.


Invoked each time the buffer is entered.

Subclasses may extend this.


Perform special processing when line reindexing has occurred.

Subclasses may over-ride this.


Perform special processing when syntax is defined.

Subclasses may over-ride this.

on_updates_applied(changes_occurred: bool)

Perform special processing when buffer has been refreshed.

Subclasses may over-ride this.


changes_occurred: bool

True if changes to the buffer have been made.

remove_panel(panel: Panel)

Remove a panel from the panel list.


panel: Panel

The panel to remove. It must be present.

schedule_win_op(key, func, *args)

Schedule an operation for when the buffer appears in a window.



Decorator for Panel methods that can cause visible changes.