Annotation of libwww/Library/src/HText.html, revision 2.27
2.6 timbl 1: <HTML>
2: <HEAD>
2.26 frystyk 3: <TITLE>W3C Reference Library libwww Rich Hypertext object</TITLE>
2.27 ! frystyk 4: <!-- Changed by: Henrik Frystyk Nielsen, 23-Mar-1996 -->
2.9 luotonen 5: </HEAD>
2.5 timbl 6: <BODY>
2.13 frystyk 7:
2.5 timbl 8: <H1>Rich HyperText Object</H1>
2.13 frystyk 9:
2.1 timbl 10: <PRE>
2.13 frystyk 11: /*
2.16 frystyk 12: ** (c) COPYRIGHT MIT 1995.
2.13 frystyk 13: ** Please first read the full copyright statement in the file COPYRIGH.
14: */
15: </PRE>
16:
17: This is the C interface to the Objective-C (or whatever)
18: Style-oriented HyperText class. It is used when a style-oriented text
19: object is available or craeted in order to display hypertext. <P>
20:
2.15 frystyk 21: This module is a part of the <A
2.24 frystyk 22: HREF="http://www.w3.org/pub/WWW/Library/"> W3C Reference
23: Library</A>. However, it is <B>NOT</B> implemented anywhere in the
24: library, as it is client (and often platform) specific code. Hence
25: these functions <EM>must</EM> be implemented in the client. The <A
26: HREF="http://www.w3.org/pub/WWW/LineMode/">Line Mode Browser</A> has
27: the implementation in the <A
2.26 frystyk 28: HREF="http://www.w3.org/pub/WWW/LineMode/src/GridText.html">
2.15 frystyk 29: GridText</A> module.
2.13 frystyk 30:
31: <PRE>
32: #ifndef HTEXT_H
2.1 timbl 33: #define HTEXT_H
2.15 frystyk 34:
2.1 timbl 35: #include "HTAnchor.h"
36: #include "HTStyle.h"
2.20 frystyk 37: #include "HTStruct.h"
2.1 timbl 38:
39: #ifndef HyperText /* Objective C version defined HyperText */
40: typedef struct _HText HText; /* Normal Library */
2.9 luotonen 41: #else
42: @class HText; /* Objective C version for NeXTStep */
2.1 timbl 43: #endif
44:
45: extern HText * HTMainText; /* Pointer to current main text */
46: extern HTParentAnchor * HTMainAnchor; /* Pointer to current text's anchor */
2.19 frystyk 47: </PRE>
2.1 timbl 48:
2.6 timbl 49: <H2>Creation and deletion</H2>
2.7 timbl 50:
2.19 frystyk 51: <A NAME="z0"><H3>Create hypertext object</H3></A>
52:
53: There are several methods depending on how much you want to specify.
54: The output stream is used with objects which need to output the
55: hypertext to a stream. The structure is for objects which need to
56: refer to the structure which is kep by the creating stream.
57:
58: <PRE>
2.24 frystyk 59: extern HText * HText_new (HTRequest * request, HTParentAnchor * anchor);
2.19 frystyk 60:
2.24 frystyk 61: extern HText * HText_new2 (HTRequest * request,
62: HTParentAnchor * anchor,
63: HTStream * output_stream);
64:
65: extern HText * HText_new3 (HTRequest * request,
66: HTStream * output_stream,
67: HTStructured * structure);
2.7 timbl 68: </PRE>
2.19 frystyk 69:
2.7 timbl 70: <H3>Free hypertext object</H3>
2.1 timbl 71:
2.19 frystyk 72: <PRE>
2.23 frystyk 73: extern void HText_free (HText * me);
2.19 frystyk 74: </PRE>
75:
76: <H2>Object Building methods</H2>
77:
78: These are used by a parser to build the text in an object
79: HText_beginAppend must be called, then any combination of other append
80: calls, then HText_endAppend. This allows optimised handling using
81: buffers and caches which are flushed at the end.
2.1 timbl 82:
2.19 frystyk 83: <PRE>
2.23 frystyk 84: extern void HText_beginAppend (HText * text);
2.1 timbl 85:
2.23 frystyk 86: extern void HText_endAppend (HText * text);
2.19 frystyk 87: </PRE>
2.1 timbl 88:
2.6 timbl 89: <H3>Set the style for future text</H3>
2.19 frystyk 90:
2.6 timbl 91: <PRE>
2.23 frystyk 92: extern void HText_setStyle (HText * text, HTStyle * style);
2.1 timbl 93:
2.6 timbl 94: </PRE>
95: <H3>Add one character</H3>
2.23 frystyk 96: <PRE>extern void HText_appendCharacter (HText * text, char ch);
2.1 timbl 97:
2.6 timbl 98: </PRE>
99: <H3>Add a zero-terminated string</H3>
100: <PRE>
2.25 frystyk 101: extern void HText_appendText (HText * text, const char * str);
2.1 timbl 102:
2.6 timbl 103: </PRE>
2.19 frystyk 104:
105: <H3>New Paragraph</H3>
106:
107: and similar things
108:
109: <PRE>
2.23 frystyk 110: extern void HText_appendParagraph (HText * text);
2.6 timbl 111:
2.23 frystyk 112: extern void HText_appendLineBreak (HText * text);
2.6 timbl 113:
2.23 frystyk 114: extern void HText_appendHorizontalRule (HText * text);
2.19 frystyk 115: </PRE>
2.6 timbl 116:
2.19 frystyk 117: <H3>Start/end sensitive text</H3>
2.1 timbl 118:
2.19 frystyk 119: The anchor object is created and passed to HText_beginAnchor. The
120: senstive text is added to the text object, and then HText_endAnchor is
121: called. Anchors may not be nested.
2.1 timbl 122:
2.23 frystyk 123: <PRE>extern void HText_beginAnchor (HText * text, HTChildAnchor * anc);
124: extern void HText_endAnchor (HText * text);
2.1 timbl 125:
126:
2.6 timbl 127: </PRE>
2.12 timbl 128: <h3>Set the next free identifier</h3>
129: The string must be of the form aaannnnn where aaa is the prefix
130: for automatically generated ids, normally "z", and nnnn is the
131: next unused number. If not present, defaults to z0. An
132: editor should pick up both the a and n bits, and increment n
133: when generating ids. This ensures that old ids are not reused,
134: even if the elements using them have been deleted from the document.
135: <pre>
2.23 frystyk 136: extern void HText_setNextId (
2.12 timbl 137: HText * text,
2.25 frystyk 138: const char * s);
2.12 timbl 139:
140: </pre>
2.6 timbl 141: <H3>Append an inline image</H3>The image is handled by the creation
142: of an anchor whose destination is
143: the image document to be included.
144: The semantics is the intended inline
145: display of the image.<P>
146: An alternative implementation could
147: be, for example, to begin an anchor,
148: append the alternative text or "IMAGE",
149: then end the anchor. This would simply
150: generate some text linked to the
151: image itself as a separate document.
2.8 timbl 152: <H2></H2>
2.23 frystyk 153: <PRE>extern void HText_appendImage (
2.6 timbl 154: HText * text,
155: HTChildAnchor * anc,
2.25 frystyk 156: const char * alternative_text,
157: const char * alignment,
2.23 frystyk 158: BOOL isMap);
2.6 timbl 159:
160: </PRE>
2.10 timbl 161: <H3>HText_appendObject: Append an object
162: which does its own work</H3>The SGML parameters are passed untouched.
2.11 timbl 163: Currently this is only used for empty
164: elements. Extensions could be (1)
165: to pass CDATA contents as well as
166: any attributes and (2) to pass the
167: whole structured stream until the
168: compound object has parsed itself.
2.23 frystyk 169: <PRE>extern void HText_appendObject (
2.10 timbl 170: HText * text,
171: int element_number,
2.25 frystyk 172: const BOOL * present,
173: const char * const * value);
2.10 timbl 174:
175: </PRE>
2.8 timbl 176: <H3>HText_unimplemented: Warn that object
177: is not completely rendered.</H3>If the parser realises that it has
178: incompletely parsed an object, then
179: it can call this to flag it to the
180: object. This will for example prevent
181: editing or writing back.
2.23 frystyk 182: <PRE>extern void HText_unimplemented (
183: HText * text);
2.8 timbl 184:
185:
186: </PRE>
187: <H2>Utilities</H2>
2.6 timbl 188: <H3>Dump diagnostics to stderr</H3>
189: <PRE>
2.23 frystyk 190: extern void HText_dump (HText * me);
2.1 timbl 191:
2.6 timbl 192: </PRE>
193: <H3>Return the anchor associated with
194: this node</H3>
2.23 frystyk 195: <PRE>extern HTParentAnchor * HText_nodeAnchor (HText * me);
2.1 timbl 196:
197:
2.6 timbl 198: </PRE>
199: <H2>Browsing functions</H2>
200: <PRE>
2.1 timbl 201:
2.6 timbl 202: </PRE>
203: <H3>Bring to front and highlight it</H3>
204: <PRE>
2.1 timbl 205:
2.23 frystyk 206: extern BOOL HText_select (HText * text);
207: extern BOOL HText_selectAnchor (HText * text, HTChildAnchor* anchor);
2.1 timbl 208:
2.6 timbl 209: </PRE>
210: <H2>Editing functions</H2>These are called from the application.
211: There are many more functions not
212: included here from the orginal text
213: object. These functions NEED NOT
214: BE IMPLEMENTED in a browser which
215: cannot edit.
216: <PRE>/* Style handling:
2.1 timbl 217: */
218: /* Apply this style to the selection
219: */
2.23 frystyk 220: extern void HText_applyStyle (HText * me, HTStyle *style);
2.1 timbl 221:
222: /* Update all text with changed style.
223: */
2.23 frystyk 224: extern void HText_updateStyle (HText * me, HTStyle *style);
2.1 timbl 225:
226: /* Return style of selection
227: */
2.23 frystyk 228: extern HTStyle * HText_selectionStyle (
2.1 timbl 229: HText * me,
2.23 frystyk 230: HTStyleSheet* sheet);
2.1 timbl 231:
232: /* Paste in styled text
233: */
2.23 frystyk 234: extern void HText_replaceSel (HText * me,
2.25 frystyk 235: const char *aString,
2.23 frystyk 236: HTStyle* aStyle);
2.1 timbl 237:
238: /* Apply this style to the selection and all similarly formatted text
239: ** (style recovery only)
240: */
2.23 frystyk 241: extern void HTextApplyToSimilar (HText * me, HTStyle *style);
2.1 timbl 242:
243: /* Select the first unstyled run.
244: ** (style recovery only)
245: */
2.23 frystyk 246: extern void HTextSelectUnstyled (HText * me, HTStyleSheet *sheet);
2.1 timbl 247:
248:
249: /* Anchor handling:
250: */
2.23 frystyk 251: extern void HText_unlinkSelection (HText * me);
252: extern HTAnchor * HText_referenceSelected (HText * me);
253: extern HTAnchor * HText_linkSelTo (HText * me, HTAnchor* anchor);
2.1 timbl 254:
2.27 ! frystyk 255: #endif /* HTEXT_H */
! 256: </PRE>
2.1 timbl 257:
2.27 ! frystyk 258: <HR>
! 259: <ADDRESS>
! 260: @(#) $Id: Date Author State $
! 261: </ADDRESS>
! 262: </BODY>
2.6 timbl 263: </HTML>
Webmaster