ControlElement Class Reference

Inheritance diagram for ControlElement:

Detailed Description

A XHTML form control.

This class defines the common interface and features of a control in an XHTML form. It importantly adds the ability to assign events and actions to a control, effectively creating an event driven model for a web application.

An event is an effect on the control that represents user interaction (e.g. clicking, changing text). Not all controls support all events, although they do all support the FC_EVENT_UPDATE event.

An action is a callback routine that is associated with a specific control event. This routine is triggered if the event is detected. In this way, for example, some code can be called whenever an input image is clicked.

Definition at line 261 of file controls.php.

Public Member Functions

ControlElement ($name, $control_name=null)

The ControlElement constructor.

getId ()

Get the unique ID.

setId ($id)

Set the unique ID.

isSimpleControl ()

Check whether this is a simple control.

submitsMultipleValues ()

Check whether this control submits multiple values.

display ()

Check whether this control should be displayed.

setDisplay ($display)

Decide whether this control should be displayed.

disabled ()

Check whether this control is disabled.

setDisabled ($disabled)

Decide whether this control should be disabled.

updated ()

Check whether the control has been updated.

setUpdated ($updated)

Decide whether the control is to be marked as being updated.

checkControlName ($name)

Check a control name.

getControlName ()

Get the control's name.

setControlName ($name)

Set the control's name.

getValue ()

Get the control's value.

setValue ($value)

Set the control's value.

addAction ($event, $name, $callback)

Add an action.

setActionTriggered ($name, $state)

Decide whether an action should be flagged as having been triggered.

actionTriggered ($name)

Check whether an action has been triggered.

& getAction ($name)

Get an action callback.

getEvent ($name)

Get the event(s) associated with a specific action.

getActionNames ($event=0)

Get the action names, optionally associated with a particular event.

getActions ($event=0)

Get the control actions, optionally associated with a particular event.

actionExists ($name)

Check whether an action exists.

triggerAction ($name)

Trigger an action.

removeAction ($name)

Remove an action.

triggerActions ()

Trigger all actions associated with the control.

addEvent ($event)

Adds an event to the control.

eventHasOccurred ($event)

Check whether an event has occurred.

setEventHasOccurred ($event, $state)

Decide whether an event has occurred.

supportedEvents ()

Get the events supported by the control.

isValidEvent ($event)

Check whether the control supports an event.

resetEvents ()

Reset the status of the control's events.

_processPOSTED ($post)

Process a HTTPD POSTed value.

__wakeup ()

Initialise control after unserialisation.

__sleep ()

Prepare object for serialisation.

Public Attributes

$actions

A list of actions.

$events

A list of supported events.

$display

A flag stating whether the control should be displayed.

Constructor & Destructor Documentation

ControlElement::ControlElement ( $ name,

$ control_name = null

)

The ControlElement constructor.

Parameters:

$name the name of the XHTML element

Parameters:

$control_name the unique name for the control (also as appears in the HTTPD POST string)

Definition at line 275 of file controls.php.
References FC_EVENT_UPDATE, and gen_control_name().

Member Function Documentation

ControlElement::__sleep ( )

Prepare object for serialisation.
This method is automatically called just before the object is serialised to carry out clean-up operations. See the PHP documentation at http://www.php.net/manual/en/language.oop.magic-functions.php for more information.
Returns:
an array of object property names to be serialised.

Reimplemented from XHTMLElement.
Reimplemented in EnhancedImageInput, Option, CheckedInput, and SelectElement.
Definition at line 786 of file controls.php.

ControlElement::__wakeup ( )

Initialise control after unserialisation.
Checks for a POST variable corresponding to this control and processes it if found.
Returns:
void

Reimplemented from XHTMLElement.
Reimplemented in FileInput, and SelectElement.
Definition at line 769 of file controls.php.

ControlElement::_processPOSTED ( $ post )

Process a HTTPD POSTed value.
The POSTed value is processed and set as the value of the current control.
Parameters:

$post the POSTed value

Returns:
void

Reimplemented in ClickedInput, SingleOption, MultipleOption, RadioInput, and CheckboxInput.
Definition at line 749 of file controls.php.

ControlElement::actionExists ( $ name )

Check whether an action exists.

Parameters:

$name the name of an action

Returns:
true of the action exists, false otherwise

Definition at line 585 of file controls.php.

ControlElement::actionTriggered ( $ name )

Check whether an action has been triggered.

Parameters:

$name the name of the action

Returns:
true if the action has been triggered, false otherwise

Definition at line 496 of file controls.php.

ControlElement::addAction ( $ event,

$ name,

$ callback

)

Add an action.
Associate a callback routine with an event and a unique action name.

Parameters:

$event an FC_EVENT_* constant or bitwise combination to specify the event should be called for multiple events.

$name the unique name for the action

$callback a callback routine that should accept the control as it's argument (it should have the prototype: do_action(&$control);)

