Annotation of libwww/Library/src/HText.html, revision 2.18
2.6 timbl 1: <HTML>
2: <HEAD>
2.9 luotonen 3: <TITLE>Rich Hypertext object for libWWW</TITLE>
4: </HEAD>
2.5 timbl 5: <BODY>
2.13 frystyk 6:
2.5 timbl 7: <H1>Rich HyperText Object</H1>
2.13 frystyk 8:
2.1 timbl 9: <PRE>
2.13 frystyk 10: /*
2.16 frystyk 11: ** (c) COPYRIGHT MIT 1995.
2.13 frystyk 12: ** Please first read the full copyright statement in the file COPYRIGH.
13: */
14: </PRE>
15:
16: This is the C interface to the Objective-C (or whatever)
17: Style-oriented HyperText class. It is used when a style-oriented text
18: object is available or craeted in order to display hypertext. <P>
19:
2.15 frystyk 20: This module is a part of the <A
2.17 frystyk 21: HREF="http://www.w3.org/hypertext/WWW/Library/">
22: W3C Reference Library</A>. However, it is <B>NOT</B> implemented
2.15 frystyk 23: anywhere in the library, as it is client (and often platform) specific
24: code. Hence these functions <EM>must</EM> be implemented in the
25: client. The <A
2.18 ! frystyk 26: HREF="http://www.w3.org/hypertext/WWW/LineMode/">Line Mode
2.15 frystyk 27: Browser</A> has the implementation in the <A
28: HREF="http://www.w3.org/hypertext/WWW/LineMode/Implementation/GridText.html">
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"
37: #include "HTStream.h"
2.7 timbl 38: #include "SGML.h"
2.1 timbl 39:
40: #ifndef THINK_C
41: #ifndef HyperText /* Objective C version defined HyperText */
42: typedef struct _HText HText; /* Normal Library */
2.9 luotonen 43: #else
44: @class HText; /* Objective C version for NeXTStep */
2.1 timbl 45: #endif
46: #else
47: class CHyperText; /* Mac Think-C browser hook */
48: typedef CHyperText HText;
49: #endif
50:
51: extern HText * HTMainText; /* Pointer to current main text */
52: extern HTParentAnchor * HTMainAnchor; /* Pointer to current text's anchor */
53:
2.6 timbl 54: </PRE>
55: <H2>Creation and deletion</H2>
2.7 timbl 56: <H3>HText_new: Create hypertext object</H3>There are several methods depending
57: on how much you want to specify.
58: The output stream is used with objects
59: which need to output the hypertext
60: to a stream. The structure is for
61: objects which need to refer to the
62: structure which is kep by the creating
63: stream.
2.9 luotonen 64: <PRE> extern HText * HText_new PARAMS((HTParentAnchor * anchor));
2.7 timbl 65:
2.9 luotonen 66: extern HText * HText_new2 PARAMS((HTParentAnchor * anchor,
67: HTStream * output_stream));
2.1 timbl 68:
2.9 luotonen 69: extern HText * <A
70: NAME="z0">HText_new3</A> PARAMS((HTRequest * request,
71: HTStream * output_stream,
72: HTStructured * structure));
2.7 timbl 73:
74: </PRE>
75: <H3>Free hypertext object</H3>
76: <PRE>extern void HText_free PARAMS((HText * me));
2.1 timbl 77:
78:
2.6 timbl 79: </PRE>
80: <H2>Object Building methods</H2>These are used by a parser to build
81: the text in an object HText_beginAppend
82: must be called, then any combination
83: of other append calls, then HText_endAppend.
84: This allows optimised handling using
85: buffers and caches which are flushed
86: at the end.
87: <PRE>extern void HText_beginAppend PARAMS((HText * text));
2.1 timbl 88:
89: extern void HText_endAppend PARAMS((HText * text));
90:
2.6 timbl 91: </PRE>
92: <H3>Set the style for future text</H3>
93: <PRE>
2.1 timbl 94: extern void HText_setStyle PARAMS((HText * text, HTStyle * style));
95:
2.6 timbl 96: </PRE>
97: <H3>Add one character</H3>
98: <PRE>extern void HText_appendCharacter PARAMS((HText * text, char ch));
2.1 timbl 99:
2.6 timbl 100: </PRE>
101: <H3>Add a zero-terminated string</H3>
102: <PRE>
2.1 timbl 103: extern void HText_appendText PARAMS((HText * text, CONST char * str));
104:
2.6 timbl 105: </PRE>
106: <H3>New Paragraph</H3>and similar things
107: <PRE>extern void HText_appendParagraph PARAMS((HText * text));
108:
109: extern void HText_appendLineBreak PARAMS((HText * text));
110:
111: extern void HText_appendHorizontalRule PARAMS((HText * text));
112:
2.1 timbl 113:
114:
2.6 timbl 115: </PRE>
116: <H3>Start/end sensitive text</H3>
117: <PRE>
118: </PRE>The anchor object is created and
119: passed to HText_beginAnchor. The
120: senstive text is added to the text
121: object, and then HText_endAnchor
122: is called. Anchors may not be nested.
123: <PRE>extern void HText_beginAnchor PARAMS((HText * text, HTChildAnchor * anc));
2.1 timbl 124: extern void HText_endAnchor PARAMS((HText * text));
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>
136: extern void HText_setNextId PARAMS((
137: HText * text,
138: CONST char * s));
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.6 timbl 153: <PRE>extern void HText_appendImage PARAMS((
154: HText * text,
155: HTChildAnchor * anc,
156: CONST char * alternative_text,
2.9 luotonen 157: CONST char * alignment,
2.6 timbl 158: BOOL isMap));
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.10 timbl 169: <PRE>extern void HText_appendObject PARAMS((
170: HText * text,
171: int element_number,
2.11 timbl 172: CONST BOOL * present,
2.10 timbl 173: CONST char * CONST * value));
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.
182: <PRE>extern void HText_unimplemented PARAMS((
183: HText * text));
184:
185:
186: </PRE>
187: <H2>Utilities</H2>
2.6 timbl 188: <H3>Dump diagnostics to stderr</H3>
189: <PRE>
2.1 timbl 190: extern void HText_dump PARAMS((HText * me));
191:
2.6 timbl 192: </PRE>
193: <H3>Return the anchor associated with
194: this node</H3>
195: <PRE>extern HTParentAnchor * HText_nodeAnchor PARAMS((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:
206: extern BOOL HText_select PARAMS((HText * text));
207: extern BOOL HText_selectAnchor PARAMS((HText * text, HTChildAnchor* anchor));
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: */
220: extern void HText_applyStyle PARAMS((HText * me, HTStyle *style));
221:
222: /* Update all text with changed style.
223: */
224: extern void HText_updateStyle PARAMS((HText * me, HTStyle *style));
225:
226: /* Return style of selection
227: */
228: extern HTStyle * HText_selectionStyle PARAMS((
229: HText * me,
230: HTStyleSheet* sheet));
231:
232: /* Paste in styled text
233: */
234: extern void HText_replaceSel PARAMS((HText * me,
235: CONST char *aString,
236: HTStyle* aStyle));
237:
238: /* Apply this style to the selection and all similarly formatted text
239: ** (style recovery only)
240: */
241: extern void HTextApplyToSimilar PARAMS((HText * me, HTStyle *style));
242:
243: /* Select the first unstyled run.
244: ** (style recovery only)
245: */
246: extern void HTextSelectUnstyled PARAMS((HText * me, HTStyleSheet *sheet));
247:
248:
249: /* Anchor handling:
250: */
251: extern void HText_unlinkSelection PARAMS((HText * me));
252: extern HTAnchor * HText_referenceSelected PARAMS((HText * me));
253: extern HTAnchor * HText_linkSelTo PARAMS((HText * me, HTAnchor* anchor));
254:
255:
256: #endif /* HTEXT_H */
2.11 timbl 257: </PRE>end</A></BODY>
2.6 timbl 258: </HTML>
Webmaster