1071 lines
34 KiB
Racket
1071 lines
34 KiB
Racket
#lang scribble/manual
|
|
@(require (for-label racket))
|
|
|
|
@title{View}
|
|
The basic visible element of GUI@section{categories}
|
|
GUI>Views
|
|
|
|
@section{description}
|
|
|
|
The View class is the superclass of all view classes.
|
|
|
|
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.
|
|
|
|
|
|
|
|
@section{CLASSMETHODS}
|
|
|
|
|
|
@section{PRIVATE}
|
|
key
|
|
|
|
@section{METHOD}
|
|
new
|
|
|
|
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.
|
|
|
|
@section{note}
|
|
|
|
|
|
The 'parent' argument may be omitted, in which case the view will be displayed as a window on its own, when link::Classes/View#-front#shown::.
|
|
|
|
The 'bounds' argument may be omitted, in which case the view will be created with its preferred size at position (0,0).
|
|
|
|
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.
|
|
::
|
|
|
|
@section{argument}
|
|
parent
|
|
The instance of View or Window that the new View will become a child of.
|
|
|
|
@section{argument}
|
|
bounds
|
|
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.
|
|
|
|
|
|
|
|
@section{METHOD}
|
|
globalKeyDownAction
|
|
|
|
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::.
|
|
|
|
When the action object is evaluated, it is passed the following arguments: view, char, modifiers, unicode, keycode.
|
|
|
|
@section{METHOD}
|
|
globalKeyUpAction
|
|
|
|
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::.
|
|
|
|
When the action object is evaluated, it is passed the following arguments: view, char, modifiers, unicode, keycode.
|
|
|
|
|
|
@section{METHOD}
|
|
currentDrag
|
|
|
|
A class variable holding the content of the current drag. It is set by beginDrag.
|
|
|
|
|
|
@section{METHOD}
|
|
currentDragString
|
|
|
|
A class variable holding the content of the current drag as link::Classes/Object#-asCompileString#"compile string"::. It is set by beginDrag.
|
|
|
|
|
|
|
|
|
|
@section{INSTANCEMETHODS}
|
|
|
|
|
|
@section{SUBSECTION}
|
|
Hierarchy and existence
|
|
|
|
@section{METHOD}
|
|
parent
|
|
@section{returns}
|
|
The view's parent view, or nil if the view is a top view.
|
|
|
|
@section{METHOD}
|
|
parents
|
|
@section{returns}
|
|
An array of all the parents, grandparents, etc., of the view.
|
|
|
|
@section{METHOD}
|
|
getParents
|
|
@section{returns}
|
|
Same as link::#-parents#parents::.
|
|
|
|
@section{METHOD}
|
|
children
|
|
@section{returns}
|
|
An array of all immediate children of the view.
|
|
|
|
@section{METHOD}
|
|
remove
|
|
Removes the view from its parent view (if any) and destroys the view. After this method is called, the view is not usable anymore.
|
|
|
|
@section{METHOD}
|
|
removeAll
|
|
Removes all the children of the view and destroys them. After this method is called, the former child views are not usable anymore.
|
|
|
|
@section{METHOD}
|
|
close
|
|
|
|
If link::#-deleteOnClose:: is true, this method has the same effect as link::#-remove::, otherwise makes the view invisible.
|
|
|
|
@section{METHOD}
|
|
isClosed
|
|
@section{returns}
|
|
A Boolean stating whether the view has been destroyed.
|
|
|
|
@section{METHOD}
|
|
notClosed
|
|
@section{returns}
|
|
A Boolean, the opposite of 'isClosed'.
|
|
|
|
@section{METHOD}
|
|
asView
|
|
Method that allows compatibility with Window and other classes that are not real subclasses of View, but implement a part of its interface.
|
|
|
|
@section{returns}
|
|
This view.
|
|
|
|
@section{SUBSECTION}
|
|
Visibility
|
|
|
|
@section{METHOD}
|
|
visible
|
|
Gets or sets whether the view is visible.
|
|
|
|
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.
|
|
|
|
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.
|
|
|
|
@section{argument}
|
|
|
|
A Boolean stating the visibility of the view.
|
|
|
|
@section{METHOD}
|
|
front
|
|
|
|
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.
|
|
|
|
@section{METHOD}
|
|
minimize
|
|
|
|
If the view is a window, hides it (only keep it present in the dock/taskbar/etc.).
|
|
|
|
@section{METHOD}
|
|
unminimize
|
|
|
|
If the view is a window, restores the its previous state after being minimized.
|
|
|
|
@section{METHOD}
|
|
fullScreen
|
|
|
|
If the view is a window, displays it full-screen.
|
|
|
|
@section{METHOD}
|
|
endFullScreen
|
|
|
|
If the view is a window, restores its previous state after being displayed full-screen.
|
|
|
|
@section{METHOD}
|
|
alwaysOnTop
|
|
|
|
|
|
If the view is a window, gets or sets whether it should always stay on top of other windows.
|
|
|
|
@section{argument}
|
|
boolean
|
|
A Boolean stating whether the view should always stay on top.
|
|
|
|
|
|
|
|
|
|
@section{SUBSECTION}
|
|
Size and position
|
|
|
|
@section{METHOD}
|
|
bounds
|
|
|
|
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.
|
|
|
|
The setter takes a Rect or a Point interpreted link::Classes/Point#-asRect#as Rect::. The getter always returns a Rect.
|
|
|
|
@section{METHOD}
|
|
absoluteBounds
|
|
|
|
@section{returns}
|
|
A Rect describing the absolute position and the size of the view on the screen.
|
|
|
|
@section{METHOD}
|
|
sizeHint
|
|
|
|
@section{returns}
|
|
A Size describing the preferred size of the view to comfortably display its contents and allow useful interaction.
|
|
|
|
@section{METHOD}
|
|
minSizeHint
|
|
|
|
|
|
@section{returns}
|
|
A Size describing the minimum size of the view to be able to display its contents and allow any interaction.
|
|
|
|
@section{METHOD}
|
|
maxSize
|
|
|
|
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.
|
|
|
|
@section{argument}
|
|
size
|
|
A Size.
|
|
|
|
@section{METHOD}
|
|
minSize
|
|
|
|
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.
|
|
|
|
@section{argument}
|
|
size
|
|
A Size.
|
|
|
|
|
|
@section{METHOD}
|
|
fixedSize
|
|
|
|
Set both minimum and maximum allowed size of the view, thus making it non-resizable.
|
|
|
|
@section{argument}
|
|
size
|
|
A Size.
|
|
|
|
@section{METHOD}
|
|
fixedWidth
|
|
|
|
Set both minimum and maximum allowed width of the view, thus making it non-resizable.
|
|
|
|
@section{argument}
|
|
width
|
|
An Int.
|
|
|
|
@section{METHOD}
|
|
fixedHeight
|
|
|
|
Set both minimum and maximum allowed height of the view, thus making it non-resizable.
|
|
|
|
@section{argument}
|
|
height
|
|
An Int.
|
|
|
|
@section{METHOD}
|
|
maxWidth
|
|
|
|
Set maximum allowed width of the view, the view will not be able to grow larger in width, neither by user interaction nor programmatically.
|
|
|
|
@section{argument}
|
|
width
|
|
An Int.
|
|
|
|
|
|
@section{METHOD}
|
|
minWidth
|
|
|
|
Set minimum allowed width of the view, the view will not be able to shrink smaller in width, neither by user interaction nor programmatically.
|
|
|
|
@section{argument}
|
|
width
|
|
An Int.
|
|
|
|
|
|
@section{METHOD}
|
|
maxHeight
|
|
|
|
Set maximum allowed height of the view, the view will not be able to grow larger in height, neither by user interaction nor programmatically.
|
|
|
|
@section{argument}
|
|
height
|
|
An Int.
|
|
|
|
|
|
|
|
@section{METHOD}
|
|
minHeight
|
|
|
|
Set minimum allowed height of the view, the view will not be able to shrink smaller in height, neither by user interaction nor programmatically.
|
|
|
|
@section{argument}
|
|
height
|
|
An Int.
|
|
|
|
@section{METHOD}
|
|
moveTo
|
|
|
|
Move the view to new position, preserving its size.
|
|
|
|
@section{argument}
|
|
x
|
|
An Int: the horizontal position of the new position.
|
|
|
|
@section{argument}
|
|
y
|
|
An Int: the vertical position of the new position.
|
|
|
|
@section{METHOD}
|
|
resizeTo
|
|
|
|
Resize the view, preserving its position.
|
|
|
|
@section{argument}
|
|
width
|
|
An Int: the new horizontal size of the view.
|
|
|
|
@section{argument}
|
|
height
|
|
An Int: the new vertical size of the view.
|
|
|
|
@section{METHOD}
|
|
resize
|
|
Determines what happens with the view's position and size when its parent is resized. See link::Guides/GUI-Introduction#view:: for further explanation.
|
|
|
|
@section{argument}
|
|
|
|
An Int (1 to 9) defining the auto-resize behavior. See link::Reference/Resize:: for a list of valid resize modes.
|
|
|
|
@section{METHOD}
|
|
decorator
|
|
|
|
|
|
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.
|
|
|
|
@section{argument}
|
|
|
|
An instance of a decorator class (e.g. FlowLayout).
|
|
|
|
@section{METHOD}
|
|
addFlowLayout
|
|
|
|
|
|
A convenience method which sets decorator to a new instance of FlowLayout. See link::Classes/FlowLayout:: for examples.
|
|
|
|
@section{argument}
|
|
margin
|
|
A Point describing the link::Classes/FlowLayout#-margin#margin:: of the FlowLayout.
|
|
|
|
@section{argument}
|
|
gap
|
|
A Point describing the link::Classes/FlowLayout#-gap#gap:: of the FlowLayout.
|
|
|
|
@section{returns}
|
|
The new FlowLayout instance.
|
|
|
|
@section{METHOD}
|
|
flow
|
|
|
|
|
|
Creates a FlowView as a child of the view, and then evaluates 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.
|
|
|
|
@section{argument}
|
|
func
|
|
The object that will be evaluated after the creation of the FlowView, passing the new FlowView instance as an argument.
|
|
|
|
@section{argument}
|
|
bounds
|
|
A Rect to set as the bounds of the FlowView, or nil, implying the size of this view and position (0,0).
|
|
|
|
After 'func' is evaluated, the FlowView will be resized to fit its contents and cast away any extra space it occupies.
|
|
|
|
@section{returns}
|
|
The new FlowView instance.
|
|
|
|
@section{METHOD}
|
|
layout
|
|
|
|
|
|
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.
|
|
|
|
@section{argument}
|
|
|
|
An instance of a subclass of Layout.
|
|
|
|
|
|
|
|
|
|
@section{METHOD}
|
|
mapToGlobal
|
|
|
|
|
|
Map a point relative to this view's top-left to absolute position on screen.
|
|
|
|
@section{argument}
|
|
|
|
A Point describing a position relative to the view.
|
|
|
|
@section{returns}
|
|
|
|
A Point describing the same position, but relative to the screen.
|
|
|
|
|
|
@section{SUBSECTION}
|
|
Appearance
|
|
|
|
@section{METHOD}
|
|
name
|
|
|
|
|
|
If the view is a window, sets its title
|
|
|
|
@section{argument}
|
|
|
|
A String containing text for the window title.
|
|
|
|
|
|
@section{METHOD}
|
|
alpha
|
|
|
|
|
|
If the view is a window, this controls its transparency.
|
|
|
|
@section{argument}
|
|
aFloat
|
|
A Float between 0.0 (invisible) and 1.0 (opaque).
|
|
|
|
@section{METHOD}
|
|
font
|
|
@section{note}
|
|
Every view has this method.::
|
|
The font used by the view to display text (if any).
|
|
|
|
@section{argument}
|
|
|
|
A Font.
|
|
|
|
|
|
@section{METHOD}
|
|
background
|
|
Get or set the color of whatever is considered the background of the view.
|
|
|
|
@section{argument}
|
|
|
|
A Color.
|
|
|
|
|
|
@section{METHOD}
|
|
focusColor
|
|
Get or set the color used to display keyboard focus on the view.
|
|
|
|
@section{argument}
|
|
|
|
A Color.
|
|
|
|
@section{METHOD}
|
|
palette
|
|
|
|
Get or set the palette to be used by the view.
|
|
|
|
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. See also link::Classes/QPalette#-hasColor::.
|
|
|
|
When getting a palette, it will return a new copy of the view's palette every time. Therefore, if you wish to change the view's palette, you have to set the changed palette back on the view:
|
|
|
|
|
|
@racketblock[
|
|
w = Window().front.layout_( HLayout( a = Slider() ) );
|
|
a.action = { |a|
|
|
a.palette = a.palette.buttonText_( if(a.value > 0.5){Color.red}{Color.green} );
|
|
};
|
|
a.valueAction = 0.0;
|
|
::
|
|
|
|
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:
|
|
|
|
]
|
|
|
|
@racketblock[
|
|
w = Window().front.layout_( HLayout( a = Slider() ) );
|
|
p = QPalette();
|
|
a.action = { |a|
|
|
a.palette = p.buttonText_( if(a.value > 0.5){Color.red}{Color.green} );
|
|
};
|
|
a.valueAction = 0.0;
|
|
::
|
|
|
|
See link::Classes/QPalette:: for detailed explanation of how palettes work.
|
|
|
|
]
|
|
@section{argument}
|
|
|
|
A QPalette.
|
|
|
|
@section{METHOD}
|
|
refresh
|
|
Redraws the view and all its children.
|
|
|
|
|
|
@section{SUBSECTION}
|
|
Common behavior
|
|
|
|
|
|
@section{METHOD}
|
|
userCanClose
|
|
|
|
|
|
If the view is a window, sets or gets whether the user can close it via mouse or key actions.
|
|
|
|
@section{argument}
|
|
|
|
A Boolean.
|
|
|
|
|
|
@section{METHOD}
|
|
deleteOnClose
|
|
|
|
|
|
Sets or gets whether the view should be destroyed when closed.
|
|
|
|
@section{argument}
|
|
|
|
A Boolean.
|
|
|
|
@section{METHOD}
|
|
enabled
|
|
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).
|
|
|
|
@section{argument}
|
|
|
|
A Boolean.
|
|
|
|
|
|
@section{METHOD}
|
|
canFocus
|
|
Sets or gets whether the view can receive keyboard focus.
|
|
|
|
@section{argument}
|
|
|
|
A Boolean.
|
|
|
|
@section{METHOD}
|
|
focus
|
|
If 'flag' is true, gives keyboard focus to the view (if possible), otherwise removes the keyboard focus from it.
|
|
|
|
@section{argument}
|
|
flag
|
|
A Boolean.
|
|
|
|
@section{METHOD}
|
|
hasFocus
|
|
|
|
@section{returns}
|
|
A Boolean, stating whether the view currently has the keyboard focus.
|
|
|
|
@section{METHOD}
|
|
acceptsMouse
|
|
|
|
|
|
Sets or gets whether the view responds to mouse interaction. If
|
|
@racketblock[false::, the view will be completely transparent for mouse and interaction will be possible with any view under.
|
|
|
|
Defaults to ]
|
|
|
|
@racketblock[true::.
|
|
|
|
]
|
|
@section{argument}
|
|
|
|
A Boolean.
|
|
|
|
@section{METHOD}
|
|
acceptsMouseOver
|
|
If this is a top view, this variable defines whether the view and all its children receive mouse-over events. The default is
|
|
@racketblock[false::.
|
|
|
|
See also: link::#-mouseOverAction::.
|
|
|
|
]
|
|
@section{argument}
|
|
|
|
A Boolean.
|
|
|
|
|
|
@section{SUBSECTION}
|
|
Actions in general
|
|
|
|
@section{METHOD}
|
|
action
|
|
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.).
|
|
|
|
@section{argument}
|
|
func
|
|
Any object to set as default action, usually a Function or a FunctionList. When evaluated, it will be passed the view as an argument.
|
|
|
|
|
|
@section{METHOD}
|
|
doAction
|
|
Evaluates the default link::#-action#action::.
|
|
|
|
|
|
@section{METHOD}
|
|
addAction
|
|
@section{METHOD}
|
|
removeAction
|
|
|
|
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'.
|
|
|
|
This is useful for adding functionality to existing frameworks that have action functions already.
|
|
|
|
@section{argument}
|
|
func
|
|
Any object to add as an action, usually a Function.
|
|
|
|
@section{argument}
|
|
selector
|
|
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.
|
|
|
|
@section{SUBSECTION}
|
|
Key and mouse event processing
|
|
|
|
Both mouse and key events can propagate to the parent view. Event processing 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.
|
|
|
|
If you wish to control whether the event will be propagated or not, return
|
|
@racketblock[true:: or ]
|
|
|
|
@racketblock[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 ]
|
|
|
|
@racketblock[true:: or ]
|
|
|
|
@racketblock[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.
|
|
|
|
]
|
|
@section{SUBSECTION}
|
|
Mouse actions
|
|
|
|
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.
|
|
|
|
@section{note}
|
|
|
|
Mouse actions are subject to emphasis::event propagation::. See link::#Key and mouse event processing:: for details.
|
|
::
|
|
|
|
When the mouse action object is evaluated, it is passed one or more arguments from the following list (in that order):
|
|
|
|
@section{list}
|
|
|
|
## strong::view:: - the view
|
|
## strong::x:: - the x coordinate
|
|
## strong::y:: - the y coordinate
|
|
## strong::modifiers:: - A bitwise or of integers indicating the modifier keys in effect. For a list of these, see link::Reference/Modifiers::.
|
|
## strong::buttonNumber:: - 0-left, 1-right, 2-middle, etc.
|
|
## strong::clickCount:: - the number of clicks within the system click time limit. At least 1.
|
|
::
|
|
|
|
@section{METHOD}
|
|
mouseDownAction
|
|
The object to be evaluated when a mouse button is pressed on the view.
|
|
|
|
The following arguments are passed at evaluation: strong::view, x, y, modifiers, buttonNumber, clickCount::. See link::#Mouse actions:: for explanation of arguments.
|
|
|
|
The return value of evaluation controls the event propagation to parent view. See link::#Key and mouse event processing:: for details.
|
|
|
|
@section{METHOD}
|
|
mouseUpAction
|
|
The object to be evaluated when a mouse button is released after it was pressed on the view.
|
|
|
|
The following arguments are passed at evaluation: strong::view, x, y, modifiers::. See link::#Mouse actions:: for explanation of arguments.
|
|
|
|
The return value of evaluation controls the event propagation to parent view. See link::#Key and mouse event processing:: for details.
|
|
|
|
@section{METHOD}
|
|
mouseMoveAction
|
|
The object to be evaluated whenever the mouse pointer moves after a mouse button was pressed on the view.
|
|
|
|
The following arguments are passed at evaluation: strong::view, x, y, modifiers::. See link::#Mouse actions:: for explanation of arguments.
|
|
|
|
The return value of evaluation controls the event propagation to parent view. See link::#Key and mouse event processing:: for details.
|
|
|
|
@section{METHOD}
|
|
mouseOverAction
|
|
The object to be evaluated when the mouse pointer moves over the view with no mouse buttons pressed.
|
|
|
|
The following arguments are passed at evaluation: strong::view, x, y::. See link::#Mouse actions:: for explanation of arguments.
|
|
|
|
The object is evaluated only when link::Classes/Window#-acceptsMouseOver:: of the containing Window (or link::#-acceptsMouseOver:: of the top View) is
|
|
@racketblock[true::.
|
|
|
|
The return value of evaluation controls the event propagation to parent view. See link::#Key and mouse event processing:: for details.
|
|
|
|
]
|
|
@section{METHOD}
|
|
mouseWheelAction
|
|
|
|
The object to be evaluated when the mouse wheel is used while the mouse is pointing onto the view.
|
|
|
|
The following arguments are passed at evaluation: strong::view, x, y, modifiers, xDelta, yDelta::. See link::#Mouse actions:: for explanation of arguments.
|
|
|
|
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.
|
|
|
|
The return value of evaluation controls the event propagation to parent view. See link::#Key and mouse event processing:: for details.
|
|
|
|
@section{METHOD}
|
|
mouseEnterAction
|
|
|
|
The object to be evaluated when the mouse pointer enters the view.
|
|
|
|
The following arguments are passed at evaluation: strong::view, x, y::. See link::#Mouse actions:: for explanation of arguments.
|
|
|
|
@section{METHOD}
|
|
mouseLeaveAction
|
|
|
|
The object to be evaluated when the mouse pointer leaves the view.
|
|
|
|
The following arguments are passed at evaluation: strong::view, x, y::. See link::#Mouse actions:: for explanation of arguments.
|
|
|
|
|
|
@section{SUBSECTION}
|
|
Key actions
|
|
|
|
Use the methods below to set or get the view's actions in response to keyboard interaction when the view has the keyboard focus.
|
|
|
|
@section{note}
|
|
|
|
Key actions are subject to emphasis::event propagation::. See link::#Key and mouse event processing:: for details.
|
|
::
|
|
|
|
When the key action object is evaluated, it is passed one or more arguments from the following list (in that order):
|
|
|
|
@section{list}
|
|
|
|
## strong::view:: - The view.
|
|
|
|
## strong::char:: - The character (link::Classes/Char::) 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.
|
|
@section{note}
|
|
Only characters with an ASCII code are passed. Non-ASCII keys (Ctrl/Alt/Cmd/Shift modifiers, arrow keys and other control sequences) will pass a link::Classes/Char:: with ASCII code 0. (Ctrl-characters emphasis::do:: have ASCII codes, and are passed as a Char. The Ctrl key by itself also triggers the key action, but with ASCII code 0.) A useful test is link::Classes/Char#-isPrint::.::
|
|
|
|
## 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::.
|
|
|
|
## strong::uni
|
|
@racketblock[ - The Integer unicode number associated with the 'char' passed.
|
|
|
|
## strong::key]
|
|
|
|
@racketblock[ - 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. ]
|
|
@section{warning}
|
|
Function key modifier in combination with another key may change the latter's keycode.::
|
|
|
|
## strong::key:: - An Integer denoting a key, corresponding to the "Key" enum of the Qt C++ API. Comparing this value is the most reliable way to check which key was pressed. For a list of possible values, see: link::http://qt-project.org/doc/qt-4.8/qt.html#Key-enum::.
|
|
::
|
|
|
|
@section{METHOD}
|
|
keyDownAction
|
|
The object to be evaluated when a key is pressed.
|
|
|
|
The following arguments are passed at evaluation: strong::view, char, modifiers, unicode, keycode, key::. See link::#Key actions:: for explanation of arguments.
|
|
|
|
The return value of evaluation controls the event propagation to parent view. See link::#Key and mouse event processing:: for details.
|
|
|
|
If no
|
|
@racketblock[keyDownAction:: is set, link::#-defaultKeyDownAction:: is called instead, and its return value controls the event propagation.
|
|
|
|
]
|
|
|
|
@racketblock[
|
|
// open a new document that posts the parameters passed into the keydownAction function.
|
|
(
|
|
Document("test arguments").keyDownAction = { |doc, char, mod, unicode, keycode, key|
|
|
[doc, char, mod, unicode, keycode, key].postln
|
|
};
|
|
)
|
|
::
|
|
|
|
]
|
|
@section{METHOD}
|
|
keyUpAction
|
|
The object to be evaluated when a key is released.
|
|
|
|
The following arguments are passed at evaluation: strong::view, char, modifiers, unicode, keycode, key::. See link::#Key actions:: for explanation of arguments.
|
|
|
|
The return value of evaluation controls the event propagation to parent view. See link::#Key and mouse event processing:: for details.
|
|
|
|
If no
|
|
@racketblock[keyUpAction:: is set, link::#-defaultKeyUpAction:: is called instead, and its return value controls the event propagation.
|
|
|
|
]
|
|
@section{METHOD}
|
|
keyModifiersChangedAction
|
|
The object to be evaluated when a modifier key is pressed or released.
|
|
|
|
The following arguments are passed at evaluation: strong::view, modifiers::.
|
|
|
|
|
|
@section{SUBSECTION}
|
|
Drag and drop
|
|
|
|
Use the methods below to define or override how the view handles drag&drop operations.
|
|
|
|
@section{METHOD}
|
|
beginDragAction
|
|
Sets or gets the object evaluated when a drag&drop operation is initiated.
|
|
|
|
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.
|
|
|
|
If this variable is nil (the default) the view's link::#-defaultGetDrag:: method is called instead.
|
|
|
|
@section{METHOD}
|
|
canReceiveDragHandler
|
|
Sets or gets the object evaluated when the mouse pointer moves over the view while a drag&drop operation is taking place.
|
|
|
|
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.
|
|
|
|
If this variable is nil (the default) the view's link::#-defaultCanReceiveDrag:: method is called instead.
|
|
|
|
@section{METHOD}
|
|
receiveDragHandler
|
|
Sets or gets the object evaluated when a drag&drop operation finishes on this view.
|
|
|
|
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.
|
|
|
|
If this variable is nil (the default) the view's link::#-defaultReceiveDrag:: method is called instead.
|
|
|
|
|
|
@section{METHOD}
|
|
dragLabel
|
|
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::.
|
|
|
|
@section{argument}
|
|
|
|
A String containing the text to be displayed.
|
|
|
|
|
|
|
|
|
|
@section{SUBSECTION}
|
|
Other actions and hooks
|
|
|
|
@section{METHOD}
|
|
focusGainedAction
|
|
|
|
Sets or gets the object to be evaluated when the view gains the keyboard focus. It is passed the view as an argument.
|
|
|
|
@section{METHOD}
|
|
focusLostAction
|
|
|
|
|
|
Sets or gets the object to be evaluated when the view looses the keyboard focus. It is passed the view as an argument.
|
|
|
|
@section{METHOD}
|
|
toFrontAction
|
|
|
|
|
|
Sets or gets the object to be evaluated when the view becomes the active window. It is passed the view as an argument.
|
|
|
|
@section{METHOD}
|
|
endFrontAction
|
|
|
|
|
|
Sets or gets the object to be evaluated when the view becomes the active window. It is passed the view as an argument.
|
|
|
|
@section{METHOD}
|
|
onResize
|
|
|
|
|
|
Sets or gets the object to be evaluated when the view changes its size. It is passed the view as an argument.
|
|
|
|
@section{METHOD}
|
|
onMove
|
|
|
|
|
|
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.
|
|
|
|
@section{METHOD}
|
|
onClose
|
|
|
|
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.
|
|
|
|
|
|
|
|
|
|
@section{SUBSECTION}
|
|
Handlers
|
|
|
|
@section{note}
|
|
Older tutorials might recommend subclassing View to override these methods. Don't do that. Use composition, not inheritance. Make the View a property of your custom view class. ::
|
|
|
|
The following methods are the default handlers of key press and release events.
|
|
|
|
@section{METHOD}
|
|
defaultKeyDownAction
|
|
|
|
The method called when a key is pressed and link::#-keyDownAction:: is nil. Subclass it to define your own functionality on key presses.
|
|
|
|
See link::#Key actions:: for explanation of arguments.
|
|
|
|
The return value controls the event propagation to parent view. See link::#Key and mouse event processing:: for details.
|
|
|
|
@section{METHOD}
|
|
defaultKeyUpAction
|
|
|
|
The method called when a key is released and link::#-keyUpAction:: is nil. Subclass it to define your own functionality on key-release.
|
|
|
|
See link::#Key actions:: for explanation of arguments.
|
|
|
|
The return value controls the event propagation to parent view. See link::#Key and mouse event processing:: for details.
|
|
|
|
|
|
@section{METHOD}
|
|
keyDown
|
|
Handles response to a key press event. First evaluates link::#*globalKeyDownAction::.
|
|
|
|
@section{note}
|
|
|
|
This method directly triggers the action and returns, forwarding the action's return value. See link::#Key actions:: for detailed explanation.
|
|
::
|
|
|
|
See link::#Key actions:: for explanation of arguments.
|
|
|
|
@section{returns}
|
|
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.
|
|
|
|
@section{METHOD}
|
|
keyUp
|
|
|
|
Handles response to a key release event. Sets link::#-keyTyped:: to 'char', evaluates link::#*globalKeyUpAction::, and then calls link::#-handleKeyUpBubbling::.
|
|
|
|
@section{note}
|
|
|
|
This method directly triggers the action and returns, forwarding the action's return value. See link::#Key actions:: for detailed explanation.
|
|
::
|
|
|
|
See link::#Key actions:: for explanation of arguments.
|
|
|
|
@section{returns}
|
|
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.
|
|
|
|
@section{METHOD}
|
|
keyModifiersChanged
|
|
Handles response to a modifier key press or release event. Calls link::#-handleKeyModifiersChangedBubbling::.
|
|
|
|
@section{note}
|
|
|
|
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.
|
|
::
|
|
|
|
See link::#Key actions:: for explanation of arguments.
|
|
|
|
@section{METHOD}
|
|
keyTyped
|
|
|
|
An instance variable containing the key just typed (after it is released).
|
|
|
|
|
|
|
|
@section{METHOD}
|
|
mouseDown
|
|
Handles response to a mouse button press event. Evaluates link::#-mouseDownAction::.
|
|
|
|
See link::#Mouse actions:: for explanation of arguments.
|
|
|
|
@section{METHOD}
|
|
mouseUp
|
|
Handles response to a mouse button release event. Evaluates link::#-mouseDownAction::.
|
|
|
|
See link::#Mouse actions:: for explanation of arguments.
|
|
|
|
@section{METHOD}
|
|
mouseMove
|
|
Handles response to mouse pointer moving after a mouse button has been pressed on the view. Evaluates link::#-mouseMoveAction::.
|
|
|
|
See link::#Mouse actions:: for explanation of arguments.
|
|
|
|
@section{METHOD}
|
|
mouseOver
|
|
Handles response to mouse pointer moving over the view with no mouse buttons pressed. Evaluates link::#-mouseOverAction::.
|
|
|
|
This method is called only if link::Classes/Window#-acceptsMouseOver:: of the containing Window (or, link::#-acceptsMouseOver:: of the top View) is
|
|
@racketblock[true::.
|
|
|
|
See link::#Mouse actions:: for explanation of arguments.
|
|
|
|
]
|
|
@section{METHOD}
|
|
mouseEnter
|
|
|
|
Handles response to mouse pointer entering the view. Evaluates link::#-mouseEnterAction::.
|
|
|
|
@section{METHOD}
|
|
mouseLeave
|
|
|
|
Handles response to mouse pointer leaving the view. Evaluates link::#-mouseLeaveAction::.
|
|
|
|
|
|
|
|
@section{METHOD}
|
|
defaultGetDrag
|
|
|
|
@section{note}
|
|
Not yet implemented::
|
|
|
|
The view's default method to determine the content of the drag&drop operation just initiated.
|
|
|
|
@section{returns}
|
|
The object to be set as link::#*currentDrag::. If nil is returned, the drag&drop operation will not begin.
|
|
|
|
@section{METHOD}
|
|
defaultCanReceiveDrag
|
|
|
|
@section{note}
|
|
Not yet implemented::
|
|
|
|
The view's default evaluation whether the content of the ongoing drag&drop operation can be accepted.
|
|
|
|
@section{returns}
|
|
A Boolean stating whether link::#*currentDrag:: is useful. If false is returned, the drop will not be handled by this view.
|
|
|
|
@section{METHOD}
|
|
defaultReceiveDrag
|
|
|
|
@section{note}
|
|
Not yet implemented::
|
|
|
|
The view's default handling of the data dropped on it (stored in link::#*currentDrag::).
|
|
|
|
@section{METHOD}
|
|
beginDrag
|
|
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.
|
|
|
|
|
|
@section{argument}
|
|
x
|
|
Current horizontal position of the mouse pointer.
|
|
|
|
@section{argument}
|
|
y
|
|
Current vertical position of the mouse pointer.
|
|
|
|
@section{returns}
|
|
A Boolean stating whether the drag&drop operation shall begin.
|
|
|
|
@section{METHOD}
|
|
canReceiveDrag
|
|
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.
|
|
|
|
@section{argument}
|
|
x
|
|
Current horizontal position of the mouse pointer.
|
|
|
|
@section{argument}
|
|
y
|
|
Current vertical position of the mouse pointer.
|
|
|
|
@section{returns}
|
|
A Boolean stating whether the current drag&drop content can be dropped on the view.
|
|
|
|
@section{METHOD}
|
|
receiveDrag
|
|
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.
|
|
|
|
@section{argument}
|
|
x
|
|
Current horizontal position of the mouse pointer.
|
|
|
|
@section{argument}
|
|
y
|
|
Current vertical position of the mouse pointer.
|
|
|
|
|