View:
Filter:
Classes | GUI > Views

View

The basic visible element of GUI
Location: NOT INSTALLED!

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.

Class Methods

.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 decorator installed on the parent, it will manage the position of the new View.

NOTE: The 'parent' argument may be omitted, in which case the view will be displayed as a window on its own, when 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.

Arguments:

parent

The instance of View or Window that the new View will become a child of.

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.

.globalKeyDownAction

A settable class variable containing an object (e.g. an instance of Function or FunctionList) which is evaluated (i.e. value method is called on it) whenever a key is pressed, independently of keyboard focus. See also -addAction.

When the action object is evaluated, it is passed the following arguments: view, char, modifiers, unicode, keycode, key.

.globalKeyUpAction

A settable class variable containing an object (e.g. an instance of Function or FunctionList) which is evaluated (i.e. value method is called on it) whenever a key is released, independently of keyboard focus. See also -addAction.

When the action object is evaluated, it is passed the following arguments: view, char, modifiers, unicode, keycode.

.currentDrag

A class variable holding the content of the current drag. It is set by beginDrag.

.currentDragString

A class variable holding the content of the current drag as "compile string". It is set by beginDrag.

Inherited class methods

Instance Methods

Hierarchy and existence

.parent

Returns:

The view's parent view, or nil if the view is a top view.

.parents

Returns:

An array of all the parents, grandparents, etc., of the view.

.getParents

Returns:

Same as parents.

.children

Returns:

An array of all immediate children of the view.

.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.

.removeAll

Removes all the children of the view and destroys them. After this method is called, the former child views are not usable anymore.

.close

If -deleteOnClose is true, this method has the same effect as -remove, otherwise makes the view invisible.

.isClosed

Returns:

A Boolean stating whether the view has been destroyed.

.notClosed

Returns:

A Boolean, the opposite of 'isClosed'.

.asView

Method that allows compatibility with Window and other classes that are not real subclasses of View, but implement a part of its interface.

Returns:

This view.

Visibility

.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 -front, and setting it to false closes the window without destroying it.

Arguments:

A Boolean stating the visibility of the view.

.front

If the view does not have a parent, displays it on the screen as a window (it has the same effect as setting -visible to true), otherwise it has no effect.

.minimize

If the view is a window, hides it (only keep it present in the dock/taskbar/etc.).

.unminimize

If the view is a window, restores the its previous state after being minimized.

.fullScreen

If the view is a window, displays it full-screen.

.endFullScreen

If the view is a window, restores its previous state after being displayed full-screen.

.alwaysOnTop

If the view is a window, gets or sets whether it should always stay on top of other windows.

Arguments:

boolean

A Boolean stating whether the view should always stay on top.

Size and position

.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 as Rect. The getter always returns a Rect.

.absoluteBounds

Returns:

A Rect describing the absolute position and the size of the view on the screen.

.sizeHint

Returns:

A Size describing the preferred size of the view to comfortably display its contents and allow useful interaction.

.minSizeHint

Returns:

A Size describing the minimum size of the view to be able to display its contents and allow any interaction.

.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.

Arguments:

size

A Size.

.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.

Arguments:

size

A Size.

.fixedSize

Set both minimum and maximum allowed size of the view, thus making it non-resizable.

Arguments:

size

A Size.

.fixedWidth

Set both minimum and maximum allowed width of the view, thus making it non-resizable.

Arguments:

width

An Int.

.fixedHeight

Set both minimum and maximum allowed height of the view, thus making it non-resizable.

Arguments:

height

An Int.

.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.

Arguments:

width

An Int.

.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.

Arguments:

width

An Int.

.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.

Arguments:

height

An Int.

.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.

Arguments:

height

An Int.

.moveTo

Move the view to new position, preserving its size.

Arguments:

x

An Int: the horizontal position of the new position.

y

An Int: the vertical position of the new position.

.resizeTo

Resize the view, preserving its position.

Arguments:

width

An Int: the new horizontal size of the view.

height

An Int: the new vertical size of the view.

.resizeToBounds

Arguments:

rect

A Rect: the bounds to which the view will be resized.

.resizeToHint

Resizes view to the bounds returned by -sizeHint.

.resize

Determines what happens with the view's position and size when its parent is resized. See Introduction to GUI: view for further explanation.

Arguments:

An Int (1 to 9) defining the auto-resize behavior. See Resize behaviour for a list of valid resize modes.

.decorator

Get or set the decorator object, that automatically manages the positioning of new children of the view when they are created. See Introduction to GUI: decorators for further explanation.

Arguments:

An instance of a decorator class (e.g. FlowLayout).

.addFlowLayout

A convenience method which sets decorator to a new instance of FlowLayout. See FlowLayout for examples.

Arguments:

margin

A Point describing the margin of the FlowLayout.

gap

A Point describing the gap of the FlowLayout.

Returns:

The new FlowLayout instance.

.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.

Arguments:

func

The object that will be evaluated after the creation of the FlowView, passing the new FlowView instance as an 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.

Returns:

The new FlowView instance.

.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 Introduction to GUI: layouts for further explanation.

Arguments:

An instance of a subclass of Layout.

.mapToGlobal

Map a point relative to this view's top-left to absolute position on screen.

Arguments:

A Point describing a position relative to the view.

Returns:

A Point describing the same position, but relative to the screen.

Appearance

.name

If the view is a window, sets its title

Arguments:

A String containing text for the window title.

.alpha

If the view is a window, this controls its transparency.

Arguments:

aFloat

A Float between 0.0 (invisible) and 1.0 (opaque).

.font

NOTE: Every view has this method.

The font used by the view to display text (if any).

Arguments:

A Font.

.background

Get or set the color of whatever is considered the background of the view.

Arguments:

A Color.

.backgroundImage

Sets an Image as the view background. If you need more functionality, use -setBackgroundImage.

Arguments:

image

the Image to use. It will be fixed to the top left corner of the view.

Discussion:

.setBackgroundImage

Sets an Image as a valid view background, with 16 different drawing modes and opacity support.

Arguments:

image

the Image to use.

tileMode

the mode to use. By default 1 (fixed to left, fixed to top).

1fixed to left, fixed to top
2horizontally tile, fixed to top
3fixed to right, fixed to top
4fixed to left, vertically tile
5horizontally tile, vertically tile
6fixed to right, vertically tile
7fixed to left, fixed to bottom
8horizontally tile, fixed to bottom
9fixed to right, fixed to bottom
10fit
11center, center (scale)
12center , fixed to top
13center , fixed to bottom
14fixed to left, center
15fixed to right, center
16center, center (no scale)
alpha

opacity of the image. 0 <= alpha <= 1, and values outside of that range will be clipped

fromRect

the portion of the image to use. If nil, use the full image.

Discussion:

.focusColor

Get or set the color used to display keyboard focus on the view.

Arguments:

A Color.

.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 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:

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 Slider: -knobColor, since internally they use the above approach:

See QPalette for detailed explanation of how palettes work.

Arguments:

A QPalette.

.refresh

Redraws the view and all its children.

Common behavior

.userCanClose

If the view is a window, sets or gets whether the user can close it via mouse or key actions.

Arguments:

A Boolean.

.deleteOnClose

Sets or gets whether the view should be destroyed when closed.

Arguments:

A Boolean.

.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).

Arguments:

A Boolean.

.canFocus

Sets or gets whether the view can receive keyboard focus.

Arguments:

A Boolean.

.focus

If 'flag' is true, gives keyboard focus to the view (if possible), otherwise removes the keyboard focus from it.

Arguments:

flag

A Boolean.

.hasFocus

Returns:

A Boolean, stating whether the view currently has the keyboard focus.

.acceptsMouse

Sets or gets whether the view responds to mouse interaction. If false, the view will be completely transparent for mouse and interaction will be possible with any view under.

Defaults to true.

Arguments:

A Boolean.

.acceptsMouseOver

If this is a top view, this variable defines whether the view and all its children receive mouse-over events. The default is false.

See also: -mouseOverAction.

Arguments:

A Boolean.

Actions in general

.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.).

Arguments:

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.

.doAction

Evaluates the default action.

.addAction

.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.

Arguments:

func

Any object to add as an action, usually a Function.

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.

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 true or 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 true or 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.

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.

NOTE: Mouse actions are subject to event propagation. See 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):

.mouseDownAction

The object to be evaluated when a mouse button is pressed on the view.

The following arguments are passed at evaluation: view, x, y, modifiers, buttonNumber, clickCount. See Mouse actions for explanation of arguments.

The return value of evaluation controls the event propagation to parent view. See Key and mouse event processing for details.

