BBjControl::getCausesControlValidation

Description

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

Syntax

Return Value	Method
boolean	getCausesControlValidation()

Parameters

None.

Return Value

Returns whether or not this BBjControl causes control validation.

Returns true (1) when entering this control should cause control validation on the control that previously had focus. This is the default value.

Returns false (0) when entering this control will not cause control validation on the control that previously had focus. This should be used sparingly, typically with a Cancel button.

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::getCausesControlValidation

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