FL/Fl_Help_View.H

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