From 9627544714b94c703c4f5ac0fdb3d78404f90bfe Mon Sep 17 00:00:00 2001
From: Guenter Bartsch <guenter@users.sourceforge.net>
Date: Thu, 7 Feb 2002 22:47:22 +0000
Subject: paragraphs on object orientation in xine and readme instructions on
 how to use sgmltools-lite

CVS patchset: 1482
CVS date: 2002/02/07 22:47:22
---
 doc/hackersguide/README            | 13 +++++-
 doc/hackersguide/hackersguide.sgml | 87 ++++++++++++++++++++++++++++++++++++--
 2 files changed, 95 insertions(+), 5 deletions(-)

diff --git a/doc/hackersguide/README b/doc/hackersguide/README
index 6e99bc535..a9fb6d443 100644
--- a/doc/hackersguide/README
+++ b/doc/hackersguide/README
@@ -24,6 +24,17 @@ If you want to generate TeX output (needed for postscript or pdf
 generation) you will also need jadetex (backend for TeX) and an
 installed TeX system (for example teTeX).
 
+sgmltools-lite examples:
+------------------------
+
+to generate html 
+
+$ sgmltools -b onehtml hackersguide.sgml
+
+to generate pdf
+
+$ sgmltools -b pdf hackersguide.sgml
+
 --- 
 version of this file:
- $Id: README,v 1.1 2001/10/09 18:20:23 heikos Exp $
+ $Id: README,v 1.2 2002/02/07 22:47:22 guenter Exp $
diff --git a/doc/hackersguide/hackersguide.sgml b/doc/hackersguide/hackersguide.sgml
index b600b7c65..a506a7676 100644
--- a/doc/hackersguide/hackersguide.sgml
+++ b/doc/hackersguide/hackersguide.sgml
@@ -186,6 +186,86 @@
     data is no longer needed and thus released to the global buffer pool.
     </para>
   </sect1>
+  <sect1>
+    <title>Object oriented programming in c</title>
+    <para>
+    xine uses a lot of design principles normally found in 
+    object oriented designs. As xine is written in c, a few
+    basic principles shall be explained here on how xine
+    is object oriented anyway.
+    </para>
+    <para>
+    classes are structs containing (ideally only) object pointers in xine.
+    Example:
+    <programlisting>
+    typedef struct my_stack_s my_class_t;
+
+    struct my_stack_s {
+      /* method "push" with one parameter and no return value*/
+      void (*push) (my_stack_t *this, int i);
+
+      /* method "add" with no parameters and no return value */
+      void (*add) (my_stack_t *this);
+
+      /* method "pop" with no parameters (except "this") and a return value */
+      int (*pop) (my_stack_t *this);
+    } ;
+
+    /* constructor */
+    my_class_t *new_my_stack (...);
+    </programlisting>
+
+    to implement such a "class", frequently "private" member variables
+    can be added:
+
+    <programlisting>
+    typedef struct {
+       my_stack_t    stack; /* public part */
+
+       /* private part follows here */
+       int           values[MAX_STACK_SIZE]; 
+       int           stack_size;
+    } intstack_t;
+    </programlisting>
+
+    each method is implemented as a static method (static to prevent
+    namespace pollution). The "this" pointer needs to be cast to the
+    private pointer type to gain access to the private member variables.
+
+    Implementation of the "push" method follows:
+    <programlisting>
+    static void push (my_stack_t *this_gen, int i) {
+       intstack_t *this = (intstack_t *) this_gen;
+    }
+    </programlisting>
+
+    Finally the contructor mallocs() the data structs (private variant)
+    and fills in function pointers and default values. Usually the
+    constructor is the only public (i.e. non-static) function in the module:
+
+    <programlisting>
+    my_stack_t *new_my_stack (...) {
+      intstack_t *this;
+
+      /* alloc memory */
+      this = malloc (sizeof (intstack_t));
+      
+      /* fill in methods */
+      this->push = push;
+      this->add  = add;
+      this->pop  = pop;
+
+      /* init data fields */
+      this->stack_size = 0;
+
+      /* cast & return */
+
+      return (my_stack_t *) this;
+    }
+    </programlisting>
+
+    </para>   
+  </sect1>
   <sect1>
     <title>Library interfaces</title>
     <para></para>
@@ -244,9 +324,6 @@
     xine-engine/video_out.h,...).
     </para>
     <para>
-    The public
-    </para>
-    <para>
     Most plugins will need some additional "private" data fields.
     These should be simply added at the end of the plugin struct,
     e.g. a demuxer plugin called "foo" with two private 
@@ -419,7 +496,9 @@ struct demux_plugin_s
     </listitem>
     <listitem> 
       <para>
-      use expressive variable and function names on all public interfaces.
+      use expressive variable and function identifiers on all public interfaces.
+      use underscores to seperate words in identifiers, not uppercase
+      letters (my_function_name is ok, myFunctionName is not ok).
       </para>
     </listitem>
     <listitem> 
-- 
cgit v1.2.3