Professional Documents
Culture Documents
$Id$
1 - About Lua
=============
Lua documentation is available on http://www.lua.org/ . The reference manual
is very useful: http://www.lua.org/manual/5.1/ .
VLC uses Lua 5.1
All the Lua standard libraries are available.
2 - Lua in VLC
==============
Several types of VLC Lua scripts can currently be coded:
* Playlist and websites parsers (see playlist/README.txt)
* Art fetchers (see meta/README.txt)
* Interfaces (see intf/README.txt)
* Extensions (see extensions/README.txt)
* Services Discovery (see sd/README.txt)
Lua scripts are tried in alphabetical order in the user's VLC config
directory lua/{playlist,meta,intf}/ subdirectory on Windows and Mac OS X or
in the user's local share directory (~/.local/share/vlc/lua/... on linux),
then in the global VLC lua/{playlist,meta,intf}/ directory.
3 - VLC specific Lua modules
============================
All VLC specifics modules are in the "vlc" object. For example, if you want
to use the "info" function of the "msg" VLC specific Lua module:
vlc.msg.info( "This is an info message and will be displayed in the console" )
Note: availability of the different VLC specific Lua modules depends on
the type of VLC Lua script your are in.
Configuration
------------config.get( name ): Get the VLC configuration option "name"'s value.
config.set( name, value ): Set the VLC configuration option "name"'s value.
config.datadir(): Get the VLC data directory.
config.userdatadir(): Get the user's VLC data directory.
config.homedir(): Get the user's home directory.
config.configdir(): Get the user's VLC config directory.
config.cachedir(): Get the user's VLC cache directory.
config.datadir_list( name ): Get the list of possible data directories in
order of priority, appended by "name"
Dialog
-----local d = vlc.dialog( "My VLC Extension" ): Create a new UI dialog, with a human
-readable title: "My VLC Extension"
d:show(): Show this dialog.
d:hide(): Hide (but not close) this dialog.
d:delete(): Close and delete this dialog.
d:set_title( title ): set the title of this dialog.
d:update(): Update the dialog immediately (don't wait for the current function t
o return)
d:del_widget( widget ): Delete 'widget'. It disappears from the dialog and repos
itioning may occur.
In the following functions, you can always add some optional parameters: col, ro
w, col_span, row_span, width, height.
They define the position of a widget in the dialog:
- row, col are the absolute positions on a grid of widgets. First row, col are 1
.
- row_span, col_span represent the relative size of a widget on the grid. A widg
et with col_span = 4 will be displayed as wide as 4 widgets of col_span = 1.
- width and height are size hints (in pixels) but may be discarded by the GUI mo
dule
Example: w = d:add_label( "My Label", 2, 3, 4, 5 ) will create a label at row 3,
col 2, with a relative width of 4, height of 5.
d:add_button( text, func, ... ): Create a button with caption "text" (string). W
hen clicked, call function "func". func is a function reference.
d:add_label( text, ... ): Create a text label with caption "text" (string).
d:add_html( text, ... ): Create a rich text label with caption "text" (string),
that supports basic HTML formatting (such as <i> or <h1> for instance).
d:add_text_input( text, ... ): Create an editable text field, in order to read u
ser input.
d:add_password( text, ... ): Create an editable text field, in order to read use
r input. Text entered in this box will not be readable (replaced by asterisks).
d:add_check_box( text, ... ): Create a check box with a text. They have a boolea
n state (true/false).
d:add_dropdown( ... ): Create a drop-down widget. Only 1 element can be selected
the same time.
d:add_list( ... ): Create a list widget. Allows multiple or empty selections.
d:add_image( path, ... ): Create an image label. path is a relative or absolute
path to the image on the local computer.
Some functions can also be applied on widgets:
w:set_text( text ): Change text displayed by the widget. Applies to: button, lab
el, html, text_input, password, check_box.
w:get_text(): Read text displayed by the widget. Returns a string. Applies to: b
utton, label, html, text_input, password, check_box.
w:set_checked( bool ): Set check state of a check box. Applies to: check_box.
w:get_checked(): Read check state of a check box. Returns a boolean. Applies to:
check_box.
w:add_value( text, id ): Add a value with identifier 'id' (integer) and text 'te
xt'. It's always best to have unique identifiers. Applies to: drop_down.
w:get_value(): Return identifier of the selected item. Corresponds to the text v
alue chosen by the user. Applies to: drop_down.
w:clear(): Clear a list or drop_down widget. After that, all values previously a
dded are lost.
w:get_selection(): Retrieve a table representing the current selection. Keys are
the ids, values are the texts associated. Applies to: list.
Extension
--------deactivate(): Deactivate current extension (after the end of the current functio
n).
HTTPd
----http( host, port, [cert, key, ca, crl]): create a new HTTP (SSL) daemon.
Win
--This module is only available on Windows builds
win.console_init(): Initialize the windows console.
win.console_wait([timeout]): Wait for input on the console for timeout ms.
Returns true if console input is available.
win.console_read(): Read input from the windows console. Note that polling and
reading from stdin does not work under windows.
XML
--xml = vlc.xml(): Create an xml object.
reader = xml:create_reader( stream ): create an xml reader that use the given st
ream.
reader:read(): read some data, return -1 on error, 0 on EOF, 1 on start of XML
element, 2 on end of XML element, 3 on text
reader:name(): name of the element
reader:value(): value of the element
reader:next_attr(): next attribute of the element
The simplexml module can also be used to parse XML documents easily.