Docs updates

Original commit message from CVS:
* docs/design/part-TODO.txt:
* docs/design/part-events.txt:
* docs/design/part-gstbin.txt:
* docs/design/part-gstbus.txt:
* docs/design/part-gstpipeline.txt:
* docs/design/part-messages.txt:
* gst/gstbus.c:
* gst/gstmessage.c:
Docs updates

1 files changed, 53 insertions, 0 deletions

diff --git a/docs/design/part-gstbin.txt b/docs/design/part-gstbin.txt
new file mode 100644
index 0000000000..c6a0721567
--- /dev/null
+++ b/docs/design/part-gstbin.txt
@@ -0,0 +1,53 @@
+GstBin
+------
+
+GstBin is a container element for other GstElements. This makes it possible
+to group elements together so that they can be treated as one single 
+GstElement.
+
+
+Add/removing elements
+---------------------
+
+The basic functionality of a bin is to add and remove GstElements to/from it.
+gst_bin_add() and gst_bin_remove() perform these operations respectively.
+
+The bin maintains a parent-child relationship with its elements (see part-
+relations.txt).
+
+
+Retrieving elements
+-------------------
+
+GstBin provides a number of functions to retrieve one or more children from
+itself. A few examples of the provided functions:
+
+gst_bin_get_by_name() retrieves an element by name.
+
+gst_bin_iterate_elements() returns an iterator to all the children.
+
+
+element management
+------------------
+
+The most important function of the GstBin is to distribute all GstElement
+operations on itself to all of its children. This includes:
+
+ - state changes
+ - index get/set
+ - clock gst/set
+ - bus set/get
+ - scheduler set/get
+
+The state change distribution is the most complex and is explained in 
+part-states.txt.
+
+
+Subclassing
+-----------
+
+Subclasses of GstBin are free to implement their own add/remove implementations.
+It is a good idea to update the GList of children so that the _iterate() functions
+can still be used.
+
+