<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->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->p_sys).
- </para> </listitem>
+ <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.
- <listitem> <para> <function> intf_Run </function> ( <parameter>
- intf_thread_t * p_intf </parameter> ) :
- Launches the main loop, which shouldn't return
- until p_intf->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>
-
- <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
+add in the <constant>AC_CONFIG_FILES</constant> section (towards the
+end of the file) a line similar to the others.</para>
+
+<para>If you don't create a directory for your plugin (but instead
+just put it in an existing directory), you only have to add the two
+SOURCES_... lines to the existing <filename>Modules.am</filename>
+file</para>
+
+<para>This declares your module; it does not arrange for it to be
+automatically compiled; automatic compilatoin is described further
+below.</para>
+
+<para>You do not write a <filename>Makefile</filename> for your
+module. Instead this is done via the bootstrap and configuration
+process. So now run:
+</para>
+
+<!---don't know if <xmp> or <example> works. Until then... -->
+<para><filename>./bootstrap</filename></para>
+<para><filename>./configure</filename> <emphasis>configure-options</emphasis></para>
+<para><filename>make</filename></para>
+
+<para>To build the module manually, go to the
+directory it resides and type
+<constant>make libyourmodule_plugin.so</constant> (or .dll, or
+ whatever the file type for a shared library is on your Operating
+ System.)</para>
+
+<para>To <emphasis>automatically</emphasis> have your module get
+built, you also set this in the <filename>configure.ac</filename>
+file; add your module name to the <constant>default modules</constant>
+section in one of the
+<constant>AX_ADD_PLUGINS</constant> directives.</para>
+</sect2>
</sect1>
projects / vlc / blobdiff