\chapter{hyText Class Reference}
\setheader{{\it CHAPTER \thechapter}}{}{}{}{}{{\it CHAPTER \thechapter}}%
\setfooter{\thepage}{}{}{}{}{\thepage}

The member functions are given in alphabetical order except for the
constructors and destructors which appear first.

\section{\class{wxHTMappingStructure}: wxObject}

This class is used for storing mapping information for a block type.

\membersection{wxHTMappingStructure::wxHTMappingStructure}

\func{void}{wxHTMappingStructure}{\param{int}{ blockType}, \param{int}{ textSize}, \param{int}{ textFamily}, \param{int}{ textStyle},\\
\param{int}{ textWeight}, \param{char *}{textColour}, \param{char *}{name}, \param{int}{ attribute = wxHYPER\_NONE},\\
\param{int}{ visibility = TRUE}}

Constructor.

\membersection{wxHTMappingStructure::\destruct{wxHTMappingStructure}}

\func{void}{\destruct{wxHTMappingStructure}}{\void}

Destructor.

\membersection{wxHTMappingStructure::Copy}

\func{wxHTMappingStructure *}{Copy}{\void}

Copies the structure.

\membersection{wxHTMappingStructure::GetFont}

\func{wxFont *}{GetFont}{\void}

Finds or creates a font matching the characteristics stored in this
structure.

\section{\class{wxHyperTextMapping}: wxList}

An object of this class stores a list of block mapping structures. The
programmer needs to call {\bf wxHyperTextWindow::SetMapping} with an
object of this class, to specify how blocks are interpreted; several
instances of {\bf wxHyperTextWindow} could make use of the same {\bf
wxHyperTextMapping}.

\membersection{wxHyperTextMapping::wxHyperTextMapping}

\func{void}{wxHyperTextMapping}{\void}

Constructor.

\membersection{wxHyperTextMapping::\destruct{wxHyperTextMapping}}

\func{void}{\destruct{wxHyperTextMapping}}{\void}

Destructor.

\membersection{wxHyperTextMapping::AddMapping}

\func{void}{AddMapping}{\param{int}{ blockType}, \param{int}{ textSize}, \param{int}{ textFamily}, \param{int}{ textStyle},\\
\param{int}{ textWeight}, \param{char *}{ textColour}, \param{char *}{name}, \param{int}{ attribute = -1},\\
\param{int}{ visibility = TRUE}}

Adds a mapping for a block type. {\it blockType} must be unique, and
any parameters which have the default value (-1 for integers, NULL for
strings) will be instantiated according to the context of the block.
That is, if a block is nested with another block, the outer block's
characteristics are used to fill in the default values.

See {\tt wxhelp.cc} for examples.

\membersection{wxHyperTextMapping::ClearMapping}

\func{void}{ClearMapping}{\void}

Deletes all members of the mapping list.

\membersection{wxHyperTextMapping::FindByName}

\func{void}{FindByName}{\param{char *}{name}}

Finds a mapping structure by name.

\membersection{wxHyperTextMapping::GetMapping}

\func{Bool}{GetMapping}{\param{int }{blockType}, \param{int *}{ textSize}, \param{int *}{textFamily}, \param{int *}{textStyle},\\
\param{int *}{textWeight}, \param{char **}{textColour}, \param{char **}{name}, \param{int *}{attribute},\\
\param{int *}{visibility}}

Gets mapping values for a given block, returning FALSE if not found.

\section{\class{wxHyperTextWindow}: wxCanvas}

Objects of this class represent a canvas on which hypertext files are
drawn.  Most of the functionality of the library is accessed through
this class.

Note that the class defines behaviour for {\bf OnEvent} and {\bf OnPaint}.

\membersection{wxHyperTextWindow::wxHyperTextWindow}

\func{void}{wxHyperTextWindow}{\param{wxFrame *}{parent}, \param{int}{ x}, \param{int}{ y},
\param{int}{ w}, \param{int}{ h}, \param{int}{ style}}