Returns:
void

Definition at line 463 of file controls.php.

ControlElement::addEvent ( $ event )

Adds an event to the control.
If the event is not supported by the control, an error is raised.
Parameters:

$event an event as defined by a FC_EVENT_* constant

Returns:
void

Definition at line 651 of file controls.php.

ControlElement::checkControlName ( $ name )

Check a control name.
Triggers an error if the control name is not valid.
Parameters:

$name the name to check

Returns:
void

Definition at line 404 of file controls.php.
References is_valid_control_name().

ControlElement::disabled ( )

Check whether this control is disabled.

Returns:
true if it is disabled, false otherwise

Definition at line 359 of file controls.php.

ControlElement::display ( )

Check whether this control should be displayed.

Returns:
true if this control should be displayed, false otherwise

Definition at line 337 of file controls.php.

ControlElement::eventHasOccurred ( $ event )

Check whether an event has occurred.

Returns:
true if the event has occurred, false otherwise

Reimplemented in SelectElement.
Definition at line 663 of file controls.php.

& ControlElement::getAction ( $ name )

Get an action callback.

Returns:
a reference to the callback routine

Definition at line 508 of file controls.php.

ControlElement::getActionNames ( $ event = 0 )

Get the action names, optionally associated with a particular event.
All action names registered with the control are returned unless a bitwise combination of FC_EVENT_* constants is passed as an argument in which case only those actions which support that event are returned.

Parameters:

$event the FC_EVENT_* events that should be supported by the returned actions

Returns:
an array of action names

Definition at line 541 of file controls.php.

ControlElement::getActions ( $ event = 0 )

Get the control actions, optionally associated with a particular event.
All actions registered with the control are returned unless a bitwise combination of FC_EVENT_* constants is passed as an argument in which case only those actions which support that event are returned.

Parameters:

$event the FC_EVENT_* events that should be supported by the returned actions

Returns:
an array of actions

Definition at line 568 of file controls.php.
References $actions.

ControlElement::getControlName ( )

Get the control's name.

Returns:
the control's name as a string

Reimplemented in Option.
Definition at line 414 of file controls.php.

ControlElement::getEvent ( $ name )

Get the event(s) associated with a specific action.
If the action is associated with multiple events, the returned value can be checked with the bitwise operator to see what events it supports.
Returns:
a FC_EVENT_* constant or bitwise combination

Definition at line 523 of file controls.php.

ControlElement::getId ( )

Get the unique ID.

Returns:
the ID string if it exists or null otherwise

Definition at line 297 of file controls.php.

ControlElement::getValue ( )

Get the control's value.
An interface for retrieving a control's value. This should be overridden in a subclass to return a value.
Returns:
void

Reimplemented in TextArea, ValueInput, ImageInput, Option, FileInput, and SelectElement.
Definition at line 436 of file controls.php.

ControlElement::isSimpleControl ( )

Check whether this is a simple control.
A simple control is a control that does not contain other controls.
Returns:
true if it is a simple control, false otherwise

Reimplemented in SelectElement.
Definition at line 317 of file controls.php.

ControlElement::isValidEvent ( $ event )

Check whether the control supports an event.

Parameters:

$event an FC_EVENT_* constant

Returns:
true if the event is supported, false otherwise

Definition at line 710 of file controls.php.

ControlElement::removeAction ( $ name )

Remove an action.
Removes an action from the control.
Parameters:

$name the name of the action

Returns:
void

Definition at line 623 of file controls.php.

ControlElement::resetEvents ( )

Reset the status of the control's events.
All events are set as not having occurred, and all actions are set as not having been triggered.
Returns:
void

Definition at line 721 of file controls.php.
References $events.

ControlElement::setActionTriggered ( $ name,

$ state

)

Decide whether an action should be flagged as having been triggered.

Parameters:

$name the name of the action

$state true if the action has been triggered, false otherwise

Returns:
void

Definition at line 483 of file controls.php.

ControlElement::setControlName ( $ name )

Set the control's name.

Warning:
If the name is not valid, an error is raised.

Returns:
void

Reimplemented in Option, and SelectElement.
Definition at line 424 of file controls.php.

ControlElement::setDisabled ( $ disabled )

Decide whether this control should be disabled.

Parameters:

$disabled true if the control should be disabled, false otherwise

Returns:
void

Reimplemented in HiddenInput, and EnhancedImageInput.
Definition at line 369 of file controls.php.

ControlElement::setDisplay ( $ display )

Decide whether this control should be displayed.

Parameters:

$display true if the control should be displayed, false otherwise

Returns:
void

Definition at line 347 of file controls.php.
References $display.

ControlElement::setEventHasOccurred ( $ event,

$ state

)

Decide whether an event has occurred.

Parameters:

$event an FC_EVENT_* constant

$state true if the event has occurred, false otherwise

Returns:
void

Definition at line 674 of file controls.php.

