newObjects Active Label VisiLabel programming
Object references
Graphical objects
Other reference topics
File and command formats
Active Label object model
Dynamic downloads/uploads

newObjects Active Label ActiveX control is a visual ActiveX control designed for usage on WEB pages and in ActiveX host applications. Its functionality can be explained as such as of a simple report generator or design application. Active Label can show and print independently labels and other single page small format materials. It enables the user put, arrange and format a variety of graphical elements on them: barcodes, text labels, text boxes, images, shapes. Each of the elements put on the label is accessible as object as well as the Active Label ActiveX and its service objects. This enables both DTHML pages and ActiveX control host applications to fully control the appearance and behavior of the ActiveX.

Therefore the Active Label ActiveX is an almost complete application enclosed in in-process ActiveX DLL. The applications can use it to implement everything from the interactive design to the printing without need of complicated code. 


The ActiveX ClassID is: {09A02CEE-410B-47BA-A837-E62C9C8D70BF}
ProgID: newObjects.comctl.VisiLabel
Comments: The Class ID and ProgID above are for the root object in the Active Label object model. All the other objects and label elements are accessed through this hierarchy - i.e. the application/page creates the root object and through it it manages the rest of the objects and elements.
On a HTML page the object is created with code like this:

<OBJECT ID="VisiLabel1" CLASSID="CLSID:09A02CEE-410B-47BA-A837-E62C9C8D70BF">

Where the ID attribute specifies a reference name that can be used further to access the created object. In this documentation we will most often use in the example code lines VisiLabel as reference name thus assuming that we have created an Active Label control with ID="VisiLabel". In other applications, such as applications written in VB, C++, Delphi, .NET languages the creation is done with the corresponding methods the language/tool offers. Further the usage of the created ActiveX does not differ much in the different environments except for the syntax and the techniques for the particular language. Thus we will present any example code in Javascript assuming that the ActiveX is in a HTML page, but what they illustrate is also applicable for the other applications except a few specific features.

Features guide

In this section we will explain in short the Active Label features and point out the chapters in the documentation that describe them in detail.

The Active Label is not a single-object ActiveX it has an internal structure represented by many objects. See the Active Label object model for diagram and details. All the internal objects are accessible through the Active Label's root object VisiLabel. As an ActiveX designed for the WEB Active Label has many features to support standards and operations related to the WEB programming. In many aspects the ActiveX is very similar to the Microsoft Internet Explorer itself - the object model, the behavior of the elements on the label, the ability to download and upload data dynamically. Once put on a HTML page the Active Label ActiveX becomes a naturally looking extension of the HTML page - a special part of it that can perform tasks the page can't do or can't do the way you want. Among other things this includes the independent printing where Active Label can print multiple copies of the same label or set of labels driven by data arranged on pages (see VisiLabel.Print, Label object and Page object). Here are  the feature highlights and links to the overview and reference pages about them:

Instantiation and initialization. Once created the Active Label can be initialized in many different ways:

Text commands passed in a set of PARAM elements between the opening and closing OBJECT tags.

Programmatically by setting the VisiLabel.Src property or calling VisiLabel.Reload thus instructing the object to initialize from an URL or a physical path.

Using a single PARAM element between the opening and closing OBJECT tags:
<object classid="clsid:09A02CEE-410B-47BA-A837-E62C9C8D70BF" id="VisiLabel">
<PARAM NAME="SRC" VALUE="somelabel.activelabel
Which is equivalent to setting the VisiLabel.Src property programmatically but does not require separate code to do that - it is done during the creation of the control.

Using DATA attribute of the OBJECT element:
<object classid="clsid:09A02CEE-410B-47BA-A837-E62C9C8D70BF" id="VisiLabel" DATA="label.activelabel"></object>
Which is much like the previous but the difference is that with DATA attribute you instruct the browser to load the data and pass it to the ActiveX while in the previous case the ActiveX does this alone. Note that DATA attribute may not work properly with some custom protocols (others than HTTP and file). 

Partially (meaning change some settings, add data) through VisiLabel.MergeSrc for example.

Programmatically by passing the data on your own. This is done through the VisiLabel.TextCommands property.

In applications built in C++ and other sophisticated environments with lower level COM capabilities by using the standard IPersistStreamInit or IPersistPropertyBag interface.

In all those cases the initialization data format can be the same - see the Data, file and command formats.

Extracting the label design data and settings, saving or uploading the label. The application can obtain the label data and preserve it for future usage (for example to use it for initialization of the ActiveX on other pages). Because the ActiveX supports interactive editing this is needed when you want to preserve the label design and settings made by the user.

