<!doctype html public "-//w3c//dtd html 4.0 transitional//en">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<meta name="GENERATOR" content="Mozilla/4.61 [en] (X11; I; Linux 2.2.11 i586) [Netscape]">
</head>
<body text="#000000" bgcolor="#FEFEDF" link="#0000EF" vlink="#51188E" alink="#FF0000">
<h1>
FORMS</h1>
<hr WIDTH="100%">
<p>This version (0.97) of PgAccess has changed the form API : variable
handling, query results interface and control bindings naming convention.
Please read it carefully, download the database demo and practice a while
before trying to design your own forms.
<p>For the moment, it has only some basic widgets : labels, entries, buttons
, listboxes , checkboxes and radiobuttons.
<p>Also there is a pseudo data control widget that allows you yo have access
to a query results.
<p><b>How do you generate widgets :</b>
<ol>
<li>
select a widget from the toolbox by clicking the appropriate radiobutton</li>
<li>
move to the canvas , point with the mouse at the desired location and click
the mouse button to begin</li>
<li>
keeping the mouse-button pressed move the mouse in order to draw a rectangle
that will hold the widget</li>
<li>
release the mouse-button</li>
</ol>
In the rectangle that you have designed it will appear the selected object.
<br>Move now to the attribute window to change some of its properties.
<p>Renaming, resizing items are possible (for the moment) only by modifying
appropriate parameters in attribute window. You <b>must </b>press Enter
in the edit field after changing a value in order to be accepted.
<p>You can also move items by dragging them or delete them by pressing
Del key after selecting them.
<p>In attribute window, there are some fields named <b><tt><font size=+1>Command
</font></tt></b>and
<b><tt><font size=+1>Variable</font></tt></b>.
<p>The field <b><tt><font size=+1>Command </font></tt></b>have meaning
only for Button widgets and holds the command that will be invoked when
the button is pressed.
<p> The field <b><tt><font size=+1>Variable </font></tt></b>have
meaning only for EditField , Label widgets , checkboxes and radiobuttons
and it is the name of the global variable that will hold the value for
that widget. For checkboxes the values are <b>t</b> and <b>f</b> (from
true and false) in order to simplify binding to logical data fields (PgAccess
0.82 used 0 and 1).
<p> For radiobuttons, it is usual to assign the same
variable to the same radiobuttons within the same group. That variable
will contain the name of the widget of the radiobutton that has been pressed.
Let's presume that you have entered 3 radiobuttons named red, green and
blue, all of them having the same variable named color. If you will press
them, they will assign their names to global variable.
<p> In order to make a simple test, put an entry field
and set it's variable to <b>v1</b> and a button who's command is "set v1
whisky". Press the button "Test form" and click on the button. In that
entry should appear whisky.
<br>Another test is defining in Script module a script called "My first
script" having the following commands:
<br><tt><font size=+1>tk_messageBox -title Warning -message "This is my
first message!"</font></tt>
<br>and then define a button who's command is <b><tt><font size=+1>execute_script
"My first script"</font></tt></b>.
<br>
<h2>
Database manipulation</h2>
Let's presume that our form have the internal name <b><tt>mf </tt></b>(<b>m</b>y
<b>f</b>orm). Don't forget that the Tk window names could not start with
an uppercase letter.
<br>The window will be referred inside the Tcl/Tk source as <b><tt>.mf</tt></b>
<br>If you want to close the form in run-time you have to issue the command
<b><tt>destroy
.mf</tt></b>
<p>Also, any widget created inside this window (form) will have the name
prefixed by <b><tt>.mf ,</tt></b>so we will have <b><tt>.mf.button1</tt></b>
or <b><tt>.mf.listbox1</tt></b> .
<p>We can name the data control widget <b><tt>dc</tt></b> for example.
The fully qualified name for that "virtual widget" will be <b><tt>.mf.dc</tt></b>
then. A new namespace called <b><tt>DataControl(.mf.dc)</tt></b> will be
automatically defined.
<br>The <b><tt>Command </tt></b>property of the data control widget must
contain the SQL command that will be executed.
<br>When the form will be in run-time, automatically you will have access
to the following procedures and functions from the namespace:
<p><b><tt>open</tt></b> - opens the connection and execute the query (returns
nothing)
<br><b><tt>setSQL newsql</tt></b> - set the command query that will be
executed at the next <b><tt>open</tt></b>
<br><b><tt>getRowCount</tt></b> - returns the number of records of the
result set
<br><b><tt>getRowIndex </tt></b>- returns the current record number inside
the result set
<br><b><tt>getFieldList</tt></b> - returns a Tcl list containing the fields
names from the current result set
<br><b><tt>moveFirst</tt></b> - move the cursor to the first record in
the recordset
<br><b><tt>moveLast</tt></b><tt> , <b>moveNext</b> , <b>movePrevious</b></tt>-
moves the cursor there
<br><b><tt>moveTo newrecno</tt></b> - move the cursor to that new record
number (first is 0)
<br><b><tt>updateDataSet</tt></b> - update the variables inside the designed
form that have a particular name (I'll explain later)
<br><b><tt>clearDataSet</tt></b> - clear the associated DataSet variables
<br><tt><b>fill listbox field</b> </tt>- fill the named listbox (whole
widget name as <b><tt>.mf.listbox1</tt></b>) with the all the values of
that field from the current result set
<br><b><tt>close</tt></b> - close the result set (<b><font color="#FF0000">if
you don't close it, you will loose some memory</font></b>)
<p>These procedures and functions should be called in the normal Tcl namespace
mode as in the following example:
<p><tt>DataControl(.mf.dc)::setSQL "select * from phonebook"</tt>
<br><tt>DataControl(.mf.dc)::open</tt>
<br><tt>set nrecs [DataControl(.mf.dc)::getRowCount]</tt>
<p>If you complaint about writting to many DataControl(...) you can include
many commands into a single namespace eval as in the following example
:
<p><tt>namespace eval DataControl(.mf.dc) {</tt>
<br><tt> setSQL "select * from phonebook"</tt>
<br><tt> open</tt>
<br><tt> set nrecs [getRowCount]</tt>
<br><tt> moveLast</tt>
<br><tt> updateDataSet</tt>
<br><tt>}</tt>
<p>It's no need to close a query-result set if you want to assign it a
new SQL command and open it again. That will be done automatically releasing
the memory used for the last result set.
<br>Opening a new <b>DataControl</b> will automatically position the current
row index of the result set on the first row (index 0) and will define
a new global associative array named <b>DataSet</b> that will hold data
from the current row. The key into that array will be the fully qualified
name of the data control widget followed by a comma and the name of every
field in the selected rows.
<p><i>Example:</i>
<br><tt>DataSet(.mf.dc,name)</tt>
<br><tt>DataSet(.mf.dc,city)</tt>
<p>If you want to bound some controls to the fields of the recordset, you
will have to name their associate variable like that :
<p><b><tt>DataSet(.mf.dc,salary)</tt></b> to get the "salary" field , or
<b><tt>DataSet(.mf.dc,name)</tt></b> to get the "name" field. Using the
data control procedures <b><tt>DataControl(.mf.dc)::moveNext</tt></b> or
movePrevious will automatically update the <b><tt>DataSet(.mf.dc,...)</tt></b>
array so the database information from entries in the form will be refreshed.
<br>
<p>Here it is a dumped <b><a href="formdemo.sql">sample database</a></b>
that contains a demo database. What should you do ?
<br>Shift-click the above URL in order to download that tiny file (4 Kb).
Create a empty database and <b><tt>psql yourdatabase <formdemo.sql</tt></b>
<p>You should find a single table called "phonebook" a form called "Phone
book" and another "A simple demo form".
<p>First of all enter and view the phonebook table in table view. Note
the fields and their values.
<br>Open the "Phone book" form and enter a letter (a, e or i) in the field
to the left of "Find" button then press Find. It's fine to enter one letter
in order to get more records in query result. You will get information
about the number of records selected, in the listbox you will see all the
values of field "name" from the current data set. Use buttons to move to
first, next, previous or last record within the record set.
<p>In order to add a new record, press the "New" button in order to get
new, clean entries. Fill them with your data and press "Add new" button.
A new phonebook record will be added. Also, if you want to update a record,
change it's values in the displayed fields after finding it and press "Update"
button. The values will be updated in the database BUT NOT IN THE CURRENT
QUERY RESULT . If you want to see them modified, make a new query trying
to find it again.
<p><font color="#000080">Before using the results from a query you should
know that the information that has been retrieved could be found only in
your computer client memory. It has <b>no live connection</b> to the data
from the database. That's why it isn't possible to develop a simple update
function as interface to that query-result widget. More than that : a query
result could be obtained from a SQL command that return a non-updatable
data set !!! For example fields gathered from multiple tables or summary
fields. It isn't just simple to make an automatic update procedure. The
programmer must know how to make the update or the append procedure, sometimes
using key fields to point to the desired record or an OID. There are examples
in the demo database in "Phone book" form. It may be possible that in the
future, I will develop another pseudo-widget describing a table. It would
be more simple than to implement an update or append or even a delete procedure.</font>
<p>There is in the demo database also another simple form called "A simple
demo form". It will show you how to handle variables from checkboxes, radiobuttons,
how to use listboxes, open another forms and so on. I think they will help
you.
<p>In order to avoid naming user defined forms with a particular
name of another PgAccess form, I would recommend naming them as udf0, udf1
(user defined form 0 , 1 )
<p>
<hr WIDTH="25%">
<p>Please feel free to send me your opinion at <b>teo@flex.ro</b> on forms
designing and usage.
<p><b><font size=+1>KEEP IN MIND !
THE FORM API MAY CHANGE IN ORDER TO BE MORE SIMPLE AND BETTER!</font></b>
<br><b><font size=+1>SEND ME YOUR WISHES, YOUR IDEAS, YOUR OPINIONS !</font></b>
<br><b><font size=+1>ALSO ... DON'T BLAME ME IF YOU WILL HAVE TO RE-DESIGN
YOUR OLD FORMS DUE TO SOME INCOMPATIBILITIES WITH NEWER PGACCESS VERSIONS.</font></b>
</body>
</html>
distrib
>
Mandriva
>
9.0
>
x86_64
>
media
>
main
>
by-pkgid
>
b0bdaffec652d6ef8f8e02a7771c9c1a
>
files
>
17
