1 //
2 // "$Id$"
3 //
4 // Help Viewer widget definitions.
5 //
6 // Copyright 1997-2010 by Easy Software Products.
7 // Image support by Matthias Melcher, Copyright 2000-2009.
8 //
9 // This library is free software. Distribution and use rights are outlined in
10 // the file "COPYING" which should have been included with this file.  If this
11 // file is missing or damaged, see the license at:
12 //
13 //     http://www.fltk.org/COPYING.php
14 //
15 // Please report all bugs and problems on the following page:
16 //
17 //     http://www.fltk.org/str.php
18 //
19 
20 /* \file
21    Fl_Help_View widget . */
22 
23 #ifndef Fl_Help_View_H
24 #  define Fl_Help_View_H
25 
26 //
27 // Include necessary header files...
28 //
29 
30 #  include <stdio.h>
31 #  include "Fl.H"
32 #  include "Fl_Group.H"
33 #  include "Fl_Scrollbar.H"
34 #  include "fl_draw.H"
35 #  include "Fl_Shared_Image.H"
36 #  include "filename.H"
37 
38 
39 //
40 // Fl_Help_Func type - link callback function for files...
41 //
42 
43 
44 typedef const char *(Fl_Help_Func)(Fl_Widget *, const char *);
45 
46 
47 //
48 // Fl_Help_Block structure...
49 //
50 
51 struct Fl_Help_Block {
52   const char	*start,		// Start of text
53 		*end;		// End of text
54   uchar		border;		// Draw border?
55   Fl_Color	bgcolor;	// Background color
56   int		x,		// Indentation/starting X coordinate
57 		y,		// Starting Y coordinate
58 		w,		// Width
59 		h;		// Height
60   int		line[32];	// Left starting position for each line
61 };
62 
63 //
64 // Fl_Help_Link structure...
65 //
66 /** Definition of a link for the html viewer. */
67 struct Fl_Help_Link {
68   char		filename[192],	///< Reference filename
69 		name[32];	///< Link target (blank if none)
70   int		x,		///< X offset of link text
71 		y,		///< Y offset of link text
72 		w,		///< Width of link text
73 		h;		///< Height of link text
74 };
75 
76 /*
77  * Fl_Help_View font stack opaque implementation
78  */
79 
80 /** Fl_Help_View font stack element definition. */
81 struct FL_EXPORT Fl_Help_Font_Style {
82   Fl_Font      f;  ///< Font
83   Fl_Fontsize  s;  ///< Font Size
84   Fl_Color     c;  ///< Font Color
getFl_Help_Font_Style85   void get(Fl_Font &afont, Fl_Fontsize &asize, Fl_Color &acolor) {afont=f; asize=s; acolor=c;} ///< Gets current font attributes
setFl_Help_Font_Style86   void set(Fl_Font afont, Fl_Fontsize asize, Fl_Color acolor) {f=afont; s=asize; c=acolor;} ///< Sets current font attributes
Fl_Help_Font_StyleFl_Help_Font_Style87   Fl_Help_Font_Style(Fl_Font afont, Fl_Fontsize asize, Fl_Color acolor) {set(afont, asize, acolor);}
Fl_Help_Font_StyleFl_Help_Font_Style88   Fl_Help_Font_Style(){} // For in table use
89 };
90 
91 /** Fl_Help_View font stack definition. */
92 const size_t MAX_FL_HELP_FS_ELTS = 100;
93 
94 struct FL_EXPORT Fl_Help_Font_Stack {
95   /** font stack construction, initialize attributes. */
Fl_Help_Font_StackFl_Help_Font_Stack96   Fl_Help_Font_Stack() {
97     nfonts_ = 0;
98   }
99 
initFl_Help_Font_Stack100   void init(Fl_Font f, Fl_Fontsize s, Fl_Color c) {
101     nfonts_ = 0;
102     elts_[nfonts_].set(f, s, c);
103     fl_font(f, s);
104     fl_color(c);
105   }
106   /** Gets the top (current) element on the stack. */
topFl_Help_Font_Stack107   void top(Fl_Font &f, Fl_Fontsize &s, Fl_Color &c) { elts_[nfonts_].get(f, s, c); }
108   /** Pushes the font style triplet on the stack, also calls fl_font() & fl_color() adequately */
pushFl_Help_Font_Stack109   void push(Fl_Font f, Fl_Fontsize s, Fl_Color c) {
110     if (nfonts_ <  MAX_FL_HELP_FS_ELTS-1) nfonts_ ++;
111     elts_[nfonts_].set(f, s, c);
112     fl_font(f, s); fl_color(c);
113   }
114   /** Pops from the stack the font style triplet and calls fl_font() & fl_color() adequately */
popFl_Help_Font_Stack115   void pop(Fl_Font &f, Fl_Fontsize &s, Fl_Color &c) {
116     if (nfonts_ > 0) nfonts_ --;
117     top(f, s, c);
118     fl_font(f, s); fl_color(c);
119   }
120   /** Gets the current count of font style elements in the stack. */
countFl_Help_Font_Stack121   size_t count() const {return nfonts_;} // Gets the current number of fonts in the stack
122 
123 protected:
124   size_t nfonts_;		///< current number of fonts in stack
125   Fl_Help_Font_Style elts_[100]; ///< font elements
126 };
127 
128 /** Fl_Help_Target structure */
129 
130 struct Fl_Help_Target {
131   char		name[32];	///< Target name
132   int		y;		///< Y offset of target
133 };
134 
135 /**
136   The Fl_Help_View widget displays HTML text. Most HTML 2.0
137   elements are supported, as well as a primitive implementation of tables.
138   GIF, JPEG, and PNG images are displayed inline.
139 
140   Supported HTML tags:
141      - A: HREF/NAME
142      - B
143      - BODY: BGCOLOR/TEXT/LINK
144      - BR
145      - CENTER
146      - CODE
147      - DD
148      - DL
149      - DT
150      - EM
151      - FONT: COLOR/SIZE/FACE=(helvetica/arial/sans/times/serif/symbol/courier)
152      - H1/H2/H3/H4/H5/H6
153      - HEAD
154      - HR
155      - I
156      - IMG: SRC/WIDTH/HEIGHT/ALT
157      - KBD
158      - LI
159      - OL
160      - P
161      - PRE
162      - STRONG
163      - TABLE: TH/TD/TR/BORDER/BGCOLOR/COLSPAN/ALIGN=CENTER|RIGHT|LEFT
164      - TITLE
165      - TT
166      - U
167      - UL
168      - VAR
169 
170   Supported color names:
171      - black,red,green,yellow,blue,magenta,fuchsia,cyan,aqua,white,gray,grey,lime,maroon,navy,olive,purple,silver,teal.
172 
173   Supported urls:
174      - Internal: file:
175      - External: http: ftp: https: ipp: mailto: news:
176 
177   Quoted char names:
178      - Aacute aacute Acirc acirc acute AElig aelig Agrave agrave amp Aring aring Atilde atilde Auml auml
179      - brvbar bull
180      - Ccedil ccedil cedil cent copy curren
181      - deg divide
182      - Eacute eacute Ecirc ecirc Egrave egrave ETH eth Euml euml euro
183      - frac12 frac14 frac34
184      - gt
185      - Iacute iacute Icirc icirc iexcl Igrave igrave iquest Iuml iuml
186      - laquo lt
187      - macr micro middot
188      - nbsp not Ntilde ntilde
189      - Oacute oacute Ocirc ocirc Ograve ograve ordf ordm Oslash oslash Otilde otilde Ouml ouml
190      - para permil plusmn pound
191      - quot
192      - raquo reg
193      - sect shy sup1 sup2 sup3 szlig
194      - THORN thorn times trade
195      - Uacute uacute Ucirc ucirc Ugrave ugrave uml Uuml uuml
196      - Yacute yacute
197      - yen Yuml yuml
198 
199 */
200 class FL_EXPORT Fl_Help_View : public Fl_Group {	// Help viewer widget
201 
202   enum { RIGHT = -1, CENTER, LEFT };	///< Alignments
203 
204   char		title_[1024];		///< Title string
205   Fl_Color	defcolor_,		///< Default text color
206 		bgcolor_,		///< Background color
207 		textcolor_,		///< Text color
208 		linkcolor_;		///< Link color
209   Fl_Font       textfont_;		///< Default font for text
210   Fl_Fontsize  textsize_;		///< Default font size
211   const char	*value_;		///< HTML text value
212   Fl_Help_Font_Stack fstack_;		///< font stack management
213   int		nblocks_,		///< Number of blocks/paragraphs
214 		ablocks_;		///< Allocated blocks
215   Fl_Help_Block	*blocks_;		///< Blocks
216 
217   Fl_Help_Func	*link_;			///< Link transform function
218 
219   int		nlinks_,		///< Number of links
220 		alinks_;		///< Allocated links
221   Fl_Help_Link	*links_;		///< Links
222 
223   int		ntargets_,		///< Number of targets
224 		atargets_;		///< Allocated targets
225   Fl_Help_Target *targets_;		///< Targets
226 
227   char		directory_[FL_PATH_MAX];///< Directory for current file
228   char		filename_[FL_PATH_MAX];	///< Current filename
229   int		topline_,		///< Top line in document
230 		leftline_,		///< Lefthand position
231 		size_,			///< Total document length
232 		hsize_,			///< Maximum document width
233   		scrollbar_size_;	///< Size for both scrollbars
234   Fl_Scrollbar	scrollbar_,		///< Vertical scrollbar for document
235 		hscrollbar_;		///< Horizontal scrollbar
236 
237   static int    selection_first;
238   static int    selection_last;
239   static int    selection_push_first;
240   static int    selection_push_last;
241   static int    selection_drag_first;
242   static int    selection_drag_last;
243   static int    selected;
244   static int    draw_mode;
245   static int    mouse_x;
246   static int    mouse_y;
247   static int    current_pos;
248   static Fl_Help_View *current_view;
249   static Fl_Color hv_selection_color;
250   static Fl_Color hv_selection_text_color;
251 
252 
initfont(Fl_Font & f,Fl_Fontsize & s,Fl_Color & c)253   void initfont(Fl_Font &f, Fl_Fontsize &s, Fl_Color &c) { f = textfont_; s = textsize_; c = textcolor_; fstack_.init(f, s, c); }
pushfont(Fl_Font f,Fl_Fontsize s)254   void pushfont(Fl_Font f, Fl_Fontsize s) {fstack_.push(f, s, textcolor_);}
pushfont(Fl_Font f,Fl_Fontsize s,Fl_Color c)255   void pushfont(Fl_Font f, Fl_Fontsize s, Fl_Color c) {fstack_.push(f, s, c);}
popfont(Fl_Font & f,Fl_Fontsize & s,Fl_Color & c)256   void popfont(Fl_Font &f, Fl_Fontsize &s, Fl_Color &c) {fstack_.pop(f, s, c);}
257 
258   Fl_Help_Block	*add_block(const char *s, int xx, int yy, int ww, int hh, uchar border = 0);
259   void		add_link(const char *n, int xx, int yy, int ww, int hh);
260   void		add_target(const char *n, int yy);
261   static int	compare_targets(const Fl_Help_Target *t0, const Fl_Help_Target *t1);
262   int		do_align(Fl_Help_Block *block, int line, int xx, int a, int &l);
263 #if FLTK_ABI_VERSION >= 10303
264 protected:
265 #endif
266   void		draw();
267 #if FLTK_ABI_VERSION >= 10303
268 private:
269 #endif
270   void		format();
271   void		format_table(int *table_width, int *columns, const char *table);
272   void		free_data();
273   int		get_align(const char *p, int a);
274   const char	*get_attr(const char *p, const char *n, char *buf, int bufsize);
275   Fl_Color	get_color(const char *n, Fl_Color c);
276   Fl_Shared_Image *get_image(const char *name, int W, int H);
277   int		get_length(const char *l);
278 #if FLTK_ABI_VERSION >= 10303
279 public:
280 #endif
281   int		handle(int);
282 #if FLTK_ABI_VERSION >= 10303
283 private:
284 #endif
285 
286   void          hv_draw(const char *t, int x, int y, int entity_extra_length = 0);
287   char          begin_selection();
288   char          extend_selection();
289   void          end_selection(int c=0);
290   void          clear_global_selection();
291   Fl_Help_Link  *find_link(int, int);
292   void          follow_link(Fl_Help_Link*);
293 
294 public:
295 
296   Fl_Help_View(int xx, int yy, int ww, int hh, const char *l = 0);
297   ~Fl_Help_View();
298   /** Returns the current directory for the text in the buffer. */
directory()299   const char	*directory() const { if (directory_[0]) return (directory_);
300   					else return ((const char *)0); }
301   /** Returns the current filename for the text in the buffer. */
filename()302   const char	*filename() const { if (filename_[0]) return (filename_);
303   					else return ((const char *)0); }
304   int		find(const char *s, int p = 0);
305   /**
306     This method assigns a callback function to use when a link is
307     followed or a file is loaded (via Fl_Help_View::load()) that
308     requires a different file or path.
309 
310     The callback function receives a pointer to the Fl_Help_View
311     widget and the URI or full pathname for the file in question.
312     It must return a pathname that can be opened as a local file or NULL:
313 
314     \code
315     const char *fn(Fl_Widget *w, const char *uri);
316     \endcode
317 
318     The link function can be used to retrieve remote or virtual
319     documents, returning a temporary file that contains the actual
320     data. If the link function returns NULL, the value of
321     the Fl_Help_View widget will remain unchanged.
322 
323     If the link callback cannot handle the URI scheme, it should
324     return the uri value unchanged or set the value() of the widget
325     before returning NULL.
326   */
link(Fl_Help_Func * fn)327   void		link(Fl_Help_Func *fn) { link_ = fn; }
328   int		load(const char *f);
329   void		resize(int,int,int,int);
330   /** Gets the size of the help view. */
size()331   int		size() const { return (size_); }
size(int W,int H)332   void		size(int W, int H) { Fl_Widget::size(W, H); }
333   /** Sets the default text color. */
textcolor(Fl_Color c)334   void		textcolor(Fl_Color c) { if (textcolor_ == defcolor_) textcolor_ = c; defcolor_ = c; }
335   /** Returns the current default text color. */
textcolor()336   Fl_Color	textcolor() const { return (defcolor_); }
337   /** Sets the default text font. */
textfont(Fl_Font f)338   void		textfont(Fl_Font f) { textfont_ = f; format(); }
339   /** Returns the current default text font. */
textfont()340   Fl_Font       textfont() const { return (textfont_); }
341   /** Sets the default text size. */
textsize(Fl_Fontsize s)342   void		textsize(Fl_Fontsize s) { textsize_ = s; format(); }
343   /** Gets the default text size. */
textsize()344   Fl_Fontsize  textsize() const { return (textsize_); }
345   /** Returns the current document title, or NULL if there is no title. */
title()346   const char	*title() { return (title_); }
347   void		topline(const char *n);
348   void		topline(int);
349   /** Returns the current top line in pixels. */
topline()350   int		topline() const { return (topline_); }
351   void		leftline(int);
352   /** Gets the left position in pixels. */
leftline()353   int		leftline() const { return (leftline_); }
354   void		value(const char *val);
355   /** Returns the current buffer contents. */
value()356   const char	*value() const { return (value_); }
357   void          clear_selection();
358   void          select_all();
359   /**
360     Gets the current size of the scrollbars' troughs, in pixels.
361 
362     If this value is zero (default), this widget will use the
363     Fl::scrollbar_size() value as the scrollbar's width.
364 
365     \returns Scrollbar size in pixels, or 0 if the global Fl::scrollbar_size() is being used.
366     \see Fl::scrollbar_size(int)
367   */
scrollbar_size()368   int scrollbar_size() const {
369       return(scrollbar_size_);
370   }
371   /**
372     Sets the pixel size of the scrollbars' troughs to \p newSize, in pixels.
373 
374     Normally you should not need this method, and should use
375     Fl::scrollbar_size(int) instead to manage the size of ALL
376     your widgets' scrollbars. This ensures your application
377     has a consistent UI, is the default behavior, and is normally
378     what you want.
379 
380     Only use THIS method if you really need to override the global
381     scrollbar size. The need for this should be rare.
382 
383     Setting \p newSize to the special value of 0 causes the widget to
384     track the global Fl::scrollbar_size(), which is the default.
385 
386     \param[in] newSize Sets the scrollbar size in pixels.\n
387                     If 0 (default), scrollbar size tracks the global Fl::scrollbar_size()
388     \see Fl::scrollbar_size()
389   */
scrollbar_size(int newSize)390   void scrollbar_size(int newSize) {
391       scrollbar_size_ = newSize;
392   }
393 };
394 
395 #endif // !Fl_Help_View_H
396 
397 //
398 // End of "$Id$".
399 //
400