BBjControl::setCausesControlValidation

Description

In BBj 5.00 and higher, this method sets whether entering the BBjControl will trigger control validation on the control that previously had focus.

Syntax

Return Value	Method
void	setCausesControlValidation(boolean `causesValidation`)

Parameters

Parameter	Description
causesValidation	Specifies whether or not the BBjControl should cause validation. true (1) = Entering this control should cause control validation on the control that previously had focus. This is the default value. false (0) = Entering this control should not cause control validation on the control that previously had focus. This should be used sparingly, typically with a Cancel button.

Return Value

None.

Remarks

This feature is typically used with controls like the Cancel button that should let the user exit without forcing valid data to be entered first.

Controls will only trigger validation when both getCausesControlValidation() and isFocusable() are true.

Example

rem ' BBjControl::setCausesControlValidation

sysgui = unt
open (sysgui)"X0"
sysgui! = bbjapi().getSysGui()
red! = sysgui!.makeColor(sysgui!.RED)
white! = sysgui!.makeColor(sysgui!.WHITE)
title$ = "getCausesControlValidation"
window! = sysgui!.addWindow(100,100,250,200,title$,$00010083$)
window!.setCallback(sysgui!.ON_CLOSE,"Close")
statbar! = window!.addStatusBar(100)

rem ' Email Address
window!.addStaticText(201,20,25,80,25,"To:",$8000$)
addr! = window!.addEditBox(101,120,20,90,25,"Email Address")
addr!.setCallback(sysgui!.ON_CONTROL_VALIDATION,"AddrValidation")
print fnCausesControlValidation$(addr!)

rem ' Email Subject
window!.addStaticText(202,20,65,80,25,"Subject:",$8000$)
subj! = window!.addEditBox(102,120,60,90,25,"Subject")
subj!.setCallback(sysgui!.ON_CONTROL_VALIDATION,"SubjValidation")
print fnCausesControlValidation$(subj!)

rem ' OK button
OK! = window!.addButton(1,120,110,90,25,"OK")
OK!.setCallback(sysgui!.ON_BUTTON_PUSH,"OK")
OK!.setCallback(sysgui!.ON_FORM_VALIDATION,"FormValidation")
print fnCausesControlValidation$(OK!)

rem ' Cancel button
Cancel! = window!.addButton(2,20,110,90,25,"Cancel")
Cancel!.setCallback(sysgui!.ON_BUTTON_PUSH,"Cancel")
Cancel!.setCausesControlValidation(0)
print fnCausesControlValidation$(Cancel!)

rem ' Tool button
tbutton! = window!.addButton(3,20,150,90,25,"Tool Button")
tbutton!.setCallback(sysgui!.ON_BUTTON_PUSH,"tbutton")
tbutton!.setFocusable(0)
print fnCausesControlValidation$(tbutton!)
addr!.focus()
process_events

rem ' Report whether a control causes control validation
def fnCausesControlValidation$(Control!)
    causesValidation = control!.getCausesControlValidation() and control!.isFocusable()
    message$ = "Clicking in or tabbing to "
    message$ = message$ + Control!.getText()
    message$ = message$ + iff(causesValidation," causes"," does not cause")
    message$ = message$ + " control validation"
return message$
fnend

rem ' Email Address field-level validation: Must contain '@'
AddrValidation:
    valid = pos("@"=addr!.getValidationText())
    if valid
        statbar!.setText("")
        addr!.setBackColor(white!)
    else
        statbar!.setText("Email address must contain '@'")
        addr!.setBackColor(red!)
    endif
    addr!.accept(valid)
return

rem ' Email Subject field-level validation: Must be non-blank
SubjValidation:
    valid = len(subj!.getValidationText())
    if valid
        statbar!.setText("")
        subj!.setBackColor(white!)
    else
        statbar!.setText("Subject can't be blank")
        subj!.setBackColor(red!)
    endif
    subj!.accept(valid)
return

rem ' Form-level validation
FormValidation:
    if !(pos("@"=addr!.getValidationText()))
        statbar!.setText("Email address must contain '@'")
        addr!.setBackColor(red!)
        addr!.focus()
        OK!.accept(0)
    else
        if len(subj!.getValidationText()) = 0
            statbar!.setText("Subject can't be blank")
            subj!.setBackColor(red!)
            subj!.focus()
            OK!.accept(0)
        else
            OK!.accept(1)
        endif
    endif
return

rem ' We only get here if form validation is accepted
OK:
    x = msgbox("Everything is ok",0,"OK Button")
return

rem ' Cancel button bypasses validation
Cancel:
    if msgbox("I'm outta here!",1,"Cancel Button") = 1 then release
return

rem ' Non-focusable controls don't trigger validation
tbutton:
    i = msgbox("Non-focusable controls don't trigger validation",0,"tbutton")
return

rem ' Close box always lets you out
Close:
release