Editor's note: this article is contributed by Shawn Pleska, a veteran
PowerBuilder programmer who can be reached at <shawnpleska@yahoo.com>. We thank Shawn for this excellent
contribution.
If you'd like to contribute to the tech library, write to <support@morovia.com>.
Morovia, through the Morovia font-tools DLL, provides ease-of-integration with Sybase's PowerBuilder development toolset allowing many barcode types to be seamlessly generated from within PowerBuilder-developed applications. The purpose of this document is to create an understanding within the PowerBuilder development community on how to implement the Morovia Fontware products and the code necessary to enable those products within a PowerBuilder development environment.
Morovia enables the generation of variable-height barcodes within applications by providing two key components: (1) a series of true-type fonts that correspond to a specific height and type of barcode and (2) functions that generate a string result set based on a requested barcode value that when assigned to a field with the corresponding font, creates a barcode that matches the type and value requested. This two-step process enables PowerBuilder developers to continue utilizing the power of Sybase's patented data window technology while unleashing the means to imbed barcode values for display and printing within.
This tutorial is broken down into two components. First, steps necessary to enable the Morovia Fontware for development purposes are detailed. Second, steps required for deployment of applications written in PowerBuilder that include Morovia Fontware barcode capabilities are detailed.
In order to equip developers with the means to imbed barcode-generation features within an application, follow these few simple steps:
Since Morovia Fontware utilizes custom fonts to generate and display barcodes, the first step is to ensure that the required fonts are installed on the computer being used for development. For instance, the fonts available for use to create UPC-A, EAN, and Bookland barcode values include: mrvUEBma, mrvUEBsa, mrvUEBta, mrvUEBxsa, mrvUEBxta. You can check to see if these fonts are already installed by going to the Control Panel and selecting Fonts.
If the necessary font files are displayed in the list, skip this step. If they do not display in the list, this step explains how to install them. Note: Depending on the setup of the computer, administrator rights may be required to install fonts. With the correct security settings, installing fonts is a simple process. From within the Control Panel...Fonts screen, click on File and choose the option Install New Font. This will bring up an ADD FONTS explorer-style navigation window from which you can navigate to where the font-files exist on your system or network. Once the true type fonts display in the list, you can highlight the ones you need in the list by holding down the control key and clicking those needed or to select all, click on the select all button. Once the needed fonts are highlighted, click OK to add the fonts to your system. (See Ref. B)
Open Windows Explorer and navigate to c:\program files\common files\morovia\moroviaFontTools folder.
Once in this directory, search for file mrvFontTools.dll.
This file (the Morovia font-tools dll) must exist in the system directory
in order to define and call the needed external functions that
generate the string value that the fonts interrupt when creating
the barcode
If the Morovia Font Tools dll
(mrvFontTools.dll) already exists,
skip this step. If it does not, download the setup for Morovia
font-tools from http://www.morovia.com/font/support/download-fonttools.asp and run the setup to install the necessary files on your system.
After setup is complete, file mrvFontTools.dll will exist in the c:\program files\common files\morovia\MoroviaFontTools directory.
The installer also installs other support tools, such as
encoding function source code in C/C++, JavaScript, Pascal languages.
You can import the source code files into your project if you are
working with these languages. We only need the
Font Tools DLLfor our project.
With the fonts successfully installed and Morovia font-tools present, you are ready to add the code components that allow PowerBuilder to interface with Morovia's font products. Generating the interface requires that an external function be defined where most appropriate for your application. External functions can be defined locally to an object or globally to the application. Most recommendations encourage limiting use of global definitions in application architecture. If using the PowerBuilder Foundation Class, we recommend considering the application manager (n_cst_appmanager) as the most appropriate place to define the local external function. This makes the function calls available to all client code. Otherwise, creating the local external function can be done in windows and objects as needed. Creating an external function is done by opening the object in which it will be created, going to the Declare Instance Variables tab, then selecting the dropdown that shows Instance Variables and choosing instead Local External Functions (or Global External Functions if you prefer). (see Ref. C)
Define the functions to be used from the Morovia font-tools product. Once the external functions are added, save the changes. (see Ref. D). All encoder functions take a string as input and return the barcode string. Note that the function names are case sensitive and must match the ones in the DLL. For more information visit KB#10011.
Some function prototypes are listed below:
Function string UPC_A (ref string lpString) library "MRVFONTTOOLS.DLL" Function string EAN13(ref string lpString) library "MRVFONTTOOLS.DLL" Function string Code128C(ref string lpString) library "MRVFONTTOOLS.DLL"
Warning
In PowerBuilder 10 and above, strings are in Unicode and the prototypes must be modified so that conversion between Unicode and narrow strings is performed. You need to append Alias For at each declaration, as illustrated below:
Function string UPC_A (ref string lpString) & library "MRVFONTTOOLS.DLL" Alias For "UPC_A;Ansi" Function string EAN13(ref string lpString) & library "MRVFONTTOOLS.DLL" Alias For "EAN13;Ansi" Function string Code128C(ref string lpString) & library "MRVFONTTOOLS.DLL" Alias For "Code128C;Ansi"
In order to generate a barcode within a data window, open a data window and identify the fields or fields that will do so. Click on the first field and identify what its current font is defined as. Change the font of the field to be the most appropriate of the Morovia fonts previously installed to the system in step 2. (See Ref. E)
Within the code of the object responsible for creating and populating the values to be displayed in the data window, code must now be added that calls the appropriate external function with the barcode value needed. Calling the function returns a string value that should be populated into the field with the barcode font. This string value identifies for the font how the value should be displayed. If done correctly, the barcode in question should display as desired. Ref. F shows our sample window in development with the data window, a button for calculating the barcode, and a string value to the right of the button. Ref. G shows the code that will execute when the button is clicked. A UPC barcode value of 245792150797 will be passed to function UPC_A, the return string value will be captured on return, and the string value returned will be applied to field barcode_upc (defined with the UPC font). Ref. H shows the results of processing while running the window in development, after clicking the Calculate Barcode button.
Redistribution of Morovia Fontware products within PowerBuilder applications requires appropriate licensing from Morovia Corporation. Once proper licensing is obtained, there are additional terms of the licensing that must be met in order to fulfill your legal obligations under the agreement. Meeting the requirements involves registration of the fonts at runtime on the client computer and de-registration of those same fonts upon termination of your application on the client's computer. The following steps detail how these requirements can be met within PowerBuilder.
Define two external functions within your application that interface with the windows API and allow fonts to be dynamically registered and de-registered as needed. Ref. I shows these declarations.
Define a function within the application that can be called at the time the application runs and at the time that the application is being closed. Ref. J shows an example of such a function along with the code to be used to register and unregister fonts using the Windows API calls previously declared in Step 1 as external functions.
Call your function (the one you created that is similar to what was just shown in Ref. J) with a value of TRUE when the application is first run (possibly the open event of your application object or the pfc_open event of n_cst_appmanager if using the PFC) and call your function with a value of FALSE when the application is being closed (possibly the close event of your application object or the pfc_close event of n_cst_appmanager if using the PFC). This will register your fonts temporarily for use within your application at runtime, release the fonts when the application closes, and in so doing fulfill the licensing obligations in place between your company and Morovia.