After taking apart our Optimus mini three keyboard from Art. Lebedev studio, we thought it might be fun to write a plugin for the Configurator software. We discuss that effort here, so if you would just like to download our plugin for the Optimus Mini Three, you can find it at the end of this article.

Art. Lebedev’s Configurator offers a very simple DLL-based C++ plugin API. The company provides one simple plugin example that exercises most of the API’s features. The API header and example plugin source code can be found here.

A Configurator plugin is simply a DLL that exports just one function: Create(). This factory function instantiates a class of type OptimusMiniPlugin via new and returns it. Configurator then works directly with this object through a few virtual public methods defined in the OptimusMiniPlugin class. COM experts will be quick to note that this is a rather limiting architecture. Only compilers and languages that create VTABLEs compatible with Microsoft Visual C++ objects can be used to develop Configurator plugins.

NOTE: As of v1.0.28b, Configurator does not delete the instantiated plugin objects when shutting down, so the Visual Studio debugger reports a memory leak. The memory is recovered by Windows when the application terminates, but it can be disconcerting to see leak reports.

A developer begins writing a plugin by starting a DLL project in Visual Studio. The example provided by Art. Lebedev uses MFC’s facilities for working with dialog boxes. If MFC is desired, an “MFC Extension DLL” project should be started; otherwise, a standard Win32 DLL will suffice. Within the DLL project, a developer creates a new C++ class that publicly inherits from the OptimusMiniPlugin class. This class defines three pure virtual methods that a plugin writer must implement:

virtual LPARAM GetInfo(int index) = 0;
virtual BOOL Paint(int button, HDC hdc) = 0;
virtual void OnKeyDown(int button) = 0;

Configurator calls GetInfo() shortly after instantiating the plugin object to retrieve information about the plugin’s name, version, icon, author, etc. Configurator uses some of this information to provide a consistent “about” box for each plugin—complete with click-able URLs:

Configurator calls Paint() about 3 times per second, which gives the plugin an opportunity to update the OLED display on the Optimus mini three keyboard. This function is passed a handle to a device context, so the plugin can use standard GDI methods to render the desired image. The GDI is not the fastest way to draw, especially when animating; however, it’s quite sufficient for a 3FPS update rate. If a future version of the Optimus Mini Three offers faster framerates, Art. Lebedev may wish to consider offering a DirectX interface.

Finally, when a user presses the key with which a plugin is associated, Configurator calls that plugin’s OnKeyDown()method. The plugin can then execute an action in response to the user’s press.

The OptimusMiniPlugin class also defines the following virtual methods and their default implementations:

virtual BOOL GetProperty(int index, char *name, char *value){ return FALSE; }
virtual BOOL SetProperty(const char *name, const char *value){ return FALSE; }
virtual BOOL ShowProperties(HWND hwnd){ return FALSE; }

These are used for storing settings and allocating/freeing resources upon plugin load/unload. The ShowProperties()method passes in an HWND to the Configurator’s main window so that a plugin’s preferences dialog can be modal with respect to the Configurator. The sample plugin source code provided by Art. Lebedev illustrates the usage of these methods, so we won’t describe them further.

Seemingly concerned with their product’s perceived stability, Art. Lebedev has wrapped all calls to plugin methods with Microsoft-specific Structured Exception Handling try-except statements. These give the Configurator the ability to trap exceptions from poorly-written plugins. When a plugin call crashes, the Configurator catches this, dims the last image that the plugin successfully drew, and overlays a frowning triangle to indicate that the plugin has misbehaved.

While this is nice for production, it makes development debugging a plugin rather difficult as the exception is trapped and quashed without conveying meaningful information to the developer. Plugin developers would prefer an option to turn this off or a special developer version of the Configurator with this exception handling disabled.

We poked around the Configurator quite a bit and noticed that many of the included plugins link against “utility.dll”, which resides in the same folder as the Configurator executable. This, along with a few other DLLs provide classes such as CTextRenderer, CFileImage, and CWebFile. These appear to be classes that Art. Lebedev has developed to facilitate text/image handling and fetching of files via HTTP. Perhaps Art. Lebedev will eventually publish the appropriate header files for these so that plugin developers can take advantage of those facilities. In the meantime, almost everything but the communication with the Optimus Mini Three hardware is left up to plugin developers.

The MTScreenCap Plugin

For our first Configurator plugin, we decided to implement a better “Print Scrn” for Windows. Mac users have the luxury of an obscure key combination that will save a screen shot to a PNG file on the desktop. Windows users have the dedicated “Print Scrn” key for taking screen shots, but these go to the clipboard rather than directly to a file. We thought we might like to be able to assign an Optimus Mini Three key for grabbing screen shots to JPG files.

There was the question of what this plugin should display on the actual OLED key. We settled on having a “live” (updated about once a second) preview of the current screen capture. This turned out to be more entertaining than we anticipated. With the default settings of capturing only the foreground window, we thought it was fun to watch the image jump around on the Optimus Mini Three key as we navigated through applications.

You can download our free plugin at the bottom of this page. Note that this was an educational effort rather than an engineered software product, so the plugin may come with a few bugs. If you find any, you’re welcome to report them to us, but please understand that it is unsupported software. Here are some of the features the plugin offers and a screen shot of the settings dialog:

• Live preview of the current foreground window or the entire desktop, updated about once per second. This can be disabled, in which case the plugin displays the last screen shot taken.
• The plugin can be assigned to more than one Optimus Mini Three key, or it can be assigned with modifier keys. Each instance can have separate settings. For example, you could have the plugin normally capture the entire screen and capture just the foreground window when ALT is held. This would mimic the built-in Windows “Print Scrn” functionality.
• The plugin replicates the functionality provided by “Print Scrn” and handles multiple monitors and partial off-screen windows similarly.
• The plugin can automatically save the capture screen shots to time-stamped files in a folder of your choice, or it can ask you where to save each file.
• The plugin saves the files in JPG format with user-selectable quality.

To install the plugin, unzip the downloaded package and run “setup.exe”. We recommend letting the installer put the plugin in your Optimus plugins folder, which is usually: “C:\Program Files\Optimus mini Configurator\Plugins”. The installer will try to add the appropriate registry keys to register the plugin with Configurator; however, if Configurator is running, you will need to exit and reopen it before the plugin appears. If the MTScreenCap plugin still does not appear in the list of available plugins, try adding it manually with the “Add Plug-in…” button.

We found plugin development for the Optimus Mini Three Configurator to be simple and straightforward. Check back later as we might develop more!

Download the MTScreenCap Plugin below:

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT OF THIRD PARTY RIGHTS. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Version 1.0.2 includes an installer and works with Configurator 1.0.30b:
I Agree to the Above [ MTScreenCap_1.0.2.zip (5.11MB) ]

Tags: optimus, plugin, software

This entry was posted on Thursday, November 30th, 2006 at 10:39 pm and is filed under MindTribe Tech. You can follow any responses to this entry through the RSS 2.0 feed. You can leave a response, or trackback from your own site.