Wx::DBI::Form - form helper for wxPerl, DBI, and Glade


NAME

Wx::DBI::Form - form helper for wxPerl, DBI, and Glade

Back to Top


SYNOPSIS

This is an abstract base class, not for direct use.

Back to Top


DESCRIPTION

Wx::DBI::Form provides database functionality for glade produced forms.

It is meant to be a base class for "Form" packages. These packages define the database tables and columns to use for each widget in the form. This package looks at those definitions and creates the linkage to them.

Back to Top


FUNCTIONS

new($class, $parentform)
Functionality:

Constructor for the Wx::DBI::Form class.

The special $parentform "glade" is provided by the main toplevel form to tell us that we are the toplevel.

An empty $parentform implies that we need to be a 'Wx::Frame' object and so transforms the current object into a Wx::Frame as well.

Return value:

New Wx::DBI::Form object.

cancel_edit($self)
Functionality:

An 'edit' means the user has changed data in a widgets interface. our cached data is still intact since we just copy it to the widget rather than tying it. So if it is a existing record then simply copy the cached data back to the widgets.

If it is a new record, refresh the data to wipe out the "appended" extra record.

Return value:

None.

get_parentform($self)
Functionality:

Retrieve the parent form for the current form. If this form does not have a parent it returns undef.

Return value:

A reference to the parent form, or undef if there is no parent.

get_form($self, $path)
Parameters:

$path is a multipart "path", such as "./field_form/field_list", where "." = Go to toplevel form; ".." = Go up one level; "anything else" = a sub form name in the widget definition for the current form.

Functionality:

Search for a form.

Return value:

A reference to the spcified form.

initialize($self)
Functionality:

This used to be functional but has since become just a container for a create_frame call.

Return value:

None.

get_glade_widref($self, $gladename)
Parameters:

$gladename is the string identifying a particular widget.

Functionality:

Given a widget name e.g. 'panel_1' return the widget reference.

Return value:

A reference corresponding to the named glade widget.

xget_glade_toplevel($self)
Functionality:

Returns the toplevel form object. If we are not the toplevel then it recursively calls itself using get_parentform($self)

Return value:

None.

get_main_form($self)
Functionality:

Return a reference to the main form to which this widget belongs.

Return value:

A reference to the main form to which this widget belongs.

create_frame($self)
Functionality:

Loop over the 'Widget Definitions' in the form definition package and and link the glade widgets to the database columns.

Subforms defined in the widget definitions cause this method to be recursive.

Return value:

None.

create_evt_handlers($self, $typehash, $widref, $name, $widtype, $col)
Parameters:

$typehash is a reference to a hash of of event handler types (currently ON_EXIT and ON_CHANGE are recognized) and their handlers (the handlers being subroutine references). $widref is a reference to the widget for the handlers. $name is the widget's name. $widtype is the widget's type (currently "Grid" and anything else). $col is the columns to which the handlers will be assigned (for "Grid" types).

Functionality:

Create and register event handlers.

Return value:

None.

process_change_handler($self, $handler, $name)
Parameters:

$handler is the handler function for the LOST FOCUS event. $name is the name of the widget for which to process the event.

Functionality:

Process a LOST FOCUS event to see if the item has changed.

Return value:

None.

get_pkey_clause($self)
Functionality:

Return's the primary key clause.

Return value:

The primary key clause, or undef if the primary key has no data.

build_subform($self, $formdef)
Parameters:

$formdef is the subform definition.

Functionality:

With using wxGlade we can specify the name of a sizer control in the specs and use it here to insert widgets.

Return value:

A reference to the newly created subform.

build_listbox_list(@_)
Parameters:

@_ is passed directly in to build_combo_list().

Functionality:

Call build_combo_list() with @_.

Return value:

Passes back the return value of build_combo_list().

build_combo_list($self, $item, $args)
Parameters:

