HelpSource/Classes/EZPopUpMenu.schelp

   1 class:: EZPopUpMenu
   2 summary:: A wrapper class for a label plus a popUpMenu with per item actions
   3 categories:: GUI>EZ-GUI
   4 related:: Classes/PopUpMenu
   5
   6 description::
   7 EZPopUpMenu is wrapper class which creates an (optional) label and a popUpMenu. 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 menu items are also included . If the parent is nil, then EZPopUpMenu 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 EZPopUpMenu
  10 The convenience methods for EZPopUpMenu require that the items array is an array of associations of labels and functions, not like in link::Classes/PopUpMenu::, where items is simply an array of strings. If code::label:: is code::nil::, then no staticText is created.
  11
  12 classmethods::
  13 method:: new
  14
  15 argument:: parentView
  16 The parent view or window. If the parent is nil, then EZPopUpMenu 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.
  17
  18 argument:: bounds
  19 An instance of link::Classes/Rect:: or link::Classes/Point::. Default value is code::160@22::.
  20
  21 argument:: label
  22 The label. Default value is code::nil::. If code::nil::, then no link::Classes/StaticText:: is created.
  23
  24 argument:: items
  25 Default value is code::nil::. An link::Classes/Array:: of link::Classes/Association::s code:: ['label' -> { arg menuObj; value }, ] ::. Or and link::Classes/Array:: link::Classes/Symbol::s (if you are only using code::globalAction::).
  26
  27 argument:: globalAction
  28 A global function to be performed in addition to the item functions code:: { arg menuObj; value } ::.
  29
  30 argument:: initVal
  31 Initial value of the menu, i.e. the index selected. Default value is 0.
  32
  33 argument:: initAction
  34 An instance of link::Classes/Boolean::. Performs the action at code::initVal:: on creation of the menu, plus the code::globalAction::. Default value is code::false::.
  35
  36 argument:: labelWidth
  37 Default value is 80.
  38
  39 argument:: labelHeight
  40 Default value is 20. Not used if layout is code::\horz::.
  41
  42 argument:: layout
  43 code::\vert:: or code::\horz::. default is code::\horz::.
  44
  45 argument:: gap
  46 A link::Classes/Point::. By default, the view tries to get its parent's code::gap::, otherwise it defaults to code::2@2::. Setting it overrides these.
  47
  48 argument:: margin
  49 A link::Classes/Point::. This will inset the bounds occupied  by the subviews of view.
  50
  51 discussion::
  52 code::
  53 (
  54 w = Window.new.front;
  55 w.view.decorator = FlowLayout(w.view.bounds);
  56 g = EZPopUpMenu.new(
  57         w,
  58         230@22,
  59         "A PopUpMenu: ",
  60         [
  61                 \item0 ->{|a| ("this is item 0 of " ++ a).postln},
  62                 \item1 ->{|a| ("this is item 1 of " ++ a).postln},
  63                 \item2 ->{|a| ("this is item 2 of " ++ a).postln},
  64         ],
  65         globalAction: {|a| ("this is a global action of "++a.asString ).postln},
  66         initVal: 1,
  67         initAction: true,
  68         labelWidth: 120,
  69         labelHeight: 20,
  70         layout: \horz,
  71         gap: 2@2
  72 );
  73 )
  74
  75 // or a more simple syntax:
  76 (
  77 w = Window.new.front;
  78 w.view.decorator = FlowLayout(w.view.bounds);
  79 g = EZPopUpMenu.new(w, 200@22, "Menu: ");
  80 g.addItem(\item0, { |a| ("this is item 0 of " ++ a).postln });
  81 g.addItem(\item1, { |a| ("this is item 1 of " ++ a).postln });
  82 g.addItem(\item2, { |a| ("this is item 2 of " ++ a).postln });
  83 g.value = 0;
  84 )
  85 ::
  86
  87 instancemethods::
  88
  89 subsection:: Changing Appearance
  90
  91 method:: setColors
  92 argument:: stringBackground
  93 An instance of link::Classes/Color::. The code::background:: of the label and unit views.
  94 argument:: stringColor
  95 An instance of link::Classes/Color::. The code::stringColor:: of the label and unit views.
  96 argument:: menuBackground
  97 An instance of link::Classes/Color::. The code::background:: of the menu.
  98 argument:: menuStringColor
  99 An instance of link::Classes/Color::. The code::stringColor:: of the menu.
 100 argument:: background
 101 An instance of link::Classes/Color::. The code::background:: of the list view.
 102
 103 method:: font
 104 Set the link::Classes/Font:: used by all the views.
 105 argument:: font
 106 An instance of link::Classes/Font::.
 107
 108 examples::
 109 code::
 110 // try several examples together
 111 (
 112
 113 // many menus
 114 // inherits the parent's decorator gap
 115
 116 (
 117 w=Window.new("oscillators", Rect(200,500,200,160)).front;
 118 w.view.decorator = FlowLayout(w.view.bounds).gap_(2@2);
 119 5.do{|i|
 120         g = EZPopUpMenu.new(w,190@22, "Oscillator % : ".format(i+1));
 121         g.addItem(\off, {"off". postln});
 122         g.addItem(\sine, {"sine". postln});
 123         g.addItem(\saw, {"saw". postln});
 124         g.addItem(\pulse, {"pulse". postln});
 125         g.setColors(Color.grey,Color.white);
 126         g.value=0;
 127 };
 128 w.bounds=w.bounds.moveBy(300,60);
 129 );
 130
 131
 132 // Creates its own window if parentView is nil:
 133 (
 134 g = EZPopUpMenu.new(nil,250@22 ," Select : ");
 135 g.addItem(\item0, {"this is item 0". postln});
 136 g.addItem(\item1, {"this is item 1". postln});
 137 g.addItem(\item2, {"this is item 2". postln});
 138 g.setColors(Color.grey,Color.white);
 139 g.value=0;
 140
 141 );
 142
 143 // layout vertical:
 144 (
 145 g = EZPopUpMenu.new(nil,200@42, " Choose",layout:\vert);
 146 g.addItem(\item0, {"this is item 0". postln});
 147 g.addItem(\item1, {"this is item 1". postln});
 148 g.addItem(\item2, {"this is item 2". postln});
 149 g.setColors(Color.grey,Color.white);
 150 g.window.bounds=g.window.bounds.moveBy(300,-200);
 151 g.value=0;
 152 );
 153
 154 // No labelView created, so set the window title;
 155 (
 156 g = EZPopUpMenu.new(bounds:180@22); // no label
 157 g.addItem(\item0, {"this is item 0". postln});
 158 g.addItem(\item1, {"this is item 1". postln});
 159 g.addItem(\item2, {"this is item 2". postln});
 160 g.value=0;
 161 g.window.name=" choose item";
 162 g.window.bounds=g.window.bounds.moveBy(0,-200);
 163 );
 164 )
 165 // insertItem;
 166
 167 (
 168 g = EZPopUpMenu.new(nil,200@22, "Menu:");
 169 g.addItem(\item0, {"this is item 0". postln});
 170 g.addItem(\item1, {"this is item 1". postln});
 171 g.addItem(\item2, {"this is item 2". postln});
 172 g.addItem(\item4, {"this is item 4". postln});
 173 g.value=0;
 174 );
 175
 176 g.insertItem(3, \item3, {"this is item 3". postln});
 177
 178
 179 // remove Item ;
 180
 181 (
 182 w=Window.new.front;
 183 w.view.decorator = FlowLayout(w.view.bounds);
 184 g = EZPopUpMenu.new(w,200@22, "Menu:");
 185 g.addItem(\item0, {"this is item 0". postln});
 186 g.addItem(\item1, {"this is item 1". postln});
 187 g.addItem(\item2, {"this is item 2". postln});
 188 g.addItem(\item4, {"this is item 4". postln});
 189 g.insertItem(3, \item3, {"this is item 3". postln});
 190 g.value=0;
 191 )
 192
 193 g. removeItemAt(0);
 194
 195
 196
 197 // replace item;
 198 (
 199 g = EZPopUpMenu.new(nil,200@22, "List:");
 200 g.addItem(\item0, {"this is item 0". postln});
 201 g.addItem(\item1, {"this is item 1". postln});
 202 g.addItem(\item2, {"this is item 2". postln});
 203 g.addItem(\item3, {"this is item 3". postln});
 204 )
 205
 206 g.replaceItemAt(2, \item2_replaced, {"this is item 2 replaced". postln});
 207 ::