[vlc-commits] [Git][videolan/vlc][master] lua: initial work for generated documentation
François Cartegnie (@fcartegnie)
gitlab at videolan.org
Fri Apr 17 05:23:04 UTC 2026
François Cartegnie pushed to branch master at VideoLAN / VLC
Commits:
8dcde174 by Marvin Scholz at 2026-04-17T06:32:55+02:00
lua: initial work for generated documentation
- - - - -
6 changed files:
- doc/Makefile.am
- + doc/ldoc-config.ld
- modules/lua/libs/configuration.c
- modules/lua/libs/dialog.c
- modules/lua/libs/strings.c
- + share/lua/extensions/Extensions.md
Changes:
=====================================
doc/Makefile.am
=====================================
@@ -92,6 +92,7 @@ EXTRA_DIST = \
translations.txt \
demo.sh \
doc_helper.sh \
+ ldoc-config.ld \
$(NULL)
DISTCLEANFILES = Doxyfile
@@ -103,6 +104,9 @@ Doxyfile: Doxyfile.in $(top_builddir)/config.status
doc: Doxyfile
doxygen
+luadoc: ldoc-config.ld
+ ldoc -c '$<' -d $(abs_builddir)/luadoc .
+
$(CHANGELOGS): Makefile.am
if test -e "$(top_srcdir)/.git"; then \
y="$@"; y="$${y##ChangeLog-}" ; \
@@ -113,7 +117,7 @@ $(CHANGELOGS): Makefile.am
fi
# This one needs to be rebuilt all the time :)
-.PHONY: ChangeLog-2024 changelogs doc
+.PHONY: ChangeLog-2024 changelogs doc luadoc
changelogs: $(CHANGELOGS)
=====================================
doc/ldoc-config.ld
=====================================
@@ -0,0 +1,21 @@
+project = "VLC"
+title = "VLC Lua scripting"
+description = "The VLC Lua scripting reference documentation"
+format = 'markdown'
+style = "!new"
+merge = true
+no_space_before_args = true
+wrap = true
+boilerplate = true
+file = {
+ '../modules/lua/libs/configuration.c',
+ '../modules/lua/libs/dialog.c',
+ '../modules/lua/libs/strings.c',
+}
+kind_names={
+ topic='Manuals',
+}
+
+topics = {
+ '../share/lua/extensions/Extensions.md',
+}
=====================================
modules/lua/libs/configuration.c
=====================================
@@ -20,9 +20,13 @@
* Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston MA 02110-1301, USA.
*****************************************************************************/
-/*****************************************************************************
+/// VLC configuration interactions.
+// Functions to query or change VLC configuration options
+// @module vlc.config
+
+/*
* Preamble
- *****************************************************************************/
+ */
#ifndef _GNU_SOURCE
# define _GNU_SOURCE
#endif
@@ -37,9 +41,17 @@
#include "../vlc.h"
#include "../libs.h"
-/*****************************************************************************
- * Config handling
- *****************************************************************************/
+/// Config handling.
+// Functions to query or manipulate VLC configuration options.
+// @section config_handling
+
+/// Get a VLC config options value.
+//
+// Get the VLC configuration option `name`'s value.
+// @function get
+// @tparam string name Option name to get the value from
+// @treturn string|int|bool|number The option value
+// @raise Errors for an unknown option
static int vlclua_config_get( lua_State *L )
{
const char *psz_name = luaL_checkstring( L, 1 );
@@ -72,6 +84,13 @@ static int vlclua_config_get( lua_State *L )
return 1;
}
+/// Set a VLC config options value.
+//
+// Set the VLC configuration option `name`'s value.
+// @function set
+// @tparam string name Option name to set the value for
+// @tparam string|int|bool|number value Value to set the option to
+// @raise Errors for an unknown option
static int vlclua_config_set( lua_State *L )
{
const char *psz_name = luaL_checkstring( L, 1 );
@@ -99,9 +118,15 @@ static int vlclua_config_set( lua_State *L )
return 0;
}
-/*****************************************************************************
- * Directories configuration
- *****************************************************************************/
+/// Directories configuration.
+// Functions to query _special_ directories for the system VLC is running on.
+// @section config_dirs
+
+/// Get the VLC data directory.
+//
+// Returns the path of the VLC data directory (`VLC_PKG_DATA_DIR`).
+// @function datadir
+// @treturn string Path to the VLC data directory
static int vlclua_datadir( lua_State *L )
{
char *psz_data = config_GetSysPath(VLC_PKG_DATA_DIR, NULL);
@@ -110,6 +135,11 @@ static int vlclua_datadir( lua_State *L )
return 1;
}
+/// Get the user's VLC data directory.
+//
+// Returns the path of the user's VLC data directory (`VLC_USERDATA_DIR`).
+// @function userdatadir
+// @treturn string Path to the user's VLC data directory
static int vlclua_userdatadir( lua_State *L )
{
char *dir = config_GetUserDir( VLC_USERDATA_DIR );
@@ -118,6 +148,11 @@ static int vlclua_userdatadir( lua_State *L )
return 1;
}
+/// Get the user's home directory.
+//
+// Returns the path of the user's home directory (`VLC_HOME_DIR`).
+// @function homedir
+// @treturn string Path to the user's home directory
static int vlclua_homedir( lua_State *L )
{
char *home = config_GetUserDir( VLC_HOME_DIR );
@@ -126,6 +161,11 @@ static int vlclua_homedir( lua_State *L )
return 1;
}
+/// Get the user's VLC config directory.
+//
+// Returns the path of the user's VLC configuration directory (`VLC_CONFIG_DIR`).
+// @function configdir
+// @treturn string Path to the user's VLC config directory
static int vlclua_configdir( lua_State *L )
{
char *dir = config_GetUserDir( VLC_CONFIG_DIR );
@@ -134,6 +174,11 @@ static int vlclua_configdir( lua_State *L )
return 1;
}
+/// Get the user's VLC cache directory.
+//
+// Returns the path of the user's VLC cache directory (`VLC_CACHE_DIR`).
+// @function cachedir
+// @treturn string Path to the user's VLC cache directory
static int vlclua_cachedir( lua_State *L )
{
char *dir = config_GetUserDir( VLC_CACHE_DIR );
@@ -142,6 +187,13 @@ static int vlclua_cachedir( lua_State *L )
return 1;
}
+/// Get a list of possible data directories.
+//
+// Returns the list of possible data directories in order
+// of priority, appended by `name`.
+// @function datadir_list
+// @tparam string name Name for the data directory
+// @treturn {string,...} Paths to possible data directories, sorted by priority
static int vlclua_datadir_list( lua_State *L )
{
const char *psz_dirname = luaL_checkstring( L, 1 );
@@ -162,9 +214,9 @@ static int vlclua_datadir_list( lua_State *L )
return 1;
}
-/*****************************************************************************
+/*
*
- *****************************************************************************/
+ */
static const luaL_Reg vlclua_config_reg[] = {
{ "get", vlclua_config_get },
{ "set", vlclua_config_set },
=====================================
modules/lua/libs/dialog.c
=====================================
@@ -20,9 +20,13 @@
* Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston MA 02110-1301, USA.
*****************************************************************************/
-/*****************************************************************************
+/// Dialog user interface APIs.
+// Functions to create interface dialogs from Lua extensions.
+// @module vlc.dialog
+
+/*
* Preamble
- *****************************************************************************/
+ */
#ifndef _GNU_SOURCE
# define _GNU_SOURCE
#endif
@@ -40,57 +44,365 @@
#include "assert.h"
-/*****************************************************************************
+/*
*
- *****************************************************************************/
+ */
/* Dialog functions */
+
+/// Dialog methods
+//
+// A dialog object represents a dialog window, which can
+// contain multiple Widgets.
+// @section dialog_methods
+
+/// Create a dialog
+//
+// Create a new user interface dialog object
+// @function dialog
+// @tparam string title Human-readable title of the dialog
+// @treturn Dialog A new Dialog object
static int vlclua_dialog_create( lua_State *L );
+
+/// Close and delete this dialog.
+//
+// @function Dialog:delete
static int vlclua_dialog_delete( lua_State *L );
+
+/// Show this dialog.
+//
+// @function Dialog:show
static int vlclua_dialog_show( lua_State *L );
+
+/// Hide (but not close) this dialog.
+//
+// @function Dialog:hide
static int vlclua_dialog_hide( lua_State *L );
+
+/// Set the title for this dialog.
+//
+// @function Dialog:set_title
+// @tparam string title New human-readable title for this dialog
static int vlclua_dialog_set_title( lua_State *L );
+
+/// Update this dialog immediately.
+//
+// Update the dialog immediately (don't wait for the current function to return).
+// @function Dialog:update
static int vlclua_dialog_update( lua_State *L );
+
static void lua_SetDialogUpdate( lua_State *L, int flag );
static int lua_GetDialogUpdate( lua_State *L );
int lua_DialogFlush( lua_State *L );
+/// Widget creation.
+//
+// The functions in this section all create and add widgets to the dialog.
+//
+// In the following functions, you can always add some optional parameters:
+// `col`, `row`, `col_span`, `row_span`, `width`, `height`.
+//
+// They define the position of a widget in the dialog:
+//
+// - `row` and `col` are the absolute positions on a grid of widgets. The first row and col are 1,1.
+// - `row_span` and `col_span` represent the relative size of a widget on the grid.
+// A widget with a `col_span` of 4 will be displayed as wide as 4 widgets with a `col_span` of 1.
+// - `width` and `height` are size hints (in pixels) but may be discarded by the GUI module
+//
+// @usage
+// -- Creates a label at row 3, col 2, with a relative width of 4, height of 5.
+// w = d:add_label( "My Label", 2, 3, 4, 5 )
+// @section dialog_widgets
+
+/// Add a button to the dialog.
+//
+// Creates and adds a new button to the dialog
+// @function Dialog:add_button
+// @tparam string text Button label
+// @tparam func callback Function to call for button interaction
+// @tparam[opt] int col Column in the grid the Widget will be positioned at
+// @tparam[opt] int row Row in the grid the Widget will be positioned at
+// @tparam[opt] int col_span Relative grid column size
+// @tparam[opt] int row_span Relative grid row size
+// @tparam[opt] int width Width size hint (in pixels)
+// @tparam[opt] int height Height size hint (in pixels)
+// @treturn Widget The newly created button widget.
static int vlclua_dialog_add_button( lua_State *L );
+
+/// Add a label to the dialog.
+//
+// Creates and adds a new label to the dialog
+// @function Dialog:add_label
+// @tparam string text Label text
+// @tparam[opt] int col Column in the grid the Widget will be positioned at
+// @tparam[opt] int row Row in the grid the Widget will be positioned at
+// @tparam[opt] int col_span Relative grid column size
+// @tparam[opt] int row_span Relative grid row size
+// @tparam[opt] int width Width size hint (in pixels)
+// @tparam[opt] int height Height size hint (in pixels)
+// @treturn Widget The newly created label widget.
static int vlclua_dialog_add_label( lua_State *L );
+
static int vlclua_dialog_add_html( lua_State *L );
static int vlclua_dialog_add_text_inner( lua_State *L, int );
+
+/// Add an editable text field to the dialog.
+//
+// Creates and adds a new editable text field, in order to read user input.
+// @function Dialog:add_text_input
+// @tparam string text Default text of the text field
+// @tparam[opt] int col Column in the grid the Widget will be positioned at
+// @tparam[opt] int row Row in the grid the Widget will be positioned at
+// @tparam[opt] int col_span Relative grid column size
+// @tparam[opt] int row_span Relative grid row size
+// @tparam[opt] int width Width size hint (in pixels)
+// @tparam[opt] int height Height size hint (in pixels)
+// @treturn Widget The newly created text field widget.
static inline int vlclua_dialog_add_text_input( lua_State *L )
{
return vlclua_dialog_add_text_inner( L, EXTENSION_WIDGET_TEXT_FIELD );
}
+
+/// Add an editable masked text field to the dialog.
+//
+// Creates and adds a new masked editable text field, in order to read user input,
+// typically used for password fields.
+// The text entered in this field will not be readable (masked/replaced by asterisks
+// or similar).
+// @function Dialog:add_password
+// @tparam string text Default text of the password field
+// @tparam[opt] int col Column in the grid the Widget will be positioned at
+// @tparam[opt] int row Row in the grid the Widget will be positioned at
+// @tparam[opt] int col_span Relative grid column size
+// @tparam[opt] int row_span Relative grid row size
+// @tparam[opt] int width Width size hint (in pixels)
+// @tparam[opt] int height Height size hint (in pixels)
+// @treturn Widget The newly created password field widget.
static inline int vlclua_dialog_add_password( lua_State *L )
{
return vlclua_dialog_add_text_inner( L, EXTENSION_WIDGET_PASSWORD );
}
+
+/// Add a rich text HTML label to the dialog.
+//
+// Creates and adds a new rich-text label to the dialog
+// that supports basic HTML formatting (such as `<i>` or
+// `<h1>` for instance).
+// @function Dialog:add_html
+// @tparam string text HTML text
+// @tparam[opt] int col Column in the grid the Widget will be positioned at
+// @tparam[opt] int row Row in the grid the Widget will be positioned at
+// @tparam[opt] int col_span Relative grid column size
+// @tparam[opt] int row_span Relative grid row size
+// @tparam[opt] int width Width size hint (in pixels)
+// @tparam[opt] int height Height size hint (in pixels)
+// @treturn Widget The newly created HTML label widget.
static inline int vlclua_dialog_add_html( lua_State *L )
{
return vlclua_dialog_add_text_inner( L, EXTENSION_WIDGET_HTML );
}
+
+/// Add a check box to the dialog.
+//
+// Creates and adds a new check box control to the dialog
+// with the given text as label next to it.
+// The check box has a boolean state (`true`/`false`)
+// @function Dialog:add_check_box
+// @tparam string text Label for the check box
+// @tparam bool state Initial state (`true` for checked, else `false`)
+// @tparam[opt] int col Column in the grid the Widget will be positioned at
+// @tparam[opt] int row Row in the grid the Widget will be positioned at
+// @tparam[opt] int col_span Relative grid column size
+// @tparam[opt] int row_span Relative grid row size
+// @tparam[opt] int width Width size hint (in pixels)
+// @tparam[opt] int height Height size hint (in pixels)
+// @treturn Widget The newly created check box widget.
static int vlclua_dialog_add_check_box( lua_State *L );
+
+/// Add a list to the dialog.
+//
+// Creates and adds a new list control to the dialog
+//
+// The list widget allows none, one or multiple items to be selected.
+// @function Dialog:add_list
+// @tparam[opt] int col Column in the grid the Widget will be positioned at
+// @tparam[opt] int row Row in the grid the Widget will be positioned at
+// @tparam[opt] int col_span Relative grid column size
+// @tparam[opt] int row_span Relative grid row size
+// @tparam[opt] int width Width size hint (in pixels)
+// @tparam[opt] int height Height size hint (in pixels)
+// @treturn Widget The newly created list widget.
static int vlclua_dialog_add_list( lua_State *L );
+
+/// Add a drop down to the dialog.
+//
+// Creates and adds a new drop down control to the dialog
+//
+// The drop down allows only single item to be selected at the same time.
+// @function Dialog:add_dropdown
+// @tparam[opt] int col Column in the grid the Widget will be positioned at
+// @tparam[opt] int row Row in the grid the Widget will be positioned at
+// @tparam[opt] int col_span Relative grid column size
+// @tparam[opt] int row_span Relative grid row size
+// @tparam[opt] int width Width size hint (in pixels)
+// @tparam[opt] int height Height size hint (in pixels)
+// @treturn Widget The newly created drop down widget.
static int vlclua_dialog_add_dropdown( lua_State *L );
+
+/// Add an image to the dialog.
+//
+// Creates and adds a new image control to the dialog
+//
+// The image widget loads and displays an image form the supplied
+// path which can be either an absolute or relative path to a local file.
+// @function Dialog:add_image
+// @tparam string path Relative or absolute path to the image
+// @tparam[opt] int col Column in the grid the Widget will be positioned at
+// @tparam[opt] int row Row in the grid the Widget will be positioned at
+// @tparam[opt] int col_span Relative grid column size
+// @tparam[opt] int row_span Relative grid row size
+// @tparam[opt] int width Width size hint (in pixels)
+// @tparam[opt] int height Height size hint (in pixels)
+// @treturn Widget The newly created image widget.
static int vlclua_dialog_add_image( lua_State *L );
+
+/// Add a loading spinner to the dialog.
+//
+// Creates and adds a new loading spinner control to the dialog
+// @function Dialog:add_spin_icon
+// @tparam string iterations FIXME, this is currently broken
+// @tparam[opt] int col Column in the grid the Widget will be positioned at
+// @tparam[opt] int row Row in the grid the Widget will be positioned at
+// @tparam[opt] int col_span Relative grid column size
+// @tparam[opt] int row_span Relative grid row size
+// @tparam[opt] int width Width size hint (in pixels)
+// @tparam[opt] int height Height size hint (in pixels)
+// @treturn Widget The newly created loading spinner widget.
static int vlclua_dialog_add_spin_icon( lua_State *L );
+
static int vlclua_create_widget_inner( lua_State *L, int i_args,
extension_widget_t *p_widget);
+
+/// Remove a widget from the dialog.
+//
+// Removes the specified widget from the dialog
+//
+// The widget is removed from the dialog and the UI is updated accordingly,
+// which might imply repositioning of other widgets.
+// This function always updates the dialog.
+// @function Dialog:del_widget
+// @tparam Widget widget The widget to remove
+// @raise Error if called with something that isn't a Widget.
static int vlclua_dialog_delete_widget( lua_State *L );
-/* Widget methods */
+/// Widget methods
+//
+// A widget object represents a widget that is placed in
+// a Dialog.
+// @section widget_methods
+
+/// Set the widget text.
+//
+// Set the text content or label for this widget.
+//
+// Applies to: Button, Label, HTML, Text Input, Password, Checkbox
+// @function Widget:set_text
+// @tparam string text New widget text
+// @raise Error if called for an unsupported widget type.
static int vlclua_widget_set_text( lua_State *L );
+
+/// Get the widget text.
+//
+// Get the text content or label for this widget.
+//
+// Applies to: Button, Label, HTML, Text Input, Password, Checkbox
+// @function Widget:get_text
+// @raise Error if called for an unsupported widget type.
+// @treturn string The current label or content of widget.
static int vlclua_widget_get_text( lua_State *L );
+
+/// Set the checkbox widget checked state.
+//
+// Set if the widgets is currently displaying as checked.
+//
+// Applies to: Checkbox
+// @function Widget:set_checked
+// @tparam bool checked If the checkbox is checked (`true`) or not (`false`)
+// @raise Error if called for an unsupported widget type.
static int vlclua_widget_set_checked( lua_State *L );
+
+/// Get the checkbox widget checked state.
+//
+// Get if the widget is currently displaying as checked.
+//
+// Applies to: Checkbox
+// @function Widget:get_checked
+// @treturn bool If the checkbox is checked (`true`) or not (`false`)
+// @raise Error if called for an unsupported widget type.
static int vlclua_widget_get_checked( lua_State *L );
+
+/// Add an item to the widget
+//
+// Adds an item with the given `id` and user-facing `value` to the widget.
+//
+// Applies to: List, Drop-down
+// @function Widget:add_value
+// @tparam string value The user-facing text to be added
+// @tparam int id An unique identifier for this item
+// @raise Error if called for an unsupported widget type.
static int vlclua_widget_add_value( lua_State *L );
+
+/// Get the current item of the drop-down
+//
+// Gets the `id` and `value` of the item that is the currently
+// selected one for this drop-down.
+//
+// If no item is selected, the `-1` is returned for the `id`
+// and `nil` for the string.
+//
+// Applies to: Drop-down
+// @function Widget:get_value
+// @treturn[1] int The unique identifier of the current item
+// @treturn[1] string The user-facing value of the current item
+// @treturn[2] int `-1` if no item is selected
+// @return[2] `nil` if no item is selected
+// @raise Error if called for an unsupported widget type.
static int vlclua_widget_get_value( lua_State *L );
+
+/// Clear the items of the widget
+//
+// Clears all previously added items for this widget.
+//
+// Applies to: List, Drop-down
+// @function Widget:clear
+// @raise Error if called for an unsupported widget type.
static int vlclua_widget_clear( lua_State *L );
+
+/// Get the currently selected item(s) of the list
+//
+// Gets a table of the currently selected items in the list.
+// The keys of the table are the `id` of the item and the value
+// is the user-facing text.
+//
+// Applies to: List
+// @function Widget:get_selection
+// @treturn int The unique identifier of the current item
+// @raise Error if called for an unsupported widget type.
static int vlclua_widget_get_selection( lua_State *L );
+
+/// Start animating the current widget.
+//
+// Applies to: Loading spinner
+// @function Widget:animate
+// @raise Error if called for an unsupported widget type.
static int vlclua_widget_animate( lua_State *L );
+
+/// Stop animating the current widget.
+//
+// Applies to: Loading spinner
+// @function Widget:stop
+// @raise Error if called for an unsupported widget type.
static int vlclua_widget_stop( lua_State *L );
/* Helpers */
@@ -135,16 +447,16 @@ static const luaL_Reg vlclua_widget_reg[] = {
{ NULL, NULL }
};
-/** Private static variable used for the registry index */
+/* Private static variable used for the registry index */
static const char key_opaque = 'A',
key_update = 'B';
-/**
+/*
* Open dialog library for Lua
* @param L lua_State
* @param opaque Object associated to this lua state
* @note opaque will be p_ext for extensions, p_sd for service discoveries
- **/
+ */
void luaopen_dialog( lua_State *L, void *opaque )
{
lua_getglobal( L, "vlc" );
@@ -196,8 +508,8 @@ static int vlclua_dialog_create( lua_State *L )
vlc_mutex_init( &p_dlg->lock );
vlc_cond_init( &p_dlg->cond );
- /** @todo Use the registry instead of __dialog,
- so that the user can't tamper with it */
+ /* @todo Use the registry instead of __dialog,
+ so that the user can't tamper with it */
lua_getglobal( L, "vlc" );
lua_pushlightuserdata( L, p_dlg );
@@ -292,7 +604,6 @@ static int vlclua_dialog_delete( lua_State *L )
return 1;
}
-/** Show the dialog */
static int vlclua_dialog_show( lua_State *L )
{
extension_dialog_t **pp_dlg =
@@ -307,7 +618,6 @@ static int vlclua_dialog_show( lua_State *L )
return 1;
}
-/** Hide the dialog */
static int vlclua_dialog_hide( lua_State *L )
{
extension_dialog_t **pp_dlg =
@@ -322,8 +632,6 @@ static int vlclua_dialog_hide( lua_State *L )
return 1;
}
-
-/** Set the dialog's title */
static int vlclua_dialog_set_title( lua_State *L )
{
extension_dialog_t **pp_dlg =
@@ -345,7 +653,6 @@ static int vlclua_dialog_set_title( lua_State *L )
return 1;
}
-/** Update the dialog immediately */
static int vlclua_dialog_update( lua_State *L )
{
vlc_object_t *p_mgr = vlclua_get_this( L );
@@ -381,7 +688,7 @@ static int lua_GetDialogUpdate( lua_State *L )
return luaL_checkinteger( L, -1 );
}
-/** Manually update a dialog
+/* Manually update a dialog
* This can be called after a lua_pcall
* @return SUCCESS if there is no dialog or the update was successful
* @todo If there can be multiple dialogs, this function will have to
@@ -406,11 +713,11 @@ int lua_DialogFlush( lua_State *L )
return i_ret;
}
-/**
+/*
* Create a button: add_button
* Arguments: text, function (as string)
* Qt: QPushButton
- **/
+ */
static int vlclua_dialog_add_button( lua_State *L )
{
/* Verify arguments */
@@ -429,11 +736,11 @@ static int vlclua_dialog_add_button( lua_State *L )
return vlclua_create_widget_inner( L, 2, p_widget );
}
-/**
+/*
* Create a text label: add_label
* Arguments: text
* Qt: QLabel
- **/
+ */
static int vlclua_dialog_add_label( lua_State *L )
{
/* Verify arguments */
@@ -446,11 +753,11 @@ static int vlclua_dialog_add_label( lua_State *L )
return vlclua_create_widget_inner( L, 1, p_widget );
}
-/**
+/*
* Create a text area: add_html, add_text_input, add_password
* Arguments: text (may be nil)
* Qt: QLineEdit (Text/Password) or QTextArea (HTML)
- **/
+ */
static int vlclua_dialog_add_text_inner( lua_State *L, int i_type )
{
/* Verify arguments */
@@ -465,11 +772,11 @@ static int vlclua_dialog_add_text_inner( lua_State *L, int i_type )
return vlclua_create_widget_inner( L, 1, p_widget );
}
-/**
+/*
* Create a checkable box: add_check_box
* Arguments: text, checked (as bool)
* Qt: QCheckBox
- **/
+ */
static int vlclua_dialog_add_check_box( lua_State *L )
{
/* Verify arguments */
@@ -484,12 +791,12 @@ static int vlclua_dialog_add_check_box( lua_State *L )
return vlclua_create_widget_inner( L, 2, p_widget );
}
-/**
+/*
* Create a drop-down list (non editable)
* Arguments: (none)
* Qt: QComboBox
* @todo make it editable?
- **/
+ */
static int vlclua_dialog_add_dropdown( lua_State *L )
{
extension_widget_t *p_widget = calloc( 1, sizeof( extension_widget_t ) );
@@ -498,11 +805,11 @@ static int vlclua_dialog_add_dropdown( lua_State *L )
return vlclua_create_widget_inner( L, 0, p_widget );
}
-/**
+/*
* Create a list panel (multiple selection)
* Arguments: (none)
* Qt: QListWidget
- **/
+ */
static int vlclua_dialog_add_list( lua_State *L )
{
extension_widget_t *p_widget = calloc( 1, sizeof( extension_widget_t ) );
@@ -511,11 +818,11 @@ static int vlclua_dialog_add_list( lua_State *L )
return vlclua_create_widget_inner( L, 0, p_widget );
}
-/**
+/*
* Create an image label
* Arguments: (string) url
* Qt: QLabel with setPixmap( QPixmap& )
- **/
+ */
static int vlclua_dialog_add_image( lua_State *L )
{
/* Verify arguments */
@@ -529,11 +836,11 @@ static int vlclua_dialog_add_image( lua_State *L )
return vlclua_create_widget_inner( L, 1, p_widget );
}
-/**
+/*
* Create a spinning icon
* Arguments: (int) loop count to play: 0 means stopped, -1 means infinite.
* Qt: SpinningIcon (custom widget)
- **/
+ */
static int vlclua_dialog_add_spin_icon( lua_State *L )
{
/* Verify arguments */
@@ -546,12 +853,12 @@ static int vlclua_dialog_add_spin_icon( lua_State *L )
return vlclua_create_widget_inner( L, 0, p_widget );
}
-/**
+/*
* Internal helper to finalize the creation of a widget
* @param L Lua State
* @param i_args Number of arguments before "row" (0 or more)
* @param p_widget The widget to add
- **/
+ */
static int vlclua_create_widget_inner( lua_State *L, int i_args,
extension_widget_t *p_widget )
{
@@ -955,11 +1262,11 @@ static int vlclua_widget_stop( lua_State *L )
return 1;
}
-/**
+/*
* Delete a widget from a dialog
* Remove it from the list once it has been safely destroyed by the interface
* @note This will always update the dialog
- **/
+ */
static int vlclua_dialog_delete_widget( lua_State *L )
{
/* Get dialog */
@@ -1033,21 +1340,21 @@ static int vlclua_dialog_delete_widget( lua_State *L )
*/
-/**
+/*
* Add a widget to the widget list of a dialog
* @note Must be entered with lock on dialog
- **/
+ */
static void AddWidget( extension_dialog_t *p_dialog,
extension_widget_t *p_widget )
{
ARRAY_APPEND( p_dialog->widgets, p_widget );
}
-/**
+/*
* Remove a widget from the widget list of a dialog
* @note The widget MUST have been safely killed before
* @note Must be entered with lock on dialog
- **/
+ */
static int DeleteWidget( extension_dialog_t *p_dialog,
extension_widget_t *p_widget )
{
=====================================
modules/lua/libs/strings.c
=====================================
@@ -21,9 +21,12 @@
* Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston MA 02110-1301, USA.
*****************************************************************************/
-/*****************************************************************************
+/// String transformation functions
+// @module vlc.strings
+
+/*
* Preamble
- *****************************************************************************/
+ */
#ifndef _GNU_SOURCE
# define _GNU_SOURCE
#endif
@@ -40,9 +43,16 @@
#include "../vlc.h"
#include "../libs.h"
-/*****************************************************************************
+/*
* String transformations
- *****************************************************************************/
+ */
+
+/// Decode a list of URIs.
+//
+// This function returns as many variables as it had arguments.
+// @function decode_uri
+// @tparam string uri The URI to decode
+// @treturn string Decoded URI
static int vlclua_decode_uri( lua_State *L )
{
int i_top = lua_gettop( L );
@@ -60,6 +70,12 @@ static int vlclua_decode_uri( lua_State *L )
return i_top;
}
+/// Encode a list of URI components.
+//
+// This function returns as many variables as it had arguments.
+// @function encode_uri_component
+// @tparam string uri_comp An URI component to encode
+// @treturn string Encoded URI
static int vlclua_encode_uri_component( lua_State *L )
{
int i_top = lua_gettop( L );
@@ -75,6 +91,11 @@ static int vlclua_encode_uri_component( lua_State *L )
return i_top;
}
+/// Convert a file path to a URI.
+// @function make_uri
+// @tparam string path The file path to convert
+// @tparam[opt] string scheme Scheme to use for the URI (default auto: `file`, `fd` or `smb`)
+// @treturn string The URI for the given path
static int vlclua_make_uri( lua_State *L )
{
const char *psz_input = luaL_checkstring( L, 1 );
@@ -90,6 +111,10 @@ static int vlclua_make_uri( lua_State *L )
return 1;
}
+/// Convert a URI to a local path.
+// @function make_path
+// @tparam string uri The URI to convert
+// @treturn string The file path for the given URI
static int vlclua_make_path( lua_State *L )
{
const char *psz_input = luaL_checkstring( L, 1 );
@@ -99,6 +124,22 @@ static int vlclua_make_path( lua_State *L )
return 1;
}
+/// URL components.
+//
+// A table returned by the @{url_parse} function.
+// @field[type=string] protocol
+// @field[type=string] username
+// @field[type=string] password
+// @field[type=string] host
+// @field[type=int] port
+// @field[type=string] path
+// @field[type=string] option
+// @table url_components
+
+/// Parse a URL.
+// @function url_parse
+// @tparam string url The URL to parse
+// @return @{url_components}
int vlclua_url_parse( lua_State *L )
{
const char *psz_url = luaL_checkstring( L, 1 );
@@ -127,6 +168,13 @@ int vlclua_url_parse( lua_State *L )
return 1;
}
+/// Resolve XML special characters.
+//
+// Decode the XML special characters in a list of strings.
+// This function returns as many variables as it had arguments.
+// @function resolve_xml_special_chars
+// @tparam string input Input string
+// @treturn string String with the XML special characters decoded
static int vlclua_resolve_xml_special_chars( lua_State *L )
{
int i_top = lua_gettop( L );
@@ -145,6 +193,13 @@ static int vlclua_resolve_xml_special_chars( lua_State *L )
return i_top;
}
+/// Encode XML special characters.
+//
+// Encode the XML special characters in a list of strings.
+// This function returns as many variables as it had arguments.
+// @function convert_xml_special_chars
+// @tparam string input Input string
+// @treturn string String with the XML special characters encoded
static int vlclua_convert_xml_special_chars( lua_State *L )
{
int i_top = lua_gettop( L );
@@ -159,6 +214,14 @@ static int vlclua_convert_xml_special_chars( lua_State *L )
return i_top;
}
+/// Convert string from given charset to UTF-8.
+//
+// Convert a string from the specified input character encoding into UTF-8.
+// @function from_charset
+// @tparam string charset The charset of the input string
+// @tparam string input Input string
+// @treturn[1] string String converted to UTF-8
+// @treturn[2] string Empty string on error
static int vlclua_from_charset( lua_State *L )
{
if( lua_gettop( L ) < 2 ) return vlclua_error( L );
=====================================
share/lua/extensions/Extensions.md
=====================================
@@ -0,0 +1,6 @@
+## VLC Lua Extensions
+
+VLC can be extended with so called "extensions" written in Lua.
+
+These extensions can provide custom user interfaces, one prominent example is
+the VLSub subtitle downloader extension.
View it on GitLab: https://code.videolan.org/videolan/vlc/-/commit/8dcde174c141d65528a73f5738af0a0e8087a090
--
View it on GitLab: https://code.videolan.org/videolan/vlc/-/commit/8dcde174c141d65528a73f5738af0a0e8087a090
You're receiving this email because of your account on code.videolan.org.
More information about the vlc-commits
mailing list