HelpSource/Classes/ScrollView.schelp

   1 class:: ScrollView
   2 redirect:: implClass
   3 summary:: A container view that can scroll its contents
   4 categories:: GUI>Views
   5 related:: Classes/CompositeView
   6
   7 DESCRIPTION::
   8
   9 A container view which allows the user to scroll across contents when they exceed the view's bounds.
  10
  11 subsection:: The canvas
  12
  13 The view places the children onto a emphasis::canvas::, which may then be scrolled. The child views' position is always relative to the canvas, and thus not affected by scrolling.
  14
  15 The size of the canvas is always equal to the collective bounds of the children, and automatically adjusts when they are added, moved, resized and removed. If you wish to set it to a particular size, you could do so by first placing e.g. a link::Classes/CompositeView:: (or another container) of desired size, and then placing all the other views into that container.
  16
  17 Exceptionally though, in strong::Qt GUI:: you can strong::replace the canvas:: with any other view (e.g. simply with link::Classes/View::), which allows you to install a link::Classes/QLayout##layout:: on it. In that case, the canvas will fill the whole visible area of the ScrollView, if the layout contents allow so, or a larger area, if the layout contents demand so. Effectively, the strong::contents will resize:: together with the ScrollView, unless their size constraints prevent that, and if link::#-autohidesScrollers:: is code::true::, a scrollbar will only be shown if the contents can not be resized small enough in the scrollbar's direction. See link::#-canvas:: for further explanation.
  18
  19 subsection:: Restrictions
  20
  21 note::
  22 list::
  23 ## The link::Classes/View#-resize:: mode of the children is ignored.
  24 ## One should not use a decorator such as FlowLayout directly on a ScrollView, only on a container view placed within it.
  25 ::
  26 ::
  27
  28
  29 CLASSMETHODS::
  30 PRIVATE::key
  31
  32
  33 INSTANCEMETHODS::
  34
  35
  36 SUBSECTION:: Geometry
  37
  38 METHOD:: canvas
  39     note:: Only in Qt GUI ::
  40
  41     Returns the current canvas that carries the child views, or replaces it with another.
  42
  43     By default, the canvas is a subclass of QObject, and hence does not allow the type of manipulations that views do. However, it can only be replaced with a subclass of QView, which greatly extends the possibilities, including the use of layouts on the canvas.
  44
  45     The new canvas will always resize with the ScrollView, as far its size constraints allow. A plain link::Classes/View:: which completely disregards its children will be freely resizable, and hence the scrolling will never be possible, since the scrollbars are activated according to the size of the canvas. To prevent this, you can either place explicit size constraints on it using link::Classes/View#-minSize:: and similar, or you can install a layout on it, which will forward to it the size constraints of the children.
  46
  47     See the link::#examples#example:: below.
  48
  49     Once the canvas is replaced, new views constructed with the ScrollView as the parent will end up as children of the canvas view, equivalent to constructing them with the canvas as the parent, or inserting them into the layout installed on the canvas.
  50
  51     warning:: Replacing the canvas will remove and destroy all the views placed on the previous one! ::
  52
  53 METHOD:: innerBounds
  54
  55     Returns either the rectangle corresponding to the size of the canvas, or the visible area of the ScrollView's background, whichever is larger. The position of the rectangle is always 0@0.
  56
  57     See the link::#description#discussion:: above regarding the size of the canvas.
  58
  59     Returns:: A Rect.
  60
  61 METHOD:: visibleOrigin
  62
  63     Gets the position on the canvas corresponding to its upper-left-most visible point, or moves the canvas so as to leave the given point on it at the top-left corner of the visible bounds, if possible.
  64
  65     Argument::
  66         A Point.
  67
  68
  69 SUBSECTION:: Behavior
  70
  71 METHOD:: autohidesScrollers
  72
  73     Sets or gets whether the view hides one or another scrollbar if the contents do not exceed the view's bounds in the scrollbar's direction.
  74
  75     If link::#-hasHorizontalScroller:: or link::#-hasVerticalScroller:: is set to code::false::, the respective scrollbar will always be hidden, regardless of this policy.
  76
  77     Defaults to strong::true::.
  78
  79 METHOD:: hasHorizontalScroller
  80
  81     Sets or gets whether the view has the horizontal scrollbar. If this is code::true::, the scrollbar may still be hidden if link::#-autohidesScrollers:: allows so; however, if this is code::false:: the scrollbar will never be shown.
  82
  83     Defaults to strong::true::.
  84
  85 METHOD:: hasVerticalScroller
  86
  87     Sets or gets whether the view has the vertical scrollbar. If this is code::true::, the scrollbar may still be hidden if link::#-autohidesScrollers:: allows so; however, if this it code::false:: the scrollbar will never be shown.
  88
  89     Defaults to strong::true::.
  90
  91 METHOD:: autoScrolls
  92
  93     note:: Not implemented yet in Qt GUI ::
  94
  95     Sets or gets whether the view scrolls automatically when you drag on a child view past the edge of visible bounds.
  96
  97     Defaults to strong::true::.
  98
  99
 100 SUBSECTION:: Appearance
 101
 102 METHOD:: hasBorder
 103
 104     Sets or gets whether the view draws its border.
 105
 106     Defaults to strong::true::.
 107
 108 SUBSECTION:: Actions
 109
 110 METHOD:: action
 111
 112     Sets or gets the object to be evaluated when the user moves the scrollbars, or when link::#-visibleOrigin:: is set.
 113
 114 EXAMPLES::
 115
 116 SUBSECTION:: Layout management on the canvas
 117
 118 note:: Only works with Qt GUI ::
 119
 120 By replacing the canvas of the ScrollView with a View, and installing a layout on it, the contents will expand to the edge of the ScrollView, and only exceed the edge if necessary.
 121
 122 code::
 123 (
 124 var scroll = ScrollView(bounds:Rect(0,0,300,300).center_(Window.availableBounds.center));
 125 var canvas = View();
 126 var layout;
 127 var i = 0;
 128
 129 var makeEntry = {
 130     var view = View().background_(Color.rand).layout_(
 131         HLayout(
 132             TextField().string_( ("This is entry number " + i.asString) ),
 133             Button().states_([["Delete"]]).action_({view.remove; i = i - 1;})
 134         )
 135     );
 136     i = i + 1;
 137     view;
 138 };
 139
 140 layout = VLayout();
 141 layout.add ( View().background_(Color.black).layout_(
 142     HLayout(
 143         Button().states_([["Add"]]).action_({ layout.insert(makeEntry.(), i) }),
 144         nil // stretch remaining empty space
 145     )
 146 ));
 147
 148 canvas.layout = layout;
 149 10.do { canvas.layout.add( makeEntry.() ) };
 150 canvas.layout.add(nil); // stretch remaining empty space
 151
 152 scroll.canvas = canvas;
 153 scroll.front;
 154 )
 155 ::
 156
 157 SUBSECTION:: Force a canvas size
 158
 159 code::
 160 (
 161 w = Window.new;
 162
 163 b = ScrollView(w, Rect(0, 0, 300, 300)).hasBorder_(true);
 164 c = CompositeView(b, Rect(0, 0, 500, 500)); // 'canvas' is this big
 165 c.decorator = FlowLayout(c.bounds); // now we can use a decorator
 166
 167 Slider2D(c, Rect(0, 0, 240, 240));
 168 Slider2D(c, Rect(0, 0, 240, 240));
 169 Slider2D(c, Rect(0, 0, 240, 240));
 170
 171 c.decorator.nextLine;
 172 w.front;
 173 )
 174 ::
 175
 176 SUBSECTION:: "Rulers", using an action function
 177
 178 code::
 179 (
 180 var drawFunc;
 181 w = Window.new;
 182
 183 a = ScrollView(w, Rect(40, 40, 300, 300));
 184 b = ScrollView(w, Rect(0, 40, 40, 300)).hasHorizontalScroller_(false).hasVerticalScroller_(false);
 185 c = ScrollView(w, Rect(40, 0, 300, 40)).hasHorizontalScroller_(false).hasVerticalScroller_(false);
 186 b.background = Color.grey;
 187 c.background = Color.grey;
 188
 189 d = UserView(a, Rect(0, 0, 620, 620));
 190 e = UserView(b, Rect(0, 0, 40, 630));
 191 f = UserView(c, Rect(0, 0, 630, 40));
 192
 193 a.action = { var origin;
 194     origin = a.visibleOrigin;
 195     b.visibleOrigin = 0@(origin.y);
 196     c.visibleOrigin = (origin.x)@0;
 197 };
 198
 199 drawFunc = {
 200     30.do({arg i;
 201         (i+1).asString.drawAtPoint((i+1 * 20)@0, Font("Courier", 9), Color.black);
 202     });
 203 };
 204
 205 d.drawFunc = {
 206     Pen.use({
 207         Pen.translate(0, 5);
 208         drawFunc.value;
 209     });
 210     Pen.translate(15, 0).rotate(0.5pi);
 211     drawFunc.value;
 212 };
 213
 214 e.drawFunc = {
 215     Pen.translate(40, 0).rotate(0.5pi);
 216     drawFunc.value;
 217 };
 218
 219 f.drawFunc = {
 220     Pen.translate(0, 25);
 221     drawFunc.value;
 222 };
 223
 224 w.front;
 225 )
 226 ::