gnue.forms Public API - GNU Enterprise

Package gnue :: Package forms :: Package GFObjects :: Module GFBlock :: Class GFBlock

[show private | hide private]

Type GFBlock

               object --+    
                        |    
               EventAware --+
                            |
 GTriggerCore --+           |
                |           |
   object --+   |           |
            |   |           |
    ParserObj --+           |
                |           |
             GObj --+       |
                    |       |
GTriggerExtension --+       |
                    |       |
                GFObj --+   |
                        |   |
              GFContainer --+
                            |
                           GFBlock

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 init_filter, change_filter, and apply_filter methods or in a single step with the set_filter method. The clear method populates the block with a single empty record.

Within the result set, blocks maintain a pointer to a current record which can be moved around with the first_record, prev_record, next_record, last_record, goto_record, jump_records, and search_record methods.

Read and write access to the data of the current record (and the surrounding records) is possible with the get_value and set_value methods. New records can be inserted with the new_record and duplicate_record methods. Records can be marked for deletion at next commit with the delete_record method and this mark can be undone with undelete_record.

The post and requery methods are available to write the block's changes back to the datasource.

In case the block is connected to an active datasource (especially the GNUe AppServer), the update 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 call directly calls a backend function for the block's current record.

The status of the current record can be determined by get_record_status, while is_pending can be used to determine the status of the whole block. The method 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 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 focus_in, validate, and focus_out methods.

Method Summary
	`__init__(self, parent)` Create a new block instance.
	`_phase_1_init_(self)` Phase 1 initialization called after all objects of the XML tree were created.
	`apply_filter(self)` Apply the filter defined through the field values.
	`call(self, name, parameters)` Call a server side function.
	`change_filter(self)` Set the block into filter mode and initialize the filter criteria with the last executed filter.
	`clear(self)` Discard changes in this block and populate it with a single empty record.
	`delete_record(self)` Mark the current record for deletion.
	`discard_filter(self)` Reset the block from filter mode back to data browsing mode without applying the new filter.
	`duplicate_record(self, exclude, include)` Create a new record and initialize it with field values from the current record.
	`first_record(self)` Move the record pointer to the first record of the block.
	`focus_in(self)` Notify the block that it has received the focus.
	`focus_out(self)` Notify the block that it is going to lose the focus.
	`get_data(self, fieldnames)` Build a list of dictionaries of the current resultset using the fields defined by fieldnames.
	`get_focus_order(self)`
	`get_possible_operations(self)` Return a list of possible operations for this block.
	`get_record_count(self)` Return the number of records in this block.
	`get_record_status(self, offset)` Find out about the status of the record.
	`get_resultset(self)` Return the current ResultSet of the block.
	`get_value(self, field, offset)` Return the value of the given field, depending on the block's state.
	`goto_record(self, record_number)` Move the record pointer to a specific record number in the block.
	`init_filter(self)` Set the block into filter mode.
	`is_empty(self)` Return True if the current record is empty.
	`is_first_record(self)` Return True if the current record is the first one in the result set.
	`is_last_record(self)` Return True if the current record is the last one in the result set.
	`is_pending(self)` Return True if the block is pending any uncommited changes.
	`is_saved(self)` Return True if the block is not pending any uncommited changes.
	`jump_records(self, count)` Move the record pointer by a given adjustment relative to the current record.
	`last_record(self)` Move the record pointer to the last record of the block.
	`new_record(self)` Add a new record to the block.
	`next_record(self)` Move the record pointer to the next record in the block.
	`populate(self)` Populate the block with data at startup.
	`post(self)` Post all pending changes of the block and all its detail blocks to the database backend.
	`prev_record(self)` Move the record pointer to the previous record in the block.
	`register_scrollbar(self, widget)` Register a given scrollbar widget to the block.
	`requery(self, commit)` Finalize storing the values of the block in the database.
	`search_record(self, **params)` Search for (and jump to) the first record matching a set of field values.
	`set_filter(self, args, *params)` Set new filter criteria for this block.
	`set_value(self, field, value)` Set the value of the given field, depending on the block's state.
	`undelete_record(self)` Remove the deletion mark from the current record.
	`update(self)` Update the backend with changes to this block without finally commmitting them.
	`validate(self)` Validate the block to decide whether the focus can be moved away from it.
Inherited from GFObj
	`_is_navigable_(self, mode)` Return wether the object is currently navigable or not.
	`get_block(self)` Return the objects' block from the block mapping.
	`get_field(self)` Returns the objects' field from the blocks' field mapping
	`get_option(self, name)` Return the value of a given option of the object or None if no such option is present.
	`is_navigable(self, mode)` Return wether the object is currently navigable or not.
	`phase_1_init(self)` Phase 1 initialization called after all objects of the XML tree were created.
