[adobe-source-commits] sandbox/visual_refactor/adobe/documentation/sources/asl adam.dox,NONE,1.1 ada

SourceForge Headquarters 1320 Columbia Street Suite 310 San Diego, CA 92101 +1 (858) 422-6466

Update of /cvsroot/adobe-source/sandbox/visual_refactor/adobe/documentation/sources/asl
In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv27679/adobe/documentation/sources/asl

Added Files:
	adam.dox adam_evaluate.dox adam_parser.dox algorithm.dox 
	array_t.dox circular_queue.dox conversion.dox 
	copy_on_write.dox counter_t.dox defgroup_libraries.dox 
	dictionary_t.dox empty_t.dox eve.dox eve_evaluate.dox 
	eve_parser.dox final.dox forest.dox functional.dox istream.dox 
	iterator.dox name_t.dox once.dox rectangle_t.dox 
	static_table.dox string.dox table_index.dox typeinfo.dox 
	value_t.dox virtual_machine_t.dox xstr.dox 
Log Message:
SO SORRY for the large qty of emails -- creating a branch for Adobe Begin refactoring.

--- NEW FILE: adam_parser.dox ---
//***************************************************************************//
//***************************************************************************//
//***************************************************************************//

/*!
\defgroup adamparser Adam Parser
\ingroup asl_libraries
*/

/*!
\fn void adobe::parse(std::istream& stream, const adobe::line_position_t& position, const adobe::adam_callback_suite_t& callbacks)
\ingroup adamparser

The Adam parsing function.

\param stream		The input stream to be parsed.
\param position		The starting line position.
\param callbacks	The callback suite used for client code communication.
*/

/*!
\fn adobe::array_t adobe::parse_adam_expression(const std::string& expression)
\ingroup adamparser

Parses an Adam expression.

\param expression The expression to be parsed in tokenized form.
*/

//***************************************************************************//
//***************************************************************************//
//***************************************************************************//

/*!
\class adobe::adam_callback_suite_t adam_parser.hpp <adobe/adam_parser.hpp>
\ingroup adamparser

\brief Callback class for the Adam parser.

Client-defined callback function used by the Adam parser to communicate with the client code. The Adam parser will discover cell declarations and will signal callbacks herein of those declarations.
*/

/*!
\typedef adobe::adam_callback_suite_t::add_cell_proc_t

A callback function signature for a \ref concept_convertible_to_function that needs to be supplied. During the parsing of an Adam definition, the client will receive cell declaration notifications through this callback.

\param type			cell type declared in the defintion.
\param cell_name	name of the cell specified.
\param position		position in the parse of the declaration.
\param expr_or_init	array of tokens representing one of several things.
\param brief		trailing comment to this cell.
\param detailed		leading comment to this cell.
*/

/*!
\typedef adobe::adam_callback_suite_t::add_interface_proc_t

A callback function signature for a \ref concept_convertible_to_function that needs to be supplied. During the parsing of an Adam definition, the client will receive interface cell declaration notifications through this callback.

\param cell_name	name of the cell specified.
\param linked		specifies if the output cell is back-linked to the input cell.
\param position1	position1 in the parse of the declaration.
\param initializer	array of tokens representing the input cell initializer.
\param position2	position2 in the parse of the declaration.
\param expression	array of tokens representing the output cell relation expression.
\param brief		trailing comment to this cell.
\param detailed		leading comment to this cell.
*/

/*!
\typedef adobe::adam_callback_suite_t::add_relation_proc_t

A callback function signature for a \ref concept_convertible_to_function that needs to be supplied. During the parsing of an Adam definition, the client will receive relation declaration notifications through this callback.

\param position			position in the parse of the relation set declaration
\param conditional		tokenized expression array representing the optional conditional enabling this relation set.
\param first			first relation in the set.
\param last				one-past-the-last relation in the set.
\param brief			trailing comment to relation set.
\param detailed			leading comment to relation set.

\sa
	\ref adobe::adam_callback_suite_t::relation_t for more information on the relation_t type.
*/

/*!
\enum adobe::adam_callback_suite_t::cell_type_t

Enumeration type denoting the kind of cell found in the parse.
*/

/*!
\var adobe::adam_callback_suite_t::cell_type_t adobe::adam_callback_suite_t::input_k

Specifies a linked input cell for the \c add_cell_proc_m callback routine. If this cell type is specified the expression in the array_t is the cell initializer.
*/

/*!
\var adobe::adam_callback_suite_t::cell_type_t adobe::adam_callback_suite_t::output_k

Specifies an output cell for the \c add_cell_proc_m callback routine. If this cell type is specified the expression in the array_t is the relation expression.
*/

/*!
\var adobe::adam_callback_suite_t::cell_type_t adobe::adam_callback_suite_t::constant_k

Specifies a constant cell for the \c add_cell_proc_m callback routine. If this cell type is specified the expression in the array_t is the cell initializer.
*/

/*!
\var adobe::adam_callback_suite_t::cell_type_t adobe::adam_callback_suite_t::logic_k

Specifies a logic cell for the \c add_cell_proc_m callback routine. If this cell type is specified the expression in the array_t is the relation expression.
*/

/*!
\var adobe::adam_callback_suite_t::cell_type_t adobe::adam_callback_suite_t::invariant_k

Specifies an invariant cell for the \c add_cell_proc_m callback routine. If this cell type is specified the expression in the array_t is the relation expression.
*/

//***************************************************************************//
//***************************************************************************//
//***************************************************************************//

/*!
\class adobe::adam_callback_suite_t::relation_t
\ingroup adamparser

\brief Struct containing details of a relation expression for client callbacks from the Adam parser.

Every relation declared in an Adam expression is parsed and packed into this struct for the client code.
*/

/*!
\var adobe::adam_callback_suite_t::relation_t::name_m

Name of the cell being operated upon by this relation.
*/

/*!
\var adobe::adam_callback_suite_t::relation_t::position_m

Position in the parse of the relation declaration.
*/

/*!
\var adobe::adam_callback_suite_t::relation_t::expression_m

Tokenized expression array of the relation.
*/

/*!
\var adobe::adam_callback_suite_t::relation_t::detailed_m

Leading comment for the relation.
*/

/*!
\var adobe::adam_callback_suite_t::relation_t::brief_m

Trailing comment for the relation.
*/

--- NEW FILE: final.dox ---
/*!
\defgroup adobe_final Final
\ingroup asl_libraries
*/

/*!
\def ADOBE_FINAL
\ingroup adobe_final

\par
A mixin class to ensure that a class cannot be derived from. The term 
"final" is a Java keyword, for which there is no C++ equivalent.

\par
See CUJ May 2001, Page 51 for more information.

\par
Credit to Shanker Chandrabose for the idea.

\author <a href="mailto:da...@ad...">Doug Ahmann</a>
\date 05/10/2001 - created

\example
\code
class foo : ADOBE_FINAL
{
};
\endcode

\example
\code
class bar { };
class foo : public bar, ADOBE_FINAL
{
};
\endcode
*/

