include/svtools/headbar.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  * 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_SVTOOLS_HEADBAR_HXX
  21 #define INCLUDED_SVTOOLS_HEADBAR_HXX
  22
  23 #include <svtools/svtdllapi.h>
  24 #include <tools/link.hxx>
  25 #include <vcl/window.hxx>
  26 #include <o3tl/typed_flags_set.hxx>
  27
  28 /*************************************************************************
  29
  30 Description
  31 ============
  32
  33 class HeaderBar
  34
  35 This class serves for displaying a header bar. A header bar can display
  36 texts, images or both of them. The items can be changed in size, dragged or
  37 clicked at. In many cases, it makes, for example, sense to use this control
  38 in combination with a SvTabListBox.
  39
  40 --------------------------------------------------------------------------
  41
  42 WinBits
  43
  44 WB_BORDER           a border is drawn in the top and in the bottom
  45 WB_BOTTOMBORDER     a border is drawn in the bottom
  46 WB_BUTTONSTYLE      The items look like buttons, otherwise they are flat.
  47 WB_3DLOOK           3D look
  48 WB_DRAG             items can be dragged
  49 WB_STDHEADERBAR     WB_BUTTONSTYLE | WB_BOTTOMBORDER
  50
  51 --------------------------------------------------------------------------
  52
  53 ItemBits
  54
  55 HeaderBarItemBits::LEFT            content is displayed in the item left-justified
  56 HeaderBarItemBits::CENTER          content is displayed in the item centred
  57 HeaderBarItemBits::RIGHT           content is displayed in the item right-justified
  58 HeaderBarItemBits::TOP             content is displayed in the item at the upper border
  59 HeaderBarItemBits::VCENTER         content is displayed in the item vertically centred
  60 HeaderBarItemBits::BOTTOM          content is displayed in the item at the bottom border
  61 HeaderBarItemBits::LEFTIMAGE       in case of text and image, the image is displayed left of the text
  62 HeaderBarItemBits::RIGHTIMAGE      in case of text and image, the image is displayed right of the text
  63 HeaderBarItemBits::FIXED           item cannot be changed in size
  64 HeaderBarItemBits::FIXEDPOS        item cannot be moved
  65 HeaderBarItemBits::CLICKABLE       item is clickable
  66                     (select handler is only called on MouseButtonUp)
  67 HeaderBarItemBits::FLAT            item is displayed in a flat way, even if WB_BUTTONSTYLE is set
  68 HeaderBarItemBits::DOWNARROW       An arrow pointing downwards is displayed behind the text,
  69                     which should, for example, be shown, when after this item,
  70                     a corresponding list is sorted in descending order.
  71                     The status of the arrow can be set/reset with SetItemBits().
  72 HeaderBarItemBits::UPARROW         An arrow pointing upwards is displayed behind the text,
  73                     which should, for example, be shown, when after this item,
  74                     a corresponding list is sorted in ascending order.
  75                     The status of the arrow can be set/reset with SetItemBits().
  76 HeaderBarItemBits::USERDRAW        For this item, the UserDraw handler is called as well.
  77 HeaderBarItemBits::STDSTYLE        (HeaderBarItemBits::LEFT | HeaderBarItemBits::LEFTIMAGE | HeaderBarItemBits::VCENTER | HeaderBarItemBits::CLICKABLE)
  78
  79 --------------------------------------------------------------------------
  80
  81 Handler
  82
  83 Select()            Is called, when the item is clicked. If HeaderBarItemBits::CLICKABLE
  84                     is set in the item and not HeaderBarItemBits::FLAT, the handler is only
  85                     called in the MouseButtonUp handler, when the mouse has been
  86                     released over the item. In this case, the Select handler
  87                     behaves like it does with a ToolBox button.
  88 DoubleClick()       This handler is called, when an item is double-clicked.
  89                     Whether the item or the separator has been clicked, can
  90                     be determined by IsItemMode(). Normally, when a separator
  91                     is double-clicked, the optimal column width should be
  92                     calculated and should be set.
  93 StartDrag()         This handler is called, when dragging is started resp.
  94                     an item has been clicked. At the latest in this handler,
  95                     the size of the size-line should be set with
  96                     SetDragSize(), if IsItemMode() returns false.
  97 Drag()              This handler is callled, when dragging is taking place.
  98                     If no size is set with SetDragSize(), this handler can
  99                     be used to draw the line in the neighbouring window by
 100                     oneself. The current dragging position can be requested
 101                     with GetDragPos(). In every case, IsItemMode()
 102                     should be checked to find out whether a separator is
 103                     dragged as well.
 104 EndDrag()           This handler is called, when a dragging process has been
 105                     stopped. If GetCurItemId() returns 0 in the EndDrag handler,
 106                     the drag process was aborted. If this is not the case and
 107                     IsItemMode() returns false, the new size of the dragged
 108                     item should be requested using GetItemSize() and it
 109                     should be taken over in the corresponding control.
 110                     If IsItemMode() returns true, GetCurItemId()
 111                     returns an Id and IsItemDrag() returns true, this
 112                     item has been dragged. In this case, the new position
 113                     should be requested using  GetItemPos() and the data
 114                     in the corresponding control should be adapted.
 115                     Otherwise, the position to which the item has been dragged
 116                     could also be requested with GetItemDragPos().
 117
 118 Further methods that are important for the handler.
 119
 120 GetCurItemId()      Returns the id of the item, for which the handler has
 121                     currently been called. Only returns a valid id in the
 122                     handlers Select(), DoubleClick(), StartDrag(),
 123                     Drag() and EndDrag(). In the EndDrag handler,
 124                     this method returns the id of the dragged item or 0,
 125                     if the drag process has been aborted.
 126 GetItemDragPos()    Returns the position, at which an item has been moved.
 127                     HEADERBAR_ITEM_NOTFOUND is returned, if the process
 128                     has been aborted or no ItemDrag is active.
 129 IsItemMode()        This method can be used to determine whether the
 130                     handler has been called for an item or a separator.
 131                     true    - handler was called for the item
 132                     false   - handler was called for the separator
 133 IsItemDrag()        This method can be used to determine whether an item
 134                     has been dragged or selected.
 135                     true    - item is dragged
 136                     false   - item is selected
 137 SetDragSize()       This method is used to set the size of the separating
 138                     line that is drawn by the control. It should be
 139                     equivalent to the height of the neighbouring window.
 140                     The height of the HeaderBar is added automatically.
 141
 142 --------------------------------------------------------------------------
 143
 144 Further methods
 145
 146 SetOffset()             This method sets the offset, from which on the
 147                         items are shown. This is needed when the
 148                         corresponding window is scrolled.
 149 CalcWindowSizePixel()   This method can be used to calculate the height
 150                         of the window, so that the content of the item
 151                         can be displayed.
 152
 153 --------------------------------------------------------------------------
 154
 155 Tips and tricks:
 156
 157 1) ContextMenu
 158 If a context sensitive PopupMenu should be shown, the command
 159 handler must be overlaid. Using GetItemId() and when passing the
 160 mous position, it can be determined whether the mouse click has been
 161 carried out over an item resp. over which item the mouse click has been
 162 carried out.
 163
 164 2) last item
 165 If ButtonStyle has been set, it looks better, if an empty item is
 166 set at the end which takes up the remaining space.
 167 In order to do that, you can insert an item with an empty string and
 168 pass HEADERBAR_FULLSIZE as size. For such an item, you should not set
 169 HeaderBarItemBits::CLICKABLE, but HeaderBarItemBits::FIXEDPOS.
 170
 171 *************************************************************************/
 172
 173 class Accelerator;
 174 class ImplHeadItem;
 175
 176 typedef ::std::vector< ImplHeadItem* > ImplHeadItemList;
 177
 178
 179 // - WinBits -
 180
 181
 182 #define WB_BOTTOMBORDER         ((WinBits)0x0400)
 183 #define WB_BUTTONSTYLE          ((WinBits)0x0800)
 184 #define WB_STDHEADERBAR         (WB_BUTTONSTYLE | WB_BOTTOMBORDER)
 185
 186
 187 // - HeaderBarItemBits -
 188
 189
 190 enum class HeaderBarItemBits
 191 {
 192     NONE                = 0x0000,
 193     LEFT                = 0x0001,
 194     CENTER              = 0x0002,
 195     RIGHT               = 0x0004,
 196     TOP                 = 0x0008,
 197     VCENTER             = 0x0010,
 198     BOTTOM              = 0x0020,
 199     LEFTIMAGE           = 0x0040,
 200     RIGHTIMAGE          = 0x0080,
 201     FIXED               = 0x0100,
 202     FIXEDPOS            = 0x0200,
 203     CLICKABLE           = 0x0400,
 204     FLAT                = 0x0800,
 205     DOWNARROW           = 0x1000,
 206     UPARROW             = 0x2000,
 207     USERDRAW            = 0x4000,
 208     STDSTYLE            = LEFT | LEFTIMAGE | VCENTER | CLICKABLE,
 209 };
 210 namespace o3tl
 211 {
 212     template<> struct typed_flags<HeaderBarItemBits> : is_typed_flags<HeaderBarItemBits, 0x7fff> {};
 213 }
 214
 215
 216 // - HeaderBar-Types -
 217
 218
 219 #define HEADERBAR_APPEND            ((sal_uInt16)0xFFFF)
 220 #define HEADERBAR_ITEM_NOTFOUND     ((sal_uInt16)0xFFFF)
 221 #define HEADERBAR_FULLSIZE          ((long)1000000000)
 222
 223 #define HEADERBAR_TEXTOFF           2
 224
 225
 226 // - HeaderBar -
 227
 228
 229 class VCLXHeaderBar;
 230
 231 class SVT_DLLPUBLIC HeaderBar : public vcl::Window
 232 {
 233 private:
 234     ImplHeadItemList*   mpItemList;
 235     long                mnBorderOff1;
 236     long                mnBorderOff2;
 237     long                mnOffset;
 238     long                mnDX;
 239     long                mnDY;
 240     long                mnDragSize;
 241     long                mnStartPos;
 242     long                mnDragPos;
 243     long                mnMouseOff;
 244     sal_uInt16          mnCurItemId;
 245     sal_uInt16          mnItemDragPos;
 246     bool                mbDragable;
 247     bool                mbDrag;
 248     bool                mbItemDrag;
 249     bool                mbOutDrag;
 250     bool                mbButtonStyle;
 251     bool                mbItemMode;
 252     Link<>              maStartDragHdl;
 253     Link<>              maDragHdl;
 254     Link<>              maEndDragHdl;
 255     Link<>              maSelectHdl;
 256     Link<>              maDoubleClickHdl;
 257     Link<>              maCreateAccessibleHdl;
 258
 259     VCLXHeaderBar*      m_pVCLXHeaderBar;
 260
 261
 262     ::com::sun::star::uno::Reference<
 263         ::com::sun::star::accessibility::XAccessible >
 264                         mxAccessible;
 265
 266     using Window::ImplInit;
 267     SVT_DLLPRIVATE void             ImplInit( WinBits nWinStyle );
 268     SVT_DLLPRIVATE void             ImplInitSettings( bool bFont, bool bForeground, bool bBackground );
 269     SVT_DLLPRIVATE long             ImplGetItemPos( sal_uInt16 nPos ) const;
 270     SVT_DLLPRIVATE Rectangle            ImplGetItemRect( sal_uInt16 nPos ) const;
 271     using Window::ImplHitTest;
 272     SVT_DLLPRIVATE sal_uInt16               ImplHitTest( const Point& rPos, long& nMouseOff, sal_uInt16& nPos ) const;
 273     SVT_DLLPRIVATE void             ImplInvertDrag( sal_uInt16 nStartPos, sal_uInt16 nEndPos );
 274     SVT_DLLPRIVATE void             ImplDrawItem(vcl::RenderContext& rRenderContext, sal_uInt16 nPos, bool bHigh, bool bDrag,
 275                                                  const Rectangle& rItemRect, const Rectangle* pRect, sal_uLong nFlags);
 276     SVT_DLLPRIVATE void             ImplDrawItem(vcl::RenderContext& rRenderContext, sal_uInt16 nPos, bool bHigh = false,
 277                                                  bool bDrag = false, const Rectangle* pRect = NULL);
 278     SVT_DLLPRIVATE void             ImplUpdate( sal_uInt16 nPos,
 279                                        bool bEnd = false, bool bDirect = false );
 280     SVT_DLLPRIVATE void             ImplStartDrag( const Point& rPos, bool bCommand );
 281     SVT_DLLPRIVATE void             ImplDrag( const Point& rPos );
 282     SVT_DLLPRIVATE void             ImplEndDrag( bool bCancel );
 283
 284     virtual void ApplySettings(vcl::RenderContext& rRenderContext) SAL_OVERRIDE;
 285
 286 public:
 287     HeaderBar( vcl::Window* pParent, WinBits nWinBits = WB_STDHEADERBAR );
 288     virtual ~HeaderBar();
 289     virtual void dispose() SAL_OVERRIDE;
 290
 291     virtual void        MouseButtonDown( const MouseEvent& rMEvt ) SAL_OVERRIDE;
 292     virtual void        MouseMove( const MouseEvent& rMEvt ) SAL_OVERRIDE;
 293     virtual void        Tracking( const TrackingEvent& rTEvt ) SAL_OVERRIDE;
 294     virtual void        Paint(vcl::RenderContext& rRenderContext, const Rectangle& rRect) SAL_OVERRIDE;
 295     virtual void        Draw( OutputDevice* pDev, const Point& rPos, const Size& rSize, sal_uLong nFlags ) SAL_OVERRIDE;
 296     virtual void        Resize() SAL_OVERRIDE;
 297     virtual void        Command( const CommandEvent& rCEvt ) SAL_OVERRIDE;
 298     virtual void        RequestHelp( const HelpEvent& rHEvt ) SAL_OVERRIDE;
 299     virtual void        StateChanged( StateChangedType nStateChange ) SAL_OVERRIDE;
 300     virtual void        DataChanged( const DataChangedEvent& rDCEvt ) SAL_OVERRIDE;
 301
 302     void                StartDrag();
 303     void                Drag();
 304     virtual void        EndDrag();
 305     virtual void        Select();
 306     virtual void        DoubleClick();
 307
 308     void                InsertItem( sal_uInt16 nItemId, const OUString& rText,
 309                                     long nSize, HeaderBarItemBits nBits = HeaderBarItemBits::STDSTYLE,
 310                                     sal_uInt16 nPos = HEADERBAR_APPEND );
 311     void                RemoveItem( sal_uInt16 nItemId );
 312     void                MoveItem( sal_uInt16 nItemId, sal_uInt16 nNewPos );
 313     void                Clear();
 314
 315     void                SetOffset( long nNewOffset = 0 );
 316     long                GetOffset() const { return mnOffset; }
 317     inline void         SetDragSize( long nNewSize = 0 ) { mnDragSize = nNewSize; }
 318     long                GetDragSize() const { return mnDragSize; }
 319
 320     sal_uInt16          GetItemCount() const;
 321     sal_uInt16          GetItemPos( sal_uInt16 nItemId ) const;
 322     sal_uInt16          GetItemId( sal_uInt16 nPos ) const;
 323     sal_uInt16          GetItemId( const Point& rPos ) const;
 324     Rectangle           GetItemRect( sal_uInt16 nItemId ) const;
 325     sal_uInt16          GetCurItemId() const { return mnCurItemId; }
 326     long                GetDragPos() const { return mnDragPos; }
 327     sal_uInt16          GetItemDragPos() const { return mnItemDragPos; }
 328     bool                IsItemMode() const { return mbItemMode; }
 329     bool                IsItemDrag() const { return mbItemDrag; }
 330
 331     void                SetItemSize( sal_uInt16 nItemId, long nNewSize );
 332     long                GetItemSize( sal_uInt16 nItemId ) const;
 333     void                SetItemBits( sal_uInt16 nItemId, HeaderBarItemBits nNewBits );
 334     HeaderBarItemBits   GetItemBits( sal_uInt16 nItemId ) const;
 335
 336     void                SetItemText( sal_uInt16 nItemId, const OUString& rText );
 337     OUString            GetItemText( sal_uInt16 nItemId ) const;
 338
 339     OUString            GetHelpText( sal_uInt16 nItemId ) const;
 340     OString             GetHelpId( sal_uInt16 nItemId ) const;
 341
 342     Size                CalcWindowSizePixel() const;
 343
 344     inline void             SetHelpText( const OUString& rText )    { Window::SetHelpText( rText ); }
 345     inline const OUString&  GetHelpText() const                     { return Window::GetHelpText(); }
 346     inline void             SetHelpId( const OString& rId )    { Window::SetHelpId( rId ); }
 347     inline const OString& GetHelpId() const                    { return Window::GetHelpId(); }
 348
 349     inline void         SetStartDragHdl( const Link<>& rLink )      { maStartDragHdl = rLink; }
 350     inline const Link<>& GetStartDragHdl() const                    { return maStartDragHdl; }
 351     inline void         SetDragHdl( const Link<>& rLink )           { maDragHdl = rLink; }
 352     inline const Link<>& GetDragHdl() const                         { return maDragHdl; }
 353     inline void         SetEndDragHdl( const Link<>& rLink )        { maEndDragHdl = rLink; }
 354     inline const Link<>& GetEndDragHdl() const                      { return maEndDragHdl; }
 355     inline void         SetSelectHdl( const Link<>& rLink )         { maSelectHdl = rLink; }
 356     inline const Link<>& GetSelectHdl() const                       { return maSelectHdl; }
 357     inline void         SetDoubleClickHdl( const Link<>& rLink )    { maDoubleClickHdl = rLink; }
 358     inline const Link<>& GetDoubleClickHdl() const                  { return maDoubleClickHdl; }
 359     inline void         SetCreateAccessibleHdl( const Link<>& rLink ) { maCreateAccessibleHdl = rLink; }
 360     inline const Link<>& GetCreateAccessibleHdl() const             { return maCreateAccessibleHdl; }
 361
 362     inline bool         IsDragable() const                          { return mbDragable; }
 363
 364     /** Creates and returns the accessible object of the header bar. */
 365     virtual ::com::sun::star::uno::Reference<
 366         ::com::sun::star::accessibility::XAccessible >  CreateAccessible() SAL_OVERRIDE;
 367     void SetAccessible( ::com::sun::star::uno::Reference< ::com::sun::star::accessibility::XAccessible > );
 368     virtual ::com::sun::star::uno::Reference< ::com::sun::star::awt::XWindowPeer > GetComponentInterface( bool bCreate ) SAL_OVERRIDE;
 369
 370 };
 371
 372 #endif // INCLUDED_SVTOOLS_HEADBAR_HXX
 373
 374 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */