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#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: by default, after a mouse or key action is evaluated, the control returns to the C++ implementation of the view, 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, returning either code::true:: or code::false:: will completely bypass the view's C++ 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     The object to be evaluated when a mouse button is pressed on the view.
 521
 522     The following arguments are passed at evaluation: strong::view, x, y, modifiers, buttonNumber, clickCount::.
 523
 524     The return value of evaluation controls the event propagation to parent view. See link::#key_and_mouse_event_propagation#Key and mouse event propagation:: for details.
 525
 526 METHOD:: mouseUpAction
 527     The object to be evaluated when a mouse button is released after it was pressed on the view.
 528
 529     The following arguments are passed at evaluation: strong::view, x, y, modifiers::.
 530
 531     The return value of evaluation controls the event propagation to parent view. See link::#key_and_mouse_event_propagation#Key and mouse event propagation:: for details.
 532
 533 METHOD:: mouseMoveAction
 534     The object to be evaluated whenever the mouse pointer moves after a mouse button was pressed on the view.
 535
 536     The following arguments are passed at evaluation: strong::view, x, y, modifiers::.
 537
 538     The return value of evaluation controls the event propagation to parent view. See link::#key_and_mouse_event_propagation#Key and mouse event propagation:: for details.
 539
 540 METHOD:: mouseOverAction
 541     The object to be evaluated when the mouse pointer moves over the view with no mouse buttons pressed.
 542
 543     The following arguments are passed at evaluation: strong::view, x, y::.
 544
 545     The object is evaluated only when link::Classes/Window#-acceptsMouseOver:: of the containing Window (or, in Qt, link::#-acceptsMouseOver:: of the top View) is code::true::.
 546
 547     The return value of evaluation controls the event propagation to parent view. See link::#key_and_mouse_event_propagation#Key and mouse event propagation:: for details.
 548
 549 METHOD:: mouseWheelAction
 550     note:: strong:: Only in Qt GUI :: ::
 551
 552     The object to be evaluated when the mouse wheel is used while the mouse is pointing onto the view.
 553
 554     The following arguments are passed at evaluation: strong::view, x, y, modifiers, xDelta, yDelta::.
 555
 556     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.
 557
 558     The return value of evaluation controls the event propagation to parent view. See link::#key_and_mouse_event_propagation#Key and mouse event propagation:: for details.
 559
 560 METHOD:: mouseEnterAction
 561     note:: strong:: Only in Qt GUI :: ::
 562
 563     The object to be evaluated when the mouse pointer enters the view.
 564
 565     The following arguments are passed at evaluation: strong::view, x, y::.
 566
 567 METHOD:: mouseLeaveAction
 568     note:: strong:: Only in Qt GUI :: ::
 569
 570     The object to be evaluated when the mouse pointer leaves the view.
 571
 572     The following arguments are passed at evaluation: strong::view, x, y::.
 573
 574
 575 SUBSECTION:: Key actions
 576
 577 Use the methods below to set or get the view's actions in response to keyboard interaction when the view has the keyboard focus.
 578
 579 note::
 580 Key actions are subject to emphasis::event propagation::. See link::#key_and_mouse_event_propagation:: for details.
 581 ::
 582
 583 When the key action object is evaluated, it is passed one or more arguments from the following list (in that order):
 584
 585 list::
 586 ## strong::view:: - The view.
 587
 588 ## 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.::
 589
 590 ## 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::.
 591
 592 ## strong::unicode:: - The Integer unicode number associated with the 'char' passed.
 593
 594 ## 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.::
 595 ::
 596
 597 note::
 598 In Cocoa GUI, for various reasons the following key events don't make it through to SuperCollider:
 599 list::
 600 ## most command modifiers
 601 ## ctl-tab
 602 ## ctl-escape
 603 ## tab and shift tab are currently trapped by SC itself for cycling the focus through the views.
 604 ::
 605 ::
 606
 607
 608 METHOD:: keyDownAction
 609     The object to be evaluated when a key is pressed.
 610
 611     The following arguments are passed at evaluation: strong::view, char, modifiers, unicode, keycode::.
 612
 613     The return value of evaluation controls the event propagation to parent view. See link::#key_and_mouse_event_propagation#Key and mouse event propagation:: for details.
 614
 615     If no code::keyDownAction:: is set, link::#-defaultKeyDownAction:: is called instead, and its return value controls the event propagation.
 616
 617 METHOD:: keyUpAction
 618     The object to be evaluated when a key is released.
 619
 620     The following arguments are passed at evaluation: strong::view, char, modifiers, unicode, keycode::.
 621
 622     The return value of evaluation controls the event propagation to parent view. See link::#key_and_mouse_event_propagation#Key and mouse event propagation:: for details.
 623
 624     If no code::keyUpAction:: is set, link::#-defaultKeyUpAction:: is called instead, and its return value controls the event propagation.
 625
 626 METHOD:: keyModifiersChangedAction
 627     The object to be evaluated when a modifier key is pressed or released.
 628
 629     The following arguments are passed at evaluation: strong::view, modifiers::.
 630
 631
 632 SUBSECTION:: Drag and drop
 633
 634 Use the methods below to define or override how the view handles drag&drop operations.
 635
 636 METHOD:: beginDragAction
 637         Sets or gets the object evaluated when a drag&drop operation is initiated.
 638
 639         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.
 640
 641         If this variable is nil (the default) the view's link::#-defaultGetDrag:: method is called instead.
 642
 643 METHOD:: canReceiveDragHandler
 644         Sets or gets the object evaluated when the mouse pointer moves over the view while a drag&drop operation is taking place.
 645
 646         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.
 647
 648         If this variable is nil (the default) the view's link::#-defaultCanReceiveDrag:: method is called instead.
 649
 650 METHOD:: receiveDragHandler
 651         Sets or gets the object evaluated when a drag&drop operation finishes on this view.
 652
 653         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.
 654
 655         If this variable is nil (the default) the view's link::#-defaultReceiveDrag:: method is called instead.
 656
 657
 658 METHOD:: dragLabel
 659         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::.
 660
 661         argument::
 662                 A String containing the text to be displayed.
 663
 664
 665
 666
 667 SUBSECTION:: Other actions and hooks
 668
 669 METHOD:: focusGainedAction
 670         note:: only in Qt and SwingOSC GUI::
 671
 672         Sets or gets the object to be evaluated when the view gains the keyboard focus. It is passed the view as an argument.
 673
 674 METHOD:: focusLostAction
 675         note:: only in Qt and SwingOSC GUI::
 676
 677         Sets or gets the object to be evaluated when the view looses the keyboard focus. It is passed the view as an argument.
 678
 679 METHOD:: toFrontAction
 680         note:: only in Qt GUI ::
 681
 682         Sets or gets the object to be evaluated when the view becomes the active window. It is passed the view as an argument.
 683
 684 METHOD:: endFrontAction
 685         note:: only in Qt GUI ::
 686
 687         Sets or gets the object to be evaluated when the view becomes the active window. It is passed the view as an argument.
 688
 689 METHOD:: onResize
 690         note:: only in Qt GUI ::
 691
 692         Sets or gets the object to be evaluated when the view changes its size. It is passed the view as an argument.
 693
 694 METHOD:: onMove
 695         note:: only in Qt GUI ::
 696
 697         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.
 698
 699 METHOD:: onClose
 700
 701         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.
 702
 703
 704
 705
 706 SUBSECTION:: Subclassing
 707
 708 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.
 709
 710 METHOD:: defaultKeyDownAction
 711
 712         The method called when a key is pressed and link::#-keyDownAction:: is nil. Subclass it to define your own functionality on key presses.
 713
 714         See link::#key_actions#Key actions :: for explanation of arguments.
 715
 716     The return value controls the event propagation to parent view. See link::#key_and_mouse_event_propagation#Key and mouse event propagation:: for details.
 717
 718 METHOD:: defaultKeyUpAction
 719
 720         The method called when a key is released and link::#-keyUpAction:: is nil.  Subclass it to define your own functionality on key-release.
 721
 722         See link::#key_actions#Key actions :: for explanation of arguments.
 723
 724         The return value controls the event propagation to parent view. See link::#key_and_mouse_event_propagation#Key and mouse event propagation:: for details.
 725
 726
 727 METHOD:: keyDown
 728         Handles response to a key press event. First evaluates link::#*globalKeyDownAction::, then calls link::#-handleKeyDownBubbling::.
 729
 730         note::
 731         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.
 732         ::
 733
 734         See link::#key_actions#Key actions :: for explanation of arguments.
 735
 736         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.
 737
 738 METHOD:: keyUp
 739
 740         Handles response to a key release event. Sets link::#-keyTyped:: to 'char', evaluates link::#*globalKeyUpAction::, and then calls link::#-handleKeyUpBubbling::.
 741
 742         note::
 743         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.
 744         ::
 745
 746         See link::#key_actions#Key actions :: for explanation of arguments.
 747
 748         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.
 749
 750 METHOD:: keyModifiersChanged
 751         Handles response to a modifier key press or release event. Calls link::#-handleKeyModifiersChangedBubbling::.
 752
 753         note::
 754         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.
 755         ::
 756
 757         See link::#key_actions#Key actions :: for explanation of arguments.
 758
 759 METHOD:: handleKeyDownBubbling
 760         note:: Only in Cocoa and SwingOSC GUI ::
 761         Triggers key-down action and propagates the key event to the parent view, if the action returns nil.
 762
 763 METHOD:: handleKeyUpBubbling
 764         note:: Only in Cocoa and SwingOSC GUI ::
 765         Triggers key-up action and propagates the key event to the parent view, if the action returns nil.
 766
 767 METHOD:: handleKeyModifiersChangedBubbling
 768         note:: Only in Cocoa and SwingOSC GUI ::
 769         Triggers key-modifiers-changed action and propagates the key event to the parent view, if the action returns nil.
 770
 771 METHOD:: keyTyped
 772
 773         An instance variable containing the key just typed (after it is released).
 774
 775
 776
 777 METHOD:: mouseDown
 778         Handles response to a mouse button press event. Evaluates link::#-mouseDownAction::.
 779
 780         See link::#mouse_actions#Mouse actions :: for explanation of arguments.
 781
 782 METHOD:: mouseUp
 783         Handles response to a mouse button release event. Evaluates link::#-mouseDownAction::.
 784
 785         See link::#mouse_actions#Mouse actions :: for explanation of arguments.
 786
 787 METHOD:: mouseMove
 788         Handles response to mouse pointer moving after a mouse button has been pressed on the view. Evaluates link::#-mouseMoveAction::.
 789
 790         See link::#mouse_actions#Mouse actions :: for explanation of arguments.
 791
 792 METHOD:: mouseOver
 793         Handles response to mouse pointer moving over the view with no mouse buttons pressed. Evaluates link::#-mouseOverAction::.
 794
 795         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::.
 796
 797         See link::#mouse_actions#Mouse actions :: for explanation of arguments.
 798
 799 METHOD:: mouseEnter
 800         note:: strong:: Only in Qt GUI :: ::
 801
 802         Handles response to mouse pointer entering the view. Evaluates link::#-mouseEnterAction::.
 803
 804 METHOD:: mouseLeave
 805         note:: strong:: Only in Qt GUI :: ::
 806
 807         Handles response to mouse pointer leaving the view. Evaluates link::#-mouseLeaveAction::.
 808
 809
 810
 811 METHOD:: defaultGetDrag
 812
 813         The view's default method to determine the content of the drag&drop operation just initiated.
 814
 815         returns:: The object to be set as link::#*currentDrag::. If nil is returned, the drag&drop operation will not begin.
 816
 817 METHOD:: defaultCanReceiveDrag
 818
 819         The view's default evaluation whether the content of the ongoing drag&drop operation can be accepted.
 820
 821         returns:: A Boolean stating whether link::#*currentDrag:: is useful. If false is returned, the drop will not be handled by this view.
 822
 823 METHOD:: defaultReceiveDrag
 824
 825         The view's default handling of the data dropped on it (stored in link::#*currentDrag::).
 826
 827 METHOD:: beginDrag
 828         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.
 829
 830         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. ::
 831
 832         argument:: x
 833                 Current horizontal position of the mouse pointer.
 834
 835         argument:: y
 836                 Current vertical position of the mouse pointer.
 837
 838         returns:: A Boolean stating whether the drag&drop operation shall begin.
 839
 840 METHOD:: canReceiveDrag
 841         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.
 842
 843         note:: The description of arguments is valid strong:: only for Qt GUI: ::. In other GUI kits this method has no arguments. ::
 844
 845         argument:: x
 846                 Current horizontal position of the mouse pointer.
 847
 848         argument:: y
 849                 Current vertical position of the mouse pointer.
 850
 851         returns:: A Boolean stating whether the current drag&drop content can be dropped on the view.
 852
 853 METHOD:: receiveDrag
 854         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.
 855
 856         argument:: x
 857                 Current horizontal position of the mouse pointer.
 858
 859         argument:: y
 860                 Current vertical position of the mouse pointer.