More auto4 docs work.

Originally committed to SVN as r249.
This commit is contained in:
Niels Martin Hansen 2006-03-26 13:00:17 +00:00
parent 48c466c070
commit 99c38fefb0
4 changed files with 324 additions and 29 deletions

View file

@ -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.
---

View file

@ -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.

View file

@ -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.
---

View file

@ -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.
---