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