Working with SubForms in dBASE
Last Modified: July, 2002
Ken Mayer, Senior SQA Engineer
Print Friendly Version
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
In terms of dBASE's dBL programming language, a subform is a new
object in dBASE Plus, subclassed (internally) from the stock form
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
- 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
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.
EoHT: SubForms.htm -- July, 2002 -- KJM