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); 169 170 /* 171 * Routines to add images to a help file. 172 * 173 * First call whlp_add_picture() to load some actual image data 174 * into a help file. This will return a numeric index which 175 * identifies the picture. Then you can call whlp_ref_picture() to 176 * indicate that that picture should be displayed inline in the 177 * current paragraph (i.e. it occurs between a call to 178 * whlp_begin_para() and whlp_end_para()). 179 */ 180 181 /* 182 * The parameters to this function are: 183 * 184 * - wd and ht give the width and height of the image in pixels. 185 * - picdata is a pointer to the actual bitmap data. This _must_ 186 * be formatted as one byte per pixel, with each byte being an 187 * index into the `palette' array. Ordering is the normal one 188 * (top to bottom, left to right), not the Windows BMP one. 189 * - palettelen is an array of up to 256 unsigned longs. Each 190 * unsigned long represents an RGB value, in the form 191 * 0x00RRGGBB. Thus 0x00FF0000 is red, 0x00FF00 is green, 192 * 0x000000FF is blue, 0x00FFFFFF is white, zero is black, and 193 * so on. You may supply fewer than 256 entries if the image 194 * data does not refer to all possible values. 195 */ 196 int whlp_add_picture(WHLP h, int wd, int ht, const void *picdata, 197 const unsigned long *palette); 198 void whlp_ref_picture(WHLP h, int index); 199