Chapter 5. Procedures


procedure: (swl:application-modal application thunk)
returns: see below

This procedure returns the result of evaluating thunk. During the evaluation of thunk, user-interface events intended for application are ignored. This can be used, for example, to implement a file-selection dialog that prevents the user from manipulating the calling application until the dialog is dismissed. Note that the threads of the application are not suspended; its stream of events is merely redirected to a bit sink. See 5.



procedure: (swl:get-clipboard)
returns: see below

This returns the contents of the clipboard if any, else #f.



procedure: (swl:append-clipboard string)
returns: unspecified

This appends the given string to the clipboard where it may be retrieved via (swl:get-selection 'clipboard). swl:clear-clipboard must be called before calling swl:append-clipboard, and multiple appends should be carried out in a critical section to prevent another process from retrieving an incomplete clipboard or usurping ownership of the clipboard. The append mechanism makes no attempt to prevent multiple threads from writing to the clipboard.

In practice it appears that each (operating-system) process has its own clipboard and swl:append-clipboard writes to that clipboard. seems to read from the clipboard of whichever process wrote to its clipboard last. (swl:clear-selection 'clipboard) seems to clear the clipboards of all applications. (Still searching for adequate documentation of clipboards in Tcl/Tk.)



procedure: (swl:clear-clipboard)
returns: unspecified

This clears and claims ownership of the clipboard.



procedure: (swl:get-selection)
procedure: (swl:get-selection selection)
returns: see below

This returns the specified selection (primary or clipboard) as a string if it exists, #f otherwise. The default is to return the primary selection.



procedure: (swl:clear-selection)
procedure: (swl:clear-selection selection)
returns: unspecified

This clears the specified selection (primary or clipboard) if it exists. The default is to clear the primary selection.



procedure: (swl:cut-buffer)
procedure: (swl:cut-buffer text)
returns: see below

This parameter implements a global cut buffer used to emulate the behavior of paste in xterm. When text is selected in a widget for which get-export-selection returns true, subsequently clicking the mouse saves the current selection in this global cut buffer before clearing the selection. When attempting to paste in a widget, we insert the result of (swl:get-selection 'primary), if available, or the contents of the cut buffer.



procedure: (swl:font-families)
procedure: (swl:font-families constraint)
returns: a list of symbols

Returns a list of symbols naming font families known to the display. Items in the returned list are legal values for the family attribute of <font> instances created on the local display. If the optional constraint is 'fixed, only the fixed-width font families are returned.



procedure: (swl:font-available? family size file)
returns: true if the specified font is available, otherwise false



procedure: (swl:application-menu)
returns: an instance of <cascade-menu-item>
procedure: (swl:application-menu title thunk)
returns: unspecified

When invoked with no arguments, swl:application-menu returns a cascade menu item for use as a top level entry in the menu of a <toplevel> (i.e. supplied as the menu: attribute of the <toplevel> or installed via its set-menu! method).

When invoked with two arguments, swl:application-menu expects title to be a valid <command-menu-item> title (except that images are not allowed due to incompatibilities with Windows platforms) and thunk to be either a procedure of no arguments, to be invoked when this menu item is chosen, or #f. If thunk is a procedure, then existing and future SWL application menus will contain an entry with the given title that invokes this procedure. If thunk is #f, the corresponding menu entry (if any) is removed from all SWL application menus. Items on the SWL application menu are sorted alphabetically, except the last two items: one titled "Version..." that displays the version information on the initial splash screen and one titled "Exit SWL" that does what you might expect. These default menu entries cannot be removed.



procedure: (swl:help-menu)
returns: an instance of <cascade-menu-item>
procedure: (swl:help-menu title thunk)
returns: unspecified

When invoked with no arguments, swl:help-menu returns a cascade menu item for use as a top level entry in the menu of a <toplevel> (i.e. supplied as the menu: attribute of the <toplevel> or installed via its set-menu! method).

When invoked with two arguments, swl:help-menu expects title to be a valid <command-menu-item> title (except that images are not allowed due to incompatibilities with Windows platforms) and thunk to be either a procedure of no arguments, to be invoked when this menu item is chosen, or #f. If thunk is a procedure, then existing and future SWL help menus will contain an entry with the given title that invokes this procedure. If thunk is #f, the corresponding menu entry (if any) is removed from all SWL help menus. Items on the SWL help menu are sorted alphabetically, except that the last item is always a "Documentation" button that displays the online documentation. The default menu entry cannot be removed.



procedure: (swl:begin-application start-k)
returns: unspecified

Installs a new fallback queue and service thread and calls start-k to construct the application. start-k is passed a unique application token that may be supplied to swl:end-application in order to remove the applicaiton from the list of registered applications. SWL exits when the last registered application is removed. The start-k is expected to return an exit-notify thunk. The exit-notify thunk is invoked when the user clicks on the SWL "Exit SWL" button and by the default abort-handler.

Widgets created during the evaluation of start-k share the new fallback event queue. Because events must be processed serially, using a single event queue for all applications would allow one ill-behaved application to prevent other applications in the Scheme session from receiving events.



procedure: (swl:end-application token)
returns: unspecified

Remove from the list of active applications the instance granted this token and invoke the exit thunk supplied at that time (see 5). If token is the symbol exit-all, invoke the remaining exit thunks and exit SWL if no protected applications remain.



procedure: (swl:open-tcp-client hostname port-number async?)
returns: an input-output port

Returns an input/output port connected by a socket to the specified port number on the given host. If the async flag is true, the socket is connected asynchronously, i.e., the port object is returned without waiting for the actual connection to be made.



procedure: (swl:open-tcp-server host port handler)
returns: an input-output port

Creates a server socket for the given port. host specifies a fully qualified domain name or numerical IP address of the network interface to use for the connection. If host is #f then the server accepts connections via any interface. When a connection is made, handler is passed three arguments: an input/output port connected to the client via socket, the hostname of the client and the port number for the client. swl:open-tcp-server returns a port that cannot be read from or written to, but which can be closed to terminate the server.



procedure: (swl:font-dialog parent title families sizes styles current-font new-font cleanup)
returns: See below

This procedure displays a font dialog for the given parent (an instance of <toplevel> or #f, if none). SWL attempts to place the dialog centered above the parent, if given, or centered on the screen. The title is used as the title of the toplevel window that is created. The families, sizes, and styles parameters are lists of values appropriate for creating instances of the <font> class. The current-font procedure is invoked with no arguments, and should return an instance of <font> used to supply default values for the widgets displaying the various options. When the "OK" button is pressed, the new-font procedure is invoked with an instance of the selected font. When the "Cancel" button is pressed, new-font is invoked with #f.



procedure: (swl:screen-height)
returns: height of the screen, in pixels

This procedure returns height of the screen in pixels.



procedure: (swl:screen-width)
returns: width of the screen, in pixels

This procedure returns width of the screen in pixels.



procedure: (swl:sync-display)
returns: unspecified

Because display updates are buffered by Tcl/Tk, the application state can be out of sync with the display. While this is normally invisible, swl:sync-display can be used to flush pending display updates to the screen in cases where it would otherwise be noticed. It is often necessary to flushing display before getting the width or height of a widget that has just been created, because Tk defers geometry calculations until rendering the widget.