View (class)
public View {inherits GuiRangeSelectionContext, RootFrame}
Import from: CURL.GUI.STANDARD. Defined in package CURL.GUI.BASE.
Direct Known Subclasses: OutlineOnlyView

Represents a Curl window on the screen, containing Curl graphical content.

Description

Every graphic hierarchy that is intended for display has a View object at its root. Because each View is attached to a window, all window-related operations performed on the View (such as moving or closing it) are actually performed on the window.

View inherits from Frame and therefore, like a Frame, can have no more than one graphical child. Typically, you specify its graphical child as an argument when you create the View.

The following lists the often used View methods:

Notes

If you create a View object and do not call View.show method on it, then you should call the View.destroy method on it, if you no longer want this object. Otherwise this object will be destroyed only when the Applet that created it is destroyed.

This object can be styled by writing style rules for "View".

Expected Events

WindowClose: Fired when close is invoked or when the user attempts to close the View (e.g., by clicking on the x button at the top right corner).
ViewMoveEvent: Fired when the View moves from its current position.
ViewResizeEvent: Fired when the View is resized.
ViewVisibilityEvent: Fired when the View's visibility changes.
DestroyNotify: Fired just after the View has been destroyed.


ViewActivateEvent: Fired when the View becomes active.
ViewDeactivateEvent: Fired when the View becomes inactive.

Example

The operations described above are illustrated in the following example. Note that you should begin by showing the View, and once you destroy it, no more commands can act on it.

For example, the View.title operation would cause an error if called on a previously destroyed window, so it is wise to check that View.destroyed? is false before calling it.


Example
{let v:View =
    {View
        {VBox
            {text Creating Views is fairly easy,},
            {text if you follow a few simple rules.},
            {italic This example illustrates them.}}}}
{HBox
    spacing=3pt,
    {CommandButton label="Show",
        {on Action do
            {if (not v.destroyed?) then
                {v.show}
            }}},
    {CommandButton label="Hide",
        {on Action do
            {if (not v.destroyed?) then
                {v.hide}}}},
    {CommandButton label="Destroy",
        {on Action do
            {if (not v.destroyed?) then
                {v.destroy}
            }}},
    {CommandButton label="Move",
        {on Action do
            {if (not v.destroyed?) then
                {v.set-position 3*72pt, 2*72pt}
            }}},
    {CommandButton label="New Title",
        {on Action do
            {if (not v.destroyed?) then
                set v.title = "Retitled Window"
            }}}
}


When the contents of a View change, the View does not automatically resize itself. To change the size of a View so that it matches the preferred size of its contents, use View.set-size-from-child:


Example
{value
    let hb:HBox =
        {HBox spacing=3pt, {RectangleGraphic width=18pt, height=36pt}}
    let vb:VBox = {VBox hb}
    let v:#View
    {HBox
        spacing=3pt,
        {CommandButton label="Create and Show View",
            {on Action at cb:CommandButton do
                set v = {View vb,
                            {on WindowClose do
                                set cb.enabled? = true
                            }
                        }
                set cb.enabled? = false
                {v.show}
            }},
        {CommandButton label="Add Words",
            {on Action do
                {hb.add "Hello!"}
                {vb.add "Goodbye!"}
            }},
        {CommandButton label="Resize",
            {on Action do
                {v.set-size-from-child}
            }}}
}

Visual Testing

The visual test type of a View depends on how it was created. If the View is owned by another View, the visual test type is CurlDialog; otherwise, it is CurlView. The actions and properties for these visual test types are identical.

In addition to the default visual test actions supported by all Visuals, objects of this class support the following actions:

action arguments description
Close <none> Closes the window.
Maximize <none> Maximizes the window to fill the entire screen.
Minimize <none> Minimizes the window to an icon.
Restore <none> Restores the window to its previous size.
Move x:int, y:int Moves the window to the absolute pixel position (x, y) on the screen.
Resize width:int, height:int Resizes the window to width width and height height, in pixels.


In addition to the default visual test properties supported by all Visuals, objects of this class support the following visual test properties:

property description
maximizable:bool Indicates whether the window can be maximized.
maximized:bool Indicates whether the window is maximized.
minimizable:bool Indicates whether the window can be minimized.
minimized:bool Indicates whether the window is minimized.
resizable:bool Indicates whether the window can be resized.
title:String The window's title.

Constructors
default:Initializes a View.
constructor public {View.default
owner:#View = {View.get-default-owner},
center?:bool = false,
resizable?:bool = true,
decorations?:bool = true,
takes-focus?:bool = true,
standard-accelerators?:bool = true,
range-selection-ui-enabled?:bool = true,
title:StringInterface = "",
visibility:WINDOW.WindowVisibility = WINDOW.WindowVisibility.hidden,
...
}

Properties
active?:Returns true if the Window associated with this View is an active window.
accessor public final View.active?:bool
destroyed?:Indicates whether the View has been destroyed.
accessor public final View.destroyed?:bool
height:Controls the height of a View.
local option public View.height:any
mac-menu-bar:The BaseMenuBar for a top level View on a MAC platform.
accessor public View.mac-menu-bar:#BaseMenuBar
setter public View.mac-menu-bar:#BaseMenuBar
style-element:The "element" or "type" of this Visual, for the purpose of styling.
accessor public View.style-element:String
test-description:The name the visual testing infrastructure should use to describe this object, so that the end user may locate it visually.
accessor public View.test-description:#String
test-type-name:The type name that the visual testing infrastructure should use for mapping this object to test methods and properties.
accessor public View.test-type-name:String
title:Gets or sets the title of a View.
accessor public View.title:String
setter public View.title:StringInterface
touch-input-mode:Whether finer-grained touch input is enabled for this View, and in what manner.
accessor public View.touch-input-mode:TouchInputMode
visibility:Gets or sets the visibility of the window associated with this View.
accessor public View.visibility:WINDOW.WindowVisibility
setter public View.visibility:WINDOW.WindowVisibility
width:Controls the width of a View.
local option public View.width:any
window-enabled?:Returns true if the Window associated with this View is able to receive input.
accessor public final View.window-enabled?:bool
Properties inherited from GuiRangeSelectionContext: container, range-selection-ui-enabled?, selection
Properties inherited from RootFrame: background, bounds, cached-background, changing-size?, option-parent, pref-option-parent, x, y
Properties inherited from ContainerDragScroller: ctrl-mode?, dragscrolling?, inner-scroll-buffer
Properties inherited from OptionListInterface: option-register-proc, options-present-here, registered-option-keys
Properties inherited from Frame: clonable-class?, halign, halign-spec, hstretch?, hstretch?-spec, valign, valign-spec, vstretch?, vstretch?-spec
Properties inherited from SelectionContext: can-redo?, can-undo?, selection-context-active?
Properties inherited from BaseFrame: child, completely-clonable-children?, graphical-children, ordered-children, reverse-ordered-children, width-first?
Properties inherited from CommandContext: commands
Properties inherited from EventTarget: event-handlers
Properties inherited from GetBoundsBox: layout-locally-valid?, layout-valid?
Properties inherited from Box: clip-child-shadows?
Properties inherited from Graphic: avoid-page-break?, border-color, border-spec, border-style, border-width, cell-border-spec, cell-border-width, cell-margin, discrete-select-in-range?, display-context, enabled?, graphic-selectable, horigin, is-paginating?, layout, margin, opaque-to-events?, outside-margin, pagination-state, parent, possibly-displayed?, selection-context, shadow-color, shadow-spec, visible?, visual-parent, vorigin
Properties inherited from Visual: _style-element, cursor, data-source, dragee, font-size, graphical-parent, has-key-focus?, input-method-enabled?, input-method-keyboard-mode, name, options, style-class, style-manager, style-options, test-child?, test-name, test-parent?, test-visible?, tooltip, user-data
Properties inherited from DataBindingTarget: data-binding-context, data-bindings

Class Variables and Constants
default-context-menu-for-text-field-proc:A procedure that can be used to create a context menu for a TextField.
public View.default-context-menu-for-text-field-proc:#{proc-type {view:View}:BaseMenuPane }
default-context-menu-for-view-proc:A procedure that can be used to create a context menu for the View.
public View.default-context-menu-for-view-proc:#{proc-type {view:View}:BaseMenuPane }

Methods
add:Add a child item to a Frame.
public {View.add g:any, ...}:#Visual
attempt-revalidate-layout:Determine whether there is any change in a Graphic's layout preferences since the most recently completed layout negotiation.
public {View.attempt-revalidate-layout lc:LayoutContext}:bool
center-view:Moves the View so that it is centered with respect to the client area of another View.
public {View.center-view
reference-view:#View = {View.get-default-owner}
}:void
change-height:Handle a change in the height specification.
protected {View.change-height hspec:any}:void
change-width:Handle a change in the width specification.
protected {View.change-width wspec:any}:void
close:Closes the View gracefully.
public {View.close}:void
destroy:Permanently destroys the View.
public {View.destroy}:void
dispatch-event-to-contents:Used by the GuiManager to fire a GuiWindowEvent in a chosen View.
public {View.dispatch-event-to-contents e-in:Object}:void
draw:Draw this object's visual representation.
public {View.draw renderer2d:Renderer2d}:void
find-test-children:Accumulates the test children based on a filter.
public {View.find-test-children
children:{Array-of Visual},
filter:{proc-type {Visual}:bool}
}:void
get-position:Gets the position of this View relative to its view parent.
public {View.get-position}:(x:Distance, y:Distance)
get-position-in-display:Gets the position of this View, relative to the upper-left corner of the display.
public {View.get-position-in-display}:(Distance, Distance)
get-size:Gets the width and height of this View.
public {View.get-size}:(w:Distance, h:Distance)
get-test-parent:Returns the visual ancestor that is also a test parent.
public {View.get-test-parent}:#Visual
get-test-property:Returns a test property value for this object.
public {View.get-test-property name:String}:any
get-visibility:Get the visibility of the window associated with this View.
deprecated public {View.get-visibility}:WINDOW.WindowVisibility
get-window-position:Gets the position of this View relative to its view parent.
public {View.get-window-position}:(x:Distance, y:Distance)
get-window-position-and-size:Gets the width, height and the position of the View.
public {View.get-window-position-and-size
}:(x:Distance, y:Distance, width:Distance, height:Distance)
get-window-size:Gets the width and height of this View.
public {View.get-window-size}:(w:Distance, h:Distance)
hide:Makes the View invisible without destroying it.
public {View.hide}:void
lower:Moves the View to the bottom of the windows stack.
public {View.lower}:void
on-cancel-mode:Handle CancelMode events.
public {View.on-cancel-mode e:CancelMode}:void
on-context-menu-event:The static event handler for ContextMenuEvent events.
public {View.on-context-menu-event e:ContextMenuEvent}:void
on-pointer-crossing:The static event handler for PointerCrossing events.
public {View.on-pointer-crossing e:PointerCrossing}:void
on-window-close:The static event handler for WindowClose events.
public {View.on-window-close e:WindowClose}:void
prepare-test-parent:Prepares this object as a test parent.
public {View.prepare-test-parent}:bool
propagate-request-layout:Propagate a request for a new layout negotiation from a Box to its graphical parent, if any.
public {View.propagate-request-layout epoch:int}:void
raise:Moves the View to the top of the windows stack.
public {View.raise}:void
request-draw-rect-in-root:Requests a repaint operation for an area described by a GRect that is already in the coordinate system of the RootFrame.
public {View.request-draw-rect-in-root rect:GRect}:void
request-pointer-trace:Declare that the geometry of displayed objects may have changed and request that any needed PointerCrossing events be fired.
public {View.request-pointer-trace}:void
set-icon:Sets an icon in a View.
public {View.set-icon
large-icon:Pixmap,
small-icon-if-used:#Pixmap
}:void
set-opacity:Sets the opacity of the View.
public sealed {View.set-opacity opacity:double}:void
set-position:Sets the position of a View, relative to its view parent.
public {View.set-position x:Distance, y:Distance}:void
set-rendering-mode:Change the type of Renderer2d used to draw this View.
public {View.set-rendering-mode rendering-mode:RenderingMode}:bool
set-title:Sets the title in this View's title bar.
public final {View.set-title caption:StringInterface}:void
set-topmost:Sets or unsets this View as a topmost window.
public {View.set-topmost topmost?:bool}:void
set-touch-input-mode:Set the touch input mode for this View.
public {View.set-touch-input-mode mode:TouchInputMode}:bool
set-view-size:Updates the View's data structures to be consistent with the new size specified, which is measured in pixels.
protected {View.set-view-size new-width:int, new-height:int}:void
set-view-size-options:Synchronizes the View's size options and assumed Window size.
protected {View.set-view-size-options
new-width-in-pixels:int,
new-height-in-pixels:int
}:(width:Distance, height:Distance)
set-window-position:Sets the position of a View, relative to its view parent.
public {View.set-window-position x:Distance, y:Distance}:void
set-window-position-and-size:Sets the width, height and the position of the View.
public {View.set-window-position-and-size
x:Distance,
y:Distance,
width:Distance,
height:Distance
}:void
set-window-shape:Changes the shape of this View to the shape represented by region.
public {View.set-window-shape shape:#Region}:void
set-window-size:Resizes the View.
public {View.set-window-size width:Distance, height:Distance}:void
show:Displays the View.
public {View.show
force-on-display?:bool = true,
center?:bool = false
}:void
test-run:Performs a visual testing action on an object.
public {View.test-run action:String, args:FastArray}:any
touch-input-mode-supported?:Whether a particular TouchInputMode is supported for this View.
public {View.touch-input-mode-supported? mode:TouchInputMode}:bool
update:Updates the View immediately by doing exactly what the repaint event handler does.
public {View.update}:void
Methods inherited from GuiRangeSelectionContext: create-command, note-dragscroll-continued, note-dragscroll-started, note-selection-context-activated, note-selection-context-deactivated, on-drag-started, on-pointer-press, on-pointer-release, overdraw-selected-leaf, overdraw-selection, select, select-all, select-nothing
Methods inherited from RootFrame: compute-default-bounds, compute-default-bounds-recur, compute-initial-size, fire-event-in-envelope, get-bounds, get-elastic-bounds-into, get-layout-context, get-nonparent-bounds-into, get-top-left-in-ancestor, get-visible-bounds-into, get-visible-rect-in-root-into, request-draw, request-draw-rect, set-layout, set-size-from-child, validate-layout, validate-layout-recur
Methods inherited from ContainerDragScroller: note-dragscroll-ended, on-grab-release, on-pointer-motion, start-dragscroll
Methods inherited from OptionListInterface: add-option, add-style-option, change-option-parent-notify, clone-options, get-option, get-option-by-name, keyword-init-arg, local-add-notify, local-remove-notify, name-to-option-key, new-option-item, option-change-notify, option-lookup, option-lookup-here, option-propagate-notify, option-set?, propagate-option-change, remove-option, remove-style-option, remove-styles, set-option-by-name, set-style-option-by-name, unset-option-by-name, unset-style-option-by-name
Methods inherited from Frame: clone-appearance-helper, remove-child
Methods inherited from SelectionContext: on-selection-changed, redo, selection-context-request-activate, undo
Methods inherited from GuiEventTarget: handle-delegate-event, handle-event, on-action, on-command-changed, on-commit, on-composition-change-event, on-composition-result-event, on-current-record-change-request, on-current-record-changed, on-destroy-notify, on-destroy-requested, on-drag-over, on-drag-pointer, on-drop, on-end-composition-event, on-focus-event, on-focus-in, on-focus-out, on-gesture, on-gesture-begin, on-gesture-end, on-gesture-magnify, on-gesture-pan, on-gesture-rotate, on-gesture-swipe, on-gesture-tap, on-gesture-touch, on-gui-event, on-input-method-event, on-key-event, on-key-press, on-pointer-button, on-pointer-event, on-pointer-scroll, on-raw-key-event, on-raw-key-press, on-raw-key-release, on-reset, on-selectable-added, on-selectable-removed, on-selection-context-activated, on-selection-context-deactivated, on-selection-event, on-start-composition-event, on-start-event, on-stop-event, on-view-activate, on-view-deactivate, remove-event-handlers-for-event-class
Methods inherited from InitRestArgParser: process-rest-args
Methods inherited from BaseFrame: add-internal, after-reposition, allocate-layout-object, before-reposition, compute-child-bounds, compute-parent-elastic, constrain-height, constrain-width, end-pagination, get-height-preference, get-text, get-width-preference, install-child-bounds, internal-remove-child, note-attached, note-detaching, notify-option-children, paginate, pick-child, register-options, set-size
Methods inherited from CommandContext: add-command, command-enabled?, command-supported?, do-command, get-command, request-update-commands
Methods inherited from EventTarget: accepts-event-class?, add-event-handler, event-handler-present?, remove-event-handler, verify-event
Methods inherited from BasicBox: contains-point?, find-graphic-at, handle-crossing, on-pointer-envelope-event, pointer-enter-occurred, pointer-leave-occurred
Methods inherited from BasicEventTarget: enqueue-event
Methods inherited from GetBoundsBox: request-layout
Methods inherited from Box: clear, compare-children, get-delimited-child-text-selection, get-gui-path-to-child, get-range-as-selected-text, graphical-child-visible-at, make-gui-mark, search-next-here, search-prev-here
Methods inherited from Graphic: create-pagination-state, detach, draw-range-as-selected, draw-shadow, find-ancestor, find-graphical-ancestor, fire-inferior-crossing-event, get-graphical-root, get-gui-path, get-origin-in-graphical-ancestor, get-origin-in-root, get-pagination-state, on-drag-enter, on-inspection, on-pointer-enter, option-changed, paint-with-decorations, replace-with, search-next, search-prev, start-pagination, xy-offset-to
Methods inherited from Visual: add-from-init-args, animate, change-cursor, clonable-appearance?, clone-appearance, get-focus-manager, get-view, maybe-fire-attach-event, maybe-fire-detach-event, non-keyword-init-arg, note-caret-position, on-drag-leave, on-pointer-leave, pop-cursor, prepare-test-object, push-cursor, quantize-width, refresh-style-options, release-key-focus, request-key-focus, scroll-to-include, test-record, transform-from-display-coordinates, transform-from-graphical-root-coordinates, transform-to-display-coordinates, transform-to-graphical-root-coordinates
Methods inherited from GraphicOptions: any-to-Distance, get-display-context
Methods inherited from DataBindingTarget: add-data-binding, get-data-binding, refresh-data-binding, remove-data-binding, unset-property, update-data-binding, validate-data-binding
Methods inherited from Object: object-describe, object-describe-for-debugging, object-serialize



Constructor Details
default (constructor)
public {View.default
owner:#View = {View.get-default-owner},
center?:bool = false,
resizable?:bool = true,
decorations?:bool = true,
takes-focus?:bool = true,
standard-accelerators?:bool = true,
range-selection-ui-enabled?:bool = true,
title:StringInterface = "",
visibility:WINDOW.WindowVisibility = WINDOW.WindowVisibility.hidden,
...
}

Initializes a View.

owner: Specifies the owner View of the newly created View.

If owner is not specified, the GuiManager chooses a default owner if possible.

Use null if the View should have no owner.

If a View is owned by another View it changes the behavior of certain operations. For example, if the owner View is destroyed using View.destroy, all of its owned Views will also be destroyed. An owned View cannot be placed behind its owner and does not show up in the task bar.
center?: Specifies whether this View should be positioned so that it is centered over its owner View, if any. The default value does not cause centering.

If owner is null, the View is centered in the upper two-thirds of the screen.
resizable?: If decorations? and takes-focus? are false then this flag is ignored and the resulting View cannot be resized by user actions.

If true, the resulting View can be resized, else the resulting View cannot be resized by user actions. By default this value is set to true.
standard-accelerators?: If true, the standard accelerators are added to this View's accelerator table. The standard accelerators include cut (Ctrl+X), copy (Ctrl+C), paste (Ctrl+V), select all (Ctrl+A), and find (Ctrl+F). On the Mac, Ctrl is replaced by Command (see StateMask).
decorations?: Specify decorations? = false to create a View with no title bar or borders around the edges of the window.

There are restrictions on a decorationless view that is brought up by an unprivileged applet. These are:

takes-focus?: Specifies if the View should take focus or not. This flag is ignored if decorations? is true.
title: Title of the View.
visibility: The WindowVisibility of the View.

For an unprivileged decorationless applet, setting the visibility to WindowVisibility.maximized will be equivalent of setting the window visibility to WindowVisibility.normal.
range-selection-ui-enabled?: Provides the initial value for GuiRangeSelectionContext.range-selection-ui-enabled?.

Notes

If the width or height of the view being constructed is less than the minimum width or height of a window on the host, then the view will be constructed using the host's minimum width or height. In this case, if the center? argument is true, then the view may not be centered properly.

Additional rest arguments may include:


Property Details
active? (accessor)
accessor public final View.active?:bool

Returns true if the Window associated with this View is an active window.

Notes

A top level Window is active when it has the host keyboard focus. A child Window is active if either it has the host keyboard focus or one of the children of its top level window has the host keyboard focus.
Introduced in: version 7.0

destroyed? (accessor)
accessor public final View.destroyed?:bool

Indicates whether the View has been destroyed.

Description

A destroyed View still exists as an object, but its associated window is no longer valid. Any operations on the View that would involve its window (e.g., get-position-in-display) will result in an error.

Notes

Under some circumstances, the operating system may destroy a window without sending a WindowClose event. The DestroyNotify event will be sent however, and destroyed? will be true. Consequently, it is wise to check the destroyed? flag before operating on a View when the cause for the operation was external to the View. (E.g., a Timer, a PointerPress on an object in a different View, etc.)

height (local option)
public View.height:any

Controls the height of a View.

Description

This option is analogous to View.width. See the documentation of View.width for further information.

mac-menu-bar (accessor)
accessor public View.mac-menu-bar:#BaseMenuBar
setter public View.mac-menu-bar:#BaseMenuBar

The BaseMenuBar for a top level View on a MAC platform.

Introduced in: version 6.0

style-element (accessor)
accessor public View.style-element:String

The "element" or "type" of this Visual, for the purpose of styling.

Description

This implementation returns the value of Visual._style-element but is normally overridden to return a constant value.

Overriding

If a subclass of Visual should be stylable separately from other types of objects, this getter should be overridden to return an appropriate string. By convention, this string is the name of the class or the name of the markup that produces the object.

An override must return self._style-element if it is not the empty string.
Introduced in: version 6.0

test-description (accessor)
accessor public View.test-description:#String

The name the visual testing infrastructure should use to describe this object, so that the end user may locate it visually.

Description

This is the value that should appear in the user interface of testing tools that drive the visual testing infrastructure.

By default, this value is obtained by locating the Label, if any, that likely refers to this object. Objects that have a natural description of their own should override this method. For example, CommandButton contains an internal Label, so it returns its Label's value.

Also see test-name.

test-type-name (accessor)
accessor public View.test-type-name:String

The type name that the visual testing infrastructure should use for mapping this object to test methods and properties.

Description

The test type must be one of the types in the following list for the visual testing to operate correctly. Read the documentation for the test-run and get-test-property methods on the listed example implementations to learn about that particular test type.

If one of the predefined test types closely matches the semantics of your object, consider using it as your object's test type. However, it may be simpler to merely add additional test actions and properties to your object without changing its test type.


title (accessor)
accessor public View.title:String
setter public View.title:StringInterface

Gets or sets the title of a View.


touch-input-mode (accessor)
accessor public View.touch-input-mode:TouchInputMode

Whether finer-grained touch input is enabled for this View, and in what manner.

Description

This property represents whether it is possible to receive individual touch contact point information for this View.

Notes

See TouchInputMode for more information.
Introduced in: version 8.0

visibility (accessor)
accessor public View.visibility:WINDOW.WindowVisibility
setter public View.visibility:WINDOW.WindowVisibility

Gets or sets the visibility of the window associated with this View.

Description

See WindowVisibility for more information.

Notes

Some window managers do not support all the WindowVisibility options. For example, setting the visibility of an owned View to WindowVisibility.minimized is a no op in some window managers.

For a top level decorationless View in an unprivileged applet, setting the visibility to WindowVisibility.maximized will be equivalent of setting the window visibility to WindowVisibility.normal.

width (local option)
public View.width:any

Controls the width of a View.

Description

The value of this option must be a Quantity or a number; in the latter case the value is interpreted as specifying a width in units of points (1/72 inch). This option may be specified in the argument list when a View is created, in which case it will control the initial width of the window. It may also be set to a new value later, which will cause the window to change size, as shown in the following example:


Example
{value
    let w:Distance = 3in
    let h:Distance = 2in
    let v:View =
        {View width=w, height=h, {RectangleGraphic width=1in, height=1in}}
    {HBox
        spacing=3pt,
        {CommandButton label="Show View",
            {on Action do
                {v.show}
            }},
        {CommandButton label="Wider",
            {on Action do
                set w = w + 1in
                set v.width = w
            }},
        {CommandButton label="Taller",
            {on Action do
                set h = h + 1in
                set v.height = h
            }}}
}

window-enabled? (accessor)
accessor public final View.window-enabled?:bool

Returns true if the Window associated with this View is able to receive input.

Notes

See Window.disable-window and Window.enable-window for more information.


Class Variable and Constant Details
default-context-menu-for-text-field-proc (class variable)
public View.default-context-menu-for-text-field-proc:#{proc-type {view:View}:BaseMenuPane }

A procedure that can be used to create a context menu for a TextField.

Introduced in: version 6.0

default-context-menu-for-view-proc (class variable)
public View.default-context-menu-for-view-proc:#{proc-type {view:View}:BaseMenuPane }

A procedure that can be used to create a context menu for the View.

Introduced in: version 6.0



Method Details
add (method)
public {View.add g:any, ...}:#Visual

Add a child item to a Frame.

g: the item to add. If g is not already a Graphic, g will be coerced to a Graphic and the result of that coercion will be added.

Notes

Frame.add also has a keyword parameter replace?. If replace? is true, then the Frame's previous child, if any, will be replaced by g. If replace? is false, which is the default, then it is an error to attempt to invoke this method on a Frame that already has a child.

Returns

The actual value, whose type is a subtype of Graphic, that was added.

Overriding

May be overridden in subclasses of Frame so that additional processing can be associated with the addition of a child. Any such overriding method should invoke

{super.add g, ...}

to invoke the addition actions of Frame itself and pass along the replace? argument, if supplied.

attempt-revalidate-layout (method)
public {View.attempt-revalidate-layout lc:LayoutContext}:bool

Determine whether there is any change in a Graphic's layout preferences since the most recently completed layout negotiation.

lc: the LayoutContext in effect for this layout negotiation.

Returns

a bool that is true if there has been no change in this object's layout preferences. If the value is false, then there may or may not have been changes and a layout negotiation will be required to find out.

Notes

This method should only be invoked on an object that has previously been through a complete layout negotiation; in other words, a negotiation that culminated in an invocation of Graphic.set-size. A return of true by this method is a warranty that, if the same height and width preference questions asked during the most recent complete layout negotiation were repeated, the object would return answers equal (as computed by OriginElastic.equal?) to the previously returned answers.

Perhaps the most common case in which an object can easily return true from this method is when nothing has happened at the object to invalidate the results of the previous layout computations. Another common way to return true from this method, for an object that is a Box, is to invoke Graphic.attempt-revalidate-layout on all of the Box's children, and return true if every one of these invocations returned true. (This strategy is valid if the Box's preferences depend only on the Box's children's preferences and on other parameters that are known not to have changed.)

If this method returns true and this object's parent has no reason to change this object's bounds, then it is possible that the parent will make no further layout-negotiation calls on this object. Therefore, if this object is keeping track of whether its layout is considered to be valid, it should set itself to the layout-valid state before returning true from this method.

Programming Notes

This method is typically invoked by the Box.attempt-revalidate-layout method of this object's parent Box, as a quick first check to decide whether the previous layout preferences obtained from this object are still valid without triggering extensive computations.

Overriding

The default method Graphic.attempt-revalidate-layout just returns false, which is always a safe answer. Subclasses of Graphic that can provide more precise answers are encouraged to override this method with a method that returns true in as many situations as possible in which the layout preferences have not, in fact, changed.

center-view (method)
public {View.center-view
reference-view:#View = {View.get-default-owner}
}:void

Moves the View so that it is centered with respect to the client area of another View.

reference-view: The other View on which this one should be centered. If this is null, the View is centered in the upper two-thirds of the display the window is currently in.

If reference-view is not specified, the GuiManager chooses a default View if possible.

change-height (method)
protected {View.change-height hspec:any}:void

Handle a change in the height specification.

hspec: The new height specification

Programming Notes

This method is called from the RootFrame.height option change handler. Users should not normally need to call this directly.

Overriding

Subclasses should generally call super.change-height in their override.

