forked from mia/Aegisub
More updates to auto4 docs.
Originally committed to SVN as r219.
This commit is contained in:
Niels Martin Hansen
parent
6ed6cfc289
commit
38dd8e0fb5
2 changed files with 314 additions and 141 deletions
314
automation/v4-docs/basic-function-interface.txt
Normal file
314
automation/v4-docs/basic-function-interface.txt
Normal file
|
|
@ -0,0 +1,314 @@
|
|||
Automation 4 Basic Interface
|
||||
|
||||
This document described the basic functions needed to define an Automation 4
|
||||
script. This covers Feature registration and the prototypes of functions used
|
||||
to implement the various features.
|
||||
|
||||
---
|
||||
|
||||
Macro Registation Function
|
||||
|
||||
This is a function called from top-level of an Automation script to register
|
||||
a new Macro Feature.
|
||||
|
||||
function aegisub.register_macro(
|
||||
name,
|
||||
description,
|
||||
menu,
|
||||
processing_function,
|
||||
validation_function)
|
||||
|
||||
@name (string)
|
||||
The displayed name of the menu item this macro will generate.
|
||||
|
||||
@description (string)
|
||||
A longer description of the function of this macro. This will appear
|
||||
on the status bar when hovering over the menu item.
|
||||
|
||||
@menu (string)
|
||||
The menu this macro will appear in. Can be one of:
|
||||
o "edit"
|
||||
o "video"
|
||||
o "audio"
|
||||
o "tools"
|
||||
o "right" (the subtitles grid right-click menu)
|
||||
The menu chosen should be relevant to the function of the macro.
|
||||
|
||||
@processing_function (function)
|
||||
The actual function called for the macro execution.
|
||||
This function must be an instance of the Macro Processing Function
|
||||
described below.
|
||||
|
||||
@validation_function (function)
|
||||
Optional. A function called when it is to be determined whether the
|
||||
macro can act on the current subtitles.
|
||||
This function, if provided, must execute very quickly to avoid lag
|
||||
in the GUI.
|
||||
This function must be an instance of the Macro Validation Function
|
||||
described below.
|
||||
|
||||
Returns: nothing.
|
||||
|
||||
---
|
||||
|
||||
Filter Registration Function
|
||||
|
||||
This is a function called from top level of an Automation script to register
|
||||
a new Export Filter Feature.
|
||||
|
||||
function aegisub.register_filter(
|
||||
name,
|
||||
description,
|
||||
priority,
|
||||
processing_function,
|
||||
options_window_provider)
|
||||
|
||||
@name (string)
|
||||
The name of the filter, as presented to the user.
|
||||
|
||||
@description (string)
|
||||
A longer description of the filter presented to the user.
|
||||
|
||||
@priority (number)
|
||||
A number determining the default order the enabled filters will be
|
||||
processed. The order can be overridden by the user.
|
||||
Priorities of some built-in filters:
|
||||
o Clean Script Info = 0
|
||||
o Fix Styles = -5000
|
||||
o Transform Framerate = 1000
|
||||
Filters with higher priority will be executed earlier by default.
|
||||
|
||||
@processing_function (function)
|
||||
The function called to do the actual filter processing.
|
||||
This function must be an instance of the Filter Processing Function
|
||||
described below.
|
||||
|
||||
@options_window_provider (function)
|
||||
Optional. A function providing a dialog template for setting options
|
||||
prior to filter processing.
|
||||
This function must be an instance of the Filter Options Window Provider
|
||||
function described below.
|
||||
|
||||
Returns: nothing.
|
||||
|
||||
---
|
||||
|
||||
Format Reader Registration
|
||||
|
||||
This is a function called from top level in an Automation script to register
|
||||
a new File Format Reader Feature.
|
||||
|
||||
function aegisub.register_reader(
|
||||
name,
|
||||
extension,
|
||||
processing_function)
|
||||
|
||||
@name (string)
|
||||
The name of the file format.
|
||||
|
||||
@extension (string)
|
||||
The file extension usually given to this file format. This must not
|
||||
include any wildcards. (Ie. extension could be "srt", "sub", "ssa" and
|
||||
so on.)
|
||||
|
||||
@processing_function (function)
|
||||
The function called to do the actual file import.
|
||||
This function must be an instance of the Format Reader Function described
|
||||
below.
|
||||
|
||||
Returns: nothing.
|
||||
|
||||
---
|
||||
|
||||
Format Writer Registration
|
||||
|
||||
This is a function called from top level in an Automation script to register
|
||||
a new File Format Writer Feature.
|
||||
|
||||
function aegisub.register_writer(
|
||||
name,
|
||||
extension,
|
||||
processing_function)
|
||||
|
||||
@name (string)
|
||||
Name of the file format, as presented to the user.
|
||||
|
||||
@extension (string)
|
||||
The usual file extension given to this file format. This is automatically
|
||||
be attached to the file name on export, unless the user chooses to
|
||||
override it.
|
||||
|
||||
@processing_function (function)
|
||||
The function doing the actual file export.
|
||||
This function must be an instance of the Format Writer Function described
|
||||
below.
|
||||
|
||||
Returns: nothing.
|
||||
|
||||
---
|
||||
|
||||
Macro Processing Function
|
||||
|
||||
This function is called by Aegisub to execute a macro.
|
||||
|
||||
function process_macro(
|
||||
subtitles,
|
||||
selected_lines,
|
||||
active_line)
|
||||
|
||||
The name of the function is script-defined. (It doesn't have to be
|
||||
process_macro.)
|
||||
|
||||
@subtitles (user data)
|
||||
A Subtitles Object, that can be used to retrieve information about the
|
||||
subtitle file the macro is being applied on.
|
||||
|
||||
@selected_lines (table)
|
||||
An Array Table of numbers, each entry being an index into the file
|
||||
represented by @subtitles. Each of the entries in this table describe that
|
||||
a line is marked as selected by the user.
|
||||
|
||||
@active_line (number)
|
||||
Index of the currently active line in the subtitle file.
|
||||
|
||||
Returns: nothing.
|
||||
|
||||
---
|
||||
|
||||
Macro Validation Function
|
||||
|
||||
This function is called by Aegisub to determine whether a macro can be applied
|
||||
to the current state of the subtitles and selection.
|
||||
|
||||
This function needs to execute very fast, since it may be called for several
|
||||
macros whenever a menu is opened. It is suggested not to use @subtitles at all
|
||||
in this function.
|
||||
|
||||
This function does not have to be defined. If it's undefined, it's taken as if
|
||||
it always returned true.
|
||||
|
||||
function validate_macro(
|
||||
subtitles,
|
||||
selected_lines,
|
||||
active_line)
|
||||
|
||||
The name of the function is script-defined. (It doesn't have to be
|
||||
validate_macro.)
|
||||
|
||||
@subtitles (user data)
|
||||
A Subtitles Object, that can be used to retrieve information about the
|
||||
subtitle file the macro is to be be applied on.
|
||||
|
||||
@selected_lines (table)
|
||||
An Array Table of numbers, each entry being an index into the file
|
||||
represented by @subtitles. Each of the entries in this table describe that
|
||||
a line is marked as selected by the user.
|
||||
|
||||
@active_line (number)
|
||||
Index of the currently active line in the subtitle file.
|
||||
|
||||
Returns: Boolean.
|
||||
true is the macro can be applied to the current state of the subtitles,
|
||||
false if not.
|
||||
|
||||
---
|
||||
|
||||
Filter Processing Function
|
||||
|
||||
This function is called by Aegisub to filter the subtitles during an export
|
||||
operation.
|
||||
|
||||
function process_filter(
|
||||
subtitles,
|
||||
config)
|
||||
|
||||
The name of the function is script-defined. (It doesn't have to be
|
||||
process_filter.)
|
||||
|
||||
@subtitles (user data)
|
||||
A Subtitles Object, that can be used to retrieve information about the
|
||||
subtitle file the filter is being applied on.
|
||||
|
||||
@config (table)
|
||||
A Dialog Result table representing the options the user selected for the
|
||||
filter before starting the export operation. The fields present in this
|
||||
table are defined by the dialog provided by the Filter Options Window
|
||||
Provider function.
|
||||
|
||||
Returns: nothing.
|
||||
|
||||
---
|
||||
|
||||
Filter Options Window Provider function
|
||||
|
||||
This function is called by Aegisub to get a Dialog Window definition to prompt
|
||||
the user for input before an export operation.
|
||||
The data input into the dialog returned by this function are automatically
|
||||
stored into the original subtitle file when an export operation is started.
|
||||
|
||||
function filter_options_dialog(
|
||||
subtitles,
|
||||
stored_options)
|
||||
|
||||
The name of the function is script-defined. (It doesn't have to be
|
||||
filter_options_dialog.)
|
||||
|
||||
@subtitles (user data)
|
||||
A Subtitles Object, that can be used to retrieve information about the
|
||||
subtitle file the filter is to be applied on.
|
||||
|
||||
@stored_options (table)
|
||||
The currently stored options for this export filter. The keys in this table
|
||||
are the option names, and the values are the values stored for those options.
|
||||
|
||||
Returns: A Dialog Window table.
|
||||
|
||||
---
|
||||
|
||||
Format Reader Function
|
||||
|
||||
This function is called by Aegisub to import a file from a foreign file
|
||||
format.
|
||||
|
||||
function read_format(
|
||||
input_file,
|
||||
output_subs)
|
||||
|
||||
The name of the function is script-defined. (It doesn't have to be
|
||||
read_format.)
|
||||
|
||||
@input_file (user data)
|
||||
An Input File Stream, representing the file selected for import.
|
||||
|
||||
@output_subs (user data)
|
||||
An empty Subtitles Object the imported data should be added to.
|
||||
|
||||
Returns: Boolean.
|
||||
True if the import succeeded, false if it failed.
|
||||
|
||||
---
|
||||
|
||||
Format Writer Function
|
||||
|
||||
This function is called by Aegisub to export a file to a foreign file format.
|
||||
|
||||
function write_format(
|
||||
input_subs,
|
||||
output_file)
|
||||
|
||||
The name of the function is script-defined. (It doesn't have to be
|
||||
write_format.)
|
||||
|
||||
@input_subs (user data)
|
||||
A Subtitles Object representing the subtitles to be exported.
|
||||
|
||||
@output_file (user data)
|
||||
An Ouput File Stream, representing the file the exported data should be
|
||||
written to.
|
||||
|
||||
Returns: Boolean.
|
||||
True if the export succeeded, false if it failed.
|
||||
If this function returns false, the output file is deleted from disk.
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -1,141 +0,0 @@
|
|||
Automation 4 Basic Interface
|
||||
|
||||
This document described the basic functions needed to define an Automation 4
|
||||
script. This covers Feature registration and the prototypes of functions used
|
||||
to implement the various features.
|
||||
|
||||
---
|
||||
|
||||
Macro Registation Function
|
||||
|
||||
This is a function called from top-level of an Automation script to register
|
||||
a new Macro Feature.
|
||||
|
||||
function aegisub.register_macro(
|
||||
name,
|
||||
description,
|
||||
menu,
|
||||
processing_function,
|
||||
validation_function)
|
||||
|
||||
@name (string)
|
||||
The displayed name of the menu item this macro will generate.
|
||||
|
||||
@description (string)
|
||||
A longer description of the function of this macro. This will appear
|
||||
on the status bar when hovering over the menu item.
|
||||
|
||||
@menu (string)
|
||||
The menu this macro will appear in. Can be one of:
|
||||
o "edit"
|
||||
o "video"
|
||||
o "audio"
|
||||
o "tools"
|
||||
o "right" (the subtitles grid right-click menu)
|
||||
The menu chosen should be relevant to the function of the macro.
|
||||
|
||||
@processing_function (function)
|
||||
The actual function called for the macro execution.
|
||||
This function must be an instance of the Macro Processing Function
|
||||
described below.
|
||||
|
||||
@validation_function (functioon)
|
||||
Optional. A function called when it is to be determined whether the
|
||||
macro can act on the current subtitles.
|
||||
This function, if provided, must execute very quickly to avoid lag
|
||||
in the GUI.
|
||||
This function must be an instance of the Macro Validation Function
|
||||
described below.
|
||||
|
||||
---
|
||||
|
||||
Filter Registration Function
|
||||
|
||||
This is a function called from top level of an Automation script to register
|
||||
a new Export Filter Feature.
|
||||
|
||||
function aegisub.register_filter(
|
||||
name,
|
||||
description,
|
||||
priority,
|
||||
processing_function,
|
||||
options_window_provider)
|
||||
|
||||
@name (string)
|
||||
The name of the filter, as presented to the user.
|
||||
|
||||
@description (string)
|
||||
A longer description of the filter presented to the user.
|
||||
|
||||
@priority (nhumber)
|
||||
A number determining the default order the enabled filters will be
|
||||
processed. The order can be overridden by the user.
|
||||
Priorities of some built-in filters:
|
||||
o Clean Script Info = 0
|
||||
o Fix Styles = -5000
|
||||
o Transform Framerate = 1000
|
||||
Filters with higher priority will be executed earlier by default.
|
||||
|
||||
@processing_function (function)
|
||||
The function called to do the actual filter processing.
|
||||
This function must be an instance of the Filter Processing Function
|
||||
described below.
|
||||
|
||||
@options_window_provider (function)
|
||||
Optional. A function providing a dialog template for setting options
|
||||
prior to filter processing.
|
||||
This function must be an instance of the Filter Options Window Provider
|
||||
function described below.
|
||||
|
||||
---
|
||||
|
||||
Format Reader Registration
|
||||
|
||||
This is a function called from top level in an Automation script to register
|
||||
a new File Format Reader Feature.
|
||||
|
||||
function aegisub.register_reader(
|
||||
name,
|
||||
extension,
|
||||
processing_function)
|
||||
|
||||
@name (string)
|
||||
The name of the file format.
|
||||
|
||||
@extension (string)
|
||||
The file extension usually given to this file format. This must not
|
||||
include any wildcards. (Ie. extension could be "srt", "sub", "ssa" and
|
||||
so on.)
|
||||
|
||||
@processing_function (function)
|
||||
The function called to do the actual file import.
|
||||
This function must be an instance of the Format Reader Function described
|
||||
below.
|
||||
|
||||
---
|
||||
|
||||
Format Writer Registration
|
||||
|
||||
This is a function called from top level in an Automation script to register
|
||||
a new File Format Writer Feature.
|
||||
|
||||
function aegisub.register_writer(
|
||||
name,
|
||||
extension,
|
||||
processing_function)
|
||||
|
||||
@name (string)
|
||||
Name of the file format, as presented to the user.
|
||||
|
||||
@extension (string)
|
||||
The usual file extension given to this file format. This is automatically
|
||||
be attached to the file name on export, unless the user chooses to
|
||||
override it.
|
||||
|
||||
@processing_function (function)
|
||||
The function doing the actual file export.
|
||||
This function must be an instance of the Format Writer Function described
|
||||
below.
|
||||
|
||||
---
|
||||
|
||||
Loading…
Reference in a new issue