Commit 0a743910 authored by Rocky Bernstein's avatar Rocky Bernstein

Update How to write an interface plugin from recent vlc-devel responses.

parent 042f3711
......@@ -220,48 +220,110 @@ messages (if the message queue is in use).
<sect1> <title> How to write an interface plugin </title>
<sect2> <title> API for the Module </title>
<para>
Have a look at <filename>plugins/dummy/intf_dummy.c</filename> and
<filename>plugins/gtk/intf_gtk.c</filename>. Basically, you have to
write 5 functions :
Have a look the files in directories
<filename>modules/misc/control</filename>,
<filename> modules/misc/dummy</filename>,
<filename> modules/misc/access</filename>,
or <filename> modules/gui</filename>. However the GUI interfaces are
not very easy to understand, since they are quite big. I suggest to
start digging into a non-graphical interface modules first. For example
<filename>modules/control/hotkeys.c</filename>.</para>
<para>An interface module is made of 3 entry functions and a module
description:
</para>
<itemizedlist>
<listitem> <para> <function> intf_Probe </function> ( <parameter>
probedata_t * p_data </parameter> ) :
This is supposed to tell whether your plugin can work in this
environment or not. If it can, it returns a score between 1
and 999 indicating whether this plugin should be preferred
against others or not. <parameter> p_data </parameter> is
currently unused. </para> </listitem>
<listitem> <para> <function> intf_Open </function> ( <parameter>
intf_thread_t * p_intf </parameter> ) :
Initializes the interface (ie. opens a new window, etc.).
You can store your information in p_intf-&gt;p_sys.
</para> </listitem>
<listitem> <para> <function> intf_Close </function> ( <parameter>
intf_thread_t * p_intf </parameter> ) :
Closes the interface and frees all allocated structures
(including p_intf-&gt;p_sys).
</para> </listitem>
<listitem> <para> <function> intf_Run </function> ( <parameter>
intf_thread_t * p_intf </parameter> ) :
Launches the main loop, which shouldn't return
until p_intf-&gt;b_die is set to 1. Pay attention not to take all
CPU time with an infinite loop (add <function> msleep</function>).
</para> </listitem>
</itemizedlist>
<listitem> <para> The module description is made of macros that
declares the capabilities of the module (interface, in this case)
with their priority, the module description as it will appear in
the preferences of GUI modules that implement them, some
configuration variables specific to the module, shortcuts,
sub-modules, etc. </para></listitem>
<listitem> <para> <function> Open </function> ( <parameter>
vlc_object_t* p_object </parameter> ): This is called by
VLC to initialize the module. </para></listitem>
<listitem> <para> <function> Run </function> ( <parameter>
vlc_object_t* p_object </parameter> ): really does the job
of the interface module (waiting for user input and
displaying info). It should check periodically that
<constant>p_intf->b_die</constant> is
not <constant>VLC_TRUE</constant>.
</para></listitem>
<listitem> <para> <function> Close ( <parameter> vcl_object_t *
p_object </parameter> ) </function> function is called by VLC to
uninitialize the module (basically, this consists in destroying
whatever have been allocated
by <function>Open</function>) </para></listitem>
</itemizedlist>
<para>The above functions take a <parameter>vlc_object_t*</parameter>
as argument, but that may need to be cast into
a <parameter>intf_thread_t*</parameter> depending on your needs. This
structure is often needed as a parameter for exported VLC functions,
such as <function>msg_Err()</function>, <function>msg_Warn()</function>,
...</para>
<para>
Define <parameter>intf_sys_t</parameter> to contain any variable you
need (don't use static variables, they suck in a multi-threaded
application :-).</para>
<para>If additional capabilities (such as Open button,
playlist, menus, etc.) are needed, consult one of the GUI modules.
One of the simpler GUI modules to consult might be
<filename>modules/gui/ncurses/ncurses.c</filename>. It is a quite
simple complete interface module with playlist interaction, and
progress bar, among other things.
<para>
Don't forget to define intf_sys_t to contain any variable you need
(don't use static variables, they suck in a multi-threaded
application :-). If additionnal
capabilities (such as Open button, playlist, menus, etc.) are needed,
look at the GTK+ plug-in in <filename> plugins/gtk</filename>.
</para>
</sect2>
<sect2><title>Arranging for your Module to get Compiled</title>
<para>If you create a new directory for your module, add
a <filename>Modules.am</filename> file in it. In this file, put
something like : <constant>SOURCES_yourmodule = myfile1.c
myfile2.c</constant></para>
<para>Then, go to the main <filename>configure.ac</filename> file, and
at the end, in the <constant>AC_CONFIG_FILES</constant> section, add a
line similar to the others.</para>
<para>If you don't create a directory for your plugin (just put it in
an existing one), you only have to add the two SOURCES_... lines to
the existing <filename>Modules.am</filename> file</para>
<para>By doing this, your module is declared, but it will never automatically
compile.</para>
<para>You then have to restart from the beginning the build sequence, so:</para>
<!---don't know if <xmp> or <example> works. Until then... -->
<para><filename>./bootstrap</filename></para>
<para><filename>./configure...</filename></para>
<para><filename>make</filename></para>
<para>To build the module, you have to do it manually, by going to its
directory, and typing
<constant>make libyourmodule_plugin.so</constant> (or .dll, ora
whatever the file type for a shared library is on your Operating
System.)</para>
<para>To automatize the build of your module, you must ask this in the
configure.ac file.</para>
<para>If you want it to be always built, add it to
the <constant>default modules</constant> section
in <filename>configure.ac</filename>, in one
<constant>AX_ADD_PLUGINS</constant> directive.</para>
</sect2>
</sect1>
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment