Updated Wiki: Dynamic Forms Properties

You can get custom return values from the Dynamic Form using instances of the default “commandbutton” class, which resolves to the custom DF_ResultButton class by default. Using these command buttons, when the button is clicked, the form will hide and the caption of the command button will be passed to the loForm.cReturn property (any hotkey characters in the caption will be removed). This allows you to easily test loForm.cReturn to see which of command button was clicked, and you can take the appropriate action as control passes back to the calling program.

Actually, the button Caption is passed to the Tag property on the button, and the button click event passes its Tag value back to loForm.cResult and then hides the form. So, if needed, you can set the Tag value directly if you do not want to use the caption as the return value.

See Step 7 on main page for more info.

Any rendering errors are usually caused by errors in your cBodyMarkup markup string.

Rendering Errors - If the Render() methods returns .F., this means there were rendering errors, which you can read from loForm.oRenderEngine.nErrorCount and you can get and error list in a string format by calling loForm.oRenderEngine.GetErrorsAsString(), or get details on every error from the loForm.oRenderEngine.oErrors collection. Learn more aboutrendering errors here.

Even with rendering errors, the form can still be displayed to the user if desired. During development, showing the form (even with errors) will help you see where the errors occurred, as it will show a red error container in place of any controls which had rendering errors.

Display the form to the user by calling loForm.Show(). The default mode is a Modal, which can be overridden to Modeless with parameter tnMode.

Modal forms– After calling Show() or Show(1) a Modal form will be presented to the user. When they click Save, Cancel, or the [X] button the Dynamic Form will be hidden and flow will return to the calling program where you can then read any property on loForm and loForm.oRenderEngine, and even access the rendered controls. Note: at this point the form is hidden only, but still alive and accessible via its object reference. So, after control has passed back to the calling program code, you can perform the next steps required based on your application architecture... First, analyze the loForm.cResult value to know which button was clicked, then, for example,  perform any data validation, deal with buffered cursors, or call the “save” method on a Business Object.

Modeless forms – When calling Show(0) to create a Modeless form, Dynamic Form will add a unique global reference to itself on _screen (I.e. _screen.DF_3LW0JDOD6) so that the form will be kept alive even after control has passed back to the calling code and the local form reference eventually falls out of scope. From here your Dynamic Form will be released only when the user clicks the Save or Cancel button. When released, the global reference will be removed from _screen and form object will be cleared from memory. You may want to trap the Save or Cancel user actions by use of BindEvent(). You can bind to loForm.Save() and loForm.Cancel() for this purpose. The methods perform no local actions, and are merely provided as hook points for BindEvent() as described here.

Note, since the form is Modeless, if it is bound to a cursor, any movement in the record pointer in the underlying cursor will result in a change of data on the form. The could be a desirable or undesirable affect, and this behavior is exactly the same as with regular FoxPro modeless forms. So, your handling of record pointers and data management is something you must manage, just like you do in regular modeless forms.

Handling Save and Cancel Buttons– The Save and Cancel buttons will trigger calls to the Save() and Cancel() methods on the form. This architecture allows you subclass DynamicForm to provide your own Save() and Cancel() code, or to hook into these events with a BindEvent() call, if desired,  to respond to these  user actions when they eventually occur. After triggering the Save() or Cancel() methods on the form, the buttons will Hide the form if it is Modal (see Modal Forms section above), or Release the form if it is Modeless (see Modeless Forms section above).

Saving changes

If your fields are bound to cursors, the changes are applied in real time as the user edits the data on the form. If you cursors use Table Buffering, *you* will have to handle the TableUpdate() or TableRevert() calls in your handling of the Save() and Cancel() clicks as described above.

If your forms are bound to data objects you can process the changes according to your normal practices once flow returns to your calling code.  See the sample code at the top of the source code prg for an example of this pattern, andStep 7 on the main page.

Business Objects - If your forms are bound to data objects and have supporting Business Objects which provide data handling methods, you can wire up the Save button on your Dynamic Form to the “save” method on the Business Object by using the corresponding properties on the Render Engine to implement this functionality. See Using Dynamic Forms with Business Objects for more details.

Parameters:

tnMode -    0 = Modeless,   1 = Modal (default)

toFormObject –  You can have the rendered Dynamic Form centered in a hosting form if you pass in a reference to the hosting form when calling the Show() method on Dynamic Form:

---

To center the form relative to another other form:

loForm.Show(1, loSomeFormRef)

---

To assign a specific position:

loForm.Show(1, “100, 200”)

Notice the second parameter is a *string* with a “Top, Left” position value. This equates to loForm.Top = 100 and loForm.Left = 200.  The Height and Width of the form will be determined by the final rendered size, as always.

---

Another option is to Assign your own position using loForm.Left and loForm.Top, and then tell Dynamic Form not to touch it:

loForm.Show(1, .F.)

cAlias

The name of a cursor or alias to which the cBodyMarkup controls are bound.

oDataObject

The object to which the cBodyMarkup controls are bound.

cBodyMarkup

nControlLeft

nFirstControlTop

nVerticalSpacing

lLabelsAbove

nCheckBoxAlignment

0 = Middle Left (Caption on Right) (Default in VFP)
1 = Middle Right (Caption on Left)

When the Render() method is called, the caller passes in a container reference in which the caller wants controls to be rendered. As the controls are generated, the RenderEngine automatically increases the Height of the passed container, if necessary, to hold the generated controls. Eventually, this container could get VERY TALL, so as to become unusable or even off-screen. This is where nColumnHeight comes in, which says “grow the passed container up to this height, then move over to the next column”

Or, said another way, “If the contents reach nColumnHeight, then switch over to the next column”

You can avoid the effects of this column-changing behavior simply by setting a really high nColumnHeight in your subclass.

nControlHeight

The .Height of each control. Use :height => ‘n’ to override.

nTextBoxWidth

100

nEditBoxWidth

200

nNumericFieldTextboxWidth

100

nCheckBoxWidth

100

nControlWidth

100

Default width for any other controls besides the specific ones above.
Use :width => 'n' to override.

cDelimiterPattern

Caution: Don't use a comma as delimiter. It will likely break things. Default is (pipe symbol).

cDataObjectRef

Render()

This methods processes the cBodyMarkup string to create the individual controls within the passed toContainer.

RestoreData()

GetErrorsAsString()

Returns a string value of any rendering error messages that were triggered during the Render() process. Learn more about rendering errors here.