Working with SubForms in dBASE

Last Modified: July, 2002
Ken Mayer, Senior SQA Engineer
dBASE Inc.

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:
  • appSpeedBar
  • designView
  • scaleFontName
  • scaleFontSize
  • scaleFontBold
  • MDI
  • menuFile
• 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
fMain.open()
fSub.open()

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
fMain.open()
fSub.open()

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:
  • sizeable = false
  • moveable = false
  • sysMenu = false
  • maximize = false
  • minimize = false
  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.
• 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.

---

EoHT: SubForms.htm -- July, 2002 -- KJM