[gnue] r8910 - trunk/gnue-forms/src/GFObjects

[reinhard]

Author: reinhard
Date: 2006-10-23 10:06:44 -0500 (Mon, 23 Oct 2006)
New Revision: 8910

Modified:
   trunk/gnue-forms/src/GFObjects/GFBlock.py
Log:
Added a big docstring for the block.


Modified: trunk/gnue-forms/src/GFObjects/GFBlock.py
===================================================================
--- trunk/gnue-forms/src/GFObjects/GFBlock.py   2006-10-23 14:44:55 UTC (rev 
8909)
+++ trunk/gnue-forms/src/GFObjects/GFBlock.py   2006-10-23 15:06:44 UTC (rev 
8910)
@@ -33,7 +33,7 @@
 from gnue.forms.GFObjects.GFContainer import GFContainer
 from gnue.forms.GFObjects.GFDataSource import GFDataSource
 
-__all__ = ['GFBlock', 'DatasourceNotFoundError', 'InvalidEditableError']
+__all__ = ['GFBlock', 'DatasourceNotFoundError']
 
 
 # =============================================================================
@@ -41,6 +41,9 @@
 # =============================================================================
 
 class DatasourceNotFoundError(GParser.MarkupError):
+    """
+    This block references a non-existant datasource.
+    """
     def __init__(self, source, block):
         msg = u_(
                 "Datasource '%(datasource)s' in block '%(block)s' not found") \
@@ -49,23 +52,51 @@
 
 
 # =============================================================================
-
-class InvalidEditableError(errors.ApplicationError):
-    def __init__(self, value):
-        msg = u_(
-                "'%(value)s' is not a valid option for editable. " \
-                "Please use one of 'Y', 'N', 'new', 'update'") \
-                % {'value': value}
-        errors.ApplicationError.__init__(self, msg)
-
-
-# =============================================================================
 # <block>
 # =============================================================================
 
 class GFBlock(GFContainer, events.EventAware):
     """
-    Class that represents the <block> tag in a gfd file.
+    A block in a form definition.
+
+    A block covers all aspects of a form's connection to a data source.
+
+    Blocks can be filled with data by using the L{init_query}, L{copy_query},
+    and L{execute_query} methods. Within the result set, blocks maintain a
+    pointer to a current record which can be moved around with the
+    L{first_record}, L{prev_record}, L{next_record}, L{last_record},
+    L{goto_record}, and L{jump_records} methods.
+
+    Read and write access to the data of the current record (and the
+    surrounding records) is possible with the L{get_value} and L{set_value}
+    methods. New records can be inserted with the L{new_record} and
+    L{duplicate_record} methods. Records can be marked for deletion at next
+    commit with the L{delete_record} method and this mark can be undone with
+    L{undelete_record}.
+
+    The L{post} and L{requery} methods are available to write the block's
+    changes back to the datasource, while the L{clear} method discards all
+    changes and replaces the block's contents with a single empty record.
+
+    In case the block is connected to an active datasource (especially the GNUe
+    AppServer), the L{updateCurrentRecordSet} method can be used to write the
+    block's changes to the backend without committing them, in order to run
+    trigger functions on the backend, while L{callFunction} directly calls a
+    backend function for the block's current record.
+
+    The status of the current record can be determined by L{get_record_status},
+    while L{is_pending} can be used to determine the status of the whole block.
+    The method L{get_possible_operations} lists all operations that are
+    possible for the block in its current status.
+
+    The block keeps track of all user interface elements that are connected to
+    it and keeps the user interface up to date on all its operations. It should
+    always be kept in mind that this might result in bad performance for mass
+    operations on the data, so the method L{get_data} is available to access
+    the raw data behind the block for high speed operations.
+
+    Whenever the user interface focus enters or leaves the block, it must be
+    notified via the L{focus_in}, L{validate}, and L{focus_out} methods.
     """
 
     # -------------------------------------------------------------------------
@@ -73,6 +104,9 @@
     # -------------------------------------------------------------------------
 
     def __init__(self, parent=None):
+        """
+        Create a new block instance.
+        """
 
         GFContainer.__init__(self, parent, 'GFBlock')