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