A Java class that defines methods for using Lisp on Android . It contains one essential method, com.lispworks.Manager.init, which loads and initializes LispWorks. It also contains methods to set error reporters that will get called when an error inside Lisp is not caught by user handlers or when report-error-to-java-host is called, some methods to define where messages from Lisp (calls to send-message-to-java-host or format-to-java-host) go, and some other utilities.
init first checks whether LispWorks is already initialized or in the process of initializing, and if it is returns immediately the appropriate value (
STATUS_INITIALIZING). Otherwise it loads LispWorks, and initiates the initialization process on another thread. It returns before initialization finished.
The argument reporter is a
Runnable that is invoked (that is its run method is invoked) when LispWorks finished initialization. The invocation is on the main thread. The reporter in general should use com.lispworks.Manager.status to check that initializing LispWorks succeeded. Once the reporter is invoked and com.lispworks.Manager.status returned
STATUS_READY, it is possible to make calls into Lisp by methods in com.lispworks.LispCalls. If reporter is not supplied, it is possible to know that LispWorks is ready by two other mechanisms:
The argument deliverName specifies the name of the delivered LispWorks, specifically the base name of the heap and the dynamic library. See deliver-to-android-project for discussion. The default for deliverName is "LispWorks", which is the default in deliver-to-android-project, so normally you do not need it.
init returns one of the
STATUS_* constants. See the entry for com.lispworks.Manager.status.
init can be called repeatedly and it is thread-safe. The second and subsequent calls will not try to initialize it, unless the status is
STATUS_ERROR, in which case it will try again. Each reporter that is passed to
init is called independently. This is designed so if your application does not initialize LispWorks on startup, each part of it that relies on LispWorks can use com.lispworks.Manager.status to check whether LispWorks is ready, and if not call
init with a reporter, and when the reporter is invoked check that com.lispworks.Manager.status returns
STATUS_READY, and then rely on working LispWorks.
LispWorks started initializing but has not finished yet. Because com.lispworks.Manager.init is asynchronous, it typically returns this value.
LispWorks has not started initializing, that is before com.lispworks.Manager.init was called.
There was an error during initialization that prevented initialization. The method com.lispworks.Manager.init_result_code and the field com.lispworks.Manager.mInitErrorString gives more information about the reason for failure.
Return a more detailed code specifying the result of the call to com.lispworks.Manager.init. The code is either one of the three
INIT_ERROR_* constants above, or one of the codes that InitLispWorks returns.
com.lispworks.Manager.init did not find the library.
Normally that would mean it is not in the project where it should be (
libs/armeabi-v7a for Eclipse,
jniLibs/armeabi-v7a for Android Studio), or its name is not correct. See deliver-to-android-project for details.
com.lispworks.Manager.init failed to find the LispWorks heap in the assets. Normally that means that the LispWorks heap is missing from the project (it should be in assets), or its name is incorrect. See deliver-to-android-project for details.
Other values are documented for InitLispWorks. In general:
init_result_code would typically be used after com.lispworks.Manager.status returned
When there is an error, com.lispworks.Manager.mInitErrorString contains a string describing it.
mInitErrorString is set to a non-empty string if there is an error during initialization of LispWorks, which would be detected either by using com.lispworks.Manager.status or com.lispworks.Manager.init_result_code.
loadLibrary is called by com.lispworks.Manager.init, and in general you should not use it. It is supplied because it is sometimes useful for debugging.
com.lispworks.Manager.init can be called after
loadLibrary was called, and will skip the call to it in this case.
deliverName has the same meaning as in com.lispworks.Manager.init.
true on success, otherwise it returns
false and sets com.lispworks.Manager.mInitErrorString
Set error reporters that gets invoked when either report-error-to-java-host is called, or an error is not caught by your handler or hook.
setGuiErrorReporter are used to set error reporters. When either report-error-to-java-host is called (by your code, the system does not use it) or an error is not handled by your handlers (including debugger-wrappers and
report method of the interface is invoked. By default the reporters are both
Note: when report-error-to-java-host is called it is your responsibility to pass the right strings.
The reporters should do whatever you want to do. The return value should indicate if the error was dealt with completely, so there is no need to call com.lispworks.Manager.addMessage (see below).
The reporter that is set by
setErrorReporter ("the Lisp error reporter") and the reporter that is set by
setGuiErrorReporter ("the Lisp GUI error reporter") differ by the scope in which their
report method is invoked:
reportmethod of the Lisp error reporter is invoked within the scope of the error, which also means it can be any thread. It is therefore cannot do anything related to the GUI, and needs to be runnable on any thread. In general, it should only set internal variables and return, but it may also do things like copying the log file somewhere.
reportmethod of the Lisp GUI error reporter is invoked outside the scope of the error, on the GUI thread. It is done by the event loop of the GUI thread, so it is also synchronous with respect to processing events. It can therefore safely access the GUI and perform what is needed to inform the user that an error has occurred.
setGuiErrorReporter can be called at any time, before or after com.lispworks.Manager.init. There is only one Lisp error reporter and one Lisp GUI error reporter, and each call to
setGuiErrorReporter overwrites the previous value. The reporters can be set to
null, invoke its
null, arrange for its
reportmethod to be invoked on the GUI process, and does the next 2 steps after this invocation.
true, use com.lispworks.Manager.addMessage to append the error message. See documentation for com.lispworks.Manager.addMessage.
The log files are deleted when LispWorks starts (when com.lispworks.Manager.init is successful). They are also in the internal cache directory, which means they are not visible to other applications. If you want to make the logs visible, the reporter needs to copy the file to an external directory.
LispWorks keeps a record of error reports containing the error strings and the file names containing the log (the arguments the
report method of com.lispworks.Manager.LispErrorReporter received).
clearBugFormLogs eliminates all entries except the last count entries, and removes the files.
The record is limited to com.lispworks.Manager.mMaxErrorLogsNumber, which defaults to 5.
The record can be displayed by com.lispworks.Manager.showBugFormLogs, which allows the user to open the log file of a record by selecting it.
The log files are also automatically deleted when LispWorks starts (that is when com.lispworks.Manager.init is successful).
The default value of 5 is a compromise between keeping many logs (in case some are useful) and avoiding filling the disk. During development you may want to enlarge it, and in the finished product maybe reduce it, possibly to 0.
showBugFormLogs shows a list of the
BugFormLogs, where each item is an error string, and allows you to open the associated log file by touching the item. If there is only one item, it opens it immediately.
The bug list is displayed in its own activity, com.lispworks.BugFormLogsList, and the log file is opened to another activity, com.lispworks.BugFormViewer. To make
showBugFormLogs work, you must add these activities to the file
AndroidManifest.xml in your project like this:
There will not be any bug form logs if there was no error, or com.lispworks.Manager.mMaxErrorLogsNumber is set to 0, in which case
showBugFormLogs does nothing. It is also possible for the user error reporters (see com.lispworks.Manager.setErrorReporter) to delete the log files, so com.lispworks.BugFormViewer will fail to show it.
The actual meaning of adding a message is either to call the message handler if it was set by com.lispworks.Manager.setMessageHandler, or put the message in the output text view if it was set by com.lispworks.Manager.setTextView, if neither the handler or the view are set, then
addMessage accumulates the messages, and inserts the text next time that that com.lispworks.Manager.setTextView is called.
The operation of
addMessage is first to check whether the handler is not
null, and if it is call the handler with the two arguments. If the handler returns
addMessage does not do anything else. Otherwise, if there is a textview it adds the message to it, otherwise it adds the message to its own buffer.
The where argument needs to be one of the four
ADDMESSAGE_* constants, and determines how the message is added.
addMessage to first clear the textview or the internal string before adding the message.
ADDMESSAGE_PREPEND mean adding the string in the end or the beginning respectively of the textview or internal string. By default, when adding the string to a textview,
addMessage causes it to scroll such that the top of the message is visible.
ADDMESSAGE_APPEND_NO_SCROLL does like
ADDMESSAGE_APPEND but without ever scrolling.
addMessage is used by LispWorks to perform the operation of send-message-to-java-host, and to report errors which are not dealt with by the error reporters. You can use it when it is useful.
The call to the handler is done on the thread on which
addMessage is called, so the handler must be able to cope with being called on any thread, and needs to be thread-safe. The access to the textview or the internal string is done on the GUI thread and is thread-safe.
mMessagesMaxLength limits the length that
addMessage accumulates. The length of the text that
addMessage accumulates, either internally or in the
TextView, is limited to the value
mMessagesMaxLength (default 10000). When appending causes the length to overflow this value,
addMessage removes the beginning of the old accumulated text so the total is the limited to
mMessagesMaxLength. However, it does not remove part of the message itself, so calling
addMessage with a string longer than
mMessagesMaxLength will cause the
TextView or internal string to be longer than
mMessagesMaxLength (the old text would be removed completely in this case).
Sets the message handler which com.lispworks.Manager.addMessage uses.
When the handler is not
null, com.lispworks.Manager.addMessage calls the
handle method with its arguments. The result tells com.lispworks.Manager.addMessage whether to deal further with the string, see its reference entry for further details.
Sets the textview for com.lispworks.Manager.addMessage.
The textview defaults to
null and can be set to
null. When it is
null, com.lispworks.Manager.addMessage accumulates the message.
setTextView is called, if there is already a textview it takes the content first and puts it in the buffer of com.lispworks.Manager.addMessage. If the new value textview is not
null, it puts into it the buffer of com.lispworks.Manager.addMessage and clears the buffer. This is designed such that you can set the
TextView to another
TextView or to
null without losing text.
The intention is that
TextView makes it easy to display messages that come from Lisp. In a fully-developed product you probably want a better mechanism, by setting the message handler with com.lispworks.Manager.setMessageHandler.
There is no expectation by
setTextView or com.lispworks.Manager.addMessage about the properties of the
TextView except that it is possible to add text to it and delete all the text from it. You can manipulate it yourself (for example delete all the text, or all the text except the last 100 lines) while is set.
setTextView can be called on any thread, and is thread-safe. The manipulation of the
TextView by com.lispworks.Manager.addMessage is always done on the GUI process,
Return the application context of the context that was supplied to com.lispworks.Manager.init, and the
ClassLoader associated with it.
These are utility methods that LispWorks itself uses and you may find useful. They must be called only after com.lispworks.Manager.init was called.
Sets the current activity that can be used inside Lisp using android-get-current-activity.
The argument activity must be the current active
null. The Lisp function android-get-current-activity returns this activity.
setCurrentActivityis effectively licensing the Lisp side to raise dialogs in the current activity.
setCurrentActivityshould reset it by calling it with
onPausemethod, to ensure that they are not used after they are no longer visible.
setCurrentActivityonly affects what android-get-current-activity returns. Code that gets the
Activityin other way will not be affected.
LispWorks User Guide and Reference Manual - 13 Feb 2015