HelpSource/Classes/View.schelp

   1 CLASS:: View
   2 redirect:: implClass
   3 summary:: The basic visible element of GUI
   4 categories:: GUI>Views
   5
   6 DESCRIPTION::
   7 The View class is the superclass of all view classes.
   8
   9 The view is the basic visible element of which the graphical user interface is composed. It occupies a rectangular space on screen within which it draws itself to display some data or to indicate a mode of interaction between the user and the program. Views receive keyboard and mouse events generated by the user and respond to them by controlling the behavior of the program. They also display information about the state of the program and the data on which it operates.
  10
  11
  12
  13 CLASSMETHODS::
  14
  15 PRIVATE:: key
  16
  17 METHOD:: new
  18
  19 Creates a new instance of View and makes it a child of another View or Window, effectively placing it within the parent's visual space. If there is a link::#-decorator#decorator:: installed on the parent, it will manage the position of the new View.
  20
  21 note::
  22
  23 strong::Qt GUI: ::
  24
  25 The 'parent' argument may be omitted, in which case the view will be displayed as a window on its own, when link::Classes/QView#-front#shown::.
  26
  27 The 'bounds' argument may be omitted, in which case the view will be created with its preferred size at position (0,0).
  28
  29 If a parent is given and there is a layout installed on it, the layout will manage the position and size of this view and the 'bounds' argument will have no effect.
  30 ::
  31
  32 argument:: parent
  33 The instance of View or Window that the new View will become a child of.
  34
  35 argument:: bounds
  36 A Rect or a Point describing size and position of the new View. If a Point is given, its coordinates will denote the view's size, while the view's position will be (0,0). Position is measured relative to the parent's top-left corner.
  37
  38 returns::
  39 note::
  40 SuperCollider has different GUI kits implementing the same functionality on different platforms. The View's constructor will return an instance of the equivalent class of the currently active GUI kit. See link::Guides/GUI-Introduction:: for detailed explanation.
  41 ::
  42
  43
  44 METHOD:: globalKeyDownAction
  45
  46         A settable class variable containing an object (e.g. an instance of Function or FunctionList) which is evaluated (i.e. link::Classes/Object#-value#value:: method is called on it) whenever a key is pressed, independently of keyboard focus. See also link::#-addAction::.
  47
  48         When the action object is evaluated, it is passed the following arguments: view, char, modifiers, unicode, keycode.
  49
  50
  51 METHOD:: globalKeyUpAction
  52
  53         A settable class variable containing an object (e.g. an instance of Function or FunctionList) which is evaluated (i.e. link::Classes/Object#-value#value:: method is called on it) whenever a key is released, independently of keyboard focus. See also link::#-addAction::.
  54
  55         When the action object is evaluated, it is passed the following arguments: view, char, modifiers, unicode, keycode.
  56
  57
  58 METHOD:: currentDrag
  59
  60         A class variable holding the content of the current drag. It is set by beginDrag.
  61
  62
  63 METHOD:: currentDragString
  64
  65         A class variable holding the content of the current drag as link::Classes/Object#-asCompileString#"compile string"::. It is set by beginDrag.
  66
  67
  68
  69
  70 INSTANCEMETHODS::
  71
  72 SUBSECTION:: Hierarchy and existence
  73
  74 METHOD:: parent
  75         returns:: The view's parent view, or nil if the view is a top view.
  76
  77 METHOD:: parents
  78         returns:: An array of all the parents, grandparents, etc., of the view.
  79
  80 METHOD:: getParents
  81         returns:: Same as link::-parents::.
  82
  83 METHOD:: children
  84         returns:: An array of all immediate children of the view.
  85
  86 METHOD:: remove
  87         Removes the view from its parent view (if any) and destroys the view. After this method is called, the view is not usable anymore.
  88
  89 METHOD:: removeAll
  90         Removes all the children of the view and destroys them. After this method is called, the former child views are not usable anymore.
  91
  92 METHOD:: close
  93         note:: only in Qt GUI ::
  94
  95         If link::#-deleteOnClose:: is true, this method has the same effect as link::#-remove::, otherwise makes the view invisible.
  96
  97 METHOD:: isClosed
  98         returns:: A Boolean stating whether the view has been destroyed.
  99
 100 METHOD:: notClosed
 101         returns:: A Boolean, the opposite of 'isClosed'.
 102
 103 METHOD:: asView
 104         Method that allows compatibility with Window and other classes that are not real subclasses of View, but implement a part of its interface.
 105
 106         returns:: This view.
 107
 108 SUBSECTION:: Visibility
 109
 110 METHOD:: visible
 111         Gets or sets wether the view is visible.
 112
 113         In Qt:
 114
 115         Making a child view invisible means it does not occupy any space from the standpoint of the layout that contains it, so the layout will distribute the space the view occupied when visible among other views. When the view becomes visible again it is given back the same space.
 116
 117         If the view has no parent, setting this to true has the same effect as link::#-front::, and setting it to false closes the window without destroying it.
 118
 119         argument::
 120                 A Boolean stating the visibility of the view.
 121
 122 METHOD:: front
 123         note:: only in Qt GUI ::
 124         If the view does not have a parent, displays it on the screen as a window (it has the same effect as setting link::#-visible:: to true), otherwise it has no effect.
 125
 126 METHOD:: minimize
 127         note:: only in Qt GUI ::
 128         If the view is a window, hides it (only keep it present in the dock/taskbar/etc.).
 129
 130 METHOD:: unminimize
 131         note:: only in Qt GUI ::
 132         If the view is a window, restores the its previous state after being minimized.
 133
 134 METHOD:: fullScreen
 135         note:: only in Qt GUI ::
 136         If the view is a window, displays it full-screen.
 137
 138 METHOD:: endFullScreen
 139         note:: only in Qt GUI ::
 140         If the view is a window, restores its previous state after being displayed full-screen.
 141
 142 METHOD:: alwaysOnTop
 143         note:: only in Qt GUI ::
 144
 145         If the view is a window, gets or sets whether it should always stay on top of other windows.
 146
 147         argument:: boolean
 148                 A Boolean stating whether the view should always stay on top.
 149
 150
 151
 152
 153 SUBSECTION:: Size and position
 154
 155 METHOD:: bounds
 156
 157         Gets or sets both the position and the size of the view. The position is relative to the parent view's top-left corner. Some containers, such as HLayoutView and VLayoutView, will use only the width and height of a child view's bounds.
 158
 159         The setter takes a Rect or a Point interpreted link::Classes/Point#-asRect#as Rect::. The getter always returns a Rect.
 160
 161 METHOD:: absoluteBounds
 162
 163         returns:: A Rect describing the absolute position and the size of the view on the screen.
 164
 165 METHOD:: sizeHint
 166         note:: only in Qt GUI ::
 167         returns:: A Size describing the preferred size of the view to comfortably display its contents and allow useful interaction.
 168
 169 METHOD:: minSizeHint
 170         note:: only in Qt GUI ::
 171
 172         returns:: A Size describing the minimum size of the view to be able to display its contents and allow any interaction.
 173
 174 METHOD:: maxSize
 175         note:: only in Qt GUI ::
 176         Set maximum allowed size of the view. The view will not be able to grow larger than this size, neither by user interaction nor programmatically.
 177
 178         argument:: size
 179                 A Size.
 180
 181 METHOD:: minSize
 182         note:: only in Qt GUI ::
 183         Set minimum allowed size of the view. The view will not be able to shrink smaller than this size, neither by user interaction nor programmatically.
 184
 185         argument:: size
 186                 A Size.
 187
 188
 189 METHOD:: fixedSize
 190         note:: only in Qt GUI ::
 191         Set both minimum and maximum allowed size of the view, thus making it non-resizable.
 192
 193         argument:: size
 194                 A Size.
 195
 196 METHOD:: fixedWidth
 197         note:: only in Qt GUI ::
 198         Set both minimum and maximum allowed width of the view, thus making it non-resizable.
 199
 200         argument:: width
 201                 An Int.
 202
 203 METHOD:: fixedHeight
 204         note:: only in Qt GUI ::
 205         Set both minimum and maximum allowed height of the view, thus making it non-resizable.
 206
 207         argument:: height
 208                 An Int.
 209
 210 METHOD:: maxWidth
 211         note:: only in Qt GUI ::
 212         Set maximum allowed width of the view, the view will not be able to grow larger in width, neither by user interaction nor programmatically.
 213
 214         argument:: width
 215                 An Int.
 216
 217
 218 METHOD:: minWidth
 219         note:: only in Qt GUI ::
 220         Set minimum allowed width of the view, the view will not be able to shrink smaller in width, neither by user interaction nor programmatically.
 221
 222         argument:: width
 223                 An Int.
 224
 225
 226 METHOD:: maxHeight
 227         note:: only in Qt GUI ::
 228         Set maximum allowed height of the view, the view will not be able to grow larger in height, neither by user interaction nor programmatically.
 229
 230         argument:: height
 231                 An Int.
 232
 233
 234
 235 METHOD:: minHeight
 236         note:: only in Qt GUI ::
 237         Set minimum allowed height of the view, the view will not be able to shrink smaller in height, neither by user interaction nor programmatically.
 238
 239         argument:: height
 240                 An Int.
 241
 242 METHOD:: moveTo
 243         note:: only in Qt GUI ::
 244         Move the view to new position, preserving its size.
 245
 246         argument:: x
 247                 An Int: the horizontal position of the new position.
 248
 249         argument:: y
 250                         An Int: the vertical position of the new position.
 251
 252 METHOD:: resizeTo
 253         note:: only in Qt GUI ::
 254         Resize the view, preserving its position.
 255
 256         argument:: width
 257                 An Int: the new horizontal size of the view.
 258
 259         argument:: height
 260                 An Int: the new vertical size of the view.
 261
 262 METHOD:: resize
 263         Determines what happens with the view's position and size when its parent is resized. See link::Guides/GUI-Introduction#view:: for further explanation.
 264
 265         argument::
 266                 An Int (1 to 9) defining the auto-resize behavior. See link::Reference/Resize:: for a list of valid resize modes.
 267
 268 METHOD:: decorator
 269         note:: only in Qt GUI ::
 270
 271         Get or set the decorator object, that automatically manages the positioning of new children of the view when they are created. See link::Guides/GUI-Introduction#decorators:: for further explanation.
 272
 273         argument::
 274                 An instance of a decorator class (e.g. FlowLayout).
 275
 276 METHOD:: addFlowLayout
 277         note:: only in Qt GUI ::
 278
 279         A convenience method which sets decorator to a new instance of FlowLayout. See link::Classes/FlowLayout:: for examples.
 280
 281         argument:: margin
 282                 A Point describing the link::Classes/FlowLayout#-margin#margin:: of the FlowLayout.
 283
 284         argument:: gap
 285                 A Point describing the link::Classes/FlowLayout#-gap#gap:: of the FlowLayout.
 286
 287         returns:: The new FlowLayout instance.
 288
 289 METHOD:: flow
 290         note:: only in Qt GUI ::
 291
 292         Creates a FlowView as a child of the view, and then evalutes the object given in the 'func' argument. It is most common to pass a Function for 'func' in which the FlowView is filled with other child views.
 293
 294         argument:: func
 295                 The object that will be evaluated after the creation of the FlowView, passing the new FlowView instance as an argument.
 296
 297         argument:: bounds
 298                 A Rect to set as the bounds of the FlowView, or nil, implying the size of this view and position (0,0).
 299
 300                 After 'func' is evaluated, the FlowView will be resized to fit its contents and cast away any extra space it occupies.
 301
 302         returns:: The new FlowView instance.
 303
 304 METHOD:: layout
 305         note:: only in Qt GUI ::
 306
 307         Get or set the layout object, that automatically manages the position and the size of the children of the view dynamically, in relation to the view's size. See link::Guides/GUI-Introduction#layouts:: for further explanation.
 308
 309         argument::
 310                 An instance of a subclass of QLayout.
 311
 312
 313
 314
 315 METHOD:: mapToGlobal
 316         note:: only in Qt GUI ::
 317
 318         Map a point relative to this view's top-left to absolute position on screen.
 319
 320         argument::
 321                 A Point describing a position relative to the view.
 322
 323         returns::
 324                 A Point describing the same position, but relative to the screen.
 325
 326
 327 SUBSECTION:: Appearance
 328
 329 METHOD:: name
 330         note:: only in Qt GUI ::
 331
 332         If the view is a window, sets its title
 333
 334         argument::
 335                 A String containing text for the window title.
 336
 337
 338 METHOD:: alpha
 339         note:: only in Qt GUI ::
 340
 341         If the view is a window, this controls its transparency.
 342
 343         argument:: aFloat
 344                 A Float between 0.0 (invisible) and 1.0 (opaque).
 345
 346 METHOD:: font
 347         note:: Only in Qt every view has this method. In other GUI kits, only some views have it. ::
 348         The font used by the view to display text (if any).
 349
 350         argument::
 351                 A Font.
 352
 353
 354 METHOD:: background
 355         Get or set the color of whatever is considered the background of the view.
 356
 357         argument::
 358                 A Color.
 359
 360
 361 METHOD:: focusColor
 362         Get or set the color used to display keyboard focus on the view.
 363
 364         argument::
 365                 A Color.
 366
 367 METHOD:: palette
 368         note:: Only available in Qt GUI ::
 369
 370         Get or set the palette to be used by the view.
 371
 372         When setting a palette, only those colors that have been set on the palette will take effect, other colors will be inherited from the parent view's palette, or QtGUI. See also link::Classes/QPalette#-hasColor::.
 373
 374         When getting a palette, it will return everytime a new copy of the view's palette. Therefore, if you wish to change the view's palette, you have to set the changed palette back on the view:
 375
 376 code::
 377         w = Window().front.layout_( HLayout( a = Slider() ) );
 378         a.action = { |a|
 379                 a.palette = a.palette.buttonText_( if(a.value > 0.5){Color.red}{Color.green} );
 380         };
 381         a.valueAction = 0.0;
 382 ::
 383
 384         To dynamically modify the view's palette, it is thus more efficient, if possible, to keep a palette instance to operate on. Note that this is also more efficient than using methods like link::Classes/Slider#-knobColor::, since internally they use the above approach:
 385
 386 code::
 387         w = Window().front.layout_( HLayout( a = Slider() ) );
 388         p = QPalette();
 389         a.action = { |a|
 390                 a.palette = p.buttonText_( if(a.value > 0.5){Color.red}{Color.green} );
 391         };
 392         a.valueAction = 0.0;
 393 ::
 394
 395         See link::Classes/QPalette:: for detailed explanation of how palettes work.
 396
 397         argument::
 398                 A QPalette.
 399
 400 METHOD:: refresh
 401         Redraws the view and all its children.
 402
 403
 404 SUBSECTION:: Common behavior
 405
 406
 407 METHOD:: userCanClose
 408         note:: only in Qt GUI ::
 409
 410         If the view is a window, sets or gets whether the user can close it via mouse or key actions.
 411
 412         argument::
 413                 A Boolean.
 414
 415
 416 METHOD:: deleteOnClose
 417         note:: only in Qt GUI ::
 418
 419         Sets or gets whether the view should be destroyed when closed.
 420
 421         argument::
 422                 A Boolean.
 423
 424 METHOD:: enabled
 425         Sets or gets whether the view allows the user to interact with it. Usually, when a view is disabled it will be displayed differently (typically it will be greyed out).
 426
 427         argument::
 428                 A Boolean.
 429
 430
 431 METHOD:: canFocus
 432         Sets or gets whether the view can receive keyboard focus.
 433
 434         argument::
 435                 A Boolean.
 436
 437 METHOD:: focus
 438         If 'flag' is true, gives keyboard focus to the view (if possible), otherwise removes the keayboard focus from it.
 439
 440         argument:: flag
 441                 A Boolean.
 442
 443 METHOD:: hasFocus
 444
 445         returns:: A Boolean, stating whether the view currently has the keyboard focus.
 446
 447 METHOD:: acceptsMouse
 448     note:: Only in Qt GUI ::
 449
 450     Sets or gets whether the view responds to mouse interaction. If code::false::, the view will be completely transparent for mouse and interaction will be possible with any view under.
 451
 452     Defaults to code::true::.
 453
 454     argument::
 455         A Boolean.
 456
 457 METHOD:: acceptsMouseOver
 458         If this is a top view, this variable defines whether the view and all its children receive mouse-over events. The default is code::false::.
 459
 460         See also: link::#-mouseOverAction::.
 461
 462         argument::
 463                 A Boolean.
 464
 465
 466
 467 SUBSECTION:: Actions in general
 468
 469 METHOD:: action
 470         Gets or sets the default action of the view, i.e. the object to be evaluated when the user interacts with the view in an essential way (e.g. a Button is clicked, a ListView item is selected, etc.).
 471
 472         argument:: func
 473                 Any object to set as default action, usually a Function or a FunctionList. When evaluated, it will be passed the view as an argument.
 474
 475
 476 METHOD:: doAction
 477         Evaluates the default link::#-action#action::.
 478
 479
 480 METHOD:: addAction
 481 METHOD:: removeAction
 482
 483         Adds/removes 'func' to or from the list of objects in the variable determined by 'selector'. If 'selector' is not an Array or a List, it will become one, containing the previous object plus 'func'.
 484
 485         This is useful for adding functionality to existing frameworks that have action functions already.
 486
 487         argument:: func
 488                 Any object to add as an action, usually a Function.
 489
 490         argument:: selector
 491                 A Symbol containing the name of the action variable to which 'func' will be added. In other words, 'add' method will be invoked on that variable; by default that is \action, but any other (sensible) instance or class variable of the view could work (e.g. \globalKeyDownAction or \mouseUpAction or \onClose, etc.). See the other action variables below.
 492
 493
 494
 495
 496 SUBSECTION:: Mouse actions
 497
 498 Use the methods below to set or get the view's actions in response to mouse interaction with the view. A view must be enabled for the mouse actions to work.
 499
 500 When the action object is evaluated, it is passed one or more arguments from the following list (in that order):
 501
 502 list::
 503 ## strong::view:: - the view
 504 ## strong::x:: - the x coordinate
 505 ## strong::y:: - the y coordinate
 506 ## strong::modifiers:: - A bitwise or of integers indicating the modifier keys in effect. For a list of these, see link::Reference/Modifiers::.
 507 ## strong::buttonNumber:: - 0-left, 1-right, 2-middle, etc.
 508 ## strong::clickCount:: - the number of clicks within the system click time limit. At least 1.
 509 ::
 510
 511 METHOD:: mouseDownAction
 512         Sets or gets the object to be evaluated when a mouse button is pressed on the view.
 513
 514                 It is passed the following arguments: view, x, y, modifiers, buttonNumber, clickCount.
 515
 516 METHOD:: mouseUpAction
 517         Sets or gets the object to be evaluated when a mouse button is released after it was pressed on the view.
 518
 519                 It is passed the following arguments: view, x, y, modifiers.
 520
 521 METHOD:: mouseMoveAction
 522         Sets or gets the object to be evaluated whenever the mouse pointer moves after a mouse button was pressed on the view.
 523
 524                 It is passed the following arguments: view, x, y, modifiers.
 525
 526 METHOD:: mouseOverAction
 527         Sets or gets the object to be evaluated when the mouse pointer moves over the view with no mouse buttons pressed.
 528
 529         The action is triggered only when link::Classes/Window#-acceptsMouseOver:: of the containing Window (or, in Qt, link::#-acceptsMouseOver:: of the top View) is code::true::.
 530
 531                 It is passed the following arguments: view, x, y.
 532
 533 METHOD:: mouseEnterAction
 534         note:: strong:: Only in Qt GUI :: ::
 535
 536         Sets or gets the object to be evaluated when the mouse pointer enters the view.
 537
 538                 It is passed the following arguments: view, x, y.
 539
 540 METHOD:: mouseLeaveAction
 541         note:: strong:: Only in Qt GUI :: ::
 542
 543         Sets or gets the object to be evaluated when the mouse pointer leaves the view.
 544
 545                 It is passed the following arguments: view, x, y.
 546
 547
 548 SUBSECTION:: Key actions
 549
 550 Use the methods below to set or get the view's actions in response to keyboard interaction when the view has the keyboard focus.
 551
 552 If evaluating the action object returns nil, or there is no action set, keyboard event will propagate up to the parent view which may then respond and trigger its actions. On the same condition, it will continue to propagate up unless some view responds or it hits the top of the view hierarchy. You may register an action on the Window's top view to respond to all unhandled keyboard events for the window.
 553
 554 note::
 555 In Qt GUI, event propagation works differently. After handling a key event within SuperCollider language, the event processing continues in the Qt implementation of the view, and if it is not handled there it propagates to the parent view. If you want to have control over key event propagation, you can return true or false from key actions (meaning that the event was handled and will not propagate, or converse), but note that this will also prevent the Qt view implementation to respond to the key event.
 556 ::
 557
 558 When the action object is evaluated, it is passed one or more arguments from the following list (in that order):
 559
 560 list::
 561 ## strong::view:: - The view.
 562
 563 ## strong::char:: - The character associated with the key, possibly unprintable. Character sequences (for example é) get passed as two characters, the first one blank ( ), the second one is the unmodified character (e). This will also vary depending on the nationality the keyboard is set to. note:: In Qt GUI only printable characters are passed. If a key is not associated with any printable character, nil will be passed instead.::
 564
 565 ## strong::modifiers:: - A bitwise or of integers indicating the modifier keys in effect. You can examine individual flag settings using the C bitwise AND operator. For a list of these, see link::Reference/Modifiers::.
 566
 567 ## strong::unicode:: - The Integer unicode number associated with the 'char' passed.
 568
 569 ## strong::keycode:: - The hardware dependent keycode indicating the physical key. This will vary from machine to machine, but is useful for building musical interfaces using the computer keyboard. warning::Function key modifier in combination with another key may change the latter's keycode.::
 570 ::
 571
 572 note::
 573 In Cocoa GUI, for various reasons the following key events don't make it through to SuperCollider:
 574 list::
 575 ## most command modifiers
 576 ## ctl-tab
 577 ## ctl-escape
 578 ## tab and shift tab are currently trapped by SC itself for cycling the focus through the views.
 579 ::
 580 ::
 581
 582
 583 METHOD:: keyDownAction
 584         Sets or gets the object to be evaluated when a key is pressed.
 585
 586                 It is passed the following arguments: strong::view, char, modifiers, unicode, keycode::.
 587
 588 METHOD:: keyUpAction
 589         Sets or gets the object to be evaluated when a key is released.
 590
 591                 It is passed the following arguments: strong::view, char, modifiers, unicode, keycode::.
 592
 593 METHOD:: keyModifiersChangedAction
 594         Sets or gets the object to be evaluated when a modifier key is pressed or released.
 595
 596                 It is passed the following arguments: strong::view, modifiers::.
 597
 598
 599 SUBSECTION:: Drag and drop
 600
 601 Use the methods below to define or override how the view handles drag&drop operations.
 602
 603 METHOD:: beginDragAction
 604         Sets or gets the object evaluated when a drag&drop operation is initiated.
 605
 606         At evaluation, the following arguments will be passed: strong:: view, x, y ::. The view expects an object to be returned which will become the data subject to the drag&drop operation. Returning nil will prevent the drag&drop operation to begin.
 607
 608         If this variable is nil (the default) the view's link::#-defaultGetDrag:: method is called instead.
 609
 610 METHOD:: canReceiveDragHandler
 611         Sets or gets the object evaluated when the mouse pointer moves over the view while a drag&drop operation is taking place.
 612
 613         At evaluation, the following arguments will be passed: strong:: view, x, y ::. The view expects the link::#*currentDrag#drag&drop data:: to be examined, and a Boolean returned stating whether the view can make use of that data. If true is returned, the data may be dropped on the view, otherwise the drop event will not be handled by this view.
 614
 615         If this variable is nil (the default) the view's link::#-defaultCanReceiveDrag:: method is called instead.
 616
 617 METHOD:: receiveDragHandler
 618         Sets or gets the object evaluated when a drag&drop operation finishes on this view.
 619
 620         At evaluation, the following arguments will be passed: strong:: view, x, y ::. The link::#*currentDrag#drag&drop data:: is expected to be applied to the view in some way.
 621
 622         If this variable is nil (the default) the view's link::#-defaultReceiveDrag:: method is called instead.
 623
 624
 625 METHOD:: dragLabel
 626         Sets or gets the text displayed by the mouse pointer during the drag&drop operation. It is expected to be set while handling the beginning of the operation, i.e. in link::#-beginDragAction:: or link::#-defaultGetDrag::.
 627
 628         argument::
 629                 A String containing the text to be displayed.
 630
 631
 632
 633
 634 SUBSECTION:: Other actions and hooks
 635
 636 METHOD:: focusGainedAction
 637         note:: only in Qt and SwingOSC GUI::
 638
 639         Sets or gets the object to be evaluated when the view gains the keyboard focus. It is passed the view as an argument.
 640
 641 METHOD:: focusLostAction
 642         note:: only in Qt and SwingOSC GUI::
 643
 644         Sets or gets the object to be evaluated when the view looses the keyboard focus. It is passed the view as an argument.
 645
 646 METHOD:: toFrontAction
 647         note:: only in Qt GUI ::
 648
 649         Sets or gets the object to be evaluated when the view becomes the active window. It is passed the view as an argument.
 650
 651 METHOD:: endFrontAction
 652         note:: only in Qt GUI ::
 653
 654         Sets or gets the object to be evaluated when the view becomes the active window. It is passed the view as an argument.
 655
 656 METHOD:: onResize
 657         note:: only in Qt GUI ::
 658
 659         Sets or gets the object to be evaluated when the view changes its size. It is passed the view as an argument.
 660
 661 METHOD:: onMove
 662         note:: only in Qt GUI ::
 663
 664         Sets or gets the object to be evaluated when the view changes position relatively to its parent. It is passed the view as an argument.
 665
 666 METHOD:: onClose
 667
 668         Sets or gets the object to be evaluated when the view is destroyed (i.e. link::#-close#closed:: or link::#-remove#removed::). It is passed the view as an argument.
 669
 670
 671
 672
 673 SUBSECTION:: Subclassing
 674
 675 The following methods are the default handlers of key press and release events. When subclassing, override them to implement custom functionality. Many view classes in the standard library do that.
 676
 677 METHOD:: defaultKeyDownAction
 678
 679         The method called when a key is pressed and link::#-keyDownAction:: is nil. Subclass it to define your own functionality on key-press.
 680
 681         See link::#key_actions#Key actions :: for explanation of arguments.
 682
 683         returns:: nil, if the key event is not handled by the view, which will propagated it to the parent.
 684
 685 METHOD:: defaultKeyUpAction
 686
 687         The method called when a key is released and link::#-keyUpAction:: is nil.  Subclass it to define your own functionality on key-release.
 688
 689         See link::#key_actions#Key actions :: for explanation of arguments.
 690
 691         returns:: nil, if the key event is not handled by the view, which will propagated it to the parent.
 692
 693
 694 METHOD:: keyDown
 695         Handles response to a key press event. First evaluates link::#*globalKeyDownAction::, then calls link::#-handleKeyDownBubbling::.
 696
 697         note::
 698         In Qt GUI, instead of calling link::#-handleKeyDownBubbling::, this method directly triggers the action and returns, forwarding the action's return value. See link::#key_actions#Key Actions :: for detailed explanation.
 699         ::
 700
 701         See link::#key_actions#Key actions :: for explanation of arguments.
 702
 703         returns:: strong:: Only in Qt GUI: :: A Boolean, stating whether the event was handled or not (and will not or will propagate to the parent view, respectively), or the view, in which case it lets the Qt view implementation handle the event.
 704
 705 METHOD:: keyUp
 706
 707         Handles response to a key release event. Sets link::#-keyTyped:: to 'char', evaluates link::#*globalKeyUpAction::, and then calls link::#-handleKeyUpBubbling::.
 708
 709         note::
 710         In Qt GUI, instead of calling link::#-handleKeyUpBubbling::, this method directly triggers the action and returns, forwarding the action's return value. See link::#key_actions#Key Actions :: for detailed explanation.
 711         ::
 712
 713         See link::#key_actions#Key actions :: for explanation of arguments.
 714
 715         returns:: strong:: Only in Qt GUI: :: A Boolean, stating whether the event was handled or not (and will not or will propagate to the parent view, respectively), or the view, in which case it lets the Qt view implementation handle the event.
 716
 717 METHOD:: keyModifiersChanged
 718         Handles response to a modifier key press or release event. Calls link::#-handleKeyModifiersChangedBubbling::.
 719
 720         note::
 721         In Qt GUI, instead of calling link::#-handleKeyModifiersChangedBubbling::, a modifier key press or release event also produces a normal key press or release event, and it is the handling of those events that will determine propagation to the parent.
 722         ::
 723
 724         See link::#key_actions#Key actions :: for explanation of arguments.
 725
 726 METHOD:: handleKeyDownBubbling
 727         note:: Only in Cocoa and SwingOSC GUI ::
 728         Triggers key-down action and propagates the key event to the parent view, if the action returns nil.
 729
 730 METHOD:: handleKeyUpBubbling
 731         note:: Only in Cocoa and SwingOSC GUI ::
 732         Triggers key-up action and propagates the key event to the parent view, if the action returns nil.
 733
 734 METHOD:: handleKeyModifiersChangedBubbling
 735         note:: Only in Cocoa and SwingOSC GUI ::
 736         Triggers key-modifiers-changed action and propagates the key event to the parent view, if the action returns nil.
 737
 738 METHOD:: keyTyped
 739
 740         An instance variable containing the key just typed (after it is released).
 741
 742
 743
 744 METHOD:: mouseDown
 745         Handles response to a mouse button press event. Evaluates link::#-mouseDownAction::.
 746
 747         See link::#mouse_actions#Mouse actions :: for explanation of arguments.
 748
 749 METHOD:: mouseUp
 750         Handles response to a mouse button release event. Evaluates link::#-mouseDownAction::.
 751
 752         See link::#mouse_actions#Mouse actions :: for explanation of arguments.
 753
 754 METHOD:: mouseMove
 755         Handles response to mouse pointer moving after a mouse button has been pressed on the view. Evaluates link::#-mouseMoveAction::.
 756
 757         See link::#mouse_actions#Mouse actions :: for explanation of arguments.
 758
 759 METHOD:: mouseOver
 760         Handles response to mouse pointer moving over the view with no mouse buttons pressed. Evaluates link::#-mouseOverAction::.
 761
 762         This method is called only if link::Classes/Window#-acceptsMouseOver:: of the containing Window (or, in Qt, link::#-acceptsMouseOver:: of the top View) is code::true::.
 763
 764         See link::#mouse_actions#Mouse actions :: for explanation of arguments.
 765
 766 METHOD:: mouseEnter
 767         note:: strong:: Only in Qt GUI :: ::
 768
 769         Handles response to mouse pointer entering the view. Evaluates link::#-mouseEnterAction::.
 770
 771 METHOD:: mouseLeave
 772         note:: strong:: Only in Qt GUI :: ::
 773
 774         Handles response to mouse pointer leaving the view. Evaluates link::#-mouseLeaveAction::.
 775
 776
 777
 778 METHOD:: defaultGetDrag
 779
 780         The view's default method to determine the content of the drag&drop operation just initiated.
 781
 782         returns:: The object to be set as link::#*currentDrag::. If nil is returned, the drag&drop operation will not begin.
 783
 784 METHOD:: defaultCanReceiveDrag
 785
 786         The view's default evaluation whether the content of the ongoing drag&drop operation can be accepted.
 787
 788         returns:: A Boolean stating whether link::#*currentDrag:: is useful. If false is returned, the drop will not be handled by this view.
 789
 790 METHOD:: defaultReceiveDrag
 791
 792         The view's default handling of the data dropped on it (stored in link::#*currentDrag::).
 793
 794 METHOD:: beginDrag
 795         Handles initiation of a drag&drop operation. Evaluates link::#-beginDragAction:: or calls link::#-defaultGetDrag:: if the former is nil, then stores the object returned into link::#*currentDrag::, and the object interpreted as link::Classes/Object#-asCompileString#"compile string":: into link::#*currentDragString::. Returns whether link::#*currentDrag:: is not nil.
 796
 797         note:: The description of arguments and return value is valid strong:: only for Qt GUI: ::. In other GUI kits this method has no arguments and its return value is insignificant. ::
 798
 799         argument:: x
 800                 Current horizontal position of the mouse pointer.
 801
 802         argument:: y
 803                 Current vertical position of the mouse pointer.
 804
 805         returns:: A Boolean stating whether the drag&drop operation shall begin.
 806
 807 METHOD:: canReceiveDrag
 808         Handles evaluation whether the view can accept the current drag&drop data. Evaluates link::#-canReceiveDragHandler:: or calls link::#-defaultCanReceiveDrag:: if the former is nil, then forwards the return value.
 809
 810         note:: The description of arguments is valid strong:: only for Qt GUI: ::. In other GUI kits this method has no arguments. ::
 811
 812         argument:: x
 813                 Current horizontal position of the mouse pointer.
 814
 815         argument:: y
 816                 Current vertical position of the mouse pointer.
 817
 818         returns:: A Boolean stating whether the current drag&drop content can be dropped on the view.
 819
 820 METHOD:: receiveDrag
 821         Handles the end of the drag&drop operation. Evaluates link::#-receiveDragHandler:: or calls link::#-defaultReceiveDrag:: if the former is nil, then sets link::#*currentDrag:: and link::#*currentDragString:: to nil.
 822
 823         argument:: x
 824                 Current horizontal position of the mouse pointer.
 825
 826         argument:: y
 827                 Current vertical position of the mouse pointer.