| 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); |