Rich HyperText Object

This is the C interface to the Objective-C (or whatever) Style-oriented HyperText class. It is used when a style-oriented text object is available or craeted in order to display hypertext.

#ifndef HTEXT_H
#define HTEXT_H
#include "HTAnchor.h"
#include "HTStyle.h"
#include "HTStream.h"
#include "SGML.h"

#ifdef SHORT_NAMES
#define HTMainText			HTMaText
#define HTMainAnchor			HtMaAnch
#define HText_new			HTHTNew
#define HText_new2			HTHTNew2
#define HText_free			HTHTFree
#define HText_beginAppend		HTHTBeAp
#define HText_endAppend			HTHTEnAp
#define HText_setStyle			HTHTSeSt
#define HText_appendCharacter		HTHTApCh
#define HText_appendImage		HTHTApIm
#define HText_appendText		HTHTApTe
#define HText_appendParagraph		HTHTApPa
#define HText_beginAnchor		HTHTBeAn
#define HText_endAnchor			HTHTEnAn
#define HText_dump			HTHTDump
#define HText_nodeAnchor		HTHTNoAn
#define HText_select			HTHTSele
#define HText_selectAnchor		HTHTSeAn
#define HText_applyStyle		HTHTApSt
#define HText_updateStyle		HTHTUpSt
#define HText_selectionStyle		HTHTStyl
#define HText_replaceSel		HTHTRepl
#define HText_applyToSimilar		HTHTApTo
#define HText_selectUnstyled		HTHTSeUn
#define HText_unlinkSelection		HTHTUnSe
#define HText_linkSelTo			HTHTLiSe
#define HText_referenceSelected		HTHTRefS
#endif

#ifndef THINK_C
#ifndef HyperText		/* Objective C version defined HyperText */
typedef struct _HText HText;	/* Normal Library */
#else
@class HText;			/* Objective C version for NeXTStep */
#endif
#else
class CHyperText;		/* Mac Think-C browser hook */
typedef CHyperText HText;
#endif

extern HText * HTMainText;		/* Pointer to current main text */
extern HTParentAnchor * HTMainAnchor;	/* Pointer to current text's anchor */

Creation and deletion

HText_new: Create hypertext object

There are several methods depending on how much you want to specify. The output stream is used with objects which need to output the hypertext to a stream. The structure is for objects which need to refer to the structure which is kep by the creating stream.

 extern HText *	HText_new PARAMS((HTParentAnchor * 	anchor));

 extern HText *	HText_new2 PARAMS((HTParentAnchor * 	anchor,
 				HTStream * 		output_stream));

 extern HText *	HText_new3 PARAMS((HTRequest *		request,
 				HTStream * 		output_stream,
				HTStructured * 		structure));

Free hypertext object

extern void 	HText_free PARAMS((HText * me));

Object Building methods

These are used by a parser to build the text in an object HText_beginAppend must be called, then any combination of other append calls, then HText_endAppend. This allows optimised handling using buffers and caches which are flushed at the end.

extern void HText_beginAppend PARAMS((HText * text));

extern void HText_endAppend PARAMS((HText * text));

Set the style for future text

extern void HText_setStyle PARAMS((HText * text, HTStyle * style));

Add one character

extern void HText_appendCharacter PARAMS((HText * text, char ch));

Add a zero-terminated string

extern void HText_appendText PARAMS((HText * text, CONST char * str));

New Paragraph

and similar things

extern void HText_appendParagraph PARAMS((HText * text));

extern void HText_appendLineBreak PARAMS((HText * text));

extern void HText_appendHorizontalRule PARAMS((HText * text));

Start/end sensitive text

The anchor object is created and passed to HText_beginAnchor. The senstive text is added to the text object, and then HText_endAnchor is called. Anchors may not be nested.

extern void HText_beginAnchor PARAMS((HText * text, HTChildAnchor * anc));
extern void HText_endAnchor PARAMS((HText * text));

Set the next free identifier

The string must be of the form aaannnnn where aaa is the prefix for automatically generated ids, normally "z", and nnnn is the next unused number. If not present, defaults to z0. An editor should pick up both the a and n bits, and increment n when generating ids. This ensures that old ids are not reused, even if the elements using them have been deleted from the document.

extern void HText_setNextId PARAMS((
	HText *		text,
	CONST char *    s));

Append an inline image

The image is handled by the creation of an anchor whose destination is the image document to be included. The semantics is the intended inline display of the image.

An alternative implementation could be, for example, to begin an anchor, append the alternative text or "IMAGE", then end the anchor. This would simply generate some text linked to the image itself as a separate document.

extern void HText_appendImage PARAMS((
	HText * 	text,
	HTChildAnchor * anc,
	CONST char * 	alternative_text,
	CONST char *	alignment,
	BOOL		isMap));

HText_appendObject: Append an object which does its own work

The SGML parameters are passed untouched. Currently this is only used for empty elements. Extensions could be (1) to pass CDATA contents as well as any attributes and (2) to pass the whole structured stream until the compound object has parsed itself.

extern void HText_appendObject PARAMS((
	HText * 		text,
	int			element_number,
	CONST BOOL *		present,
	CONST char * CONST * 	value));

HText_unimplemented: Warn that object is not completely rendered.

If the parser realises that it has incompletely parsed an object, then it can call this to flag it to the object. This will for example prevent editing or writing back.

extern void HText_unimplemented PARAMS((
	HText *		text));

Utilities

Dump diagnostics to stderr

extern void HText_dump PARAMS((HText * me));

Return the anchor associated with this node

extern HTParentAnchor * HText_nodeAnchor PARAMS((HText * me));

Browsing functions

Bring to front and highlight it


extern BOOL HText_select PARAMS((HText * text)); 
extern BOOL HText_selectAnchor PARAMS((HText * text, HTChildAnchor* anchor));

Editing functions

These are called from the application. There are many more functions not included here from the orginal text object. These functions NEED NOT BE IMPLEMENTED in a browser which cannot edit.

/*	Style handling:
*/
/*	Apply this style to the selection
*/
extern void HText_applyStyle PARAMS((HText * me, HTStyle *style));

/*	Update all text with changed style.
*/
extern void HText_updateStyle PARAMS((HText * me, HTStyle *style));

/*	Return style of  selection
*/
extern HTStyle * HText_selectionStyle PARAMS((
	HText * me,
	HTStyleSheet* sheet));

/*	Paste in styled text
*/
extern void HText_replaceSel PARAMS((HText * me,
	CONST char *aString, 
	HTStyle* aStyle));

/*	Apply this style to the selection and all similarly formatted text
**	(style recovery only)
*/
extern void HTextApplyToSimilar PARAMS((HText * me, HTStyle *style));
 
/*	Select the first unstyled run.
**	(style recovery only)
*/
extern void HTextSelectUnstyled PARAMS((HText * me, HTStyleSheet *sheet));


/*	Anchor handling:
*/
extern void		HText_unlinkSelection PARAMS((HText * me));
extern HTAnchor *	HText_referenceSelected PARAMS((HText * me));
extern HTAnchor *	HText_linkSelTo PARAMS((HText * me, HTAnchor* anchor));


#endif /* HTEXT_H */

end