AboutProjects

VID Extension Kit - Function Reference - Build 003 (obsolete)

This document is obsolete and will be updated for the latest build.

Window Handling

Windows functions are meant to help in the creation and maintenance of windows.

activate-window

Description:

Activates the given window.

Arguments:
faceThe window face [object!]

display-window

Description:

This displays a face as a window and manages the face in the window list.

Arguments:
faceThe window face [object!]

do-window

Description:

Performs a method on the given window, such as activate, maximize, etc. It's used as the base function for a range of window action functions, like maximize-window.

Arguments:
faceThe window face [object!]
wordThe action to perform, which can be activate, maximize [word!]
Example:

This maximizes the window:

do-window win 'maximize

focus-default-input

Description:

This focuses the first input face with a default flag set. This is used during the execution of init-window. This also sets the focus ring.

Arguments:
faceThe window face [object!]

focus-first-input

Description:

This focuses the first input face. This is used during the execution of init-window, usually after a failed focus-default-input. This also sets the focus ring.

Arguments:
faceThe window face [object!]

focus-first-false

Description:

This focuses the first face, which identifies as a false face, such as FALSE-BUTTON. This also sets the focus ring. This is used in cases without an input face, such as simple dialogs, where quick key access to a cancel button is the correct method.

Arguments:
faceThe window face [object!]

init-enablers

Description:

This initializes all ENABLER styles inside the window. This is used in the init-window function.

Arguments:
faceThe window face [object!]

init-window

Description:

This performs window initialization during view. The ENABLER faces are set, forms are initialized, and it's decided which face to focus first. All operations are done in that order prior to display.

Arguments:
faceThe window face [object!]
Refinements:
/focusDetermines which face to specifically focus on window open.

layout

Description:

This creates a face object tree using the Visual Interface Dialect (VID). This is used to create nearly all subface panes in styles that require them and windows in the VID Extension Kit. It returns a face for viewing with view.

Arguments:
blockThe visual interface dialect block [block!]
Refinements:
/sizeSize (width and height) of pane face [pair!]
/offsetOffset of pane face [pair!]
/parentFace style for pane [object! word! block!]
/originSet layout origin [pair!]
/stylesBlock of styles to use [block!]
/keepKeep style related data
/tightZero offset and origin
Example:
view layout [button "Hello World!"]

make-window

Description:

This creates a resizable window with tab navigation capabilities, focus ring from the given dialect block and stores the tab-face for the face. It returns a face for viewing with view.

Note that all windows created with this function are centered on the screen.

Arguments:
blockThe visual interface dialect block [block!]
Refinements:
optionsBlock of words to use for the resizable window: no-border, no-title
Example:
view make-window [button "Hello World!"]

maximize-window

Description:

Maximizes the given window.

Arguments:
faceWindow face to maximize [object!]

popup?

Description:

Returns whether the window is a popup, shown by inform. This is used when closing the window programmatically, to make sure the correct method for window closing (hide-popup vs. hide) is used.

Arguments:
faceWindow face to investigate [object!]

vid-window?

Description:

Determines if the given face is a VID Extension Kit window, i.e. investigates whether the focus ring exists and the style is window. Such windows are made using the make-window function. They are not created with the layout function.

Arguments:
faceWindow face to investigate [object!]

view

Description:

This displays a pre-existing face object tree created with make-window, layout or manually.

Refinements:
/newCreates a new window and returns immediately.
/offsetOffset of window on screen (Type: pair)
/optionsWindow options [no-title no-border resize] (Type: block word)
/titleWindow bar title (Type: string)

window-open?

Determines if the given window is visible.

Pane Handling

align

Description:

Aligns a face and its content according to the resizing and aligning rules in the VID Extension Kit.

Arguments:
faceFace to align [object!]
Refinements:
/no-showDo not show changes yet

back-face

Description:

Returns the previous face in relation to the input face. It moves along the same path, but opposite direction of next-face.

When used with the /deep refinement, it travels recursively inward through faces that have panes as blocks, functions (iterated faces) or face objects.