ControlElement::setId ( $ id )

Set the unique ID.

Parameters:

$id the ID string

Reimplemented in SelectElement.
Definition at line 306 of file controls.php.

ControlElement::setUpdated ( $ updated )

Decide whether the control is to be marked as being updated.
Determines whether the control should be flagged as having experienced a FC_EVENT_UPDATE event.
Returns:
void

Definition at line 390 of file controls.php.
References FC_EVENT_UPDATE.

ControlElement::setValue ( $ value )

Set the control's value.
This sets the control's value and flags the control has having been updated.
Returns:
void

Reimplemented in TextArea, ValueInput, ImageInput, Option, and FileInput.
Definition at line 446 of file controls.php.

ControlElement::submitsMultipleValues ( )

Check whether this control submits multiple values.
A control that submits multiple values is a control such as a checkbox or multiple select.
Returns:
true if the control is capable of submitting multiple values, false otherwise

Reimplemented in ImageInput, MultipleOption, CheckboxInput, SelectElement, and MultipleSelect.
Definition at line 328 of file controls.php.

ControlElement::supportedEvents ( )

Get the events supported by the control.

Returns:
an integer representing the bitwise combination of FC_EVENT_* constants supported

Definition at line 692 of file controls.php.
References $events.

ControlElement::triggerAction ( $ name )

Trigger an action.
The callback routine associated with a particular action is executed if the event associated with the action has occurred.

Parameters:

$name the name of the action

Returns:
the value returned by the callback routine, or false if the callback is not executed

Definition at line 598 of file controls.php.

ControlElement::triggerActions ( )

Trigger all actions associated with the control.
ControlElement::triggerAction() is called for each of the control's actions.
Returns:
void

Reimplemented in SelectElement.
Definition at line 634 of file controls.php.

ControlElement::updated ( )

Check whether the control has been updated.
Checks whether the FC_EVENT_UPDATE event has occurred.
Returns:
true of the control has been updated, false otherwise

Definition at line 379 of file controls.php.
References FC_EVENT_UPDATE.

Member Data Documentation

ControlElement::$actions

A list of actions.

Definition at line 264 of file controls.php.
Referenced by getActions().

ControlElement::$display

A flag stating whether the control should be displayed.

Definition at line 268 of file controls.php.
Referenced by setDisplay().

ControlElement::$events

A list of supported events.

Definition at line 266 of file controls.php.
Referenced by resetEvents(), and supportedEvents().

The documentation for this class was generated from the following file:

formcontrols/controls.php

Generated on Mon Feb 14 11:39:51 2005 for FormControls by

1.3.5


Public Member Functions
	ControlElement ($name, $control_name=null)
	The ControlElement constructor.
	getId ()
	Get the unique ID.
	setId ($id)
	Set the unique ID.
	isSimpleControl ()
	Check whether this is a simple control.
	submitsMultipleValues ()
	Check whether this control submits multiple values.
	display ()
	Check whether this control should be displayed.
	setDisplay ($display)
	Decide whether this control should be displayed.
	disabled ()
	Check whether this control is disabled.
	setDisabled ($disabled)
	Decide whether this control should be disabled.
	updated ()
	Check whether the control has been updated.
	setUpdated ($updated)
	Decide whether the control is to be marked as being updated.
	checkControlName ($name)
	Check a control name.
	getControlName ()
	Get the control's name.
	setControlName ($name)
	Set the control's name.
	getValue ()
	Get the control's value.
	setValue ($value)
	Set the control's value.
	addAction ($event, $name, $callback)
	Add an action.
	setActionTriggered ($name, $state)
	Decide whether an action should be flagged as having been triggered.
	actionTriggered ($name)
	Check whether an action has been triggered.
&	getAction ($name)
	Get an action callback.
	getEvent ($name)
	Get the event(s) associated with a specific action.
	getActionNames ($event=0)
	Get the action names, optionally associated with a particular event.
	getActions ($event=0)
	Get the control actions, optionally associated with a particular event.
	actionExists ($name)
	Check whether an action exists.
	triggerAction ($name)
	Trigger an action.
	removeAction ($name)
	Remove an action.
	triggerActions ()
	Trigger all actions associated with the control.
	addEvent ($event)
	Adds an event to the control.
	eventHasOccurred ($event)
	Check whether an event has occurred.
	setEventHasOccurred ($event, $state)
	Decide whether an event has occurred.
	supportedEvents ()
	Get the events supported by the control.
	isValidEvent ($event)
	Check whether the control supports an event.
	resetEvents ()
	Reset the status of the control's events.
	_processPOSTED ($post)
	Process a HTTPD POSTed value.
	__wakeup ()
	Initialise control after unserialisation.
	__sleep ()
	Prepare object for serialisation.
Public Attributes
	$actions
	A list of actions.
	$events
	A list of supported events.
	$display
	A flag stating whether the control should be displayed.