More auto4 docs work.
Originally committed to SVN as r249.
This commit is contained in:
Niels Martin Hansen
parent
48c466c070
commit
99c38fefb0
4 changed files with 324 additions and 29 deletions
32
automation/v4-docs/misc.txt
Normal file
32
automation/v4-docs/misc.txt
Normal 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.
|
||||
|
||||
---
|
||||
|
|
@ -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.
|
||||
|
|
|
|||
102
automation/v4-docs/progress-reporting.txt
Normal file
102
automation/v4-docs/progress-reporting.txt
Normal 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.
|
||||
|
||||
---
|
||||
|
|
@ -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.
|
||||
|
||||
---
|
||||
|
|
|
|||
Loading…
Reference in a new issue