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