include/sfx2/thumbnailview.hxx

   1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
   2 /*
   3  * This file is part of the LibreOffice project.
   4  *
   5  * This Source Code Form is subject to the terms of the Mozilla Public
   6  * License, v. 2.0. If a copy of the MPL was not distributed with this
   7  * file, You can obtain one at http://mozilla.org/MPL/2.0/.
   8  */
   9
  10 #ifndef THUMBNAILVIEW_HXX
  11 #define THUMBNAILVIEW_HXX
  12
  13 #include "sfx2/dllapi.h"
  14
  15 #include <vector>
  16 #include <boost/function.hpp>
  17
  18 #include <sfx2/thumbnailviewitem.hxx>
  19 #include <vcl/ctrl.hxx>
  20 #include <vcl/timer.hxx>
  21
  22 class BitmapEx;
  23 class MouseEvent;
  24 class TrackingEvent;
  25 class HelpEvent;
  26 class KeyEvent;
  27 class DataChangedEvent;
  28 class ScrollBar;
  29 typedef ::std::vector< ThumbnailViewItem* > ValueItemList;
  30
  31 struct ThumbnailItemAttributes;
  32 class ThumbnailViewAcc;
  33 class ThumbnailViewItemAcc;
  34
  35 namespace drawinglayer {
  36     namespace processor2d {
  37         class BaseProcessor2D;
  38     }
  39 }
  40
  41 /*************************************************************************
  42
  43     Description
  44     ============
  45
  46     class ThumbnailView
  47
  48     This class allows the selection of an item. In the process items are
  49     drawn side by side. The selection of items can be more clear than in a
  50     ListBox shape for example in case of colors or samples.
  51     The amount of columns drawn by the control and whether the items
  52     should be encircled can be specified. Optional a NoSelection or name
  53     field could be shown. By default image and color items are supported.
  54     Items could be drawn by oneself if InsertItem() is only called with
  55     an ID. To achieve this the UserDraw handler needs to be overloaded. The
  56     description text could be specified afterwards in case of UserDraw
  57     and any other items.
  58
  59     Cross references
  60
  61     class ListBox
  62
  63     --------------------------------------------------------------------------
  64
  65     WinBits
  66
  67     WB_VSCROLL          A scroolbar will be always shown. The visible number of
  68                         lines have to be specified with SetLineCount() if this
  69                         flag is set.
  70     WB_TABSTOP          It is possible to jump into the ValueSet with the tab key.
  71     WB_NOTABSTOP        It is not possible to jump into the ValueSet with the
  72                         tab key.
  73     --------------------------------------------------------------------------
  74
  75     The number of columns must be either set with SetColCount() or
  76     SetItemWidth(). If the number of colums is specified by SetColCount()
  77     the width of the items will be calculated by the visible range.
  78     If the items should have a static width, it has to be specified
  79     with SetItemWidth(). In this case the number of columns will be calculated
  80     by the visible range.
  81
  82     The number of rows is given by the number of items / number of columns. The
  83     number of visible rows must either specified by SetLineCount() or
  84     SetItemWidth(). If the number of visible rows is specified by SetLineCount(),
  85     the height of the items will be calculated from the visible height. If the
  86     items should have a fixed height it has to be specified with SetItemHeight().
  87     In this case the number of visible rows is then calculated from the visible
  88     height. If the number of visible rows is neither specified by SetLineCount()
  89     nor by SetItemHeight() all rows will be shown. The height of the items will
  90     be calculated by the visible height. If the number of visible rows is
  91     specified by SetLineCount() or SetItemHeight() ValueSet does scroll
  92     automatically when more lines are available, as are visible. If scrolling
  93     should be also possible with a ScrollBar  WB_VSCROLL needs to be set.
  94
  95     The distance between the items can be increased by SetExtraSpacing(). The
  96     distance, which will be shown between two items (both in x and in y), is
  97     measured in pixels.
  98
  99     The exact window size for a specific item size can be calculated by
 100     CalcWindowSizePixel(). To do this all relevant data (number of columns/...)
 101     have to be specified and if no number of rows was set, all items need to
 102     be inserted. If the window was created with WB_BORDER/Border=sal_True the
 103     size has to be specified with SetOutputSizePixel(). In other cases different
 104     size-methods can be used. With CalcItemSize() the inner and outer size of
 105     an item could be calculated (for this the free space defined by
 106     SetExtraSpacing() will not be included).
 107
 108     The background color could be specified by SetColor(), with which the image
 109     or UserDraw items will be underlayed. If no color is specified the color
 110     of other windows (WindowColor) will be used for the background.
 111
 112     --------------------------------------------------------------------------
 113
 114     At first all items should be inserted and only then Show() should be called
 115     since the output area will be precomputed. If this is not done the first
 116     Paint will appear a little bit slower. Therefore the Control, if it is loaded
 117     from the resource and only supplied with items during runtime, should be
 118     loaded with Hide = sal_True and then displayed with Show().
 119
 120     In case of a visible Control the creation of the new output area could be
 121     activated before Paint by calling Format().
 122
 123     --------------------------------------------------------------------------
 124
 125     If Drag and Drop will be called from the ValueSet the Command-Handler has to
 126     be overloaded. From this StartDrag needs to be called. If this method returns
 127     sal_True the drag-process could be initiated by  ExecuteDrag(), otherwise no
 128     processing will take place. This method makes sure that ValueSet stops its
 129     processing and as appropriate selects the entry. Therefore the calling of
 130     Select-Handler within this function must be expected.
 131
 132     For dropping QueryDrop() and Drop() need to be overloaded and ShowDropPos()
 133     and HideDropPos() should be called within these methods.
 134     To show the insertion point ShowDropPos() has to be called within the
 135     QueryDrop-Handler. ShowDropPos() also scrolls the ValueSet if the passed
 136     position is located at the window border. Furthermore ShowDropPos() returns
 137     the position, at which the item should be inserted respectively which
 138     insertion point was shown. If no insertion point was determined
 139     VALUESET_ITEM_NOTFOUND will be returned. If the window was left during dragging
 140     or the drag process is terminated HideDropPos() should be called in any case.
 141
 142     --------------------------------------------------------------------------
 143
 144     This class is currently still in the SV-Tools. That's why the ValueSet needs
 145     to be loaded as a Control out of the resource and the desired WinBits have
 146     to be set (before Show) with SetStyle().
 147
 148 *************************************************************************/
 149
 150 /* ThumbnailView types */
 151
 152 #define THUMBNAILVIEW_APPEND         ((sal_uInt16)-1)
 153 #define THUMBNAILVIEW_ITEM_NOTFOUND  ((sal_uInt16)-1)
 154
 155 // Display all the available items in the thumbnail.
 156 class ViewFilterAll
 157 {
 158 public:
 159
 160     bool operator () (const ThumbnailViewItem*) const
 161     {
 162         return true;
 163     }
 164 };
 165
 166 /**
 167  *
 168  *  Class to display thumbnails with their names below their respective icons
 169  *
 170  **/
 171
 172 class SFX2_DLLPUBLIC ThumbnailView : public Control
 173 {
 174 public:
 175
 176     ThumbnailView ( Window* pParent, WinBits nWinStyle = WB_TABSTOP, bool bDisableTransientChildren = false );
 177
 178     ThumbnailView ( Window* pParent, const ResId& rResId, bool bDisableTransientChildren = false );
 179
 180     virtual ~ThumbnailView ();
 181
 182     void AppendItem (ThumbnailViewItem *pItem);
 183
 184     void RemoveItem( sal_uInt16 nItemId );
 185
 186     void Clear();
 187
 188     // Change current thumbnail item list with new one (invalidates all pointers to a thumbnail item)
 189     void updateItems(const std::vector<ThumbnailViewItem *> &items);
 190
 191     size_t GetItemPos( sal_uInt16 nItemId ) const;
 192
 193     sal_uInt16 GetItemId( size_t nPos ) const;
 194
 195     sal_uInt16 GetItemId( const Point& rPos ) const;
 196
 197     sal_uInt16 getNextItemId () const;
 198
 199     long GetItemWidth() const { return mnItemWidth; }
 200
 201     long GetItemHeight() const { return mnItemHeight; }
 202
 203     void setItemMaxTextLength (sal_uInt32 nLength);
 204
 205     void setItemDimensions (long ItemWidth, long ThumbnailHeight,
 206                             long DisplayHeight, int itemPadding);
 207
 208     sal_uInt16 GetFirstLine() const { return mnFirstLine; }
 209
 210     void SelectItem( sal_uInt16 nItemId );
 211
 212     void DeselectItem( sal_uInt16 nItemId );
 213
 214     bool IsItemSelected( sal_uInt16 nItemId ) const;
 215
 216     /**
 217      *
 218      * @brief deselect all current selected items.
 219      *
 220      **/
 221
 222     void deselectItems ();
 223
 224     OUString GetItemText( sal_uInt16 nItemId ) const;
 225
 226     void SetColor( const Color& rColor );
 227
 228     void SetColor() { SetColor( Color( COL_TRANSPARENT ) ); }
 229
 230     Color GetColor() const { return maColor; }
 231
 232     bool IsColor() const { return maColor.GetTransparency() == 0; }
 233
 234     void filterItems (const boost::function<bool (const ThumbnailViewItem*) > &func);
 235
 236     void sortItems (const boost::function<bool (const ThumbnailViewItem*,
 237                                                 const ThumbnailViewItem*) > &func);
 238
 239     void setItemStateHdl (const Link &aLink) { maItemStateHdl = aLink; }
 240
 241     virtual void Resize();
 242
 243     virtual bool renameItem(ThumbnailViewItem* pItem, OUString sNewTitle);
 244
 245 protected:
 246
 247     virtual void KeyInput( const KeyEvent& rKEvt );
 248
 249     virtual void MouseButtonDown( const MouseEvent& rMEvt );
 250
 251     virtual void MouseButtonUp( const MouseEvent& rMEvt );
 252
 253     virtual void Command( const CommandEvent& rCEvt );
 254
 255     virtual void Paint( const Rectangle& rRect );
 256
 257     virtual void GetFocus();
 258
 259     virtual void LoseFocus();
 260
 261     virtual void StateChanged( StateChangedType nStateChange );
 262
 263     virtual void DataChanged( const DataChangedEvent& rDCEvt );
 264
 265     virtual ::com::sun::star::uno::Reference< ::com::sun::star::accessibility::XAccessible > CreateAccessible();
 266
 267 protected:
 268
 269     // Drawing item related functions, override them to make your own custom ones.
 270
 271     virtual void DrawItem (ThumbnailViewItem *pItem);
 272
 273     virtual void OnItemDblClicked (ThumbnailViewItem *pItem);
 274
 275 protected:
 276
 277     friend class ThumbnailViewAcc;
 278     friend class ThumbnailViewItemAcc;
 279     using Control::ImplInitSettings;
 280     using Window::ImplInit;
 281
 282     void CalculateItemPositions ();
 283     void MakeItemVisible( sal_uInt16 nId );
 284
 285     SFX2_DLLPRIVATE void         ImplInit();
 286     SFX2_DLLPRIVATE void         ImplInitSettings( bool bFont, bool bForeground, bool bBackground );
 287     SFX2_DLLPRIVATE void         ImplInitScrollBar();
 288     SFX2_DLLPRIVATE void         ImplDeleteItems();
 289     SFX2_DLLPRIVATE void         ImplDraw();
 290     SFX2_DLLPRIVATE size_t       ImplGetItem( const Point& rPoint, bool bMove = false ) const;
 291     SFX2_DLLPRIVATE ThumbnailViewItem*    ImplGetItem( size_t nPos );
 292     SFX2_DLLPRIVATE sal_uInt16          ImplGetVisibleItemCount() const;
 293     SFX2_DLLPRIVATE ThumbnailViewItem*    ImplGetVisibleItem( sal_uInt16 nVisiblePos );
 294     SFX2_DLLPRIVATE void            ImplFireAccessibleEvent( short nEventId, const ::com::sun::star::uno::Any& rOldValue, const ::com::sun::star::uno::Any& rNewValue );
 295     SFX2_DLLPRIVATE bool         ImplHasAccessibleListeners();
 296     DECL_DLLPRIVATE_LINK( ImplScrollHdl, ScrollBar* );
 297
 298     DECL_LINK(OnItemSelected, ThumbnailViewItem*);
 299
 300 protected:
 301
 302     ValueItemList mItemList;
 303     ValueItemList mFilteredItemList; ///< Cache to store the filtered items
 304     ValueItemList::iterator mpStartSelRange;
 305     ScrollBar* mpScrBar;
 306     Rectangle maItemListRect;
 307     long mnHeaderHeight;
 308     long mnItemWidth;
 309     long mnItemHeight;
 310     long mnItemPadding;
 311     long mnThumbnailHeight;     // Maximum height of the thumbnail
 312     long mnDisplayHeight;       // Height of the data display box (name, etc)
 313     long mnVisLines;
 314     long mnLines;
 315     sal_uInt16 mnHighItemId;
 316     sal_uInt16 mnCols;
 317     sal_uInt16 mnFirstLine;
 318     sal_uInt16 mnSpacing;
 319     bool mbScroll : 1;
 320     bool mbIsTransientChildrenDisabled : 1;
 321     bool mbHasVisibleItems : 1;
 322     Color maColor;
 323
 324     Link maItemStateHdl;
 325     ThumbnailItemAttributes *mpItemAttrs;
 326     drawinglayer::processor2d::BaseProcessor2D *mpProcessor;
 327     boost::function<bool (const ThumbnailViewItem*) > maFilterFunc;
 328 };
 329
 330 #endif // THUMBNAILVIEW_HXX
 331
 332 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */