HelpSource/Classes/Window.schelp

   1 CLASS:: Window
   2 redirect:: implClass
   3 summary:: Top-level container of views
   4 categories:: GUI>Views
   5
   6 DESCRIPTION::
   7
   8 The Window is the most fundamental element of the GUI. It occupies a rectangular space on the screen within which other GUI elements (Views) are displayed.
   9
  10 A child view is added into a window by passing the window to the view's constructor. See link::Classes/View#*new::.
  11
  12 note::
  13 In strong::Qt GUI:: there is no distinction between windows, views, and containers; a View can be displayed directly on screen, and can contain other views. Therefore, visual descriptions of Window and most of the methods that are specific to Window in other GUI kits, also apply to and make part of View in Qt, and are thus shared by all its subclasses.
  14
  15 The Window class is provided in Qt GUI for compatibility as well as convenience: e.g. unlike View, Window will be created by default in the center of the screen, and various aspects can be conveniently controlled using its constructor arguments.
  16 ::
  17
  18 The Window is usually drawn with a bar on its top edge that displays the window's title which you can set in the link::#*new#constructor::, or using link::#-name::.
  19
  20
  21
  22 CLASSMETHODS::
  23
  24 PRIVATE:: key
  25
  26 METHOD:: new
  27
  28         Creates a new Window instance. You will need to call link::#-front:: on it to become visible.
  29
  30         argument:: name
  31                 A String for the text that will be displayed in the title bar. The default is 'panel'.
  32         argument:: bounds
  33                 A Rect specifying position and size of the window. The size does not include the border and title bar. Position is measured from the bottom-left corner of the screen (this is different than link::Classes/View#-bounds::). The default is size 400x400 at position 128x64, but in Qt the window is centered on the screen by default.
  34         argument:: resizable
  35                 A Boolean indicating whether this window is resizable by the user. The default is code::true::.
  36         argument:: border
  37                 A Boolean indicating whether this window has a border. Borderless windows have no title bar and thus can only be closed in code. The default is code::true::.
  38         argument:: server
  39                 This is a dummy argument which is here to provide compatibility with SwingOSC and has no effect.
  40         argument:: scroll
  41                 A Boolean indicating whether this window will add scrollbars if its contents exceed its bounds. If this is set to code::true::, then link::Classes/View#-resize:: settings will be ignored for contained views. The default is false.
  42
  43 METHOD:: allWindows
  44
  45         An array of all existing Window instances.
  46
  47 METHOD:: closeAll
  48
  49         Calls link::#-close:: an all existing Window instances.
  50
  51 METHOD:: initAction
  52
  53         The default action object to be evaluated whenever a new Window is instantiated.
  54
  55 METHOD:: screenBounds
  56
  57         Returns a Rect with the size of the screen in pixels
  58
  59 METHOD:: availableBounds
  60
  61         Returns a Rect describing the area of the screen that windows can actually occupy (i.e. excluding the Mac dock, the task bar, or similar).
  62
  63
  64
  65
  66 INSTANCEMETHODS::
  67
  68 SUBSECTION:: View hierarchy
  69
  70 METHOD:: view
  71         When a Window is created, it creates a container view, accessible using this method, that occupies the whole area of the window, and which will be used as the actual parent of the child widgets.
  72
  73         returns::
  74                 A View.
  75
  76 METHOD:: asView
  77         Equivalent to link::#-view::
  78
  79 METHOD:: currentSheet
  80         note:: Only in Cocoa GUI ::
  81         returns:
  82                 The current modal sheet attached to this window, if it exists. See link::Classes/SCModalSheet::.
  83
  84
  85
  86
  87 SUBSECTION:: Visibility
  88
  89 METHOD:: front
  90         Displays the window on the screen (In Qt GUI this has the same effect as setting link::#-visible:: to true).
  91
  92 METHOD:: minimize
  93         Hides the window, only keeping its representation in the dock, taskbar, etc..
  94
  95 METHOD:: unminimize
  96         Restores the window's previous state after being minimized.
  97
  98 METHOD:: fullScreen
  99         Displays the window full-screen.
 100
 101 METHOD:: endFullScreen
 102         Restores the window's previous state after being displayed full-screen.
 103
 104 METHOD:: alwaysOnTop
 105         Whether the window should always stay on top of other windows, even when it is not the active one.
 106
 107         argument::
 108                 A Boolean.
 109
 110 METHOD:: visible
 111         note:: only in Qt GUI ::
 112
 113         Whether the window is visible.
 114
 115         Setting this to code::true:: has the same effect as link::#-front::, and setting it to false closes the window without destroying it.
 116
 117         argument::
 118                 A Boolean.
 119
 120 METHOD:: close
 121
 122         Closes and destroys the window.
 123
 124 METHOD:: isClosed
 125         returns:: A Boolean stating whether the view has been closed.
 126
 127
 128
 129
 130 SUBSECTION:: Geometry
 131
 132 METHOD:: bounds
 133
 134         The position and size of the window. The position is relative to the bottom-left corner of the screen.
 135
 136         argument::
 137                 A Rect or a Point interpreted link::Classes/Point#-asRect#as Rect::.
 138         returns::
 139                 A Rect.
 140
 141 METHOD:: setTopLeftBounds
 142
 143         A convenience method that, unlike link::#-bounds::, sets the bounds by measuring position from the top-left corner of the screen, and vertically offset by code::menuSpacer::.
 144
 145         argument:: rect
 146                 A Rect.
 147         argument:: menuSpacer
 148                 An Integer amount of pixels.
 149
 150 METHOD:: setInnerExtent
 151
 152         Resizes the window, keeping its position intact.
 153
 154         In strong:: Qt GUI ::, this is equivalent to link::Classes/View#-resizeTo:: called on the link::#-view::.
 155
 156         argument:: w
 157                 An Integer width in pixels.
 158         argument:: h
 159                 An Integer height in pixels.
 160
 161 METHOD:: sizeHint
 162         note:: only in Qt GUI ::
 163         Redirects to link::Classes/View#-sizeHint:: of the link::#-view::.
 164
 165 METHOD:: minSizeHint
 166         note:: only in Qt GUI ::
 167         Redirects to link::Classes/View#-minSizeHint:: of the link::#-view::.
 168
 169 METHOD:: addFlowLayout
 170
 171         A convenience method which sets code::decorator:: of the link::#-view:: to a new instance of FlowLayout. See link::Classes/FlowLayout:: for examples.
 172
 173         argument:: margin
 174                 A Point describing the link::Classes/FlowLayout#-margin#margin:: of the FlowLayout.
 175
 176         argument:: gap
 177                 A Point describing the link::Classes/FlowLayout#-gap#gap:: of the FlowLayout.
 178
 179         returns:: The new FlowLayout instance.
 180
 181 METHOD:: layout
 182         note:: only in Qt GUI ::
 183         Redirects to link::Classes/View#-layout:: of the link::#-view::.
 184
 185
 186
 187 SUBSECTION:: Appearance
 188
 189 METHOD:: name
 190         The title of the window.
 191
 192         argument::
 193                 A String.
 194
 195 METHOD:: background
 196         The background color of the window.
 197
 198         argument::
 199                 A Color.
 200
 201 METHOD:: alpha
 202         The transparancy of the window.
 203
 204         argument::
 205                 A Float between 0.0 (invisible) and 1.0 (opaque).
 206
 207 METHOD:: refresh
 208         Redraws the window and all its children.
 209
 210
 211
 212 SUBSECTION:: Interaction
 213
 214 METHOD:: userCanClose
 215         Whether the user can close the window. The default is code::true::.
 216
 217         argument::
 218                 A Boolean.
 219
 220 METHOD:: acceptsClickThrough
 221         Whether the window receives clicks when it is not front-most. The default is code::true::.
 222
 223         argument::
 224                 A Boolean.
 225
 226 METHOD:: acceptsMouseOver
 227         Whether the window and all its children receive mouse-over events. The default is code::false::.
 228
 229         See also: link::Classes/View#-acceptsMouseOver:: and link::Classes/View#-mouseOverAction::.
 230
 231         argument::
 232                 A Boolean.
 233
 234
 235
 236 SUBSECTION:: Actions and hooks
 237
 238 METHOD:: drawFunc
 239         Just like the link::Classes/UserView::, the window can be given a Function to evalute whenever it is asked to redraw itself, so you can use the link::Classes/Pen:: class to draw on the window. See link::Classes/UserView#-drawFunc:: for explanation.
 240
 241         argument::
 242                 A Function.
 243
 244 METHOD:: toFrontAction
 245
 246         The action object to be evaluated whenever the window becomes the active one.
 247
 248 METHOD:: endFrontAction
 249
 250         The action object to be evaluated whenever the window ceases to be the active one.
 251
 252 METHOD:: onClose
 253
 254         The action object to be evaluated when the window is closed.
 255
 256 METHOD:: addToOnClose
 257
 258         Adds an object to link::#-onClose::, wrapping the current value into an Array, if it is not yet.
 259
 260 METHOD:: removeFromOnClose
 261
 262         Removes an object from link::#-onClose::, if the latter is an Array.
 263
 264
 265
 266 EXAMPLES::
 267
 268 subsection:: Adding Views
 269
 270 code::
 271 (
 272 var w;
 273 w = Window("my name is... panel", Rect(128, 64, 340, 360));
 274
 275 32.do({ arg i;
 276     b = Button(w, Rect(rrand(20,300),rrand(20,300), 75, 24));
 277     b.states = [["Start "++i, Color.black, Color.rand],
 278         ["Stop "++i, Color.white, Color.red]];
 279 });
 280 w.front;
 281 )
 282 ::
 283
 284
 285 subsection:: Using Decorator
 286
 287 code::
 288 (
 289 var w;
 290 w = Window("my name is... panel", Rect(128, 64, 340, 360));
 291
 292 w.view.decorator = FlowLayout(w.view.bounds);
 293 // w.addFlowLayout; // you can als write this instead of the line above
 294
 295 w.view.background = Color(0.6,0.8,0.8);
 296 32.do({ arg i;
 297     b = Button(w, Rect(rrand(20,300),rrand(20,300), 75, 24));
 298     b.states = [["Start "++i, Color.black, Color.rand],
 299         ["Stop "++i, Color.white, Color.red]];
 300 });
 301
 302 w.front;
 303 )
 304 ::
 305
 306
 307 subsection:: Setting Bounds
 308
 309 code::
 310 // use screenbounds for precise placement from the top
 311 (
 312 x = Window.new("test", Rect(100,Window.screenBounds.height-180,300,100));x.front;
 313 )
 314
 315 // bounds.top refers to the bottom edge of the window,
 316 // measured from the bottom of the screen. Different than in View.
 317 x.bounds_(Rect(100,400,300,300));
 318 ::
 319
 320
 321 subsection:: Borderless Window
 322
 323 code::
 324 w = Window.new(border:false).front; // can't be manually closed
 325 w.close; // so close it in code
 326 ::
 327
 328
 329 subsection:: Window with Scrollers
 330
 331 code::
 332 (
 333 w = Window(scroll: true); // you must set this when the window is created
 334 c = Slider2D(w, Rect(0, 0, 1500, 300));
 335 d = Slider(w, Rect(0, 310, 20, 300));
 336 c.background = Color.grey.alpha = 0.6;
 337 d.background = Color.grey.alpha = 0.6;
 338 w.front;
 339 )
 340 ::
 341
 342
 343 subsection::onClose
 344
 345 code::
 346 (
 347 x = Window.new.front;
 348 x.alpha = 0.8;
 349 x.onClose_({ y = Synth.new(\default) }); //close the window and the synth plays
 350 )
 351 x.close;
 352 y.free;
 353 ::
 354
 355
 356 subsection:: Drawing on Window with Pen
 357
 358 code::
 359 (
 360 var w, much = 0.02, string, synth;
 361
 362 w = Window.new("gui", Rect(100, 100, 300, 500)).front;
 363 w.view.background_(Color.new255(153, 255, 102).vary);
 364
 365 string = "gui ".dup(24).join;
 366
 367 w.drawFunc = Routine {
 368     var i = 0;
 369     var size = 40;
 370     var func = { |i, j| sin(i * 0.07 + (j * 0.0023) + 1.5pi) * much + 1 };
 371     var scale;
 372     var font = Font("Helvetica", 40).boldVariant;
 373     loop {
 374         i = i + 1;
 375         Pen.font = font;
 376         string.do { |char, j|
 377
 378             scale = func.value(i, j).dup(6);
 379
 380             Pen.fillColor = Color.new255(0, 120, 120).vary;
 381             Pen.matrix = scale * #[1, 0, 0, 1, 1, 0];
 382             Pen.stringAtPoint(char.asString,
 383                 ((size * (j % 9)) - 10) @ (size * (j div: 9))
 384             );
 385         };
 386         0.yield // stop here, return something unimportant
 387     }
 388 };
 389
 390 { while { w.isClosed.not } { w.refresh; 0.04.wait; } }.fork(AppClock);
 391
 392 w.front;
 393
 394 )
 395 ::