Class dCursorMixin

Read-only object reference to the Dabo Application object.  (dApp).

When inserting a new record, does the backend populate the PK field?

When True (default), table and column names are enclosed with
quotes during SQL creation.  (bool)

Returns the SQL statement automatically generated by the sql manager.

Auxiliary cursor object that handles queries that would otherwise
affect the main cursor's data set.  (dCursorMixin subclass)

Returns a reference to the object defining backend-specific behavior (dBackend)

The base Dabo class of the object. Read-only.  (class)

Base key used when saving/restoring preferences  (str)

The class the object is based on. Read-only.  (class)

Returns the current SQL that will be run, which is one of UserSQL or AutoSQL.

Returns the structure of the cursor in a tuple of 6-tuples.

| 0: field alias (str)
| 1: data type code (str)
| 2: pk field (bool)
| 3: table name (str)
| 4: field name (str)
| 5: field scale (int or None)

This information will try to come from a few places, in order:

1) The explicitly-set DataStructure property
2) The backend table method

Encoding type used by the Backend  (string)

Tuple of field names and types, as returned by the backend  (tuple)

Returns True if the current record is new and unsaved

Returns True if this cursor is used for managing internal
Dabo preferences and settings. Default=False.  (bool)

Name of field that is the PK. If multiple fields make up the key,
separate the fields with commas. (str)

Returns the last executed SQL statement.

Specifies which events to log.  (list of strings)

If the first element is 'All', all events except the following listed events
will be logged.
Event logging is resource-intensive, so in addition to setting this LogEvents
property, you also need to make the following call:

	>>> dabo.eventLogging = True

The name of the object.  (str)

The character(s) used to indicate a parameter in an SQL statement.
This can be different for different backend systems. Read-only.  (str)

The containing object.  (obj)

Reference to the Preference Management object  (dPref)

Represents a record in the data set. You can address individual
columns by referring to 'self.Record.fieldName' (read-only) (no type)

Current number of rows in the recordset. Read-only.

Current row in the recordset.

The name of the table in the database that this cursor is updating.

SQL statement to run. If set, the automatic SQL builder will not be used.

A dictionary mapping virtual_field_name to a function to call.

The specified function will be called when getFieldVal() is called on
the specified field name.

Add a field to the field clause.

Add a table to the sql statement. For joins, use
the addJoin() method.

Add an expression to the group-by clause.

Add a joined table to the sql statement.

Add an expression to the order-by clause.

Add an expression to the where clause.

Subclass hook. Called after the object's __init__ has run fully.
Subclasses should place their __init__ code here in this hook, instead of
overriding __init__ directly, to avoid conflicting with base Dabo behavior.

Appends the rows in the passed dataset to this cursor's dataset. No checking
is done on the dataset columns to make sure that they are correct for this cursor;
it is the responsibility of the caller to make sure that they match. If invalid data is
passed, a dException.FieldNotFoundException will be raised.

Automatically bind any on*() methods to the associated event.

User code only needs to define the callback, and Dabo will automatically
set up the event binding. This will satisfy lots of common cases where
you want an object or its parent to respond to the object's events.

To use this feature, just define a method on<EventName>(), or	if you
want a parent container to respond to the event, make a method in the
parent on<EventName>_<object Name or RegID>().

For example::
	
	class MyButton(dabo.ui.dButton):
		def onHit(self, evt):
			print "Hit!"

	class MyPanel(dabo.ui.dPanel):
		def afterInit(self):
			self.addObject(MyButton, RegID="btn1")

		def onHit_btn1(self, evt):
			print "panel: button hit!"

When the button is pressed, you'll see both 'hit' messages because of
auto event binding.

If you want to bind your events explicitly, you can turn off auto event
binding by calling::

	 dabo.autoBindEvents = False

This feature is inspired by PythonCard.

