There are currently seven Microsoft Access skeleton applications to help you quickstart your journey to learning how to use and integrate the Consoul library in your applications.
Focus is on 32 bits, although the applications should be ready to run in 64 bits Access VB/A. Don't forget to download the correct bitness of the Consoul dll and place it either in the directory where you unzip the skeleton applications, or in one of the directories of your PATH environment variable.
Checking the Consoul dll existence at runtime
Each application holds a copy of the FindConsoulLibrary() function (in the MCounsoul.bas standard module), that will check the presence of the Consoul dll at runtime and alert the user if it cannot be found in the current directory or in the PATH.
Access will therefore not fail on an unhadled error if the dll is not found, because FindConsoulLibrary() is invoked before a CConsoul object is ever created, so Access still doesn't has tried to resolve the dll bindings (the "Declare"s for the Consoul dll API) that are all contained in the CConsoul class module.
Another technique would be to use the Win32 LoadLibrary API to load the Consoul dll, the drawback being that you should then take care to call FreeLibrary() before the application exits (and also do that only once).
You can download all the applications from this consoul_Skeleton_Applications zip archive that contains the following files:
Minimal Access/VBA application to display a Consoul window on an Access Form, with some helpers.
Demonstrates how to respond to a simple click message on a zone (see zones). The message routing from the Consoul dll callback to the form is handled by the CConsoulEventDispatcher class with a global instance.
Demonstrates zone painting, with the Console form implementing the ICsZonePaintEventSink interface, to draw emojis from another font.
Although the result resembles the previous application (drawing emojis) the technique used is different. Another console is present on the form (on the top) and its contents are painted in a specific zone of the console form by leveraging the CSPaintOnDC Consoul API.
Demonstrates how to use a console in virtual mode, with the Console form implementing then ICsVirtualLineEventSink interface and providing line content to the Consoul window from a string array (module level variable in MVirtualModeDemo.bas).
Same as previous sample, but with a bigger text file as the source. Left as an exercice is the wrapping of the text on a given column width, using the VT_WrapToArray() function (the text file is loaded in the DemoLoadTextFile() function).
Demoes a text search feature that highlights hits in the console and allows navigation and positioning on the next/previous hits with F3/Shift F3.
There are two core modules that are really at the core of Consoul integration in VB/A:
- CConsoul (Class)
The CConsoul class wraps the Consoul API in an easier to use class.
- MConsoul (Module)
Contains useful constants definition and facilitates VT100 output generation with the VT_xxx and VTX_xxx functions. Also contains functions capable of doing advanced VT100 string parsing (VT_RealLen, VT_Left, ...) and formatting (VT_WrapToArray, ...).
The other modules are basically helpers around the Consoul callback mechanics. Fi we want interactivity with Consoul console windows, we need a way to respond to callbacks from the dll. The functions that the Consoul dll calls back in VB/A code must reside in a standard module, but the problem is that we may have multiple console windows on a form and on multiple other opened forms at the same time.
This is a module that is used as a central callback point for all the dll callbacks. It uses a global instance of the CConsoulEventDispatcher class to route the Consoul messages for each console window, to its specific object interface implementation.
The Consoul event dispatcher class responsibility is to bridge the Consoul dll messages to their correct interface implementation. For an interface to receive its messages, it must register itself to the event dispatcher (RegisterEventSink method) and then unregister itself when appropriate (like when the form is unloaded, if the interface is implemented by the form), otherwise VB/A will not release the object referenced by the event dispatcher, which can lead to serious problems.
ICsxxxx interfaces (Classes)
These are the four different interface classes dedicated transform the different Consoul callback functions to a mechanism similar event handlers; they're needed ontly to support interactivity.
Except for the first application, all the other ones use an embedded version of the rowlistlib2 library, mainly because the CConsoulEventDispatcher class uses a CList object to maintain its list of event sink interfaces to which it dispatches the events that are collected thru the MCCallbacks module function calls.
Displaying text via global functions
Each application has a Form (named "Console", name is not prefixed) that will host a Consoul window when opened.
Displaying text (with support for Consoul's VT100 like enhancements) is achieved by calling the global ConOut() and ConOutLn() functions. Using global functions to display text in a console may be useful in some possible uses cases. For instance, you may want to use the console for echoing whatever you write in an application event log, for which you have some global LogWrite() function. You can then simply add a call to ConOutLn() in your logging function to echo the log in the console.
The Console Form implements an additional IConsoleOutput interface, that then uses a local CConsoul object to display text. ConOut() and ConOutLn() use an internal (module level) IConsoleOutput reference to drive the display action to the Console Form. This simple architecture may be already be enough for some applications, and can be anyway used as a starting point or inspiration for developing your own system.
Skeleton applications in the downloadable archive are distributed under the terms of the GNU General Public License v2.0 (see LICENSE.txt included in the downloadable archive).