#ifndef COMMONGUIEXTENSION_H
#define COMMONGUIEXTENSION_H
#include "uiextension.h"
#include <QMap>
#include <QPointer>
class LurchScriptEngineAgent;
/** \brief Implements the most common UIExtension functions for a GUI
*
* See UIExtension's documentation to understand what this class does.
* To see which functions it adds to a LurchEnvironment, examine the list of slots below.
*/
class CommonGUIExtension : public UIExtension
{
Q_OBJECT
public:
/** \brief Construct a UIExtension that adds the slots below
*
* \param center Several of the functions this class adds pop up message or show dialogs,
* and thus it helps to have an on-screen widget over which to center those
* dialogs. If you pass a valid widget as \a center, it will be used for
* that purpose. Otherwise, passing NULL (the default) will center such
* dialogs on the screen, rather than over any widget.
* \param parent Passed on to the UIExtension constructor as the parent QObject.
*/
CommonGUIExtension ( QWidget* center = 0, QObject* parent = 0 );
/** \brief The main routine used by script_runTests()
*
* See script_runTests() for complete documentation. This can be used independently, taking
* a string of JavaScript containing tests to run, and returning a string array of results
* as specified in the documentation for script_runTests().
*/
QStringList runTests ( QString code, QScriptEngine* engine );
public slots:
/** \brief Installs a LurchScriptEngineAgent, then calls the parent implementation
*
* This handler is here just to attach to the script engine a LurchScriptEngineAgent before
* letting the default implementation of installFunctionNames() proceed.
*/
virtual void installFunctionNames ( QScriptEngine* engine );
/** \brief Pop up an alert dialog showing the value of the first parameter
*
* Implements the <code>uiCommand( 'alert', ... )</code> function
* available in the LurchEnvironment \a env.
* That command pops up an alert dialog showing the value of the parameter after
* the first (the one that is simply the string <code>'alert'</code>).
* If two parameters are given, the value of the second is shown, while the first is
* treated as the dialog title (replacing the default "Lurch script alert").
*
* For an explanation of how this class uses this slot, see the documentation for the
* UIExtension base class.
* For documentation on uiCommands in general (and <code>alert</code> in particular), see
* \link uiprotocol the Protocol for Document-UI Communication\endlink.
*/
QScriptValue script_alert ( QScriptContext* context, QScriptEngine* engine );
/** \brief Pop up an alert dialog with given title, text, and list of buttons
*
* Implements the <code>uiCommand( 'alert', ... )</code> function
* available in the LurchEnvironment \a env.
* That command pops up an alert dialog with the following properties.
* <ol>
* <li>The first parameter after 'alert' is used as the dialog's first line (larger font).
* If no such parameter is given, "Lurch script alert" is used.</li>
* <li>The parameter after that is the remaining text in the dialog (smaller font).
* If no such parameter is given, the dialog will contain no more text.</li>
* <li>The remaining parameters are each separate button texts.
* If no such parameters are given, 'OK' is used as the one button text.</li>
* </ol>
* Thus, for example, the following code would make a reasonable dialog.
* \code
* UI.alert( 'Stop processing?',
* 'Should the processing of the wuzzles be aborted now?',
* 'Yes', 'No', 'Yes and handle the wuzzles carefully' );
* \endcode
*
* All parameters are treated as strings.
* Any of the buttons dismisses the dialog, and the text of the button used to dismiss
* the dialog is returned as a string from this function.
*
* For an explanation of how this class uses this slot, see the documentation for the
* UIExtension base class.
* For documentation on uiCommands in general (and <code>alert</code> in particular), see
* \link uiprotocol the Protocol for Document-UI Communication\endlink.
*/
QScriptValue script_alertWithButtons ( QScriptContext* context, QScriptEngine* engine );
/** \brief Dumps the string values of all parameters to the console using qDebug()
*
* Implements the <code>uiCommand( 'print', ... )</code> function
* available in the LurchEnvironment \a env.
* That command dumps the other parameters (those after the <code>'print'</code> string)
* to the console using qDebug().
*
* For an explanation of how this class uses this slot, see the documentation for the
* UIExtension base class.
* For documentation on uiCommands in general (and <code>print</code> in particular), see
* \link uiprotocol the Protocol for Document-UI Communication\endlink.
*/
QScriptValue script_print ( QScriptContext* context, QScriptEngine* engine );
/** \brief Sets data about whether and how to trace calls to a function
*
* Data set with this function does not persist across reloads of the script environment.
* For instance, if you execute a full reload in Lurch, or change an auto-run script so
* that the script environment is cleared and repopulated, this data will disappear. To
* ensure that it does not disappear in this way, place calls to this function in auto-run
* scripts so that they happen after each script environment repopulation.
*
* Implements the <code>uiCommand( 'trace', ... )</code> function
* available in the LurchEnvironment \a env.
*
* Example call:
* \code
* UI.trace( 'Schmog function', mySchmogFn, 'enter return' );
* \endcode
*
* The first argument should be the name of the function to be traced, in a human
* readable form. The second argument should be the function to trace (or, rather, to
* modify the trace flags on). The third argument is an explanation string.
*
* The explanation is a string of words separated by spaces, where the words come from
* this set: entry, noentry, exit, noexit, params, noparams, return, noreturn.
* The "no" words disable tracing featuers, and the others enable them.
*
* A function with entry tracing enabled prints its name each time its body is entered
* during script execution. If param tracing is also enabled, the parameter list is
* also printed.
*
* A function with exit tracing enabled prints its name each time execution returns from
* that function during script execution. If return tracing is also enabled,
* the return value is also printed.
*
* For an explanation of how this class uses this slot, see the documentation for the
* UIExtension base class.
* For documentation on uiCommands in general see
* \link uiprotocol the Protocol for Document-UI Communication\endlink.
*/
QScriptValue script_trace ( QScriptContext* context, QScriptEngine* engine );
/** \brief Prompt the user to enter a string and return their response as a string
* (or false if they cancel)
*
* Implements the <code>uiCommand( 'ask', promptString[, defaultValue] )</code> function
* available in the LurchEnvironment \a env.
* That command prompts the user with the given \a promptString, fills in their response
* with the given \a defaultValue (if supplied), and lets them type a response. Their
* response is returned as a string if they give one; if they cancel the input, the
* boolean false is returned instead. This prompt is synchronous; program execution halts
* while the user's response is awaited.
*
* For an explanation of how this class uses this slot, see the documentation for the
* UIExtension base class.
* For documentation on uiCommands in general see
* \link uiprotocol the Protocol for Document-UI Communication\endlink.
*/
QScriptValue script_ask ( QScriptContext* context, QScriptEngine* engine );
/** \brief Pop up a dialog to whcih the user must answer yes or no; return it as a boolean
*
* Implements the <code>uiCommand( 'askYN', promptString )</code> function
* available in the LurchEnvironment \a env.
* That command prompts the user with the given \a promptString, and allows them to
* choose a yes or no response (no other options). Their response is returned as a
* boolean (yes is true, no is false). This prompt is synchronous; program execution halts
* while the user's response is awaited.
*
* For an explanation of how this class uses this slot, see the documentation for the
* UIExtension base class.
* For documentation on uiCommands in general see
* \link uiprotocol the Protocol for Document-UI Communication\endlink.
*/
QScriptValue script_askYN ( QScriptContext* context, QScriptEngine* engine );
/** \brief Launch the user's default external browser to the URL passed as a string
*
* Implements the <code>uiCommand( 'openURL', urlString )</code> function
* available in the LurchEnvironment \a env.
* That command launches the user's default external browser to the URL in \a urlString.
* This function returns immediately.
*
* For an explanation of how this class uses this slot, see the documentation for the
* UIExtension base class.
* For documentation on uiCommands in general see
* \link uiprotocol the Protocol for Document-UI Communication\endlink.
*/
QScriptValue script_openURL ( QScriptContext* context, QScriptEngine* engine );
/** \brief Pop up a dialog showing the text given as a string (with scrollbars if long)
*
* Implements the <code>uiCommand( 'showText', title, text )</code> function
* available in the LurchEnvironment \a env.
* That command pops up a dialog showing the (possibly lengthy) string of (plain or rich)
* text, allowing the user to scroll through it to read it at their convenience, and
* click a button to close the dialog. This prompt is synchronous; program execution halts
* while the user reads, until they close the dialog. The \a title parameter is used
* for the popup window's title.
*
* For an explanation of how this class uses this slot, see the documentation for the
* UIExtension base class.
* For documentation on uiCommands in general see
* \link uiprotocol the Protocol for Document-UI Communication\endlink.
*/
QScriptValue script_showText ( QScriptContext* context, QScriptEngine* engine );
/** \brief Prompts the user with several input options in one dialog; returns an array of
* their responses
*
* Implements the <code>uiCommand( 'inputDialog', ... )</code> function
* available in the LurchEnvironment \a env.
* Displays to the user a sequence of input requests as a group (e.g., in one dialog).
* Program execution pauses and awaits the user to answer each one, and then choose
* OK or cancel. If they choose cancel, false is returned, otherwise, the array of
* their responses is returned. The first parameter (after 'inputDialog') is a string
* to use for the title bar of the dialog. After that, any number of additional
* parameters can be passed, each indicating a different type of input.
* Here are the different input types to choose from:
* <ul>
* <li>One line of text: Pass an argument of the form
* <code>[ 'LineEdit', 'prompt here', 'default value here' ]</code></li>
* <li>Large section of text: Same as previous, but with 'TextEdit' instead</li>
* <li>Selection from a list: Pass an argument of the form
* <code>[ 'ComboBox', 'prompt here', 'option 1', 'option 2', ... ]</code>
* which assumes the first on the list is the default; to change it, use the
* form <code>[ 'ComboBox', 'prompt here', ['option 1', 'option 2', ...],
* 'default' ]</code>. In this latter form, you can also pass an optional
* fifth entry <code>true</code> if you wish to make the combo box freely editable.
* Otherwise the user must pick from the given list only.</li>
* <li>Selection from a range of numbers: Pass an argument of the form
* <code>[ 'Slider', 'prompt here',
* rangeMinimum, rangeMaximum, rangeStep ]</code></li>
* <li>Yes/no response: Pass an argument of the form
* <code>[ 'CheckBox', 'prompt here', booleanDefault ]</code></li>
* </ul>
* Optionally, you can make the last parameter of the call the string 'horizontal',
* in which case it will lay out the dialog horizontally (prompts in one row,
* input widgets in the row below).
*
* For an explanation of how this class uses this slot, see the documentation for the
* UIExtension base class.
* For documentation on uiCommands in general see
* \link uiprotocol the Protocol for Document-UI Communication\endlink.
*/
QScriptValue script_inputDialog ( QScriptContext* context, QScriptEngine* engine );
/** \brief Takes a code string as input, splits it into statements, and runs each as a test
*
* Implements the <code>uiCommand( 'runTests', codeBlock )</code> function
* available in the LurchEnvironment \a env.
*
* Split <i>codeBlock</i> at newlines, except those in the middle of a Javascript
* expression, and treat each string in the resulting array as a test to run. That
* is, a test is a string of Javascript code that will be evaluated, and its result
* treated as a boolean, true indicating the test passes and false that it fails.
* If the code raises an uncaught exception while running, this is reported as a
* failure.
*
* The result of this function is an array of the form
* <code>[ code1, result1, ..., codeN, resultN ]</code>, in which each
* <code>codeI</code> is a string of Javascript code, a test that was run, and the
* corresponding <code>resultI</code> is the result, as a string. If it is the
* string "Pass", the test passed because the code evaluated to a boolean true.
* If it is the string "Fail", the test failed because the code evaluated to a boolean
* false. Otherwise, the code had an uncaught exception, and so the string will be
* of the form "Fail due to error: [error message here]".
*
* If no parameter is passed, then this function behaves differently in two ways.
* First, it iterates over all scripts in the document of type <code>test</code>,
* and processes each as described above. Second, it does not return its
* result as an array, but rather a single HTML string that reports
* the results in a readable and color-coded format, suitable for display in the console.
* Thus <code>print(UI.runTests())</code> can be executed from the console alone and
* result in a nicely formatted report.
*
* For an explanation of how this class uses this slot, see the documentation for the
* UIExtension base class.
* For documentation on uiCommands in general see
* \link uiprotocol the Protocol for Document-UI Communication\endlink.
*/
QScriptValue script_runTests ( QScriptContext* context, QScriptEngine* engine );
/** \brief Selects a random number in the given range
*
* A random integer from \a a to \a b (inclusive) is chosen and returned.
*
* For an explanation of how this class uses this slot, see the documentation for the
* UIExtension base class.
* For documentation on uiCommands in general see
* \link uiprotocol the Protocol for Document-UI Communication\endlink.
*/
QScriptValue script_random ( QScriptContext* context, QScriptEngine* engine );
/** \brief Fetches the contents of the clipboard as an object mapping MIME types to string data
*
* Returns an object whose keys are the string MIME types on the clipboard, and whose values
* are the corresponding data on the clipboard, converted to strings. The conversion is very
* simple; it treats every datum on the clipboard as if it were the UTF-8 encoding of a
* string. The only exception to this rule is that if the data is an image (which will have
* MIME type "application/x-qt-image" due to Lurch's use of the Qt toolkit) then the data
* will be a string containing an HTML image tag using a base-64 data URI to embed the image,
* as in createEmbeddedImageTag().
*
* Thus a script might do something like this.
* \code
* var clipData = UI.getClipboard();
* if ( "text/plain" in clipData ) {
* myProcessingRoutine( clipData["text/plain"] ); // that datum is a string
* } else {
* print( "Couldn't handle clipboard that didn't contain text." );
* print( "MIME types it contained: " + clipData.objKeys().join( ", " ) );
* }
* \endcode
*
* For an explanation of how this class uses this slot, see the documentation for the
* UIExtension base class.
* For documentation on uiCommands in general see
* \link uiprotocol the Protocol for Document-UI Communication\endlink.
*/
QScriptValue script_getClipboard ( QScriptContext* context, QScriptEngine* engine );
/** \brief Sets the contents of the clipboard to the given data
*
* If only one argument is passed, and it is not an array or object, then this function just
* calls QApplication::clipboard()->setText() on that argument, treated as a string.
*
* If more than one argument is passed, or an array is passed as the first argument, they
* are treated as key-value pairs (element0 => element1, element2 => element3, ... ).
* If a non-array object is passed as the first argument, its own properties are treated as
* keys, and with their values, therefore make key-value pairs.
*
* The keys in such maps are treated as (string) MIME types, e.g. "text/plain" or "image/png".
* Ensure that the keys are sensible MIME types; this routine does no validation of that.
* The values are the data to be placed in the clipboard. For now, all are placed in the
* clipboard as text strings.
*
* Returns the new clipboard, represented as a JavaScript object in the same way that
* script_getClipboard() returns it.
*
* For an explanation of how this class uses this slot, see the documentation for the
* UIExtension base class.
* For documentation on uiCommands in general see
* \link uiprotocol the Protocol for Document-UI Communication\endlink.
*/
QScriptValue script_setClipboard ( QScriptContext* context, QScriptEngine* engine );
/** \brief Stores a Lob into the user's settings, under a given key
*
* This enables scripts to store permanent user settings that they can look up later.
* The setting key is an OpenMath symbol, and the value can be any Lob.
* The key symbol is not case sensitive.
*
* When a script calls UI.saveSetting( A, B ), the following takes place.
* <ul>
* <li>If either A or B is not a Lob, this throws an error stating that they must be
* Lobs.</li>
* <li>If A.hasAttribute( B ), this stores the association with key B and value
* A.attribute( B ).</li>
* <li>Otherwise if A is a symbol, this stores the association with key A and value B.</li>
* <li>Otherwise, this throws an error stating that the parameters were incorrectly
* configured.</li>
* </ul>
*
* \see script_loadSetting(), script_setOptions()
*
* For an explanation of how this class uses this slot, see the documentation for the
* UIExtension base class.
* For documentation on uiCommands in general see
* \link uiprotocol the Protocol for Document-UI Communication\endlink.
*/
QScriptValue script_saveSetting ( QScriptContext* context, QScriptEngine* engine );
/** \brief Restores a previously stored Lob from the user's settings
*
* The one argument must be a symbol Lob that serves as the key, and the value will be
* returned as a Lob. If it is not a symbol, then an error is thrown. If there is no
* setting stored under the given symbol, the empty Lob is returned.
*
* \see script_saveSetting(), script_setOptions()
*
* For an explanation of how this class uses this slot, see the documentation for the
* UIExtension base class.
* For documentation on uiCommands in general see
* \link uiprotocol the Protocol for Document-UI Communication\endlink.
*/
QScriptValue script_loadSetting ( QScriptContext* context, QScriptEngine* engine );
/** \brief Clears a previously stored Lob from the user's settings
*
* The one argument must be a symbol Lob that serves as the key, and both it and its value
* will be removed from the user's settings. If it is not a symbol, then an error is thrown.
*
* \see script_loadSetting(), script_saveSetting()
*
* For an explanation of how this class uses this slot, see the documentation for the
* UIExtension base class.
* For documentation on uiCommands in general see
* \link uiprotocol the Protocol for Document-UI Communication\endlink.
*/
QScriptValue script_clearSetting ( QScriptContext* context, QScriptEngine* engine );
/** \brief Stores a set of options in the application's QSettings for use in the
* preferences dialog
*
* This routine takes one parameter, an object with several key-value pairs.
* <ul>
* <li>One of the keys must be <tt>category</tt>, and its value a string indicating the
* category into which all the other keys fit. For example, you might call this
* function from within a package on truth tables, and use the category
* "truth tables". This key must be present and its value must be a nonempty
* string, or this routine does nothing.</li>
* <li>The rest of the key should each be a description of a setting, written as it will
* appear in the global preferences dialog box. Thus this string must be
* user-readable, and not require and specific context to be understood. For
* example, "Enable probabalistic checking of frabjous widgets".</li>
* <li>The values for such keys should be the defaults that will be shown the first time
* the user opens the preferences dialog, and that will be reported as the values
* at any time before the user first changes them. A boolean value will result in
* a checkbox widget, and any other value will be converted to a string, and result
* in an editable string of text.</li>
* </ul>
*
* These settings differ from what script_saveSetting() and script_loadSetting() deal
* with in that these are publicly editable by the user in the global preferences dialog,
* while those are invisible to the user, and stored only by scripts. They are disjoint,
* in that no matter what keys/categories you use, they cannot collide in the QSettings
* object.
*
* Example call:
* \code
* UI.setOptions( { category : 'algebra tooltips',
* 'Show tips about how to fix factoring errors' : true,
* 'Show tips mocking the user when they add wrong' : false } );
* \endcode
* Such code belongs in the package that wishes to use these options, outside of any
* function definition, so that it is called when the package is first loaded. The call
* only sets the defaults once; if the user changes them thereafter, this call does not
* reset the options to the defaults.
*
* This function <i>does</i>, however, delete any options in the same category that do not
* appear on this list. This is desirable because if one version of a package installs
* an option that later becomes irrelevant, then it will be removed from the global
* preferences dialog (and thus from the user's view) when he or she begins to use the new
* version of the same package, and an updated call to this routine is first made.
* Thus you should ensure that the categories are distinct in each call you make to this
* routine. Since the categories are not user-visible, you can use whatever convention
* you like to ensure their uniqueness.
*
* Use script_getOption() and script_setOption() to manipulate these settings
* programmatically. Recall that the user can always manipulate them with the preferences
* dialog.
*
* For an explanation of how this class uses this slot, see the documentation for the
* UIExtension base class.
* For documentation on uiCommands in general see
* \link uiprotocol the Protocol for Document-UI Communication\endlink.
*/
QScriptValue script_setOptions ( QScriptContext* context, QScriptEngine* engine );
/** \brief Query the value of an option installed with script_setOptions()
*
* For the overview of what script options are and how they differ from settings, see
* script_setOptions().
*
* This function queries the value of a single option that has been installed with that
* function. It takes two string parameters,
* <ol>
* <li>the category name and</li>
* <li>the option name,</li>
* </ol>
* each just as it was passed to an earlier call to script_setOptions().
*
* Example:
* \code
* var showTip = UI.getOption( 'algebra tooltips',
* 'Show tips about how to fix factoring errors' );
* \endcode
* If the user has never edited this option in the global preferences dialog, and no call
* to script_setOption() has been made with this category and option name, then this
* function returns the default installed in the earlier call to script_setOptions().
*
* For an explanation of how this class uses this slot, see the documentation for the
* UIExtension base class.
* For documentation on uiCommands in general see
* \link uiprotocol the Protocol for Document-UI Communication\endlink.
*/
QScriptValue script_getOption ( QScriptContext* context, QScriptEngine* engine );
/** \brief Change the value of an option installed with script_setOptions()
*
* For the overview of what script options are and how they differ from settings, see
* script_setOptions().
*
* This function changes the value of a single option that has been installed with that
* function. It takes three parameters,
* <ol>
* <li>the category name,</li>
* <li>the option name, and</li>
* <li>the new value that should replace the previous value (which may or may not be
* the default, depending on whether the user has edited it using the preferences
* dialog).</li>
* </ol>
* The first to parameters should each be just as it was passed to an earlier call to
* script_setOptions(). The last may be a boolean, which will cause the option to be
* shown as a checkbox in the preferences dialog, or anything else, which will be editable
* as a single line of text in that dialog.
*
* Example:
* \code
* UI.setOption( 'algebra tooltips',
* 'Show tips about how to fix factoring errors',
* true );
* \endcode
*
* For an explanation of how this class uses this slot, see the documentation for the
* UIExtension base class.
* For documentation on uiCommands in general see
* \link uiprotocol the Protocol for Document-UI Communication\endlink.
*/
QScriptValue script_setOption ( QScriptContext* context, QScriptEngine* engine );
/** \brief Returns the given code syntax-highlighted either as JavaScript or as XML
*
* Treats the first argument as a string, the text to syntax highlight.
* If the second argument (when treated as a string) is "XML" then this routine returns
* a string containing the result of invoking syntaxHighlightXML() on the input.
* Otherwise it returns a string containing the result of invoking
* syntaxHighlightJavascript() on the input.
*
* For an explanation of how this class uses this slot, see the documentation for the
* UIExtension base class.
* For documentation on uiCommands in general see
* \link uiprotocol the Protocol for Document-UI Communication\endlink.
*/
QScriptValue script_syntaxHighlight ( QScriptContext* context, QScriptEngine* engine );
/** \brief Does the given comptuation only once, using the cache if possible
*
* If a given computation may be executed many times from many places, but the result is
* not expected to change in a short time (before the current script finishes and the
* event loop gets control back), it can be much faster to load the result of the
* computation from a cache. This function provides that functionality.
* For example, you may need to compute
* \code
* UI.LobAt( UI.cursorPosition() )
* \endcode
* several times in several different handler functions, all within milliseconds of one
* another. It would be unnecessarily time consuming to do the computation over for each
* handler, and yet the burden of caching the data is too much to put on each library.
* So instead you write code like this.
* \code
* UI.stable( 'UI.LobAt( UI.cursorPosition() )' )
* \endcode
* The code is run (using flexeval(), so it can be CoffeeScript, too) and the result is
* cached. Any further calls to the same code as above will use the cache rather than
* recompute.
*
* The cache is cleared using a zero-timer, but ensures first that the script engine has
* completed evaluation. So as soon as the script that was being execute completes, the
* next time the event loop regains control, the cache is invalidated. Note that for a
* very lengthy computation, such as validation, this may mean that the cursor may move,
* the document may change, etc., before the cache is invalidted.
* Furthermore, scripts may modify the document before the cache is invalidated,
* so be aware of those limitations and do not use this function if such
* modifications would invalidate your intentions for the cache.
*
* Use this function at your own risk; if the code you pass has side-effects that you
* <i>want</i> to happen once for each call to the function, then caching the value is
* not what ought to happen in your circumstance. Evaluate your own needs, and use this
* as appropriate.
*
* If the code you pass contains free variables, then you may not want the cache to be
* keyed based only on the code itself, but may want additional data to help make the key
* unique. You can pass such additional data, as a string, as the second argument.
* For example:
* \code
* for ( int i = 0 ; i < N ; i++ ) {
* var tmp = UI.stable( 'longComputation( myData[i] )', myData[i].toString() );
* // here do some decision-making or processing of tmp
* }
* \endcode
* Thus each pass through the loop gets its own entry in the cache. In fact, if the order
* will not change, and no other potentially conflicting calls are expected to
* <tt>UI.stable()</tt>, perhaps <tt>myData[i].toString()</tt> could be replaced simply
* with <tt>i</tt>.
*/
QScriptValue script_stable ( QScriptContext* context, QScriptEngine* engine );
/** \brief Interface to a profiling service with several features
*
* To turn on profiling for a function, execute the script call
* \code
* UI.profile( 'on', 'myFunctionName' );
* \endcode
* This will assign to the variable <tt>myFunctionName</tt> a new wrapper function that
* records start and stop times for each call, but otherwise passes arguments and return
* values through transparently. Use <tt>'off'</tt> to return to the original function.
*
* To see a profiling report, execute the script call
* \code
* UI.profile( 'report' );
* \endcode
* and to clear all data from the report, execute
* \code
* UI.profile( 'clear' );
* \endcode
*
* To profile just a short section of code that is not a function, you can also use the
* command
* \code
* UI.profile( 'mark', 'any descriptor here' );
* \endcode
* and when that command is executed, it prints to the system console the descriptor given,
* together with the number of milliseconds since the last call to that function. For
* example:
* \code
* UI.profile( 'mark', 'start of area to profile' );
* doSomethingRatherLong();
* UI.profile( 'mark', 'first phase complete' );
* doSomethingMaybeLonger();
* UI.profile( 'mark', 'second phase complete' );
* for ( var i = 0 ; i < N ; i++ ) {
* processOneItem( i );
* UI.profile( 'mark', 'iteration '+i+' complete' );
* }
* \endcode
* The first call to <tt>UI.profile( 'mark', '...' )</tt> will use 0ms.
* The number of milliseconds is returned.
*/
QScriptValue script_profile ( QScriptContext* context, QScriptEngine* engine );
private:
/** \brief The widget over which to center popup message and dialogs
*/
QWidget* center;
/** \brief The LurchScriptEngineAgent used in script_trace().
*/
LurchScriptEngineAgent* lsea;
/** \brief Cache for script_stable()
*
* \see script_stable()
*/
QMap<QString,QScriptValue> stableCache;
/** \brief Stores the engine when script_stable() is called
*
* This way, the stableCache will not be cleared if the engine is still computing.
* This allows <tt>UI.stable()</tt> calls to result in only one evaluation of the given
* argument during a lengthy computation, such as document validation.
* This is usually the behavior the script author expects anyway; they do not want to have
* to think about how many milliseconds until the cache is invalidated!
*/
QPointer<QScriptEngine> engineForStableCache;
private slots:
/** \brief Clears stableCache (from a zero-timer started in script_stable())
*
* \see script_stable()
*/
void clearStableCache ();
};
#endif // COMMONGUIEXTENSION_H