hk_datasource is the basic class which represents a resultquery or a table of a database. Never create this table directly. Use the hk_database.new_table() method instead.
Inherits from hk_data.
Two types of this class can be distinguished. Tables and resultqueries.
Resultqueries are queries with a SELECT - SQL-statement. The resulting data is readonly.
Tables are a special form of resultqueries. The SQL-statement is fixed ("SELECT * FROM <tablename>), but the resulting dataset can be edited. To reduce the number of rows you can use the function set_filter() and set_temporaryfilter(). To order the rows use the functions set_sorting() and set_temporarysorting().
A datasource manages hk_column objects, which allows you to modify the data of the datasource. See function column_by_name() for more information.
The datasource can be enabled with enable() and disabled by calling disable().
Figure 2-5. hk_datasource methods
- name()
returns the name of the datasource
- goto_row(rownumber)
moves the row selector (row cursor) to 'rownumber'
- goto_first()
move the row selector to the first row. All depending objects will be informed (visible objects, depending datasources etc) True if success, else False.
- goto_last()
move the row selector to the last row. All depending objects will be informed (visible objects, depending datasources etc) True if success, else False.
- goto_next()
move the row selector to the next row. All depending objects will be informed (visible objects, depending datasources etc) True if success, else False.
- goto_previous()
move the row selector to the previous row. All depending objects will be informed (visible objects, depending datasources etc) True if success, else False.
- row_position()
returns the row number of the current row
- max_rows()
returns the total number of existing rows
- enable()
If hk_connection is connected, this method will enable the datasource. The SQL-Statement in @ref SQL will be executed. If the SQL-statement is ok, the resulting data can be reached via the columns returned by columns(). You can browse the data by using the methods goto_row(), goto_first(), goto_last(), goto_next() and goto_previous(). returns True if enable() was successful.
- disable()
if the datasource is enabled, this function will disable it. The columnlist will be deleted.
- set_enabled(e)
convenience function: if e is true the datasource will be enabled by calling enable() else it will disable the datasource by calling disable().
- is_enabled()
returns True if the datasource is enabled.
- column_by_name(name)
returns an hk_column object of the column with the name 'name'
- store_changed_data()
if the data of the actual row has changed you can manually send the changes to the SQL Server by calling this function. The function will be called automatically before the datasource disables or the row selector will be moved to another row.
- database()
returns the hk_database object, to which this datasource belongs
- set_filter(filter[,registerchange])
It is possible to filter only specific rows from a datasource by setting this filter. just add the conditions with this function. The parameter 'filter has the same syntax as a SQL statement in the 'WHERE' section, but without the word 'WHERE'
The parameter 'registerchange' : if this class is part of a hk_presentation object (i.e. a form or a report) and registerchange is True, then the changes will be stored when the hk_presentation object is closed.
Example: SELECT * from addresses WHERE city="München", so you would call set_filter("city=\"München\"");
- filter()
returns the filter string set with set_filter()
- set_temporaryfilter(temporaryfilter)
a temporary filter just work like a normal filter (see set_filter() ), but have to be manually activated with set_use_temporaryfilter(). When the datasource is loaded with loaddata() temporaryfilters are deactivated by default.
- temporaryfilter()
returns the temporary filter string
- set_use_temporaryfilter(use)
If 'use' is set to True the temporary filter is used, else it it is not used. Attention: this will be only used next time when the datasource will be enabled. If the datasource is already enabled, first disable() the datasource and then enable() it again.
- use_temporaryfilter()
returns True if the temporary filter is used, else False is returned
- clear_filter([registerchange])
deletes the filter, which was set with set_filter()
- set_sorting(order[,registerchange])
It is possible to sort the datasource. Just add the conditions with this function. 'order' has the same syntax as a SQL statement in the "ORDER BY" section, but without the words "ORDER BY".
'registerchange': if this class is part of a hk_presentation object (i.e. a form or a report) and registerchange is true, then the changes will be stored when the hk_presentation object is closed.
Example: SELECT * from addresses ORDER BY city DESC , so you would call set_sorting("city DESC");
- sorting()
returns the sorting string set with set_sorting()
- set_temporarysorting(temporarysorting)
temporary sorting just works like normal sorting (see set_sorting() ), but has to be manually activated with set_use_temporarysorting().
- temporarysorting()
returns the temporary sorting string set with set_temporarystring()
- set_use_temporarysorting(use)
If 'use' is set to True the temporary sorting string is used, else it it is not used. Attention: this will be only used next time when the datasource will be enabled. If the datasource is already enabled, first disable() the datasource and then enable() it again.
- use_temporarysorting()
returns True if the temporary sorting string is used, else False is returned
- clear_sorting([registerchange])
deletes the sorting order, which was set with set_order()
- datasource_used()
returns True if a hk_visible object or a depending datasource is using this datasource, else returns False