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