USR Functions References - GiuseppeChillemi/VID-Extension-Kit GitHub Wiki

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:

:face - The window face [object!]

---display-window

...Description:

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

...Arguments:

:face - The 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:

:face - The window face [object!]

:word - The 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:

:face - The 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:

:face - The 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:

:face - The window face [object!]

---init-enablers

...Description:

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

...Arguments:

:face - The 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:

:face - The window face [object!]

...Refinements:

:/focus - Determines 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:

:block - The visual interface dialect block [block!]

...Refinements:

:/size - Size (width and height) of pane face [pair!]

:/offset - Offset of pane face [pair!]

:/parent - Face style for pane [object! word! block!]

:/origin - Set layout origin [pair!]

:/styles - Block of styles to use [block!]

:/keep - Keep style related data

:/tight - Zero 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:

:block - The visual interface dialect block [block!]

...Refinements:

:options - Block 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:

:face - Window 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:

:face - Window 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:

:face - Window face to investigate [object!]

---view

...Description:

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

...Refinements:

:/new - Creates a new window and returns immediately.

:/offset - Offset of window on screen (Type: pair)

:/options - Window options [no-title no-border resize] (Type: block word)

:/title - Window 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:

:face - Face to align [object!]

...Refinements:

:/no-show - Do 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.

=image images/vid-ext-kit-back-face-loop.png

...Arguments:

:face - Face to move one step backwards from [object!]

...Refinements:

:/deep - Traverses 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:

:face - Face or window to center [object!]

...Refinements:

:/with - Centers 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:

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

:face - Face 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:

:face - Face to use as start position for search [object!]

:flag - Flag to search for [word!]

...Refinements:

:/reverse - Searches 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:

:face - Face to search in [object!]

...Refinements:

:/panes - Search 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:

:face - Face or window to begin search in [object!]

:keycode - Keycode 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:

:face - Face to use as start position for search [object!]

:criteria - Block 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:

:face - Face to use as start position for search [object!]

:style - Style 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:

:face - Face to freeze [object!]

...Refinements:

:/no-show - Do 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:

:face - Face 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:

:style - Name or example face of style to use [word! object!]

...Refinements:

:/styles - Stylesheet

:/clone - Copy all primary facets

:/size - Size of face [pair!]

:/spec - Specification block [block!]

:/offset - Offset of face [pair!]

:/keep - Keep 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:

:face - Face to move and resize [object!]

:offset - Offset from current position of upper left corner [number! pair!]

:size - New size of the face [number! pair!]

...Refinements:

:/scale - Keeps the lower right corner at the original position. The face and all subfaces are resized.

:/no-show - Do 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.

=image images/vid-ext-kit-next-face-loop.png

...Arguments:

:face - Face to move one step forward from [object!]

...Refinements:

:/deep - Traverses 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.

:/panes - Traverses 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:

:face - The face to find the face the offset is at

:offset - The 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:

:face - The face to resize [object!]

:size - The new size for the face [pair!]

:offset - The new offset for the face [pair!]

...Refinements:

:/no-show - Do not show change yet

---root-face

...Description:

Returns the window in which the given face resides.

...Arguments:

:face - The 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:

:face - Face to set default flag for [object!]

:parent - Parent 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:

:face - Face to set parent faces in [object!]

...Refinements:

:/parent - Use 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:

:face - Face to thaw [object!]

...Refinements:

:/no-show - Do 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:

:face - Face to traverse [object!]

:action - Action 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:

:face - Face 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:

:face - Face to click [object!]

...Refinements:

:alt - Right 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:

:face - Face to remove flag from [object!]

:flag - Flag 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:

:face - Face 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:

:face - Face to set the dirty? flag in [object!]

---do-face

...Description:

Performs the action function of the face.

...Arguments:

:face - Face to perform the action function on [object!]

:value - The value passed to the action function [object!]

---do-face-alt

...Description:

Performs the alt-action function of the face.

...Arguments:

:face - Face to perform the alt-action function on [object!]

:value - The 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:

:face - The face to set the flag for [object!]

:flag - The 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:

:face - Face to focus [object!]

...Refinements:

:/no-show - Do not display the focus change immediately.

:/no-save - Do 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:

:face - Face 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:

:face - Face 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:

:face - Face 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:

:child - face to investigate [object!]

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

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

:face - Face 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:

:face - Face to restore flags for [object!]

---save-face

...Description:

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

...Arguments:

:face - Face 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:

:face - Face 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:

:face - Face 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:

:face - Face to disable [object!]

---enable-face

...Description:

This enables a previously disabled face.

...Arguments:

:face - Face to enable [object!]

---get-face

...Description:

This returns the face value.

...Arguments:

:face - Face 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:

:face - face to send the event to [object!]

:event - event to send to the face [event!]

---reset-face

...Description:

This resets the face value to its default.

...Arguments:

:face - Face to reset [object!]

---resize-face

...Description:

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

...Arguments:

:face - Face to resize [object!]

:size - The 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:

:face - Face to save [object!]

---scroll-face

...Description:

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

...Arguments:

:face - Face to scroll [object!]

:x-value - Value between 0 and 1 or none [integer! decimal! none!]

:y-value - Value between 0 and 1 or none [integer! decimal! none!]

...Refinements:

:/step - x and y values are multiples of face step size instead of absolutes

:/no-show - Do not show changes yet.

---set-face

...Description:

This sets the face value.

...Arguments:

:face - Face to set the value for [object!]

:value - Value to set [any-type!]

...Refinements:

:/no-show - Do 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:

:face - Face to set up [object!]

:setup - Block of values or dialect specific to the style to set up the face [block!]

;---get-face-path - This returns the PATH value of the face.

;---set-face-path - This sets the PATH value of the face.

===Debugging

---debug-align

...Description:

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

...Arguments:

:face - Face 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:

:doing - String to print to tell what action is happening now [string!]

:data - Data 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:

:face - Face to dump resize information from [object!]

:diff - Size difference to output [pair!]

---dump-face

...Description:

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

...Arguments:

:face - Face 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:

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