change-width (method)
protected {View.change-width wspec:any}:void

Handle a change in the width specification.

wspec: The new width specification

Programming Notes

This method is called from the RootFrame.width option change handler. Users should not normally need to call this directly.

Overriding

Subclasses should generally call super.change-width in their override.

close (method)
public {View.close}:void

Closes the View gracefully.

Description

This method is invoked when a user attempts to close a window using a window-manager decoration such as the "x" button that many windows display. It causes a WindowClose event to fire at this View. You can invoke this method to mimic the behavior of pressing the "x" button.

View's default handler for WindowClose destroys the View by calling View.destroy.

If you want to alter the way a View closes, for example, if you want to hide the window (using View.hide) rather than destroy it, you can: In so doing, the View will not perform its normal close behavior, which includes destroying itself.

Overriding

It is not generally wise to override this method. To intercept window-close requests, a better alternative is to add an event handler for the WindowClose event that this method fires.

destroy (method)
public {View.destroy}:void

Permanently destroys the View.

Notes

See destroyed? for more information.

dispatch-event-to-contents (method)
public {View.dispatch-event-to-contents e-in:Object}:void

Used by the GuiManager to fire a GuiWindowEvent in a chosen View.

e-in: the event to fire.

Notes

For the GuiInputEvents the event coordinates in e (see GuiInputEvent.x and GuiInputEvent.y) should be relative to the top left corner of the client area in the target View. This method will adjust the event coordinates to be relative to the origin of the View, and will then invoke GuiEventTarget.handle-event to handle the GuiEvent fired at the View. The original contents of the event's coordinates fields are restored before View.dispatch-event-to-contents returns.

