Keycommand Plugins

Keycommand plugins are those that implement handles that are called when keypress events happen.

Plugins can be placed in your ~/.vy/ folder as well as being on any folder that is in your sys.path. It means vy plugins can be packaged and installed as any other python application.

Function based

def handle0(event):
    pass

def handle1(event):
    pass

def handle2(event):
    pass

def install(area, *args, **kwargs):
    area.install('plugin-namespace', 
    ('mode', 'event0', handle0), 
    ('mode', 'event1', handle1), ...)

A keycommand plugin have a plugin namespace that is used for customization of its keycommands using the mapset function. The plugin namespace usually is the name of the plugin where '_' are replaced for '-'.

Example: A plugin named hello_word.py would have namespace like 'hello-world'.

The arguments passed to the AreaVi.install method are the plugin namespace and a sequence of tuples that specifies in which conditions handles will be fired.

In the example above it means that when a given instance is in a mode named 'mode' and 'event0' happens then handle0 will be called, when 'event1' happens then handle1 will be called.

For each new AreaVi instance that is created it calls the plugin's install method with the arguments given to the plugin from your ~/.vy/vyrc file.

Create the file below.

~/.vy/show_hello.py

def install(area, name):
    # The AreaVi insert method inserts text in a given index.
    area.insert('1.0', name)

Install show_hello.py plugin with:

import show_hello
autoload(show_hello, 'VyUserName')

Once vy runs it will insert 'VyUserName' string whenever an AreaVi instance is created. Try opening some tabs, panels.

Class based

Class based plugins are used when it is necessary to save state across events that happen in a given AreaVi.

class Name(object):
    def __init__(self, area, *args, **kwargs):
        # Saving the instance for later usage.
        self.area = area
        area.install('plugin-namespace', 
        ('mode', 'event0', self.handle0), 
        ('mode', 'event1', self.handle1), ...)
    
    def handle0(self, event):
        pass

    def handle1(self, event):
        pass

install = Name

Let us write a simple class based plugin. Create the file below.

~/.vy/counter.py

from vyapp.app import root

class Counter(object):
    def __init__(self, area):
        self.area = area
        area.install('counter', ('NORMAL', '<Control-z>', self.count))
        self.value = 0

    def count(self, event):
        self.value = self.value + 1
        root.status.set_msg('Counter value:%s' % self.value)

install = Counter

Just add the lines to your *vyrc file.

import counter
autoload(counter)

Once vy is running in NORMAL mode whenever the event below happens:

<Control-z>

It increases the variable and shows its value on the statusbar.