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