include/wx/msw/imaglist.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        wx/msw/imaglist.h
   3 // Purpose:     wxImageList class
   4 // Author:      Julian Smart
   5 // Modified by:
   6 // Created:     01/02/97
   7 // RCS-ID:      $Id$
   8 // Copyright:   (c) Julian Smart
   9 // Licence:     wxWindows licence
  10 /////////////////////////////////////////////////////////////////////////////
  11
  12 #ifndef _WX_IMAGLIST_H_
  13 #define _WX_IMAGLIST_H_
  14
  15 #if defined(__GNUG__) && !defined(NO_GCC_PRAGMA)
  16 #pragma interface "imaglist.h"
  17 #endif
  18
  19 #include "wx/bitmap.h"
  20
  21 /*
  22  * wxImageList is used for wxListCtrl, wxTreeCtrl. These controls refer to
  23  * images for their items by an index into an image list.
  24  * A wxImageList is capable of creating images with optional masks from
  25  * a variety of sources - a single bitmap plus a colour to indicate the mask,
  26  * two bitmaps, or an icon.
  27  *
  28  * Image lists can also create and draw images used for drag and drop functionality.
  29  * This is not yet implemented in wxImageList. We need to discuss a generic API
  30  * for doing drag and drop and see whether it ties in with the Win95 view of it.
  31  * See below for candidate functions and an explanation of how they might be
  32  * used.
  33  */
  34
  35 // Flags for Draw
  36 #define wxIMAGELIST_DRAW_NORMAL         0x0001
  37 #define wxIMAGELIST_DRAW_TRANSPARENT    0x0002
  38 #define wxIMAGELIST_DRAW_SELECTED       0x0004
  39 #define wxIMAGELIST_DRAW_FOCUSED        0x0008
  40
  41 // Flag values for Set/GetImageList
  42 enum {
  43     wxIMAGE_LIST_NORMAL, // Normal icons
  44     wxIMAGE_LIST_SMALL,  // Small icons
  45     wxIMAGE_LIST_STATE   // State icons: unimplemented (see WIN32 documentation)
  46 };
  47
  48 // Eventually we'll make this a reference-counted wxGDIObject. For
  49 // now, the app must take care of ownership issues. That is, the
  50 // image lists must be explicitly deleted after the control(s) that uses them
  51 // is (are) deleted, or when the app exits.
  52 class WXDLLEXPORT wxImageList : public wxObject
  53 {
  54 public:
  55   /*
  56    * Public interface
  57    */
  58
  59   wxImageList();
  60
  61   // Creates an image list.
  62   // Specify the width and height of the images in the list,
  63   // whether there are masks associated with them (e.g. if creating images
  64   // from icons), and the initial size of the list.
  65   wxImageList(int width, int height, bool mask = TRUE, int initialCount = 1)
  66   {
  67     Create(width, height, mask, initialCount);
  68   }
  69   ~wxImageList();
  70
  71
  72   // Attributes
  73   ////////////////////////////////////////////////////////////////////////////
  74
  75   // Returns the number of images in the image list.
  76   int GetImageCount() const;
  77
  78   // Returns the size (same for all images) of the images in the list
  79   bool GetSize(int index, int &width, int &height) const;
  80
  81   // Operations
  82   ////////////////////////////////////////////////////////////////////////////
  83
  84   // Creates an image list
  85   // width, height specify the size of the images in the list (all the same).
  86   // mask specifies whether the images have masks or not.
  87   // initialNumber is the initial number of images to reserve.
  88   bool Create(int width, int height, bool mask = TRUE, int initialNumber = 1);
  89
  90   // Adds a bitmap, and optionally a mask bitmap.
  91   // Note that wxImageList creates *new* bitmaps, so you may delete
  92   // 'bitmap' and 'mask' after calling Add.
  93   int Add(const wxBitmap& bitmap, const wxBitmap& mask = wxNullBitmap);
  94
  95   // Adds a bitmap, using the specified colour to create the mask bitmap
  96   // Note that wxImageList creates *new* bitmaps, so you may delete
  97   // 'bitmap' after calling Add.
  98   int Add(const wxBitmap& bitmap, const wxColour& maskColour);
  99
 100   // Adds a bitmap and mask from an icon.
 101   int Add(const wxIcon& icon);
 102
 103   // Replaces a bitmap, optionally passing a mask bitmap.
 104   // Note that wxImageList creates new bitmaps, so you may delete
 105   // 'bitmap' and 'mask' after calling Replace.
 106   bool Replace(int index, const wxBitmap& bitmap, const wxBitmap& mask = wxNullBitmap);
 107
 108 /* Not supported by Win95
 109   // Replacing a bitmap, using the specified colour to create the mask bitmap
 110   // Note that wxImageList creates new bitmaps, so you may delete
 111   // 'bitmap'.
 112   bool Replace(int index, const wxBitmap& bitmap, const wxColour& maskColour);
 113 */
 114
 115   // Replaces a bitmap and mask from an icon.
 116   // You can delete 'icon' after calling Replace.
 117   bool Replace(int index, const wxIcon& icon);
 118
 119   // Removes the image at the given index.
 120   bool Remove(int index);
 121
 122   // Remove all images
 123   bool RemoveAll();
 124
 125   // Draws the given image on a dc at the specified position.
 126   // If 'solidBackground' is TRUE, Draw sets the image list background
 127   // colour to the background colour of the wxDC, to speed up
 128   // drawing by eliminating masked drawing where possible.
 129   bool Draw(int index, wxDC& dc, int x, int y,
 130             int flags = wxIMAGELIST_DRAW_NORMAL,
 131             bool solidBackground = FALSE);
 132
 133   // TODO: miscellaneous functionality
 134 /*
 135   wxIcon *MakeIcon(int index);
 136   bool SetOverlayImage(int index, int overlayMask);
 137
 138 */
 139
 140   // TODO: Drag-and-drop related functionality.
 141
 142 #if 0
 143   // Creates a new drag image by combining the given image (typically a mouse cursor image)
 144   // with the current drag image.
 145   bool SetDragCursorImage(int index, const wxPoint& hotSpot);
 146
 147   // If successful, returns a pointer to the temporary image list that is used for dragging;
 148   // otherwise, NULL.
 149   // dragPos: receives the current drag position.
 150   // hotSpot: receives the offset of the drag image relative to the drag position.
 151   static wxImageList *GetDragImageList(wxPoint& dragPos, wxPoint& hotSpot);
 152
 153   // Call this function to begin dragging an image. This function creates a temporary image list
 154   // that is used for dragging. The image combines the specified image and its mask with the
 155   // current cursor. In response to subsequent mouse move messages, you can move the drag image
 156   // by using the DragMove member function. To end the drag operation, you can use the EndDrag
 157   // member function.
 158   bool BeginDrag(int index, const wxPoint& hotSpot);
 159
 160   // Ends a drag operation.
 161   bool EndDrag();
 162
 163   // Call this function to move the image that is being dragged during a drag-and-drop operation.
 164   // This function is typically called in response to a mouse move message. To begin a drag
 165   // operation, use the BeginDrag member function.
 166   static bool DragMove(const wxPoint& point);
 167
 168   // During a drag operation, locks updates to the window specified by lockWindow and displays
 169   // the drag image at the position specified by point.
 170   // The coordinates are relative to the window's upper left corner, so you must compensate
 171   // for the widths of window elements, such as the border, title bar, and menu bar, when
 172   // specifying the coordinates.
 173   // If lockWindow is NULL, this function draws the image in the display context associated
 174   // with the desktop window, and coordinates are relative to the upper left corner of the screen.
 175   // This function locks all other updates to the given window during the drag operation.
 176   // If you need to do any drawing during a drag operation, such as highlighting the target
 177   // of a drag-and-drop operation, you can temporarily hide the dragged image by using the
 178   // wxImageList::DragLeave function.
 179
 180   // lockWindow: pointer to the window that owns the drag image.
 181   // point:      position at which to display the drag image. Coordinates are relative to the
 182   //             upper left corner of the window (not the client area).
 183
 184   static bool DragEnter( wxWindow *lockWindow, const wxPoint& point );
 185
 186   // Unlocks the window specified by pWndLock and hides the drag image, allowing the
 187   // window to be updated.
 188   static bool DragLeave( wxWindow *lockWindow );
 189
 190   /* Here's roughly how you'd use these functions if implemented in this Win95-like way:
 191
 192   1) Starting to drag:
 193
 194   wxImageList *dragImageList = new wxImageList(16, 16, TRUE);
 195   dragImageList->Add(myDragImage); // Provide an image to combine with the current cursor
 196   dragImageList->BeginDrag(0, wxPoint(0, 0));
 197   wxShowCursor(FALSE);        // wxShowCursor not yet implemented in wxWin
 198   myWindow->CaptureMouse();
 199
 200   2) Dragging:
 201
 202   // Called within mouse move event. Could also use dragImageList instead of assuming
 203   // these are static functions.
 204   // These two functions could possibly be combined into one, since DragEnter is
 205   // a bit obscure.
 206   wxImageList::DragMove(wxPoint(x, y));  // x, y are current cursor position
 207   wxImageList::DragEnter(NULL, wxPoint(x, y)); // NULL assumes dragging across whole screen
 208
 209   3) Finishing dragging:
 210
 211   dragImageList->EndDrag();
 212   myWindow->ReleaseMouse();
 213   wxShowCursor(TRUE);
 214 */
 215
 216 #endif
 217
 218   // Implementation
 219   ////////////////////////////////////////////////////////////////////////////
 220
 221   // Returns the native image list handle
 222   WXHIMAGELIST GetHIMAGELIST() const { return m_hImageList; }
 223
 224 protected:
 225   WXHIMAGELIST m_hImageList;
 226
 227   DECLARE_DYNAMIC_CLASS(wxImageList)
 228 };
 229
 230 #endif
 231     // _WX_IMAGLIST_H_