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 SUBSECTION:: Actions in general
 467
 468 METHOD:: action
 469         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.).
 470
 471         argument:: func
 472                 Any object to set as default action, usually a Function or a FunctionList. When evaluated, it will be passed the view as an argument.
 473
 474
 475 METHOD:: doAction
 476         Evaluates the default link::#-action#action::.
 477
 478
 479 METHOD:: addAction
 480 METHOD:: removeAction
 481
 482         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'.
 483
 484         This is useful for adding functionality to existing frameworks that have action functions already.
 485
 486         argument:: func
 487                 Any object to add as an action, usually a Function.
 488
 489         argument:: selector
 490                 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.
 491
 492 SUBSECTION:: Key and mouse event propagation
 493
 494 In strong::Cocoa and SwingOSC:: GUI kits, a key event occurring on a view can propagate to the parent view, and trigger the parent's key action, if either the child's action returns code::nil::, or the child has no action assigned for that key event. This has also been referred to as "key event bubbling".
 495
 496 In strong::Qt:: GUI, however, both mouse and key events can propagate to the parent view. Event propagation works differently in Qt. By default, after a mouse or key action is evaluated, the control returns to the internals of the view implementation, and if no response to the particular mouse or key event is implemented there, it propagates to the parent.
 497
 498 If you wish to control whether the event will be propagated or not, return code::true:: or code::false:: from the action. True means you have responded to the event, and the propagation will be stopped; false means you are not interested in the event, and the event will propagate. However, this will completely bypass the view implementation, so it will not get a chance at responding to the event with its standard behavior. Use this feature with care.
 499
 500 SUBSECTION:: Mouse actions
 501
 502 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.
 503
 504 note::
 505 In Qt GUI, Mouse actions are subject to emphasis::event propagation::. See link::#key_and_mouse_event_propagation:: for details.
 506 ::
 507
 508 When the mouse action object is evaluated, it is passed one or more arguments from the following list (in that order):
 509
 510 list::
 511 ## strong::view:: - the view
 512 ## strong::x:: - the x coordinate
 513 ## strong::y:: - the y coordinate
 514 ## strong::modifiers:: - A bitwise or of integers indicating the modifier keys in effect. For a list of these, see link::Reference/Modifiers::.
 515 ## strong::buttonNumber:: - 0-left, 1-right, 2-middle, etc.
 516 ## strong::clickCount:: - the number of clicks within the system click time limit. At least 1.
 517 ::
 518
 519 METHOD:: mouseDownAction
 520         Sets or gets the object to be evaluated when a mouse button is pressed on the view.
 521
 522                 It is passed the following arguments: view, x, y, modifiers, buttonNumber, clickCount.
 523
 524 METHOD:: mouseUpAction
 525         Sets or gets the object to be evaluated when a mouse button is released after it was pressed on the view.
 526
 527                 It is passed the following arguments: view, x, y, modifiers.
 528
 529 METHOD:: mouseMoveAction
 530         Sets or gets the object to be evaluated whenever the mouse pointer moves after a mouse button was pressed on the view.
 531
 532                 It is passed the following arguments: view, x, y, modifiers.
 533
 534 METHOD:: mouseOverAction
 535         Sets or gets the object to be evaluated when the mouse pointer moves over the view with no mouse buttons pressed.
 536
 537         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::.
 538
 539                 It is passed the following arguments: view, x, y.
 540
 541 METHOD:: mouseWheelAction
 542     note:: strong:: Only in Qt GUI :: ::
 543
 544     The object to be evaluated when the mouse wheel is used while the mouse is pointing onto the view.
 545
 546     It is passed the following arguments: view, x, y, modifiers, xDelta, yDelta.
 547
 548     The xDelta and yDelta arguments express rotation in horizontal and vertical direction, respectively. The value is in degrees (typically, an event occurs every 15 degrees), and can be positive or negative, depending on the direction of rotation.
 549
 550 METHOD:: mouseEnterAction
 551         note:: strong:: Only in Qt GUI :: ::
 552
 553         Sets or gets the object to be evaluated when the mouse pointer enters the view.
 554
 555                 It is passed the following arguments: view, x, y.
 556
 557 METHOD:: mouseLeaveAction
 558         note:: strong:: Only in Qt GUI :: ::
 559
 560         Sets or gets the object to be evaluated when the mouse pointer leaves the view.
 561
 562                 It is passed the following arguments: view, x, y.
 563
 564
 565 SUBSECTION:: Key actions
 566
 567 Use the methods below to set or get the view's actions in response to keyboard interaction when the view has the keyboard focus.
 568
 569 note::
 570 Key actions are subject to emphasis::event propagation::. See link::#key_and_mouse_event_propagation:: for details.
 571 ::
 572
 573 When the key action object is evaluated, it is passed one or more arguments from the following list (in that order):
 574
 575 list::
 576 ## strong::view:: - The view.
 577
 578 ## 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.::
 579
 580 ## 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::.
 581
 582 ## strong::unicode:: - The Integer unicode number associated with the 'char' passed.
 583
 584 ## 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.::
 585 ::
 586
 587 note::
 588 In Cocoa GUI, for various reasons the following key events don't make it through to SuperCollider:
 589 list::
 590 ## most command modifiers
 591 ## ctl-tab
 592 ## ctl-escape
 593 ## tab and shift tab are currently trapped by SC itself for cycling the focus through the views.
 594 ::
 595 ::
 596
 597
 598 METHOD:: keyDownAction
 599         Sets or gets the object to be evaluated when a key is pressed.
 600
 601                 It is passed the following arguments: strong::view, char, modifiers, unicode, keycode::.
 602
 603 METHOD:: keyUpAction
 604         Sets or gets the object to be evaluated when a key is released.
 605
 606                 It is passed the following arguments: strong::view, char, modifiers, unicode, keycode::.
 607
 608 METHOD:: keyModifiersChangedAction
 609         Sets or gets the object to be evaluated when a modifier key is pressed or released.
 610
 611                 It is passed the following arguments: strong::view, modifiers::.
 612
 613
 614 SUBSECTION:: Drag and drop
 615
 616 Use the methods below to define or override how the view handles drag&drop operations.
 617
 618 METHOD:: beginDragAction
 619         Sets or gets the object evaluated when a drag&drop operation is initiated.
 620
 621         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.
 622
 623         If this variable is nil (the default) the view's link::#-defaultGetDrag:: method is called instead.
 624
 625 METHOD:: canReceiveDragHandler
 626         Sets or gets the object evaluated when the mouse pointer moves over the view while a drag&drop operation is taking place.
 627
 628         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.
 629
 630         If this variable is nil (the default) the view's link::#-defaultCanReceiveDrag:: method is called instead.
 631
 632 METHOD:: receiveDragHandler
 633         Sets or gets the object evaluated when a drag&drop operation finishes on this view.
 634
 635         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.
 636
 637         If this variable is nil (the default) the view's link::#-defaultReceiveDrag:: method is called instead.
 638
 639
 640 METHOD:: dragLabel
 641         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::.
 642
 643         argument::
 644                 A String containing the text to be displayed.
 645
 646
 647
 648
 649 SUBSECTION:: Other actions and hooks
 650
 651 METHOD:: focusGainedAction
 652         note:: only in Qt and SwingOSC GUI::
 653
 654         Sets or gets the object to be evaluated when the view gains the keyboard focus. It is passed the view as an argument.
 655
 656 METHOD:: focusLostAction
 657         note:: only in Qt and SwingOSC GUI::
 658
 659         Sets or gets the object to be evaluated when the view looses the keyboard focus. It is passed the view as an argument.
 660
 661 METHOD:: toFrontAction
 662         note:: only in Qt GUI ::
 663
 664         Sets or gets the object to be evaluated when the view becomes the active window. It is passed the view as an argument.
 665
 666 METHOD:: endFrontAction
 667         note:: only in Qt GUI ::
 668
 669         Sets or gets the object to be evaluated when the view becomes the active window. It is passed the view as an argument.
 670
 671 METHOD:: onResize
 672         note:: only in Qt GUI ::
 673
 674         Sets or gets the object to be evaluated when the view changes its size. It is passed the view as an argument.
 675
 676 METHOD:: onMove
 677         note:: only in Qt GUI ::
 678
 679         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.
 680
 681 METHOD:: onClose
 682
 683         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.
 684
 685
 686
 687
 688 SUBSECTION:: Subclassing
 689
 690 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.
 691
 692 METHOD:: defaultKeyDownAction
 693
 694         The method called when a key is pressed and link::#-keyDownAction:: is nil. Subclass it to define your own functionality on key-press.
 695
 696         See link::#key_actions#Key actions :: for explanation of arguments.
 697
 698         returns:: nil, if the key event is not handled by the view, which will propagated it to the parent.
 699
 700 METHOD:: defaultKeyUpAction
 701
 702         The method called when a key is released and link::#-keyUpAction:: is nil.  Subclass it to define your own functionality on key-release.
 703
 704         See link::#key_actions#Key actions :: for explanation of arguments.
 705
 706         returns:: nil, if the key event is not handled by the view, which will propagated it to the parent.
 707
 708
 709 METHOD:: keyDown
 710         Handles response to a key press event. First evaluates link::#*globalKeyDownAction::, then calls link::#-handleKeyDownBubbling::.
 711
 712         note::
 713         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.
 714         ::
 715
 716         See link::#key_actions#Key actions :: for explanation of arguments.
 717
 718         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.
 719
 720 METHOD:: keyUp
 721
 722         Handles response to a key release event. Sets link::#-keyTyped:: to 'char', evaluates link::#*globalKeyUpAction::, and then calls link::#-handleKeyUpBubbling::.
 723
 724         note::
 725         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.
 726         ::
 727
 728         See link::#key_actions#Key actions :: for explanation of arguments.
 729
 730         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.
 731
 732 METHOD:: keyModifiersChanged
 733         Handles response to a modifier key press or release event. Calls link::#-handleKeyModifiersChangedBubbling::.
 734
 735         note::
 736         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.
 737         ::
 738
 739         See link::#key_actions#Key actions :: for explanation of arguments.
 740
 741 METHOD:: handleKeyDownBubbling
 742         note:: Only in Cocoa and SwingOSC GUI ::
 743         Triggers key-down action and propagates the key event to the parent view, if the action returns nil.
 744
 745 METHOD:: handleKeyUpBubbling
 746         note:: Only in Cocoa and SwingOSC GUI ::
 747         Triggers key-up action and propagates the key event to the parent view, if the action returns nil.
 748
 749 METHOD:: handleKeyModifiersChangedBubbling
 750         note:: Only in Cocoa and SwingOSC GUI ::
 751         Triggers key-modifiers-changed action and propagates the key event to the parent view, if the action returns nil.
 752
 753 METHOD:: keyTyped
 754
 755         An instance variable containing the key just typed (after it is released).
 756
 757
 758
 759 METHOD:: mouseDown
 760         Handles response to a mouse button press event. Evaluates link::#-mouseDownAction::.
 761
 762         See link::#mouse_actions#Mouse actions :: for explanation of arguments.
 763
 764 METHOD:: mouseUp
 765         Handles response to a mouse button release event. Evaluates link::#-mouseDownAction::.
 766
 767         See link::#mouse_actions#Mouse actions :: for explanation of arguments.
 768
 769 METHOD:: mouseMove
 770         Handles response to mouse pointer moving after a mouse button has been pressed on the view. Evaluates link::#-mouseMoveAction::.
 771
 772         See link::#mouse_actions#Mouse actions :: for explanation of arguments.
 773
 774 METHOD:: mouseOver
 775         Handles response to mouse pointer moving over the view with no mouse buttons pressed. Evaluates link::#-mouseOverAction::.
 776
 777         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::.
 778
 779         See link::#mouse_actions#Mouse actions :: for explanation of arguments.
 780
 781 METHOD:: mouseEnter
 782         note:: strong:: Only in Qt GUI :: ::
 783
 784         Handles response to mouse pointer entering the view. Evaluates link::#-mouseEnterAction::.
 785
 786 METHOD:: mouseLeave
 787         note:: strong:: Only in Qt GUI :: ::
 788
 789         Handles response to mouse pointer leaving the view. Evaluates link::#-mouseLeaveAction::.
 790
 791
 792
 793 METHOD:: defaultGetDrag
 794
 795         The view's default method to determine the content of the drag&drop operation just initiated.
 796
 797         returns:: The object to be set as link::#*currentDrag::. If nil is returned, the drag&drop operation will not begin.
 798
 799 METHOD:: defaultCanReceiveDrag
 800
 801         The view's default evaluation whether the content of the ongoing drag&drop operation can be accepted.
 802
 803         returns:: A Boolean stating whether link::#*currentDrag:: is useful. If false is returned, the drop will not be handled by this view.
 804
 805 METHOD:: defaultReceiveDrag
 806
 807         The view's default handling of the data dropped on it (stored in link::#*currentDrag::).
 808
 809 METHOD:: beginDrag
 810         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.
 811
 812         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. ::
 813
 814         argument:: x
 815                 Current horizontal position of the mouse pointer.
 816
 817         argument:: y
 818                 Current vertical position of the mouse pointer.
 819
 820         returns:: A Boolean stating whether the drag&drop operation shall begin.
 821
 822 METHOD:: canReceiveDrag
 823         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.
 824
 825         note:: The description of arguments is valid strong:: only for Qt GUI: ::. In other GUI kits this method has no arguments. ::
 826
 827         argument:: x
 828                 Current horizontal position of the mouse pointer.
 829
 830         argument:: y
 831                 Current vertical position of the mouse pointer.
 832
 833         returns:: A Boolean stating whether the current drag&drop content can be dropped on the view.
 834
 835 METHOD:: receiveDrag
 836         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.
 837
 838         argument:: x
 839                 Current horizontal position of the mouse pointer.
 840
 841         argument:: y
 842                 Current vertical position of the mouse pointer.