#ifndef QTEXTDOCUMENTLOBS_H
#define QTEXTDOCUMENTLOBS_H
/** \file qtextdocumentlobs.h
*
* \brief Defines functions for dealing with word processing Lobs
*
* This file defines the set of OpenMath symbols I use in encoding QTextDocuments as Lobs.
* <table>
* <tr><td><b>Symbol name</b></td><td><b>Symbol CD</b></td><td><b>Purpose</b></td></tr>
* <tr><td>StandardFrame</td><td>LurchUI</td>
* <td>An application of this to a sequence of frames and blocks encodes a QTextFrame
* whose QTextFrameFormat is the default one</td></tr>
* <tr><td>TableFrame</td><td>LurchUI</td>
* <td>An application of this to a sequence of frames and blocks encodes a QTextFrame
* whose QTextFrameFormat is a QTextTableFormat</td></tr>
* <tr><td>Block</td><td>LurchUI</td>
* <td>An application of this to a sequence of text objects encodes a paragraph, also known
* as a QTextBlock</td></tr>
* <tr><td>charFormat</td><td>LurchUI</td>
* <td>This symbol can be used as an attribute key on text or block Lobs, and its value may
* be a string encoding a character format, as implemented in LurchDocumentConverter
* </td></tr>
* <tr><td>blockFormat</td><td>LurchUI</td>
* <td>This symbol can be used as an attribute key on block Lobs only, and its value may
* be a string encoding a block format, as implemented in LurchDocumentConverter
* </td></tr>
* <tr><td>listFormat</td><td>LurchUI</td>
* <td>This symbol can be used as an attribute key only on block Lobs only, and its value may
* be a string encoding a list format, as implemented in LurchDocumentConverter
* </td></tr>
* </table>
* These are defined as global functions StandardFrameSym(), TableFrameSym(), BlockSym(),
* charFormatSym(), blockFormatSym(), and listFormatSym(), and they return new copies each time
* they are called, so they are safe to use for inserting their results into new structures.
*
* Also, this file defines routines for identifying Lobs as encoding certain types of
* QTextDocument structures. These include isBlock(), isFrame(), isList(), and isText().
*
* Lastly, this file defines the routine normalize(), which simplifies word processing
* structures by uniting adjacent text fragments with identical character formatting.
*/
#include "lob.h"
/** \brief Symbol for a standard QTextDocument frame
*
* See the documentation for this file (qtextdocumentutils.h) for more information.
*/
const Lob StandardFrameSym ();
/** \brief Symbol for a QTextDocument frame holding a table
*
* See the documentation for this file (qtextdocumentutils.h) for more information.
*/
const Lob TableFrameSym ();
/** \brief Symbol for a QTextDocument block
*
* See the documentation for this file (qtextdocumentutils.h) for more information.
*/
const Lob BlockSym ();
/** \brief Symbol for attributing blocks and text with character formats
*
* See the documentation for this file (qtextdocumentutils.h) for more information.
*/
const Lob charFormatSym ();
/** \brief Symbol for attributing blocks with paragraph-level formatting
*
* See the documentation for this file (qtextdocumentutils.h) for more information.
*/
const Lob blockFormatSym ();
/** \brief Symbol for attributing blocks with list formatting
*
* See the documentation for this file (qtextdocumentutils.h) for more information.
*/
const Lob listFormatSym ();
/** \brief Whether \a L is an application of BlockSym() to zero or more arguments
*
* \see isFrame(), isText(), isList()
*/
bool isBlock ( Lob L );
/** \brief Whether \a L is an application of StandardFrameSym() or TableFrameSym()
* to zero or more arguments
*
* \see isBlock(), isText(), isList()
*/
bool isFrame ( Lob L );
/** \brief Whether \a L wraps an OpenMath string node (because any string can be text in the
* word processor)
*
* \see isFrame(), isBlock(), isList()
*/
bool isText ( Lob L );
/** \brief Whether \a L is a list item
*
* This means that \a L passes isBlock() and has an attribute whose key is listFormatSym().
*
* \see isFrame(), isText(), isBlock()
*/
bool isListItem ( Lob L );
/** \brief Combines adjacent text fragments with identical formatting
*
* This routine finds any text blocks inside the Lob hierarchy of \a L and combines any
* adjacent text fragments with identical character formatting.
*
* E.g., it is possible for a block to contain a text fragment <tt>"hello "</tt> followed
* immediately by a text fragment <tt>"there!"</tt>, with neither having any formatting
* (or both having the same non-default formatting), when in reality such a block could be
* represented more simply with just one text fragment. Thus we provide this normalization
* routine that combines all such sequences into one.
*
* Any other attributes of either text fragment are copied to the combined text fragment,
* with those of the first (left) text fragment taking precedence in the case of conflicts.
*/
void normalize ( Lob L );
#endif // QTEXTDOCUMENTLOBS_H