Subclass hook. Called before the object is fully instantiated.
Usually, user code should override afterInit() instead, but there may be
cases where you need to set an attribute before the init stage is fully
underway.

Begin a SQL transaction.

Bind a dEvent to a callback function.

Bind a sequence of [dEvent, callback] lists.

Revert any changes to the data set back to the original values.

Verify that the field(s) specified in the KeyField prop exist.

Clear the last requery time to force the cache to be expired.

Creates a copy of the current record and adds it to the dataset.

Commit a SQL transaction.

Create a many-to-many association.

Create indexes based on the table definition.

Create a table based on the table definition.

Create a table and its indexes based on the table definition.

Returns an XML string containing the information necessary to
re-create this cursor.

Delete the specified row, or the currently active row.

Escape special characters in SQL strings.

Provides the proper escaping of values in XML output

Execute the sql, and populate the DataSet if it is a select statement.

Execute the passed SQL using an auxiliary cursor.
This is considered 'safe', because it won't harm the contents
of the main cursor. Returns the temp cursor.

Apply a filter to the current records.

Allows you to filter by any valid Python expression.

Move the record pointer to the first record of the data set.

Some backends need to be prompted to flush changes
to disk even without starting a transaction. This is the method
to call to accomplish this.

Format BLOB values for the backend

Format DateTime values for the backend

Format None values for the backend

Create a temporary PK for a new record. Set the key field to this
value, and also create a temp field to hold it so that when saving the
new record, child records that are linked to this one can be updated
with the actual PK value.

Return the fully qualified name of the object.

Returns a list of rows with changes.

Get the child filter part of the sql statement.

Returns the current record (as determined by self.RowNumber)
as a dict, or None if the RowNumber is not a valid record.

Create a compact representation of all the modified records
for this cursor.

Get the entire data set encapsulated in a dDataSet object.

If the optional	'flds' parameter is given, the result set will be filtered
to only include the specified fields. rowStart specifies the starting row
to include, and rows is the number of rows to return.

Returns the internal _types dict.

Get the field clause of the sql statement.

Get field information from the cursor description.

Returns a tuple of 3-tuples, where the 3-tuple's elements are:

	| 0: the field name (string)
	| 1: the field type ('I', 'N', 'C', 'M', 'B', 'D', 'T'), or None.
	| 2: boolean specifying whether this is a pk field, or None.

Return the value of the specified field in the current or specified row.

Get field information about the backend table.

Returns a list of 3-tuples, where the 3-tuple's elements are:

	| 0: the field name (string)
	| 1: the field type ('I', 'N', 'C', 'M', 'B', 'D', 'T')
	| 2: boolean specifying whether this is a pk field.

Get the from clause of the sql statement.

Get the group-by clause of the sql statement.

Get the join clause of the sql statement.

Return the most recently generated PK

Get the limit clause of the sql statement.

Get the limit clause of the sql statement.

Return the position to place the limit clause.

For currently-supported dbapi's, the return values of 'top' or 'bottom'
are sufficient.

Return the word to use in the db-specific limit clause.

Get the order-by clause of the sql statement.

Returns the value of the PK field in the current or passed record number.
If that record is a new unsaved record, return the temp PK value. If this is a
compound PK, return a tuple containing each field's values.

Returns a dictionary of property name/value pairs.

If a sequence of properties is passed, just those property values
will be returned. Otherwise, all property values will be returned.
The sequence of properties can be a list, tuple, or plain string
positional arguments. For instance, all of the following are
equivilent::

	print self.getProperties("Caption", "FontInfo", "Form")
	print self.getProperties(["Caption", "FontInfo", "Form"])
	t = ("Caption", "FontInfo", "Form")
	print self.getProperties(t)
	print self.getProperties(\*t)

An exception will be raised if any passed property names don't
exist, aren't actual properties, or are not readable (do not have
getter functions).

However, if an exception is raised from the property getter function,
the exception will get caught and used as the property value in the
returned property dictionary. This allows the property list to be
returned even if some properties can't be evaluated correctly by the
object yet.

Returns a dictionary containing an element for each changed
field in the specified record (or the current record if none is specified).
The field name is the key for each element; the value is a 2-element
tuple, with the first element being the original value, and the second
being the current value. You can specify the record by either the
row number or the PK.

Get the complete SQL statement from all the parts.

Creates a SQL statement that will not return any records.

Get the number of records in the backend table.

Return a tuple of tables in the current database.

Get the where clause of the sql statement.

Return True if the passed pk is present in the dataset.

Hook for subclasses. User code should do custom event binding
here, such as::
	
	self.bindEvent(dEvents.GotFocus, self.customGotFocusHandler)
	

Hook for subclasses. User subclasses should set properties
here, such as::
	
	self.Name = "MyTextBox"
	self.BackColor = (192,192,192)
	

Return True if there are any changes to the local field values.

If allRows is True (the default), all records in the recordset will be
considered. Otherwise, only the current record will be checked.

If includeNewUnchanged is True, new records that have not been
modified from their default values, which normally are not
considered 'changed', will be counted as 'changed'.

Move the record pointer to the last record in the recordset.

Find the first row where the field value matches the passed value.

Returns True or False, depending on whether a matching value was located.
If 'fld' is not specified, the current sortColumn is used. If 'caseSensitive' is
set to False, string comparisons are done in a case-insensitive fashion.

This is very similar to the seek() method, with two main differences: there
is no concept of a near-match; either the value is found or it isn't; the return
value is a boolean indicating if the match was found, not the matching RowNumber.

Runs a lookup in the specified field for the desired value. If
found, returns the PK for that record. If not found, a record is
inserted into the table, with its 'field' column populated with 'val',
and the new PK is returned. None of this affects the current dataset.

Create the WHERE clause used for updates, based on the pk field.

Optionally pass in a row number, otherwise use the current record.

Create the 'set field=val' section of the Update statement. Return a 2-tuple
containing the sql portion as the first element, and the parameters for the
values as the second.

Creates an association in a M-M relationship. If the relationship
already exists, nothing changes. Otherwise, this will ensure that
both values exist in their respective tables, and will create the 
entry in the association table.

Associates the value in the 'other' table of a M-M relationship with the
current record. If that value doesn't exist in the other table, it is added.

Removes all associations between the current record and the associated
M-M table.

Removes the association between the current record and the specified value
in the 'other' table of a M-M relationship. If no such association exists,
nothing happens.

Removes the association between the current record and every item in 'listOfValues'
in the 'other' table of a M-M relationship. If no such association exists,
nothing happens.

Returns a dataset containing the values for the specified fields
in the records associated with the current record.

Adds and/or removes association records so that the current record
is associated with every item in listOfValues, and none other.

Find the record with the passed primary key, and make it active.

If the record is not found, the position is set to the first record.

Move the record pointer to the specified row number.

If the specified row does not exist, the pointer remains where it is,
and an exception is raised.

Add a new record to the data set.

Move the record pointer forward one position in the recordset.

Returns the value of the field as it existed after the last requery.

Returns the PK expression for the passed record.

Returns the field or comma-separated list of field names
for the PK for this cursor's table.

Various backend databases require that you manually
generate new PKs if you need to refer to their values afterward.
This method will call the backend to generate and
retrieve a new PK if the backend supports this. We use the
auxiliary cursor so as not to alter the current data.

Modifies WHERE clauses as needed for each backend.

Move the record pointer back one position in the recordset.

Send the event to all registered listeners.

If uiEvent is sent, dEvents.Event will be able to parse it for useful
information to send along to the callback. 

Additional arguments, if any, are sent along to the constructor	of the
event. While this feature exists so that UI-lib event handlers can pass
along information (such as the keystroke information in a key event), user
code may pass along additional arguments as well, which	will exist in the
event.EventData dictionary property.

