Annotation of libwww/Library/src/HTHist.html, revision 2.12
2.1 frystyk 1: <HTML>
2: <HEAD>
2.11 frystyk 3: <TITLE>W3C Reference Library libwww HISTORY</TITLE>
2.12 ! frystyk 4: <!-- Changed by: Henrik Frystyk Nielsen, 23-Mar-1996 -->
2.1 frystyk 5: </HEAD>
6: <BODY>
7:
2.5 frystyk 8: <H1>History Manager</H1>
2.1 frystyk 9:
10: <PRE>
11: /*
2.3 frystyk 12: ** (c) COPYRIGHT MIT 1995.
2.1 frystyk 13: ** Please first read the full copyright statement in the file COPYRIGH.
14: */
15: </PRE>
16:
17: This is a simple history module for a WWW client. It keeps a linear
2.7 frystyk 18: history, with a destructive <EM>or</EM> non-destructive backtrack, and
19: list sequencing (previous, next) operations.<P>
2.1 frystyk 20:
21: If you are building a client, you don't have to use this: just don't
22: call it. This module is not used by any other modules in the libwww,
23: so if you don't refer to it you don't get it in your linked
24: application. <P>
25:
2.2 frystyk 26: This module is implemented by <A HREF="HTHist.c">HTHist.c</A>, and it
2.9 frystyk 27: is a part of the <A HREF="http://www.w3.org/pub/WWW/Library/">
2.4 frystyk 28: W3C Reference Library</A>.
2.1 frystyk 29:
30: <PRE>
31: #ifndef HTHISTORY_H
32: #define HTHISTORY_H
33:
34: #include "HTAnchor.h"
2.7 frystyk 35: </PRE>
36:
2.8 frystyk 37: <H2>Creation and Deletion Methods</H2>
38:
39: The history module can handle multiple history lists which can be
40: useful in a multithreaded environment with several open windows in the
41: client application. A new histrory lidt is referenced by the handle
42: returned from the creation method.
43:
44: <PRE>
45: typedef struct _HTHistory HTHistory;
46:
2.10 frystyk 47: extern HTHistory *HTHistory_new (void);
48: extern BOOL HTHistory_delete (HTHistory *old);
2.8 frystyk 49: </PRE>
50:
51: <H2>Add and delete History Elements</H2>
52:
53: <H3>Record an entry in a list</H3>
2.7 frystyk 54:
55: Registers the object in the linear list. The first entry is the home
2.8 frystyk 56: page. No check is done for duplicates. Returns YES if ok, else NO
2.7 frystyk 57:
58: <PRE>
2.10 frystyk 59: extern BOOL HTHistory_record (HTHistory *hist, HTAnchor *cur);
2.7 frystyk 60: </PRE>
61:
2.8 frystyk 62: <H3>Replace list with new element</H3>
2.7 frystyk 63:
2.8 frystyk 64: Iserts the new element at the current position and removes all any
65: old list from current position. For example if c is cur pos
66: <UL>
67: <LI>before: a b c d e
68: <LI>after : a b f
69: </UL>
70: Returns YES if ok, else NO
2.7 frystyk 71:
72: <PRE>
2.10 frystyk 73: extern BOOL HTHistory_replace (HTHistory *hist, HTAnchor *cur);
2.7 frystyk 74: </PRE>
75:
2.8 frystyk 76: <H3>Delete last entry in a list</H3>
2.7 frystyk 77:
2.8 frystyk 78: Deletes the last object from the list Returns YES if OK, else NO
2.7 frystyk 79:
80: <PRE>
2.10 frystyk 81: extern BOOL HTHistory_removeLast (HTHistory *hist);
2.7 frystyk 82: </PRE>
83:
2.8 frystyk 84: <H3>Remove the History list from position</H3>
2.7 frystyk 85:
2.8 frystyk 86: Deletes the history list FROM the entry at position 'cur' (excluded).
87: Home page has position 1. Returns YES if OK, else NO
2.7 frystyk 88:
89: <PRE>
2.10 frystyk 90: extern BOOL HTHistory_removeFrom (HTHistory *hist, int pos);
2.7 frystyk 91: </PRE>
92:
2.8 frystyk 93: <H3>Number of elements stored</H3>
2.7 frystyk 94:
2.8 frystyk 95: Returns the size of the history list or -1 if none.
2.7 frystyk 96:
97: <PRE>
2.10 frystyk 98: extern int HTHistory_count (HTHistory *hist);
2.7 frystyk 99: </PRE>
100:
2.8 frystyk 101: <H3>Current Position</H3>
2.7 frystyk 102:
2.8 frystyk 103: Returns the current position or -1 on error
2.7 frystyk 104:
105: <PRE>
2.10 frystyk 106: extern int HTHistory_position (HTHistory *hist);
2.7 frystyk 107: </PRE>
108:
2.8 frystyk 109: <H3>Find and re-register visited anchor</H3>
2.7 frystyk 110:
2.8 frystyk 111: Finds already registered anchor at given position and registers it
2.7 frystyk 112: again EXCEPT if last entry. This allows for `circular' history lists
2.8 frystyk 113: with duplicate entries. Position 1 is the home anchor. The current
114: position <EM>is</EM> updated.
2.7 frystyk 115:
116: <PRE>
2.10 frystyk 117: extern HTAnchor * HTHistory_recall (HTHistory *hist, int pos);
2.7 frystyk 118: </PRE>
119:
2.8 frystyk 120: <H3>Find Entry at position</H3>
2.1 frystyk 121:
2.7 frystyk 122: Entry with the given index in the list (1 is the home page). Like
2.8 frystyk 123: <CODE>HTHistory_recall</CODE> but without re-registration. Un success,
124: the current position <EM>is</EM> updated to the value 'pos' value.
2.7 frystyk 125:
126: <PRE>
2.10 frystyk 127: extern HTAnchor * HTHistory_find (HTHistory *hist, int pos);
2.7 frystyk 128: </PRE>
2.1 frystyk 129:
2.8 frystyk 130: <H3>List the History List</H3>
131:
132: This function is like <CODE>HTHistory_find()</CODE> but <EM>does
133: not</EM> update the current position
134:
135: <PRE>
2.10 frystyk 136: extern HTAnchor * HTHistory_list (HTHistory *hist, int pos);
2.8 frystyk 137: </PRE>
138:
139: <H2>Navigation</H2>
140:
141: <H3>Can we back in history</H3>
2.1 frystyk 142:
2.7 frystyk 143: Returns YES if the current anchor is not the first entry (home page)
2.1 frystyk 144:
2.7 frystyk 145: <PRE>
2.10 frystyk 146: extern BOOL HTHistory_canBacktrack (HTHistory *hist);
2.7 frystyk 147: </PRE>
2.1 frystyk 148:
2.8 frystyk 149: <H3>Backtrack with deletion</H3>
2.1 frystyk 150:
2.7 frystyk 151: Returns the previous object and erases the last object. This does not
152: allow for 'forward' as we are always at the end of the list. If no
153: previous object exists, NULL is returned so that the application knows
154: that no previous object was found. See also HTHistory_back().
2.1 frystyk 155:
2.7 frystyk 156: <PRE>
2.10 frystyk 157: extern HTAnchor * HTHistory_backtrack (HTHistory *hist);
2.7 frystyk 158: </PRE>
159:
2.8 frystyk 160: <H3>Backtrack without deletion</H3>
2.7 frystyk 161:
162: Returns the previos object but does not erase the last object. This
163: does not allow for 'forward'. If no previous object exists, NULL is
164: returned so that the application knows that no previous object was
165: found. See also HTHistory_backtrack()
2.1 frystyk 166:
2.7 frystyk 167: <PRE>
2.10 frystyk 168: extern HTAnchor * HTHistory_back (HTHistory *hist);
2.7 frystyk 169: </PRE>
170:
2.8 frystyk 171: <H3>Can we go forward</H3>
2.7 frystyk 172:
173: Returns YES if the current anchor is not the last entry
174:
175: <PRE>
2.10 frystyk 176: extern BOOL HTHistory_canForward (HTHistory *hist);
2.7 frystyk 177: </PRE>
178:
2.8 frystyk 179: <H3>Forward</H3>
2.1 frystyk 180:
2.7 frystyk 181: Return the next object in the list or NULL if none
182:
183: <PRE>
2.10 frystyk 184: extern HTAnchor * HTHistory_forward (HTHistory *hist);
2.1 frystyk 185:
186: #endif /* HTHISTORY_H */
2.7 frystyk 187: </PRE>
2.12 ! frystyk 188:
! 189: <HR>
! 190: <ADDRESS>
! 191: @(#) $Id: Date Author State $
! 192: </ADDRESS>
2.7 frystyk 193: </BODY>
2.1 frystyk 194: </HTML>
Webmaster