ControlChoice Class Reference

Inheritance diagram for ControlChoice:

Detailed Description

A ControlContainer that acts as a ControlElement.

This class extends a ControlContainer an also implements the interface of a ControlElement. As such it provides the basis for all 'complex' controls where an user choice is possible (e.g. <select/>) by allowing Option controls to be contained within it.

Definition at line 1946 of file controls.php.

Public Member Functions

ControlChoice ($control_class, $choice)

The ControlChoice constructor.

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.

checkControlName ($name)

Check a control name.

setControlName ($name)

Set the control's name.

getControlName ()

Get the control's name.

updated ()

Check whether the control has been updated.

getId ()

Get the unique ID.

setId ($id)

Set the unique ID.

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.

add (&$control)

Add a control.

setControlClass ($control_class)

Set the class from which Options are instantiated.

getControlClass ()

Get the class from which Options are instantiated.

& addChoice ($value, $label=null, $selected=false)

Add an Option.

getSelectedIds ()

Get the currently selected Option IDs.

getSelectedControls ()

Get the currently selected Options.

selectedCount ()

Get the number of currently selected controls.

select ($id)

Select an Option by ID.

selected ($id)

Check whether an option is selected.

deselect ($id)

Deselect an Option.

toString ()

Returns:
string

__wakeup ()

Initialise object after unserialisation.

__sleep ()

Prepare object for serialisation.

Public Attributes

$control_name

The name of the control.

$id

the unique ID of the control

$control_class

The class name of option elements.

$actions

A list of actions.

$selected

A list of selected control element IDs.

$display

Whether this control should be displayed.

$events

A list of supported events.

Constructor & Destructor Documentation

ControlChoice::ControlChoice ( $ control_class,

$ choice

)

The ControlChoice constructor.

Parameters:

$control_class the class name of supported Option controls

$choice an array of choices with which to create Option controls

Definition at line 1968 of file controls.php.
References $control_class, $control_name, $id, FC_EVENT_UPDATE, and gen_control_name().

Member Function Documentation

ControlChoice::__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 ControlContainer.
Definition at line 2551 of file controls.php.

ControlChoice::__wakeup ( )

Initialise object after unserialisation.
This method is automatically called just after the object is unserialised and ensures it is properly initialised. See the PHP documentation at http://www.php.net/manual/en/language.oop.magic-functions.php for more information.
Returns:
void

Definition at line 2542 of file controls.php.

ControlChoice::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 2239 of file controls.php.

ControlChoice::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 2172 of file controls.php.

ControlChoice::add ( &$ control )

Add a control.

Parameters:

$control a reference to the control

Returns:
void

Reimplemented from ControlContainer.
Definition at line 2394 of file controls.php.

ControlChoice::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 2142 of file controls.php.

& ControlChoice::addChoice ( $ value,

$ label = null,

$ selected = false

)

Add an Option.

Parameters:

$value the value for the option

$label the label for the option

$selected true if the Option is to be selected, false otherwise

Returns:
a reference to the newly instantiated control

Definition at line 2431 of file controls.php.
References $control_class, and $selected.

ControlChoice::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 2296 of file controls.php.

ControlChoice::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 2062 of file controls.php.
References is_valid_control_name().

ControlChoice::deselect ( $ id )

Deselect an Option.

Parameters:

$id the ID of the option to deselect

Returns:
the result of calling Option::deselect()

Definition at line 2509 of file controls.php.

ControlChoice::display ( )

Check whether this control should be displayed.

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

Definition at line 2041 of file controls.php.

ControlChoice::eventHasOccurred ( $ event )

Check whether an event has occurred.

Returns:
true if the event has occurred, false otherwise

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

& ControlChoice::getAction ( $ name )

Get an action callback.

Returns:
a reference to the callback routine

Definition at line 2184 of file controls.php.

ControlChoice::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 2202 of file controls.php.

ControlChoice::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 2223 of file controls.php.
References $actions.

ControlChoice::getControlClass ( )

Get the class from which Options are instantiated.

Returns:
the class name

Definition at line 2419 of file controls.php.

ControlChoice::getControlName ( )

Get the control's name.

Returns:
the control's name as a string

Definition at line 2088 of file controls.php.

ControlChoice::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 2193 of file controls.php.

ControlChoice::getId ( )

Get the unique ID.

Returns:
the ID string if it exists or null otherwise

Definition at line 2106 of file controls.php.

ControlChoice::getSelectedControls ( )

Get the currently selected Options.

Returns:
an array of references to controls

Definition at line 2463 of file controls.php.
References $id.

ControlChoice::getSelectedIds ( )

Get the currently selected Option IDs.

Returns:
an array of control IDs

Definition at line 2448 of file controls.php.
References $id.

ControlChoice::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 SingleChoice, and MultipleChoice.
Definition at line 2124 of file controls.php.

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

Definition at line 2023 of file controls.php.

ControlChoice::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 2364 of file controls.php.

ControlChoice::removeAction ( $ name )

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

$name the name of the action

Returns:
void

Definition at line 2271 of file controls.php.

ControlChoice::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 2373 of file controls.php.
References $events.

ControlChoice::select ( $ id )

Select an Option by ID.

Parameters:

$id the ID of the option to select

Returns:
the result of calling Option::select() on the option

Reimplemented in SingleChoice.
Definition at line 2487 of file controls.php.

ControlChoice::selected ( $ id )

Check whether an option is selected.

Parameters:

$id the ID of the option to check

Returns:
true if the option is selected, false otherwise

Definition at line 2498 of file controls.php.

ControlChoice::selectedCount ( )

Get the number of currently selected controls.

Returns:
an integer

Definition at line 2477 of file controls.php.

ControlChoice::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 2160 of file controls.php.

ControlChoice::setControlClass ( $ control_class )

Set the class from which Options are instantiated.

Parameters:

$control_class the class name

Returns:
void

Definition at line 2409 of file controls.php.
References $control_class.

ControlChoice::setControlName ( $ name )

Set the control's name.

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

Returns:
void

Definition at line 2072 of file controls.php.
References $id.

ControlChoice::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 2050 of file controls.php.
References $display.

ControlChoice::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 2329 of file controls.php.

ControlChoice::setId ( $ id )

Set the unique ID.

Parameters:

$id the ID string

Definition at line 2115 of file controls.php.
References $id.

ControlChoice::setValue ( $ value )

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

Definition at line 2132 of file controls.php.

ControlChoice::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 MultipleChoice.
Definition at line 2032 of file controls.php.

ControlChoice::supportedEvents ( )

Get the events supported by the control.

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

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

ControlChoice::toString ( )

Returns:
string

Definition at line 2521 of file controls.php.

ControlChoice::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 2248 of file controls.php.

ControlChoice::triggerActions ( )

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

Definition at line 2280 of file controls.php.

ControlChoice::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 2097 of file controls.php.
References FC_EVENT_UPDATE.

Member Data Documentation

ControlChoice::$actions

A list of actions.

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

ControlChoice::$control_class

The class name of option elements.

Definition at line 1953 of file controls.php.
Referenced by addChoice(), ControlChoice(), and setControlClass().

ControlChoice::$control_name

The name of the control.

Definition at line 1949 of file controls.php.
Referenced by ControlChoice().

ControlChoice::$display

Whether this control should be displayed.

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

ControlChoice::$events

A list of supported events.

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

ControlChoice::$id

the unique ID of the control

Definition at line 1951 of file controls.php.
Referenced by ControlChoice(), getSelectedControls(), getSelectedIds(), setControlName(), and setId().

ControlChoice::$selected

A list of selected control element IDs.

Definition at line 1957 of file controls.php.
Referenced by addChoice().

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
	ControlChoice ($control_class, $choice)
	The ControlChoice constructor.
	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.
	checkControlName ($name)
	Check a control name.
	setControlName ($name)
	Set the control's name.
	getControlName ()
	Get the control's name.
	updated ()
	Check whether the control has been updated.
	getId ()
	Get the unique ID.
	setId ($id)
	Set the unique ID.
	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.
	add (&$control)
	Add a control.
	setControlClass ($control_class)
	Set the class from which Options are instantiated.
	getControlClass ()
	Get the class from which Options are instantiated.
&	addChoice ($value, $label=null, $selected=false)
	Add an Option.
	getSelectedIds ()
	Get the currently selected Option IDs.
	getSelectedControls ()
	Get the currently selected Options.
	selectedCount ()
	Get the number of currently selected controls.
	select ($id)
	Select an Option by ID.
	selected ($id)
	Check whether an option is selected.
	deselect ($id)
	Deselect an Option.
	toString ()
	Returns: string
	__wakeup ()
	Initialise object after unserialisation.
	__sleep ()
	Prepare object for serialisation.
Public Attributes
	$control_name
	The name of the control.
	$id
	the unique ID of the control
	$control_class
	The class name of option elements.
	$actions
	A list of actions.
	$selected
	A list of selected control element IDs.
	$display
	Whether this control should be displayed.
	$events
	A list of supported events.