.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: view, x, y, modifiers, buttonNumber. See Mouse actions for explanation of arguments.

The return value of evaluation controls the event propagation to parent view. See Key and mouse event processing for details.

.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: view, x, y, modifiers. See Mouse actions for explanation of arguments.

The return value of evaluation controls the event propagation to parent view. See Key and mouse event processing for details.

.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: view, x, y. See Mouse actions for explanation of arguments.

The object is evaluated only when Window: -acceptsMouseOver of the containing Window (or -acceptsMouseOver of the top View) is true.

The return value of evaluation controls the event propagation to parent view. See Key and mouse event processing for details.

.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: view, x, y, modifiers, xDelta, yDelta. See 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 Key and mouse event processing for details.

.mouseEnterAction

The object to be evaluated when the mouse pointer enters the view.

The following arguments are passed at evaluation: view, x, y. See Mouse actions for explanation of arguments.

.mouseLeaveAction

The object to be evaluated when the mouse pointer leaves the view.

The following arguments are passed at evaluation: view, x, y. See Mouse actions for explanation of arguments.

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.

NOTE: Key actions are subject to event propagation. See 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):

.keyDownAction

The object to be evaluated when a key is pressed.

The following arguments are passed at evaluation: view, char, modifiers, unicode, keycode, key. See Key actions for explanation of arguments.

The return value of evaluation controls the event propagation to parent view. See Key and mouse event processing for details.

If no keyDownAction is set, -defaultKeyDownAction is called instead, and its return value controls the event propagation.

.keyUpAction

The object to be evaluated when a key is released.

The following arguments are passed at evaluation: view, char, modifiers, unicode, keycode, key. See Key actions for explanation of arguments.

The return value of evaluation controls the event propagation to parent view. See Key and mouse event processing for details.

If no keyUpAction is set, -defaultKeyUpAction is called instead, and its return value controls the event propagation.

.keyModifiersChangedAction

The object to be evaluated when a modifier key is pressed or released.

The following arguments are passed at evaluation: view, modifiers.

Drag and drop

Use the methods below to define or override how the view handles drag&drop operations.

.beginDragAction

Sets or gets the object evaluated when a drag&drop operation is initiated.

At evaluation, the following arguments will be passed: 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 -defaultGetDrag method is called instead.

.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: view, x, y. The view expects the 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 -defaultCanReceiveDrag method is called instead.

.receiveDragHandler

Sets or gets the object evaluated when a drag&drop operation finishes on this view.

At evaluation, the following arguments will be passed: view, x, y. The drag&drop data is expected to be applied to the view in some way.

If this variable is nil (the default) the view's -defaultReceiveDrag method is called instead.

.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 -beginDragAction or -defaultGetDrag.

Arguments:

A String containing the text to be displayed.

Context Menus

These methods are used to add context menu and shortcut key support to a View.

.setContextMenuActions

Set the MenuActions that should appear in the context menu for this view. This implicitly calls View: -enableContextMenu.

Arguments:

A list of one or more MenuActions. These will be shown when the context menu for this View is invoked by right-clicking. In addition, the shortcut keys for these actions will be active in the context of this View. Calling this method with no actions will remove all context menus.

.enableContextMenu

Enablement of context menu support for this View. If true and actions are attached, a right click will show the context menu. This property can enable and disable context menu support for a View without removing the attached actions.

Arguments:

A Boolean

.insertMenuAction

Insert a MenuAction into the list of attached actions.

Arguments:

action

A MenuAction to add.

addBefore

A MenuAction or integer index value. The action will be inserted before this item in the list. By default, actions are inserted at the end of the list.

.removeMenuAction

Remove a MenuAction from the list of attached actions.

Arguments:

action

A MenuAction to add.

.removeAllMenuActions

Remove all MenuActions from the view.

.enableContextMenu

Enablement of context menu support for this View. If true and actions are attached, a right click will show the context menu. This property can enable and disable context menu support for a View without removing the attached actions.

Arguments:

A Boolean

Other actions and hooks

.focusGainedAction

Sets or gets the object to be evaluated when the view gains the keyboard focus. It is passed the view as an argument.

.focusLostAction

Sets or gets the object to be evaluated when the view looses the keyboard focus. It is passed the view as an argument.

.toFrontAction

Sets or gets the object to be evaluated when the view becomes the active window. It is passed the view as an argument.

