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