This section contains an assortment of useful GUI and other functions.
batch
begin-busy-cursor
bell
chdir
clean-windows
clear-ide-window
clear-resources
copy-file
debug-msg
dir-exists
dll-execute
dll-free-library
dll-function-exists
dll-load-library
end-busy-cursor
execute
fact-string-existp
file-exists
file-selector
find-window-by-label
find-window-by-name
float-to-string
get-active-window
get-choice
get-elapsed-time
get-ide-window
get-os-version
get-platform
get-resource
get-text-from-user
load-resource-file
long-to-string
make-metafile-placeable
mci-send-string
message-box
mkdir
now
read-string
return-result
rmdir
show-ide-window
set-work-proc
shell-execute
sleep
start-timer
string-sort
string-to-float
string-to-long
string-to-symbol
symbol-to-string
write-resource
wxclips-object-exists
yield
void ( batch string filename)
Executes the given file of CLIPS commands as if from a terminal. Note that full error checking on construct definitions is not performed; use load when checking is required.
void ( begin-busy-cursor)
Starts a 'busy' section of code, putting up an hourglass cursor. Use end-busy-cursor at the end of the section.
These pairs of calls may be nested for programming convenience.
void ( bell)
Rings the system bell.
long ( chdir string directory)
Changes to the given directory and returns 1 if successful, 0 otherwise.
void ( clean-windows)
Delete all frames and dialog boxes created through CLIPS calls.
void ( clear-ide-window)
Clears the wxCLIPS development window.
long ( clear-resources)
Clears the wxCLIPS resource table. This table is separate from the default resource table that is used by wxCLIPS and other host C++ applications.
See also load-resource-file, panel-create-from-resource, dialog-box-create-from-resource.
long ( copy-file string f1 string f2)
Copies file f1 to f2, returning 1 if successful, 0 otherwise.
void ( debug-msg string text)
Outputs text to the debugging stream. Under X, this is the standard error stream. Under Windows, this outputs to the debugger (if present) or any other program that can intercept debug messages, such as Microsoft's DBWIN sample application. This can be useful if you don't have a text window available, and you want the messages to persist after your program has exited, gracefully or otherwise.
long ( dir-exists string directory)
Returns 1 if the directory exists, 0 otherwise.
char* ( dll-execute string library string function string argument="")
Calls a function in a DLL (32-bit Windows only). For example:
(bind ?ans (dll-execute "c:\\windows\\system\\mydll.dll" "MyFunction" "my args"))The C DLL function must be of the form:
extern "C" char* APIENTRY FunctionName(char* arg) ;The function argument and return types must be fixed because it is not possible to construct an arbitrary function call. The DLL function must parse the argument (which might, for example, be one or more space-separated numbers) and convert the result of the call to a string. The calling CLIPS code has to in turn convert the argument(s) to a string, and parse the returned string.
To speed up execution of a DLL function and avoid unnecessary loading and unloading of the module, call dll-load-library before any dll-execute calls are made and dll-free-library when the function will no longer be called. Windows keeps a reference count and will keep the DLL in memory between these two calls.
See also dll-load-library, dll-free-library, dll-function-exists.
long ( dll-free-library long library-id)
Frees the given DLL module, return 1 if succesful, 0 otherwise. This should match a call to dll-load-library.
long ( dll-function-exists string file string function)
Returns 1 if the given function exists in the DLL file, 0 otherwise.
long ( dll-load-library string library)
Loads the given DLL module. Call dll-free-library to free the module. This does not have to be called before dll-execute, but if you are calling a function multiple times, it will speed things up.
The function returns an identifier that must be passed to dll-free-library.
void ( end-busy-cursor)
Ends a 'busy' section of code, resetting the cursor to the original for each window. Use begin-busy-cursor at the start of the section.
These pairs of calls may be nested for programming convenience.
long ( execute string command optional long synchronous = 0)
Executes the given system command, either asynchronously (the function returns control immediately) or synchronously (the function returns control when the command terminates). The default is asynchronous execution.
This function should be used in preference to the CLIPS system command. Under Windows, it calls WinExec. You cannot call built-in DOS commands (such erase) with this function: you may need to write a batch file instead.
See also shell-execute.
bool ( fact-string-existp string fact)
Allows an application to test a fact from within a function. For example:
CLIPS> (fact-string-existp "(Example 1)")
CLIPS> FALSE
CLIPS> (assert (Example 2))
CLIPS> <Fact-0>
CLIPS> (fact-string-existp "(Example 2)")
CLIPS> TRUE
CLIPS> (retract 0)
CLIPS> (fact-string-existp "(Example 2)")
CLIPS> FALSE
long ( file-exists string filename)
Returns 1 if the file exists, 0 otherwise.
string ( file-selector optional string message optional string path optional string file optional string extension optional string wildcard optional long parent-id optional string flags)
Pops up a file selector with given (optional) arguments, returning a fully qualified filename or the empty string.
flags can be the empty string or a bit list of the following:
| wxSAVE | Display the Save button instead of the Open button (Windows only). |
| wxOVERWRITE_PROMPT | Prompts the user when saving if there is already a file of that name (Windows only). |
| wxOPEN | Display the Open button (Windows only). |
| wxHIDE_READONLY | Hide the "Open as read-only" checkbox (Windows only). |
long ( find-window-by-label string label optional long parent-id)
Finds a window with a label or title corresponding to label. Optionally pass a parent id from where to start searching.
long ( find-window-by-name string name optional long parent-id)
Finds a window with a name corresponding to name. Optionally pass a parent id from where to start searching.
string ( float-to-string double n)
Convert a floating point number to a string.
long ( get-active-window)
Returns the id of the active window, or -1 if either there is no active window in this application, or the active window has not been created as a wxCLIPS window.
This function only works under MS Windows.
string ( get-choice string message multifield choices optional long centre-message optional long parent-id)
Given a message string and a multifield comprising a number of choice strings, pops up a menu for the user to select one item. Returns one of the supplied strings if the user pressed Ok, or the null string if the user pressed Cancel.
A multifield can be created with the CLIPS function mv-append, for example:
(bind ?choice (get-choice "Choose please"
(mv-append "One" "Two" "Three")))
If centre-message is 1 (the default), the message will be
centred on the dialog box. If it is 0, the message will be
left-justified. New lines are allowed in the message.
long ( get-elapsed-time optional long reset-timer = 1)
Returns the elapsed time in milliseconds since the last reset, using start-timer or by passing 1 to this function.
long ( get-ide-window)
Gets the id of the wxCLIPS development window (stand-alone wxCLIPS only). If the development window has not been created, zero is returned.
string ( get-os-version)
Returns a string representing the operating system under which the program is currently running. It is more precise than get-platform. However, be careful about inferring from a value of wxWIN95 that this version of wxCLIPS is compiled as a Windows 95 application: it may be compiled as a generic WIN32 application.
This may be one of the following (although only a number of these platforms are currently supported).
string ( get-platform)
Gets a string indicating the current platform the program is running on. Currently one of "XView'', "Motif'' and "Windows 3.1''.
For a more precise notion of current operating system, see get-os-version.
string ( get-resource string section string entry optional string filename)
Gets the value from the resource file (such as WIN.INI or .Xdefaults, depending on platform). If the filename is omitted, WIN.INI under Windows or .Xdefaults under X will be used.
See also write-resource
string ( get-text-from-user string message optional string default-value
optional long centre-message optional long parent-id)
Give a message string and a default value, pops up a dialog box prompting the user to enter a string. Returns the input string if the user pressed Ok, or the null string if the user pressed Cancel.
If centre-message is 1 (the default), the message will be centred on the dialog box. If it is 0, the message will be left-justified. New lines are allowed in the message.
long ( load-resource-file string filename)
Loads the given .wxr resource file, return 1 if the operation was successful.
See also clear-resources, panel-create-from-resource, dialog-box-create-from-resource.
string ( long-to-string long value)
Convert the integer to a string.
long ( make-metafile-placeable string filename long min-x long min-y long max-x long max-y optional double scale)
Given a filename for an existing, valid metafile, makes it into a placeable metafile by prepending a header containing the given bounding box. The bounding box may be obtained from a device context after drawing into it, using the functions dc-get-min-x, dc-get-min-y, dc-get-max-x, and dc-get-max-y.
In addition to adding the placeable metafile header, this function adds the equivalent of the following code to the start of the metafile data:
SetMapMode(dc, MM_ANISOTROPIC); SetWindowOrg(dc, minX, minY); SetWindowExt(dc, maxX - minX, maxY - minY);This simulates the MM_TEXT mapping mode, which wxWindows assumes.
Placeable metafiles may be imported by many Windows applications, and can be used in RTF (Rich Text Format) files.
scale allows the specification of scale for the metafile.
This function is only available under Windows.
See also metafile-dc.
string ( mci-send-string string command)
Sends an MCI (Media Control Interface) string to Windows. Returns an error string if there was an error, or the empty string if there was no error. This allows you to play MIDI and WAV files, for example, and videos if you have an appropriate device driver.
For example:
(bind ?err (mci-send-string "play bark.wav")) (if (neq ?err "") then (printout t "Error: " ?err crlf))The following describes the basic command syntax.
load device_name {file_name}
pause device_name
play device_name [from position]
[to position]
[insert | overwrite]
resume device_name
save device_name [file_name]
seek device_name {to position | to start | to end}
set device_name [audio all off
| audio all on
| audio left off
| audio left on
| audio right off
| audio right on
| video off
| video on]
[door closed | door open]
[time format milliseconds | time format ms]
status device_name {current track
| length
| length track track_number
| mode
| number of tracks
| position
| position track track_number
| ready
| start position
| time format}
stop device name
word ( message-box string message optional word type
optional long centre-message optional long parent-id optional string title)
Pops up a dialog box with a message, where the buttons on the dialog box depend on the type parameter. This may be OK, OK-CANCEL, YES-NO or YES-NO-CANCEL. The return value is OK, CANCEL, YES or NO.
If centre-message is 1 (the default), the message will be centred on the dialog box. If it is 0, the message will be left-justified. New lines are allowed in the message.
The optional title parameter allows the message box title to be changed from the default string 'Message'.
long ( mkdir string directory)
Creates the given directory and returns 1 if successful, 0 otherwise.
string ( now)
Returns a string representing the current time and date.
string ( read-string)
Read a string (pops up a dialog box).
void ( return-result any result)
Used by internal C++ functions to get the return value of an arbitrary CLIPS expression.
long ( rmdir string directory)
Removes the given directory and returns 1 if successful, 0 otherwise.
void ( show-ide-window)
Shows the wxCLIPS development window if it has not already been created (stand-alone wxCLIPS only). This can be useful if starting a CLIPS program from the command line, and you want the development window to be shown before app-on-init has finished. Only likely to work under Windows.
void ( set-work-proc string function)
Sets the work function, a function with no parameter and no return result, which will be called when the application is otherwise idle. If this is the empty string, the work procedure is cancelled.
(Stand-alone version of wxCLIPS only).
Note: this has been found not to work properly on the Windows version, and is not implemented for XView. So probably this is useful only under Motif.
long ( shell-execute string op string file optional string params="" optional string directory="" optional string show="show")
Executes the given shell command, in Windows only.
op can be one of "open", "print" and "explore".
file should be an executable or file.
params can be a list of parameters ("" if the file is a document file).
directory is a the default directory to open the file in.
show is one of "show", "hide", "maximize", "minimize", "restore", "showdefault", "showmaximized", "showminimized", "showminnoactive", "showna", "shownoactivate", "shownormal". See the Windows API documentation for the meaning of these flags.
Example:
(shell-execute "print" "c:\\temp\\temp.txt" "" "" "show")See also execute.
long ( sleep long no-secs)
Makes the process dormant for the given number of seconds. This might be used in a loop involving interprocess communication, for example, to allow time for programs to be loaded. Message processing will take place whilst the process is asleep, so beware of the user interacting with the system during this period.
void ( start-timer)
Starts the wxCLIPS stopwatch. You can get elapsed time in milliseconds with get-elapsed-time.
multifield ( string-sort multifield string-list)
Sorts the given multifield list in ascending alphabetical order. A list may be created using the mv-append CLIPS function.
double ( string-to-float string value)
Convert the string to a floating point number.
long ( string-to-long string value)
Convert the string to a long integer.
word ( string-to-symbol string value)
Convert the string to a symbol.
string ( symbol-to-string word value)
Convert the string to a symbol.
long ( write-resource string section string entry string value optional string filename)
Writes the value into the resource file (such as WIN.INI or .Xdefaults, depending on platform). If the filename is omitted, WIN.INI under Windows or .Xdefaults under X will be used.
See also get-resource
long ( wxclips-object-exists long id)
Returns 1 if the given wxCLIPS object exists, 0 otherwise.
long ( yield)
Yields to the windowing system message loop, if appropriate. Normally only of use under Windows, during periods of intensive processing, particularly following window creation or modification. It has no effect under XView or Motif.