include/wx/osx/carbon/databrow.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        include/mac/carbon/databrow.h
   3 // Purpose:     Classes and functions for the Carbon data browser
   4 // Author:
   5 // Modified by:
   6 // Created:     2007-05-18
   7 // RCS-ID:      $Id$
   8 // Copyright:   (c)
   9 // Licence:     wxWindows licence
  10 /////////////////////////////////////////////////////////////////////////////
  11
  12 #ifndef _WX_DATABROW_H_
  13 #define _WX_DATABROW_H_
  14
  15 #include "wx/defs.h"
  16
  17 #if wxUSE_GUI
  18
  19 #include "wx/osx/private.h"
  20
  21 WX_DEFINE_ARRAY_SIZE_T(size_t,wxArrayDataBrowserItemID);
  22
  23 // ============================================================================
  24 // wxMacDataBrowserTableViewControl
  25 // ============================================================================
  26 //
  27 // this is a wrapper class for the Mac OS X data browser environment,
  28 // it covers all general data brower functionality,
  29 //
  30
  31 // data browser's property IDs have a reserved ID range from 0 - 1023
  32 // therefore, the first usable property ID is 'kMinPropertyID'
  33 DataBrowserPropertyID const kMinPropertyID = 1024;
  34
  35 class wxMacDataBrowserTableViewControl : public wxMacControl
  36 {
  37 public:
  38 //
  39 // constructors / destructor
  40 //
  41   wxMacDataBrowserTableViewControl(wxWindow* peer, const wxPoint& pos, const wxSize& size, long style);
  42   wxMacDataBrowserTableViewControl(void)
  43   {
  44   }
  45
  46 //
  47 // callback handling
  48 //
  49   OSStatus SetCallbacks      (DataBrowserCallbacks const*       callbacks);
  50   OSStatus SetCustomCallbacks(DataBrowserCustomCallbacks const* customCallbacks);
  51
  52 //
  53 // header handling
  54 //
  55   OSStatus GetHeaderDesc(DataBrowserPropertyID property, DataBrowserListViewHeaderDesc* desc) const;
  56
  57   OSStatus SetHeaderDesc(DataBrowserPropertyID property, DataBrowserListViewHeaderDesc* desc);
  58
  59 //
  60 // layout handling
  61 //
  62   OSStatus AutoSizeColumns();
  63
  64   OSStatus EnableCellSizeModification(bool enableHeight=true, bool enableWidth=true); // enables or disables the column width and row height modification (default: false)
  65
  66 #if MAC_OS_X_VERSION_MAX_ALLOWED >= MAC_OS_X_VERSION_10_4
  67   OSStatus GetAttributes        (OptionBits* attributes);
  68 #endif
  69   OSStatus GetColumnWidth       (DataBrowserPropertyID column, UInt16 *width ) const; // returns the column width in pixels
  70   OSStatus GetDefaultColumnWidth(UInt16 *width ) const; // returns the default column width in pixels
  71   OSStatus GetDefaultRowHeight  (UInt16 * height ) const;
  72   OSStatus GetHeaderButtonHeight(UInt16 *height );
  73   OSStatus GetPartBounds        (DataBrowserItemID item, DataBrowserPropertyID property, DataBrowserPropertyPart part, Rect* bounds);
  74   OSStatus GetRowHeight         (DataBrowserItemID item , UInt16 *height) const;
  75   OSStatus GetScrollPosition    (UInt32* top, UInt32 *left) const;
  76
  77 #if MAC_OS_X_VERSION_MAX_ALLOWED >= MAC_OS_X_VERSION_10_4
  78   OSStatus SetAttributes (OptionBits attributes);
  79 #endif
  80   OSStatus SetColumnWidth(DataBrowserPropertyID column, UInt16 width); // sets the column width in pixels
  81   OSStatus SetDefaultColumnWidth( UInt16 width );
  82   OSStatus SetDefaultRowHeight( UInt16 height );
  83   OSStatus SetHasScrollBars( bool horiz, bool vert );
  84   OSStatus SetHeaderButtonHeight( UInt16 height );
  85   OSStatus SetHiliteStyle( DataBrowserTableViewHiliteStyle hiliteStyle );
  86   OSStatus SetIndent(float Indent);
  87   OSStatus SetRowHeight( DataBrowserItemID item , UInt16 height);
  88   OSStatus SetScrollPosition( UInt32 top , UInt32 left );
  89
  90 //
  91 // column handling
  92 //
  93   OSStatus GetColumnCount   (UInt32* numColumns) const;
  94   OSStatus GetColumnIndex   (DataBrowserPropertyID propertyID, DataBrowserTableViewColumnIndex* index) const; // returns for the passed property the corresponding column index
  95   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
  96   OSStatus GetPropertyFlags (DataBrowserPropertyID propertyID, DataBrowserPropertyFlags *flags ) const;
  97   OSStatus GetPropertyID    (DataBrowserItemDataRef itemData, DataBrowserPropertyID* propertyID); // returns for the passed item data reference the corresponding property ID
  98   OSStatus GetPropertyID    (DataBrowserTableViewColumnIndex index, DataBrowserPropertyID* propertyID); // returns for the passed column index the corresponding property ID
  99
 100   OSStatus IsUsedPropertyID(DataBrowserPropertyID propertyID) const; // checks if passed property id is used by the control; no error is returned if the id exists
 101
 102   OSStatus RemoveColumnByProperty(DataBrowserTableViewColumnID propertyID);
 103   OSStatus RemoveColumnByIndex   (DataBrowserTableViewColumnIndex index);
 104
 105   OSStatus SetColumnIndex     (DataBrowserPropertyID propertyID, DataBrowserTableViewColumnIndex index);
 106   OSStatus SetDisclosureColumn(DataBrowserPropertyID propertyID, Boolean expandableRows=false);
 107   OSStatus SetPropertyFlags   (DataBrowserPropertyID propertyID, DataBrowserPropertyFlags flags);
 108
 109 //
 110 // item handling
 111 //
 112   OSStatus AddItem(DataBrowserItemID container, DataBrowserItemID const* itemID) // adds a single item
 113   {
 114     return this->AddItems(container,1,itemID,kDataBrowserItemNoProperty);
 115   }
 116   OSStatus AddItems(DataBrowserItemID container, UInt32 numItems, DataBrowserItemID const* items, DataBrowserPropertyID preSortProperty); // adds items to the data browser
 117
 118   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
 119   OSStatus GetItemCount (ItemCount* numItems) const
 120   {
 121     return this->GetItemCount(kDataBrowserNoItem,true,kDataBrowserItemAnyState,numItems);
 122   }
 123   OSStatus GetItemCount (DataBrowserItemID container, Boolean recurse, DataBrowserItemState state, ItemCount* numItems) const;
 124   OSStatus GetItemID    (DataBrowserTableViewRowIndex row, DataBrowserItemID* item) const;
 125   OSStatus GetItems     (DataBrowserItemID container, Boolean recurse, DataBrowserItemState state, Handle items) const;
 126   OSStatus GetItemRow   (DataBrowserItemID item, DataBrowserTableViewRowIndex* row) const;
 127
 128   OSStatus IsUsedItemID(DataBrowserItemID itemID) const; // checks if the passed id is in use
 129
 130   OSStatus RevealItem(DataBrowserItemID item, DataBrowserPropertyID propertyID, DataBrowserRevealOptions options) const;
 131
 132   OSStatus RemoveItem(DataBrowserItemID container, DataBrowserItemID const* itemID) // removes a single item
 133   {
 134     return this->RemoveItems(container,1,itemID,kDataBrowserItemNoProperty);
 135   }
 136   OSStatus RemoveItems(void) // removes all items
 137   {
 138     return this->RemoveItems(kDataBrowserNoItem,0,NULL,kDataBrowserItemNoProperty);
 139   }
 140   OSStatus RemoveItems(DataBrowserItemID container, UInt32 numItems, DataBrowserItemID const* items, DataBrowserPropertyID preSortProperty);
 141
 142   OSStatus UpdateItems(void) // updates all items
 143   {
 144     return this->UpdateItems(kDataBrowserNoItem,0,NULL,kDataBrowserItemNoProperty,kDataBrowserItemNoProperty);
 145   }
 146   OSStatus UpdateItems(DataBrowserItemID const* item) // updates all columns of item
 147   {
 148     return this->UpdateItems(kDataBrowserNoItem,1,item,kDataBrowserItemNoProperty,kDataBrowserItemNoProperty);
 149   }
 150   OSStatus UpdateItems(DataBrowserItemID container, UInt32 numItems, DataBrowserItemID const* items, DataBrowserPropertyID preSortProperty, DataBrowserPropertyID propertyID) const;
 151
 152 //
 153 // item selection
 154 //
 155   size_t   GetSelectedItemIDs(wxArrayDataBrowserItemID& itemIDs) const; // returns the number of selected item and the item IDs in the array
 156   OSStatus GetSelectionAnchor(DataBrowserItemID *first, DataBrowserItemID *last) const;
 157   OSStatus GetSelectionFlags (DataBrowserSelectionFlags* flags) const;
 158
 159   bool IsItemSelected(DataBrowserItemID item) const;
 160
 161   OSStatus SetSelectionFlags(DataBrowserSelectionFlags flags);
 162   OSStatus SetSelectedItems (UInt32 numItems, DataBrowserItemID const* itemIDs, DataBrowserSetOption operation);
 163
 164 //
 165 // item sorting
 166 //
 167   OSStatus GetSortOrder   (DataBrowserSortOrder* order) const;
 168   OSStatus GetSortProperty(DataBrowserPropertyID* propertyID) const;
 169
 170   OSStatus Resort(DataBrowserItemID container=kDataBrowserNoItem, Boolean sortChildren=true);
 171
 172   OSStatus SetSortOrder   (DataBrowserSortOrder  order);
 173   OSStatus SetSortProperty(DataBrowserPropertyID propertyID);
 174
 175 //
 176 // container handling
 177 //
 178   OSStatus CloseContainer(DataBrowserItemID containerID);
 179
 180   OSStatus OpenContainer(DataBrowserItemID containerID);
 181
 182 protected :
 183 //
 184 // standard callback functions
 185 //
 186   static pascal Boolean  DataBrowserCompareProc          (ControlRef browser, DataBrowserItemID itemOneID, DataBrowserItemID itemTwoID, DataBrowserPropertyID sortProperty);
 187   static pascal void     DataBrowserGetContextualMenuProc(ControlRef browser, MenuRef* menu, UInt32* helpType, CFStringRef* helpItemString, AEDesc* selection);
 188   static pascal OSStatus DataBrowserGetSetItemDataProc   (ControlRef browser, DataBrowserItemID itemID, DataBrowserPropertyID property, DataBrowserItemDataRef itemData, Boolean getValue);
 189   static pascal void     DataBrowserItemNotificationProc (ControlRef browser, DataBrowserItemID itemID, DataBrowserItemNotification message, DataBrowserItemDataRef itemData);
 190
 191   virtual Boolean  DataBrowserCompareProc          (DataBrowserItemID itemOneID, DataBrowserItemID itemTwoID, DataBrowserPropertyID sortProperty) = 0;
 192   virtual void     DataBrowserGetContextualMenuProc(MenuRef* menu, UInt32* helpType, CFStringRef* helpItemString, AEDesc* selection) = 0;
 193   virtual OSStatus DataBrowserGetSetItemDataProc   (DataBrowserItemID itemID, DataBrowserPropertyID property, DataBrowserItemDataRef itemData, Boolean getValue) = 0;
 194   virtual void     DataBrowserItemNotificationProc (DataBrowserItemID itemID, DataBrowserItemNotification message, DataBrowserItemDataRef itemData) = 0;
 195
 196 //
 197 // callback functions for customized types
 198 //
 199   static pascal void                      DataBrowserDrawItemProc(ControlRef browser, DataBrowserItemID itemID, DataBrowserPropertyID propertyID, DataBrowserItemState state, Rect const* rectangle, SInt16 bitDepth, Boolean colorDevice);
 200   static pascal Boolean                   DataBrowserEditItemProc(ControlRef browser, DataBrowserItemID itemID, DataBrowserPropertyID propertyID, CFStringRef theString, Rect* maxEditTextRect, Boolean* shrinkToFit);
 201   static pascal Boolean                   DataBrowserHitTestProc (ControlRef browser, DataBrowserItemID itemID, DataBrowserPropertyID propertyID, Rect const* theRect, Rect const* mouseRect);
 202   static pascal DataBrowserTrackingResult DataBrowserTrackingProc(ControlRef browser, DataBrowserItemID itemID, DataBrowserPropertyID propertyID, Rect const* theRect, Point startPt, EventModifiers modifiers);
 203
 204   virtual void                      DataBrowserDrawItemProc(DataBrowserItemID itemID, DataBrowserPropertyID propertyID, DataBrowserItemState state, Rect const* rectangle, SInt16 bitDepth, Boolean colorDevice) = 0;
 205   virtual Boolean                   DataBrowserEditItemProc(DataBrowserItemID itemID, DataBrowserPropertyID propertyID, CFStringRef theString, Rect* maxEditTextRect, Boolean* shrinkToFit) = 0;
 206   virtual Boolean                   DataBrowserHitTestProc (DataBrowserItemID itemID, DataBrowserPropertyID propertyID, Rect const* theRect, Rect const* mouseRect) = 0;
 207   virtual DataBrowserTrackingResult DataBrowserTrackingProc(DataBrowserItemID itemID, DataBrowserPropertyID propertyID, Rect const* theRect, Point startPt, EventModifiers modifiers) = 0;
 208
 209 //
 210 // callback functions for drag & drop
 211 ///
 212   static pascal Boolean DataBrowserAcceptDragProc (ControlRef browser, DragReference dragRef, DataBrowserItemID itemID);
 213   static pascal Boolean DataBrowserAddDragItemProc(ControlRef browser, DragReference dragRef, DataBrowserItemID itemID, ItemReference* itemRef);
 214   static pascal Boolean DataBrowserReceiveDragProc(ControlRef browser, DragReference dragRef, DataBrowserItemID itemID);
 215
 216   virtual Boolean DataBrowserAcceptDragProc (DragReference dragRef, DataBrowserItemID itemID)                         = 0;
 217   virtual Boolean DataBrowserAddDragItemProc(DragReference dragRef, DataBrowserItemID itemID, ItemReference* itemRef) = 0;
 218   virtual Boolean DataBrowserReceiveDragProc(DragReference dragRef, DataBrowserItemID itemID)                         = 0;
 219
 220 private:
 221 //
 222 // wxWidget internal stuff
 223 //
 224     DECLARE_ABSTRACT_CLASS(wxMacDataBrowserTableViewControl)
 225 };
 226
 227 // ============================================================================
 228 // wxMacDataBrowserListViewControl
 229 // ============================================================================
 230 //
 231 // this class is a wrapper for a list view which incorporates all general
 232 // data browser functionality of the inherited table view control class;
 233 // the term list view is in this case Mac OS X specific and is not related
 234 // to any wxWidget naming conventions
 235 //
 236 class wxMacDataBrowserListViewControl : public wxMacDataBrowserTableViewControl
 237 {
 238 public:
 239 //
 240 // constructors / destructor
 241 //
 242   wxMacDataBrowserListViewControl(wxWindow* peer, wxPoint const& pos, wxSize const& size, long style) : wxMacDataBrowserTableViewControl(peer,pos,size,style)
 243   {
 244   }
 245
 246 //
 247 // column handling
 248 //
 249   OSStatus AddColumn(DataBrowserListViewColumnDesc *columnDesc, DataBrowserTableViewColumnIndex position);
 250
 251 protected:
 252 private:
 253 };
 254
 255
 256 // ============================================================================
 257 // wxMacDataViewDataBrowserListViewControl
 258 // ============================================================================
 259 //
 260 // internal interface class between wxDataViewCtrl (wxWidget) and the data
 261 // browser (Mac OS X)
 262 //
 263 class wxMacDataViewDataBrowserListViewControl : public wxMacDataBrowserListViewControl
 264 {
 265 public:
 266 //
 267 // constructors / destructor
 268 //
 269   wxMacDataViewDataBrowserListViewControl(wxWindow* peer, wxPoint const& pos, wxSize const& size, long style);
 270
 271 protected:
 272 //
 273 // standard callback functions (inherited from wxMacDataBrowserTableViewControl)
 274 //
 275   virtual Boolean  DataBrowserCompareProc          (DataBrowserItemID itemOneID, DataBrowserItemID itemTwoID, DataBrowserPropertyID sortProperty);
 276   virtual void     DataBrowserItemNotificationProc (DataBrowserItemID itemID, DataBrowserItemNotification message, DataBrowserItemDataRef itemData);
 277   virtual void     DataBrowserGetContextualMenuProc(MenuRef* menu, UInt32* helpType, CFStringRef* helpItemString, AEDesc* selection);
 278   virtual OSStatus DataBrowserGetSetItemDataProc   (DataBrowserItemID itemID, DataBrowserPropertyID propertyID, DataBrowserItemDataRef itemData, Boolean getValue);
 279
 280 //
 281 // callback functions for customized types (inherited from wxMacDataBrowserTableViewControl)
 282 //
 283   virtual void                      DataBrowserDrawItemProc(DataBrowserItemID itemID, DataBrowserPropertyID propertyID, DataBrowserItemState state, Rect const* rectangle, SInt16 bitDepth, Boolean colorDevice);
 284   virtual Boolean                   DataBrowserEditItemProc(DataBrowserItemID itemID, DataBrowserPropertyID propertyID, CFStringRef theString, Rect* maxEditTextRect, Boolean* shrinkToFit);
 285   virtual Boolean                   DataBrowserHitTestProc (DataBrowserItemID itemID, DataBrowserPropertyID propertyID, Rect const* theRect, Rect const* mouseRect);
 286   virtual DataBrowserTrackingResult DataBrowserTrackingProc(DataBrowserItemID itemID, DataBrowserPropertyID propertyID, Rect const* theRect, Point startPt, EventModifiers modifiers);
 287
 288 //
 289 // callback functions for drag & drop (inherited from wxMacDataBrowserTableViewControl)
 290 //
 291   virtual Boolean DataBrowserAcceptDragProc (DragReference dragRef, DataBrowserItemID itemID);
 292   virtual Boolean DataBrowserAddDragItemProc(DragReference dragRef, DataBrowserItemID itemID, ItemReference* itemRef);
 293   virtual Boolean DataBrowserReceiveDragProc(DragReference dragRef, DataBrowserItemID itemID);
 294
 295 //
 296 // drag & drop helper methods
 297 //
 298   wxDataFormat           GetDnDDataFormat(wxDataObjectComposite* dataObjects);
 299   wxDataObjectComposite* GetDnDDataObjects(DragReference dragRef, ItemReference itemRef) const; // create the data objects from the native dragged object
 300
 301 private:
 302 };
 303
 304 typedef wxMacDataViewDataBrowserListViewControl* wxMacDataViewDataBrowserListViewControlPointer;
 305
 306
 307 #endif // WX_GUI
 308
 309 #endif // _WX_DATABROW_H_