Annotation of libwww/Library/src/HTAnchor.html, revision 2.17
2.7 timbl 1: <HTML>
2: <HEAD>
2.8 timbl 3: <TITLE>Anchor object for libwww</TITLE>
4: </HEAD>
2.6 timbl 5: <BODY>
2.15 frystyk 6:
7: <H1>Hypertext "Anchor" Object</H1>
8:
9: <PRE>
10: /*
11: ** (c) COPYRIGHT CERN 1994.
12: ** Please first read the full copyright statement in the file COPYRIGH.
13: */
14: </PRE>
15:
16: An anchor represents a region of a hypertext document which is linked
17: to another anchor in the same or a different document. <P>
18:
19: This module is implemented by <A HREF="HTAnchor.c">HTAnchor.c</A>, and
20: it is a part of the <A
21: HREF="http://info.cern.ch/hypertext/WWW/Library/User/Guide/Guide.html">
22: Library of Common Code</A>.
23:
24: <PRE>
25: #ifndef HTANCHOR_H
1.1 timbl 26: #define HTANCHOR_H
2.17 ! frystyk 27: #include "HTList.h"
! 28: #include "HTAtom.h"
1.1 timbl 29:
30: /* Version 0 (TBL) written in Objective-C for the NeXT browser */
31: /* Version 1 of 24-Oct-1991 (JFG), written in C, browser-independant */
32:
2.7 timbl 33: </PRE>
34: <H3>Short names</H3>
35: <PRE>#ifdef SHORT_NAMES
1.1 timbl 36: #define HTAnchor_findChild HTAnFiCh
37: #define HTAnchor_findChildAndLink HTAnFiLi
38: #define HTAnchor_findAddress HTAnFiAd
39: #define HTAnchor_delete HTAnDele
40: #define HTAnchor_makeLastChild HTAnMaLa
41: #define HTAnchor_parent HTAnPare
42: #define HTAnchor_setDocument HTAnSeDo
43: #define HTAnchor_document HTAnDocu
44: #define HTAnchor_setFormat HTAnSeFo
45: #define HTAnchor_format HTAnForm
46: #define HTAnchor_setIndex HTAnSeIn
47: #define HTAnchor_isIndex HTAnIsIn
48: #define HTAnchor_address HTAnAddr
49: #define HTAnchor_hasChildren HTAnHaCh
50: #define HTAnchor_title HTAnTitl
51: #define HTAnchor_setTitle HTAnSeTi
52: #define HTAnchor_appendTitle HTAnApTi
53: #define HTAnchor_link HTAnLink
54: #define HTAnchor_followMainLink HTAnFoMa
55: #define HTAnchor_followTypedLink HTAnFoTy
56: #define HTAnchor_makeMainLink HTAnMaMa
2.6 timbl 57: #define HTAnchor_setProtocol HTAnSePr
58: #define HTAnchor_protocol HTAnProt
59: #define HTAnchor_physical HTAnPhys
60: #define HTAnchor_setPhysical HTAnSePh
61: #define HTAnchor_methods HtAnMeth
1.1 timbl 62: #endif
63:
2.7 timbl 64: </PRE>
2.13 frystyk 65: <A NAME="anchor"><H2>Anchor data structures</H2></A>
2.7 timbl 66: <PRE>typedef struct _HyperDoc HyperDoc; /* Ready for forward references */
1.1 timbl 67: typedef struct _HTAnchor HTAnchor;
68: typedef struct _HTParentAnchor HTParentAnchor;
2.10 timbl 69: typedef struct _HTChildAnchor HTChildAnchor;
1.1 timbl 70:
2.7 timbl 71: </PRE>Must be AFTER definition of HTAnchor:
72: <PRE>#include "HTFormat.h"
1.1 timbl 73:
74: typedef HTAtom HTLinkType;
75:
76: typedef struct {
77: HTAnchor * dest; /* The anchor to which this leads */
78: HTLinkType * type; /* Semantics of this link */
79: } HTLink;
80:
2.8 timbl 81: </PRE>
2.14 frystyk 82: <A NAME="Generic"><H3>Generic Anchor type</H3></A>
2.8 timbl 83: <PRE>struct _HTAnchor { /* Generic anchor : just links */
1.1 timbl 84: HTLink mainLink; /* Main (or default) destination of this */
85: HTList * links; /* List of extra links from this, if any */
86: /* We separate the first link from the others to avoid too many small mallocs
87: involved by a list creation. Most anchors only point to one place. */
88: HTParentAnchor * parent; /* Parent of this anchor (self for adults) */
89: };
90:
2.8 timbl 91: </PRE>
92: <H3>Anchor for a whole object</H3>
93: <PRE>struct _HTParentAnchor {
1.1 timbl 94: /* Common part from the generic anchor structure */
95: HTLink mainLink; /* Main (or default) destination of this */
96: HTList * links; /* List of extra links from this, if any */
97: HTParentAnchor * parent; /* Parent of this anchor (self) */
98:
99: /* ParentAnchor-specific information */
100: HTList * children; /* Subanchors of this, if any */
101: HTList * sources; /* List of anchors pointing to this, if any */
102: HyperDoc * document; /* The document within which this is an anchor */
103: char * address; /* Absolute address of this node */
104: HTFormat format; /* Pointer to node format descriptor */
105: BOOL isIndex; /* Acceptance of a keyword search */
106: char * title; /* Title of document */
107:
108: HTList* methods; /* Methods available as HTAtoms */
109: void * protocol; /* Protocol object */
110: char * physical; /* Physical address */
2.8 timbl 111: HTList * <A
2.10 timbl 112: NAME="z1">cacheItems</A> ; /* Cache hits (see <A
2.17 ! frystyk 113: NAME="z0" HREF="HTFWrite.html">HTFWriter</A> ) for this URL */
2.9 timbl 114: long int size; /* Indicative size only if multiformat */
1.1 timbl 115: };
116:
2.8 timbl 117: </PRE>
118: <H3>Anchor for a fragment of an object</H3>
2.10 timbl 119: <PRE>struct _HTChildAnchor {
1.1 timbl 120: /* Common part from the generic anchor structure */
121: HTLink mainLink; /* Main (or default) destination of this */
122: HTList * links; /* List of extra links from this, if any */
123: HTParentAnchor * parent; /* Parent of this anchor */
124:
125: /* ChildAnchor-specific information */
126: char * tag; /* Address of this anchor relative to parent */
2.10 timbl 127: };
1.1 timbl 128:
2.7 timbl 129: </PRE>
130: <H2>Class methods</H2>
131: <H3>HTAnchor_findChild: Create new or
132: find old sub-anchor</H3>This one is for a new anchor being
133: edited into an existing document.
134: The parent anchor must already exist.
135: <PRE>extern HTChildAnchor * HTAnchor_findChild
1.1 timbl 136: PARAMS(
137: (HTParentAnchor *parent,
138: CONST char *tag)
139: );
140:
2.7 timbl 141: </PRE>
142: <H3>HTAnchor_findChildAndLink: Create
143: or find a child anchor with a possible
144: link</H3>Create new anchor with a given parent
145: and possibly a name, and possibly
146: a link to a _relatively_ named anchor.
147: <PRE>extern HTChildAnchor * HTAnchor_findChildAndLink
1.1 timbl 148: PARAMS((
149: HTParentAnchor * parent, /* May not be 0 */
150: CONST char * tag, /* May be "" or 0 */
151: CONST char * href, /* May be "" or 0 */
152: HTLinkType * ltype /* May be 0 */
153: ));
154:
155:
2.7 timbl 156: </PRE>
157: <H3>Create new or find old named anchor</H3>
158: <PRE>
159: </PRE>This one is for a reference which
160: is found in a document, and might
161: not be already loaded. Note: You
162: are not guaranteed a new anchor --
163: you might get an old one, like with
164: NXFonts.
165: <PRE>extern HTAnchor * HTAnchor_findAddress
1.1 timbl 166: PARAMS(
167: (CONST char * address)
168: );
169:
170:
2.7 timbl 171: </PRE>
172: <H3>HTAnchor_delete: Delete an anchor</H3>Also possibly delete related things
173: (auto garbage collection)<P>
174: The anchor is only deleted if the
175: corresponding document is not loaded.
176: All outgoing links from parent and
177: children are deleted, and this anchor
178: is removed from the sources list
179: of all its targets. We also try to
180: delete the targets whose documents
181: are not loaded. If this anchor's
182: source list is empty, we delete it
183: and its children.
184: <PRE>extern BOOL HTAnchor_delete
1.1 timbl 185: PARAMS(
1.2 timbl 186: (HTParentAnchor *me)
1.1 timbl 187: );
188:
189:
2.7 timbl 190: </PRE>
191: <H3>HTAnchor_makeLastChild: Move an
192: anchor to the head of the list of
193: its siblings</H3>This is to ensure that an anchor
194: which might have already existed
195: is put in the correct order as we
196: load the document.
197: <PRE>
1.1 timbl 198:
199: extern void HTAnchor_makeLastChild
200: PARAMS(
1.2 timbl 201: (HTChildAnchor *me)
1.1 timbl 202: );
203:
2.7 timbl 204: </PRE>
2.12 frystyk 205: <H2>Accessing Properties of the Anchor</H2>
2.7 timbl 206: <PRE>
1.1 timbl 207:
208: extern HTParentAnchor * HTAnchor_parent
209: PARAMS(
1.2 timbl 210: (HTAnchor *me)
1.1 timbl 211: );
212:
213: extern void HTAnchor_setDocument
214: PARAMS(
1.2 timbl 215: (HTParentAnchor *me, HyperDoc *doc)
1.1 timbl 216: );
217:
218: extern HyperDoc * HTAnchor_document
219: PARAMS(
1.2 timbl 220: (HTParentAnchor *me)
1.1 timbl 221: );
222: /* We don't want code to change an address after anchor creation... yet ?
223: extern void HTAnchor_setAddress
224: PARAMS(
1.2 timbl 225: (HTAnchor *me, char *addr)
1.1 timbl 226: );
227: */
228:
2.7 timbl 229: </PRE>
230: <H3>HTAnchor_address</H3>Returns the full URI of the anchor,
231: child or parent as a malloc'd string
232: to be freed by the caller.
233: <PRE>
1.1 timbl 234: extern char * HTAnchor_address
235: PARAMS(
1.2 timbl 236: (HTAnchor *me)
1.1 timbl 237: );
238:
2.7 timbl 239: </PRE>
240: <H3>Format of source</H3>
241: <PRE>extern void HTAnchor_setFormat
1.1 timbl 242: PARAMS(
1.2 timbl 243: (HTParentAnchor *me, HTFormat form)
1.1 timbl 244: );
245:
246: extern HTFormat HTAnchor_format
247: PARAMS(
1.2 timbl 248: (HTParentAnchor *me)
1.1 timbl 249: );
2.11 frystyk 250: </PRE>
1.1 timbl 251:
2.11 frystyk 252: <H3>Is it searchable?</H3>
253: <PRE>
254: extern void HTAnchor_clearIndex PARAMS((HTParentAnchor *me));
255: extern void HTAnchor_setIndex PARAMS((HTParentAnchor *me));
256: extern BOOL HTAnchor_isIndex PARAMS((HTParentAnchor *me));
2.7 timbl 257: </PRE>
1.1 timbl 258:
2.7 timbl 259: <H3>Does it have any anchors within it?</H3>
260: <PRE>extern BOOL HTAnchor_hasChildren
1.1 timbl 261: PARAMS(
1.2 timbl 262: (HTParentAnchor *me)
1.1 timbl 263: );
264:
2.7 timbl 265: </PRE>
266: <H3>List of methods which can operate
267: on object</H3>
268: <PRE>extern HTList * HTAnchor_methods PARAMS((HTParentAnchor *me));
269:
270: </PRE>
271: <H3>Protocol</H3>
272: <PRE>extern void * HTAnchor_protocol PARAMS((HTParentAnchor * me));
273: extern void HTAnchor_setProtocol PARAMS((HTParentAnchor * me,
274: void* protocol));
275:
276: </PRE>
277: <H3>Physical address</H3>
278: <PRE>extern char * HTAnchor_physical PARAMS((HTParentAnchor * me));
279: extern void HTAnchor_setPhysical PARAMS((HTParentAnchor * me,
280: char * protocol));
281:
282: </PRE>
283: <H2>Title handling</H2>
284: <PRE>
1.1 timbl 285: extern CONST char * HTAnchor_title
286: PARAMS(
1.2 timbl 287: (HTParentAnchor *me)
1.1 timbl 288: );
289:
290: extern void HTAnchor_setTitle
291: PARAMS(
1.2 timbl 292: (HTParentAnchor *me, CONST char * title)
1.1 timbl 293: );
294:
295: extern void HTAnchor_appendTitle
296: PARAMS(
1.2 timbl 297: (HTParentAnchor *me, CONST char * title)
1.1 timbl 298: );
299:
300:
2.7 timbl 301: </PRE>
2.13 frystyk 302: <A NAME="links"><H2>Manipulation of Links</H2></A>
2.7 timbl 303: <H3>Link this Anchor to another given
304: one</H3>
305: <PRE>
1.1 timbl 306: extern BOOL HTAnchor_link
307: PARAMS(
308: (HTAnchor *source, HTAnchor *destination, HTLinkType *type)
309: );
310:
2.7 timbl 311: </PRE>
312: <H3>Find destination of link</H3>
313: <PRE>extern HTAnchor * HTAnchor_followMainLink
1.1 timbl 314: PARAMS(
1.2 timbl 315: (HTAnchor *me)
1.1 timbl 316: );
317:
2.7 timbl 318: </PRE>
319: <H3>Find destination with given relationship</H3>
320: <PRE>extern HTAnchor * HTAnchor_followTypedLink
1.1 timbl 321: PARAMS(
1.2 timbl 322: (HTAnchor *me, HTLinkType *type)
1.1 timbl 323: );
324:
2.7 timbl 325: </PRE>
326: <H3>Make a particular link the main link</H3>
327: <PRE>extern BOOL HTAnchor_makeMainLink
1.1 timbl 328: PARAMS(
1.2 timbl 329: (HTAnchor *me, HTLink *movingLink)
1.1 timbl 330: );
331:
332:
2.7 timbl 333: #endif /* HTANCHOR_H */
1.1 timbl 334:
2.6 timbl 335:
2.8 timbl 336:
337:
338:
2.10 timbl 339:
340: </PRE></BODY>
2.7 timbl 341: </HTML>
Webmaster