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