Table

TABLE_NOTES.md

@@ -0,0 +1,106 @@
+# Thoughts on table control support
+
+(BenC - 2017-09-25)
+
+## win32 comctl listview TODOs
+
+- maintain proper list of column parts, even if dummy.
+ (or cut down the public API to text columns only for now
+ until a better windows table control is available - see below
+ for more thoughts on this)
+- support editing of cells
+- expandable parts (allocate leftover space)
+- how to determine column width? random sample of data?
+
+
+## Is the parts system the right abstraction?
+
+Some toolkits support implementing cell views as custom
+widget layouts eg [item delgates in QML](http://doc.qt.io/qt-5/qml-qtquick-controls-tableview.html#itemDelegate-prop).
+So an item can be just about any widget layout you want.
+
+Is that kind of thing a future aspiration for libui?
+If so, I'd suggest cutting the parts API back to just
+uiTableAppendTextColumn() for now.
+
+The parts API gives _some_ of the flexiblity, but would likely
+get in the way if libui went the whole hog on custom item view
+layouts.
+
+
+## API change: support bulk invalidation of model
+
+Currently, the only way to notify the control that new data has
+been added is via the uiTableModelRow[Inserted|Changed|Deleted]
+functions. This inevitably causes redraws for each item, which
+can get _really_ slow for large numbers of items.
+
+The use cases are:
+ - adding large numbers of rows to existing models
+ - sorting (eg clicking on various column headings to change
+ the sort field and order.
+ The user-supplied model needs to handle the sorting, the
+ table control can't help.
+
+I think a single uiTableModelAllChanged() function would be
+enough. The underlying control needs to know that it should
+to redraw everything visible (and the number of items might
+have chnaged).
+
+
+## API change: support flags/styles
+
+- single or multiselect
+- hide column headers?
+- allow column reordering?
+- allow column resizing?
+- allow click on columns (+indicators for ascending/descending)?
+ (will require corresponding event handling/callbacks)
+
+I'd suggest implementing whichever of these flags are supported on
+all platforms.
+
+
+
+
+## API Change: Selection
+
+In general, most toolkits avoid exposing a flat array of
+selected items, presumably because the dataset could be
+very large. Usually there are methods to iterate over
+selection, often with simplified interface for
+single-selection-only tables.
+
+[GtkTreeView](https://developer.gnome.org/gtk3/stable/GtkTreeView.html)
+- has a selection object for getting/setting selection
+ - can fetch selection as a list, or via a foreach callback
+ - need to map GtkTreeview paths back to row indexes
+
+[QML TableView](http://doc.qt.io/qt-5/qml-qtquick-controls-tableview.html)
+- has a selection object for getting/setting selection
+- supports iteration of selected items
+
+[OSX NSTableView](https://developer.apple.com/documentation/appkit/nstableview)
+- has an IndexSet to hold selected items
+ - general purpose class? Lots of general set methods
+
+win32 commonctrl listview
+- items have LVIS_SELECTED flag
+- state changes notified via
+ [LVN_ODSTATECHANGED](https://msdn.microsoft.com/en-us/library/windows/desktop/bb774859(v=vs.85).aspx)
+ (indicates one or more contiguous items have changed state)
+- Use LVN_GETNEXTITEM to iterate through items with selected state
+
+[wxWidgets wxDataViewCtrl](http://docs.wxwidgets.org/3.0/classwx_data_view_ctrl.html)
+- provides `GetSelections( wxDataViewItemArray& sel)`, where `wxDataViewItemArray`
+ is presumably a growable array of some kind.
+
+
+aiming to support:
+
+- a "selection has changed" event
+ `uiTableOnSelectionChanged(uiTable* t, handlerfn fn, void* userdata)`?
+- functions to programatically select/unselect item(s)
+- access current selection (preferably by iteration rather than returning
+ possibly-huge arrays)
+

darwin/table.m

@@ -65,8 +65,60 @@ @interface tableView : NSTableView
  tableView *tv;
  struct scrollViewData *d;
  int backgroundColumn;
+ void (*onSelectionChanged)(uiTable *, void *);
+ void *onSelectionChangedData;
 };
 
+@interface tableDelegateClass : NSObject {
+ struct mapTable *tables;
+}
+- (void)tableViewSelectionDidChange:(NSNotification *)notification;
+- (void)registerTable:(uiTable *)t;
+- (void)unregisterTable:(uiTable *)t;
+@end
+
+@implementation tableDelegateClass
+
+- (id)init
+{
+ self = [super init];
+ if (self)
+ self->tables = newMap();
+ return self;
+}
+
+- (void)dealloc
+{
+ mapDestroy(self->tables);
+ [super dealloc];
+}
+
+- (void)tableViewSelectionDidChange:(NSNotification *)notification
+{
+ uiTable *t;
+
+ t = (uiTable *) mapGet(self->tables, notification);
+ (*(t->onSelectionChanged))(t, t->onSelectionChangedData);
+}
+
+- (void)registerTable:(uiTable *)t
+{
+ mapSet(self->tables, t->tv, t);
+ [t->tv setTarget:self];
+ [t->tv setAction:@selector(tableViewSelectionDidChange:)];
+}
+
+- (void)unregisterTable:(uiTable *)t
+{
+ [t->tv setTarget:nil];
+ mapDelete(self->tables, t->tv);
+}
+
+@end
+
+static tableDelegateClass *tableDelegate = nil;
+
+
 @implementation tableModel
 
 - (id)initWithModel:(uiTableModel *)m
@@ -510,6 +562,7 @@ static void uiTableDestroy(uiControl *c)
 {
  uiTable *t = uiTable(c);
 
+ [tableDelegate unregisterTable:t];
  // TODO
  [t->sv release];
  uiFreeControl(uiControl(t));
@@ -538,7 +591,49 @@ void uiTableSetRowBackgroundColorModelColumn(uiTable *t, int modelColumn)
  t->backgroundColumn = modelColumn;
 }
 
-uiTable *uiNewTable(uiTableModel *model)
+void uiTableOnSelectionChanged(uiTable *t, void (*f)(uiTable *, void *), void *data)
+{
+ t->onSelectionChanged = f;
+ t->onSelectionChangedData = data;
+}
+
+struct uiTableIter {
+ NSIndexSet *set;
+ int foo;
+ NSUInteger curr;
+};
+
+uiTableIter* uiTableGetSelection(uiTable *t)
+{
+ uiTableIter *it = uiprivAlloc(sizeof(uiTableIter), "uiTableIter");
+ it->set = [t->tv selectedRowIndexes];
+ it->foo = 0;
+
+ it->curr = [it->set firstIndex];
+ return it;
+}
+
+
+int uiTableIterAdvance(uiTableIter *it)
+{
+ if (it->foo>0) {
+ it->curr = [it->set indexGreaterThanIndex:it->curr];
+ }
+ it->foo++;
+ return (it->curr==NSNotFound) ? 0:1;
+}
+
+int uiTableIterCurrent(uiTableIter *it)
+{
+ return (int)it->curr;
+}
+
+void uiTableIterComplete(uiTableIter *it)
+{
+ uiprivFree(it);
+}
+
+uiTable *uiNewTable(uiTableModel *model, int styleFlags)
 {
  uiTable *t;
  struct scrollViewCreateParams p;
@@ -556,7 +651,11 @@ void uiTableSetRowBackgroundColorModelColumn(uiTable *t, int modelColumn)
  // TODO is this sufficient?
  [t->tv setAllowsColumnReordering:NO];
  [t->tv setAllowsColumnResizing:YES];
- [t->tv setAllowsMultipleSelection:NO];
+ if (styleFlags & uiTableStyleMultiSelect) {
+ [t->tv setAllowsMultipleSelection:YES];
+ } else {
+ [t->tv setAllowsMultipleSelection:NO];
+ }
  [t->tv setAllowsEmptySelection:YES];
  [t->tv setAllowsColumnSelection:NO];
  [t->tv setUsesAlternatingRowBackgroundColors:YES];
@@ -578,5 +677,10 @@ void uiTableSetRowBackgroundColorModelColumn(uiTable *t, int modelColumn)
 
  t->backgroundColumn = -1;
 
+ if (tableDelegate == nil) {
+ tableDelegate = [[tableDelegateClass new] autorelease];
+ [delegates addObject:tableDelegate];
+ }
+ [tableDelegate registerTable:t];
  return t;
 }

examples/CMakeLists.txt

@@ -23,6 +23,12 @@ _add_example(histogram
  ${_EXAMPLE_RESOURCES_RC}
 )
 
+_add_example(table
+ table/main.cpp
+ table/planet.cpp
+ ${_EXAMPLE_RESOURCES_RC}
+)
+
 _add_example(cpp-multithread
  cpp-multithread/main.cpp
  ${_EXAMPLE_RESOURCES_RC}
@@ -35,6 +41,8 @@ if(APPLE)
  # see issue #302 for more details
  target_compile_options(cpp-multithread PRIVATE --stdlib=libc++)
  target_link_libraries(cpp-multithread --stdlib=libc++)
+ target_compile_options(table PRIVATE --stdlib=libc++)
+ target_link_libraries(table --stdlib=libc++)
 endif()
 
 _add_example(drawtext
@@ -45,6 +53,7 @@ _add_example(drawtext
 add_custom_target(examples
  DEPENDS
  controlgallery
+ table
  histogram
  cpp-multithread
  drawtext)