Inherited from GObj
	`__getitem__(self, key)`
	`__setitem__(self, key, value)`
	`_dumpXML_(self, lookupDict, treeDump, gap, xmlnamespaces, textEncoding, stripPrefixes, escape)` Dumps an XML representation of the object
	`buildAndInitObject(self, **params)` This is a convenience function for applications NOT using GParser to load an object tree.
	`buildObject(self, **params)` A convenience function for applications NOT using GParser to load an object tree.
string	`getXmlTag(self, stripPrefixes)` Returns the xml tag to be used to represent the object.
	`iterator(self, test, types, includeSelf)` Return a python iterator of child objects.
	`maxInits(self)` maxInits returns the maximum size of all the _inits list from this object or it's children
	`phaseInit(self, iterations)` Starts GNUe's phased initialization system from this object down.
	`showTree(self, indent)` A recusive function to print an indented text representation of the GObj tree from this object down.
	`walk(self, function, args, *parms)` Function that recursively walks down through a tree of `ParserObj` instances and applies a function to them.
Inherited from GTriggerCore
	`__repr__(self)`
	`create_namespace_object(self, global_namespace, namespace_name)` Construct a namespace object tree from an XML (`definitions.GObjects.GObj`) object tree.
	`get_namespace_object(self)` Return the namespace object that mirrors this object in the action/trigger namespace.
Inherited from ParserObj
	`_diffActionWalker_(self, obj, action)` Set the action attribute of a given object to the specified action.
	`_getAsContents_(self)` Get the contents of this object.
	`_id_(self, maxIdLength)` Return a compareable and identifying id of an object within a tree.
	`_set_initial_attributes_(self, attributes)` Set attributes loaded by GParser.
	`addChild(self, child)` Add an object to the list of children
	`assign(self, source, recursive)` Assign all attributes from a given object to this one.
	`diff(self, goal, maxIdLength)` Build an object tree representing the difference between two object trees.
	`dumpXML(self, lookupDict, treeDump, gap, xmlnamespaces, textEncoding, stripPrefixes, escape)` Return a XML representation of the object.
	`findChildNamed(self, name, childType)` Moves downward though the children of an object till it finds the child with the specified name.
	`findChildOfType(self, childType, includeSelf, allowAllChildren)` Moves downward through the children of an object till it finds the child of the specified type.
	`findChildrenOfType(self, childType, includeSelf, allowAllChildren)` Find all children of a specific type.
	`findParentOfType(self, parentType, includeSelf)` Moves upward though the parents of an object till it finds the parent of the specified type.
	`getChildrenAsContent(self)` Returns the content of any GContent objects that are children of this object.
	`getDescription(self)` Return a useful description of the object.
any	`getParent(self)` Returns the immediate parent of an object instance in a GObj tree.
	`merge(self, other, maxIdLength, overwrite)` Merge another object tree into this tree.
	`setParent(self, newParent)` Set the immediate parent of an object instance in a GObj tree
Inherited from object
	`__delattr__(...)` x.__delattr__('name') <==> del x.name
	`__getattribute__(...)` x.__getattribute__('name') <==> x.name
	`__hash__(x)` Return hash(x)...
	`__new__(T, S, ...)` Return a new object with type S, a subtype of T...
	`__reduce__(...)` helper for pickle
	`__reduce_ex__(...)` helper for pickle
	`__setattr__(...)` x.__setattr__('name', value) <==> x.name = value
	`__str__(x)` Return str(x)...
Inherited from GTriggerExtension
	`associateTrigger(self, key, function)` Associate a trigger with this object.
	`processTrigger(self, key, ignoreAbort)` Fire the requested trigger if a trigger of that type has been associated with this object.

Property Summary
Inherited from GFObj
	`has_label`

Method Details

init(self, parent)
(Constructor)

Create a new block instance.

Parameters:: parent - Parent object.

Overrides:: gnue.forms.GFObjects.GFObj.GFObj.__init__

_phase_1_init_(self)

Phase 1 initialization called after all objects of the XML tree were created. Descendants can overwrite this function to perform actions after construction of the objects.

Overrides:: gnue.forms.GFObjects.GFObj.GFObj._phase_1_init_ (inherited documentation)

apply_filter(self)

Apply the filter defined through the field values.

The block switches back from filter mode to data browsing mode and is populated with all records that match the filter criteria.

call(self, name, parameters)

Call a server side function.

Currently, the only backend to support server side function calls is gnue-appserver.

Parameters:: name - Function name.; parameters - Function parameter dictionary.

change_filter(self)

Set the block into filter mode and initialize the filter criteria with the last executed filter.

From this point on, changes to fields within this block will be understood as filter criteria. Use apply_filter to apply the filter and populate the block with all records matching the criteria.

clear(self)

Discard changes in this block and populate it with a single empty record.

delete_record(self)

Mark the current record for deletion. The acutal deletion will be done on the next commit, call or update.

discard_filter(self)

Reset the block from filter mode back to data browsing mode without applying the new filter.

The result set that was active before switching to filter mode remains active.

duplicate_record(self, exclude=(), include=())

Create a new record and initialize it with field values from the current record.

Parameters:: exclude - list of fields not to copy.; include - list of fields to copy. An empty list means to copy all fields except primary key fields and rowid fields, which are never copied anyway.

first_record(self)

Move the record pointer to the first record of the block.

focus_in(self)

Notify the block that it has received the focus.

focus_out(self)

Notify the block that it is going to lose the focus.

The focus change is already decided at this moment, there is no way to stop the focus from changing now.

get_data(self, fieldnames=None)

Build a list of dictionaries of the current resultset using the fields defined by fieldnames.

Parameters:: fieldnames - list of fieldnames to export per record

Returns:: list of dictionaries (one per record)

get_focus_order(self)

Overrides:: gnue.forms.GFObjects.GFContainer.GFContainer.get_focus_order

get_possible_operations(self)

Return a list of possible operations for this block.

The form can use this function to enable or disable commanders (menu items or toolbar buttons) that are bound to the respective action.

The return value is basically a list of method names that can be called for this block in the current state.

get_record_count(self)

Return the number of records in this block.

get_record_status(self, offset=0)

Find out about the status of the record.

The status can be one of 'empty', 'inserted', 'void', 'clean', 'modified', or 'deleted', or None if there is no current record.

get_resultset(self)

Return the current ResultSet of the block.

get_value(self, field, offset)

Return the value of the given field, depending on the block's state.

Parameters:: field - the GFField object.; offset - the offset from the current record (to get data for records other than the current one).

goto_record(self, record_number)

Move the record pointer to a specific record number in the block.

Parameters:: record_number - Record number to jump to. If this is a negative value, move relative to the last record.

init_filter(self)

Set the block into filter mode.

From this point on, changes to fields within this block will be understood as filter criteria. Use apply_filter to apply the filter and populate the block with all records matching the criteria.

is_empty(self)

Return True if the current record is empty.

Empty means that it has been newly inserted, but neither has any field been changed nor has a detail for this record been inserted with a status other than empty.

is_first_record(self)

Return True if the current record is the first one in the result set.

is_last_record(self)

Return True if the current record is the last one in the result set.

is_pending(self)

Return True if the block is pending any uncommited changes.

is_saved(self)

Return True if the block is not pending any uncommited changes.

This method is depreciated. Please use block.is_pending() instead !

jump_records(self, count)

Move the record pointer by a given adjustment relative to the current record.

Parameters:: count - the number of records to move from the current record.

last_record(self)

Move the record pointer to the last record of the block.

new_record(self)

Add a new record to the block.

next_record(self)

Move the record pointer to the next record in the block.

If the record is already the last one, a new record will be created if the "autoCreate" attribute of the block is set.

Returns:: True if the record pointer was moved, False if it was already the last record and no new record was inserted.

populate(self)

Populate the block with data at startup.

Depending on the properties of the block, it is populated either with a single empty record or the result of a full query.

post(self)

Post all pending changes of the block and all its detail blocks to the database backend.

If this function has been run successfully, requery must be called.

prev_record(self)

Move the record pointer to the previous record in the block.

Returns:: True if the record pointer was moved, False if it was already the first record.

register_scrollbar(self, widget)

Register a given scrollbar widget to the block. This widget will be notified on record movement. It has to implement a method 'adjust_scrollbar', taking the current record and the number of records as arguments.

requery(self, commit)

Finalize storing the values of the block in the database.

This method must be called after post has run successfully. It restores the block into a consistent state.

Parameters:: commit - True if a commit has been run on the backend connection between post and requery.

search_record(self, **params)

Search for (and jump to) the first record matching a set of field values.

Parameters:: params - search conditions in the notation fieldname=value where the fieldname is the name of a GFField.

Returns:: True if a record was found, False otherwise.

set_filter(self, *args, **params)

Set new filter criteria for this block.

Parameters:: args - zero, one or more condition trees, can be in dictionary format, in prefix notation, or GCondition object trees. Field names in these conditions are passed directly to the backend, i.e. they are database column names. This is useful to create queries of arbitary complexity.; params - simple filter values in the notation fieldname=value where the fieldname is the name of a GFField. This is useful to create straightforward simple filters where the database columns included in the condition have their GFField assigned. This also works for lookup fields.

Returns:: True if the filter was applied, False if the user aborted when being asked whether or not to save changes.

set_value(self, field, value)

Set the value of the given field, depending on the block's state.

Parameters:: field - the GFField object.

undelete_record(self)

Remove the deletion mark from the current record.

update(self)

Update the backend with changes to this block without finally commmitting them.

This can be useful to make the backend react to changes entered by the user, for example to make gnue-appserver recalculate calculated fields.

validate(self)

Validate the block to decide whether the focus can be moved away from it.

This function can raise an exception, in which case the focus change will be prevented.