If the event is a PointerEvent, it is fired inside a PointerEnvelopeEvent so that the usual protocol for forwarding the event down the graphic hierarchy will be followed.

Programming Notes

This method is provided for use by several methods of GuiManager e.g. GuiManager.on-pointer-motion.

The method is not generally intended to for other uses, although it can be invoked from elsewhere if it would be useful to do so.
Introduced in: version 6.0

draw (method)
public {View.draw renderer2d:Renderer2d}:void

Draw this object's visual representation.

renderer2d: The Renderer2d that this object should use to draw itself.

Notes

In an unprivileged applet, a View that has no decorations has a 1 pixel raised border, which is drawn inside the client area of the View. This border is drawn after the contents of the View have been drawn.

find-test-children (method)
public {View.find-test-children
children:{Array-of Visual},
filter:{proc-type {Visual}:bool}
}:void

Accumulates the test children based on a filter.

children: An array. Test children that pass the filter will be added to this array.
filter: A procedure that takes a potential test child as an argument and returns a boolean indicating whether or not the child should be accepted.

Notes

An object is a test child if it is a test object (because it has a non-null test-name or test-type-name) or it is a test parent (because test-parent? is true).

A test child must also be visible. Implementations should not search within objects for which Visual.test-visible? or Graphic.visible? are false.

get-position (method)
public {View.get-position}:(x:Distance, y:Distance)

Gets the position of this View relative to its view parent.

Returns

The x and y offsets from the upper-left corner of its view parent to its upper-left corner.

Notes

This method is going to be deprecated in the future. Use View.get-window-position instead.

get-position-in-display (method)
public {View.get-position-in-display}:(Distance, Distance)

Gets the position of this View, relative to the upper-left corner of the display.

Description

