LibreOffice Module vcl (master)  1
headbar.hxx
Go to the documentation of this file.
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  * This file incorporates work covered by the following license notice:
10  *
11  * Licensed to the Apache Software Foundation (ASF) under one or more
12  * contributor license agreements. See the NOTICE file distributed
13  * with this work for additional information regarding copyright
14  * ownership. The ASF licenses this file to you under the Apache
15  * License, Version 2.0 (the "License"); you may not use this file
16  * except in compliance with the License. You may obtain a copy of
17  * the License at http://www.apache.org/licenses/LICENSE-2.0 .
18  */
19 
20 #ifndef INCLUDED_VCL_HEADBAR_HXX
21 #define INCLUDED_VCL_HEADBAR_HXX
22 
23 #include <vcl/dllapi.h>
24 #include <tools/link.hxx>
25 #include <vcl/window.hxx>
26 #include <o3tl/typed_flags_set.hxx>
27 #include <memory>
28 
29 /*************************************************************************
30 
31 Description
32 ============
33 
34 class HeaderBar
35 
36 This class serves for displaying a header bar. A header bar can display
37 texts, images or both of them. The items can be changed in size, dragged or
38 clicked at. In many cases, it makes, for example, sense to use this control
39 in combination with a SvTabListBox.
40 
41 --------------------------------------------------------------------------
42 
43 WinBits
44 
45 WB_BORDER a border is drawn in the top and in the bottom
46 WB_BOTTOMBORDER a border is drawn in the bottom
47 WB_BUTTONSTYLE The items look like buttons, otherwise they are flat.
48 WB_3DLOOK 3D look
49 WB_DRAG items can be dragged
50 WB_STDHEADERBAR WB_BUTTONSTYLE | WB_BOTTOMBORDER
51 
52 --------------------------------------------------------------------------
53 
54 ItemBits
55 
56 HeaderBarItemBits::LEFT content is displayed in the item left-justified
57 HeaderBarItemBits::CENTER content is displayed in the item centred
58 HeaderBarItemBits::RIGHT content is displayed in the item right-justified
59 HeaderBarItemBits::TOP content is displayed in the item at the upper border
60 HeaderBarItemBits::VCENTER content is displayed in the item vertically centred
61 HeaderBarItemBits::BOTTOM content is displayed in the item at the bottom border
62 HeaderBarItemBits::LEFTIMAGE in case of text and image, the image is displayed left of the text
63 HeaderBarItemBits::RIGHTIMAGE in case of text and image, the image is displayed right of the text
64 HeaderBarItemBits::FIXED item cannot be changed in size
65 HeaderBarItemBits::FIXEDPOS item cannot be moved
66 HeaderBarItemBits::CLICKABLE item is clickable
67  (select handler is only called on MouseButtonUp)
68 HeaderBarItemBits::FLAT item is displayed in a flat way, even if WB_BUTTONSTYLE is set
69 HeaderBarItemBits::DOWNARROW An arrow pointing downwards is displayed behind the text,
70  which should, for example, be shown, when after this item,
71  a corresponding list is sorted in descending order.
72  The status of the arrow can be set/reset with SetItemBits().
73 HeaderBarItemBits::UPARROW An arrow pointing upwards is displayed behind the text,
74  which should, for example, be shown, when after this item,
75  a corresponding list is sorted in ascending order.
76  The status of the arrow can be set/reset with SetItemBits().
77 HeaderBarItemBits::USERDRAW For this item, the UserDraw handler is called as well.
78 HeaderBarItemBits::STDSTYLE (HeaderBarItemBits::LEFT | HeaderBarItemBits::LEFTIMAGE | HeaderBarItemBits::CLICKABLE)
79 
80 --------------------------------------------------------------------------
81 
82 Handler
83 
84 Select() Is called, when the item is clicked. If HeaderBarItemBits::CLICKABLE
85  is set in the item and not HeaderBarItemBits::FLAT, the handler is only
86  called in the MouseButtonUp handler, when the mouse has been
87  released over the item. In this case, the Select handler
88  behaves like it does with a ToolBox button.
89 DoubleClick() This handler is called, when an item is double-clicked.
90  Whether the item or the separator has been clicked, can
91  be determined by IsItemMode(). Normally, when a separator
92  is double-clicked, the optimal column width should be
93  calculated and should be set.
94 StartDrag() This handler is called, when dragging is started resp.
95  an item has been clicked. At the latest in this handler,
96  the size of the size-line should be set with
97  SetDragSize(), if IsItemMode() returns false.
98 Drag() This handler is called, when dragging is taking place.
99  If no size is set with SetDragSize(), this handler can
100  be used to draw the line in the neighbouring window by
101  oneself. The current dragging position can be requested
102  with GetDragPos(). In every case, IsItemMode()
103  should be checked to find out whether a separator is
104  dragged as well.
105 EndDrag() This handler is called, when a dragging process has been
106  stopped. If GetCurItemId() returns 0 in the EndDrag handler,
107  the drag process was aborted. If this is not the case and
108  IsItemMode() returns false, the new size of the dragged
109  item should be requested using GetItemSize() and it
110  should be taken over in the corresponding control.
111  If IsItemMode() returns true, GetCurItemId()
112  returns an Id and IsItemDrag() returns true, this
113  item has been dragged. In this case, the new position
114  should be requested using GetItemPos() and the data
115  in the corresponding control should be adapted.
116  Otherwise, the position to which the item has been dragged
117  could also be requested with GetItemDragPos().
118 
119 Further methods that are important for the handler.
120 
121 GetCurItemId() Returns the id of the item, for which the handler has
122  currently been called. Only returns a valid id in the
123  handlers Select(), DoubleClick(), StartDrag(),
124  Drag() and EndDrag(). In the EndDrag handler,
125  this method returns the id of the dragged item or 0,
126  if the drag process has been aborted.
127 GetItemDragPos() Returns the position, at which an item has been moved.
128  HEADERBAR_ITEM_NOTFOUND is returned, if the process
129  has been aborted or no ItemDrag is active.
130 IsItemMode() This method can be used to determine whether the
131  handler has been called for an item or a separator.
132  true - handler was called for the item
133  false - handler was called for the separator
134 IsItemDrag() This method can be used to determine whether an item
135  has been dragged or selected.
136  true - item is dragged
137  false - item is selected
138 SetDragSize() This method is used to set the size of the separating
139  line that is drawn by the control. It should be
140  equivalent to the height of the neighbouring window.
141  The height of the HeaderBar is added automatically.
142 
143 --------------------------------------------------------------------------
144 
145 Further methods
146 
147 SetOffset() This method sets the offset, from which on the
148  items are shown. This is needed when the
149  corresponding window is scrolled.
150 CalcWindowSizePixel() This method can be used to calculate the height
151  of the window, so that the content of the item
152  can be displayed.
153 
154 --------------------------------------------------------------------------
155 
156 Tips and tricks:
157 
158 1) ContextMenu
159 If a context sensitive PopupMenu should be shown, the command
160 handler must be overlaid. Using GetItemId() and when passing the
161 mouse position, it can be determined whether the mouse click has been
162 carried out over an item resp. over which item the mouse click has been
163 carried out.
164 
165 2) last item
166 If ButtonStyle has been set, it looks better, if an empty item is
167 set at the end which takes up the remaining space.
168 In order to do that, you can insert an item with an empty string and
169 pass HEADERBAR_FULLSIZE as size. For such an item, you should not set
170 HeaderBarItemBits::CLICKABLE, but HeaderBarItemBits::FIXEDPOS.
171 
172 *************************************************************************/
173 
174 class ImplHeadItem;
175 
176 #define WB_BOTTOMBORDER (WinBits(0x0400))
177 #define WB_BUTTONSTYLE (WinBits(0x0800))
178 #define WB_STDHEADERBAR (WB_BUTTONSTYLE | WB_BOTTOMBORDER)
179 
181 {
182  NONE = 0x0000,
183  LEFT = 0x0001,
184  CENTER = 0x0002,
185  RIGHT = 0x0004,
186  LEFTIMAGE = 0x0010,
187  RIGHTIMAGE = 0x0020,
188  CLICKABLE = 0x0400,
189  FLAT = 0x0800,
190  DOWNARROW = 0x1000,
191  UPARROW = 0x2000,
193 };
194 
195 namespace o3tl
196 {
197  template<> struct typed_flags<HeaderBarItemBits> : is_typed_flags<HeaderBarItemBits, 0x3c37> {};
198 }
199 
200 #define HEADERBAR_APPEND (sal_uInt16(0xFFFF))
201 #define HEADERBAR_ITEM_NOTFOUND (sal_uInt16(0xFFFF))
202 #define HEADERBAR_FULLSIZE (tools::Long(1000000000))
203 
205 {
206 private:
207  std::vector<std::unique_ptr<ImplHeadItem>> mvItemList;
217  sal_uInt16 mnCurItemId;
218  sal_uInt16 mnItemDragPos;
220  bool mbDrag;
222  bool mbOutDrag;
229 
230  css::uno::Reference< css::accessibility::XAccessible >
232 
233  using Window::ImplInit;
234  VCL_DLLPRIVATE void ImplInit( WinBits nWinStyle );
235  VCL_DLLPRIVATE void ImplInitSettings( bool bFont, bool bForeground, bool bBackground );
236  VCL_DLLPRIVATE tools::Long ImplGetItemPos( sal_uInt16 nPos ) const;
237  VCL_DLLPRIVATE tools::Rectangle ImplGetItemRect( sal_uInt16 nPos ) const;
238  VCL_DLLPRIVATE sal_uInt16 ImplDoHitTest( const Point& rPos, tools::Long& nMouseOff, sal_uInt16& nPos ) const;
239  VCL_DLLPRIVATE void ImplInvertDrag( sal_uInt16 nStartPos, sal_uInt16 nEndPos );
240  VCL_DLLPRIVATE void ImplDrawItem(vcl::RenderContext& rRenderContext, sal_uInt16 nPos, bool bHigh,
241  const tools::Rectangle& rItemRect, const tools::Rectangle* pRect);
242  VCL_DLLPRIVATE void ImplDrawItem(vcl::RenderContext& rRenderContext, sal_uInt16 nPos, bool bHigh,
243  const tools::Rectangle* pRect);
244  VCL_DLLPRIVATE void ImplUpdate( sal_uInt16 nPos,
245  bool bEnd = false );
246  VCL_DLLPRIVATE void ImplStartDrag( const Point& rPos, bool bCommand );
247  VCL_DLLPRIVATE void ImplDrag( const Point& rPos );
248  VCL_DLLPRIVATE void ImplEndDrag( bool bCancel );
249 
250  virtual void ApplySettings(vcl::RenderContext& rRenderContext) override;
251 
252 public:
253  HeaderBar( vcl::Window* pParent, WinBits nWinBits );
254  virtual ~HeaderBar() override;
255 
256  virtual void MouseButtonDown( const MouseEvent& rMEvt ) override;
257  virtual void MouseMove( const MouseEvent& rMEvt ) override;
258  virtual void Tracking( const TrackingEvent& rTEvt ) override;
259  virtual void Paint(vcl::RenderContext& rRenderContext, const tools::Rectangle& rRect) override;
260  virtual void Draw( OutputDevice* pDev, const Point& rPos, DrawFlags nFlags ) override;
261  virtual void Resize() override;
262  virtual void Command( const CommandEvent& rCEvt ) override;
263  virtual void RequestHelp( const HelpEvent& rHEvt ) override;
264  virtual void StateChanged( StateChangedType nStateChange ) override;
265  virtual void DataChanged( const DataChangedEvent& rDCEvt ) override;
266 
267  virtual Size GetOptimalSize() const override;
268 
269  virtual void EndDrag();
270  virtual void Select();
271  virtual void DoubleClick();
272 
273  void InsertItem( sal_uInt16 nItemId, const OUString& rText,
275  sal_uInt16 nPos = HEADERBAR_APPEND );
276  void RemoveItem( sal_uInt16 nItemId );
277  void MoveItem( sal_uInt16 nItemId, sal_uInt16 nNewPos );
278  void Clear();
279 
280  void SetOffset( tools::Long nNewOffset );
281  void SetDragSize( tools::Long nNewSize ) { mnDragSize = nNewSize; }
282 
283  sal_uInt16 GetItemCount() const;
284  sal_uInt16 GetItemPos( sal_uInt16 nItemId ) const;
285  sal_uInt16 GetItemId( sal_uInt16 nPos ) const;
286  sal_uInt16 GetItemId( const Point& rPos ) const;
287  tools::Rectangle GetItemRect( sal_uInt16 nItemId ) const;
288  sal_uInt16 GetCurItemId() const { return mnCurItemId; }
289  bool IsItemMode() const { return mbItemMode; }
290 
291  void SetItemSize( sal_uInt16 nItemId, tools::Long nNewSize );
292  tools::Long GetItemSize( sal_uInt16 nItemId ) const;
293  void SetItemBits( sal_uInt16 nItemId, HeaderBarItemBits nNewBits );
294  HeaderBarItemBits GetItemBits( sal_uInt16 nItemId ) const;
295 
296  void SetItemText( sal_uInt16 nItemId, const OUString& rText );
297  OUString GetItemText( sal_uInt16 nItemId ) const;
298 
299  OUString GetHelpText( sal_uInt16 nItemId ) const;
300 
301  Size CalcWindowSizePixel() const;
302 
303  using Window::SetHelpId;
304 
305  void SetStartDragHdl( const Link<HeaderBar*,void>& rLink ) { maStartDragHdl = rLink; }
306  void SetEndDragHdl( const Link<HeaderBar*,void>& rLink ) { maEndDragHdl = rLink; }
307  void SetSelectHdl( const Link<HeaderBar*,void>& rLink ) { maSelectHdl = rLink; }
308  void SetCreateAccessibleHdl( const Link<HeaderBar*,void>& rLink ) { maCreateAccessibleHdl = rLink; }
309 
310  bool IsDragable() const { return mbDragable; }
311 
313  virtual css::uno::Reference< css::accessibility::XAccessible > CreateAccessible() override;
314  void SetAccessible( const css::uno::Reference< css::accessibility::XAccessible >& );
315 };
316 
317 #endif // INCLUDED_VCL_HEADBAR_HXX
318 
319 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */
bool mbOutDrag
Definition: headbar.hxx:222
tools::Long mnDX
Definition: headbar.hxx:211
css::uno::Reference< css::accessibility::XAccessible > mxAccessible
Definition: headbar.hxx:231
virtual void MouseButtonDown(const MouseEvent &rMEvt)
Definition: mouse.cxx:413
#define VCL_DLLPUBLIC
Definition: dllapi.h:29
long Long
Link< HeaderBar *, void > maCreateAccessibleHdl
Definition: headbar.hxx:228
const OUString & GetHelpText() const
Definition: window.cxx:3071
void SetStartDragHdl(const Link< HeaderBar *, void > &rLink)
Definition: headbar.hxx:305
virtual Size GetOptimalSize() const
Definition: window3.cxx:26
void SetHelpId(const OString &)
Definition: window2.cxx:822
tools::Long mnBorderOff2
Definition: headbar.hxx:209
Link< HeaderBar *, void > maSelectHdl
Definition: headbar.hxx:227
void SetCreateAccessibleHdl(const Link< HeaderBar *, void > &rLink)
Definition: headbar.hxx:308
bool IsDragable() const
Definition: headbar.hxx:310
StateChangedType
Definition: window.hxx:288
sal_Int64 WinBits
virtual css::uno::Reference< css::accessibility::XAccessible > CreateAccessible()
tools::Long mnDY
Definition: headbar.hxx:212
tools::Long mnDragPos
Definition: headbar.hxx:215
void SetSelectHdl(const Link< HeaderBar *, void > &rLink)
Definition: headbar.hxx:307
void SetEndDragHdl(const Link< HeaderBar *, void > &rLink)
Definition: headbar.hxx:306
virtual void Tracking(const TrackingEvent &rTEvt)
Definition: window.cxx:1914
void SetAccessible(const css::uno::Reference< css::accessibility::XAccessible > &)
tools::Long mnOffset
Definition: headbar.hxx:210
sal_uInt16 mnCurItemId
Definition: headbar.hxx:217
DrawFlags
Definition: window.hxx:331
virtual void ApplySettings(vcl::RenderContext &rRenderContext)
Definition: window.cxx:3810
Some things multiple-inherit from VclAbstractDialog and OutputDevice, so we need to use virtual inher...
Definition: outdev.hxx:288
bool mbDragable
Definition: headbar.hxx:219
virtual void Draw(::OutputDevice *pDev, const Point &rPos, DrawFlags nFlags)
Definition: window.cxx:1811
virtual void Resize()
Definition: window.cxx:1817
bool mbItemMode
Definition: headbar.hxx:224
tools::Long mnDragSize
Definition: headbar.hxx:213
bool mbDrag
Definition: headbar.hxx:220
std::vector< std::unique_ptr< ImplHeadItem > > mvItemList
Definition: headbar.hxx:207
sal_uInt16 mnItemDragPos
Definition: headbar.hxx:218
#define HEADERBAR_APPEND
Definition: headbar.hxx:200
SAL_DLLPRIVATE void ImplInit(vcl::Window *pParent, WinBits nStyle, SystemParentData *pSystemParentData)
Definition: window.cxx:926
bool IsItemMode() const
Definition: headbar.hxx:289
Link< HeaderBar *, void > maStartDragHdl
Definition: headbar.hxx:225
void SetDragSize(tools::Long nNewSize)
Definition: headbar.hxx:281
virtual void Paint(vcl::RenderContext &rRenderContext, const tools::Rectangle &rRect)
Definition: paint.cxx:1017
tools::Long mnBorderOff1
Definition: headbar.hxx:208
#define VCL_DLLPRIVATE
Definition: dllapi.h:31
virtual void StateChanged(StateChangedType nStateChange)
Definition: window.cxx:1922
virtual void MouseMove(const MouseEvent &rMEvt)
Definition: mouse.cxx:407
sal_uInt16 GetCurItemId() const
Definition: headbar.hxx:288
tools::Long mnMouseOff
Definition: headbar.hxx:216
bool mbButtonStyle
Definition: headbar.hxx:223
bool mbItemDrag
Definition: headbar.hxx:221
virtual void Command(const CommandEvent &rCEvt)
Definition: window.cxx:1905
virtual void RequestHelp(const HelpEvent &rHEvt)
Definition: window.cxx:1851
tools::Long mnStartPos
Definition: headbar.hxx:214
Link< HeaderBar *, void > maEndDragHdl
Definition: headbar.hxx:226
HeaderBarItemBits
Definition: headbar.hxx:180
virtual void DataChanged(const DataChangedEvent &rDCEvt)
Definition: event.cxx:36