Constructor; for details see {\bf wxCanvas} in the wxWindows class reference.

\membersection{wxHyperTextWindow::\destruct{wxHyperTextWindow}}

\func{void}{\destruct{wxHyperTextWindow}}{\void}

Destructor.

\membersection{wxHyperTextWindow::AddBlock}

\func{Bool}{AddBlock}{\param{int}{ xStart}, \param{int}{ yStart}, \param{int}{ xEnd}, \param{int}{ yEnd}, \param{int}{ blockType}, \param{int}{ blockId}}

Adds a block from the first row/column to the second row/column, with
given type and unique identifier. The display will not change until
the functions {\bf Compile} and {\bf DisplayFileAt} are called.

\membersection{wxHyperTextWindow::ClearBlock}

\func{Bool}{ClearBlock}{\param{int}{ blockId}}

Clears the given block. The display will not change until the
functions {\bf Compile} and {\bf DisplayFileAt} are called.

\membersection{wxHyperTextWindow::ClearFile}

\func{void}{ClearFile}{\void}

Clears the current hypertext file.

\membersection{wxHyperTextWindow::Compile}

\func{void}{Compile}{\void}

Compiles the current hypertext file, that is, traverses the block
structure of the file associating actual fonts and other attributes to
text chunks. This must be done before a file may be displayed, and may
also require the functions {\bf SaveSection} and {\bf RestoreSection}
to be called in order to save and restore the current position in the
file, since compilation destroys section pointers.

After a {\bf Compile} (which is necessary after marking up or any
operation which affects the display) the file must be displayed with
{\bf DisplayFileAt} or {\bf RestoreSection}.

\membersection{wxHyperTextWindow::DiscardEdits}

\func{void}{DiscardEdits}{\void}

Discards any edits (just sets the internal {\it modified} flag to FALSE).

\membersection{wxHyperTextWindow::DisplayFile}

\func{void}{DisplayFile}{\void}

Draw the text at the point found by {\bf DisplayFileAt}.

\membersection{wxHyperTextWindow::DisplayFileAt}

\func{void}{DisplayFileAt}{\param{long}{ blockId}, \param{Bool }{refresh = TRUE}}

Positions the file at the given block, drawing the text only if {\it refresh} is TRUE.
If {\it blockId} is -1, the file is displayed at the top.

\membersection{wxHyperTextWindow::DisplayFileAtTop}

\func{void}{DisplayFileAtTop}{\void}

Displays the file at the top (first section).

\membersection{wxHyperTextWindow::DisplayNextSection}

\func{void}{DisplayNextSection}{\void}

Finds and displays the next section.

\membersection{wxHyperTextWindow::DisplayPreviousSection}

\func{void}{DisplayPreviousSection}{\void}

Finds and displays the previous section.

\membersection{wxHyperTextWindow::DrawOutline}

\func{void}{DrawOutline}{\param{float}{ x1}, \param{float}{ y1}, \param{float}{ x2}, \param{float}{ y2}}

Draws a rectangular outline for rubber-banding using the given
top-left and bottom-right coordinates

\membersection{wxHyperTextWindow::FindBlock}

\func{wxTextChunk *}{FindBlock}{\param{long}{ blockId}}

For a given block id, returns the text chunk at the start of the
block.

\membersection{wxHyperTextWindow::FindBlockForSection}

\func{long}{FindBlockForSection}{\param{wxNode *}{sectionNode}}

Pointers to blocks which mark sections are stored in the data member
{\bf sections}. This function takes a node which is known to point
to a text chunk marking a block, and returns the block id.
This is a fairly trivial function since it just gets the {\bf wxTextChunk}
from the node and returns its {\bf block\_id}.

\membersection{wxHyperTextWindow::FindChunkAtBlock}

\func{wxNode *}{FindChunkAtBlock}{\param{long}{ blockId}}

For a given block id, returns the position in the text chunks list of
the first CHUNK\_START\_LINE chunk before the block.  A {\bf wxNode}
pointer is returned to allow the programmer to efficiently traverse
the text chunks list from this point. The data stored in this node is
a {\bf wxTextChunk} object.

This function may not be very useful for programmers; it is mainly for
internal use. Normally functions returning and taking block ids
are used for manipulating blocks.

\membersection{wxHyperTextWindow::FindChunkAtLine}

\func{wxNode *}{FindChunkAtLine}{\param{long}{ blockId}}

For a given block id, returns the position in the text chunks list of
the first chunk on the given line.  A {\bf wxNode} pointer is returned
to allow the programmer to efficiently traverse the text chunks list
from this point. The data stored in this node is a {\bf wxTextChunk}
object.

This function may not be very useful for programmers; it is mainly for
internal use. Normally functions returning and taking block ids
are used for manipulating blocks.

\membersection{wxHyperTextWindow::FindPosition}

\func{Bool}{FindPosition}{\param{float}{ mouseX}, \param{float}{ mouseY}, \param{int *}{charPos}, \param{int *}{linePos}, \param{long *}{blockId}}

Finds the character and line position of the given point, plus the id of the block found.
Returns FALSE if no character was found at this position.

\membersection{wxHyperTextWindow::GenerateId}

\func{long}{GenerateId}{\void}

Generates a unique identifier for a block; may be overridden to supply
a different generator.

\membersection{wxHyperTextWindow::GetBlockText}

\func{void}{GetBlockText}{\param{char *}{buffer}, \param{int}{ maxSize}, \param{long}{ blockId}}

\func{void}{GetBlockText}{\param{char *}{buffer}, \param{int}{ maxSize}, \param{wxNode *}{node}, \param{long}{ blockId}}

Gets the plain text bounded by the given block, stripping out any
block codes.  The second form is more efficient since it takes a node
containing a pointer to the {\bf wxTextChunk}, and doesn't have to
search for the block.

\membersection{wxHyperTextWindow::GetBlockType}

\func{int}{GetBlockType}{\param{long}{ blockId}}

Gets the type of the given block.

\membersection{wxHyperTextWindow::GetCurrentSectionNumber}

\func{int}{GetCurrentSectionNumber}{\void}

Gets the number of the currently-displayed section, starting from 1. Zero is returned
if there are no section markers.

\membersection{wxHyperTextWindow::GetEditMode}

\func{Bool}{GetEditMode}{\void}

Returns TRUE if the hypertext window is editable.

\membersection{wxHyperTextWindow::GetFirstSelection}

\func{long}{GetFirstSelection}{\void}

Gets the first block selected. Use {\bf GetNextSelection} for subsequent
blocks. Returns -1 if no more selections.

\membersection{wxHyperTextWindow::GetLinkTable}

\func{wxHashTable *}{GetLinkTable}{\void}

Returns the hypertext window's hash table used for storing links
between blocks. Objects of type {\bf HypertextItem} are stored in the
table, containing a destination filename and destination block id;
these objects must be indexed by the source block id, to store a link
between a source block and destination block.

This is only relevant if using the built-in index facility, rather than
implementing your own index. You need to put and get explicitly, and writing
to a file will use this table for saving the index. For example:

\begin{verbatim}
  if (GetLinkTable()->Get(block_id))
    MainFrame->SetStatusText("This block already linked!");
  else if (hySelection->block_id > -1)
  {
    GetLinkTable()->Put(block_id,
      new HypertextItem(hySelection->filename, hySelection->block_id));
    modified = TRUE;
    SelectBlock(hySelection->block_id, FALSE);
    Compile();
    DisplayFile();
  }
\end{verbatim}

\membersection{wxHyperTextWindow::GetNextSelection}

\func{long}{GetNextSelection}{\void}

Gets the next  block selected (use {\bf GetFirstSelection} to start.
Returns -1 if no more selections.

\membersection{wxHyperTextWindow::GetOffsetPosition}

\func{Bool}{GetOffsetPosition}{\param{int }{line1}, \param{int }{char1},\\
  \param{int }{offset}, \param{int *}{line2}, \param{int *}{char2}}

Gets the line number and character position of the point which is {\it offset}
number of characters from the given point. The position is returned in {\it line2}
and {\it char2}.

Returns FALSE if it failed for any reason.

\membersection{wxHyperTextWindow::GetTitle}

\func{char *}{GetTitle}{\void}

Returns NULL or the title (pointer to the hypertext window's local memory).

\membersection{wxHyperTextWindow::GetSpanText}

\func{void}{GetSpanText}{\param{char *}{buffer}, \param{int}{ maxSize},\\
  \param{int}{ line1}, \param{int}{ char1}, \param{int}{ line2}, \param{int}{ char2},\\
  \param{Bool}{ convertNewLinesToSpaces = FALSE}}

Gets the plain text bounded by two line/character positions, stripping out any
block codes. The final parameter allows the user to get text in a form
that can be matched against a string with no newlines; the newlines are converted
to spaces. If this is FALSE, a ASCII code 10 will be inserted for
each newline.

\membersection{wxHyperTextWindow::LineLength}

\func{int}{LineLength}{\param{int}{lineNo}}

Returns the length of the specified line, or -1 if there is no such
line.

\membersection{wxHyperTextWindow::LoadFile}

\func{Bool}{LoadFile}{\param{char *}{file}}

Loads the named file.

\membersection{wxHyperTextWindow::Modified}

\func{Bool}{Modified}{\void}

Returns true if the user has modified the text.

\membersection{wxHyperTextWindow::NoLines}

\func{int}{NoLines}{\void}

Returns the current number of lines in the window.

\membersection{wxHyperTextWindow::OnBeginDragLeft}

\func{void}{OnBeginDragLeft}{\param{float}{ x}, \param{float}{ y}, \param{long}{ blockId}, \param{int}{ keys}}

Called when the user starts to left-drag. Overrideable.

\membersection{wxHyperTextWindow::OnBeginDragRight}

\func{void}{OnBeginDragRight}{\param{float}{ x}, \param{float}{ y}, \param{long}{ blockId}, \param{int}{ keys}}

Called when the user starts to right-drag. Overrideable.

\membersection{wxHyperTextWindow::OnDragLeft}

\func{void}{OnDragLeft}{\param{Bool}{ draw}, \param{float}{ x}, \param{float}{ y}, \param{long}{ blockId}, \param{int}{ keys}}

Called when the user is in the middle of a drag operation; called once
with {\it draw} equal to FALSE and with {\it x} and {\it y} equal to
the old values, then again with {\it draw} equal to TRUE and updated
{\it x} and {\it y} (to allow erase/draw operations).

\membersection{wxHyperTextWindow::OnDragRight}

\func{void}{OnDragRight}{\param{Bool}{ draw}, \param{float}{ x}, \param{float}{ y}, \param{long}{ blockId}, \param{int}{ keys}}

Called when the user is in the middle of a drag operation; called once
with {\it draw} equal to FALSE and with {\it x} and {\it y} equal to
the old values, then again with {\it draw} equal to TRUE and updated
{\it x} and {\it y} (to allow erase/draw operations).

\membersection{wxHyperTextWindow::OnEndDragLeft}

\func{void}{OnEndDragLeft}{\param{float}{ x}, \param{float}{ y}, \param{long}{ blockId}, \param{int}{ keys}}

Called when the user finishes left-dragging. Overrideable.

\membersection{wxHyperTextWindow::OnEndDragRight}

\func{void}{OnEndDragRight}{\param{float}{ x}, \param{float}{ y}, \param{long}{ blockId}, \param{int}{ keys}}

Called when the user finishes right-dragging. Overrideable.

\membersection{wxHyperTextWindow::OnLeftClick}

\func{void}{OnLeftClick}{\param{float}{ x}, \param{float}{ y}, \param{int}{ charPos}, \param{int}{ linePos}, \param{long}{ blockId}, \param{int}{ keys}}

Called when the user left-clicks. Overrideable. The default behaviour when SHIFT is held down
is to select or deselect the mouse-over block.

\membersection{wxHyperTextWindow::OnRightClick}

\func{void}{OnRightClick}{\param{float}{ x}, \param{float}{ y}, \param{int}{ charPos}, \param{int}{ linePos}, \param{long}{ blockId}, \param{int}{ keys}}

Called when the user right-clicks. Overrideable.

\membersection{wxHyperTextWindow::OnSelectBlock}

\func{void}{OnSelectBlock}{\param{long}{ blockId}, \param{Bool}{ select}}

Called whenever a block is selected or deselected. Overridable.

\membersection{wxHyperTextWindow::RestoreSection}

\func{void}{RestoreSection}{\void}

When a call is made to {\bf Compile}, the current pointer to the current
section becomes invalid, since all sections are recalculated. You need
to {\bf SaveSection} before {\bf Compile}, followed by {\bf RestoreSection} after
the {\bf Compile}, in order to restore the display to the previous state.

\membersection{wxHyperTextWindow::SaveFile}

\func{Bool}{SaveFile}{\param{char *}{file}}

Saves the hypertext file and index.

\membersection{wxHyperTextWindow::SaveSection}

\func{void}{SaveSection}{\void}

When a call is made to {\bf Compile}, the current pointer to the current
section becomes invalid, since all sections are recalculated. You need
to call this before {\bf Compile}, followed by {\bf RestoreSection} after
the {\bf Compile}, in order to restore the display to the previous state.

\membersection{wxHyperTextWindow::SelectBlock}

\func{void}{SelectBlock}{\param{wxTextChunk *}{ block}, \param{Bool}{ select = TRUE}}

\func{void}{SelectBlock}{\param{long}{ blockId}, \param{Bool}{ select = TRUE}}

If {\it select} is TRUE, select the existing block, marking it in cyan
(colour screens) or in inverse video (monochrome screens).  If {\it
select} is FALSE, deselect the block. The first form is more efficient
since no search need be done for the block.

Note that {\bf Compile} must be called before this call has any visible effect.

\membersection{wxHyperTextWindow::SetBlockType}

\func{void}{SetBlockType}{\param{long}{ blockId}, \param{int}{ blockType}}

Set the specified block to have the given type.

\membersection{wxHyperTextWindow::SetEditMode}

\func{void}{SetEditMode}{\param{Bool}{ editable}}

Specifies whether the user should be able to mark up the text or not.

\membersection{wxHyperTextWindow::SetIndexWriting}

\func{void}{SetIndexWriting}{\param{Bool}{ indexWriting}}

Specifies whether the built-in index and title should be written when
{\bf SaveFile} is called. The default is FALSE.

\membersection{wxHyperTextWindow::SetMapping}

\func{void}{SetMapping}{\param{wxHyperTextMapping *}{mapping}}

Specify the set of block mappings for this window; this must be called.

\membersection{wxHyperTextWindow::SetMargins}

\func{void}{SetMargins}{\param{int}{ left}, \param{int}{ top}}

Sets the margins to leave to the left and top of the canvas when
displaying text.

\membersection{wxHyperTextWindow::SetTitle}

\func{void}{SetTitle}{\param{char *}{title}}

Sets the title of the hypertext window (allocates its own memory), to be written
to the index file if index writing mode is on.

\membersection{wxHyperTextWindow::StringSearch}

\func{Bool}{StringSearch}{\param{char *}{searchString}, \param{int *}{linePos},\\
  \param{int *}{charPos}, \param{Bool }{ignoreCase = TRUE}}

Search for a string from the given position. If the search matches,
the values of the {\it linePos} and {\it charPos} arguments will be
set to the start of the matching string, and the function returns TRUE.

If there are no (more) matches, the functions returns FALSE.

If {\it ignoreCase} is TRUE, case is ignored, otherwise an exact match
is required.

In this function, newlines in the hypertext are converted to spaces, increasing
the chance of matching a phrase across newline boundaries.

\section{\class{wxTextChunk}: wxObject}

This class is used for storing a text string which has all the
same font and colour attributes. The entire hypertext file is broken
up into a list of these fragments, and the {\bf Compile} function
assigns actual font and colour attributes to each chunk.
A text chunk may also mark the start of a line (each line has
a special start line text chunk).

If a chunk represents the start of a block, the {\bf block\_id} is
this block. For chunks within a block, the {\bf block\_id} is always
the id of the block currently in scope. A text chunk which marks the
end of a block has {\bf block\_id} set to the {\it next} block's id,
but {\bf end\_block} set to the ending block's id. This is because a
text chunk contains the {\it next} fragment of text, and an end block
chunk has two purposes: to end one block, and continue another.

\membersection{wxTextChunk::wxTextChunk}

\func{void}{wxTextChunk}{\param{int}{ chunkType}, \param{int}{ lineNumber}, \param{char *}{text}, \param{wxFont *}{font},\\
\param{wxColour *}{colour}, \param{int}{ blockType}, \param{long}{ blockId}, \param{int}{ attribute}, \param{Bool}{ visibility}}

Constructor. Used only internally.

\membersection{wxTextChunk::\destruct{wxTextChunk}}

\func{void}{\destruct{wxTextChunk}}{\void}

Destructor. Used only internally.

\membersection{wxTextChunk::background\_colour}

\member{wxColour *}{background\_colour}

The background colour allocated for the chunk by {\bf Compile}.

\membersection{wxTextChunk::block\_id}

\member{long}{block\_id}

Id of the block associated with the text in the chunk.

\membersection{wxTextChunk::block\_type}

\member{int}{block\_type}

Block type, an integer defined by the application using a {\bf wxHyperTextMapping}
object.

\membersection{wxTextChunk::chunk\_type}

\member{int}{chunk\_type}

The {\bf chunk\_type} data member may be one of:

\begin{itemize}
\item CHUNK\_START\_BLOCK
\item CHUNK\_START\_UNRECOGNIZED\_BLOCK
\item CHUNK\_END\_BLOCK
\item CHUNK\_START\_BLOCK
\end{itemize}

\membersection{wxTextChunk::colour}

\member{wxColour *}{colour}

The foreground colour allocated for the chunk by {\bf Compile}.

\membersection{wxTextChunk::end\_id}

\member{long}{end\_id}

Id of the block which has just ended, if the type of this chunk is CHUNK\_END\_BLOCK.
{\bf block\_id} is the id of block which has come into scope, and which starts with the
text stored in the chunk.

\membersection{wxTextChunk::font}

\member{wxFont *}{font}

The font allocated for the chunk by {\bf Compile}.

\membersection{wxTextChunk::line\_no}

\member{int}{line\_no}

The line number for this chunk.

\membersection{wxTextChunk::logical\_op}

\member{int}{logical\_op}

The logical operator for this chunk.

\membersection{wxTextChunk::selected}

\member{Bool}{selected}

For chunks which start a block, TRUE if the block is currently selected.

\membersection{wxTextChunk::special\_attribute}

\member{int}{special\_attribute}

For a block-starting chunk, specifies one or more special attributes ORed together.
There is currently only one such attribute, wxHYPER\_SECTION, which
if present indicates that the block starts a new section.

\membersection{wxTextChunk::text}

\member{char *}{text}

The actual text in the chunk.

\membersection{wxTextChunk::visibility}

\member{Bool}{visibility}

For a block-starting chunk, determines whether the chunk is visible.