Obtain ready-to use HTML code for OBJECT element with text commands in set of PARAM elements - see VisiLabel.ObjectParams.

Obtain text commands as string from VisiLabel.TextCommands.

Upload the label data to an URL. See VisiLabel.Dst and VisiLabel.PostData. The upload and download functionality is explained in depth in How to Download and Upload.

Printing. The Active Label prints the label configured in it by placing series of labels on the pages.

Printing is initiated through VisiLabel.Print method. The ActiveX prints copies of the same label or set of labels over the specified data set (see below about the data connectivity) from left to right and from top to the bottom (as shown above). The size of the page and the settings that affect how the labels are arranged are specified through the properties of the VisiLabel.Page object (see also the figure above).

Each label has the same size and margins which are controlled through the VisiLabel.Label object. The figure below shows the main settings:

The elements on the label. On the label you can put any number of these elements:

Barcode. Support most of the standard 1-d barcode symbologies used today.

Image. Picture in almost any popular image format. Supports transformations, smart sizing and dynamic download/upload. The element behaves like the <IMG> elements on a HTML page, but in addition they can also be uploaded separately to any URL (with or without transformations applied over them). For downloading/uploading see How to Download and Upload.

Simple text label. A text line which can have specific font, orientation (can be rotated) and other characteristics.

Text box. A multiline text which may have specific font and other characteristics.

Symbol. Much like text labels, but this object offers a bit different interface which makes it perfect for placing sole symbols from symbol fonts.

Simple shape.  Simple shapes such as lines, ovals, lines and rounded rectangles. Can be filled or transparent.

The labels are designed by using one or more of those elements placed on the label surface. Almost any property of any of the elements can be linked to the data set thus allowing the application print sets of labels where each label obtains the desired characteristics from the fields in the data set.

Data connectivity and data sets. Apparently we need the ability to print sets of labels over a set of data - changing barcodes, text labels according to the fields in a data set for example. To accomplish this Active Label supports two methods for binding data with the label. Both are controlled by the VisiLabel.Variables object which has a recordset-like behavior.

External data base connection. Version 1.0 allows you configure any ADO compatible database connection string and execute any supported by the database on the other side SELECT query over it. The data obtained this way is used as data set over which the label sets are generated and printed. The application can also enable the user to navigate through the data set and see the preview of the label for each record (see VisiLabel.Variables.UpdateLabel for instance).

Internal cache. It is actually a 2-d array managed internally by the VisiLabel.Variables object. It provides the same functionality (even extended functionality in fact) over it as in the case of external data base. The difference is that this internal cache is auto-configured to match the record structure specified by the application by configuring fields (Field object) into the Variables object (see also VisiLabel.Variables.AddField). Further the data in this cache can be filled in different manners:

As part of the label initialization putting CACHEDATA entries containing the field values into the initialization data (see above). This can be used with any of the supported initialization techniques.

Programmatically at run-time using the Variables object (see VisiLabel.Variables.Update, VisiLabel.Variables.AddNew) by setting the values of its fields (each is represented by a Field object) and adding new records as needed.

By downloading data from an URL - see VisiLabel.MergeSrc.

As you can see above the internal cache can be filled by putting PARAM entries in the OBJECT tag, or by the server-side script that extracts a stored label from your database appending it with CACHEDATA entries, or by separate server side script that generates only such entries. This means that you can use the same techniques you use for outputting WEB pages in your application (no matter what the language is - ASP, JSP, PHP or anything else). Note that this is most often the easiest way because the WEB pages of your application will most likely need the same data or part of it for other purposes as well. Thus the work you need to do is practically the same - you just need to format the output to match the CACHEDATA entries syntax which is almost always as simple as printing a formatted string.

Linking the data to the elements. No matter what kind of data source is used the linking works the same way. Each Field object has two properties that specify which element on the label is controlled by it. These are Field.Element and Field.Property and they specify the name of the element and which property of the specified element to fill with the data in the field when the data set is navigated. The ActiveX provides also user interface that can be used for that purpose - for example each element has a Data connection property sheet.

The limitation caused by this approach is that one data field can be linked to only one element and only one of its properties. Most often this is enough and if it is not the duplication of a field is not difficult - you just need to configure two fields that will be filled with the same values or if you use external database duplicate the output in the query. 

Interactive editing. The Active Label ActiveX implements the full set of features needed for interactive editing. The application or WEB page that hosts the control needs to do very little to incorporate full interactive label editing. For instance it needs to provide a few user interface elements such as buttons that create new elements on the label, some other elements that would provide the user with convenient way to control some of the general control view settings (such as zoom for example) and some UI elements to invoke load/save operations for example. Most of the work is done by the control itself and the application/page needs to implement only some simple method calls or change certain properties in response to the user actions. The control implements many property sheets that implement suitable user interface for managing the settings of the entire control and its elements - see the ShowProperties methods of each object. Although every developer will have his/her own opinion about how such user interface should look having it saves the need to implement such. Of course if you want to provide alternative way to manage some of the settings you can do so in your application/page, but every time you need to hurry you can simply provide means for opening the control's property pages without spending efforts on this. Later if the time permits it you can add more pretty-looking replacements for the parameters most often used in your case.

Active Label provides methods that allow the user to draw the frame or click the location where a new element is to be created - see VisiLabel.Edit.IntereactiveNew and VisiLabel.Edit.IntereactiveCancel. Sometimes it is preferred to create the new elements at predefined locations and then allow or not allow (as appropriate) the user to change them. You can use VisiLabel.CreateElement to do that. The interactive mode is controlled by the VisiLabel.Edit object, the VisiLabel.Edit.EditMode property switches between view and edit mode. In edit mode the user can also use the keyboard to change the selection or move the selected element, or invoke its property sheets by double click or pressing Enter. The keyboard shortcuts are described in the ActiveX UI help file (which can be also invoked from any of the control's dialog boxes).

Through the property pages of the Active Label objects the user has access to the connectivity options - see the Load and Save property pages. For example if the user opens the property pages of an image element he/she can load an image in it from any location. These property pages also give the user means to upload data, but this is, of course of little use except for the administrators and the developers because the user must know where to upload. Therefore the saving/upload of the label or the elements on it should be simplified by the application/page that hosts the control. This means that the application should configure the control for upload and minimize the information that needs to be supplied by the user. For example an WEB application can just provide a button that the user clicks. In response to this the page on which the control resides can invoke upload of the images on the label and then the label itself to the URL on which resides the application's label repository script/module which is of course known to the page when it is loaded. Thus the user is simply required to click a button and the rest of the work can be done without need of more user interactions. The developer should notice that the upload of a label with images requires a bit more attention - the page needs to upload the images, if everything is ok update the references into the label to the locations from which the saved images can be obtained from that point further and just then upload the label. The Active Label ships with some examples that illustrate this. Typically it requires 10-20 lines of Javascript code to invoke the operation and handle the OnPostCompleted event. The other side (on the server) is quite simple as well. In contrast to the file upload implemented by the browsers the Active Label uses simpler mechanisms which require no additional components or libraries on the server and almost all of the work the script/module needs to do is to check a few URL arguments and decide where to put the received data depending on the applications structure. See the next section or go directly to the How to Download and Upload for more specific information.

Connectivity. This has been mentioned in the other sections. Lets summarize the connectivity capabilities of the Active Label:

Download/load: The VisiLabel object, the Image element and the Text (box) element support common features available through their Src property and Reload method. The entire label (through the VisiLabel object) or the image displayed by the image element, or the text displayed in a text element can be downloaded dynamically from a local or remote source through any URL protocol. The download is asynchronous (except while printing) and the application can stay unformed about the the result of any such operation initiated by it by intercepting the VisiLabel object's events - see OnDownloadCompleted. By "dynamic" we mean that changing the Src property of the objects that support it invokes an immediate download of the data pointed by the new URL put into the property. This is just like the IMG element in MS Internet Explore.

Upload/post. The VisiLabel object, the Image element and the Text (box) element support common features available through their Dst, PostVerb, PostParams properties and the PostData method. The label (through the VisiLabel object) or the data of the individual Image or Text elements can be uploaded/posted to the URL put into the Dst property. The operation proceeds asynchronously and the application can keep in touch with the results by handling the VisiLabel object's events - see OnPostCompleted

The details about the download and upload operations are discussed in How to Download and Upload.

A question you may ask: If it is possible to upload the label or some of its elements separately to any URL is it possible to save them to the local file system?
The answer is not simple: A C++ application that hosts the control can use the IPersistStreamInit supported by the VisiLabel object and the Image and Text element objects to direct the data to a file stream. However from a script on a WEB page this is not possible for security reasons. Still, if you use a solution like Active Local Pages (ALP) you can save the data locally by posting to an URL and writing an acceptor script which will do the actual file writing. Solutions like ALP work like WEB servers but they are doing everything locally only imitating network functionality. Thus the code you will need in such an environment will be the same as on a WEB server that supports the same programming language (in the ALP case you can use ASP). Obviously it is not appropriate to allow data from the control to be saved directly to the disk, because this will enable any WEB page to mess with the local file system and to avoid this a complicated security mechanisms would be required.







newObjects Copyright 2001-2006 newObjects [ ]