On X windows, this method currently returns the location of the upper left-hand corner of the client area (the rectangular area in the window excluding the window's title and frame) because the coordinates of the window's upper-left corner are not available.

Returns

The x and y offsets from the upper-left corner of the display to the View's upper-left corner.

get-size (method)
public {View.get-size}:(w:Distance, h:Distance)

Gets the width and height of this View.

Returns

The width and height of this View.

Notes

This method will be deprecated in the future. Use View.get-window-size instead.

get-test-parent (method)
public {View.get-test-parent}:#Visual

Returns the visual ancestor that is also a test parent.

Notes

An object is a test parent if test-parent? is true.

Overriding

Not normally overridden.

get-test-property (method)
public {View.get-test-property name:String}:any

Returns a test property value for this object.

Description

The default implementation uses reflection to obtain the value of runtime properties of the object. Subclasses only need to override this method when a property is to be added to the testing environment but not the runtime interface.

Notes

See also: canonical-test-value.

get-visibility (method)
deprecated public {View.get-visibility}:WINDOW.WindowVisibility

Get the visibility of the window associated with this View.

Description

See WindowVisibility for more information.

Deprecated

Use the View.visibility getter instead.

get-window-position (method)
public {View.get-window-position}:(x:Distance, y:Distance)

Gets the position of this View relative to its view parent.

Description

If the View does not have a view parent, this method returns the View's position relative to the upper-left corner of the display.

On X windows, this method currently returns the coordinates of the upper left-hand corner of the client area because the coordinates of the window's upper-left corner are not available. The client area is the rectangular area in the window excluding the window's title and frame.

Returns

The x and y offsets from the upper-left corner of its view parent to its upper-left corner.

get-window-position-and-size (method)
public {View.get-window-position-and-size
}:(x:Distance, y:Distance, width:Distance, height:Distance)

Gets the width, height and the position of the View.

Notes

Use this when both the position and size are needed. This may be faster than calling View.get-window-position and View.get-window-size methods.

get-window-size (method)
public {View.get-window-size}:(w:Distance, h:Distance)

Gets the width and height of this View.

Returns

The width and height of this View.

hide (method)
public {View.hide}:void

Makes the View invisible without destroying it.


lower (method)
public {View.lower}:void

Moves the View to the bottom of the windows stack.

Description

If the View is not designated as a topmost window (from calling View.set-topmost), it is moved to the bottom of all windows; if it is a topmost window, the View is moved to the bottom of the topmost windows only.

Notes

See Also: View.raise.

on-cancel-mode (method)
public {View.on-cancel-mode e:CancelMode}:void

Handle CancelMode events.

e: The CancelMode event sent to this View.

Description

The default handler on View calls GuiManager.on-cancel-mode.
Introduced in: version 6.0

on-context-menu-event (method)
public {View.on-context-menu-event e:ContextMenuEvent}:void

The static event handler for ContextMenuEvent events.

Description

See GuiEventTarget.on-pointer-event for general information about static event handlers.

on-pointer-crossing (method)
public {View.on-pointer-crossing e:PointerCrossing}:void

The static event handler for PointerCrossing events.

Description

See GuiEventTarget.on-pointer-event for general information about static event handlers.

on-window-close (method)
public {View.on-window-close e:WindowClose}:void

The static event handler for WindowClose events.

Description

See GuiEventTarget.on-pointer-event for general information about static event handlers.

Overriding

The default method GuiEventTarget.on-window-close does nothing. This method is overridden by View.on-window-close, which destroys the View on which it is invoked unless the WindowClose event has been consumed before it gets to View.on-window-close. Accordingly, to intercept window-close gestures and provide an alternate to the standard treatment (for example, invoke View.hide rather than View.destroy), you should provide a static or dynamic event handler that consumes the event and runs before View.on-window-close.

prepare-test-parent (method)
public {View.prepare-test-parent}:bool

Prepares this object as a test parent.

Description

Before the visual testing infrastructure calls prepare-test-object on a test object, prepare-test-parent is called on each ancestor for which test-parent? is true.

Overriding

An overriding method must call {super.prepare-test-parent} at the start of its implementation.

propagate-request-layout (method)
public {View.propagate-request-layout epoch:int}:void

Propagate a request for a new layout negotiation from a Box to its graphical parent, if any.

epoch: the layout epoch that is associated with this layout invalidation. Typically this will be the current layout epoch, accessed using get-layout-epoch.

Programming Notes

This method is normally invoked either from Box.request-layout, to propagate a layout request to a Box's parent, or from Layout.request-layout.

Invocation of this method on a Box indicates that one of the Box's graphical descendants has requested a new layout negotiation. This situation contrasts with an invocation of Box.request-layout on the Box, which means that the Box itself has requested a new layout negotiation. These two separate methods are provided because they warrant different actions when Graphic.attempt-revalidate-layout is invoked early in the ensuing layout negotiation. If this Box was notified of the layout request by an invocation of Box.propagate-request-layout, then nothing has changed at the Box itself, and accordingly the Box can answer true to Graphic.attempt-revalidate-layout any time that all of the Box's children answer true when their Graphic.attempt-revalidate-layout methods are invoked. However, if Box.request-layout was invoked, the Box may not be able to revalidate its layout even if all of its children have revalidated theirs because there may have been some change in the structure of the Box itself, such as the gain or loss of graphical children or a change in the spacing or arrangement of those children.

Overriding

This method may be overridden in Box subclasses that maintain bookkeeping information to track layout invalidations. All such overriding methods should include an invocation of super.propagate-request-layout. This method is also overridden in classes such as View that are designed to serve as the root of graphic hierarchies. In this case, the method is overridden by code that notes the layout request and arranges for a new layout negotiation to occur.

raise (method)
public {View.raise}:void

Moves the View to the top of the windows stack.

Description

If the View is not designated as a topmost window (from calling View.set-topmost), it is raised to the top of the non-topmost windows; if it is a topmost window, the View is moved to the top of all windows.

Notes

See Also: View.lower.

request-draw-rect-in-root (method)
public {View.request-draw-rect-in-root rect:GRect}:void

Requests a repaint operation for an area described by a GRect that is already in the coordinate system of the RootFrame.

Description

The area to be repainted is described in relation to the coordinate system of the root of a graphical hierarchy.
rect: A GRect that describes the area to be repainted, relative to the coordinate system of the RootFrame.

Programming Notes

This method is usually invoked after first obtaining rect via LayoutContext.rect-for-request-draw and filling values into rect using a method such as BasicLayout.get-visible-bounds-into.

However, if you have access to a LayoutContext, call request-draw-rect-in-root on it instead of looking for a RootFrame in the graphical hierarchy.

request-pointer-trace (method)
public {View.request-pointer-trace}:void

Declare that the geometry of displayed objects may have changed and request that any needed PointerCrossing events be fired.

Description

The request will be forwarded up through this object's chain of graphical ancestors until it reaches the root of this object's graphic hierarchy. If that root is a View and the pointer is within that View, a PointerEnvelopeEvent containing a PointerNonevent will be fired to catalyze the generation of any needed PointerCrossing events.

Overriding

May be overridden by subclasses such as SequenceBox that contain cached state that maps (x,y) positions to the identity of a child object that contains the point (x,y). Such state should be reset so that the new PointerEnvelopeEvent can be properly routed even if the geometry of objects in the graphic hierarchy has changed. If this method is overridden, the overriding method should include a call to

{super.request-pointer-trace}

set-icon (method)
public {View.set-icon
large-icon:Pixmap,
small-icon-if-used:#Pixmap
}:void

Sets an icon in a View.

large-icon: The image to be used when a larger icon (32x32 pixels) is needed.
small-icon-if-used: If non-null, this is the icon that may be displayed in the View caption. If null then this may remove the icon, if any, from the View caption.

Notes

Calling this method will be a no-op in an unprivileged View.

Notes

Some windowing systems do not use the small-icon. Some do not show the icon on the View caption. It basically depends on the windowing system.

set-opacity (method)
public sealed {View.set-opacity opacity:double}:void

Sets the opacity of the View.

opacity: The opacity of this View.

It can range from 0 (completely transparent) to 1 (opaque). If it is less than 0 it is treated as 0 and if it is greater than 1 it is treated as 1.

Notes

For an unprivileged applet the opacity will always be more than 0.50.

This is supported for only Windows XP and newer and on the Macintosh platform. On all other platforms it has no effect.
Introduced in: version 6.0

set-position (method)
public {View.set-position x:Distance, y:Distance}:void

Sets the position of a View, relative to its view parent.

x, y: The new coordinates of the View's upper-left corner, relative to its view parent's upper-left corner. If this View does not have a view parent, (x, y) is relative to the upper left corner of the display.

Notes

This method is going to be deprecated in the future. Use View.set-window-position instead.

set-rendering-mode (method)
public {View.set-rendering-mode rendering-mode:RenderingMode}:bool

Change the type of Renderer2d used to draw this View.

rendering-mode: The new RenderingMode for this View.

Returns

true if rendering-mode is supported on this platform.

Description

This is analogous to set-rendering-mode, but it only affects this particular View. Note that subsequent calls to the global set-rendering-mode will affect this View, overriding any previous calls to View.set-rendering-mode.

Changing this value will induce layout for this View. The change to rendering mode will take place after the Curl event loop has run; this allows View.set-rendering-mode to be safely called even during layout or drawing.

For more information about rendering modes, including more information on which modes are supported for which platforms, please see RenderingMode.

Notes

If you set a View to a RenderingMode that is different from the global RenderingMode, you may run into inconsistencies in the default DisplayContext (as returned by get-default-display-context). In particular, this DisplayContext will correspond to the rendering mode specified globally, and its metrics will not match those in Views using a different rendering mode. It is best to avoid using the default DisplayContext in favor of Visual.get-display-context if possible.
Introduced in: version 6.0

set-title (method)
public final {View.set-title caption:StringInterface}:void

Sets the title in this View's title bar.

caption: The title to display.

Notes

This method will be deprecated in the future.

Use the View.title to get or set the title of a View.

set-topmost (method)
public {View.set-topmost topmost?:bool}:void

Sets or unsets this View as a topmost window.

Description

Views that are designated as topmost windows float above all other (non-topmost) windows, including those of other (non-Curl) applications. To make a View a topmost window, invoke this method, supplying true as its argument. A topmost window remains one until this method is invoked with false as its argument.
topmost?: If true, makes this View a topmost window. If false, causes this View to be a non-topmost window.

Notes

You can move a View to the top or bottom of its category's window stack by invoking View.raise and View.lower respectively. That is, a topmost window can move to the top or bottom of all topmost windows, and a non-topmost window can do the same among non-topmost windows.

set-touch-input-mode (method)
public {View.set-touch-input-mode mode:TouchInputMode}:bool

Set the touch input mode for this View.

mode: The new TouchInputMode to set.

Description

Touch input is not supported on all systems; see touch-input-mode-supported?.

Notes

See TouchInputMode for more information.

Returns

true if the operation is successful, false otherwise.
Introduced in: version 8.0

set-view-size (method)
protected {View.set-view-size new-width:int, new-height:int}:void

Updates the View's data structures to be consistent with the new size specified, which is measured in pixels.

new-width, new-height: The sizes the View is using to represent the bounds of its associated Window, in pixels.

Description

This method is the same as View.set-view-size-options, except that it also resizes RootFrame.bounds (thus potentially causing a layout invalidation).

Programming Notes

This requires extensive knowledge of how a View performs its sizing calculations in order to use safely.

set-view-size-options (method)
protected {View.set-view-size-options
new-width-in-pixels:int,
new-height-in-pixels:int
}:(width:Distance, height:Distance)

Synchronizes the View's size options and assumed Window size.

new-width, new-height: The sizes the View is using to represent the bounds of its associated Window, in pixels.

Description

Set this View's height and width options from the values (in pixels) supplied as the arguments to this method. Return the values (in points) to which the options were set.

Programming Notes

This requires extensive knowledge of how a View performs its sizing calculations in order to use safely.

set-window-position (method)
public {View.set-window-position x:Distance, y:Distance}:void

Sets the position of a View, relative to its view parent.

x, y: The new coordinates of the View's upper-left corner, relative to its view parent's upper-left corner. If this View does not have a view parent, (x, y) is relative to the upper left corner of the display.

Overriding

Not normally overridden.

set-window-position-and-size (method)
public {View.set-window-position-and-size
x:Distance,
y:Distance,
width:Distance,
height:Distance
}:void

Sets the width, height and the position of the View.

Notes

Use this when both the position and size are to be set. This may be faster than calling View.set-window-position and View.set-window-size methods.

set-window-shape (method)
public {View.set-window-shape shape:#Region}:void

Changes the shape of this View to the shape represented by region.

Description

This method must only be called for undecorated, top-level Views; if the View has a title bar and/or border, or is a child View, this method will throw an exception.

A SecurityException will be thrown if an unprivileged applet calls this method.
shape: The shape of the View. Coordinates are interpreted relative to the View's origin (the top-left corner). If this parameter is null, the View's shape is reset to its normal bounds.

Notes

The shape will be limited to the View's size; that is, the actual displayed shape of the View will be the intersection of region and the View's bounds. This intersection will be recomputed whenever either the shape or size of the View changes.

Calling this method only schedules the shape change; it does not actually change the shape of the window until window events have been processed. Usually, this is not an important distinction, as the delay is very small.
Introduced in: version 7.0

set-window-size (method)
public {View.set-window-size width:Distance, height:Distance}:void

Resizes the View.

width: The new width.
height: The new height.

Description

It is not guaranteed that this View will actually resize to this value.

show (method)
public {View.show
force-on-display?:bool = true,
center?:bool = false
}:void

Displays the View.

Description

If a View is created without making it visible, invoke this method to make it visible. If the View is minimized, it will be restored to its default position. If it is maximized, then it will remain maximized.

Making a View visible may not bring it to the top of the window order. It will however change its visibility to WindowVisibility.normal or WindowVisibility.maximized as described in the previous paragraph.
force-on-display?: If true, the View is moved onto the display even if its location coordinates places it wholly off the display. In this case, its position values change once the View is displayed. force-on-display works only if it is supported by the host platform.
center?: Specifies whether this View should be positioned so that it is centered over its owner View, if any. The default value does not cause centering.

If owner is null, this View is centered in the upper two-thirds of the screen.

test-run (method)
public {View.test-run action:String, args:FastArray}:any

Performs a visual testing action on an object.

action: The name of the action to perform.
args: Arguments to the visual testing action. The visual testing infrastructure checks the number and types of the arguments, but not their values. Implementations should strive to handle all legal values and throw exceptions or errors for all illegal values.

Description

Read the class documentation for a list of test actions supported by that class.

The default implementation handles generic operations such as RawClick and will also use reflection to invoke a method if action does not match any known actions.

Notes

Because the QuickTest Property™ visual testing environment does not support direct calls to arbitrary runtime methods, instead use the special CallMethod action, passing the method name as the first argument. The visual testing infrastructure will convert the CallMethod action into the real action before calling test-run.

Notes

See also: canonical-test-value.

Overriding

To add a new testing action, compare action to the name of your new action. If it matches, handle the arguments, perform the action, and return a value of the appropriate type (or null, if there is no return value). If action doesn't match any of your new testing actions, call super.test-run.

touch-input-mode-supported? (method)
public {View.touch-input-mode-supported? mode:TouchInputMode}:bool

Whether a particular TouchInputMode is supported for this View.

mode: The new TouchInputMode to set.

Notes

See TouchInputMode for more information.

Returns

true if supported, and false otherwise.
Introduced in: version 8.0

update (method)
public {View.update}:void

Updates the View immediately by doing exactly what the repaint event handler does.

Description

The window associated with this View is repainted as if a repaint event were being handled. If the layout is not current, it will be recomputed.

Notes

If this method is called from within an event handler, the x, y coordinates in the event being handled may become invalid should this method force a new layout.