Bump version to 6.4-15
[LibreOffice.git] / include / sfx2 / thumbnailview.hxx
blobb924da0f6b76e3f23cf3307e58f2c3a5eea6e04f
1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
2 /*
3 * This file is part of the LibreOffice project.
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 */
10 #ifndef INCLUDED_SFX2_THUMBNAILVIEW_HXX
11 #define INCLUDED_SFX2_THUMBNAILVIEW_HXX
13 #include <sfx2/dllapi.h>
15 #include <functional>
16 #include <memory>
17 #include <vector>
19 #include <vcl/ctrl.hxx>
20 #include <vcl/customweld.hxx>
22 class BitmapEx;
23 class MouseEvent;
24 class KeyEvent;
25 class DataChangedEvent;
26 class ScrollBar;
27 class ThumbnailViewItem;
28 typedef ::std::vector< ThumbnailViewItem* > ThumbnailValueItemList;
31 struct ThumbnailItemAttributes;
33 /*************************************************************************
35 Description
36 ============
38 class ThumbnailView
40 This class allows the selection of an item. In the process items are
41 drawn side by side. The selection of items can be more clear than in a
42 ListBox shape for example in case of colors or samples.
43 The amount of columns drawn by the control and whether the items
44 should be encircled can be specified. Optional a NoSelection or name
45 field could be shown. By default image and color items are supported.
46 Items could be drawn by oneself if InsertItem() is only called with
47 an ID. To achieve this the UserDraw handler needs to be overridden. The
48 description text could be specified afterwards in case of UserDraw
49 and any other items.
51 Cross references
53 class ListBox
55 --------------------------------------------------------------------------
57 WinBits
59 WB_VSCROLL A scrollbar will be always shown. The visible number of
60 lines have to be specified with SetLineCount() if this
61 flag is set.
62 WB_TABSTOP It is possible to jump into the ValueSet with the tab key.
63 WB_NOTABSTOP It is not possible to jump into the ValueSet with the
64 tab key.
65 --------------------------------------------------------------------------
67 The number of columns must be either set with SetColCount() or
68 SetItemWidth(). If the number of columns is specified by SetColCount()
69 the width of the items will be calculated by the visible range.
70 If the items should have a static width, it has to be specified
71 with SetItemWidth(). In this case the number of columns will be calculated
72 by the visible range.
74 The number of rows is given by the number of items / number of columns. The
75 number of visible rows must either specified by SetLineCount() or
76 SetItemWidth(). If the number of visible rows is specified by SetLineCount(),
77 the height of the items will be calculated from the visible height. If the
78 items should have a fixed height it has to be specified with SetItemHeight().
79 In this case the number of visible rows is then calculated from the visible
80 height. If the number of visible rows is neither specified by SetLineCount()
81 nor by SetItemHeight() all rows will be shown. The height of the items will
82 be calculated by the visible height. If the number of visible rows is
83 specified by SetLineCount() or SetItemHeight() ValueSet does scroll
84 automatically when more lines are available, as are visible. If scrolling
85 should be also possible with a ScrollBar WB_VSCROLL needs to be set.
87 The distance between the items can be increased by SetExtraSpacing(). The
88 distance, which will be shown between two items (both in x and in y), is
89 measured in pixels.
91 The exact window size for a specific item size can be calculated by
92 CalcWindowSizePixel(). To do this all relevant data (number of columns/...)
93 have to be specified and if no number of rows was set, all items need to
94 be inserted. If the window was created with WB_BORDER/Border=sal_True the
95 size has to be specified with SetOutputSizePixel(). In other cases different
96 size-methods can be used. With CalcItemSize() the inner and outer size of
97 an item could be calculated (for this the free space defined by
98 SetExtraSpacing() will not be included).
100 The background color could be specified by SetColor(), with which the image
101 or UserDraw items will be underlaid. If no color is specified the color
102 of other windows (WindowColor) will be used for the background.
104 --------------------------------------------------------------------------
106 At first all items should be inserted and only then Show() should be called
107 since the output area will be precomputed. If this is not done the first
108 Paint will appear a little bit slower. Therefore the Control, if it is loaded
109 from the resource and only supplied with items during runtime, should be
110 loaded with Hide = sal_True and then displayed with Show().
112 In case of a visible Control the creation of the new output area could be
113 activated before Paint by calling Format().
115 --------------------------------------------------------------------------
117 If Drag and Drop will be called from the ValueSet the Command-Handler has to
118 be overridden. From this StartDrag needs to be called. If this method returns
119 sal_True the drag-process could be initiated by ExecuteDrag(), otherwise no
120 processing will take place. This method makes sure that ValueSet stops its
121 processing and as appropriate selects the entry. Therefore the calling of
122 Select-Handler within this function must be expected.
124 For dropping QueryDrop() and Drop() need to be overridden and ShowDropPos()
125 and HideDropPos() should be called within these methods.
126 To show the insertion point ShowDropPos() has to be called within the
127 QueryDrop-Handler. ShowDropPos() also scrolls the ValueSet if the passed
128 position is located at the window border. Furthermore ShowDropPos() returns
129 the position, at which the item should be inserted respectively which
130 insertion point was shown. If no insertion point was determined
131 VALUESET_ITEM_NOTFOUND will be returned. If the window was left during dragging
132 or the drag process is terminated HideDropPos() should be called in any case.
134 --------------------------------------------------------------------------
136 This class is currently still in the SV-Tools. That's why the ValueSet needs
137 to be loaded as a Control out of the resource and the desired WinBits have
138 to be set (before Show) with SetStyle().
140 *************************************************************************/
142 /* ThumbnailView types */
144 #define THUMBNAILVIEW_ITEM_NOTFOUND (sal_uInt16(-1))
146 // Display all the available items in the thumbnail.
147 class ViewFilterAll
149 public:
151 bool operator () (const ThumbnailViewItem*) const
153 return true;
159 * Class to display thumbnails with their names below their respective icons
163 class ThumbnailViewBase
165 friend class ThumbnailViewAcc;
166 friend class ThumbnailViewItemAcc;
168 virtual sal_uInt16 ImplGetVisibleItemCount() const = 0;
169 virtual ThumbnailViewItem* ImplGetVisibleItem(sal_uInt16 nVisiblePos) = 0;
171 virtual css::uno::Reference<css::accessibility::XAccessible> getAccessible() = 0;
173 public:
174 /// Updates information in the view; used only in RecentDocsView ATM.
175 virtual void Reload() {}
177 virtual bool renameItem(ThumbnailViewItem* pItem, const OUString& sNewTitle);
179 virtual ~ThumbnailViewBase();
182 class SFX2_DLLPUBLIC ThumbnailView : public Control, public ThumbnailViewBase
184 public:
186 ThumbnailView(vcl::Window* pParent, WinBits nWinStyle = WB_TABSTOP);
188 virtual ~ThumbnailView() override;
189 virtual void dispose() override;
191 virtual void MouseMove(const MouseEvent& rMEvt) override;
193 void AppendItem(std::unique_ptr<ThumbnailViewItem> pItem);
195 virtual void Clear();
197 // Change current thumbnail item list with new one (invalidates all pointers to a thumbnail item)
198 void updateItems(std::vector<std::unique_ptr<ThumbnailViewItem>> items);
200 size_t GetItemPos( sal_uInt16 nItemId ) const;
202 sal_uInt16 GetItemId( size_t nPos ) const;
204 sal_uInt16 GetItemId( const Point& rPos ) const;
206 sal_uInt16 getNextItemId () const;
208 void setItemMaxTextLength (sal_uInt32 nLength);
210 void setItemDimensions (long ItemWidth, long ThumbnailHeight,
211 long DisplayHeight, int itemPadding);
213 void SelectItem( sal_uInt16 nItemId );
215 bool IsItemSelected( sal_uInt16 nItemId ) const;
219 * @brief deselect all current selected items.
223 void deselectItems ();
225 void ShowTooltips( bool bShowTooltips );
227 void filterItems (const std::function<bool (const ThumbnailViewItem*) > &func);
229 virtual void Resize() override;
231 static BitmapEx readThumbnail(const OUString &msURL);
233 protected:
235 virtual void KeyInput( const KeyEvent& rKEvt ) override;
237 virtual void MouseButtonDown( const MouseEvent& rMEvt ) override;
239 virtual void Command( const CommandEvent& rCEvt ) override;
241 virtual void Paint(vcl::RenderContext& rRenderContext, const tools::Rectangle& rRect) override;
243 virtual void GetFocus() override;
245 virtual void LoseFocus() override;
247 virtual void StateChanged( StateChangedType nStateChange ) override;
249 virtual void DataChanged( const DataChangedEvent& rDCEvt ) override;
251 virtual css::uno::Reference< css::accessibility::XAccessible > CreateAccessible() override;
253 virtual css::uno::Reference<css::accessibility::XAccessible> getAccessible() override;
255 protected:
257 // Drawing item related functions, override them to make your own custom ones.
259 void DrawItem (ThumbnailViewItem const *pItem);
261 virtual void OnItemDblClicked (ThumbnailViewItem *pItem);
263 protected:
265 friend class ThumbnailViewAcc;
266 friend class ThumbnailViewItemAcc;
267 using Window::ImplInit;
269 void CalculateItemPositions (bool bScrollBarUsed = false);
270 void MakeItemVisible( sal_uInt16 nId );
272 SFX2_DLLPRIVATE void ImplInit();
274 virtual void ApplySettings(vcl::RenderContext& rRenderContext) override;
276 SFX2_DLLPRIVATE void ImplDeleteItems();
277 SFX2_DLLPRIVATE size_t ImplGetItem( const Point& rPoint ) const;
278 SFX2_DLLPRIVATE ThumbnailViewItem* ImplGetItem( size_t nPos );
279 SFX2_DLLPRIVATE virtual sal_uInt16 ImplGetVisibleItemCount() const override;
280 SFX2_DLLPRIVATE virtual ThumbnailViewItem* ImplGetVisibleItem(sal_uInt16 nVisiblePos) override;
281 SFX2_DLLPRIVATE void ImplFireAccessibleEvent( short nEventId, const css::uno::Any& rOldValue, const css::uno::Any& rNewValue );
282 SFX2_DLLPRIVATE bool ImplHasAccessibleListeners();
283 DECL_DLLPRIVATE_LINK( ImplScrollHdl, ScrollBar*, void );
285 protected:
287 std::vector< std::unique_ptr<ThumbnailViewItem> > mItemList;
288 ThumbnailValueItemList mFilteredItemList; ///< Cache to store the filtered items
289 ThumbnailValueItemList::iterator mpStartSelRange;
290 VclPtr<ScrollBar> mpScrBar;
291 long mnItemWidth;
292 long mnItemHeight;
293 long mnItemPadding;
294 long mnThumbnailHeight; // Maximum height of the thumbnail
295 long mnDisplayHeight; // Height of the data display box (name, etc)
296 long mnVisLines;
297 long mnLines;
299 sal_uInt16 mnCols;
300 sal_uInt16 mnFirstLine;
301 bool mbScroll : 1;
302 bool mbHasVisibleItems : 1;
303 bool mbShowTooltips : 1;
304 Color maFillColor; ///< Background color of the thumbnail view widget.
305 Color maTextColor; ///< Text color.
306 Color maHighlightColor; ///< Color of the highlight (background) of the hovered item.
307 Color maHighlightTextColor; ///< Color of the text for the highlighted item.
308 Color maSelectHighlightColor; ///< Color of the highlight (background) of the selected and hovered item.
309 Color maSelectHighlightTextColor; ///< Color of the text of the selected and hovered item.
310 double mfHighlightTransparence; ///< Transparence of the highlight.
312 std::unique_ptr<ThumbnailItemAttributes> mpItemAttrs;
314 std::function<bool (const ThumbnailViewItem*)> maFilterFunc;
317 class SfxThumbnailView : public weld::CustomWidgetController, public ThumbnailViewBase
319 public:
320 SfxThumbnailView(std::unique_ptr<weld::ScrolledWindow> xWindow, std::unique_ptr<weld::Menu> xMenu);
322 virtual ~SfxThumbnailView() override;
324 virtual bool MouseMove(const MouseEvent& rMEvt) override;
326 void AppendItem(std::unique_ptr<ThumbnailViewItem> pItem);
328 void RemoveItem(sal_uInt16 nItemId);
330 void Clear();
332 // Change current thumbnail item list with new one (invalidates all pointers to a thumbnail item)
333 void updateItems(std::vector<std::unique_ptr<ThumbnailViewItem>> items);
335 size_t GetItemPos( sal_uInt16 nItemId ) const;
337 sal_uInt16 GetItemId( size_t nPos ) const;
339 sal_uInt16 GetItemId( const Point& rPos ) const;
341 sal_uInt16 getNextItemId () const;
343 void setItemMaxTextLength (sal_uInt32 nLength);
345 void setItemDimensions (long ItemWidth, long ThumbnailHeight,
346 long DisplayHeight, int itemPadding);
348 void SelectItem( sal_uInt16 nItemId );
350 bool IsItemSelected( sal_uInt16 nItemId ) const;
354 * @brief deselect all current selected items.
358 void deselectItems ();
360 void ShowTooltips( bool bShowTooltips );
362 void SetMultiSelectionEnabled( bool bIsMultiSelectionEnabled );
364 void filterItems (const std::function<bool (const ThumbnailViewItem*) > &func);
366 void setItemStateHdl (const Link<const ThumbnailViewItem*,void> &aLink) { maItemStateHdl = aLink; }
368 virtual void Resize() override;
370 virtual void Show() override
372 mxScrolledWindow->show();
373 CustomWidgetController::Show();
376 virtual void Hide() override
378 mxScrolledWindow->hide();
379 CustomWidgetController::Hide();
382 virtual void SetDrawingArea(weld::DrawingArea* pDrawingArea) override;
384 protected:
386 virtual bool KeyInput( const KeyEvent& rKEvt ) override;
388 virtual bool MouseButtonDown( const MouseEvent& rMEvt ) override;
390 virtual void Paint(vcl::RenderContext& rRenderContext, const tools::Rectangle& rRect) override;
392 virtual void GetFocus() override;
394 virtual void LoseFocus() override;
396 virtual OUString RequestHelp(tools::Rectangle& rRect) override;
398 virtual css::uno::Reference< css::accessibility::XAccessible > CreateAccessible() override;
400 virtual css::uno::Reference<css::accessibility::XAccessible> getAccessible() override;
402 protected:
404 // Drawing item related functions, override them to make your own custom ones.
406 void DrawItem (ThumbnailViewItem const *pItem);
408 virtual void OnItemDblClicked (ThumbnailViewItem *pItem);
410 protected:
412 friend class SfxThumbnailViewAcc;
413 friend class ThumbnailViewItemAcc;
415 void CalculateItemPositions (bool bScrollBarUsed = false);
416 void MakeItemVisible( sal_uInt16 nId );
418 void ImplInit();
420 void ImplDeleteItems();
421 size_t ImplGetItem( const Point& rPoint ) const;
422 ThumbnailViewItem* ImplGetItem( size_t nPos );
423 virtual sal_uInt16 ImplGetVisibleItemCount() const override;
424 virtual ThumbnailViewItem* ImplGetVisibleItem(sal_uInt16 nVisiblePos) override;
425 void ImplFireAccessibleEvent( short nEventId, const css::uno::Any& rOldValue, const css::uno::Any& rNewValue );
426 bool ImplHasAccessibleListeners();
427 DECL_LINK( ImplScrollHdl, weld::ScrolledWindow&, void );
429 protected:
431 std::vector< std::unique_ptr<ThumbnailViewItem> > mItemList;
432 css::uno::Reference<css::accessibility::XAccessible> mxAccessible;
433 ThumbnailValueItemList mFilteredItemList; ///< Cache to store the filtered items
434 ThumbnailValueItemList::iterator mpStartSelRange;
435 long mnItemWidth;
436 long mnItemHeight;
437 long mnItemPadding;
438 long mnThumbnailHeight; // Maximum height of the thumbnail
439 long mnDisplayHeight; // Height of the data display box (name, etc)
440 long mnVisLines;
441 long mnLines;
443 sal_uInt16 mnCols;
444 sal_uInt16 mnFirstLine;
445 bool mbScroll : 1;
446 bool mbHasVisibleItems : 1;
447 bool mbShowTooltips : 1;
448 bool mbIsMultiSelectionEnabled: 1;
449 Color maFillColor; ///< Background color of the thumbnail view widget.
450 Color maTextColor; ///< Text color.
451 Color maHighlightColor; ///< Color of the highlight (background) of the hovered item.
452 Color maHighlightTextColor; ///< Color of the text for the highlighted item.
453 Color maSelectHighlightColor; ///< Color of the highlight (background) of the selected and hovered item.
454 Color maSelectHighlightTextColor; ///< Color of the text of the selected and hovered item.
455 double mfHighlightTransparence; ///< Transparence of the highlight.
457 Link<const ThumbnailViewItem*, void> maItemStateHdl;
458 std::unique_ptr<ThumbnailItemAttributes> mpItemAttrs;
459 std::unique_ptr<weld::ScrolledWindow> mxScrolledWindow;
460 std::unique_ptr<weld::Menu> mxContextMenu;
462 std::function<bool (const ThumbnailViewItem*)> maFilterFunc;
466 #endif // INCLUDED_SFX2_THUMBNAILVIEW_HXX
468 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */