newObjects Active Label VisiLabel object

The VisiLabel object is the root of the object hierarchy of newObjects Active Label. It maintains the drawing surface on which the drawing objects are shown, various settings, drives the printing and connects the internal data source with the drawing objects. The application code  accesses the other internal objects by using certain properties or methods of the VisiLabel object. As you can see below most of the visual properties and printing parameters are accessible through a helper object and not directly through the VisiLabel object itself. This is so because the number of parameters is big enough to make their usage inconvenient if exposed by a single object.


Members reference:

Edit Provides access to the interactive editing mode parameters and methods. The application actually needs this object if it wants to allow the user to visually edit the label elements and layout. In applications that use Active Label ActiveX to show, and print pre-designed labels this object is rarely needed.
Label Provides access to the label format and appearance properties. Through this object you can set the label size, margins, border, background and so on.
Page Provides access to the page setup properties and methods. You can specify the details about the placement of the separate labels on the paper, the page size and margins in this object
TextDefaults Allows the application to set/get the text related default settings, such as default font, charset and so on. These settings are mostly useful when the application prepares empty or template label for interactive editing. The default settings may save the user some efforts to specify every detail about the graphical elements he/she adds to the label.
Misc Other general properties and methods, such as enabling/disabling the data source, changing the measurement units and so on.
Variables The internal data source. This object offers an interface very similar to a typical recordset and like such it supports varying number of Field objects the application can configure in it.
The role of the Variables object is to connect the data with the drawing objects. The object supports internal cache which can be controlled by the application. This allows the developer to develop with minimal efforts various data driven scenarios no matter what is the nature of the actual data source. 
ElementCount Long integer. Returns the number of the drawing objects in the label as an integer number.
count = obj.ElementCount;
Element Object,Default, indexed property. Returns the specified drawing object (element).
el = obj.Element(name_or_index);
el = obj(name_or_index);

name_or_index - a string or an integer. It specifies the name or the index of the drawing object to be retrieved.

If the index is less than 0 or greater than the ElementCount - 1 or if the name is not found an error will occur. 

