include/vcl/toolkit/lstbox.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 #pragma once
  21
  22 #if !defined(VCL_DLLIMPLEMENTATION) && !defined(TOOLKIT_DLLIMPLEMENTATION) && !defined(VCL_INTERNALS)
  23 #error "don't use this in new code"
  24 #endif
  25
  26 #include <config_options.h>
  27 #include <sal/types.h>
  28 #include <o3tl/typed_flags_set.hxx>
  29 #include <vcl/dllapi.h>
  30 #include <vcl/ctrl.hxx>
  31
  32 class DataChangedEvent;
  33 class NotifyEvent;
  34 class UserDrawEvent;
  35
  36 #define LISTBOX_APPEND              (SAL_MAX_INT32)
  37 #define LISTBOX_ENTRY_NOTFOUND      (SAL_MAX_INT32)
  38 #define LISTBOX_MAX_ENTRIES         (SAL_MAX_INT32 - 1)
  39
  40 // the following defines can be used for the SetEntryFlags()
  41 // and GetEntryFlags() methods
  42
  43 // !! Do not use these flags for user data as they are reserved      !!
  44 // !! to change the internal behaviour of the ListBox implementation !!
  45 // !! for specific entries.                                          !!
  46
  47 enum class ListBoxEntryFlags
  48 {
  49     NONE                    = 0x0000,
  50 /** this flag disables a selection of an entry completely. It is not
  51     possible to select such entries either from the user interface
  52     nor from the ListBox methods. Cursor traveling is handled correctly.
  53     This flag can be used to add titles to a ListBox.
  54 */
  55     DisableSelection        = 0x0001,
  56
  57 /** this flag can be used to make an entry multiline capable
  58     A normal entry is single line and will therefore be clipped
  59     at the right listbox border. Setting this flag enables
  60     word breaks for the entry text.
  61 */
  62     MultiLine               = 0x0002,
  63
  64 /** this flags lets the item be drawn disabled (e.g. in grey text)
  65     usage only guaranteed with ListBoxEntryFlags::DisableSelection
  66 */
  67     DrawDisabled            = 0x0004,
  68 };
  69 namespace o3tl
  70 {
  71     template<> struct typed_flags<ListBoxEntryFlags> : is_typed_flags<ListBoxEntryFlags, 0x0007> {};
  72 }
  73
  74 class Image;
  75 class ImplListBox;
  76 class ImplListBoxFloatingWindow;
  77 class ImplBtn;
  78 class ImplWin;
  79 class ImplListBoxWindow;
  80
  81 /// A widget used to choose from a list of items and which has no entry.
  82 class VCL_DLLPUBLIC ListBox : public Control
  83 {
  84 private:
  85     VclPtr<ImplListBox>                mpImplLB;
  86     VclPtr<ImplListBoxFloatingWindow>  mpFloatWin;
  87     VclPtr<ImplWin>                    mpImplWin;
  88     VclPtr<ImplBtn>                    mpBtn;
  89     sal_uInt16                  mnDDHeight;
  90     sal_Int32                   m_nMaxWidthChars;
  91     Link<ListBox&,void>          maSelectHdl;
  92     sal_uInt16                  mnLineCount;
  93
  94     bool            mbDDAutoSize : 1;
  95
  96 private:
  97     SAL_DLLPRIVATE void    ImplInitListBoxData();
  98
  99     DECL_DLLPRIVATE_LINK( ImplSelectHdl, LinkParamNone*, void );
 100     DECL_DLLPRIVATE_LINK( ImplScrollHdl, ImplListBox*, void );
 101     DECL_DLLPRIVATE_LINK( ImplCancelHdl, LinkParamNone*, void );
 102     DECL_DLLPRIVATE_LINK( ImplDoubleClickHdl, ImplListBoxWindow*, void );
 103     DECL_DLLPRIVATE_LINK( ImplPopupModeEndHdl, FloatingWindow*, void );
 104     DECL_DLLPRIVATE_LINK( ImplSelectionChangedHdl, sal_Int32, void );
 105     DECL_DLLPRIVATE_LINK( ImplFocusHdl, sal_Int32, void );
 106     DECL_DLLPRIVATE_LINK( ImplListItemSelectHdl, LinkParamNone*, void );
 107
 108     DECL_DLLPRIVATE_LINK( ImplClickBtnHdl, void*, void );
 109
 110 protected:
 111     using Window::ImplInit;
 112     SAL_DLLPRIVATE void    ImplInit( vcl::Window* pParent, WinBits nStyle );
 113     SAL_DLLPRIVATE static WinBits ImplInitStyle( WinBits nStyle );
 114     bool               IsDropDownBox() const { return mpFloatWin != nullptr; }
 115
 116 protected:
 117     explicit            ListBox( WindowType nType );
 118
 119     virtual void        FillLayoutData() const override;
 120
 121 public:
 122     explicit            ListBox( vcl::Window* pParent, WinBits nStyle = WB_BORDER );
 123     virtual             ~ListBox() override;
 124     virtual void        dispose() override;
 125
 126     virtual void        ApplySettings(vcl::RenderContext& rRenderContext) override;
 127     virtual void        Draw( OutputDevice* pDev, const Point& rPos, SystemTextColorFlags nFlags ) override;
 128     virtual void        Resize() override;
 129     virtual bool        PreNotify( NotifyEvent& rNEvt ) override;
 130     virtual void        StateChanged( StateChangedType nType ) override;
 131     virtual void        DataChanged( const DataChangedEvent& rDCEvt ) override;
 132
 133     void                Select();
 134     void                DoubleClick();
 135     virtual void        GetFocus() override;
 136     virtual void        LoseFocus() override;
 137
 138     virtual const Wallpaper& GetDisplayBackground() const override;
 139
 140     virtual void        setPosSizePixel( tools::Long nX, tools::Long nY,
 141                                          tools::Long nWidth, tools::Long nHeight, PosSizeFlags nFlags = PosSizeFlags::All ) override;
 142
 143     tools::Rectangle           GetDropDownPosSizePixel() const;
 144
 145     void                AdaptDropDownLineCountToMaximum();
 146     void                SetDropDownLineCount( sal_uInt16 nLines );
 147     sal_uInt16          GetDropDownLineCount() const;
 148
 149     void                EnableAutoSize( bool bAuto );
 150     bool                IsAutoSizeEnabled() const { return mbDDAutoSize; }
 151
 152     sal_Int32           InsertEntry( const OUString& rStr, sal_Int32  nPos = LISTBOX_APPEND );
 153     sal_Int32           InsertEntry( const OUString& rStr, const Image& rImage, sal_Int32  nPos = LISTBOX_APPEND );
 154     void                RemoveEntry( sal_Int32  nPos );
 155
 156     void                Clear();
 157
 158     sal_Int32           GetEntryPos( std::u16string_view rStr ) const;
 159     Image               GetEntryImage( sal_Int32  nPos ) const;
 160     OUString            GetEntry( sal_Int32  nPos ) const;
 161     sal_Int32           GetEntryCount() const;
 162
 163     void                SelectEntry( std::u16string_view rStr, bool bSelect = true );
 164     void                SelectEntryPos( sal_Int32  nPos, bool bSelect = true );
 165     void                SelectEntriesPos( const std::vector<sal_Int32>& rPositions, bool bSelect = true );
 166
 167     sal_Int32           GetSelectedEntryCount() const;
 168     OUString            GetSelectedEntry( sal_Int32  nSelIndex = 0 ) const;
 169     sal_Int32           GetSelectedEntryPos( sal_Int32  nSelIndex = 0 ) const;
 170
 171     bool                IsEntryPosSelected( sal_Int32  nPos ) const;
 172     void                SetNoSelection();
 173
 174     void                SetEntryData( sal_Int32  nPos, void* pNewData );
 175     void*               GetEntryData( sal_Int32  nPos ) const;
 176
 177     /** this methods stores a combination of flags from the
 178         ListBoxEntryFlags::* defines at the given entry.
 179         See description of the possible ListBoxEntryFlags::* flags
 180         for details.
 181         Do not use these flags for user data as they are reserved
 182         to change the internal behaviour of the ListBox implementation
 183         for specific entries.
 184     */
 185     void                SetEntryFlags( sal_Int32  nPos, ListBoxEntryFlags nFlags );
 186
 187     void                SetTopEntry( sal_Int32  nPos );
 188     sal_Int32           GetTopEntry() const;
 189
 190     /**
 191      * Removes existing separators, and sets the position of the
 192      * one and only separator.
 193      */
 194     void                SetSeparatorPos( sal_Int32 n );
 195     /**
 196      * Gets the position of the separator which was added first.
 197      * Returns LISTBOX_ENTRY_NOTFOUND if there is no separator.
 198      */
 199     sal_Int32           GetSeparatorPos() const;
 200
 201     /**
 202      * Adds a new separator at the given position n.
 203      */
 204     void                AddSeparator( sal_Int32 n );
 205
 206     bool                IsTravelSelect() const;
 207     bool                IsInDropDown() const;
 208     void                ToggleDropDown();
 209
 210     void                EnableMultiSelection( bool bMulti );
 211     bool                IsMultiSelectionEnabled() const;
 212     void                SetHighlightColor(const Color& rColor);
 213     void                SetHighlightTextColor(const Color& rColor);
 214
 215     void                SetReadOnly( bool bReadOnly = true );
 216     bool                IsReadOnly() const;
 217
 218     tools::Rectangle           GetBoundingRectangle( sal_Int32  nItem ) const;
 219
 220     void                SetSelectHdl( const Link<ListBox&,void>& rLink )     { maSelectHdl = rLink; }
 221
 222     Size                CalcSubEditSize() const;    //size of area inside lstbox, i.e. no scrollbar/dropdown
 223     Size                CalcMinimumSize() const;    //size of lstbox area, i.e. including scrollbar/dropdown
 224     virtual Size        GetOptimalSize() const override;
 225     Size                CalcAdjustedSize( const Size& rPrefSize ) const;
 226     Size                CalcBlockSize( sal_uInt16 nColumns, sal_uInt16 nLines ) const;
 227     void                GetMaxVisColumnsAndLines( sal_uInt16& rnCols, sal_uInt16& rnLines ) const;
 228
 229     sal_uInt16          GetDisplayLineCount() const;
 230
 231     /** checks whether a certain point lies within the bounds of
 232         a listbox item and returns the item as well as the character position
 233         the point is at.
 234
 235         <p>If the point is inside an item the item pos is put into <code>rPos</code> and
 236         the item-relative character index is returned. If the point is not inside
 237         an item -1 is returned and rPos is unchanged.</p>
 238
 239         @param rPoint
 240         tells the point for which an item is requested.
 241
 242         @param rPos
 243         gets the item at the specified point <code>rPoint</code>
 244
 245         @returns
 246         the item-relative character index at point <code>rPos</code> or -1
 247         if no item is at that point.
 248      */
 249     using Control::GetIndexForPoint;
 250     tools::Long GetIndexForPoint( const Point& rPoint, sal_Int32 & rPos ) const;
 251
 252     void setMaxWidthChars(sal_Int32 nWidth);
 253
 254     virtual bool set_property(const OUString &rKey, const OUString &rValue) override;
 255
 256     virtual FactoryFunction GetUITestFactory() const override;
 257
 258     virtual void DumpAsPropertyTree(tools::JsonWriter&) override;
 259 };
 260
 261 class UNLESS_MERGELIBS(VCL_DLLPUBLIC) MultiListBox final : public ListBox
 262 {
 263 public:
 264     explicit        MultiListBox( vcl::Window* pParent, WinBits nStyle );
 265
 266 };
 267
 268 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */