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