Originally committed to SVN as r239.

This commit is contained in:
Niels Martin Hansen 2006-03-22 21:57:03 +00:00
parent bc28f47f1c
commit d45fb68058
2 changed files with 238 additions and 1 deletions

View file

@ -26,7 +26,7 @@ function aegisub.register_macro(
on the status bar when hovering over the menu item.
@menu (string)
The menu this macro will appear in. Can be one of:
The menu this macro will appear in. Must be one of:
o "edit"
o "video"
o "audio"

View file

@ -0,0 +1,237 @@
Automation 4 Subtitle Data format and functions API
This file describes the API for retrieving and manipulating subtitle data in
Automation 4, as well as the data structures generated and accepted by these
APIs.
---
Subtitle Line table
A Subtitle Line table contains various information about a line in the
subtitle file being processed. There are several classes of subtitle lines,
which all have a few fields in common, but otherwise have different fields.
Common keys for all Subtitle Line classes:
class (string)
The class of the Subtitle Line. Must be one of:
"clear", (empty line)
"comment", (semicolon-style comment line)
"head", (section heading)
"info", (key/value pair in Script Info section)
"format", (line format definition)
"style", (style definition line)
"stylex", (style extension line, tentative AS5 feature)
"dialogue", (dialogue line or dialogue-style comment line)
"unknown" (unknown kind of line)
Lines of the "unknown" class should never appear in well-formed subtitle
scripts. They will usually be a result of a line being outside the section
it belongs in.
raw (string)
The raw text of the line.
You should not change this field directly, since the data in it will never
be used for generating lines in internal representation. It will, however,
be updated from the remaining data in the line whenever it is required for
one thing or another by an internal function.
section (string)
The section this line is placed in. If it is placed before the first section
heading, this field is nil.
Key defined only for the "comment" class:
text (string)
The text of the comment line, ie. everything after the initial semicolon,
including any spaces.
Key defined only for the "head" class:
No special keys are defined for this class, but the "section" field will be
the name of the new section started.
Keys defined only for the "info" class:
key (string)
The "key" part of the line, ie. everything before the first colon.
value (string)
The "value" part of the line, ie. everything after the first colon,
discarding any leading whitespace.
Keys defined only for the "format" class:
fields (table)
An Array Table of strings, each being the name of a field on the line.
Keys defined only for the "style" class:
name (string)
Name of the style.
fontname (string)
Name of the font used.
fontsize (string)
Size of the font used, in pixels.
color1 (string)
color2 (string)
color3 (string)
color4 (string)
The four colors for the style. (Fill, pre-karaoke fill, border, shadow)
In VB hexadecimal, ie. "&HAABBGGRR&"
bold (boolean/number)
The boldness/weight of the font. This will usually be a boolean, but it
can be a number, in which case it must be one of 0, 100, 200, ..., 900.
italic (boolean)
underline (boolean)
strikeout (boolean)
Other properties of the font.
scale_x (number)
scale_y (number)
Scaling of the text, in percent.
spacing (number)
Additional spacing between letters. Always integer.
angle (number)
Rotation of the text on the Z axis in degrees.
borderstyle (number)
1 = outline and drop shadow; 3 = opaque box.
outline (number)
Width of the outline.
shadow (number)
Distance between shadow and text.
align (number)
Numpad alignment of the text.
margin_l (number)
margin_r (number)
margin_t (number)
margin_b (number)
Left/right/top/bottom margins of the text in pixels.
If using a format without support for separate top and bottom margins, the
margin_t value will be used for vertical margin when converting back to
textual representation.
encoding (number)
Font encoding used for text. This follows the MS Windows font encoding
constants.
relative_to (number)
???
vertical (boolean)
Whether vertical text semantics is used or not.
Keys defined only for the "stylex" class:
Remember that this class is only for the tentative AS5 format.
name (string)
Name of the new style defined.
basename (string)
Name of the style the new style is based on.
overrides (string)
String of override tags defining the new style.
Keys only defined for the "dialogue" class:
comment (boolean)
True if the line is a comment line, otherwise false.
layer (number)
The layer the line is rendered in.
start_time (number)
end_time (number)
Start/end time of the line in miliseconds.
style (string)
Name of the style assigned to this line.
actor (string)
Name of the actor performing this line.
margin_l (number)
margin_r (number)
margin_t (number)
margin_b (number)
Left/right/top/bottom margins of the text in pixels.
If any of these are zero, it's considered "not overriding".
Same comment as for style lines applies.
effect (string)
Effect to apply to the line.
userdata (string)
Authoring-application defined data. (Tentative AS5 field.)
text (string)
The text for this line.
---
Subtitle File user data object
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:
n = subs[0]
n = subs.length
Retrieve the number of lines in total.
line = subs[i]
Retrieve line i, assuming 1 <= i <= n.
subs[i] = line
Replace line i with new data.
subs[i] = nil
subs.delete(i[, i2, ...])
Delete line i, pushing all following lines up an index. (Ie. by repeatedly
deleting line 1 this way, the file will eventually end up empty.)
The function syntax for this function can also take multiple line indexes,
in which case it deletes each of those lines. All indexes are relative to
the line numbering before the function is called.
subs.deleterange(a, b)
Deletes all lines from index a to index b, both inclusive. If b < a,
nothing is done.
subs[0] = line
subs.append(line)
Append a line to the file.
subs[-i] = line
subs.insert(i, line[, line2, ...])
Insert a line before index i.
The function syntax can also insert multiple lines.
(Note that the function-syntax ways of doing these operations is slower than
the array-syntax way of doing them.)
---