One basic condition for this function to work, is that all faces must have a parent face. If this is fulfilled, such as by making a window using make-window, back-face will, when used multiple times, traverse every single face in the face object tree.

Arguments:
faceFace to move one step backwards from [object!]
Refinements:
/deepTraverses recursively inward. If the face contains a pane, the first face in that pane is visited. If a face is part of a pane, and is the last face, next-face proceeds with the next face relative to the parent face of the input face.
Example:
back-face face

center-face

Description:

Centers a given face in relation to a parent face. This is a remnant from VID, not used in the VID Extension Kit, as windows automatically center themselves with make-window and there are other facilities for centering faces inside windows.

Arguments:
faceFace or window to center [object!]
Refinements:
/withCenters relative to a sibling face [object!]

clean-face

Note: This is not in use in the VID Extension Kit yet.

Cleans a face and all its subfaces. A dirty face is one that has had an edit stored by a user, such as a text field in a form. Cleaning the field resets the dirty? flag of the face. It does not perform a clear-face or reset-face and provides no visible changes to the face.

Arguments:
faceface and subfaces to clean the dirty? flag in [object!]

dirty-face?

Note: This is not yet used in the VID Extension Kit.

Description:

Returns if a face or if any of its subfaces are dirty. This is used to detect if there are changes in a form. It does not perform a visible change to the face.

Arguments:
faceFace and subfaces to check the dirty? flag in [object!]

find-flag

Description:

Finds a face with a particular flag relative to the given face. Searches deeply in the face hierarchy

Arguments:
faceFace to use as start position for search [object!]
flagFlag to search for [word!]
Refinements:
/reverseSearches in the opposite direction.

find-face

Description:

Returns the pane for the face, for use when figuring out where the face is in the pane.

