]> git.saurik.com Git - wxWidgets.git/blob - include/wx/osx/carbon/dataview.h
Extensive documentation typo patch (closes #13063).
[wxWidgets.git] / include / wx / osx / carbon / dataview.h
1 /////////////////////////////////////////////////////////////////////////////
2 // Name: wx/osx/carbon/dataview.h
3 // Purpose: wxDataViewCtrl native implementation header for carbon
4 // Author:
5 // Id: $Id: dataview.h 57374 2009-01-27
6 // Copyright: (c) 2009
7 // Licence: wxWindows licence
8 /////////////////////////////////////////////////////////////////////////////
9
10 #ifndef _WX_DATAVIEWCTRL_CARBON_H_
11 #define _WX_DATAVIEWCTRL_CARBON_H_
12
13 #include "wx/defs.h"
14
15 #if wxUSE_GUI
16
17 #include "wx/osx/core/dataview.h"
18 #include "wx/osx/private.h"
19
20 // ============================================================================
21 // wxDataViewColumnNativeData
22 // ============================================================================
23 class wxDataViewColumnNativeData
24 {
25 public:
26 //
27 // constructors / destructor
28 //
29 wxDataViewColumnNativeData()
30 {
31 }
32 wxDataViewColumnNativeData(DataBrowserPropertyID initPropertyID)
33 :m_PropertyID(initPropertyID)
34 {
35 }
36
37 //
38 // data access methods
39 //
40 DataBrowserPropertyID GetPropertyID() const
41 {
42 return m_PropertyID;
43 }
44
45 void SetPropertyID(DataBrowserPropertyID newPropertyID)
46 {
47 m_PropertyID = newPropertyID;
48 }
49
50 protected:
51 private:
52 //
53 // variables
54 //
55 DataBrowserPropertyID m_PropertyID; // each column is identified by its unique property ID (NOT by the column's index)
56 };
57
58 // ============================================================================
59 // wxDataViewRendererNativeData
60 // ============================================================================
61 class wxDataViewRendererNativeData
62 {
63 public:
64 //
65 // constructors / destructor
66 //
67 wxDataViewRendererNativeData()
68 {
69 }
70 wxDataViewRendererNativeData(DataBrowserPropertyType initPropertyType, DataBrowserItemDataRef initItemDataRef=NULL)
71 :m_ItemDataRef(initItemDataRef), m_PropertyType(initPropertyType)
72 {
73 }
74
75 //
76 // data access methods
77 //
78 DataBrowserItemDataRef GetItemDataRef() const
79 {
80 return m_ItemDataRef;
81 }
82 DataBrowserPropertyType GetPropertyType() const
83 {
84 return m_PropertyType;
85 }
86
87 void SetItemDataRef(DataBrowserItemDataRef newItemDataRef)
88 {
89 m_ItemDataRef = newItemDataRef;
90 }
91 void SetPropertyType(DataBrowserPropertyType newPropertyType)
92 {
93 m_PropertyType = newPropertyType;
94 }
95
96 protected:
97 private:
98 //
99 // variables
100 //
101 DataBrowserItemDataRef m_ItemDataRef;
102
103 DataBrowserPropertyType m_PropertyType;
104 };
105
106 // ============================================================================
107 // wxMacDataBrowserTableViewControl
108 // ============================================================================
109 //
110 // This is a wrapper class for the Mac OS X data browser environment.
111 // It covers all data brower functionality for the native browser's list
112 // and column style.
113 //
114
115 // data browser's property IDs have a reserved ID range from 0 - 1023
116 // therefore, the first usable property ID is 'kMinPropertyID'
117 DataBrowserPropertyID const kMinPropertyID = 1024;
118
119 // array of data browser item IDs
120 WX_DEFINE_ARRAY_SIZE_T(size_t,wxArrayDataBrowserItemID);
121
122 class wxMacDataBrowserTableViewControl : public wxMacControl
123 {
124 public:
125 //
126 // constructors / destructor
127 //
128 wxMacDataBrowserTableViewControl(wxWindow* peer, const wxPoint& pos, const wxSize& size, long style);
129 wxMacDataBrowserTableViewControl()
130 {
131 }
132 ~wxMacDataBrowserTableViewControl();
133
134 //
135 // callback handling
136 //
137 OSStatus SetCallbacks (DataBrowserCallbacks const* callbacks);
138 OSStatus SetCustomCallbacks(DataBrowserCustomCallbacks const* customCallbacks);
139
140 //
141 // DnD handling
142 //
143 OSStatus EnableAutomaticDragTracking(bool enable=true);
144
145 //
146 // header handling
147 //
148 OSStatus GetHeaderDesc(DataBrowserPropertyID property, DataBrowserListViewHeaderDesc* desc) const;
149
150 OSStatus SetHeaderDesc(DataBrowserPropertyID property, DataBrowserListViewHeaderDesc* desc);
151
152 //
153 // layout handling
154 //
155 OSStatus AutoSizeColumns();
156
157 OSStatus EnableCellSizeModification(bool enableHeight=true, bool enableWidth=true); // enables or disables the column width and row height modification (default: false)
158
159 #if MAC_OS_X_VERSION_MAX_ALLOWED >= MAC_OS_X_VERSION_10_4
160 OSStatus GetAttributes (OptionBits* attributes);
161 #endif
162 OSStatus GetColumnWidth (DataBrowserPropertyID column, UInt16 *width ) const; // returns the column width in pixels
163 OSStatus GetDefaultColumnWidth(UInt16 *width ) const; // returns the default column width in pixels
164 OSStatus GetDefaultRowHeight (UInt16 * height ) const;
165 OSStatus GetHeaderButtonHeight(UInt16 *height );
166 OSStatus GetPartBounds (DataBrowserItemID item, DataBrowserPropertyID property, DataBrowserPropertyPart part, Rect* bounds);
167 OSStatus GetRowHeight (DataBrowserItemID item , UInt16 *height) const;
168 OSStatus GetScrollPosition (UInt32* top, UInt32 *left) const;
169
170 #if MAC_OS_X_VERSION_MAX_ALLOWED >= MAC_OS_X_VERSION_10_4
171 OSStatus SetAttributes (OptionBits attributes);
172 #endif
173 OSStatus SetColumnWidth(DataBrowserPropertyID column, UInt16 width); // sets the column width in pixels
174 OSStatus SetDefaultColumnWidth( UInt16 width );
175 OSStatus SetDefaultRowHeight( UInt16 height );
176 OSStatus SetHasScrollBars( bool horiz, bool vert );
177 OSStatus SetHeaderButtonHeight( UInt16 height );
178 OSStatus SetHiliteStyle(DataBrowserTableViewHiliteStyle hiliteStyle);
179 OSStatus SetIndent(float Indent);
180 OSStatus SetItemRowHeight( DataBrowserItemID item , UInt16 height);
181 OSStatus SetScrollPosition( UInt32 top , UInt32 left );
182
183 //
184 // column handling
185 //
186 OSStatus GetColumnCount (UInt32* numColumns) const;
187 OSStatus GetColumnIndex (DataBrowserPropertyID propertyID, DataBrowserTableViewColumnIndex* index) const; // returns for the passed property the corresponding column index
188 OSStatus GetFreePropertyID(DataBrowserPropertyID* propertyID) const; // this method returns a property id that is valid and currently not used; if it cannot be found 'errDataBrowerPropertyNotSupported' is returned
189 OSStatus GetPropertyFlags (DataBrowserPropertyID propertyID, DataBrowserPropertyFlags *flags ) const;
190 OSStatus GetPropertyID (DataBrowserItemDataRef itemData, DataBrowserPropertyID* propertyID) const; // returns for the passed item data reference the corresponding property ID
191 OSStatus GetPropertyID (DataBrowserTableViewColumnIndex index, DataBrowserPropertyID* propertyID) const; // returns for the passed column index the corresponding property ID
192
193 OSStatus IsUsedPropertyID(DataBrowserPropertyID propertyID) const; // checks if passed property id is used by the control; no error is returned if the id exists
194
195 OSStatus RemoveColumnByProperty(DataBrowserTableViewColumnID propertyID);
196 OSStatus RemoveColumnByIndex (DataBrowserTableViewColumnIndex index);
197
198 OSStatus SetColumnIndex (DataBrowserPropertyID propertyID, DataBrowserTableViewColumnIndex index);
199 OSStatus SetDisclosureColumn(DataBrowserPropertyID propertyID, Boolean expandableRows=false);
200 OSStatus SetPropertyFlags (DataBrowserPropertyID propertyID, DataBrowserPropertyFlags flags);
201
202 //
203 // item handling
204 //
205 OSStatus AddItem(DataBrowserItemID container, DataBrowserItemID const* itemID) // adds a single item
206 {
207 return AddItems(container,1,itemID,kDataBrowserItemNoProperty);
208 }
209 OSStatus AddItems(DataBrowserItemID container, UInt32 numItems, DataBrowserItemID const* items, DataBrowserPropertyID preSortProperty); // adds items to the data browser
210
211 OSStatus GetFreeItemID(DataBrowserItemID* id) const; // this method returns an item id that is valid and currently not used; if it cannot be found 'errDataBrowserItemNotAdded' is returned
212 OSStatus GetItemCount (ItemCount* numItems) const
213 {
214 return GetItemCount(kDataBrowserNoItem,true,kDataBrowserItemAnyState,numItems);
215 }
216 OSStatus GetItemCount (DataBrowserItemID container, Boolean recurse, DataBrowserItemState state, ItemCount* numItems) const;
217 OSStatus GetItemID (DataBrowserTableViewRowIndex row, DataBrowserItemID* item) const;
218 OSStatus GetItems (DataBrowserItemID container, Boolean recurse, DataBrowserItemState state, Handle items) const;
219 OSStatus GetItemRow (DataBrowserItemID item, DataBrowserTableViewRowIndex* row) const;
220 OSStatus GetItemState (DataBrowserItemID item, DataBrowserItemState* state) const;
221
222 OSStatus IsUsedItemID(DataBrowserItemID itemID) const; // checks if the passed id is in use
223
224 OSStatus RevealItem(DataBrowserItemID item, DataBrowserPropertyID propertyID, DataBrowserRevealOptions options) const;
225
226 OSStatus RemoveItem(DataBrowserItemID container, DataBrowserItemID const* itemID) // removes a single item
227 {
228 return RemoveItems(container,1,itemID,kDataBrowserItemNoProperty);
229 }
230 OSStatus RemoveItems(void) // removes all items
231 {
232 return RemoveItems(kDataBrowserNoItem,0,NULL,kDataBrowserItemNoProperty);
233 }
234 OSStatus RemoveItems(DataBrowserItemID container, UInt32 numItems, DataBrowserItemID const* items, DataBrowserPropertyID preSortProperty);
235
236 OSStatus UpdateItem(DataBrowserItemID container, DataBrowserItemID const* item) // updates all columns of the passed item
237 {
238 return UpdateItems(container,1,item,kDataBrowserItemNoProperty,kDataBrowserItemNoProperty);
239 }
240 OSStatus UpdateItems(void) // updates all items
241 {
242 return UpdateItems(kDataBrowserNoItem,0,NULL,kDataBrowserItemNoProperty,kDataBrowserItemNoProperty);
243 }
244 OSStatus UpdateItems(DataBrowserItemID container, UInt32 numItems, DataBrowserItemID const* items, DataBrowserPropertyID preSortProperty, DataBrowserPropertyID propertyID) const;
245
246 //
247 // item selection
248 //
249 size_t GetSelectedItemIDs(wxArrayDataBrowserItemID& itemIDs) const; // returns the number of selected item and the item IDs in the array
250 OSStatus GetSelectionAnchor(DataBrowserItemID *first, DataBrowserItemID *last) const;
251 OSStatus GetSelectionFlags (DataBrowserSelectionFlags* flags) const;
252
253 bool IsItemSelected(DataBrowserItemID item) const;
254
255 OSStatus SetSelectionFlags(DataBrowserSelectionFlags flags);
256 OSStatus SetSelectedItems (UInt32 numItems, DataBrowserItemID const* itemIDs, DataBrowserSetOption operation);
257
258 //
259 // item sorting
260 //
261 OSStatus GetSortOrder (DataBrowserSortOrder* order) const;
262 OSStatus GetSortProperty(DataBrowserPropertyID* propertyID) const;
263
264 OSStatus Resort(DataBrowserItemID container=kDataBrowserNoItem, Boolean sortChildren=true);
265
266 OSStatus SetSortOrder (DataBrowserSortOrder order);
267 OSStatus SetSortProperty(DataBrowserPropertyID propertyID);
268
269 //
270 // container handling
271 //
272 OSStatus CloseContainer(DataBrowserItemID containerID);
273
274 OSStatus OpenContainer(DataBrowserItemID containerID);
275
276 protected :
277 //
278 // standard callback functions
279 //
280 static pascal Boolean DataBrowserCompareProc (ControlRef browser, DataBrowserItemID itemOneID, DataBrowserItemID itemTwoID, DataBrowserPropertyID sortProperty);
281 static pascal void DataBrowserGetContextualMenuProc(ControlRef browser, MenuRef* menu, UInt32* helpType, CFStringRef* helpItemString, AEDesc* selection);
282 static pascal OSStatus DataBrowserGetSetItemDataProc (ControlRef browser, DataBrowserItemID itemID, DataBrowserPropertyID property, DataBrowserItemDataRef itemData, Boolean getValue);
283 static pascal void DataBrowserItemNotificationProc (ControlRef browser, DataBrowserItemID itemID, DataBrowserItemNotification message, DataBrowserItemDataRef itemData);
284
285 virtual Boolean DataBrowserCompareProc (DataBrowserItemID itemOneID, DataBrowserItemID itemTwoID, DataBrowserPropertyID sortProperty) = 0;
286 virtual void DataBrowserGetContextualMenuProc(MenuRef* menu, UInt32* helpType, CFStringRef* helpItemString, AEDesc* selection) = 0;
287 virtual OSStatus DataBrowserGetSetItemDataProc (DataBrowserItemID itemID, DataBrowserPropertyID property, DataBrowserItemDataRef itemData, Boolean getValue) = 0;
288 virtual void DataBrowserItemNotificationProc (DataBrowserItemID itemID, DataBrowserItemNotification message, DataBrowserItemDataRef itemData) = 0;
289
290 //
291 // callback functions for customized types
292 //
293 static pascal void DataBrowserDrawItemProc(ControlRef browser, DataBrowserItemID itemID, DataBrowserPropertyID propertyID, DataBrowserItemState state, Rect const* rectangle, SInt16 bitDepth, Boolean colorDevice);
294 static pascal Boolean DataBrowserEditItemProc(ControlRef browser, DataBrowserItemID itemID, DataBrowserPropertyID propertyID, CFStringRef theString, Rect* maxEditTextRect, Boolean* shrinkToFit);
295 static pascal Boolean DataBrowserHitTestProc (ControlRef browser, DataBrowserItemID itemID, DataBrowserPropertyID propertyID, Rect const* theRect, Rect const* mouseRect);
296 static pascal DataBrowserTrackingResult DataBrowserTrackingProc(ControlRef browser, DataBrowserItemID itemID, DataBrowserPropertyID propertyID, Rect const* theRect, Point startPt, EventModifiers modifiers);
297
298 virtual void DataBrowserDrawItemProc(DataBrowserItemID itemID, DataBrowserPropertyID propertyID, DataBrowserItemState state, Rect const* rectangle, SInt16 bitDepth, Boolean colorDevice) = 0;
299 virtual Boolean DataBrowserEditItemProc(DataBrowserItemID itemID, DataBrowserPropertyID propertyID, CFStringRef theString, Rect* maxEditTextRect, Boolean* shrinkToFit) = 0;
300 virtual Boolean DataBrowserHitTestProc (DataBrowserItemID itemID, DataBrowserPropertyID propertyID, Rect const* theRect, Rect const* mouseRect) = 0;
301 virtual DataBrowserTrackingResult DataBrowserTrackingProc(DataBrowserItemID itemID, DataBrowserPropertyID propertyID, Rect const* theRect, Point startPt, EventModifiers modifiers) = 0;
302
303 //
304 // callback functions for drag & drop
305 ///
306 static pascal Boolean DataBrowserAcceptDragProc (ControlRef browser, DragReference dragRef, DataBrowserItemID itemID);
307 static pascal Boolean DataBrowserAddDragItemProc(ControlRef browser, DragReference dragRef, DataBrowserItemID itemID, ItemReference* itemRef);
308 static pascal Boolean DataBrowserReceiveDragProc(ControlRef browser, DragReference dragRef, DataBrowserItemID itemID);
309
310 virtual Boolean DataBrowserAcceptDragProc (DragReference dragRef, DataBrowserItemID itemID) = 0;
311 virtual Boolean DataBrowserAddDragItemProc(DragReference dragRef, DataBrowserItemID itemID, ItemReference* itemRef) = 0;
312 virtual Boolean DataBrowserReceiveDragProc(DragReference dragRef, DataBrowserItemID itemID) = 0;
313
314 //
315 // event handler for hit testing
316 ///
317 void* m_macDataViewCtrlEventHandler;
318
319 private:
320 //
321 // wxWidget internal stuff
322 //
323 DECLARE_ABSTRACT_CLASS(wxMacDataBrowserTableViewControl)
324 };
325
326 // ============================================================================
327 // wxMacDataBrowserListViewControl
328 // ============================================================================
329 //
330 // This class is a wrapper for the native browser's list view style. It expands
331 // the inherited functionality of the table view control class.
332 // The term list view is in this case Mac OS X specific and is not related
333 // to any wxWidget naming conventions.
334 //
335 class wxMacDataBrowserListViewControl : public wxMacDataBrowserTableViewControl
336 {
337 public:
338 //
339 // constructors / destructor
340 //
341 wxMacDataBrowserListViewControl(wxWindow* peer, wxPoint const& pos, wxSize const& size, long style) : wxMacDataBrowserTableViewControl(peer,pos,size,style)
342 {
343 }
344
345 //
346 // column handling
347 //
348 OSStatus AddColumn(DataBrowserListViewColumnDesc *columnDesc, DataBrowserTableViewColumnIndex position);
349
350 protected:
351 private:
352 };
353
354
355 // ============================================================================
356 // wxMacDataViewDataBrowserListViewControl
357 // ============================================================================
358 //
359 // This is the internal interface class between wxDataViewCtrl (wxWidget) and
360 // the native data browser (Mac OS X carbon).
361 //
362 class wxMacDataViewDataBrowserListViewControl : public wxMacDataBrowserListViewControl, public wxDataViewWidgetImpl
363 {
364 public:
365 //
366 // constructors / destructor
367 //
368 wxMacDataViewDataBrowserListViewControl(wxWindow* peer, wxPoint const& pos, wxSize const& size, long style);
369
370 //
371 // column related methods (inherited from wxDataViewWidgetImpl)
372 //
373 virtual bool ClearColumns ();
374 virtual bool DeleteColumn (wxDataViewColumn* columnPtr);
375 virtual void DoSetExpanderColumn(wxDataViewColumn const* columnPtr);
376 virtual wxDataViewColumn* GetColumn (unsigned int pos) const;
377 virtual int GetColumnPosition (wxDataViewColumn const* columnPtr) const;
378 virtual bool InsertColumn (unsigned int pos, wxDataViewColumn* columnPtr);
379 virtual void FitColumnWidthToContent(unsigned int WXUNUSED(pos)) { /*not implemented*/ }
380
381 //
382 // item related methods (inherited from wxDataViewWidgetImpl)
383 //
384 virtual bool Add (wxDataViewItem const& parent, wxDataViewItem const& item);
385 virtual bool Add (wxDataViewItem const& parent, wxDataViewItemArray const& items);
386 virtual void Collapse (wxDataViewItem const& item);
387 virtual void EnsureVisible(wxDataViewItem const& item, wxDataViewColumn const* columnPtr);
388 virtual void Expand (wxDataViewItem const& item);
389 virtual unsigned int GetCount () const;
390 virtual wxRect GetRectangle (wxDataViewItem const& item, wxDataViewColumn const* columnPtr);
391 virtual bool IsExpanded (wxDataViewItem const& item) const;
392 virtual bool Reload ();
393 virtual bool Remove (wxDataViewItem const& parent, wxDataViewItem const& item);
394 virtual bool Remove (wxDataViewItem const& parent, wxDataViewItemArray const& item);
395 virtual bool Update (wxDataViewColumn const* columnPtr);
396 virtual bool Update (wxDataViewItem const& parent, wxDataViewItem const& item);
397 virtual bool Update (wxDataViewItem const& parent, wxDataViewItemArray const& items);
398
399 //
400 // model related methods
401 //
402 virtual bool AssociateModel(wxDataViewModel* model);
403
404 //
405 // selection related methods (inherited from wxDataViewWidgetImpl)
406 //
407 virtual wxDataViewItem GetCurrentItem() const;
408 virtual void SetCurrentItem(const wxDataViewItem& item);
409 virtual int GetSelections(wxDataViewItemArray& sel) const;
410 virtual bool IsSelected (wxDataViewItem const& item) const;
411 virtual void Select (wxDataViewItem const& item);
412 virtual void SelectAll ();
413 virtual void Unselect (wxDataViewItem const& item);
414 virtual void UnselectAll ();
415
416 //
417 // sorting related methods
418 //
419 virtual wxDataViewColumn* GetSortingColumn () const;
420 virtual void Resort ();
421
422 //
423 // other methods (inherited from wxDataViewWidgetImpl)
424 //
425 virtual void DoSetIndent (int indent);
426 virtual void HitTest (wxPoint const& point, wxDataViewItem& item, wxDataViewColumn*& columnPtr) const;
427 virtual void SetRowHeight(wxDataViewItem const& item, unsigned int height);
428 virtual void OnSize ();
429
430 //
431 // other methods
432 //
433 wxDataViewCtrl* GetDataViewCtrl() const
434 {
435 return dynamic_cast<wxDataViewCtrl*>(GetWXPeer());
436 }
437
438 protected:
439 //
440 // standard callback functions (inherited from wxMacDataBrowserTableViewControl)
441 //
442 virtual Boolean DataBrowserCompareProc (DataBrowserItemID itemOneID, DataBrowserItemID itemTwoID, DataBrowserPropertyID sortProperty);
443 virtual void DataBrowserItemNotificationProc (DataBrowserItemID itemID, DataBrowserItemNotification message, DataBrowserItemDataRef itemData);
444 virtual void DataBrowserGetContextualMenuProc(MenuRef* menu, UInt32* helpType, CFStringRef* helpItemString, AEDesc* selection);
445 virtual OSStatus DataBrowserGetSetItemDataProc (DataBrowserItemID itemID, DataBrowserPropertyID propertyID, DataBrowserItemDataRef itemData, Boolean getValue);
446
447 //
448 // callback functions for customized types (inherited from wxMacDataBrowserTableViewControl)
449 //
450 virtual void DataBrowserDrawItemProc(DataBrowserItemID itemID, DataBrowserPropertyID propertyID, DataBrowserItemState state, Rect const* rectangle, SInt16 bitDepth, Boolean colorDevice);
451 virtual Boolean DataBrowserEditItemProc(DataBrowserItemID itemID, DataBrowserPropertyID propertyID, CFStringRef theString, Rect* maxEditTextRect, Boolean* shrinkToFit);
452 virtual Boolean DataBrowserHitTestProc (DataBrowserItemID itemID, DataBrowserPropertyID propertyID, Rect const* theRect, Rect const* mouseRect);
453 virtual DataBrowserTrackingResult DataBrowserTrackingProc(DataBrowserItemID itemID, DataBrowserPropertyID propertyID, Rect const* theRect, Point startPt, EventModifiers modifiers);
454
455 //
456 // callback functions for drag & drop (inherited from wxMacDataBrowserTableViewControl)
457 //
458 virtual Boolean DataBrowserAcceptDragProc (DragReference dragRef, DataBrowserItemID itemID);
459 virtual Boolean DataBrowserAddDragItemProc(DragReference dragRef, DataBrowserItemID itemID, ItemReference* itemRef);
460 virtual Boolean DataBrowserReceiveDragProc(DragReference dragRef, DataBrowserItemID itemID);
461
462 //
463 // drag & drop helper methods
464 //
465 wxDataFormat GetDnDDataFormat(wxDataObjectComposite* dataObjects);
466 wxDataObjectComposite* GetDnDDataObjects(DragReference dragRef, ItemReference itemRef) const; // create the data objects from the native dragged object
467
468 //
469 // other methods
470 //
471 wxDataViewColumn* GetColumnPtr(DataBrowserPropertyID propertyID) const; // returns for the passed property the corresponding pointer to a column; NULL is returned if not found
472
473 private:
474 };
475
476 typedef wxMacDataViewDataBrowserListViewControl* wxMacDataViewDataBrowserListViewControlPointer;
477
478 #endif // WX_GUI
479 #endif // _WX_MACCARBONDATAVIEWCTRL_H_