-
Notifications
You must be signed in to change notification settings - Fork 3
/
Plugin.txt
118 lines (117 loc) · 15.2 KB
/
Plugin.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
:Plugin: are *.py files written in Python, which define & run commands
ST3 use Python 3 language
*.py files are located in:
Packages\*.sublime-package (Default Packages)
\Data\Installed Packages\*.sublime-package (Installed Packages)
Packages\<pkg_name>\*.py
Packages\User\*.py
There's no priority difference between these location (ST loads all *.py and execute them equally)
Write a .py plugin
Example:
import sublime, sublime_plugin # import collections of Methods (see Method below)
class ExampleCommand(sublime_plugin.TextCommand): # initiate built-in TextCommand Class (collection of methods). Resolved command name = "example"
def run(self, edit): # define action to 'run' when trigger this command
self.view.insert(edit, 0, "Hello, World!") # method insert(edit, point, string) in View Class [[#Method:]]
sublime.message_dialog("string inserted") # Easiest way to view info
sublime.status_message("string inserted")
Command name
Filename of .py file does not matter
To run a plugin, you refer to the name name defined inside that .py
Example: class NewExampleCommand(sublime_plugin.TextCommand) → the raw name is NewExampleCommand
However, ST will resolve by:
Trim-off the suffix "Command"
Convert CamelCase to lowercase & underscore, i.e: CamelCase → camel_case
So, the final name is "new_example"
to run this command via console: Ctrl+` → window.run_command("new_example")
Module-Class-Methods
Module
is a *.py file
Module can contain functions, classes, variables, runnable code... (aka attributes)
Can import modules then reuse functions, classes, variables inside those modules
Class:
is a collection of several functions & variables, which can be reused
Differ from module:
module is imported and run only once >< can create multiple instances of a class, then run them without conflict
module can contain multiple classes (and also module's functions & variables)
Method:
is a function defined inside a class and takes a class instance as 1st parameter
i.e: def method_name(self, arg1, arg2):
i.e: new_file(), get_view_index(view),...
To use a method, we have to initiate relevant module & Class, i.e:
import sublime, sublime_plugin, os # Now, all methods provided by sublime.py, sublime_plugin.py, os.py can be used
class ExampleCommand(sublime_plugin.TextCommand): # Define a new class, which inherit all methods from Class "TextCommand" inside sublime_plugin module [[Plugin.API.txt]]
run(self): # call run() method from TextCommand class
sublime.message_dialog('Hello World') # call message_dialog() method from "sublime" module
ST3 can use:
ST built-in methods [[Plugin.API.txt]]
ST built-in commands [[Command.txt#Built-in commands]]
Python 3.x standard methods
Object:
Buffer:
is the whole text-editing region on screen
each character is located by 1 integer count from beginning to end
Point:
is an integer used to locate 1 character
i.e: sublime.message_dialog(self.view.substr(12)) = the 12th character counted from the beginning of the buffer
Region:
a range from Point a to Point b
i.e: view.substr(sublime.region(12, 15)) = 3 characters counted from Point 12 to Point 14
Selection
is a region (multiple regions in case multiple selections)
sels = self.view.sel() => Return a List of selected regions i.e: [(3,0), (12,15)]
sel = sels[0] => return the first region, i.e: (3,0)
sel.a --> the start of the selection, i.e: =3 because user drag-selected from from Point 3 to Point 0 (right-to-left)
sel.b --> the end of the selection, i.e: =0
sel.begin() --> the minimum of a and b
sel.end() --> the maximum of a and b
view object vs window object
Sometime, you need to feed an abstract object to a method (i.e: 1st and 3rd tab to method close())
View object represent current buffer => feed it to text-dealing-methods [[Plugin.API.txt#sublime.View]]
Window object represent ST's UI such as panels, tabs, bars...=> feed to [[Plugin.API.txt#sublime.Window]]
TextCommand:
self.view return current View object
window = self.view.window() return current Window object
WindowCommand:
self.window return current Window object
view = self.window.active_view() return current View object
Example: To toggle side bar & reveal current file
Note:
a "view" is required to run_command("reveal_in_side_bar");
but we need a "window" to run_command("toggle_side_bar")
Method 1 - using WindowCommand
import sublime, sublime_plugin
class examplCommand(sublime_plugin.WindowCommand):
def run(self):
view = self.window.active_view()
view.run_command("reveal_in_side_bar")
self.window.run_command("toggle_side_bar")
Method 2 - using TextCommand
import sublime, sublime_plugin
class examplCommand(sublime_plugin.TextCommand):
def run(self, view):
self.view.run_command("reveal_in_side_bar")
window = self.view.window()
window.run_command("toggle_side_bar")
Settings
is an object, which allow [[#sublime.Settings]] methods i.e:
SettingObject = self.view.settings()
SettingObject.set('word_wrap', 'false')
Value: ???
Vector: is a combination of begin Point and end Point, i.e: (234.0, 1342.0)
Plugin Lifecycle
At importing time, plugins may not call any API functions, with the exception of sublime.version(), sublime.platform(), sublime.architecture() and sublime.channel().
If a plugin defines a module level function plugin_loaded(), this will be called when the API is ready to use.
Plugins may also define plugin_unloaded(), to get notified just before the plugin is unloaded.
Some useful pieces of codes: [[Plugin.Snippet.py]]
Working Example (sorted from basic → advance):
[[obj\message.py]]
[[obj\insert_text.py]]
[[obj\change_settings.py]]
[[obj\Expand selection to bracket.py]]
[[obj\OpenInBrowser.py]]
[[obj\view_scope.py]]
[[obj\CopyPath.py]]
[[obj\TrimWhiteSpace.py]]
[[obj\Set_timeout.py]]
Several pre-made plugins for further study: *.py inside \Packages\Default.sublime-package
To Run a command/plugin [[Command.txt#Commands can be triggered via]]