BBjControl::setCausesControlValidation

Description

In BBj 5.0 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

Variable

Description

causesValidation

Specifies if the BBjControl should cause control validation.

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.

1 = Entering this control should cause control validation on the control that previously had focus. This is the default value.

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

See Also

BBjAPI

BBjSysGui

BBjControl

BBjWindow

See the BBj Object Diagram for an illustration of the relationship between BBj Objects.