$item is the ComboBox whose list will be built. $args is a hash of any optional arguments (currently, these can be $args->{widref} and $args->{conditional}.

Functionality:

Takes the sql definitions of a combo and creates the data necessary to fill the box.

NOTE: This may need to be moved to the ComboBox.pm.

Return value:

A reference to the data added to the ComboBox.

get_tablename($self)
Functionality:

Used in save_data to use as a reference on new records.

Return value:

The name of the form's associated SQL table.

build_sql_xref($self)
Functionality:

Build a cross reference hash so that we can cross reference column number (0 .... X) to column name.

Return value:

None.

build_form_xref($self)
Functionality:

Build a cross reference hash so that we can cross reference column number (0 .... X) to column name.

Return value:

None.

get_sqlcolumnidx($self, $column)
Parameters:

$column is the name of the column for which the index is desired.

Functionality:

Given a column name return the index of that column.

Return value:

The index corresponding to the specified column.

get_formcolumnidx($self, $column)
Parameters:

$column is the name of the column for which the index is desired.

Functionality:

Given a column name (or label, or gladename, if column name does not exist) return the index of that column.

Return value:

The index corresponding to the specified column.

get_widdef_slow($self, $searchhash)
Parameters:

$searchhash is a hash of widget definitions.

Functionality:

Get widget definition by matching one or more key value pairs.

Return value:

First widget definition matched, or undef if there is no match.

get_widdef($self, $string)
Parameters:

$string is the name of a widget for which a definition is desired.

Functionality:

Get widget definition given a string. The string is matched using the xref table created by build_form_xref() and build_sql_xref(). It refs on sqlcol, then label if that does not exist. If this does work for you then use get_widdef_slow().

Return value:

Returns the specified widget's definition.

extract_form_from_path($self, $path)
Parameters:

$path is a string of the form "parent.col", "./form1/form2/form3.col", or "../../form2.col".

Functionality:

Determines the form name and its associated column name.

Return value:

A reference to the form and the associated column name.

get_col_data($self, $column)
Parameters:

$column is the name (or label) of a column for which to retrieve data.

Functionality:

Given a column name (or label if column name does not exist) return the data that has been retrieved for that column.

Return value:

The data associated with the specified column, or undef if the the column does not exist.

get_wid_data($self, $column)
Parameters:

$column is the name (or label) of a column for which to retrieve widget data. $row is required if the widget is a grid.

Functionality:

Given a column name (or label if column name does not exist) return the data that is in the widget for that column.

Return value:

The widget data associated with the specified column, or undef if the the column does not exist.

set_wid_data($self, $colname, $data, $extra)
Parameters:

$colname is the name of the column whose data is to be set. $data is a reference to the data to set (unless this is a grid, in which case it is the row). $extra is used when setting data in a grid, and is a reference to the data.

Functionality:

Given a particular column name, set the data for the widget.

Return value:

None.

get_grid_ref($self)
Functionality:

Find the grid ref in $self and return that reference. This is called from save_all_data() and show_all_data(). This presumes that we have only one grid in $self which is also assumed in the basic structure of this package so we are not really stepping out on a limb here.

Return value:

A reference to the grid in $self.

save_all_data($self)
Functionality:

Loop through the grid reference and call save_data() for each row in the grid.

Return value:

None.

delete_all_data($self)
Functionality:

Delete data in a grid form.

Return value:

None.

do_backtrace($error)
Functionality:

Output (to both standard out and to the log file) an emergency error message, along with a backtrace, and then terminate the application.

Return value:

None.

show_all_data($self, $direction)
Parameters:

$direction is ... FIXME

Functionality:

For grid oriented forms. The data set should be limited to whatever data corresponds to the parent id. So we will not be showing multiple sets of data, just all the records belonging to this set.

Return value:

None.

filter_remove($self)
Functionality:

Remove the form's current filter and replace its WHERE clause.

Return value:

None.

filter_add($self, $filter)
Parameters:

$filter is the new clause to add to the WHERE part of the SQL query.i

Functionality:

If there is no WHERE clause, the $filter becomes the WHERE clause. If there is already a WHERE clause, the $filter is joined to the current WHERE with an AND.

Return value:

None.

process_goto($self, $goto)
Parameters:

$goto is the string which will be matched to a record. The string can be either a number, a regular expression, or an equality, depending on whether the string contains only digits, "=~", or "=", respectively.

Functionality:

Given a goto statement search through the data to find the first matching record and return the index to that record.

Return value:

The index to the matching record, or undef if no record is matched.

delete_data($self, $direction)
Parameters:

$direction is ... FIXME

Functionality:

Delete a form record.

Return value:

undef if there is no parent form, or 1 otherwise.

delete_single_grid_record($self)
Functionality:

Removes the data associated with the current record and then remove the row from the grid.

Return value:

None.

save_data($self, $direction)
Parameters:

$direction is ... FIXME

Functionality:

Save all the data in the form.

Return value:

1.

create_save_data_statements($self)
Functionality:

Use the _save_data hash to create a series of UPDATE/INSERT statements.

Return value:

None.

create_save_data_statement($self, $data, $table)
Parameters:

$data is a hash with column names as keys. Each value for a column name will be a hash as well. Most of the time this will contain one key 'data'. sometimes it will contain a 'ref' key as well that indicates it is a primary key or a parent linker column (contains a parent key). $table is the table in which the data will be saved.

Functionality:

Save the specified data in the specified table.

Return value:

($pkname, $pkvalue) - the last found Primary Key name and value so that we can find the record when we are complete.

show_data($self, $direction, $gridonly)
Parameters:

$direction is one of the members of the list qw/next prev first last current refresh new/. If $gridonly has any value, then expand_sqlwhere() will not be called.

Functionality:

This is for the entire form (that this scope knows of). This is a base class so we have access to the $self->widdefs.

  1. Get a row of data

  2. Loop over the widdefs and for each widget update the contents to its corresponding data column.

  3. Anything special needs to happen for "Hidden" widget type (placeholders)?

Return value:

1.

get_default($self, $widgetdef, $direction, $dataref)
Parameters:

$widgetdef is the widget for which we want data. The only currently recognized $direction is new. $dataref is a reference where the widget's data will be placed (i.e., returned to the caller).

Functionality:

None.

Return value:

None.

get_data($self, $direction)
Parameters:

$direction is one of the members of the list qw/next prev first last current refresh new/.

Functionality:

Get a row of data from the data cache.

Return value:

return $self-{data}->[$self->{datacursor}]> or undef is there is no data.

expand_sqlwhere($self, $where, $alt)
Parameters:

$where is the WHERE clause, which potentially contains variable references. $alt, if true, indicates that two lists should be returned.

Functionality:

Look at the where clause. If it contains any variable references then expand them into real data and return the result.

Return value:

The WHERE clause (passed in as $where), with any variables expanded and replaced with real data. Also, if $alt is true, then an alternately formatted list is returned. The two formats are (data=?, data2=?) and ($data, $data2).

append_new_data_record($self, $gridonly)
Parameters:

$gridonly should be true when the function is being called on a grid.

Functionality:

Create an empty recordset based on the widget definitions and append it to the end of our current recordset.

Return value:

None.

fetch_data($self)
Functionality:

Get the bulk data from the database.

Return value:

None.

get_cached_qry($self, $qry)
Parameters:

$qry is the query to find or cache.

Functionality:

Look for $qry in the cache of queries. If it is there, then returned the cached query. If it is not present in the cache, then cache (prepare) it and returned the cached (prepared) version.

Return value:

None.

sum_data_col($self, $colname)
Parameters:

$colname is the name of the column to aggregate.

Functionality:

Loop over all the data in our current recordset, sum a specific column and return the total.

This is a simple aggregate function that can be done on the current data in memory without having to translate into SQL.

Return value:

The total of the numeric values in the column.

get_grid_col($self, $colname)
Parameters:

$colname is the name of the database column, for which the corresponding grid column is desired.

Functionality:

Find and return the data in the grid column corresponding to the database column identified by $colname.

Return value:

An array with the data contained in the corresponding grid column.

sum_grid_col($self, $colname)
Parameters:

$colname is the name of the column to aggregate.

Functionality:

Loop over all the data in our current recordset, sum a specific column and return the total.

This is a simple aggregate function that can be done on the current data in memory without having to translate into SQL.

In contrast to sum_data_col(), this method sums a grid column. Which is identical if there is no new user entered data. However if the user has entered data and not yet saved, this method is the one we want.

Return value:

The total of the numeric values in the column.

merge_data($self, $data)
Parameters:

$data is a reference to a hash whose values will be merged into $self.

Functionality:

Take a ref to hash and merge its keys into the self hash.

Return value:

None.

print_combo_list($self, $data)
Parameters:

$data is a reference to an array that presumably contains values from a combo box widget.

Functionality:

Debug method for viewing the contents of a list.

Return value:

None.

Back to Top


AUTHORS

Doug Breshears <doug@jshfarms.com>
Roberto C. Sanchez <roberto@connexer.com>

Back to Top


BUGS

No known bugs.

Back to Top


SEE ALSO

README

Back to Top


COPYRIGHT

Copyright 2008-2009 JSH Farms, Inc.

Wx::DBI is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version, or under the terms of the Artistic License as published by the Perl Foundation, either version 2.0 of the license, or (at your option) any later version.

Wx::DBI is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License or the Artistic License for more details.

You should have received a copy of the GNU General Public License and a copy of the Artistic License along with Wx::DBI. If not, see <http://www.gnu.org/licenses/> and <http://www.perlfoundation.org/artistic_license_2_0>, respectively.

Back to Top

 Wx::DBI::Form - form helper for wxPerl, DBI, and Glade