目录
API接口
Sublime API
基础类
示例插件
Sublime Text 2有几个自预装的插件，你可以在Packages/Default目录中找到它们：
sublime 模型
| 方法 | 返回值 | 描述 |
|---|
| set_timeout(callback, delay) | None | 在指定的延迟(以毫秒为单位)后调用回调。相同延迟的回调将会以添加的顺序运行。从多线程调用setTimeout是安全的。 |
| status_message(string) | None | 设置状态栏出现的信息。 |
| error_message(string) | None | 向用户显示错误提示对话框。 |
| message_dialog(string) | None | 向用户显示一个消息对话框。 |
| ok_cancel_dialog(string, <ok_button>) | bool | 向用户显示一个ok / cancel问题对话框。如果ok_button有值，将作为ok button的文字。如果用户点击ok按钮返回True。 |
| load_settings(base_name) | Settings | 载入指定设置。name应当包含一个文件名和扩展名，但是不是一个路径。将会在包目录里搜索匹配base_name的文件，结果将会被整理成settings对象。后面再次调用load_settings用同一个base_name将会返回相同的object，不会再次从硬盘加载配置文件。（未测试是否指的是base_name必须相同） |
| save_settings(base_name) | None | 刷新内存中任何指定配置对象的更改到硬盘。 |
| windows() | [Window] | 返回所有打开窗口的列表。 |
| active_window() | Window | 返回最近用过的窗口。 |
| packages_path() | String | 返回包目录的基本路径。 |
| installed_packages_path() | String | 返回所有用的 *.sublime-package 文件所在的包路径。 |
| get_clipboard() | String | 返回剪切板的文本。 |
| set_clipboard(string) | None | 设置剪切板的文本。 |
| score_selector(scope, selector) | Int | 在所给范围内匹配指定选择器，返回一个分数。0分指没有匹配，大于0指匹配到了。同一个作用域将会被不同的选择器匹配比较：分数越高匹配的选择器越好。 |
| run_command(string, <args>) | None | 执行参数中传进来的可选参数的应用命令。 |
| log_commands(flag) | None | 控制命令日志。如果启用，所有组合键和菜单调用的命令将会记录到终端。 |
| log_input(flag) | None | 控制输入日志。如果启用，所有的键输入将会被记录到终端。 |
| version() | String | 返回版本号。 |
| platform() | String | 返回系统平台，可能是"osx"，"linux"或者"windows" |
| arch() | String | 返回CPU架构，"x32"或"x64" |
Class sublime.View
代表着一个文本缓冲区的一个视图。注意多个视图也许指向是同一个缓冲区，但是它们有自己唯一的选择区和图形。
| 方法 | 返回值 | 描述 |
|---|
| id() | int | 返回一个标识当前view的数字。 |
| buffer_id() | int | 返回一个和当前视图相关的缓冲区的唯一标识。 |
| file_name() | String | 缓冲区文件的全名，如果硬盘上不存在返回None。 |
| name() | String | 分配给缓冲区的名称，如果有的话。 |
| set_name(name) | None | 指定给缓冲区一个名称。 |
| is_loading() | bool | 如果缓冲区仍然在从硬盘加载，并且没有准备好使用返回true。 |
| is_dirty() | bool | 如果有任何未保存的修改过的缓冲区返回true。 |
| is_read_only() | bool | 如果缓冲区不能被修改返回true。 |
| set_read_only(value) | None | 将缓冲区设为只读。 |
| is_scratch() | bool | 如果缓冲区是一个临时缓冲区返回true。临时缓冲区从来不被视为脏的。 |
| set_scratch(value) | None | 将缓冲区设为临时缓冲区。 |
| settings() | Settings | 返回视图配置对象的引用。任何对此对象的改变将私有的做用于当前视图。 |
| window() | Window | 返回包含视图的窗口的引用。 |
| run_command(string, <args>) | None | 运行带可选参数的指定名称的TextCommand。 |
| size() | int | 返回文件中的字符个数。 |
| substr(region) | String | 该区域的内容作为一个字符串返回。 |
| substr(point) | String | 返回光标右侧的字符。 |
| begin_edit(<command>, <args>) | Edit | 创建一个编辑对象，划定一个撤销组。必须调用相应的end_edit()。 |
| end_edit(edit) | Edit | 完成编辑。 |
| insert(edit, point, string) | int | 在视图中指定光标处插入所给字符串。返回插入的字符数：如果当前缓冲区tabs正被转换为空格，结果是不同的。 |
| erase(edit, region) | None | 擦除缓冲区区域的文本。 |
| replace(edit, region, string) | None | 替换区域的文本为给定字符串。 |
| sel() | RegionSet | 返回一个选区的引用。 |
| line(point) | Region | 返回包含光标的行。 |
| line(region) | Region | 返回一个修改过的区域的副本，它开始于一行的开始，并结束在一行的结尾，注意它有可能跨几行。 |
| full_line(point) | Region | 像line()，但是该选区包含紧跟的换行符，如果有的话。 |
| full_line(region) | Region | 像line()，但是该选区包含紧跟的换行符，如果有的话。 |
| lines(region) | [Region] | 返回选区相交的（以排好序的）行的列表。 |
| split_by_newlines(region) | [Region] | 分割选区至每个选区只返回精确的一行。 |
| word(point) | Region | 返回包含光标的单词。 |
| word(region) | Region | 返回一个修改过的区域的副本，它开始于一词的开始，并结束在一词的结尾，注意它有可能跨几个词。 |
| find(pattern, fromPosition, <flags>) | Region | 返回从所给光标后的第一个匹配正则模式的区域，未找到返回None。可选的flags参数可以是sublime.LITERAL、sublime.IGNORECASE或者2个都有。 |
| find_all(pattern, <flags>, <format>, <extractions>) | [Region] | 返回所有匹配正则的非重叠的区域。可选的flags参数可以是sublime.LITERAL、sublime.IGNORECASE或者2个都有。如果提供了一个格式化用的format字符串，那么所有匹配将被格式化，并且放入extractions列表中。 |
| rowcol(point) | (int, int) | 基于0点计算光标所在行数和列数。 |
| text_point(row, col) | int | 基于0点通过所给的行和列计算字符的偏移。注意，'col'解释为超过一行开头的字符的个数。 |
| set_syntax_file(syntax_file) | None | 改变视图使用的语法高亮。syntax_file 应该是一个在Packages/Python/Python.tmLanguage中的名字。检索当前的语法,使用view.settings().get('syntax'). |
| extract_scope(point) | Region | 返回分配给所给光标处字符的语法的范围。 |
| scope_name(point) | String | 返回分配给所给光标处字符的语法的名称。 |
| score_selector(point, selector) | Int | 在所给范围内匹配指定选择器，返回一个分数。0分指没有匹配，大于0指匹配到了。同一个作用域将会被不同的选择器匹配比较：分数越高匹配的选择器越好。 |
| find_by_selector(selector) | [Regions] | 找到文件中所有匹配选择器的区域，作为一个列表范围他们。 |
| show(point, <show_surrounds>) | None | 滚动视图到指定的光标。 |
| show(region, <show_surrounds>) | None | 滚动视图到指定的区域。 |
| show(region_set, <show_surrounds>) | None | 滚动视图来显示错给区域集。 |
| show_at_center(point) | None | 滚动视图使光标居中。 |
| show_at_center(region) | None | 滚动视图到区域的中心。 |
| visible_region() | Region | 返回当前视图可见的区域。 |
| viewport_position() | Vector | 返回视口的布局坐标的偏移。 |
| set_viewport_position(vector, <animate<) | None | 滚动视口到所给布局坐标。 |
| viewport_extent() | vector | 返回视口的宽和高。 |
| layout_extent() | vector | 返回布局的宽和高。 |
| text_to_layout(point) | vector | 转换一个文本坐标到布局坐标。 |
| layout_to_text(vector) | point | 转换一个布局坐标到文本坐标。 |
| line_height() | real | 返回布局中使用的行高。 |
| em_width() | real | 返回视图中使用的经典字符串的宽度。 |
| add_regions(key, [regions], scope, <icon>, <flags>) | None | 添加一组区域到视图。如果指定的key已存在一组区域了，它们将被覆写。scope用来定位一种在区域内所绘的颜色，它应当是有一种范围的名称,比如"comment"或"string"。如果scope为空，区域不会被绘制。
可选参数icon如果指定名称了，将会绘制到相邻每个区域的阴沟。icon将会使用scope相关的颜色。可用的icon值是dot, circle, bookmark和cross。
可选的标志参数是一个按位组合：
- sublime.DRAW_EMPTY. Draw empty regions with a vertical bar. By default, they aren't drawn at all.
- sublime.HIDE_ON_MINIMAP. Don't show the regions on the minimap.
- sublime.DRAW_EMPTY_AS_OVERWRITE. Draw empty regions with a horizontal bar instead of a vertical one.
- sublime.DRAW_OUTLINED. Draw regions as an outline, rather than filled in.
- sublime.PERSISTENT. Save the regions in the session.
- sublime.HIDDEN. Don't draw the regions.
|
| get_regions(key) | [regions] | 返回与所给key相关的选区，如果有的话。 |
| erase_regions(key) | None | 移除指定的区域。 |
| set_status(key, value) | None | 添加状态key到视图。这些值将会被显示在状态栏，组成一个以逗号分割所有值，按照key排序的列表。设置值为空字符串将清楚状态。 |
| get_status(key) | String | 返回现在分配给相关key的value，如果有的话。 |
| erase_status(key) | None | 清除指定name的状态值。 |
| command_history(index, <modifying_only>) | (String,Dict,int) | 返回存在撤销/重做堆栈中的所给历史入口的命令名，命令参数，和重复次数。
索引0代表最近使用的命令， -1表示在那之前的命令，等等。正值的索引意味着在重做堆栈中的命令。如果undo / redo 历史不存在，返回(None, None, 0)。
设置modifying_only为True(默认False)将会只返回缓冲区内修改过的入口。
|
| fold([regions]) | bool | 折叠所给的区域们，如果他们都已折叠了返回False |
| fold(region) | bool | 折叠所给区域，如果已闭合返回False。 |
| unfold(region) | [regions] | 展开该区域里所有文字，返回展开的区域。 |
| unfold([regions]) | [regions] | 展开各区域里所有文字，返回展开的区域。 |
| encoding() | String | 返回当前文件相关的编码。 |
| set_encoding(encoding) | None | 给当前文件指定一个新的编码。这个编码将在下次文件保存时使用。 |
| line_endings() | String | 返回当前文件使用的line endings。 |
| set_line_endings(line_endings) | None | 设置下次保存时使用的line endings。 |
Class sublime.RegionSet
维持一组区域，确保他们没有重叠。这些区域有序存储。.
| 方法 | 返回值 | 描述 |
|---|
| clear() | None | 移除所有区域。 |
| add(region) | None | 添加指定区域。它将与集合内任何和它相交的区域合并。 |
| add_all(region_set) | None | 添加指定集合内的区域。 |
| subtract(region) | None | 从集合中减去该区域。 |
| contains(region) | bool | 当且仅当给的区域是集合的子集时返回true |
Class sublime.Region
代表一个缓冲区的区域。空区域，其中A == B是有效的。
| 构造方法 | 描述 |
|---|
| Region(a, b) | 用a和b的初始值创建一个区域。 |
| 属性 | Type | 描述 |
|---|
| a | int | 该区域的首端。 |
| b | int | 该区域的第二个结束。也许比a小，此时区域是相反的。 |
| 方法 | 返回值 | 描述 |
|---|
| begin() | int | 返回a和b中的最小值。 |
| end() | int | 返回a和b中的最大值。 |
| size() | int | 返回该区域跨域的字符串的个数。总是>= 0. |
| empty() | bool | 当且仅当begin() == end()时返回true. |
| cover(region) | Region | 返回一个跨越当前区域和所给区域的区域。 |
| intersection(region) | Region | 返回两个区域的交集。 |
| intersects(region) | bool | 当且仅当当前区域和所给区域相等或者两个包含至少一个共同处时返回True。 |
| contains(region) | bool | 当且仅当所给区域是当前区域的子集时返回True。 |
| contains(point) | bool | 当前仅当begin() <= point <= end()返回True。 |
Class sublime.Edit
Edit对象没有功能，它们用来分组缓冲区的修改。
它们可以通过view.begin_edit()被创建。每次调用view.begin_edit()必须有个相关的view.end_edit()的调用，通常包裹在try … finally块中。
Class sublime.Window
| 方法 | 返回值 | 描述 |
|---|
| id() | int | 返回一个唯一标示窗口的数字。 |
| new_file() | View | 创建一个文件。返回的视图是空的，并且它的is_loaded方法将返回True. |
| open_file(file_name, <flags>) | View | 打开指定文件，返回相关的view。如果已经打开了，文件tab将被激活。注意因为文件加载是异步的，对返回的view的操作是不肯能的，直到它的its is_loading()方法返回False。
可选的标志参数是一个按位组合：
- sublime.ENCODED_POSITION. Indicates the file_name should be searched for a :row or :row:col suffix
- sublime.TRANSIENT. Open the file as a preview only: it won't have a tab assigned it until modified
|
| active_view() | View | 返回当前编辑的视图。 |
| active_view_in_group(group) | View | 返回做给小组中当前编辑的视图。 |
| views() | [View] | 返回视窗中所有打开的视图。 |
| views_in_group(group) | [View] | 返回指定组内所有的视图。 |
| num_groups() | int | 返回视窗内视图组中的视图的个数。 |
| active_group() | int | 返回当前选中的组的索引。. |
| focus_group(group) | None | 激活指定组。 |
| focus_view(view) | None | 切换到指定视图。 |
| get_view_index(view) | (group, index) | 返回的视图组内组和索引。如果没有找到则返回-1。 |
| set_view_index(view, group, index) | None | 移动视图到指定视图组并给以索引。 |
| folders() | [String] | 返回一个当前打开目录的列表。 |
| run_command(string, <args>) | None | 执行指定的带可选的参数的WindowCommand。 |
| show_quick_panel(items, on_done, <flags>) | None | 显示一个快速面板，用来选择列表中的一个项目。当选中时，on_done会被调用一次，参数时选中的项目的索引。如果快捷面板取消了，on_done将会被调用，参数为-1。
项目也许是一个字符串数组，或者是一个每维是个字符串数组的多维数组。在后一种情况下，快速面板中的每个条目将显示多行。
Flags目前只有一个选项，sublime.MONOSPACE_FONT
|
| show_input_panel(caption, initial_text, on_done, on_change, on_cancel) | View | 显示输入面板，收集来自用户的一行输入。on_done和on_change,如果有的话，应当是一个接收一个字符串为参数的函数。on_cancel应当是没有参数的函数。返回用于输入组件的视图。 |
| get_output_panel(name) | View | 返回带指定name的输出面板的视图，如果需要的话会创建面板。输出面板可通过执行show_panelwindow命令来显示,其panel参数是name加上"output."前缀。 |
Class sublime.Settings
| 方法 | 返回值 | 描述 |
|---|
| get(name) | value | 返回指定名称的配置值。 |
| get(name, default) | value | 返回指定名称的配置值，如果没定义返回所传默认值。 |
| set(name, value) | None | 设置指定name配置的值。配置的值只允许原始类型、列表和字典这几种类型。 |
| erase(name) | None | 删除指定名称的配置。不会移除上一级的同名配置。 |
| has(name) | bool | 当且仅当指定名称的配置项存在配置集合或者父级配置中时返回true。 |
| add_on_change(key, on_change) | None | 注册一个回调函数当无论什么时候配置对象中的配置值变化时都会执行。 |
| clear_on_change(key) | None | 移除所有注册到指定key上的回调。 |
Module sublime_plugin
Class sublime_plugin.EventListener
注意许多事件是由和视图相关的缓冲区触发的，因此方法只能调用一次，并且view做为它的第一个参数。
| 方法 | 返回值 | 描述 |
|---|
| on_new(view) | None | 当一个新缓冲区被创建时调用。 |
| on_clone(view) | None | 当从一个已存视图克隆出新视图时调用。 |
| on_load(view) | None | 当文件完成加载时调用。 |
| on_close(view) | None | 当一个视图被关闭时调用(注意，同一个缓冲区中也许有其他的视图)。 |
| on_pre_save(view) | None | 当一个视图即将保存时调用。 |
| on_post_save(view) | None | 当一个视图被保存后调用。 |
| on_modified(view) | None | 当更改被应用到视图时调用。 |
| on_selection_modified(view) | None | 当一个视图里的选区被修改时调用。 |
| on_activated(view) | None | 当一个视图获得焦点时调用。 |
| on_deactivated(view) | None | 当一个视图失去焦点时调用。 |
| on_query_context(view, key, operator, operand, match_all) | bool or None | 当给指定上下文绑定的键被触发时调用。如果插件知道如何响应上下文，应当返回结果True和False。如果不知道，返回None。
operator is one of:
- sublime.OP_EQUAL. Is the value of the context equal to the operand?
- sublime.OP_NOT_EQUAL. Is the value of the context not equal to the operand?
- sublime.OP_REGEX_MATCH. Does the value of the context match the regex given in operand?
- sublime.OP_NOT_REGEX_MATCH. Does the value of the context not match the regex given in operand?
- sublime.OP_REGEX_CONTAINS. Does the value of the context contain a substring matching the regex given in operand?
- sublime.OP_NOT_REGEX_CONTAINS. Does the value of the context not contain a substring matching the regex given in operand?
match_all应当在上下文涉及相关选区时使用：是每个选区必须匹配到(match_all = True)，或者至少一个选区有匹配(match_all = False)?
|
Class sublime_plugin.ApplicationCommand
| 方法 | 返回值 | 描述 |
|---|
| run(<args>) | None | 当命令运行时调用。 |
| is_enabled(<args>) | bool | 此时如果命令能够被运行时返回true。默认实现总是返回True。 |
| is_visible(<args>) | bool | 此时如果命令应该被显示在菜单中返回true。默认实现总是返回True。 |
| description(<args>) | String | 返回指定参数时命令的一段描述。在菜单中使用，如果没有标题，则返回默认描述。 |
Class sublime_plugin.WindowCommand
WindowCommands是每个视图的实例化。窗口对象可以通过self.window访问。
| 方法 | 返回值 | 描述 |
|---|
| run(<args>) | None | 当命令运行时调用。 |
| is_enabled(<args>) | bool | 此时如果命令能够被运行时返回true。默认实现总是返回True。 |
| is_visible(<args>) | bool | 此时如果命令应该被显示在菜单中返回true。默认实现总是返回True。 |
| description(<args>) | String | 返回指定参数时命令的一段描述。在菜单中使用，如果没有标题，则返回默认描述。 |
Class sublime_plugin.TextCommand
TextCommands是每个视图的实例化。视图对象可以通过self.view访问。
| 方法 | 返回值 | 描述 |
|---|
| run(edit, <args>) | None | 当命令运行时调用。 |
| is_enabled(<args>) | bool | 此时如果命令能够被运行时返回true。默认实现总是返回True。 |
| is_visible(<args>) | bool | 此时如果命令应该被显示在菜单中返回true。默认实现总是返回True。 |
| description(<args>) | String | 返回指定参数时命令的一段描述。在菜单中使用，撤销/重复描述。没有则返回默认描述。 |
