diff --git a/automation/v4-docs/basic-function-interface.txt b/automation/v4-docs/basic-function-interface.txt new file mode 100644 index 000000000..dfbd6b632 --- /dev/null +++ b/automation/v4-docs/basic-function-interface.txt @@ -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. + +--- + diff --git a/automation/v4-docs/data-structures.txt b/automation/v4-docs/data-structures.txt deleted file mode 100644 index efc262749..000000000 --- a/automation/v4-docs/data-structures.txt +++ /dev/null @@ -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. - ---- -