Some conditions apply, depending on the location of the input face:

  • If the pane is a block, the pane is returned at that index. If the parent-face of the pane does not match the input face, an error is thrown.
  • If the input face is a window (style = 'window), system/view/screen-face is searched.
  • If the pane is an object, i.e. the input face itself, the input face is returned.
  • If the pane is a function, i.e. an iterated face, the input face is returned
  • If the face does not have a parent-face, an error is thrown.
Arguments:
faceFace to search in [object!]
Refinements:
/panesSearch in a specific pane in a multi pane face [integer!]

find-key-face

Description:

Search faces to determine if keycode applies in the given face object tree. This is used when a key is pressed in the global window feel detect function.

Arguments:
faceFace or window to begin search in [object!]
keycodeKeycode to search for [char! word!]

find-relative-face

Description:

Finds a specific face relative to a given face, traversing deeply and using specific criteria.

Arguments:
faceFace to use as start position for search [object!]
criteriaBlock of criteria to use. Bound to the face currently being examined [block!]
Refinements:

/reverse - Move backwards in the layout

Example:

make-window [
    h3 "Window"
    bar
    my-field: field
    my-button: button "Hello World!"
]
describe-face
    find-relative-face
        my-field
        [all [face in face 'text find face/text "hello"]]
== {'button' named: 'Hello World!' at: 4x56 size: 100x24}

find-style

Description:

Finds a face by style name, relative to the given face.

Arguments:
faceFace to use as start position for search [object!]
styleStyle name [any-word! string!]
Refinements:

/reverse - Move backwards in the layout

Example:

win: make-window [
    h3 "Window"
    bar
    my-field: field
    my-button: button "Hello World!"
]
describe-face find-style win 'button
== {'button' named: 'Hello World!' at: 4x56 size: 100x24}

freeze-face

Description:

Freezes a face or a panel of faces. This removes the feel of the face, except redraw. This basically locks the face from user inputs via keyboard or mouse without visibly changing it, but it can still be set with set-face. Also using tab navigation will skip the face.

Arguments:
faceFace to freeze [object!]
Refinements:
/no-showDo not display change yet.

get-default-face

Note: This is not used anywhere. This may be deprecated.

Description:

Gets the default face (the one which has the default flag set).

Arguments:
faceFace or window to find the default face in [object!]

make-face

Description:

Creates a face from a given style name or example face. This is used internally by layout to construct the face object tree, but can also be used in styles, where special panes are created in ways that would be impractical with layout.

Arguments:
styleName or example face of style to use [word! object!]
Refinements:
/stylesStylesheet
/cloneCopy all primary facets
/sizeSize of face [pair!]
/specSpecification block [block!]
/offsetOffset of face [pair!]
/keepKeep style related data

move-face

Note: This function may be rewritten.

Description:

This moves the upper left corner of the face, optionally without disturbing the lower right corner of the face. Thus the face can both be moved and resized.

When resized, all subfaces are resized according to VID Extension Kit resize rules.

Arguments:
faceFace to move and resize [object!]
offsetOffset from current position of upper left corner [number! pair!]
sizeNew size of the face [number! pair!]
Refinements:
/scaleKeeps the lower right corner at the original position. The face and all subfaces are resized.
/no-showDo not show changes yet.

next-face

Description:

Returns the next face in relation to the input face. It moves along the same path, but opposite direction of back-face.

When used with the /deep refinement, it travels recursively inward through faces that have panes as blocks, functions (iterated faces) or face objects.

One basic condition for this function to work, is that all faces must have a parent face. If this is fulfilled, such as by making a window using make-window, back-face will, when used multiple times, traverse every single face in the face object tree.

Arguments:
faceFace to move one step forward from [object!]
Refinements:
/deepTraverses recursively inward. If the face contains a pane, the first face in that pane is visited. If a face is part of a pane, and is the last face, next-face proceeds with the next face relative to the parent face of the input face.
/panesTraverses all panes in a panel instead of the currently visible pane. The input number is to know which pane to start from. [integer!].
Example:
next-face face

over-face

Description:

Returns the face that that exists under a particular offset inside a face.

Arguments:
faceThe face to find the face the offset is at
offsetThe offset in relation to the face in the first argument [pair!]
Example:

Return the face that is at a particular offset inside a window:

win: make-window [
    b1: box "1" b2: box "2" return ; standard box is 100x100
    b3: box "3" b4: box "4"
]
describe-face over-face win 150x150
== "'box' named: '4' at: 106x106 size: 100x100"

This can be used to find a face at a particular location when hovering over it with the mouse.

resize

Description:

Resizes a face and its contents according to the rules provided in the VID Extension Kit. This is not to be confused to the resize-face accessor function, as this function accepts both a size and an offset, where resize-face only cares for the size.

Arguments:
faceThe face to resize [object!]
sizeThe new size for the face [pair!]
offsetThe new offset for the face [pair!]
Refinements:
/no-showDo not show change yet

root-face

Description:

Returns the window in which the given face resides.

Arguments:
faceThe face to return the root face for [object!]

set-default-face

Note: This is not used anywhere. This may be deprecated.

Description:

Sets the default flag for a given face. Clears existing default face within the given parent.

Arguments:
faceFace to set default flag for [object!]
parentParent face limit, the face which is used to remove the original default face from [object!]

set-parent-faces

Description:

This function sets the parent face correctly for all subfaces for the given face.

This function is very important, as VID normally only sets the parent face for some faces in layouts, as the layout is being viewed the first time using view. For the VID Extension Kit, this is not enough, so this function has been provided.

As a main rule, in the VID Extension Kit, all faces must have a valid parent face. This function helps that to happen in the creation of windows and panes for panels. It's used in styles that creates subfaces, such as PANEL or FACE-CONSTRUCT.

Arguments:
faceFace to set parent faces in [object!]
Refinements:
/parentUse a specific parent face to set parent-face against. Only used internally in the set-parent-faces function.

thaw-face

Description:

Thaws a face or a panel of faces. This restores the feel of the face and lets the user interact with the face again via keyboard and mouse.

Arguments:
faceFace to thaw [object!]
Refinements:
/no-showDo not display change yet.

traverse-face

Description:

Traverses all subfaces in a given face and lets you perform an action on each face. This is for example used to determine whether the tab face is located inside a tab pane, that becomes invisible, when the user switches to a new tab.

Note that the given face will not be included in the traversal. That means the action block will not be run for that face.

Arguments:
faceFace to traverse [object!]
actionAction block to run on each encountered face [block!]
Example:

Traverse my-panel-face to find a field face.

result: none
traverse-face my-panel-face [
    all [
        not result
        face in face 'style face/style = 'field result: face
    ]
]

Note that it's not possible to break from the traversal process.

validate-face

Description:

This validates a single face or a whole window. It's used internally to perform initial condition validation on window open, when a TRUE-BUTTON validates the window and when a single face is validated when pressing Tab.

Arguments:
faceFace to validate [object!]

Face Handling

These are functions that work on the single face without touching subfaces.

click-face

Description

This simulates a mouse click on a face, i.e. mouse down followed by a mouse up. This is used during tab navigation, when you press Space to click a button.

Arguments:
faceFace to click [object!]
Refinements:
altRight click instead of left click
Example:
click-face face

Right click the face:

click-face/alt face

deflag-face

Description:

Removes the flag of a face.

Arguments:
faceFace to remove flag from [object!]
flagFlag to remove [word!]

describe-face

Description:

This is a quick way to dump important, yet compressed information from a face, and is used when a fatal error occurs.

Arguments:
faceFace to describe [object!]
Example:
make-window [my-button: button "Hello World"]
describe-face my-button
== "'button' named: 'Hello World' at: 4x4 size: 100x24"

dirty-face

Note: This is not yet implemented

Description:

Sets a face dirty? flag. This is usually done, after a user has altered the value of the face. It does not set subfaces and does not perform a visible change to the face.

Arguments:
faceFace to set the dirty? flag in [object!]

do-face

Description:

Performs the action function of the face.

Arguments:
faceFace to perform the action function on [object!]
valueThe value passed to the action function [object!]

do-face-alt

Description:

Performs the alt-action function of the face.

Arguments:
faceFace to perform the alt-action function on [object!]
valueThe value passed to the alt-action function [object!]

flag-face

Description:

This sets a flag for a VID face. This function is used throughout the VID Extension Kit in many functions.

Arguments:
faceThe face to set the flag for [object!]
flagThe flag to set [word!]
Example:
flag-face face disabled

Note that the input is not a lit-word!, but a word!.

flag-face?

Description:

This checks for the presence of a specific flag in a VID face. This function is used throughout the VID Extension Kit in many functions.

Example:
flag-face? face disabled

Note that the input is not a lit-word!, but a word!.

focus

Description:

This focuses a specific face without setting the focus ring. It runs the on-focus key formatter.

Arguments:
faceFace to focus [object!]
Refinements:
/no-showDo not display the focus change immediately.
/no-saveDo not save the state of the previous face focused.

get-tab-face

Description:

Returns the tab face for the window in which the given face resides.

Arguments:
faceFace that exists in the window (or the window face itself), in which to get the tab face from [object!]

set-tab-face

Description:

Sets the tab face to the given face. Only touches the tab face in the window in which the face resides. Does not provide visible change.

Arguments:
faceFace that should become tab face [object!]

get-tip-face

Description:

Used internally to find the last face in the last pane inside a pane. This is used to determine for traverse-face, when the pane of its input face has been traversed.

Arguments:
faceFace to find the tip face in [object!]

inside-face?

Description:

Returns whether a given face exists inside the pane of another face. This is used when switching pane in a panel, and you want to make sure that any face that was tab focused there, is properly unfocused.

Arguments:
childface to investigate [object!]
parentparent that child is supposed to reside in [object!]

iterated-face?

Description:

This determines if the given face is correctly set for iteration. If it returns true, then the face has a proper iteration function.

Arguments:
faceface to investigate [object!]

iterated-pane

Description:

This is a uniform way to evaluate the first entry in an iterated face. It is used to determine subfaces inside an iterated face.

Arguments:
faceFace to return first iteration entry from [object!]

restore-flags

Description:

This restores the flag setup for the given face from face/saved-flags, saved by save-flags. This is used for functions that manipulate the feel of the face, such as disable-face.

Arguments:
faceFace to restore flags for [object!]

save-face

Description:

Saves the content of the current focal-face being edited.

Arguments:
faceFace to save [object!]

save-flags

Description:

Saves the flag setup for the given face in face/saved-flags. This is used for functions that manipulate the feel of the face, such as disable-face.

Arguments:
faceFace to save flags for [object!]

unfocus

Description:

This removes key event focus from a face and runs the on-unfocus key formatter. Note that it does not alter the focus ring.

Arguments:
faceFace to unfocus [object!]

Accessor Functions

Although you can create your own accessor functions to access face/access, a range of standard functions are included.

disable-face

Description:

This disables a previously enabled face. The face will appear "dulled" and is no longer accepting user input or tabbing. It can, however, still be managed with setup-face, set-face and get-face.

Arguments:
faceFace to disable [object!]

enable-face

Description:

This enables a previously disabled face.

Arguments:
faceFace to enable [object!]

get-face

Description:

This returns the face value.

Arguments:
faceFace to return the value for [object!]

key-face

Note: This function is not yet included, as there has not been any use of it yet.

Description:

This sends a key event to the face, so it can be processed internally. For example, you can process the cursor keys in a list view separately from the global key handlers in window/feel/detect. For key-face to work, the face must be tab-focused, but it is not required that the cursor is present for editing.

Arguments:
faceface to send the event to [object!]
eventevent to send to the face [event!]

reset-face

Description:

This resets the face value to its default.

Arguments:
faceFace to reset [object!]

resize-face

Description:

Resizes a face and its subfaces according to the rules provided in the VID Extension Kit.

Arguments:
faceFace to resize [object!]
sizeThe new size of the face [number! pair!]

save-face

Description:

This saves the content of the face and thus makes it possible to do a get-face. This is useful if you are writing in a field and then click a button without unfocusing the field by hand.

Arguments:
faceFace to save [object!]

scroll-face

Description:

This scrolls the face vertically or horizontally. The style can use separate functions for each direction.

Arguments:
faceFace to scroll [object!]
x-valueValue between 0 and 1 or none [integer! decimal! none!]
y-valueValue between 0 and 1 or none [integer! decimal! none!]
Refinements:
/stepx and y values are multiples of face step size instead of absolutes
/no-showDo not show changes yet.

set-face

Description:

This sets the face value.

Arguments:
faceFace to set the value for [object!]
valueValue to set [any-type!]
Refinements:
/no-showDo not show changes yet.

setup-face

Description:

This sets the face up, if the face supports setup. This counts for faces that may have sophisticated panes or elements that are allowed to dynamically change during its lifetime.

Arguments:
faceFace to set up [object!]
setupBlock of values or dialect specific to the style to set up the face [block!]

Debugging

debug-align

Description:

Outputs an alignment action in the console. Used internally to debug alignment.

Arguments:
faceFace to dump alignment information from [object!]

debug-face

Description:

Function used internally in the resizing system to output debugging information about resizing and alignment.

Arguments:
doingString to print to tell what action is happening now [string!]
dataData corresponding to the action, such as the output from describe-face [string!]

debug-resize

Description:

Outputs a resize action in the console. Used internally to debug resizing.

Arguments:
faceFace to dump resize information from [object!]
diffSize difference to output [pair!]

dump-face

Description:

Prints face info for the entire pane, for debugging purposes.

Arguments:
faceFace and subfaces to output for [object!]

dump-pane

Description:

Same function as dump-face, except it does at this time not support iterated faces. Please use dump-face instead.

Arguments:
faceFace and subfaces to output for [object!]

Helper Objects

err-face

The err-face is set with the face that fails for some reason during processing of faces using one of the following functions:

  • find-face
  • back-face
  • next-face
  • find-relative-face
  • init-window resets it.

mouse-over-face

This is set to the face every time a mouse move event occurs over a window face. The event is sent in the window detect function.