d7482997 |
1 | /* |
2 | * winhelp.h header file for winhelp.c |
3 | */ |
4 | |
5 | typedef struct WHLP_tag *WHLP; |
6 | |
7 | typedef struct WHLP_TOPIC_tag *WHLP_TOPIC; |
8 | |
9 | /* |
10 | * Initialise a new WHlp context and begin accumulating data in it. |
11 | */ |
12 | WHLP whlp_new(void); |
13 | |
14 | /* |
15 | * Close a WHlp context and write out the help file it has created. |
16 | */ |
17 | void whlp_close(WHLP h, char *filename); |
18 | |
19 | /* |
20 | * Abandon and free a WHlp context without writing out anything. |
21 | */ |
22 | void whlp_abandon(WHLP h); |
23 | |
24 | /* |
25 | * Specify the title and copyright notice of a help file. Also |
26 | * specify Help macros to be run on loading. |
27 | */ |
28 | void whlp_title(WHLP h, char *title); |
29 | void whlp_copyright(WHLP h, char *copyright); |
30 | void whlp_start_macro(WHLP h, char *macro); |
31 | |
32 | /* |
33 | * Register a help topic. Irritatingly, due to weird phase-order |
34 | * issues with the whole file format, you have to register all your |
35 | * topics _before_ actually outputting your text. This seems likely |
36 | * to require two passes over the source document. |
37 | * |
38 | * If you want to specify a particular context string (for |
39 | * reference from other programs, to provide context-sensitive |
40 | * help), you can supply it here. Otherwise, just pass NULL and a |
41 | * nondescript one will be allocated automatically. |
42 | * |
43 | * If you specify two context strings which clash under the Windows |
44 | * help file hash algorithm, this function will return NULL and |
45 | * provide a pointer to the other context string that this one |
46 | * clashed with, and you must tell your user to fix the clash. |
47 | * Sadly this is the only way to do it; despite HLP files having a |
48 | * perfectly good method of mapping arbitrary strings to things, |
49 | * they didn't see fit to use that method for help contexts, so |
50 | * instead they hash the context names and expect the hashes to be |
51 | * unique. Sigh. |
52 | * |
53 | * On success (i.e. in any circumstance other than a hash clash), a |
54 | * valid WHLP_TOPIC is returned for later use. |
55 | */ |
56 | WHLP_TOPIC whlp_register_topic(WHLP h, char *context_name, char **clash); |
57 | |
58 | /* |
59 | * Link two topics together in a browse sequence. Automatically |
60 | * takes care of the forward and reverse links. |
61 | */ |
62 | void whlp_browse_link(WHLP h, WHLP_TOPIC before, WHLP_TOPIC after); |
63 | |
64 | /* |
65 | * After calling whlp_register_topic for all topics, you should |
66 | * call this, which will sort out all loose ends and allocate |
67 | * context names for all anonymous topics. Then you can start |
68 | * writing actual text. |
69 | */ |
70 | void whlp_prepare(WHLP h); |
71 | |
72 | /* |
73 | * Create a link from an index term to a topic. |
74 | */ |
75 | void whlp_index_term(WHLP h, char *index, WHLP_TOPIC topic); |
76 | |
77 | /* |
78 | * Call this if you need the id of a topic and you don't already |
79 | * know it (for example, if whlp_prepare has allocated it |
80 | * anonymously for you). You might need this, for example, in |
81 | * creating macros for button-bar bindings. |
82 | * |
83 | * The string returned will be freed when the WHLP context is |
84 | * closed. You should not free it yourself. |
85 | * |
86 | * Do not call this before calling whlp_prepare(). |
87 | */ |
88 | char *whlp_topic_id(WHLP_TOPIC topic); |
89 | |
90 | /* |
91 | * Call this to specify which help topic will be the first one |
92 | * displayed when the help file is loaded. |
93 | */ |
94 | void whlp_primary_topic(WHLP h, WHLP_TOPIC topic); |
95 | |
96 | /* |
97 | * Call this when about to begin writing out the text for a topic. |
98 | * |
99 | * Any additional arguments are Help macros, terminated with a |
100 | * NULL. So the minimum call sequence is |
101 | * |
102 | * whlp_begin_topic(helpfile, mytopic, "Title", NULL); |
103 | */ |
104 | void whlp_begin_topic(WHLP h, WHLP_TOPIC topic, char *title, ...); |
105 | |
106 | /* |
107 | * Call this to set up a font descriptor. You supply the font name, |
108 | * the font size (in half-points), the graphic rendition flags |
109 | * (bold, italic etc), and the general font family (for Windows to |
110 | * select a fallback font if yours is unavailable). You can also |
111 | * specify a foreground colour for the text (but unfortunately not |
112 | * a background). |
113 | * |
114 | * Font descriptors are identified in whlp_set_font() by small |
115 | * integers, which are allocated from 0 upwards in the order you |
116 | * call whlp_create_font(). For your convenience, |
117 | * whlp_create_font() returns the integer allocated to each font |
118 | * descriptor you create, but you could work this out just as |
119 | * easily yourself by counting. |
120 | */ |
121 | enum { |
122 | WHLP_FONT_BOLD = 1, |
123 | WHLP_FONT_ITALIC = 2, |
124 | WHLP_FONT_UNDERLINE = 4, |
125 | WHLP_FONT_STRIKEOUT = 8, |
126 | WHLP_FONT_DOUBLEUND = 16, |
127 | WHLP_FONT_SMALLCAPS = 32 |
128 | }; |
129 | enum { |
130 | WHLP_FONTFAM_FIXED = 1, |
131 | WHLP_FONTFAM_SERIF = 2, |
132 | WHLP_FONTFAM_SANS = 3, |
133 | WHLP_FONTFAM_SCRIPT = 4, |
134 | WHLP_FONTFAM_DECOR = 5 |
135 | }; |
136 | int whlp_create_font(WHLP h, char *font, int family, int halfpoints, |
137 | int rendition, int r, int g, int b); |
138 | |
139 | /* |
140 | * Routines to output paragraphs and actual text (at last). |
141 | * |
142 | * You should start by calling whlp_para_attr() to set any |
143 | * paragraph attributes that differ from the standard settings. |
144 | * Next call whlp_begin_para() to start the paragraph. Then call |
145 | * the various in-paragraph functions until you have output the |
146 | * whole paragraph, and finally call whlp_end_para() to finish it |
147 | * off. |
148 | */ |
149 | enum { |
150 | WHLP_PARA_SPACEABOVE=1, WHLP_PARA_SPACEBELOW, WHLP_PARA_SPACELINES, |
151 | WHLP_PARA_LEFTINDENT, WHLP_PARA_RIGHTINDENT, WHLP_PARA_FIRSTLINEINDENT, |
152 | WHLP_PARA_ALIGNMENT |
153 | }; |
154 | enum { |
155 | WHLP_ALIGN_LEFT, WHLP_ALIGN_RIGHT, WHLP_ALIGN_CENTRE |
156 | }; |
157 | enum { |
158 | WHLP_PARA_SCROLL, WHLP_PARA_NONSCROLL |
159 | }; |
160 | void whlp_para_attr(WHLP h, int attr_id, int attr_param); |
161 | void whlp_set_tabstop(WHLP h, int tabstop, int alignment); |
162 | void whlp_begin_para(WHLP h, int para_type); |
163 | void whlp_end_para(WHLP h); |
164 | void whlp_set_font(WHLP h, int font_id); |
165 | void whlp_text(WHLP h, char *text); |
166 | void whlp_start_hyperlink(WHLP h, WHLP_TOPIC target); |
167 | void whlp_end_hyperlink(WHLP h); |
168 | void whlp_tab(WHLP h); |