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