--- NEW FILE: empty_t.dox ---
/*!
\class adobe::empty_t empty.hpp <adobe/empty.hpp>
\ingroup asl_libraries

\model_of
	- \ref concept_regular_type
	- \ref stldoc_LessThanComparable

\brief An empty regular- and less-than-comparable- type.

\rationale
	empty_t is useful for default values. For example, value_t() will construct a value_t containing an empty_t by default.
*/

--- NEW FILE: functional.dox ---
/*!
\defgroup adobe_functional Functional
\ingroup asl_libraries
*/

/*!
\class adobe::delete_ptr<T*> functional.hpp <adobe/functional.hpp>
\ingroup adobe_functional

\brief A function object for type \c T that invokes \c delete on a \c T*.

adobe::delete_ptr is similar to boost::lambda::delete_ptr except it inhereits from std::unary_function so it can also be used with boost::bind.

That requirement changes the interface so the pointer type must be provided in advance. This is as of boost 1.28. This functionality may be included in later releases of boost.
*/

/*!
\class adobe::delete_ptr<T(*)[]> functional.hpp <adobe/functional.hpp>
\ingroup adobe_functional

\brief A function object for type \c T that invokes \c delete[] on an array of \c T.

adobe::delete_ptr is similar to boost::lambda::delete_ptr except it inhereits from std::unary_function so it can also be used with boost::bind.

That requirement changes the interface so the pointer type must be provided in advance. This is as of boost 1.28. This functionality may be included in later releases of boost.
*/

/*!
\class adobe::constructor functional.hpp <adobe/functional.hpp>
\ingroup adobe_functional

\brief A function object for type \c T that constructs a new T with parameters.

adobe::constructor is similar to boost::lambda::constructor except it defines \c result_type so it can also be used with \c boost::bind. This is as of boost 1.32.0.

Also had to add the \c const \c A1 parameters to compile with CodeWarrior 9.3.
*/

/*!
\class adobe::generator_t functional.hpp <adobe/functional.hpp>
\ingroup adobe_functional

\brief A function object for value generation within a domain.
*/

/*!
\class adobe::sequence_t functional.hpp <adobe/functional.hpp>
\ingroup adobe_functional

\brief A function object for sequence generation within a domain.
*/

/*!
\defgroup compare_members Object Member Comparsion
\ingroup adobe_functional

The library provides basic function object classes for comparing two member variables between object instances.
*/

/*!
\class adobe::compare_members_t functional.hpp <adobe/functional.hpp>
\ingroup compare_members

\brief Utility class for adobe::compare_members.
*/

/*!
\fn adobe::compare_members_t<T, R, std::less<R> > adobe::compare_members(R T::* member)
\ingroup compare_members

Used to compare members in two objects of type \c T using \c std::less<R>.

\param member Name of the member to compare.

\return
	An adobe::compare_members_t which can be used to make the comparison.
*/

/*!
\fn adobe::compare_members_t<T, R, Compare> adobe::compare_members(R T::* member, Compare compare)
\ingroup compare_members

Used to compare members in two objects of type \c T using a provided comparsion function object.

\param member Name of the member to compare.
\param compare \ref concept_convertible_to_function object used for comparing the instance members.

\return
	An adobe::compare_members_t which can be used to make the comparison.
*/

/*!
\defgroup transform_member Object Member Transformation
\ingroup adobe_functional

The library provides basic function object classes for transforming a class instance into a member variable of that class.
*/

/*!
\class adobe::transform_member_t functional.hpp <adobe/functional.hpp>
\ingroup transform_member

\brief Adaptor similar to \c boost::mem_fn() used by \c boost::bind.

Unlike boost::mem_fn() this is of use when you want to use a pointer to a member and have it return a non-const reference.

\todo
	(sparent) Propose this addition back to Boost.
*/

/*!
\fn adobe::transform_member_t<T, R> adobe::make_transform(R T::* member)
\ingroup transform_member

Used to transform an object as a contained member variable.

\param member Name of the member to which to transform.

\return
	An adobe::transform_member_t which can be used to make the transformation.
*/

/*!
\class adobe::indirect_t functional.hpp <adobe/functional.hpp>
\ingroup adobe_functional

\brief Adapter used to convert pointers to references.
*/

/*!
\defgroup bitwise_operators Bitwise Operations
\ingroup adobe_functional

The library provides basic function object classes for all of the bitwise logical operators in the language.
*/

/*!
\class adobe::bitwise_or functional.hpp <adobe/functional.hpp>
\ingroup bitwise_operators

\brief \c operator() returns <code>x | y</code>.
*/

/*!
\class adobe::bitwise_and functional.hpp <adobe/functional.hpp>
\ingroup bitwise_operators

\brief \c operator() returns <code>x & y</code>.
*/

/*!
\class adobe::bitwise_xor functional.hpp <adobe/functional.hpp>
\ingroup bitwise_operators

\brief \c operator() returns <code>x ^ y</code>.
*/

--- NEW FILE: eve_parser.dox ---
/*!
\defgroup eveparser Eve Parser
\ingroup asl_libraries
*/

/*!
\typedef adobe::eve::position_t
\ingroup eveparser

Client-defined type that contains relevant client-dependent information. Passed as a parameter to the assemble_t function to denote the parent of a node being created.
*/

/*!
\typedef adobe::eve::assemble_t
\ingroup eveparser

Client-defined callback function used by the Eve parser to communicate with the client code. The Eve parser will discover view class declarations and will notify this callback of those declarations.

\param parent The parent view's position_t of the view currently being created.
\param parse_location The line position of the view currently being created.
\param name The name of the view currently being created.
\param parameters An expression which will evaluate to a dictionary_t containing the view attributes.
\param brief The contents of the trailing comment (if any) after this view class declaration
\param detailed The contents of the lead comment (if any) before this view class declaration

\return
	The client callback should return an adobe::eve::position_t, which is a user-defined type that will be propagated to any immediate children of this view class declaration (if any).
*/

/*!
\fn adobe::line_position_t adobe::eve::parse(std::istream& in, const adobe::line_position_t&, const adobe::eve::position_t&, const adobe::eve::assemble_t&)
\ingroup eveparser

The Eve parsing function.

\param in				The input stream to be parsed.
\param line_position	The starting line position.
\param position			The initial client-specific data to be used for the root view declaration(s).
\param assembler		The client-defined callback function to be called whenever a new view class declaration is encountered.

\exception adobe::stream_error_t Thrown upon parsing failure. See documentation on adobe::stream_error_t for more information about this type.

\return
	Stream position information regarding where the parse finished.
*/

--- NEW FILE: typeinfo.dox ---
/*!
\class adobe::bad_cast typeinfo.hpp <adobe/typeinfo.hpp>
\ingroup asl_libraries

\brief An exception class thrown during ASL failures to cast.

<code>adobe::bad_cast</code> is a decendant of <code>std::exception</code>. It is intended to provide detailed type information regarding the parameters into a cast that failed. If no <code>typeid()</code> information was used to construct the object, it simply relays "bad_cast".
*/

/*!
\fn adobe::bad_cast::bad_cast(const std::type_info& from, const std::type_info& to)

\param from <code>typeid()</code> result for the source object.
\param to <code>typeid()</code> result for the destination type.
*/

/*!
\fn const char* adobe::bad_cast::what() const throw()

\return
	Either:
		- The string "bad_cast"
		- A string detailing the source and destination types that could not be cast successfully.
*/

--- NEW FILE: array_t.dox ---
/*!
\class adobe::array_t array.hpp <adobe/array.hpp>
\ingroup asl_libraries

\brief A copy-on-write array of <code>adobe::value_t</code>.

array_t is an array of heterogeneous types. array_t is copy-on-write, intended for usage where copies are frequent, but writing is infrequent. Constructing an empty array will never throw an exception - no allocations are required until something is stored into it. Likewise, copying with assignment or copy constructor will not throw.

\model_of
	- \ref concept_regular_type

\note
	When copy-on-write semantics are not important, it is advised to use <code>std::vector<adobe::value_t></code> or another container type instead of array_t.

\note
	\anchor _1 [1] Because an array_t is copy-on-write, modifications through an iterator are not supported except via back_insert_iterator.

\tutorial
	A tutorial for \ref asl_tutorials_array_t is available.
*/

/*!
\typedef adobe::array_t::size_type
An unsigned integral type.
*/

/*!
\typedef adobe::array_t::difference_type
A signed integral type.
*/

/*!
\typedef adobe::array_t::value_type
The type of object, <code>adobe::value_t</code>, stored in the <code>array_t</code>.
*/

/*!
\typedef adobe::array_t::reference
Reference to <code>adobe::value_t</code>.
*/

/*!
\typedef adobe::array_t::const_reference
Const reference to <code>adobe::value_t</code>.
*/

/*!
\typedef adobe::array_t::pointer
Pointer to <code>adobe::value_t</code>.
*/

/*!
\typedef adobe::array_t::const_pointer
Const pointer to <code>adobe::value_t</code>.
*/

/*!
\typedef adobe::array_t::iterator
A random access iterator for the array \ref _1 "[1]".
*/

/*!
\typedef adobe::array_t::const_iterator
Equivalent to <code>array_t::iterator</code>.
*/

/*!
\typedef adobe::array_t::reverse_iterator
A reverse iterator into the array \ref _1 "[1]".
*/

/*!
\typedef adobe::array_t::const_reverse_iterator
Equivalent to <code>array_t:: reverse_iterator</code>.
*/

/*!
\fn adobe::array_t::array_t(size_type n, const value_t& item)

Initializes the array_t with <code>n</code> items of value <code>item</code>.
*/

/*!
\fn adobe::array_t::const_reference adobe::array_t::at(adobe::array_t::size_type index) const

\param index The index at which the element to be referenced resides.

\note
	Identical semantics to operator[]().

\return
	A const_reference to the element specified.
*/

/*!
\fn adobe::array_t::const_reference adobe::array_t::operator[](adobe::array_t::size_type index) const

\param index The index at which the element to be referenced resides.

\note
	Identical semantics to at().

\return
	A const_reference to the element specified.
*/

/*!
\fn T adobe::array_t::get(adobe::array_t::size_type index) const

\param index The index at which the element to be referenced resides.

\return
	A copy of the element at the specified index.

\exception
	std::exception Throws when the index is out-of-range.
*/

/*!
\fn void adobe::array_t::get(adobe::array_t::size_type index, T& value) const

\param index The index at which the element to be referenced resides.
\param value Assigned the result if successful. Otherwise, <code>value</code> is untouched.

\exception
	None. Guaranteed not to throw.
*/

/*!
\fn adobe::array_t::const_reference adobe::array_t::front() const

\return
	A const_reference to the first element in the array.
*/

/*!
\fn adobe::array_t::const_reference adobe::array_t::back() const

\return
	A const_reference to the last element in the array. Note this returns a different element than end().
*/

/*!
\fn adobe::array_t::write_reference adobe::array_t::write()

\return
	A write_reference to the array.

\note
	copy_on_write semantics mandate a copy of the internal implementation if it is being shared.
*/

/*!
\fn adobe::array_t::array_t& adobe::array_t::set(adobe::array_t::size_type index, const T& value)

\param index The index at which the element to be modified resides.
\param value The value to which the element at <code>index</code> is assigned.

\return
	A new array; a duplicate of this one with the new value set at index <code>index</code>.
*/

/*!
\fn adobe::array_t::array_t& adobe::array_t::push_back(const T& value)

\param value The value to be appended to the end of the array.

\return
	A new array; a duplicate of this one with this value appended.
*/

/*!
\fn bool adobe::array_t::empty() const

\return
	<code>true</code> if the array is void of elements, <code>false</code> otherwise.
*/

/*!
\fn adobe::array_t::size_type adobe::array_t::size() const

\return
	A count of the number of elements in the array.
*/

/*!
\fn adobe::array_t::size_type adobe::array_t::max_size() const

\return
	Number of elements allowed to be added to the array before a memory reallocation is required.
*/

/*!
\fn void adobe::array_t::resize(adobe::array_t::size_type n, const value_t& c)

\param n Number of elements to resize the array to.
\param c Value to which all new elements are initialized.
*/

/*!
\fn void adobe::array_t::assign(adobe::array_t::size_type n, const value_t& c)

\todo (fbrereto) Detail parameters
*/

/*!
\fn size_type adobe::array_t::erase(adobe::array_t::size_type x)

\param x index of the element to be removed.

\todo (fbrereto) Detail return
*/

/*!
\fn void adobe::array_t::pop_back()

Erases the last element in the array.
*/

/*!
\fn void adobe::array_t::clear()

Resets the array's internals to a default state.

\note
	This will not guarantee destruction of the elements formerly contained within the array, as other arrays may also be referring to them.
*/

/*!
\fn adobe::array_t::const_iterator adobe::array_t::begin() const

\return
	An iterator to the first element in the array
*/

/*!
\fn adobe::array_t::const_iterator adobe::array_t::end() const

\return
	An iterator to one past the last element in the array
*/

/*!
\fn adobe::array_t::const_reverse_iterator adobe::array_t::rbegin() const

\return
	An iterator to one past the last element in the array
*/

/*!
\fn adobe::array_t::const_reverse_iterator adobe::array_t::rend() const

\return
	An iterator to the first element in the array
*/

/*!
\fn adobe::array_t::back_insert_iterator adobe::array_t::back_inserter()

\return
	An insert iterator into the array allowing for backside appending of new elements.
*/

/*!
\fn bool adobe::array_t::identity(const array_t& x) const

\param x Array to compare this array against.

\return
	<code>true</code> if this array and the argument refer to the same copy_on_write instance; <code>false</code> otherwise.

\note
	This is not the same as <code>operator==</code>. This function will return <code>false</code> if the arrays are identical but do not refer to the same implementation instance.
*/

/*!
\fn bool adobe::array_t::unique_instance() const

\return
	<code>true</code> if this array is the only one referrring to its implementation instance (i.e., the implementation instance is currently not being shared). <code>false</code> otherwise.
*/

/*!
\class adobe::array_t::back_insert_iterator array.hpp <adobe/array.hpp>
\ingroup asl_libraries

\brief a back insert iterator for appending to array_t.

Assignment through a <code>back_insert_iterator</code> will insert an object after the last element of an <code>array_t</code>.

\model_of
	- \ref output_iterator
*/

--- NEW FILE: adam_evaluate.dox ---
//***************************************************************************//
//***************************************************************************//
//***************************************************************************//

/*!
\fn adobe::adam_callback_suite_t adobe::bind_to_sheet(adobe::sheet_t&)
\ingroup adamparser

\param sheet the sheet to be bound to this parse of an adam file
\return A callback suite for the parser to communicate to the sheet
*/

--- NEW FILE: value_t.dox ---
/*!
\class adobe::value_t value.hpp <adobe/value.hpp>
\ingroup asl_libraries

\brief A descriminated type for single values.

\model_of
	- \ref concept_regular_type

\details
\par Type Promotion
	\c adobe::value_t leverages <code>adobe::promote</code> while storing instance values. This is an exception to the discriminating union concept to which \c adobe::value_t adheres.

\par Getting a Value
	\c adobe::value_t uses <code>get<>()</code> to get its instance value. It behaves like an explicit cast and an assignment: getting a value_t out will always succeed and simply returns the same value_t.

\par Setting a Value
	\c adobe::value_t uses <code>set<>()</code> to set its instance value. It behaves like an explicit cast and an assignment: putting a value_t into a value_t simply assigns the values; it does not wrap them.

\par How does adobe::value_t differ from boost::any?
	value_t differs from <a href="http://www.boost.org/doc/html/any.html"><code>boost::any</code></a> in several ways:
		- value_t models \ref stldoc_EqualityComparable, fully modeling a \ref concept_regular_type.
		- value_t supports type promotion. See <code>adobe::promote</code> for more details.
		- get<>() results are returned by reference, making value_t generally more efficient.

\tutorial
	A tutorial for \ref asl_tutorials_value_t is available.
*/

/*!
\fn adobe::value_t::value_t(const T& x)

\param x Value to copy as the instance value of this object.

\note
	What is stored is a copy of <code>x</code> promoted to <code>promote<T>::type</code>.
*/

/*!
\fn const typename promote<T>::type& adobe::value_t::get() const

\return
	A refernce to a promoted type for <code>T</code> containing the <code>value_t</code>'s instance value.

\exception
	adobe::bad_cast Thrown if <code>adobe::promote<T></code> does not match the stored instance type.
*/

/*!
\fn typename promote<T>::type& adobe::value_t::get()

\return
	A refernce to a promoted type for <code>T</code> containing the <code>value_t</code>'s instance value.

\exception
	adobe::bad_cast Thrown if <code>adobe::promote<T></code> does not match the stored instance type.
*/

/*!
\fn bool adobe::value_t::get(T& x) const

\param
	x Value that will be set to the value stored in the value_t.

\return
	<code>true</code> if x was set successfully, <code>false</code> otherwise.

\exception
	Undefined Will relay anything thrown by <code>x.operator=()</code>.
*/

/*!
\fn adobe::value_t& adobe::value_t::set(const T& x)

\param x The new value to assign to this value_t.

\return
	The value_t with its new value set.
*/

/*!
\fn const std::type_info& adobe::value_t::type() const

\return
	The information returned by <code>typeid()</code> for the instance value.
*/

/*!
\class adobe::value_t::transform value.hpp <adobe/value.hpp>
\ingroup asl_libraries

\brief Function object used in binding for instance value access.
*/

/*!
\typedef adobe::value_t::transform::result_type

The promoted value type from T that will be returned by this function object's <code>operator()</code>s.
*/

/*!
\typedef adobe::value_t::transform::argument_type

Parameter type required by this function object's <code>operator()</code>s.
*/

/*!
\fn promote<T>::type& adobe::value_t::transform::operator()(value_t &x) const

\param x The value from which the result is to be obtained.

\return
	A reference to the instance value stored in this value_t.
*/

/*!
\fn const promote<T>::type& adobe::value_t::transform::operator()(const value_t &x) const

\param x The value from which the result is to be obtained.

\return
	A reference to the instance value stored in this value_t.
*/

--- NEW FILE: copy_on_write.dox ---
//***************************************************************************//
//***************************************************************************//
//***************************************************************************//

/*!
\class adobe::copy_on_write copy_on_write.hpp <adobe/copy_on_write.hpp>
\ingroup asl_libraries

\brief A wrapper class enabling copy on write semantics for a type.

\model_of
	- \ref concept_regular_type

\rationale
Copy on write semantics treat an object such that a copying becomes "lazy", that is, a copy of an object will only take place when absolutely necessary. This happens whenever the value is written to, hence the name "copy on write". Internally the object stores a reference count to a commonly shared element, and copies the element off at write time. If there is only one copy_on_write object referencing that element, no copies are made at write time.

\note
The copy_on_write class is thread safe when compiled with BOOST_HAS_THREADS defined.
*/

/*!
\typedef adobe::copy_on_write::value_type

\brief A typedef of the type T used as the underlying value type of this object.
*/

/*!
\fn adobe::copy_on_write::copy_on_write(const value_type& x)

\brief Constructs a new copy_on_write object with a value <code>x</code>.

\param x A default value to assign to this object
*/

/*!
\fn adobe::copy_on_write::copy_on_write(const copy_on_write& x)

\brief Constructs a new copy_on_write object using another copy_on_write object as its value.

\param x Right hand side element to duplicate
*/

/*!
\fn value_type& adobe::copy_on_write::write()

\brief Obtain a reference to the object the object is referencing. This will copy the underlying value (if necessary) so changes to the value do not affect other copy_on_write objects.

\return A reference to the underlying object
*/

/*!
\fn adobe::copy_on_write::operator const value_type&() const

\brief Obtain a reference to the underlying object.

\return A reference to the underlying object
*/

/*!
\fn const value_type& adobe::copy_on_write::operator*() const

\brief Obtain a reference to the underlying object.

This is provided because you cannot override <code>operator . ()</code>. It allows copy_on_write to be used with common transformation techniques, such as boost <code>indirect_iterator</code> and <code>transform_iterator</code>. It does not imply "pointer" semantics.

\return A reference to the underlying object
*/

/*!
\fn const value_type* adobe::copy_on_write::operator->() const

\brief Obtain a pointer to the underlying object.

This is provided because you cannot override <code>operator . ()</code>. It allows copy_on_write to be used with common transformation techniques, such as boost <code>indirect_iterator</code> and <code>transform_iterator</code>. It does not imply "pointer" semantics.

\return A pointer to the underlying object
*/

/*!
\fn bool adobe::copy_on_write::unique_instance() const

\brief unique_instance returns whether or not the reference count to the object instance is one. This is useful if you want to determine if writing will cause a copy.

\return Boolean; <code>true</code> if the ref count for the instance is one.
*/

/*!
\fn bool adobe::copy_on_write::identity(const copy_on_write< T > &x) const

\brief identity is used to see if two copy_on_write items refer to the same instance.

\return Boolean; <code>true</code> if the underlying object instance is shared by both objects.
*/

/*!
\fn adobe::copy_on_write& adobe::copy_on_write::operator=(const adobe::copy_on_write& x)

\return a reference to this object.
*/

--- NEW FILE: eve.dox ---
/*!
\defgroup eve_engine Eve
\ingroup asl_libraries
*/

//***************************************************************************//
//***************************************************************************//
//***************************************************************************//

/*!
\class adobe::eve_t eve.hpp <adobe/eve.hpp>
\ingroup eve_engine

\brief Eve engine.
*/

/*!
\typedef adobe::eve_t::debug_frame_proc_t

\ref concept_convertible_to_function type used for debugging eve layouts.

\sa
	\ref adobe::eve_t::set_debug_frame_proc()
\sa
	\ref adobe::eve_t::do_framing()

*/

/*!
\enum adobe::eve_t::alignment_t

Specifies the alignment of a view along the horizontal or vertical axis relative to its parent view.

\note
	Locale support for direction is not implemented yet.
*/

/*!
\var adobe::eve_t::alignment_t adobe::eve_t::align_default

(Horizontal and vertical) default alignment.
*/

/*!
\var adobe::eve_t::alignment_t adobe::eve_t::align_forward

(Horizontal and vertical) aligned in-order relative to current locale settings.
*/

/*!
\var adobe::eve_t::alignment_t adobe::eve_t::align_reverse

(Horizontal and vertical) aligned in reverse order relative to current locale settings.
*/

/*!
\var adobe::eve_t::alignment_t adobe::eve_t::align_center

(Horizontal and vertical) aligned centered.
*/

/*!
\var adobe::eve_t::alignment_t adobe::eve_t::align_proportional

(Horizontal and vertical) extra space in the parent container's layout is distributed evenly among those with this alignment.
*/

/*!
\var adobe::eve_t::alignment_t adobe::eve_t::align_fill

(Horizontal and vertical) the dimensions of this view are expanded to consume all extra space on either side of this view.
*/

/*!
\var adobe::eve_t::alignment_t adobe::eve_t::align_left

(Horizontal) left-alignment. Changes with the current locale.
*/

/*!
\var adobe::eve_t::alignment_t adobe::eve_t::align_right

(Horizontal) right-alignment. Changes with the current locale.
*/

/*!
\var adobe::eve_t::alignment_t adobe::eve_t::align_top

(Vertical) top-alignment. Changes with the current locale.
*/

/*!
\var adobe::eve_t::alignment_t adobe::eve_t::align_bottom

(Vertical) bottom-alignment. Changes with the current locale.
*/

/*!
\enum adobe::eve_t::placement_t

Specifies the placement of child views inside their containing view.
*/

/*!
\var adobe::eve_t::placement_t adobe::eve_t::place_leaf

This view is a leaf node and has no children.
*/

/*!
\var adobe::eve_t::placement_t adobe::eve_t::place_column

Children are to be stacked in a column in the parent view.
*/

/*!
\var adobe::eve_t::placement_t adobe::eve_t::place_row

Children are to be lined up in a row in the parent view.
*/

/*!
\var adobe::eve_t::placement_t adobe::eve_t::place_overlay

Intended for use when two or more widgets are to occupy the same screen real estate at mutually exclusive times. In this instance the immediate children of the parent whose placement is set to overlay have their vertical and horizontal alignments set to align_fill.
*/

/*!
\var adobe::eve_t::placement_t adobe::eve_t::place_row_forced_left_to_right

Forces alignement of the children views from left to right. Locale independent.

\todo (sparent) : Unimplemented
*/

/*!
\enum adobe::eve_t::evaluate_options_t

Specifies the coordinate system origin for the place_data_t of a given view.
*/

/*!
\var adobe::eve_t::evaluate_options_t adobe::eve_t::evaluate_nested

Specifies the origin of the coordinate system to be the top left point of the parent view.
*/

/*!
\var adobe::eve_t::evaluate_options_t adobe::eve_t::evaluate_flat

Specifies the origin of the coordinate system to be the top left point of the topmost view in the hierarchy.
*/

/*!
\fn adobe::eve_t::iterator adobe::eve_t::add_view_element(const adobe::eve_t::iterator& parent, const adobe::eve_t::insert_element_t& element)

\par
Adds a new view element to the view hierarchy being formed for layout.

\param parent the parent of this view. Specify a default-constructed adobe::eve_t::iterator if this view is to be the topmost view. There can only be one topmost view when Eve goes to solve for the layout.
\param element details on the element being appended at this node, including callbacks specific to this node that will be used when Eve wants to communicate with the client regarding this specific view.

\return
An opaque adobe::eve_t::iterator, which can be used as the <code>parent</code> parameter in another call to add_view_element to place subviews inside this one.
*/

/*!
\fn void adobe::eve_t::evaluate(adobe::eve_t::evaluate_options_t options)

\par
Hands the constructed view tree over to the Eve engine to solve for the layout. All elements should be added (with add_view_element) before this call is invoked.

\param options options to be passed to the solution engine.

\sa
	\ref adobe::eve_t::evaluate_options_t
*/

/*!
\fn void adobe::eve_t::adjust(long width, long height, adobe::eve_t::evaluate_options_t options)

\par
Adjusts the solved view layout to fit within the nely specified dimensions. Eve will relay the new solved layout information to individual widgets through thier place() callbacks.

\param width the new width for the view layout.
\param height the new height for the view layout.
\param options options to be passed to the solution engine.

\sa
	\ref adobe::eve_t::evaluate_options_t
*/

/*!
\fn void adobe::eve_t::set_debug_frame_proc(const adobe::eve_t::debug_frame_proc_t& proc)

\par
This function is one of two for debugging purposes. Only one callback function is retained per Eve instance, and can be overwritten any time.

\param proc the callback function Eve will notify of the widget boundaries it calculated.
*/

/*!
\fn void adobe::eve_t::do_framing()

\par
This function is the second of two for debugging purposes. After the layout of a view has been calculated completely, a client of the Eve engine can set a framing callback with set_debug_frame_proc, then have Eve notify that proc with this function call. Each widget's placement data will be send to the callback specified.
\par
One very practical use for this function in debugging is drawing the boundaries on the screen directly over the human interface. This will reveal misalignments between where the widgets laid out versus where Eve placed them ideally.
*/

//***************************************************************************//
//***************************************************************************//
//***************************************************************************//

/*!
\class adobe::eve_t::insert_element_t eve.hpp <adobe/eve.hpp>
\ingroup eve_engine

\brief Data type for detailing view node insertion into the engine.
*/

/*!
\var adobe::eve_t::insert_element_t::is_container_type_m

Specifies whether or not the new node is to be a container view or not, irrespective of whether or not it will actually contain subviews.
*/

/*!
\var adobe::eve_t::insert_element_t::parameters_m

Specifies default parameters by which the view is to be initialized.

\par Available Parameter Keys
<table width="100%" border="1">
	<tr><th>Name</th><th>Possible Values</th><th>Default</th><th>Notes</th></tr>
	<tr>
		<td><code>child_horizontal</code></td>
		<td>Any of the adobe::eve_t::alignment_t enumeration labels as an adobe::name_t</td>
		<td><code>align_default</code></td>
		<td></td>
	</tr>
	<tr>
		<td><code>child_vertical</code></td>
		<td>Any of the adobe::eve_t::alignment_t enumeration labels as an adobe::name_t</td>
		<td><code>align_default</code></td>
		<td></td>
	</tr>
	<tr>
		<td><code>guide_mask</code></td>
		<td>array containing any of [ guide_baseline, guide_label ]</td>
		<td>empty (no suppression)</td>
		<td>Suppression of horizontal and/or vertical guides</td>
	</tr>
	<tr>
		<td><code>horizontal</code></td>
		<td>Any of the adobe::eve_t::alignment_t enumeration labels as an adobe::name_t</td>
		<td><code>align_default</code></td>
		<td></td>
	</tr>
	<tr>
		<td><code>indent</code></td>
		<td>integer</td>
		<td>0</td>
		<td></td>
	</tr>
	<tr>
		<td><code>placement</code></td>
		<td>Any of the adobe::eve_t::placement_t enumeration labels as an adobe::name_t</td>
		<td><code>place_leaf</code></td>
		<td></td>
	</tr>
	<tr>
		<td><code>spacing</code></td>
		<td>array of integers</td>
		<td><code>[ 0 ]</code></td>
		<td>A single value here will propagate for all needed spacing values</td>
	</tr>
	<tr>
		<td><code>vertical</code></td>
		<td>Any of the adobe::eve_t::alignment_t enumeration labels as an adobe::name_t</td>
		<td><code>align_default</code></td>
		<td></td>
	</tr>
</table>
*/

/*!
\var adobe::eve_t::insert_element_t::signals_m

Specifies a suite of \ref concept_convertible_to_function callbacks Eve will use to communicate with the client.

\sa
	\ref adobe::eve_t::signal_suite_t
*/

//***************************************************************************//
//***************************************************************************//
//***************************************************************************//

/*!
\class adobe::eve_t::calculate_data_t eve.hpp <adobe/eve.hpp>
\ingroup eve_engine

\brief Eve data interface from the client to the engine.

\par
\image html calculate_data_t.jpg calculate_data_t slice-independent widget geometry

\todo
	(sparent) : We have a mechanism for defaulting container attributes. This needs to be extended to view attributes such as supressing guides.
*/

/*!
\var adobe::eve_t::calculate_data_t::spacing_m

\par
spacing is the amount of space between children. Because the spacing vector is used to determine spacing between children, for a container with <code>N</code> children only the first <code>N-1</code> spacing values will be used. If the spacing vector has a single element, that value is used for all spacing between all children. This only applies to container widgets.
*/

/*!
\var adobe::eve_t::calculate_data_t::placement_m

\par
placement is the enumeration denoting the orientation children will have with respect to one another when being laid out.

\sa
	\ref adobe::eve_t::placement_t
*/

/*!
\var adobe::eve_t::calculate_data_t::slice_m

\par
This array contains the orientation-specific geometry for the widget in the two relative orientations (horiztonal and vertical).

\sa
	\ref adobe::eve_t::calculate_data_t::slice_t
*/

/*!
\var adobe::eve_t::calculate_data_t::indent_m

\par
indent is a cross-stream value denoting the amount of indent for this single value. Cross-stream means that it is a value perpendicular to the orientation of the slice in which it is defined. Therefore, the horizontal indent is the amount in which the widget will be moved down vertically inside its parent.
*/

/*!
\var adobe::eve_t::calculate_data_t::create_m

\par
create is a boolean denoting whether or not this widget will actually exist as a UI framework. If <code>false</code>, this widget's geometry will affect the view layout but will not send a <code>place</code> call through the widget signal suite. Noncreating views such as <code>row</code> and <code>column</code> are good examples of widget types whose <code>create_m</code> is <code>false</code>.

\sa
	\ref adobe::eve_t::signal_suite_t
*/

//***************************************************************************//
//***************************************************************************//
//***************************************************************************//

/*!
\class adobe::eve_t::calculate_data_t::slice_t eve.hpp <adobe/eve.hpp>
\ingroup eve_engine

\brief Widget geometry for a single orientation of eve_t::calculate_data_t.

\par
\image html calculate_data_t_slice_t.jpg calculate_data_t::slice_t widget geometry for the horizontal orientation

\par
The above is a diagram detailing a widget's geometry for a the horizontal orientation. The vertical orientation is similar but runs top-to-bottom instead of left-to-right.
*/

/*!
\var adobe::eve_t::calculate_data_t::slice_t::length_m

\par
length is the "active content" of the widget, and is also the space in which child widgets are allowed. In a container this the minimum allowable size of the container- Eve will then grow the container to contain its children if need be. Therefore, the typical value for this variable for a container is zero.
*/

/*!
\var adobe::eve_t::calculate_data_t::slice_t::outset_m

\par
outset is a pair of values- one for either end of the slice. An outset represents an outer boundary of space taken up graphically by the widget, but is not considered when the functionality of the widget is concerned. The outset is bounded on the inside by the outside of the widget frame. An example of something defined by an outset would be a drop shadow. Outsets are allowed to bleed into the whitespace of the owning view (insets and spacings, but not margins), and if any outsets are left over they propagate to the parent view.
*/

/*!
\var adobe::eve_t::calculate_data_t::slice_t::inset_m

\par
inset is a pair of values- one for either end of the slice. An inset represents an inner boundary of space taken up graphically by the widget, but is not considered when the functionality of the widget is concerned. An inset is bounded on the outside by the inside of the widget frame. An (seemingly nonsensical) example of something defined by the inset would be a drop shadow internal to the bounds of the window.

\note
	inset is not implemented yet.
*/

/*!
\var adobe::eve_t::calculate_data_t::slice_t::frame_m

\par
frame is a pair of values- one for either end of the slice. A frame represents a border around the widget. An example of such would be the grow-frame around a typical window in the Windows operating system. A frame is surrounded by the outset of the widget on the outside and the inset of the widget on the inside.
*/

/*!
\var adobe::eve_t::calculate_data_t::slice_t::margin_m

\par
margin is a pair of values- one for either end of the slice. A margin represents a border around the children of this widget. Thus, this value only applies to container widgets. Margins are similar to insets except they cannot be "bled into" by subchildren outsets.
*/

/*!
\var adobe::eve_t::calculate_data_t::slice_t::alignment_m

\par
alignment specifies the relationship of this widget to its parent along this orientation.

\sa
	\ref adobe::eve_t::alignment_t
*/

/*!
\var adobe::eve_t::calculate_data_t::slice_t::child_alignment_m

\par
child_alignment attempts to specify the alignment of the children contained inside this widget for this orientation. This alignment value will be applied to all immediate children of this widget who have no overriding alignment value of their own (that is, their alignment is <code>align_default</code>).

\sa
	\ref adobe::eve_t::alignment_t
*/

/*!
\var adobe::eve_t::calculate_data_t::slice_t::guides_m

\par
guides are a vector of values relaying internal "points of interest" from the widget to the Eve engine so that these points in other widgets may "snap" into co-alignment. An example of something using guides would be colon-alignment (horizontal case) or baseline-alignment (vertical case). Note that the guides in a slice affect the position of the widget along the other orientation: to specify a horizontal guide point is to allow the widget to be shifted vertically to align with other horizontal guide points.
*/

/*!
\var adobe::eve_t::calculate_data_t::slice_t::suppress_m

\par
suppress handles the propagation of guide points from the children in this widget to the parent of this widget. If suppress is <code>true</code> then guides are "clipped" at this widget and the parent of this widget does not see guide point information about any of the children contained within.

\todo
	(sparent) Currently only implemented cross stream
*/

//***************************************************************************//
//***************************************************************************//
//***************************************************************************//

/*!
\class adobe::eve_t::place_data_t eve.hpp <adobe/eve.hpp>
\ingroup eve_engine

\brief Eve data interface from the engine to the client.

\par
The place_data_t is the primary communication mechanism Eve uses to get solved layout information to the client. The place_data_t is similar to the calculate_data_t, except for the following:
	- data included is the "solved" result, not the data the client passed in (though the solution is based on the client's data)
	- data included is only pertinent to the laying-out of the widget into it's final resting place.
\par
This struct is used when calling the place signal inside the widget's related place signal.

\sa
	\ref adobe::eve_t::signal_suite_t
*/

//***************************************************************************//
//***************************************************************************//
//***************************************************************************//

/*!
\class adobe::eve_t::place_data_t::slice_t eve.hpp <adobe/eve.hpp>
\ingroup eve_engine

\brief Element geometry for a single orientation of eve_t::place_data_t.
*/

/*!
\var adobe::eve_t::place_data_t::slice_t::length_m

\par
length is the "active content" of the widget, and is also the space in which child widgets will be placed (if there are any).
*/

/*!
\var adobe::eve_t::place_data_t::slice_t::position_m

\par
position is a point representing the top-left corner of the widget. The point can either be relative to the top-left point of the topmost view or the top-left point of the parent view depending on which option was specified to Eve at layout time.

\sa
	\ref adobe::eve_t::evaluate_options_t
*/

/*!
\var adobe::eve_t::place_data_t::slice_t::outset_m

\par
outset is the same as the outset value described in \ref adobe::eve_t::calculate_data_t::slice_t::outset_m. However because the outset can bleed through a parent widget, it is possible for the outset of any given widget to change during layout. Therefore this calculated outset value is returned to the client for proper placement of outset-affected widgets.
*/

/*!
\var adobe::eve_t::place_data_t::slice_t::guides_m

\par
guides are the same as the guides values described in \ref adobe::eve_t::calculate_data_t::slice_t::guides_m. However now the values have been modified to coincide with other guide values presented to the engine. These guide values will ensure points of interest in this widget will "snap" to points of interest in other widgets.
*/

//***************************************************************************//
//***************************************************************************//
//***************************************************************************//

/*!
\class adobe::eve_t::signal_suite_t eve.hpp <adobe/eve.hpp>
\ingroup eve_engine

\brief Eve function interface between the engine and the client.
*/

/*!
\var adobe::eve_t::signal_suite_t::eve_container_defaults_proc_m

\par
The container defaults proc is the first function called for a widget. It is only called when the widget is specified as being a container (whether or not it actually will contain children). This callback allows the client to set default container information about this type of widget before overrides are applied to it (by the parameters passed in or by other widgets imposing themselves on the container. Widget-specific measurements are not applied here: they should be calculated during the calculate callback proc.
*/

/*!
\var adobe::eve_t::signal_suite_t::eve_calculate_proc_m

\par
The calculate proc is the time when the engine gets the widget-specific information from the client. The client is allowed to modify the calculate_data_t parameter passed in as they please in order to best describe the geometric details of this widget. This is the second (first if the widget is not a container) proc called while Eve is solving the layout.
*/

/*!
\var adobe::eve_t::signal_suite_t::eve_calculate_vertical_proc_m

\par
Sometimes a widget's height is dependent upon the solved width of that widget. An example of this would be a widget with paginated text inside of it. In that case, the widget should provide a callback here to remeasure just the vertical slice information for the widget. All other information modified here will be discarded in favor of the values given during the first calculate call.
*/

/*!
\var adobe::eve_t::signal_suite_t::eve_place_proc_m

\par
Place is the final callback signaled from the Eve engine to a widget. When this callback is made there are several guarantees for the client:
	- All parent views for this widget have already had their place callback signalled
	- All data provided in the place_data_t is the final geometric information for the widget.
\par
	Note that this callback can be signalled multiple times- given a view re-layout (i.e. during a window resize event) the other callbacks will not be signalled- the layout will be adjusted internally in the Eve engine and only this callback will be signalled with updated placement information for the widget.
*/

//***************************************************************************//
//***************************************************************************//
//***************************************************************************//

/*!
\fn void adobe::set_margin(adobe::eve_t::calculate_data_t& container, long x)
\ingroup eve_engine

Quick way of setting every margin in a container to a single size.

\param container geography for a container
\param x value to which the margins should be set
*/

--- NEW FILE: name_t.dox ---
/*!
\class adobe::name_t name.hpp <adobe/name.hpp>
\ingroup asl_libraries

\brief A character string class for immutable strings.

A name_t is a string class for immutable strings. The storage for name_t is globally pooled and strings are reused. Although an adobe::name_t can be somewhat expensive to construct, copying assignment, and equality comparisons are very fast. Because strings are reused, the pointer returned from name_t::get() can be used for indexing.

\par Model Of:
	- \ref concept_regular_type
	- \ref stldoc_LessThanComparable
	- \ref concept_convertible_to_bool

\par Rationale:

\note
The name_t class is thread safe when compiled with BOOST_HAS_THREADS defined.

\todo
The complexity of construction of a name_t is currently O(log(n)). An efficient hash implementation may improve efficiency.

\todo
Serialization support for name_t is not complete, but can be enabled by defining ADOBE_SERIALIZATION.
*/

/*!
\fn adobe::name_t::name_t(const char* string_name = "")

Constructs a name_t associated with string_name. If this is the first instance of this string, then the string will be copied to a pool with static storage duration.

\pre \c string_name is a '\\0' terminated character sequence.
*/

/*!
\fn adobe::name_t::name_t(const char* string_name, std::size_t length)

Constructs a name_t associated with string_name. If this is the first instance of this string, then the string will be copied to a pool with static storage duration.

\pre <code> [string_name, string_name + length) </code> is a sequence of non '\\0' characters.
*/

/*!
\fn const char* adobe::name_t::get() const throw()

Returns the associated '\\0' terminated string.

\return a character pointer, guaranteed identical for equivalent strings.

\par Semantic Requirements:
The pointer returned is guaranteed identical for equivalent strings. i.e. <code>assert(name_t("test").get() == name_t("test").get());</code>
*/

/*!
\class adobe::static_name_t name.hpp <adobe/name.hpp>
\ingroup asl_libraries

\brief Utility wrapper to construct name_t with strings of static storage duration.

\promotes_to
	adobe::name_t
*/

/*!
\fn adobe::static_name_t::static_name_t(const char* string_name = "")

Constructs a static_name_t associated with string_name. The string will not be copied to the pool, however, it is not guaranteed that the associated string will be the identity of string_name.

\pre \c string_name is a '\\0' terminated character sequence.
\pre \c string_name is immutable, and has static storage duration \ref note_1 "[1]".

\note
\anchor note_1 [1] C++ Standard, second edition, (ISO/IEC 14882, 2003-04-01), section 3.7.1.
*/

/*!
\class adobe::once_name_t name.hpp <adobe/name.hpp>
\ingroup asl_libraries

\brief Utility wrapper to construct name_t without initializing the string pointer.

\promotes_to
	adobe::name_t

\rationale
	The primary purpose of once_name_t is to provide a name_t implementation that can be used in a multithreaded environment as a static variable. Because its construction does nothing to initialize the value of the name_t, such initialization must take place during a threadsafe intialization function (boost::call_once, for instance).
*/

/*!
\fn adobe::once_name_t::once_name_t()

Constructs a name_t without pointing the name to a valid string.
*/

--- NEW FILE: rectangle_t.dox ---
//***************************************************************************//
//***************************************************************************//
//***************************************************************************//

/*!
\class adobe::rectangle_t rectangle.hpp <adobe/rectangle.hpp>
\ingroup asl_libraries

\brief An intrinsic geometry class for objects with a graphical representation.

rectangle_t is a totally ordered class for storing intrinsic geometry about a graphical element. Each rectangle_t is comprised of two slices. A slice stores intrinsic geometry about a graphical element for in a single direction, either vertically or horizontally.

\model_of
	- \ref concept_regular_type

\rationale
	rectangle_t is intended to describe only the properties of a graphical element which it retains intrinsically. Properties that involve an element as it relates to another element (like position) should not be described here. This is intended to separate the notions of intrinsic versus extrinsic values. This seems strange at first, but is justified when considering how to make a copy of an element's geometry: the copy will not have the same relationships as the original, so extrinsic values cannot be copied, nor can they be set to default values because there is no relationship to which they relate. Any extrinsic value in that case is equally meaningless.

\todo
	(fbrereto) We need a better name than rectangle_t
\todo
	(fbrereto) We need a better name than points_of_interest_t

*/

/*!
\var boost::array<adobe::rectangle_t::slice_t, 2> adobe::rectangle_t::slice_m

The two slices that comprise this rectangle.
*/

/*!
\fn long& adobe::rectangle_t::height()

\return a reference to length_m in the vertical slice.
*/

/*!
\fn long& adobe::rectangle_t::width()

\return a reference to length_m in the horizontal slice.
*/

/*!
\fn const long& adobe::rectangle_t::height() const

\return a reference to length_m in the vertical slice.
*/

/*!
\fn const long& adobe::rectangle_t::width() const

\return a reference to length_m in the horizontal slice.
*/

//***************************************************************************//
//***************************************************************************//
//***************************************************************************//

/*! \class adobe::rectangle_slices_t rectangle.hpp <adobe/rectangle.hpp>
\ingroup asl_libraries

\brief A utility class for referencing the two slices of a rectangle_t.
*/

/*!
\var adobe::rectangle_slices_t::horizontal

An index used to reference the horizontal rectangle_t::slice_t in a rectangle_t.
*/

/*!
\var adobe::rectangle_slices_t::vertical

An index used to reference the vertical rectangle_t::slice_t in a rectangle_t.
*/

//***************************************************************************//
//***************************************************************************//
//***************************************************************************//

/*! \class adobe::rectangle_t::slice_t rectangle.hpp <adobe/rectangle.hpp>
\ingroup asl_libraries

\brief A class containing element geometry for a single orientation.

\par Model Of:
Regular Type

\par Rationale
adobe::rectangle_t::slice_t is intended to make iterating over a rectangle easier. If the notion of orientation is abstracted out when manipulating geometries, it is possible to loop once over a series of rectangles in one direction, then again in the other. More code can be shared at that point, no matter which way you slice it.
*/

/*!
\fn adobe::rectangle_t::slice_t::slice_t

Default constructor.
*/

/*!
\var long adobe::rectangle_t::slice_t::length_m

The length of this slice.
*/

/*!
\var pair_long_t adobe::rectangle_t::slice_t::outset_m

Outset describes the amount outside the bounds of the element taken up by a graphic that can be absorbed by spacing. An example of this would be the drop shadow around a window. This value is a hither/yon pair, meaning the values represent the values on either side of the element being described for this orientation.
*/

/*!
\var pair_long_t adobe::rectangle_t::slice_t::frame_m

Frame describes the amount inside the bounds of the element taken up by a graphic that cannot be absorbed by spacing. This value is a hither/yon pair, meaning the values represent the values on either side of the element being described for this orientation.
*/

/*!
\var pair_long_t adobe::rectangle_t::slice_t::inset_m

Inset describes the amount inside the bounds of the element taken up by a graphic that can be absorbed by spacing. This value is a hither/yon pair, meaning the values represent the values on either side of the element being described for this orientation.
*/

/*!
\var points_of_interest_t adobe::rectangle_t::slice_t::poi_m

The points of interest for a slice are simply a vector of values relating to points inside the element that might be of some value to objects outside the element. Examples of these are baseline values, colon-alignment values, and the widths of subparts of the graphical element. Note that points of interest are intended to be snapped together - that is, the size of the element is able to grow and shrink so the points of interest between two related elements are the same for a given orient...

[truncated message content]