Sublime Text 3. Руководство по созданию плагина для начинающих

Команда разработки Sublime Text 3 позаботилась о том, чтобы писать плагины под ST было просто. Когда я писал плагин впервые, я даже не знал синтаксис Python. В общем, поехали!

Мы напишем плагин UnicodeCharacterInsert, который по нажатию горячей клавиши откроет всплывающее окно с таблицей Unicode символов. При выборе символа он будет вставлен в текущую позицию курсора. Таблица символов будет находится во внешнем HTML файле.

warning: mnemonic f not found in menu caption Unicode Characters

Документация

Сразу приведу ссылки на документацию по модулям и API для Sublime Text, которая вам пригодится при создании собственного плагина.

• Events & Idle Watcher: http://www.sublimetext.com/docs/plugin-examples
• API Reference: http://www.sublimetext.com/docs/3/api_reference.html
  
• Commands: http://www.sublimetext.com/docs/3/commands.html
  
• Commands: http://sublimetext.info/docs/en/core/commands.html
  
• EventListener: https://www.sublimetext.com/docs/3/api_reference.html#sublime_plugin.EventListener
  

Костяк плагина

Открываем редактор Sublime Text и создаем костяк нового плагина: Tools » New Plugin.. Сохраняем сгенерированный файл в подкаталоге плагинов  ~/.config/sublime-text-3/Packages/UnicodeCharacterInsert с именем UnicodeCharacterInsert.py.

* Путь к плагинам в Windows: C:\Documents and Settings\username\Application Data\Sublime Text\Packages.

Переименуйте название класса команды на UnicodeCharacterInsertCommand:

import sublime, sublime_plugin

class UnicodeCharacterInsertCommand(sublime_plugin.TextCommand):
    def run(self, edit):
        self.view.insert(edit, 0, "Hello, World!")

Для запуска плагина, выполните в консоли Sublime Text следующий код:

view.run_command('unicode_character_insert')

Этот плагин просто вставит текст "Hello, World!" с начала текущего открытого документа.

Вставка текста

Данный код будет вставлять текст в начало файла, что не очень полезно для нас. Чтобы вставить текст на место курсора, вы можете определить его позицию и задать это значение вместо 0:

pos = self.view.sel()[0].begin()
self.view.insert(edit, pos, "Unicode Character")

Чтобы вставить текст после курсора вы можете использовать команду view.run_command("insert"):

self.view.run_command("insert", {"characters": "Unicode Character"})

Горячие клавиши

Сразу расскажу как назначить горячие клавиши на запуск созданной команды, чтобы вы могли отлаживать код не переключаясь в консоль.

В каталоге плагина создайте файл Default.sublime-keymap со следующим содержимым:

[
    { "keys": [ "ctrl+shift+u", "ctrl+shift+i" ], "command": "unicode_character_insert" }
]

Теперь команда unicode_character_insert из вашего плагина будет вызываться при нажатии Ctrl+Shift+U+I, проверьте это.

Popup окно

Чтобы показать всплывающее окно с некоторым HTML контентом, в нашем случае это будет набор некоторых Unicode символов, используйте метод view.show_popup(content):

content = '<b>bold</b> text and <a href="link value">link</a>'
self.view.show_popup(content, sublime.HTML, location=-1, on_navigate=print)

Параметры метода show_popup:

flags        sublime.HTML, sublime.COOPERATE_WITH_AUTO_COMPLETE
location     -1
max_width    максимальная ширина popup окна
max_height   максимальная высота popup окна
on_navigate  метод, который будет вызван при нажатии на ссылку
on_hide      метод, который будет вызван при сокрытии окна

Код класса UnicodeCharacterInsertCommand (блок import я буду опускать для экономии места):

class UnicodeCharacterInsertCommand(sublime_plugin.TextCommand):
    def run(self, edit):
        content = '<b>bold</b> text and <a href="link value">link</a>'
        self.view.show_popup(content, flags=sublime.HTML, location=-1, max_width=400, on_navigate=print)

Всплывающее окно c HTML разметкой

При нажатии на ссылку, в консоль будет выводится значение этой ссылки, текст link value.

Контент popup-окна в HTML файле

Теперь вынесем HTML разметку всплывающего окна во внешний файл unicode-characters.html, который сохраним в каталоге нашего плагина.

<style>
    html { background-color: #272822; margin: 0px; }
    body { margin: 10px; padding: 0; }
    a { text-decoration: none; margin: 0px; font-size: 24px; font-family: monospace; color: #EEF8F2; height: 30px; }
</style>

<div>
    <a href="«">«</a>
    <a href="»">»</a>
    <a href="‹">‹</a>
    <a href="›">›</a>
    <a href="§">§</a>
    <a href="¶">¶</a>
    <a href="©">©</a>
    <a href="®">®</a>
    <a href="™">™</a>
    <a href="؟">؟</a>
</div>

Получить контент из внешнего файла можно так:

tpl_path = os.path.dirname(os.path.realpath(__file__)) + '/unicode-characters.html'
content = open(tpl_path, 'r').read()

При публикации плагина в репозитории packagecontrol.io мне подсказали, что внешние ресурсы необходимо подгружать методом sublime.load_resource. Этому методу нужно передавать путь к внешнему файлу относительно каталога ~/.config/sublime-text-3:

Packages/UnicodeCharacterInsert/unicode-characters.html

Финальная реализация

Реализуем методы get_characters_html для получения разметки всплывающего окна из файла unicode-characters.html и метод on_choice_symbol, который будет вставлять в документ выбранный Unicode символ и закрывать popup:

class UnicodeCharacterInsertCommand(sublime_plugin.TextCommand):
    def run(self, edit):
        content = self.get_popup_content
        self.view.show_popup(content, flags=sublime.HTML, location=-1, max_width=400, on_navigate=self.on_choice_symbol)

    def get_characters_html(self):
        resources = sublime.find_resources('unicode-characters.html')
        content = sublime.load_resource(resources[0])
        return content

    def on_choice_symbol(self, symbol):
        self.view.run_command("insert", {"characters": symbol})
        self.view.hide_popup()

В результате у нас получилось вот такое popup-окно с таблицей Unicode символов:

Вид панели с Unicode символами

Добавление команды Command Palette

Создайте файл Default.sublime-commands в каталоге плагина:

[
    { "caption": "Unicode Character Insert: Show Panel", "command": "unicode_character_insert" }
]

Контекстное меню

Для добавление пунктов в контекстное меню создайте файл Context.sublime-menu в каталоге плагина:

[
    {
        "caption": "Unicode Characters",
        "mnemonic": "f",
        "id": "unicode_character_insert",
        "children":
        [
            {
                "command": "unicode_character_insert",
                "caption": "Show Characters Table"
            }
        ]
    },
	{
        "caption": "-",
        "id": "separator"
    }
]

Чтобы добавить пункты в основное меню создайте файл Main.sublime-menu:

[
    {
        "mnemonic": "n",
        "caption": "Preferences",
        "id": "preferences",
        "children": [
            {
                "mnemonic": "P",
                "caption": "Package Settings",
                "id": "package-settings",
                "children": [
                    {
                        "caption": "Unicode Character Insert",
                        "children": [
                            {
                                "caption": "Key Bindings – Default",
                                "command": "open_file",
                                "args": {
                                    "file": "${packages}/UnicodeCharacterInsert/Default.sublime-keymap"
                                }
                            }
                        ]
                    }
                ]
            }
        ]
    }
]

#sublime text 3, #ST3, #st3 create plugin manual