ObjectParams Returns a text that contains the HTML code for the object in its current configuration. This code can be put directly in a WEB page, ASP page, JSP page etc. The code contains the <OBJECT> tag and a number of <PARAMETER> tags containing the settings and the parameters of all the drawing objects. See Data, file and command formats for details about the settings.
s = obj.ObjectParams;
This property returns all of the settings of the ActiveX including the drawing objects/elements currently on the label. It is usually used by applications that allow the user to change the label layout and content and want to save the label in a WEB page compatible form or enable the user to grab the HTML code and put it manually in a HTML page.
Note that the property will include the Variables object settings and the parameters of all of its Field objects, but not the content of the cache. If you want to include the content of the cache you will need to set the Variables.SaveCache = true.
Caption The label caption read/write. When the label or its element is uploaded the label caption is automatically appended to the URL parameters of the upload operation.
s = obj.Caption
obj.Caption = s
The caption is not shown anywhere on the label itself. You can treat it as a name of the label which you can use for purposes you choose. A semi-unique name is generated each time a new label is created (when the ActiveX is instantiated or after calling the Clear method. However, the algorithm is very simple (based on the system up time) and the name is not truly guaranteed to be unique in contrast to the LabelUID parameter (which is generated in the PostParams property when the new label is created). Most applications do not need unlimited number of label designs. Therefore it is often convenient enough to force the user to choose appropriate and descriptive name for the label before saving/uploading it. Checking for duplication or silent replacing in the application label repository/database will solve any problems with the uniqueness.
TextCommands Read/Write, String. Returns all the label settings as a string containing multiple text commands. When written executes the string passed to it as text commands. See Data, file and command formats for details about how the settings and elements are represented as text commands.
s = obj.TextCommands;
obj.TextCommands = strCommands;

As you already know the label can be directly uploaded to a server or you can extract its settings in HTML format - as <OBJECT> element. However some applications may want to deal with the ActiveX in more customized way. In such case through this property you can obtain the label design encoded as series of text commands each ending with new line. From that point further you can do with the returned commands whatever you choose - save them post them through a HTML form etc. Furthermore you can execute such command(s) over the ActiveX by putting a string containing such into this property. You can put a single command or series of commands (each on a separate line) as appropriate for the task you want to accomplish. The executed commands will affect only the settings or elements controlled by them. Thus for example a SHAPE command will create a new shape element on the label, while a LAYOUT command will update the label size and its other settings. This enables you to apply changes or add settings. This property is particularly useful for adding data entries (see CAHEDATA command) to the label before printing in applications that want to pass the data in their own way.
ShowNavCursor Boolean. If set to true instructs the ActiveX to change the mouse cursor to hand whenever it is placed over an element with non-empty Href property. Default is false.
objVisiLabel.ShowNavCursor = true;
curMode = objVisiLabel.ShowNavCursor;

This has effect only if the ActiveX is not in interactive editing more (see Edit.EditMode).
Stock properties (affect the ActiveX work area - outside the label)
BackColor Specifies the background color of the workarea. See Active Label colors.
obj.BackColor = 0x0000FF; // Sets the background color to red
v = obj.
BackStyle Long integer. Specifies the background style for the workarea.
obj.BackStyle = -1; // Solid fill
v = obj.BackStyle;

Supported styles are:
-1 - solid (default)
0 - horizontal hatching
1 - vertical hatching
2 - diagonal left to right hatching
3 - diagonal right to left hatching
4 - cross (horizontal and vertical) hatching
5 - diagonal cross
BorderColor Specifies the color for the border of the workarea. See Active Label colors.
obj.BorderColor = 0x00FF00; // Sets the color to green
v = obj.BorderColor;
BorderStyle Long integer. Specifies the line style used for border of the workarea.
obj.BorderStyle = 1; // Dashed line
v = obj.BorderStyle;

The supported line styles are:
0 - solid (default)
1 - dashed
2 - dotted
3 - dash dot
4 - dash dot dot
5 - none
6 - solid inside frame (makes sense for closed shapes only - the line is solid but is drawn inside the shape and not over the shape borders).
BorderWidth Long integer. Specifies the line thickness of the workarea border
obj.BorderWidth = 0; // Thin 1 pixel line
obj.BorderWidth = 100; // 1 mm thick line
v = obj.BorderWidth;
ForeColor Specifies a default foreground color. See Active Label colors.
BorderVisible Boolean. Default is true - the border of the ActiveX workarea is visible otherwise it is not drawn.
Connectivity related properties
Src Read/Write, String
Gets/sets an URL, relative or virtual path from which the label is loaded. When set the label pointed by the property is downloaded/read, the current contents and settings of the label are discarded.
objVisiLabel.Src = "http://myserver/mylabel.activelabel";
objVisiLabel.Src = "http://myserver/getlabel.asp?Label=MyLabel";
var scurURL = objVisiLabel.Src;
When set the download occurs asynchronously an OnDownloadCompleted event is fired by the VisiLabel object when it is finished. The immediate download can be disabled using the DisableConnectivity property. See How to Download and Upload for detailed explanation on how to use the download/upload capabilities of the ActiveX. 
Dst Read/Write, String
Gets/sets an URL, relative or virtual path to which the label is uploaded. When set the upload starts immediately.
oVisiLabel.Dst = "http://server/myscript.asp";
oVisiLabel.Dst = "/labels/upllabel.asp";
var strLastUpload = oVisiLabel.Dst;
When set the upload starts immediately and when finished an OnPostCompleted event is fired by the VisiLabel object.
The immediate upload can be disabled using the DisableConnectivity property.
When referring a resource it is enough to specify its URL in the Src property, but for uploads/posts there must be a script/application at the URL location which will accept the uploaded data (all the label data in this case). The format in which the label is uploaded is defined by the Misc.SaveFormat property.
See detailed explanation in How to Download and Upload.
ObjectState Read-only, long integer
Returns the load state of the object. 
var state = oLabel.ObjectState;
See also: How to Download and Upload
The possible values are:
0 - uninitialized. The element is in undetermined and unusable state. This value is not actually returned except to indicate fatal internal errors. In future versions of the ActiveX it may be used by some new graphical element types if appropriate.
1 -  loading.
The element is currently loading data. While in this state the element should not be used if possible. The data is not yet entirely received.
2 - loaded
. The last download operation has finished but unsuccessfully.
3 - usable
. The last download operation (if any) has finished but was not completely successful. This may indicate that the the data has been incomplete or corrupted, or no data has been ever downloaded or that the server side encountered an error specific to your application.
4 - ready.
  The element is ready and any download operations have been finished successfully.
PostResult Read-only, Long integer
Indicates the state and success of the last post/upload operation.
state = obj.PostResult; // get the state
if (state > 1) { ... } // if the upload is complete do something.

The possible values are:
0 - Undefined state ( not currently used).
1 - uploading.
  Upload/post operation is in progress.
2 - finished
. Upload finished but unsuccessfully.
3 - uploaded.
The upload/post has been completed without success confirmation from the server-side.
4 - complete.
The operation has been completed successfully.
For details see How to Download and Upload. In short
DisableConnectivity Read/Write, Boolean
Default value is false. When set to true disables the immediate download/upload which is otherwise invoked when the Src or Dst property are set.
oLabel.DisableConnectivity = true;
When the "connectivity is disabled" you can still invoke downloads and uploads but only by calling Reload or PostData respectively.
PostVerb Read/Write, String
Default value: POST
Sets/gets the verb used for data uploads/posts. The term verb is usually associated with the HTTP protocol only, but it is also supported by most other protocols. 
oImage.PostVerb = "PUT";
var curVerb = oImage.PostVerb;

For HTTP and virtually all the similar protocols the verb POST should be the best choice. This includes for instance pseudo WEB server protocols like ALP. Sometimes even with a typical WEB server you may want for some reason to use another verb (also called sometimes - request method). In such cases do not forget to check if the verb is permitted by the WEB server's configuration. For non-HTTP-like protocols (such as FTP) the verb can be actually the protocol command used for upload or something with similar meaning.
PostParams Read/Write, String
Specifies custom URL parameters that will be sent along with the upload/post.
obj.PostParams = "MyParam=1234&MyParam2=A parameter";
curparams = obj.PostParams;

When a new label is created the value of this property is not empty. The ActiveX generates an unique GUID and sets it as LabelUID={....} in it. If your application needs a guaranteed unique identifier for the label designs it can use it to identify them. If you do not need it you can clear the property or just ignore the parameter when processing the upload on the server side. The ActiveX always appends silently a parameter LabelCaption=<Caption> where <Caption> is the value of the Caption property. It is semi-unique but its main purpose is to serve as human readable name of the label. Therefore you should attempt to keep it short and readable if possible. When a new label is created a caption is generated automatically too.
For more information on the standard parameters and how to use this property see How to Download and Upload.
CreateElement Creates a new drawing object (element) in the label. Allows the application to implement label design generation tasks.

o = obj.CreateElement( nType[, name]);
nType - A numeric constant (from 1 to 6 in version 1.0). Specifies the element type to create.
name - An optional string argument. Specifies the name for the new element. If omitted a name will be generated automatically (the automatic name is like this "Element N" where N is a number).
returned value - is the created element. You can initialize it immediately after the creation by changing its properties.
The newly created elements initialize automatically so that they can become at least visible. All the elements use the TextDefaults and properties of the Label object as default values for their similar properties. However, these defaults do not cover every possible aspect of the visual characteristics of the element and the application will need to change some properties over the created element to achieve the wanted result. 
RemoveElement Removes a drawing object (element) from the label

index_or_name - An element index or name. If there are more than one elements with the same name only the first found will be affected.
Any existing data links between a field in the data source (see Variables) and properties of the deleted object are not deleted! Thus the fields linked to properties of the object will remember the link (i.e. the object name and the property name) - this can be useful if you want to replace the object with another - you may be able to skip some work related to data link changes if you put a new element with the same name.
ReorderElement Syntax:
obj.ReorderElement( name_or_index, lPos)
name_or_index - An element index or name. If there are more than one elements with the same name only the first found will be affected.
lPos - the new element position in the elements stack or a reorder constant.
   -1 - moves the element to the bottom
   -3 - moves the element to the top
   >=0 - moves the element to the specified z-order position.
Clear Syntax:
obj.Clear([ bFull])
bFull - optional Boolean argument. If omitted or set to false only all the drawing objects (elements) are removed. If set to true the data source (See Variables) is rest and the Active Label's factory defaults are applied.
Print Prints one or more labels arranged on the paper as specified by the Page object's properties.
obj.Print( [ bDefault [, lNumber]]);
bDefault - Boolean, default is false. If true the label(s) will be printed to the default printer, no user interface is displayed.
lNumber - Long integer, default is 1. Specifies the number of copies to print or the maximum labels to print (See the remarks for details).
The first important detail about the Print method behavior is the value of the Variables.UseDataSource property. If it is set to true the Print will print series of labels arranged on the paper, by navigating the internal data source (Variables object) through the data. In such case the lNumber value serves as an upper limit to the number of labels printed. If the data records are less then the lNumber then the printing will stop as all the data is consumed, if the data is more than lNumber then the printing will stop as lNumber labels are printed. Therefore in such case the application uses the lNumber parameter to set a sanity limit to the printing and thus avoid scheduling printing tasks that may consume all the paper in the printer for instance. Obviously this should be used as a precaution for human mistakes and errors in the application that may cause printing labels from data sets that contain unexpectedly huge amount of records.

When the Variables.UseDataSource is set to false the Print will print copies of the same label. It will print exactly lNumber copies. 

The second important detail is the bDefault argument. When it is false the printer select/settings dialog will pop-up and the user will be able to cancel the printing, select which printer to be used and even change the printer settings (paper size, orientation etc.). When the bDefault is true the default printer is used and the printing occurs unattended. Apparently this is a security risk and thus it is controlled by the ActiveX security settings. 

During the printing process the Active Label switches to synchronous download mode. This means that it will block the user interface until the print operation finishes or fails. During that time the ActiveX may need to download different images or other data for each label in the set sent to the printer. This is also done synchronously in order to avoid problems that can be caused by the user - for example he/she may choose to navigate to another page and thus unload the ActiveX which is in a middle of a printing operation. Any asynchronous solution will require a lot of side work from the developer in order to prevent any such possibilities, thus blocking the user interface automatically discards all the potential problems of this sort.

ShowProperties Displays the main property sheets of the ActiveX giving the user the opportunity to change the settings and visual appearance through them.

MergeSrc Downloads label data from the specified URL and merges it with the label settings.
obj.MergeSrc(url [, how]);
url - full, virtual or relative url from which to download.
how - reserved for future versions. Set it to 0 if the language you use does not support optional parameters.
This method works in much similar way to the Src property when it is set. The difference is that MergeSrc does not clear the label. Instead it loads the label data and merges it with the data already in the label. This can be used to download data entries in the data cache separately or to add additional elements on the label, to change some settings, to merge two labels etc. See also How to Download and Upload and the samples packed with the ActiveX.
PostData Syntax:
Invokes upload/post operation of the label to the URL specified in the Dst property. By default the Dst property invokes this when changed, but if you want to upload again to the same URL you can call this method. Also some applications may prefer to disable the immediate upload when the Dst is changed by setting the DisableConnectivity to true. Such applications will need to call PostData explicitly to invoke upload.
Note that if there is upload/post operation in progress it is cancelled and you will not receive any more information about it (events, status information). The newly started operation takes precedence.
For details and samples see How to Download and Upload.
Reload Syntax:
Similar to the PostData, but this one invokes new download/reload operation from the URL that is specified in the Src property. The DisableConnectivity has same effect as in case of upload - disables auto-download on Src property change.
Note that if there is download operation in progress it is cancelled and you will not receive any more information about it (events, status information). The newly started operation takes precedence.
For details and samples see How to Download and Upload.
OnElementCreated Syntax:
OnElementCreated( index)
index - Long integer, the index of the new element. It can be accessed using this index through the Element property and the other methods that require element index or name..

Fired after a drawing object/element is created in interactive mode. It is not fired when an element is created programmatically by calling CreateElement.
OnPrintCompleted Syntax:
Fired when the printing operation completes both successfully or not.
OnLabelPrinted Syntax:
OnLabelPrinted( number)
number - Long integer, the total number of the labels printed up to now.
Because Active Label ActiveX is often used in scripting environments (such as DHTML pages) the event is fired for each page and not for each label.  
OnElementChanged Syntax:
OnElementChanged( index)
index -
Long integer, the index of the changed element. This index can be used to access the element through any member that requires drawing object/element name or index.
Fired after any change made to the element by the user. I.e. this event if fired when the user changes the element interactively by using its property sheets or by moving/sizing it. The even does not occur when an element is programmatically changed through its properties.
OnElementDeleted Syntax:
OnElementDeleted( index)
index -
Long integer, the index of the selected element.
Fired when an element is deleted by the user in interactive mode (by pressing the del key over the selected element for example). Not fired when the element is deleted programmatically. The returned index cannot be used to access the element as it is already deleted, but it can help the application improve the user interface - for example select the next element.
OnModeChanged Syntax:
OnModeChanged( )
Fired whenever there is a possibility that some general settings are changed. I.e. it is fired after the user closes a property sheet that contains settings that may affect the behavior, general design, the measurement units etc. An application that allows the user access these property pages may handle this event inspect the settings that may affect its function and perform the appropriate actions.
OnPrintStarted Syntax:
OnPrintStarted( )
Fired just before the first label is printed.
OnDownloadCompleted Syntax:
OnDownloadCompleted( index, success)
index -
Long integer, the index of the element which performs the download/load operation. If index is -1 this is the VisiLabel object and not a drawing object/element.
success - Boolean, Indicates if the operation has been successful.
If the index is 0 or greater this is an element on the label - such as image or a text box. If the value of index is less than 0 it has special meaning, at this time only -1 is used to indicate download performed by the root object - VisiLabel (i.e. the label itself had been downloaded).
Typically the applications need to perform entirely different tasks when an element is downloaded and when the label itself is loaded. Therefore usually you would like to use code like this:
<SCRIPT FOR="VisiLabel" EVENT="OnDownloadCompleted(Index,Success)">
if (index >= 0) {
  // Deal with the downloaded element  
} else if (index == -1) {
  // Deal with the root object - VisiLabel object itself.
The download operations are invoked when the Src property of an element or of the VisiLabel object is changed. Also the download can be invoked by calling the Reload method of the element or the VisiLabel object.
See also How to Download and Upload.
OnPostCompleted Syntax:
OnPostCompleted( index, success)
index -
Long integer, the index of the element which performs the upload/post operation. If index is -1 this is the VisiLabel object and not a drawing object/element.
success - Boolean, Indicates if the operation has been successful.
Very much like the OnDownloadCompleted, but for uploads. See the remarks for OnDownloadCompleted and How to Download and Upload.
OnObjectState Syntax:
OnObjectState( lState)
Reserved. Not currently fired.
OnDataDownloaded Syntax:
OnDataDownloaded( success)
Reserved. Not currently fired.
OnDataPosted Syntax:
OnDataPosted( success)
Reserved. Not currently fired.
OnDebugEvent Syntax:
OnDebugEvent( text)
text -
Debug text, containing human readable information.
This event is currently fired during download and upload operations of elements and the VisiLabel object. By handling it the application can obtain some tracing information such as the data returned by the server side during uploads. This event is especially useful during the development process it helps the developer access more details about the downloads and uploads. Hint: When you work with WEB pages after posting a form you see the returned result in a new WEB page, in Active Label there is no equivalent way, thus by handling the event you can gain access to that data. For example while you develop the server side part of the application that accepts image uploads from the ActiveX you may want to see if it responds correctly or see the error response if error occurs on the server side. For more information see How to Download and Upload.
OnPrintTimeout Syntax:
OnPrintTimeout( number)
number - the number of labels printed.
Fired when the printing operation fails.
OnElementClicked Syntax:
OnElementClicked( index, href)
index -
the index of the element that has been clicked.
href - The value of the Href property of the element.
This event is fired when an element is clicked in non-interactive mode. If interactive editing is on it is not fired. Can be used to implement navigation using the href properties of the elements - for example they may contain an URL from which to load a new label. If you want to implement hyperlink navigation (browser-like) you can instruct Active Label to change the mouse cursor to hand whenever it is over an element with non-empty Href property. See the ShowNavCursor property.


The developers who want to use the Active Label ActiveX in form based RAD environments (such as VB, Visual Studio, Delphi etc.) should note that it supports also a number of stock properties (standard properties for ActiveX controls). However not all of them are listed in this page because they are accessible through some of the objects returned by the root object (VisiLabel object - see Label, TextDefaults etc.). It is not recommended to use the stock properties not documented here programmatically, use instead the properties exposed by the corresponding Active Label's objects. This will guarantee the correct function of the application with future versions of the product.




newObjects Copyright 2001-2006 newObjects [ ]