.endFrontAction

Sets or gets the object to be evaluated when the view becomes the active window. It is passed the view as an argument.

.onResize

Sets or gets the object to be evaluated when the view changes its size. It is passed the view as an argument.

.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.

.onClose

Sets or gets the object to be evaluated when the view is destroyed (i.e. closed or removed). It is passed the view as an argument.

Handlers

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.

.defaultKeyDownAction

The method called when a key is pressed and -keyDownAction is nil. Subclass it to define your own functionality on key presses.

See Key actions for explanation of arguments.

The return value controls the event propagation to parent view. See Key and mouse event processing for details.

.defaultKeyUpAction

The method called when a key is released and -keyUpAction is nil. Subclass it to define your own functionality on key-release.

See Key actions for explanation of arguments.

The return value controls the event propagation to parent view. See Key and mouse event processing for details.

.keyDown

Handles response to a key press event. First evaluates *globalKeyDownAction.

NOTE: This method directly triggers the action and returns, forwarding the action's return value. See Key actions for detailed explanation.

See Key actions for explanation of arguments.

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.

.keyUp

Handles response to a key release event. Sets -keyTyped to 'char', evaluates *globalKeyUpAction, and then calls -handleKeyUpBubbling.

NOTE: This method directly triggers the action and returns, forwarding the action's return value. See Key actions for detailed explanation.

See Key actions for explanation of arguments.

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.

.keyModifiersChanged

Handles response to a modifier key press or release event. Calls -handleKeyModifiersChangedBubbling.

NOTE: Instead of calling -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 Key actions for explanation of arguments.

.keyTyped

An instance variable containing the key just typed (after it is released).

.mouseDown

Handles response to a mouse button press event. Evaluates -mouseDownAction.

See Mouse actions for explanation of arguments.

.mouseUp

Handles response to a mouse button release event. Evaluates -mouseDownAction.

See Mouse actions for explanation of arguments.

.mouseMove

Handles response to mouse pointer moving after a mouse button has been pressed on the view. Evaluates -mouseMoveAction.

See Mouse actions for explanation of arguments.

.mouseOver

Handles response to mouse pointer moving over the view with no mouse buttons pressed. Evaluates -mouseOverAction.

This method is called only if Window: -acceptsMouseOver of the containing Window (or, -acceptsMouseOver of the top View) is true.

See Mouse actions for explanation of arguments.

.mouseEnter

Handles response to mouse pointer entering the view. Evaluates -mouseEnterAction.

.mouseLeave

Handles response to mouse pointer leaving the view. Evaluates -mouseLeaveAction.

.defaultGetDrag

NOTE: Not yet implemented

The view's default method to determine the content of the drag&drop operation just initiated.

Returns:

The object to be set as *currentDrag. If nil is returned, the drag&drop operation will not begin.

.defaultCanReceiveDrag

NOTE: Not yet implemented

The view's default evaluation whether the content of the ongoing drag&drop operation can be accepted.

Returns:

A Boolean stating whether *currentDrag is useful. If false is returned, the drop will not be handled by this view.

.defaultReceiveDrag

NOTE: Not yet implemented

The view's default handling of the data dropped on it (stored in *currentDrag).

.beginDrag

Handles initiation of a drag&drop operation. Evaluates -beginDragAction or calls -defaultGetDrag if the former is nil, then stores the object returned into *currentDrag, and the object interpreted as "compile string" into *currentDragString. Returns whether *currentDrag is not nil.

Arguments:

x

Current horizontal position of the mouse pointer.

y

Current vertical position of the mouse pointer.

Returns:

A Boolean stating whether the drag&drop operation shall begin.

.canReceiveDrag

Handles evaluation whether the view can accept the current drag&drop data. Evaluates -canReceiveDragHandler or calls -defaultCanReceiveDrag if the former is nil, then forwards the return value.

Arguments:

x

Current horizontal position of the mouse pointer.

y

Current vertical position of the mouse pointer.

Returns:

A Boolean stating whether the current drag&drop content can be dropped on the view.

.receiveDrag

Handles the end of the drag&drop operation. Evaluates -receiveDragHandler or calls -defaultReceiveDrag if the former is nil, then sets *currentDrag and *currentDragString to nil.

Arguments:

x

Current horizontal position of the mouse pointer.

y

Current vertical position of the mouse pointer.

Inherited instance methods