include/svtools/valueset.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 _VALUESET_HXX
  21 #define _VALUESET_HXX
  22
  23 #include "svtools/svtdllapi.h"
  24
  25 #include <vcl/ctrl.hxx>
  26 #include <vcl/virdev.hxx>
  27 #include <vcl/timer.hxx>
  28 #include <vector>
  29
  30 class MouseEvent;
  31 class TrackingEvent;
  32 class HelpEvent;
  33 class KeyEvent;
  34 class DataChangedEvent;
  35 class ScrollBar;
  36
  37 struct ValueSetItem;
  38 typedef ::std::vector< ValueSetItem* > ValueItemList;
  39
  40 class ValueSetAcc;
  41 class ValueItemAcc;
  42
  43 /*************************************************************************
  44
  45 Description
  46 ============
  47
  48 class ValueSet
  49
  50 This class allows the selection of an item. In the process items are
  51 drawn side by side. The selection of items can be more clear than in a
  52 ListBox shape for example in case of colors or samples.
  53 The amount of columns drawn by the control and whether the items
  54 should be encircled can be specified. Optional a NoSelection or name
  55 field could be shown. By default image and color items are supported.
  56 Items could be drawn by oneself if InsertItem() is only called with
  57 an ID. To achieve this the UserDraw handler needs to be overloaded. The
  58 description text could be specified afterwards in case of UserDraw
  59 and any other items.
  60
  61 Cross references
  62
  63 class ListBox
  64
  65 --------------------------------------------------------------------------
  66
  67 WinBits
  68
  69 WB_RADIOSEL         If set the selection will be drawn like an
  70                     ImageRadioButton. This does only make sense if the image
  71                     is at least 8 pixel smaller on each side than the item
  72                     and also WB_DOUBLEBORDER is set and as color
  73                     COL_WINDOWWORKSPACE is specified.
  74 WB_FLATVALUESET     Flat Look (if you set WB_ITEMBORDER or WB_DOUBLEBORDER,
  75                     then you get extra border space, but the Borders
  76                     aren't painted),
  77 WB_ITEMBORDER       Items will be bordered
  78 WB_DOUBLEBORDER     Items will be bordered twice. Additionally WB_ITEMBORDER
  79                     has to be set, as otherwise this WinBit wouldn't have any
  80                     effect. It is needed if there are items with a white
  81                     background, since otherwise the 3D effect wouldn't be
  82                     recognizable.
  83 WB_NAMEFIELD        There is a namefield, where the name of an item will be
  84                     shown.
  85 WB_NONEFIELD        There is a NoSelection field which can be selected if
  86                     0 is passed along with SelectItem. Respectively
  87                     GetSelectItemId() returns 0 if this field or nothing
  88                     is selected. This field shows the text which is specified
  89                     by SetText() respectively no one, if no text was set. With
  90                     SetNoSelection() the selection can be disabled.
  91 WB_VSCROLL          A scroolbar will be always shown. The visible number of
  92                     lines have to be specified with SetLineCount() if this
  93                     flag is set.
  94 WB_BORDER           A border will be drawn around the window.
  95 WB_NOPOINTERFOCUS   The focus won't be gathered, if the control was pressed by
  96                     the mouse.
  97 WB_TABSTOP          It is possible to jump into the ValueSet with the tab key.
  98 WB_NOTABSTOP        It is not possible to jump into the ValueSet with the
  99                     tab key.
 100 WB_NO_DIRECTSELECT  Cursor travelling doesn't call select immediately. To
 101                     execute the selection <RETURN> has to be pressed.
 102 --------------------------------------------------------------------------
 103
 104 The number of columns must be either set with SetColCount() or
 105 SetItemWidth(). If the number of colums is specified by SetColCount()
 106 the width of the items will be calculated by the visible range.
 107 If the items should have a static width, it has to be specified
 108 with SetItemWidth(). In this case the number of columns will be calculated
 109 by the visible range.
 110
 111 The number of rows is given by the number of items / number of columns. The
 112 number of visible rows must either specified by SetLineCount() or
 113 SetItemWidth(). If the number of visible rows is specified by SetLineCount(),
 114 the height of the items will be calculated from the visible height. If the
 115 items should have a fixed height it has to be specified with SetItemHeight().
 116 In this case the number of visible rows is then calculated from the visible
 117 height. If the number of visible rows is neither specified by SetLineCount()
 118 nor by SetItemHeight() all rows will be shown. The height of the items will
 119 be calculated by the visible height. If the number of visible rows is
 120 specified by SetLineCount() or SetItemHeight() ValueSet does scroll
 121 automatically when more lines are available, as are visible. If scrolling
 122 should be also possible with a ScrollBar  WB_VSCROLL needs to be set.
 123
 124 The distance between the items can be increased by SetExtraSpacing(). The
 125 distance, which will be shown between two items (both in x and in y), is
 126 measured in pixels.
 127
 128 The exact window size for a specific item size can be calculated by
 129 CalcWindowSizePixel(). To do this all relevant data (number of columns/...)
 130 have to be specified and if no number of rows was set, all items need to
 131 be inserted. If the window was created with WB_BORDER/Border=sal_True the
 132 size has to be specified with SetOutputSizePixel(). In other cases different
 133 size-methods can be used. With CalcItemSize() the inner and outer size of
 134 an item could be calculated (for this the free space defined by
 135 SetExtraSpacing() will not be included).
 136
 137 The background color could be specified by SetColor(), with which the image
 138 or UserDraw items will be underlayed. If no color is specified the color
 139 of other windows (WindowColor) will be used for the background.
 140
 141 --------------------------------------------------------------------------
 142
 143 At first all items should be inserted and only then Show() should be called
 144 since the output area will be precomputed. If this is not done the first
 145 Paint will appear a little bit slower. Therefore the Control, if it is loaded
 146 from the resource and only supplied with items during runtime, should be
 147 loaded with Hide = sal_True and then displayed with Show().
 148
 149 In case of a visible Control the creation of the new output area could be
 150 activated before Paint by calling Format().
 151
 152 --------------------------------------------------------------------------
 153
 154 If Drag and Drop will be called from the ValueSet the Command-Handler has to
 155 be overloaded. From this StartDrag needs to be called. If this method returns
 156 sal_True the drag-process could be initiated by  ExecuteDrag(), otherwise no
 157 processing will take place. This method makes sure that ValueSet stops its
 158 processing and as appropriate selects the entry. Therefore the calling of
 159 Select-Handler within this function must be expected.
 160
 161 For dropping QueryDrop() and Drop() need to be overloaded and ShowDropPos()
 162 and HideDropPos() should be called within these methods.
 163 To show the insertion point ShowDropPos() has to be called within the
 164 QueryDrop-Handler. ShowDropPos() also scrolls the ValueSet if the passed
 165 position is located at the window border. Furthermore ShowDropPos() returns
 166 the position, at which the item should be inserted respectively which
 167 insertion point was shown. If no insertion point was determined
 168 VALUESET_ITEM_NOTFOUND will be returned. If the window was left during dragging
 169 or the drag process is terminated HideDropPos() should be called in any case.
 170
 171 --------------------------------------------------------------------------
 172
 173 This class is currently still in the SV-Tools. That's why the ValueSet needs
 174 to be loaded as a Control out of the resource and the desired WinBits have
 175 to be set (before Show) with SetStyle().
 176
 177 *************************************************************************/
 178
 179 // ------------------
 180 // - ValueSet types -
 181 // ------------------
 182
 183 #define WB_RADIOSEL             ((WinBits)0x00008000)
 184 #define WB_ITEMBORDER           ((WinBits)0x00010000)
 185 #define WB_DOUBLEBORDER         ((WinBits)0x00020000)
 186 #define WB_NAMEFIELD            ((WinBits)0x00040000)
 187 #define WB_NONEFIELD            ((WinBits)0x00080000)
 188 #define WB_FLATVALUESET         ((WinBits)0x02000000)
 189 #define WB_NO_DIRECTSELECT      ((WinBits)0x04000000)
 190 #define WB_MENUSTYLEVALUESET    ((WinBits)0x08000000)
 191
 192 // ------------
 193 // - ValueSet -
 194 // ------------
 195
 196 #define VALUESET_APPEND         ((sal_uInt16)-1)
 197 #define VALUESET_ITEM_NOTFOUND  ((sal_uInt16)-1)
 198
 199 class SVT_DLLPUBLIC ValueSet : public Control
 200 {
 201 private:
 202
 203     VirtualDevice   maVirDev;
 204     Timer           maTimer;
 205     ValueItemList   mItemList;
 206     ValueSetItem*   mpNoneItem;
 207     ScrollBar*      mpScrBar;
 208     Rectangle       maNoneItemRect;
 209     Rectangle       maItemListRect;
 210     long            mnItemWidth;
 211     long            mnItemHeight;
 212     long            mnTextOffset;
 213     long            mnVisLines;
 214     long            mnLines;
 215     long            mnUserItemWidth;
 216     long            mnUserItemHeight;
 217     sal_uInt16      mnSelItemId;
 218     sal_uInt16      mnHighItemId;
 219     sal_uInt16      mnCols;
 220     sal_uInt16      mnCurCol;
 221     sal_uInt16      mnUserCols;
 222     sal_uInt16      mnUserVisLines;
 223     sal_uInt16      mnFirstLine;
 224     sal_uInt16      mnSpacing;
 225     sal_uInt16      mnFrameStyle;
 226     Color           maColor;
 227     Link            maDoubleClickHdl;
 228     Link            maSelectHdl;
 229     Link            maHighlightHdl;
 230
 231     // bitfield
 232     bool            mbFormat : 1;
 233     bool            mbHighlight : 1;
 234     bool            mbSelection : 1;
 235     bool            mbNoSelection : 1;
 236     bool            mbDrawSelection : 1;
 237     bool            mbBlackSel : 1;
 238     bool            mbDoubleSel : 1;
 239     bool            mbScroll : 1;
 240     bool            mbFullMode : 1;
 241     bool            mbEdgeBlending : 1;
 242     bool            mbIsTransientChildrenDisabled : 1;
 243     bool            mbHasVisibleItems : 1;
 244
 245     friend class ValueSetAcc;
 246     friend class ValueItemAcc;
 247     using Control::ImplInitSettings;
 248     using Window::ImplInit;
 249     SVT_DLLPRIVATE void         ImplInit();
 250     SVT_DLLPRIVATE void         ImplInitSettings( bool bFont, bool bForeground, bool bBackground );
 251     SVT_DLLPRIVATE void         ImplInitScrollBar();
 252     SVT_DLLPRIVATE void         ImplDeleteItems();
 253     SVT_DLLPRIVATE void         ImplFormatItem( ValueSetItem* pItem, Rectangle aRect );
 254     SVT_DLLPRIVATE void         ImplDrawItemText(const OUString& rStr);
 255     SVT_DLLPRIVATE void         ImplDrawSelect( sal_uInt16 nItemId, const bool bFocus, const bool bDrawSel );
 256     SVT_DLLPRIVATE void         ImplDrawSelect();
 257     SVT_DLLPRIVATE void         ImplHideSelect( sal_uInt16 nItemId );
 258     SVT_DLLPRIVATE void         ImplHighlightItem( sal_uInt16 nItemId, bool bIsSelection = true );
 259     SVT_DLLPRIVATE void         ImplDraw();
 260     using Window::ImplScroll;
 261     SVT_DLLPRIVATE bool         ImplScroll( const Point& rPos );
 262     SVT_DLLPRIVATE size_t       ImplGetItem( const Point& rPoint, bool bMove = false ) const;
 263     SVT_DLLPRIVATE ValueSetItem*    ImplGetItem( size_t nPos );
 264     SVT_DLLPRIVATE ValueSetItem*    ImplGetFirstItem();
 265     SVT_DLLPRIVATE sal_uInt16          ImplGetVisibleItemCount() const;
 266     SVT_DLLPRIVATE ValueSetItem*    ImplGetVisibleItem( sal_uInt16 nVisiblePos );
 267     SVT_DLLPRIVATE void         ImplInsertItem( ValueSetItem *const pItem, const size_t nPos );
 268     SVT_DLLPRIVATE Rectangle    ImplGetItemRect( size_t nPos ) const;
 269     SVT_DLLPRIVATE void            ImplFireAccessibleEvent( short nEventId, const ::com::sun::star::uno::Any& rOldValue, const ::com::sun::star::uno::Any& rNewValue );
 270     SVT_DLLPRIVATE bool         ImplHasAccessibleListeners();
 271     SVT_DLLPRIVATE void         ImplTracking( const Point& rPos, bool bRepeat );
 272     SVT_DLLPRIVATE void         ImplEndTracking( const Point& rPos, bool bCancel );
 273     DECL_DLLPRIVATE_LINK( ImplScrollHdl, ScrollBar* );
 274     DECL_DLLPRIVATE_LINK( ImplTimerHdl, void* );
 275
 276     // Forbidden and not implemented.
 277     ValueSet (const ValueSet &);
 278     ValueSet & operator= (const ValueSet &);
 279
 280 protected:
 281
 282     bool            StartDrag( const CommandEvent& rCEvt, Region& rRegion );
 283
 284 protected:
 285
 286     virtual ::com::sun::star::uno::Reference< ::com::sun::star::accessibility::XAccessible > CreateAccessible();
 287
 288 public:
 289                     ValueSet( Window* pParent, WinBits nWinStyle, bool bDisableTransientChildren = false );
 290                     ValueSet( Window* pParent, const ResId& rResId, bool bDisableTransientChildren = false );
 291                     ~ValueSet();
 292
 293     virtual void    MouseButtonDown( const MouseEvent& rMEvt );
 294     virtual void    MouseButtonUp( const MouseEvent& rMEvt );
 295     virtual void    MouseMove( const MouseEvent& rMEvt );
 296     virtual void    Tracking( const TrackingEvent& rMEvt );
 297     virtual void    KeyInput( const KeyEvent& rKEvt );
 298     virtual void    Command( const CommandEvent& rCEvt );
 299     virtual void    Paint( const Rectangle& rRect );
 300     virtual void    GetFocus();
 301     virtual void    LoseFocus();
 302     virtual void    Resize();
 303     virtual Size    GetOptimalSize() const;
 304     virtual void    RequestHelp( const HelpEvent& rHEvt );
 305     virtual void    StateChanged( StateChangedType nStateChange );
 306     virtual void    DataChanged( const DataChangedEvent& rDCEvt );
 307
 308     virtual void    Select();
 309     virtual void    DoubleClick();
 310     virtual void    UserDraw( const UserDrawEvent& rUDEvt );
 311
 312     void            InsertItem( sal_uInt16 nItemId, const Image& rImage,
 313                                 size_t nPos = VALUESET_APPEND );
 314     void            InsertItem( sal_uInt16 nItemId, const Color& rColor,
 315                                 size_t nPos = VALUESET_APPEND );
 316     void            InsertItem( sal_uInt16 nItemId,
 317                                 const Image& rImage, const OUString& rStr,
 318                                 size_t nPos = VALUESET_APPEND );
 319     void            InsertItem( sal_uInt16 nItemId,
 320                                 const Color& rColor, const OUString& rStr,
 321                                 size_t nPos = VALUESET_APPEND );
 322     void            InsertItem( sal_uInt16 nItemId,
 323                                 size_t nPos = VALUESET_APPEND );
 324     void            RemoveItem( sal_uInt16 nItemId );
 325
 326     void            Clear();
 327
 328     size_t          GetItemCount() const;
 329     size_t          GetItemPos( sal_uInt16 nItemId ) const;
 330     sal_uInt16          GetItemId( size_t nPos ) const;
 331     sal_uInt16          GetItemId( const Point& rPos ) const;
 332     Rectangle       GetItemRect( sal_uInt16 nItemId ) const;
 333
 334     void            EnableFullItemMode( bool bFullMode = true );
 335     bool            IsFullItemModeEnabled() const { return mbFullMode; }
 336     void            SetColCount( sal_uInt16 nNewCols = 1 );
 337     sal_uInt16          GetColCount() const { return mnUserCols; }
 338     void            SetLineCount( sal_uInt16 nNewLines = 0 );
 339     sal_uInt16          GetLineCount() const { return mnUserVisLines; }
 340     void            SetItemWidth( long nItemWidth = 0 );
 341     long            GetItemWidth() const { return mnUserItemWidth; }
 342     void            SetItemHeight( long nLineHeight = 0 );
 343     long            GetItemHeight() const { return mnUserItemHeight; }
 344     sal_uInt16          GetFirstLine() const { return mnFirstLine; }
 345
 346     void            SelectItem( sal_uInt16 nItemId );
 347     sal_uInt16          GetSelectItemId() const { return mnSelItemId; }
 348     bool            IsItemSelected( sal_uInt16 nItemId ) const
 349                         { return !mbNoSelection && (nItemId == mnSelItemId); }
 350     void            SetNoSelection();
 351     bool            IsNoSelection() const { return mbNoSelection; }
 352
 353     void            SetItemImage( sal_uInt16 nItemId, const Image& rImage );
 354     Image           GetItemImage( sal_uInt16 nItemId ) const;
 355     void            SetItemColor( sal_uInt16 nItemId, const Color& rColor );
 356     Color           GetItemColor( sal_uInt16 nItemId ) const;
 357     void            SetItemData( sal_uInt16 nItemId, void* pData );
 358     void*           GetItemData( sal_uInt16 nItemId ) const;
 359     void            SetItemText( sal_uInt16 nItemId, const OUString& rStr );
 360     OUString        GetItemText( sal_uInt16 nItemId ) const;
 361     void            SetColor( const Color& rColor );
 362     void            SetColor() { SetColor( Color( COL_TRANSPARENT ) ); }
 363     Color           GetColor() const { return maColor; }
 364     bool            IsColor() const { return maColor.GetTransparency() == 0; }
 365
 366     void            SetExtraSpacing( sal_uInt16 nNewSpacing );
 367     sal_uInt16          GetExtraSpacing() { return mnSpacing; }
 368
 369     void            Format();
 370
 371     void            StartSelection();
 372     void            EndSelection();
 373
 374     Size            CalcWindowSizePixel( const Size& rItemSize,
 375                                          sal_uInt16 nCalcCols = 0,
 376                                          sal_uInt16 nCalcLines = 0 ) const;
 377     Size            CalcItemSizePixel( const Size& rSize, bool bOut = true ) const;
 378     long            GetScrollWidth() const;
 379
 380     void            SetSelectHdl( const Link& rLink ) { maSelectHdl = rLink; }
 381     const Link&     GetSelectHdl() const { return maSelectHdl; }
 382     void            SetDoubleClickHdl( const Link& rLink ) { maDoubleClickHdl = rLink; }
 383     const Link&     GetDoubleClickHdl() const { return maDoubleClickHdl; }
 384
 385     void            SetHighlightHdl( const Link& rLink );
 386
 387     bool GetEdgeBlending() const { return mbEdgeBlending; }
 388     void SetEdgeBlending(bool bNew);
 389 };
 390
 391 #endif  // _VALUESET_HXX
 392
 393 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */