From 99c38fefb08e658377f1fd13f6aafcd074084d58 Mon Sep 17 00:00:00 2001 From: Niels Martin Hansen Date: Sun, 26 Mar 2006 13:00:17 +0000 Subject: [PATCH] More auto4 docs work. Originally committed to SVN as r249. --- automation/v4-docs/misc.txt | 32 ++++ automation/v4-docs/overview.txt | 36 ++--- automation/v4-docs/progress-reporting.txt | 102 ++++++++++++ automation/v4-docs/subtitle-data.txt | 183 ++++++++++++++++++++-- 4 files changed, 324 insertions(+), 29 deletions(-) create mode 100644 automation/v4-docs/misc.txt create mode 100644 automation/v4-docs/progress-reporting.txt diff --git a/automation/v4-docs/misc.txt b/automation/v4-docs/misc.txt new file mode 100644 index 000000000..5f9050f4d --- /dev/null +++ b/automation/v4-docs/misc.txt @@ -0,0 +1,32 @@ +Miscellaneous functions in Automation 4 + +This document describes various functions that couldn't be placed in any of +the other Automation 4 documents. + +--- + +Getting the rendered size of a string + +This function might later on be part of a full rendering-interface for +creating actual bitmaps of text. + +This function does NOT attempt to handle line breaks, automatic line breaking, +fomatting override tags, vector drawings or anything else to that effect. +If you need such functionality, you need to implement it yourself. (For now, +at least.) + +function aegisub.text_extents(style, text) + +@style (table) + A "style" class Subtitle Line table. This + +@text (string) + The text to calculate the rendered size of. + +Returns: 4 values, all numbers. + 1. Width of text in pixels. + 2. Height of text in pixels. + 3. Descent of text in pixels. + 4. External leading of text in pixels. + +--- diff --git a/automation/v4-docs/overview.txt b/automation/v4-docs/overview.txt index abe0377e5..5479af0e9 100644 --- a/automation/v4-docs/overview.txt +++ b/automation/v4-docs/overview.txt @@ -1,8 +1,8 @@ Aegisub Automation documentation Version 4 Copyright 2005-2006 Niels Martin Hansen -THIS IS A DRAFT. SUBJECT TO CHANGE. -Last updated: 2006-02-01 04:17 UTC+1 + +THIS IS OUT OF DATE COMPARED TO THE REST OF THE DOCS! --- @@ -31,6 +31,11 @@ Automation allows you to: o Exporters write directly to a file stream, allowing you to generate those huge karaoke effects much faster! +Automation runs in a true Unicode environment, meaning strings are internally +represented as UTF-32, so you, as programmer, don't have to worry about text +encodings, prefix encodings etc. to write scripts that can handle text in +mostly any language of the world. + --- Scripts, files functions @@ -41,7 +46,8 @@ being the master script, and the others being include files. Every script runs in a separate Lua interpreter, so separate scripts cannot communicate directly with each other. Scripts can share code by having common -include files. +include files. Scripts can share data by storing data in the subtitle files, +either in the dialogue lines or in the Script Info headers. Files containing Automation scripts must in UTF-8 encoding, with or without BOM (Byte Order Mark). Compiled Lua scripts should also work, as long as all @@ -65,9 +71,9 @@ The following four features can be implemented by an Automation script: The macro can create and display dialog windows to the user. - For preformance-reasons, there is currently no provision for the script to - enable/disable its menu item based on eg. the selection in the Aegisub - subtitles grid. + A macro can provide a function, that determines whether the macro cen be + run, based on the current selection in the program, and the contents of + the subtitles. - Export filter An export filter is presented as a filter in the Export dialog accessed @@ -76,16 +82,10 @@ The following four features can be implemented by an Automation script: Styles and Script Info lines) in the subtitle file, and can add/modify/ remove lines in those. - The export filter can specify a static configuration dialog presented to - the user in the Export UI. - - The export filter can specify a function that's run after the user selects - the Export item on the File menu, but before the Export dialog is actually - displayed. This function will be given access to the subtitles currently - loaded. This is to feature customising the configuration dialog based on - the contents of the subtitles. - It is strongly discouraged to change anything but a single, private Script - Info header line in the subtitles handed to this initialisation function. + The export filter can provide a function, that returns a configuration + dialog, which is presented to the user before the export is run. This + function can access the subtitle data in order to customise the + configuration dialog, before it's presented to the user. - File format reader It is not yet decided how the file format reader is accessed. @@ -166,11 +166,11 @@ Version 2 Version 3 Using Lua as engine. - Aegisub 1.10 was the last version to use Automation 3. + Aegisub 1.09 was the last release-version to use Automation 3. (Tentative release date only!) Version 4 Using Lua as engine - Present in Aegisub 1.11 and later (tentative!) + Present in Aegisub 1.10 and later (tentative!) Heavily expanded feature set, allowing a much wider range of modifications, and more direct integration into the Aegisub user interface. diff --git a/automation/v4-docs/progress-reporting.txt b/automation/v4-docs/progress-reporting.txt new file mode 100644 index 000000000..3fd1e6093 --- /dev/null +++ b/automation/v4-docs/progress-reporting.txt @@ -0,0 +1,102 @@ +Automation 4 Progress Reporting and Debugging interface + +This document describes the functions used for reporting progress and +outputting debug information during the running of a script. + +--- + +Showing/hiding the progress dialog + +This function is used to show or hide the progress dialog. + +function aegisub.progress.show(do_show, can_cancel) + +@do_show (boolean) + True if the dialog should be shown, false if it should be hidden. + +@can_cancel (boolean) + Determines whether the Cancel button is shown. If you set this to true, + you should remember to periodically test whether the script has been + cancelled. + +Returns: nothing. + +--- + +Setting the progress bar position + +function aegisub.progress.set(precent) + +@percent (number) + The percentage completed. + +Returns: nothing. + +--- + +Showing the current task + +Used to set a message describing the current task being done. + +function aegisub.progress.task(msg, ...) + +@msg (string) + A format string used for the message. + +@... + Parameters to the format string. + +Returns: nothing. + +--- + +Setting the progress dialog title + +function aegisub.progress.title(title, ...) + +@title (string) + A format string used for the title. + +@... + Parameters to the format string. + +Returns: nothing. + +--- + +Getting the "cancelled" status + +Call this function to determine whether the Cancel button in the progress +dialog has been clicked. + +function aegisub.progress.is_cancelled() + +Returns: Boolean. True is the user has clicked the Cancel button, false if it + has not been clicked, nil if there is no Cancel button. + +--- + +Outputting text to the debug log + +function aegisub.debug.out(level, msg, ...) + +@level (number) + Integer describing the verbosity of this message. Here are some suggested + values you can use: + 0: Fatal, this is really an error that can't be ignored. + 1: Error, this kind of error can be recovered from, but might result in a + fatal error later on. + 2: Warning, something might be going wrong. + 3: Hint, something isn't entirely sane, but nothing wrong. + 4: Debug, some additional data only needed for development. + 5: Trace, extremely verbose data showing every tiny step during execution. + +@msg (string) + A format string used for the message. + +@... + Parameters for the format string. + +Returns: nothing. + +--- diff --git a/automation/v4-docs/subtitle-data.txt b/automation/v4-docs/subtitle-data.txt index 79b4266ff..5b192d977 100644 --- a/automation/v4-docs/subtitle-data.txt +++ b/automation/v4-docs/subtitle-data.txt @@ -134,7 +134,7 @@ encoding (number) constants. relative_to (number) - ??? + From STS.h: "0: window, 1: video, 2: undefined (~window)" vertical (boolean) Whether vertical text semantics is used or not. @@ -164,7 +164,7 @@ layer (number) start_time (number) end_time (number) - Start/end time of the line in miliseconds. + Start/end time of the line in milliseconds. style (string) Name of the style assigned to this line. @@ -197,11 +197,12 @@ The Subtitle File object is a user data object with some of the metatable methods overridden to provide table-like access to the subtitle lines, as well as some functions to modify the subtitles. -The following operations are supported: +The following operations are supported. -n = subs[0] -n = subs.length +n = #subs +n = subs.n Retrieve the number of lines in total. + The first syntax is preferred. line = subs[i] Retrieve line i, assuming 1 <= i <= n. @@ -222,16 +223,176 @@ subs.deleterange(a, b) nothing is done. subs[0] = line -subs.append(line) - Append a line to the file. +subs.append(line[, line2, ...]) + Append one or more lines to a file. subs[-i] = line subs.insert(i, line[, line2, ...]) - Insert a line before index i. - The function syntax can also insert multiple lines. + Insert one or more lines before index i. -(Note that the function-syntax ways of doing these operations is slower than -the array-syntax way of doing them.) +Note that the array-style accessors are most likely faster for any case only +involving one line at a time, while the function syntax versions are probably +faster if operating on multiple lines at a time. --- +Parsing tag data + +This function uses the Aegisub SSA parser to split a string into override +blocks and text, and give separate access to each tag in override blocks. + +function aegisub.parse_tag_data(text) + +@text (string) + The SSA format string to parse. + +Returns: A Parsed Tag Data table. + +--- + +Recreating a line from tag data + +This function takes a Parsed Tag Data table and creates an SSA string from it. + +function aegisub.unparse_tag_data(tagdata) + +@tagdata (table) + The Parsed Tag Data table to "unparse". + +Returns: A string, being the "unparsed" data. + +--- + +Parsing karaoke data + +Tihs function uses the Aegisub SSA parser to split a string into karaoke +syllables with additional calculated information added. + +function aegisub.parse_karaoke_data(text) + +@text (string) + The SSA format string to parse. + +Returns: A Parsed Karaoke Data table. + +--- + +Parsed Tag Data table + +The Parsed Tag Data table is an Array Table containing a number of Parsed Line +Block tables. + + +Parsed Line Block table + +A Parsed Line Block describes part of a line. (See ass_dialogue.cpp:70 for a +more complete description of this. +There are several classes of Parsed Line Block tables, which have slightly +varying fields. + + +Base Parsed Line Block table class + +class (string) + One of: + "plain", + "override", + "drawing" + + +"plain" and "drawing" Parsed Line Block table classes + +text (string) + The text contained in this block. + + +"override" Parsed Line Block table class + +This class doesn't have any new, specifically named fields. It does, however, +have multiple integer indexed fields, ie. acts as an Array Table. +Each of these indexes refer to a table of type Parsed Override Tag. + + +Parsed Override Tag table + +This table describes a single override-tag in an SSA line. + +valid (boolean) + Whether this tag was parsed as a valid tag, or is just used for representing + junk in the middle of the line. + +name (string) + Name of the tag, including leading backslash character. (In the case of + invalid tags, the leading backslash might not be present.) + +paran (boolean) + Whether this tag has parantheses in its textual representation. + +params (table) + This is an Array Table containing the parameters for this tag. It will + always have the maximum number of entries that can be supported by the tag, + but in case of omitted parameters, the parameters omitted will have 'false' + for value in this table. + +--- + +Parsed Karaoke Data table + +The Parsed Karaoke Data table is simply an Array Table of Karaoke Syllable +Data tables. However, the Parsed Karaoke Data table will always have one more +item than its count shows, which is numbered 0 (zero). This item contains +everything before the first syllable. + + +Karaoke Syllable Data table + +This table contains information about a single karaoke syllable. + +duration (number) + Duration of the syllable in milliseconds. + (In case of syllable zero, this is always zero.) + +start_time (number) +end_time (number) + Start and end times of the syllable, relative to the start of the line, + given in milliseconds. + (While these can technically easily be calculated from the duration data, + they are too convenient to leave out from the standard interface.) + +tag (string) + The tag used for marking up this syllable. Usually one of: + "k", "K", "kf", "ko" + (In case of syllable zero, this is always the empty string.) + +text (string) + The text of the syllable, including all additional override tags. + +text_stripped (string) + The text of the syllable, stripped of any override tags. + +--- + +Setting undo points + +This function can only be used in macro features, it will have no effect when +used in any other feature. +It sets an undo point. + +You should always call this function after every operation that must be +undoable as a separate step. It is considered very bad practice to modify +the subtitles in a macro without setting at least one undo-point, which must +be at the end. + +Furthermore, this function also marks the subtitles as "modified". No other +function does this. + +function aegisub.set_undo_point(description) + +@description (string) + A short description of the operation that will be undone, if this undo-point + is used. Note that this is currently unused in Aegisub, and this parameter + is simply ignored. + +Returns: nothing. + +---