Working with SubForms in dBASE
Last Modified: July, 2002
Ken Mayer, Senior SQA Engineer
Example code can be obtained here: SubformSamples.zip
What Is a SubForm?
What exactly is a subform? Simply put, it is a form contained within another
form. It is a new type of container that can be used in your forms, and it acts
mostly like a regular dBASE form (see details given below).
In terms of dBASE's dBL programming language, a subform is a new object in
dBASE Plus, subclassed (internally) from the stock form class.
For all intents and purposes, a subform has all the properties, methods and events
of a standard form, except as noted below -- the following information
is from dBASE R&D:
- Subforms do not have the following properties:
- Subforms do not have a ReadModal() method.
- Subforms have a parent property, which the form object does not have.
The parent property is read-only once the subform is instantiated -- when
you create a subform the property is set at that time, therefore you cannot
set the parent property by code after it is open. If you need to
change the parent, close the subform, and reinstantiate it with
the new parent form ...
- Subforms still have the inDesign property, even though you cannot
at this time bring the subform into the designer (see later in this
document) -- this is for compatibility with custom controls that need
to check the parent.inDesign property.
- Subforms behave as if MDI=false and are parented to another form or subform.
- Parenting the subform to a form (or another subform) restricts the subform
to be displayed within the client area of the parent form. It also allows
the parent form to close the subform when it is being closed.
- Subforms are not form components.
- Subforms should be able to have their own popup menu. (See the OLH for setting
up Popup menus for forms -- the exact same syntax works with subforms. Also
see the samples -- there is a simple example of a form with a popup and
a subform with a popup -- run SubPopupTest.wfm to see this.)
- Subforms are able to have their own toolbar, however, the toolbar appears
ON THE SUBFORM, not the _app.framewin ... (see test form SubToolbarTest.wfm
in the sample code).
- All form components should be able to work properly on a subform as they do
on a form.
- A form containing one or more subforms internally tracks which
subform (if any) is currently active. When a subform is active,
the subform has the focus. When a form component is given focus,
the active subform loses focus and is set to inactive. Clicking
anywhere on a subform or subform component should activate the
subform and set focus to a control on the subform.
- A form's canClose will call the canClose for any child subforms.
If a subform's canClose returns false, the form's canClose will
return false (and the parent form will not close).
- Subforms can be parents of other subforms.
How Do I Use a SubForm?
Programmatically it's as simple as:
fMain = new Form()
fSub = new SubForm( fMain ) // 'fMain' here is the PARENT form
The code shown above would produce the following:
Form with a subform
Note that there is an optional parameter after the parent reference. The optional
parameter is the text that appears in the titlebar of the subform.
You can either set this when you create an instance of the subform or you can
set the subform's text property.
fMain = new Form()
fSub = new SubForm( fMain, "My Subform" )
// 'fMain' here is the PARENT form
// and the text "My Subform" is the titlebar text
As a developer there are a few things that are useful to know:
- Opening a parent form does not open any subforms that may
be associated with it -- you have to open those individually.
- If you attempt to release a parent form that has at least one subform,
references to the parent will still exist -- you have to release the
subforms to remove the references to the parent form. (Use the release()
method of the subform ...)
- You can create a subform with no titlebar, no border, etc. by setting
the following properties:
If you set a colorNormal property for the subform you will get just that
subform colored. If you set the clientEdge property to true you will
get a border on the subform.
- sizeable = false
- moveable = false
- sysMenu = false
- maximize = false
- minimize = false
- Objects with transparent=true on a subform will show the background of
the subform, not the parent form.
- If you wish to use the title parameter to pass title text to the subform,
make sure that the text property of the subform is not included in the
constructor code (the form designer defaults to setting the property to
an empty string) -- the subform's text property will override the parameter
passed to the subform otherwise.
You can use a form's OPEN method, or ONOPEN event to open subforms, you can
use pushbutton onClick events -- you have a lot of power and flexibility here.
Using the Designers to Create Subforms
The form designer does not, at this time, directly support the creation or modification
of subforms. However, if you create a form, you can make it a subform by changing
the following statement:
class TestFormForm of FORM
// Change to:
class TestFormForm( oParent, cTitle ) of SUBFORM( oParent, cTitle )
Note that when you make this change, the subform cannot be modified
in the form designer unless you change that statement back.
DISCLAIMER: the author is
an employee of dBASE, Inc., but has written this on his own time. If you have
questions regarding this .HOW document, or about dBASE you can communicate directly
with the author and dBVIPS in the appropriate newsgroups on the internet.
HOW TO files are created
as a free service by members of dBVIPS and dBASE, Inc. employees to help users
learn to use dBASE more effectively. They are edited by both dBVIPS members
and dBASE, Inc. Technical Support (to ensure quality). This HOW TO file MAY
NOT BE POSTED ELSEWHERE without the explicit permission of the author, who
retains all rights to the document.
Copyright 2002, Kenneth
J. Mayer. All rights reserved.
Information about dBASE,
Inc. can be found at:
EoHT: SubForms.htm -- July, 2002 -- KJM