HelpSource/Classes/EZListView.schelp

   1 class:: EZListView
   2 summary:: A wrapper class for a label plus a listView with per item actions
   3 categories:: GUI>EZ-GUI
   4 related:: Classes/ListView
   5
   6 description::
   7 EZListView is wrapper class which creates an (optional) label and a listView. It includes per item actions as well as a global action which are both evaluated upon selection of an item. Convenience methods for inserting and deleting list items are also included . If the parent is nil, then EZListView will create its own window. See link::Classes/EZGui:: and link::Classes/EZLists:: for all of the options.
   8
   9 subsection:: Some Important Issues Regarding EZListView
  10
  11 The convenience methods for EZListView require that the items array is an array of associations of labels and functions, not like in ListView, where items is simply an array of strings. If code::label:: is nil, then no staticText is created.
  12
  13 classmethods::
  14
  15 subsection:: Creation / Class Methods
  16
  17 method:: new
  18
  19 argument:: parent
  20 The parent view or window. If the parent is nil, then EZListView will create its own link::Classes/Window::, and place it conveniently on the screen if the bounds are a link::Classes/Point::. If the bounds are a link::Classes/Rect::, then the link::Classes/Rect:: determines the window bounds.
  21
  22 argument:: bounds
  23 An instance of link::Classes/Rect:: or link::Classes/Point::. Default value is code::160@200::.
  24
  25 argument:: label
  26 The label. Default value is code::nil::. If code::nil::, then no link::Classes/StaticText:: is created.
  27
  28 argument:: items
  29 Default value is code::nil::. An link::Classes/Array:: of link::Classes/Association::s code:: ['label' -> { arg listObj; value }, ] ::. Or and link::Classes/Array:: link::Classes/Symbol::s (if you are only using code::globalAction::).
  30
  31 argument:: globalAction
  32 A global function to be performed in addition to the item functions code:: { arg listObj; value } ::.
  33
  34 argument:: initVal
  35 Initial value of the List, i.e. the index selected. Default value is 0.
  36
  37 argument:: initAction
  38 An instance of link::Classes/Boolean::. Performs the action at code::initVal:: on creation of the list, plus the code::globalAction::. Default value is code::false::.
  39
  40 argument:: labelWidth
  41 Default value is 80. Not used if layout is code::\vert::.
  42
  43 argument:: labelHeight
  44 Default value is 20. Not used if layout is code::\horz::.
  45
  46 argument:: layout
  47 code::\vert:: or code::\horz::. default is code::\vert::.
  48
  49 argument:: gap
  50 A link::Classes/Point::. By default, the view tries to get its parent's gap, otherwise it defaults to code::2@2::. Setting it overrides these.
  51
  52 argument:: margin
  53 A link::Classes/Point::. This will inset the bounds occupied  by the subviews of view.
  54
  55 discussion::
  56 Example:
  57 code::
  58 (
  59 // default with vertical layout
  60 w = Window.new.front;
  61 w.view.decorator = FlowLayout(w.view.bounds);
  62 g = EZListView.new(w,
  63         230@230,
  64         "An ListView:",
  65         [
  66                 \item0 ->{ |a| ("this is item 0 of " ++ a).postln },
  67                 \item1 ->{ |a| ("this is item 1 of " ++ a).postln },
  68                 \item2 ->{ |a| ("this is item 2 of " ++ a).postln },
  69         ],
  70         globalAction: { |a| ("this is a global action of "++a.asString ).postln },
  71         initVal: 2,
  72         initAction: true,
  73         labelWidth: 120,
  74         labelHeight: 16,
  75         layout: \vert,
  76         gap: 2@2
  77         );
  78
  79 )
  80
  81 // or a more simple syntax (uses decorator gap settings):
  82 (
  83 w = Window.new.front;
  84 w.view.decorator = FlowLayout(w.view.bounds);
  85 g = EZListView.new(w,200@230, " List:");
  86 g.addItem(\item0, { |a| ("this is item 0 of " ++ a).postln });
  87 g.addItem(\item1, { |a| ("this is item 1 of " ++ a).postln });
  88 g.addItem(\item2, { |a| ("this is item 2 of " ++ a).postln });
  89 g.setColors(Color.grey, Color.white);
  90 )
  91 ::
  92
  93 instancemethods::
  94
  95 subsection:: Changing Appearance
  96
  97 method:: setColors
  98 argument:: stringBackground
  99 An instance of link::Classes/Color::. The code::background:: of the label and unit views.
 100 argument:: stringColor
 101 An instance of link::Classes/Color::. The code::stringColor:: of the label and unit views.
 102 argument:: listBackground
 103 An instance of link::Classes/Color::. The code::background:: of the list view.
 104 argument:: listStringColor
 105 An instance of link::Classes/Color::. The code::stringColor:: of the list view.
 106 argument:: selectedStringColor
 107 An instance of link::Classes/Color::. The code::selectedStringColor:: of the listView.
 108 argument:: hiliteColor
 109 An instance of link::Classes/Color::. The code::hiliteColor:: of the list view.
 110 argument:: background
 111 An instance of link::Classes/Color::. The code::background:: of the list view.
 112
 113 method:: font
 114 Set the link::Classes/Font:: used by all the views.
 115 argument:: font
 116 An instance of link::Classes/Font::.
 117
 118 examples::
 119 Creates its own window if parent is nil:
 120 code::
 121 (
 122 g = EZListView.new(label: " My PopUp List: ");
 123 g.addItem(\item0, {"this is item 0". postln});
 124 g.addItem(\item1, {"this is item 1". postln});
 125 g.addItem(\item2, {"this is item 2". postln});
 126 g.setColors(Color.grey,Color.white);
 127 )
 128 ::
 129 Layout horizontal:
 130 code::
 131 (
 132 g = EZListView.new(nil,205@180, "Choose One: ", layout:\horz);
 133 10.do{|i| g.addItem("item"++i.asString, {("this is item" ++i.asString). postln})};
 134 g.setColors(Color.grey,Color.white);
 135 )
 136 ::
 137 No labelView created, so set the window title:
 138 code::
 139 (
 140 g = EZListView.new(bounds:200@230); // no label
 141 12.do{|i| g.addItem("item"++i.asString, {("this is item" ++i.asString). postln})};
 142 g.view.parent.findWindow.name=" choose item";
 143 )
 144 ::
 145 insert item:
 146 code::
 147 (
 148 g = EZListView.new(nil,200@200, "List:");
 149 g.addItem(\item0, {"this is item 0". postln});
 150 g.addItem(\item1, {"this is item 1". postln});
 151 g.addItem(\item2, {"this is item 2". postln});
 152 g.addItem(\item4, {"this is item 4". postln});
 153 )
 154
 155 g.insertItem(3, \item3, {"this is item 3". postln});
 156 ::
 157 remove item:
 158 code::
 159 (
 160 g = EZListView.new(nil,200@200, "List:");
 161 g.addItem(\item0, {"this is item 0". postln});
 162 g.addItem(\item1, {"this is item 1". postln});
 163 g.addItem(\item2, {"this is item 2". postln});
 164 g.addItem(\item4, {"this is item 4". postln});
 165 g.insertItem(3, \item3, {"this is item 3". postln});
 166 )
 167
 168 g.removeItemAt(1);
 169 ::
 170 replace item:
 171 code::
 172 (
 173 g = EZListView.new(nil,200@200, "List:");
 174 g.addItem(\item0, {"this is item 0". postln});
 175 g.addItem(\item1, {"this is item 1". postln});
 176 g.addItem(\item2, {"this is item 2". postln});
 177 g.addItem(\item3, {"this is item 3". postln});
 178 )
 179
 180 g.replaceItemAt(2, \item2_replaced, {"this is item 2 replaced". postln});
 181 ::
 182