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
- 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
- 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
- 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
// 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
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
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.
EoHT: SubForms.htm -- July, 2002 -- KJM