| dataform1 | ||
|---|---|---|
 | Chapter 22. Overview of Window and Dialog Types Provided with SIMPOL |  |
dataform1
The dataform1 type was created in the SIMPOL language library called
databaseforms.sml in order to provide a
multi-paged, data-aware form system that works as a set of wrappers to the
wxform types. One of the other enhancements is the support for system
colors, so the page background color, plus the text and background colors of the
controls also can take a system color identifier, which is interpreted at run time to
decide which color to use. The dataform1 type family consists of the
following types:
| Type | Description |
|---|---|
| dataform1 | This represents the entire form. The form contains a dring of dataform1page objects. Each page contains the graphics and controls that are found on that page. The form also has drings of controls, graphics, datasources, bitmaps, fonts, tables, links, and sibling links. |
| dataform1arc | A basic wrapper for the wxgraphicarc type, but also includes the necessary elements to be part of dataform1. |
| dataform1bitmap | A bitmap object that is also data-aware. Can be a static bitmap
or it can have a control source that contains the path name of the
bitmap, which can be a file system resource or located on the
Internet using the HTTP protocol. Must be stored using the URL
format: "file:///c/mystuff/mypic". |
| dataform1bitmapbutton | Provides a compatible wrapper for the wxformbitmapbutton type. |
| dataform1bitmapsource | Supplies the container for the bitmaps used in the form. Also contains the path and file name for images loaded from disk. Allows easy reuse of the same bitmap multiple times on one form (or potentially on multiple pages of a form). |
| dataform1button | Compatible wrapper for a button. |
| dataform1checkbox | Supplies a data-aware check box control that can not only have on or off, but which assign a value for the on state and another for the off state to the underlying database field. |
| dataform1combo | A very flexible data-aware combo box that can be filled with static values, read the values from an array, or retrieve them from a database table. Can also one set of values, but assign a different one. Finally, it also has the option to be filled by the user program by assigning a handler to the onfill event. |
| dataform1controlsource | The information used to connect a database field with a control, including the display format (used both to convert from dates, times, etc. to string for display in the control, as well as to convert from the string value to the target data type for storage in the field). Also contains information about a detail block, if the control is part of one. |
| dataform1datagrid | The purpose of the data grid is to make it easy to show data in a grid control from a table that is dependent on the main table in a form. It has restrictions on what can be done with it. The cells are read-only, since this grid is meant for display only. |
| dataform1datagridcolumn | This is a column in a data grid type. It contains the control source, which itself may contain a link to another table. An example might be a form with an ORDERS table, a data grid of information from the ORDERDTL table, and a grid column that is linked to the PRODUCT table and is showing the product name. |
| dataform1datasource | This type is used to hold the information necessary to reopen a data source, as well as a reference to the opened data source itself. |
| dataform1detailblock | A detail block is a collection of controls that are arranged in a single row, which is then replicated into a specified number of rows and columns and which may or may not have a scroll bar. This is a very powerful mechanism for displaying data. It can either be linked to the master table of a form, or it can be unlinked and filled using a SQL query. |
| dataform1edittext | The edit control is similar to the normal edit control, but has the control source and also has a speical feature for displaying a drop list based on an indexed search using a specified number of typed characters in the edit control. Works similarly to the effect seen in web browsers that remember previous form entries. |
| dataform1ellipse | A basic wrapper for the wxgraphicellipse type, but also includes the necessary elements to be part of dataform1. |
| dataform1grid | This is a free form grid control with which the programmer can create any functionality they wish. It is almost identical to the wxformgrid type but is compatible with dataform1. |
| dataform1line | A basic wrapper for the wxgraphicline type, but also includes the necessary elements to be part of dataform1. |
| dataform1link | This object contains the information necessary to create a join between two database tables. It is included in the dataform1controlsource type. |
| dataform1list | This is similar to the capabilities of the dataform1combo, allowing various ways to populate the list. Wraps the wxformlist type, but is limited to single selection, since the result will be assigned toa ssingle field in a database record. |
| dataform1option | A data-aware option button implementation. The interesting thing is that the control source is associated with the group, not the individual controls. A selection of an option will assign the value associated with the control to the field in the database record. |
| dataform1optiongroup | Provides the host for the control source for a group of option buttons. Also implements the functionality for grouping buttons together. |
| dataform1page | This contains the controls, graphics, and the reference to the wxform object that contains all the wxform controls and graphics that make up one page. |
| dataform1record | This is a container for a type(db1record) object
that also contains a flag for indicating the record has been
modified, plus methods for saving and deletion, plus events to call
back to user program code when a record is saved and when it is
deleted. These events are not typically used, however, instead the
equivalent events of the dataform1 object are
favored. |
| dataform1recordset | When working with a detail block, you may wish to retrieve the
record(s) that make up a single row on the display. The
dataform1detailblock method
getrowdata() will return a record set
with the records representing that specific row. A record set can
also be used to update a row in a detail block, by calling the
setrowdata() method. |
| dataform1rectangle | A basic wrapper for the wxgraphicrectangle type, but also includes the necessary elements to be part of dataform1. |
| dataform1scrollbar | This is a basic wrapper for the wxformscrollbar type to make it a proper part of dataform1. |
| dataform1table | This type contains a reference to a database table –
type(db1table), it also contains an array of field
information, a reference to the data source, a reference to the
form, a reference to the current index, a dlistnode
called parentnode which is used to traverse the
tables on the form, and another dlistnode called
datasourcenode that is used to traverse the
tables in the data source. See below for information on iterating
through elements on the form. There is a method called
gettablename() that can be used to
retrieve the table name of the table regardless of the type of
table. It also has events for onnewrecord,
onsaverecord, and
ondeleterecord that can be defined by the
application programmer to take an action at that point. |
| dataform1text | This type enhances the underlying wxformtext type by making it data-aware, so that information from a record can be shown, but not edited. |
| dataform1triangle | A basic wrapper for the wxgraphictriangle type, but also includes the necessary elements to be part of dataform1. |
There are a number of design concepts that are associated with the dataform1
type. Among them are: every form has a master table and will typically have a master
record. The master table is not meant to be changed once the form has been created and
is in use. Normally only the master record (from the master table) can be modified.
There are sibling links that connect to other tables in a 1:1 or n:1 relationship, like
looking up a customer number in the customer table and then displaying the name on the
form. There are also links to detail blocks and data grids, which are of the type 1:n,
so if the current form contains an order, then the lines of the order might be in a data
grid or detail block. When using the deleterecord() method, it
only deletes the master record, it does not affect any linked records. For details on
working with the dataform1 types see:Chapter 23, Using Data-Aware Forms in SIMPOL.
Using the Various dataform1 Services
The dataform1 type not only provides the capabilities of a form and its controls, but also adds database functionality to that. It includes methods for selecting records (when using linked tables, it also performs the lookups into those tables and refreshes the form automatically), changing pages, locking, editing, and saving records, firing off calculations and validations at the time records are saved, and provides two different approaches to managing data-entry. In this section we will discuss these various services. The interesting methods are listed below:
| Method Name | Description |
|---|---|
blank() | Clears all data from the data-aware controls on the form. Does not create a new record! |
checkdirtyrecords() | Checks all associated records with the form and returns .true if there are any modified records. |
deleterecord() | Deletes the current master record and then attempts to select the next record for display according to the current index. Must be locked first. |
discardrecord() | Marks the current record as not modified (dirty) and unlocks the master record if it is locked. It will also call any programmer-defined ondiscard event handler. |
findcontrol() | Given a string this function will search for a matching dataform1 control. If found, the return value will be a reference to the form control. |
findgraphic() | Given a string this function will search for a matching dataform1 graphic. If found, the return value will be a reference to the graphic. |
getfieldandtable() | This is passed field name and table name and if a matching table with a field of this name is found, it returns a reference to a dataform1controlsource object. |
lock() | Call this method to lock the master record of the table. It
also sets the modified (dirty) state to
.true. |
nameinuse() | To establish if a control name is in use (one name space is
used for controls and graphics), call this function passing the
name of the control. If in use it returns
.true, otherwise it returns
.false. |
newrecord() | Creates a new master record for the form, also internally
calls blank() to clear the form. It
will call any previously defined
onnewrecord event handler. |
refresh() | This method re-reads the data from the records already selected and associated with the form and updates the data shown on the form. |
saverecord() | This function should be called to save the newly created or
modified master record. The record will automatically be
unlocked unless the lock parameter is set
to .true. Also, if an
onsave event handler is defined, it
must return .true if the save is meant to
continue. Handling the onsave event is how
the program can handle validations and calculations prior to the
saving of the record. It receives the dataform1
object and an optional reference. To modify the fields of the
target record, or retrieve values, use the
dataform1.masterrecord.record!fieldname type of
approach. If a validation fails, it is the responsibility of the
programmer to either request a replacement value, or to set
focus to a specific control and return
.false, so that the record is not
saved. |
selectcurrent() | This works similarly to the standard
selectcurrent() method of the
ppcstype1record, though it works with
sbme1record and vola1record as
well. Also updates the form, any form links, and will call any
defined onselect event handler (for
calculated form content based on the data). |
selectfirst() | This works similarly to the standard
selectfirst() method of the
ppcstype1record, though it works with
sbme1record and vola1record as
well. Also updates the form, any form links, and will call any
defined onselect event handler (for
calculated form content based on the data). |
selectkey() | This works similarly to the standard
selectkey() method of the
ppcstype1record, though it works with
sbme1record and vola1record as
well. Also updates the form, any form links, and will call any
defined onselect event handler (for
calculated form content based on the data). |
selectlast() | This works similarly to the standard
selectlast() method of the
ppcstype1record, though it works with
sbme1record and vola1record as
well. Also updates the form, any form links, and will call any
defined onselect event handler (for
calculated form content based on the data). |
selectnext() | This works similarly to the standard
selectnext() method of the
ppcstype1record, though it works with
sbme1record and vola1record as
well. Also updates the form, any form links, and will call any
defined onselect event handler (for
calculated form content based on the data). |
selectprevious() | This works similarly to the standard
selectprevious() method of
the ppcstype1record, though it works with
sbme1record and vola1record as
well. Also updates the form, any form links, and will call any
defined onselect event handler (for
calculated form content based on the data). |
setmasterrecord() | Use this method to set a different record as the current master record of the form. This will then use the new master record to select any dependent records in detail blocks, data grids, and 1:1 links followed by a refresh(). |
setmastertable() | This will change the master table of a form. It should never be used in a normal application program. If you choose to use it, it should be used before creating any other controls, and the setmasterrecord() method should later be used to select a record unless the table is empty. |
showpage() | To change pages on a mulit-page form, use this method. |
unlock() | Call this method to unlock the master record of the form if it was previously locked. |
There are more methods, many of which are associated with adding data
sources, tables, graphics, controls, links, and so on, but which will not be
discussed here. Since these are used by the code that loads the form, they are not
as important as the ones used to actually work with the form once it has been
loaded. If you are curious about the use of these, save a form as a
dataform1 program and examine the source code, or look at the
source code for the project formlib.sml.