You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

380 lines
14KB

  1. //
  2. // "$Id: Fl_Browser_.H 8275 2011-01-13 22:07:31Z manolo $"
  3. //
  4. // Common browser header file for the Fast Light Tool Kit (FLTK).
  5. //
  6. // Copyright 1998-2010 by Bill Spitzak and others.
  7. //
  8. // This library is free software; you can redistribute it and/or
  9. // modify it under the terms of the GNU Library General Public
  10. // License as published by the Free Software Foundation; either
  11. // version 2 of the License, or (at your option) any later version.
  12. //
  13. // This library is distributed in the hope that it will be useful,
  14. // but WITHOUT ANY WARRANTY; without even the implied warranty of
  15. // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  16. // Library General Public License for more details.
  17. //
  18. // You should have received a copy of the GNU Library General Public
  19. // License along with this library; if not, write to the Free Software
  20. // Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
  21. // USA.
  22. //
  23. // Please report all bugs and problems on the following page:
  24. //
  25. // http://www.fltk.org/str.php
  26. //
  27. /* \file
  28. Fl_Browser_ widget . */
  29. // Yes, I know this should be a template...
  30. #ifndef Fl_Browser__H
  31. #define Fl_Browser__H
  32. #ifndef Fl_Group_H
  33. #include "Fl_Group.H"
  34. #endif
  35. #include "Fl_Scrollbar.H"
  36. #include <FL/Fl.H> // Fl::scrollbar_size()
  37. #define FL_NORMAL_BROWSER 0 /**< type() of Fl_Browser */
  38. #define FL_SELECT_BROWSER 1 /**< type() of FL_Select_Browser */
  39. #define FL_HOLD_BROWSER 2 /**< type() of Fl_Hold_Browser */
  40. #define FL_MULTI_BROWSER 3 /**< type() of Fl_Multi_Browser */
  41. #define FL_SORT_ASCENDING 0 /**< sort browser items in ascending alphabetic order. */
  42. #define FL_SORT_DESCENDING 1 /**< sort in descending order */
  43. /**
  44. This is the base class for browsers. To be useful it must be
  45. subclassed and several virtual functions defined. The Forms-compatible
  46. browser and the file chooser's browser are subclassed off of this.
  47. This has been designed so that the subclass has complete control
  48. over the storage of the data, although because next() and
  49. prev() functions are used to index, it works best as a linked list
  50. or as a large block of characters in which the line breaks must be
  51. searched for.
  52. A great deal of work has been done so that the "height" of a data
  53. object does not need to be determined until it is drawn. This is
  54. useful if actually figuring out the size of an object requires
  55. accessing image data or doing stat() on a file or doing some
  56. other slow operation.
  57. */
  58. class FL_EXPORT Fl_Browser_ : public Fl_Group {
  59. int position_; // where user wants it scrolled to
  60. int real_position_; // the current vertical scrolling position
  61. int hposition_; // where user wants it panned to
  62. int real_hposition_; // the current horizontal scrolling position
  63. int offset_; // how far down top_ item the real_position is
  64. int max_width; // widest object seen so far
  65. uchar has_scrollbar_; // which scrollbars are enabled
  66. Fl_Font textfont_;
  67. Fl_Fontsize textsize_;
  68. Fl_Color textcolor_;
  69. void* top_; // which item scrolling position is in
  70. void* selection_; // which is selected (except for FL_MULTI_BROWSER)
  71. void *redraw1,*redraw2; // minimal update pointers
  72. void* max_width_item; // which item has max_width_
  73. int scrollbar_size_; // size of scrollbar trough
  74. void update_top();
  75. protected:
  76. // All of the following must be supplied by the subclass:
  77. /**
  78. This method must be provided by the subclass
  79. to return the first item in the list.
  80. \see item_first(), item_next(), item_last(), item_prev()
  81. */
  82. virtual void *item_first() const = 0;
  83. /**
  84. This method must be provided by the subclass
  85. to return the item in the list after \p item.
  86. \see item_first(), item_next(), item_last(), item_prev()
  87. */
  88. virtual void *item_next(void *item) const = 0;
  89. /**
  90. This method must be provided by the subclass
  91. to return the item in the list before \p item.
  92. \see item_first(), item_next(), item_last(), item_prev()
  93. */
  94. virtual void *item_prev(void *item) const = 0;
  95. /**
  96. This method must be provided by the subclass
  97. to return the last item in the list.
  98. \see item_first(), item_next(), item_last(), item_prev()
  99. */
  100. virtual void *item_last() const { return 0L; }
  101. /**
  102. This method must be provided by the subclass to return
  103. the height of \p item in pixels.
  104. Allow for two additional pixels for the list selection box.
  105. \param[in] item The item whose height is returned.
  106. \returns The height of the specified \p item in pixels.
  107. \see item_height(), item_width(), item_quick_height()
  108. */
  109. virtual int item_height(void *item) const = 0;
  110. /**
  111. This method must be provided by the subclass to return the width of the
  112. \p item in pixels. Allow for two additional pixels for the list
  113. selection box.
  114. \param[in] item The item whose width is returned.
  115. \returns The width of the item in pixels.
  116. */
  117. virtual int item_width(void *item) const = 0;
  118. virtual int item_quick_height(void *item) const ;
  119. /**
  120. This method must be provided by the subclass to draw the \p item
  121. in the area indicated by \p X, \p Y, \p W, \p H.
  122. */
  123. virtual void item_draw(void *item,int X,int Y,int W,int H) const = 0;
  124. /**
  125. This optional method returns a string (label) that may be used for sorting.
  126. \param[in] item The item whose label text is returned.
  127. \returns The item's text label. (Can be NULL if blank)
  128. */
  129. virtual const char *item_text(void *item) const { (void)item; return 0L; }
  130. /**
  131. This optional method should be provided by the subclass
  132. to efficiently swap browser items \p a and \p b, such as for sorting.
  133. \param[in] a,b The two items to be swapped.
  134. */
  135. virtual void item_swap(void *a,void *b) { (void)a; (void)b; }
  136. /**
  137. This method must be provided by the subclass
  138. to return the item for the specified \p index.
  139. \param[in] index The \p index of the item to be returned
  140. \returns The item at the specified \p index.
  141. */
  142. virtual void *item_at(int index) const { (void)index; return 0L; }
  143. // you don't have to provide these but it may help speed it up:
  144. // These only need to be done by subclass if you want a multi-browser:
  145. virtual void item_select(void *item,int val=1);
  146. virtual int item_selected(void *item) const ;
  147. // things the subclass may want to call:
  148. /**
  149. Returns the item that appears at the top of the list.
  150. */
  151. void *top() const { return top_; }
  152. /**
  153. Returns the item currently selected, or NULL if there is no selection.
  154. For multiple selection browsers this call returns the currently focused item,
  155. even if it is not selected. To find all selected items, call
  156. Fl_Multi_Browser::selected() for every item in question.
  157. */
  158. void *selection() const { return selection_; }
  159. void new_list(); // completely clobber all data, as though list replaced
  160. void deleting(void *item); // get rid of any pointers to item
  161. void replacing(void *a,void *b); // change a pointers to b
  162. void swapping(void *a,void *b); // exchange pointers a and b
  163. void inserting(void *a,void *b); // insert b near a
  164. int displayed(void *item) const ; // true if this item is visible
  165. void redraw_line(void *item); // minimal update, no change in size
  166. /**
  167. This method will cause the entire list to be redrawn.
  168. \see redraw_lines(), redraw_line()
  169. */
  170. void redraw_lines() { damage(FL_DAMAGE_SCROLL); } // redraw all of them
  171. void bbox(int &X,int &Y,int &W,int &H) const;
  172. int leftedge() const; // x position after scrollbar & border
  173. void *find_item(int ypos); // item under mouse
  174. void draw();
  175. Fl_Browser_(int X,int Y,int W,int H,const char *L=0);
  176. public:
  177. virtual int full_width() const ; // current width of all items
  178. virtual int full_height() const ; // current height of all items
  179. virtual int incr_height() const ; // average height of an item
  180. /**
  181. Vertical scrollbar. Public, so that it can be accessed directly.
  182. */
  183. Fl_Scrollbar scrollbar;
  184. /**
  185. Horizontal scrollbar. Public, so that it can be accessed directly.
  186. */
  187. Fl_Scrollbar hscrollbar;
  188. int handle(int event);
  189. void resize(int X,int Y,int W,int H);
  190. int select(void *item,int val=1,int docallbacks=0);
  191. int select_only(void *item,int docallbacks=0);
  192. int deselect(int docallbacks=0);
  193. /**
  194. Gets the vertical scroll position of the list as a pixel position \p pos.
  195. The position returned is how many pixels of the list are scrolled off the top edge
  196. of the screen. Example: A position of '3' indicates the top 3 pixels of
  197. the list are scrolled off the top edge of the screen.
  198. \see position(), hposition()
  199. */
  200. int position() const { return position_; }
  201. void position(int pos); // scroll to here
  202. /**
  203. Gets the horizontal scroll position of the list as a pixel position \p pos.
  204. The position returned is how many pixels of the list are scrolled off the left edge
  205. of the screen. Example: A position of '18' indicates the left 18 pixels of
  206. the list are scrolled off the left edge of the screen.
  207. \see position(), hposition()
  208. */
  209. int hposition() const { return hposition_; }
  210. void hposition(int); // pan to here
  211. void display(void *item); // scroll so this item is shown
  212. /**
  213. Values for has_scrollbar().
  214. */
  215. /** Anonymous enum bit flags for has_scrollbar().
  216. - bit 0: horizontal
  217. - bit 1: vertical
  218. - bit 2: 'always' (to be combined with bits 0 and 1)
  219. - bit 3-31: reserved for future use
  220. */
  221. enum { // values for has_scrollbar()
  222. HORIZONTAL = 1, ///< Only show horizontal scrollbar.
  223. VERTICAL = 2, ///< Only show vertical scrollbar.
  224. BOTH = 3, ///< Show both scrollbars. (default)
  225. ALWAYS_ON = 4, ///< Specified scrollbar(s) should 'always' be shown (to be used with HORIZONTAL/VERTICAL)
  226. HORIZONTAL_ALWAYS = 5, ///< Horizontal scrollbar always on.
  227. VERTICAL_ALWAYS = 6, ///< Vertical scrollbar always on.
  228. BOTH_ALWAYS = 7 ///< Both scrollbars always on.
  229. };
  230. /**
  231. Returns the current scrollbar mode, see Fl_Browser_::has_scrollbar(uchar)
  232. */
  233. uchar has_scrollbar() const { return has_scrollbar_; }
  234. /**
  235. Sets whether the widget should have scrollbars or not (default Fl_Browser_::BOTH).
  236. By default you can scroll in both directions, and the scrollbars
  237. disappear if the data will fit in the widget.
  238. has_scrollbar() changes this based on the value of \p mode:
  239. - 0 - No scrollbars.
  240. - Fl_Browser_::HORIZONTAL - Only a horizontal scrollbar.
  241. - Fl_Browser_::VERTICAL - Only a vertical scrollbar.
  242. - Fl_Browser_::BOTH - The default is both scrollbars.
  243. - Fl_Browser_::HORIZONTAL_ALWAYS - Horizontal scrollbar always on,
  244. vertical always off.
  245. - Fl_Browser_::VERTICAL_ALWAYS - Vertical scrollbar always on,
  246. horizontal always off.
  247. - Fl_Browser_::BOTH_ALWAYS - Both always on.
  248. */
  249. void has_scrollbar(uchar mode) { has_scrollbar_ = mode; }
  250. /**
  251. Gets the default text font for the lines in the browser.
  252. \see textfont(), textsize(), textcolor()
  253. */
  254. Fl_Font textfont() const { return textfont_; }
  255. /**
  256. Sets the default text font for the lines in the browser to \p font.
  257. */
  258. void textfont(Fl_Font font) { textfont_ = font; }
  259. /**
  260. Gets the default text size (in pixels) for the lines in the browser.
  261. */
  262. Fl_Fontsize textsize() const { return textsize_; }
  263. /**
  264. Sets the default text size (in pixels) for the lines in the browser to \p size.
  265. */
  266. void textsize(Fl_Fontsize size) { textsize_ = size; }
  267. /**
  268. Gets the default text color for the lines in the browser.
  269. */
  270. Fl_Color textcolor() const { return textcolor_; }
  271. /**
  272. Sets the default text color for the lines in the browser to color \p col.
  273. */
  274. void textcolor(Fl_Color col) { textcolor_ = col; }
  275. /**
  276. Gets the current size of the scrollbars' troughs, in pixels.
  277. If this value is zero (default), this widget will use the
  278. Fl::scrollbar_size() value as the scrollbar's width.
  279. \returns Scrollbar size in pixels, or 0 if the global Fl::scrollsize() is being used.
  280. \see Fl::scrollbar_size(int)
  281. */
  282. int scrollbar_size() const {
  283. return(scrollbar_size_);
  284. }
  285. /**
  286. Sets the pixel size of the scrollbars' troughs to the \p size, in pixels.
  287. Normally you should not need this method, and should use
  288. Fl::scrollbar_size(int) instead to manage the size of ALL
  289. your widgets' scrollbars. This ensures your application
  290. has a consistent UI, is the default behavior, and is normally
  291. what you want.
  292. Only use THIS method if you really need to override the global
  293. scrollbar size. The need for this should be rare.
  294. Setting \p size to the special value of 0 causes the widget to
  295. track the global Fl::scrollbar_size(), which is the default.
  296. \param[in] size Sets the scrollbar size in pixels.\n
  297. If 0 (default), scrollbar size tracks the global Fl::scrollbar_size()
  298. \see Fl::scrollbar_size()
  299. */
  300. void scrollbar_size(int size) {
  301. scrollbar_size_ = size;
  302. }
  303. /**
  304. This method has been deprecated, existing for backwards compatibility only.
  305. Use scrollbar_size() instead.
  306. This method always returns the global value Fl::scrollbar_size().
  307. \returns Always returns the global value Fl::scrollbar_size().
  308. \todo This method should eventually be removed in 1.4+
  309. */
  310. int scrollbar_width() const {
  311. return(Fl::scrollbar_size());
  312. }
  313. /**
  314. This method has been deprecated, existing for backwards compatibility only.
  315. Use scrollbar_size(int) instead.
  316. This method sets the global Fl::scrollbar_size(), and forces this
  317. instance of the widget to use it.
  318. \todo This method should eventually be removed in 1.4+
  319. */
  320. void scrollbar_width(int width) {
  321. Fl::scrollbar_size(width);
  322. scrollbar_size_ = 0;
  323. }
  324. /**
  325. Moves the vertical scrollbar to the righthand side of the list.
  326. For back compatibility.
  327. */
  328. void scrollbar_right() { scrollbar.align(FL_ALIGN_RIGHT); }
  329. /**
  330. Moves the vertical scrollbar to the lefthand side of the list.
  331. For back compatibility.
  332. */
  333. void scrollbar_left() { scrollbar.align(FL_ALIGN_LEFT); }
  334. void sort(int flags=0);
  335. };
  336. #endif
  337. //
  338. // End of "$Id: Fl_Browser_.H 8275 2011-01-13 22:07:31Z manolo $".
  339. //