In most cases, user code should call raiseEvent() with
the event class (dEvents.Hit, for example) as the only parameter.

Remove the most recently applied filter.

Remove all applied filters, going back to the original data set.

Replaces the value of the specified field with the given value
or expression. All records matching the scope are affected; if
no scope is specified, all records are affected.

'valOrExpr' will be treated as a literal value, unless it is prefixed
with an equals sign. All expressions will therefore be a string
beginning with '='. Literals can be of any type.

.. note::
	
   This does NOT work with the memento framework for
   determining modified records. It is strongly recommended that
   instead of calling this directly that the bizobj.replace() method
   be used in any programming.
   

Roll back (revert) a SQL transaction.

Save any changes to the current record back to the data store.

Find the first row where the field value matches the passed value.

Returns the row number of the first record that matches the passed
value in the designated field, or -1 if there is no match. If 'near' is
True, a match will happen on the row whose value is the greatest value
that is less than the passed value. If 'caseSensitive' is set to False,
string comparisons are done in a case-insensitive fashion.

If sort is True (the default), then we seek to the first matching value
without sorting first. 

If incremental is True (default is False), then we only compare the first
characters up until the length of val.

This method sets the appropriate WHERE filter for dependent child queries.

Set the child filter clause of the sql statement.

Set the records of the cursor to the passed dDataSet instance.

Obviously, use with care. You can't get the original records back 
and this is really intended for one-off read-only cursors.

Set the default field values for newly added records. The
'vals' parameter is a dictionary of fields and their default values.
If vals is None, the defaults for all but the KeyField will be set to
None, and their values will not be included in the insert statement
when saved unless the user changes them to some non-null
value.

Set the field clause of the sql statement.

Set the value of the specified field.

Set the value for multiple fields with one call by passing a dict containing
the field names as keys, and the new values as values.

Set the from clause of the sql statement.

Set the group-by clause of the sql statement.

Set the join clause of the sql statement.

Set the limit clause of the sql statement.

Set the limit clause of the sql statement.

Set the current record to be flagged as a new record.

dBizobj will automatically call this method as appropriate, but if you are
using dCursor without a proxy dBizobj, you'll need to manually call this
method after cursor.new(), and (if applicable) after cursor.genTempAutoPK().

For example::
	
	cursor.new()
	cursor.genTempAutoPK()
	cursor.setNewFlag()

Called when the parent has no records, which implies that the child
cannot have any, either.

Set the order-by clause of the sql statement.

Sets a group of properties on the object all at once.

You have the following options for sending the properties:
	
	1) Property/Value pair dictionary
	2) Keyword arguments
	3) Both

The following examples all do the same thing::

	self.setProperties(FontBold=True, ForeColor="Red")
	self.setProperties({"FontBold": True, "ForeColor": "Red"})
	self.setProperties({"FontBold": True}, ForeColor="Red")

Sets a group of properties on the object all at once. This
is different from the regular setProperties() method because
it only accepts a dict containing prop:value pairs, and it
assumes that the value is always a string. It will convert
the value to the correct type for the property, and then set
the property to that converted value. If the value needs to be evaluated
in a specific namespace, pass that as the 'context' parameter.

Set the value for multiple fields with one call by passing a dict containing
the field names as keys, and the new values as values.

Set the where clause of the sql statement.

Sort the result set on the specified column in the specified order. If the sort
direction is not specified, default to ascending order. If 'cycle' is specified as the
direction, use the next ordering in the list [None, 'ASC', 'DESC']. The possible
values for 'ordr' are:

	None
	"" (i.e., an empty string)
	ASC
	DESC
	CYCLE

Only the first three characters are significant; case is ignored.

Remove a previously registered event binding.

Removes all registrations that exist for the given binding for this
object. If event is None, all bindings for the passed function are
removed. If function is None, all bindings for the passed event are
removed. If both event and function are None, all event bindings are
removed.