2 * winhelp.h header file for winhelp.c
5 typedef struct WHLP_tag
*WHLP
;
7 typedef struct WHLP_TOPIC_tag
*WHLP_TOPIC
;
10 * Initialise a new WHlp context and begin accumulating data in it.
15 * Close a WHlp context and write out the help file it has created.
17 void whlp_close(WHLP h
, char *filename
);
20 * Abandon and free a WHlp context without writing out anything.
22 void whlp_abandon(WHLP h
);
25 * Specify the title and copyright notice of a help file. Also
26 * specify Help macros to be run on loading.
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
);
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.
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.
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
53 * On success (i.e. in any circumstance other than a hash clash), a
54 * valid WHLP_TOPIC is returned for later use.
56 WHLP_TOPIC
whlp_register_topic(WHLP h
, char *context_name
, char **clash
);
59 * Link two topics together in a browse sequence. Automatically
60 * takes care of the forward and reverse links.
62 void whlp_browse_link(WHLP h
, WHLP_TOPIC before
, WHLP_TOPIC after
);
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.
70 void whlp_prepare(WHLP h
);
73 * Create a link from an index term to a topic.
75 void whlp_index_term(WHLP h
, char *index
, WHLP_TOPIC topic
);
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.
83 * The string returned will be freed when the WHLP context is
84 * closed. You should not free it yourself.
86 * Do not call this before calling whlp_prepare().
88 char *whlp_topic_id(WHLP_TOPIC topic
);
91 * Call this to specify which help topic will be the first one
92 * displayed when the help file is loaded.
94 void whlp_primary_topic(WHLP h
, WHLP_TOPIC topic
);
97 * Call this when about to begin writing out the text for a topic.
99 * Any additional arguments are Help macros, terminated with a
100 * NULL. So the minimum call sequence is
102 * whlp_begin_topic(helpfile, mytopic, "Title", NULL);
104 void whlp_begin_topic(WHLP h
, WHLP_TOPIC topic
, char *title
, ...);
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
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.
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
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
136 int whlp_create_font(WHLP h
, char *font
, int family
, int halfpoints
,
137 int rendition
, int r
, int g
, int b
);
140 * Routines to output paragraphs and actual text (at last).
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
150 WHLP_PARA_SPACEABOVE
=1, WHLP_PARA_SPACEBELOW
, WHLP_PARA_SPACELINES
,
151 WHLP_PARA_LEFTINDENT
, WHLP_PARA_RIGHTINDENT
, WHLP_PARA_FIRSTLINEINDENT
,
155 WHLP_ALIGN_LEFT
, WHLP_ALIGN_RIGHT
, WHLP_ALIGN_CENTRE
158 WHLP_PARA_SCROLL
, WHLP_PARA_NONSCROLL
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
);