| Objects |
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. |
| Properties |
ElementCount |
Long integer. Returns the number of the drawing
objects in the label as an integer number.
Syntax:
count = obj.ElementCount; |
|
Element |
Object,Default, indexed property.
Returns the specified drawing object (element).
Syntax:
el = obj.Element(name_or_index);
el = obj(name_or_index);
Parameters:
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.
Syntax:
s = obj.ObjectParams;
Remarks:
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.
Syntax:
s = obj.Caption
obj.Caption = s
Remarks:
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.
Syntax:
s = obj.TextCommands;
obj.TextCommands = strCommands;
Remarks:
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.
Syntax:
objVisiLabel.ShowNavCursor = true;
curMode = objVisiLabel.ShowNavCursor;
Remarks:
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.
Syntax:
obj.BackColor = 0x0000FF; // Sets the background color to
red
v = obj.BackColor; |
|
BackStyle |
Long integer. Specifies the
background style for the workarea.
Syntax:
obj.BackStyle = -1; // Solid fill
v = obj.BackStyle;
Remarks:
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.
Syntax:
obj.BorderColor = 0x00FF00; // Sets the color to green
v = obj.BorderColor; |
|
BorderStyle |
Long integer. Specifies the line
style used for border of the workarea.
Syntax:
obj.BorderStyle = 1; // Dashed line
v = obj.BorderStyle;
Remarks:
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
Syntax:
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.
Syntax:
objVisiLabel.Src =
"http://myserver/mylabel.activelabel";
objVisiLabel.Src =
"http://myserver/getlabel.asp?Label=MyLabel";
var scurURL = objVisiLabel.Src;
Remarks:
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.
Syntax:
oVisiLabel.Dst = "http://server/myscript.asp";
oVisiLabel.Dst = "/labels/upllabel.asp";
var strLastUpload = oVisiLabel.Dst;
Remarks:
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.
Syntax:
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.
Syntax:
state = obj.PostResult; // get the state
if (state > 1) { ... } // if the upload is complete do
something.
Remarks:
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.
Syntax:
oLabel.DisableConnectivity = true;
Remarks:
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.
Syntax:
oImage.PostVerb = "PUT";
var curVerb = oImage.PostVerb;
Remarks:
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.
Syntax:
obj.PostParams = "MyParam=1234&MyParam2=A
parameter";
curparams = obj.PostParams;
Remarks:
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. |
| Methods |
CreateElement |
Creates a new drawing object
(element) in the label. Allows the application to implement
label design generation tasks.
Syntax:
o = obj.CreateElement( nType[, name]);
Parameters:
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.
Remarks:
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
Syntax:
obj.RemoveElement(index_or_name)
Parameters:
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.
Remarks:
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)
Parameters:
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])
Parameters:
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.
Syntax:
obj.Print( [ bDefault [, lNumber]]);
Parameters:
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).
Remarks:
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.
Syntax:
obj.ShowProperties();
|
|
MergeSrc |
Downloads label data from the
specified URL and merges it with the label settings.
Syntax:
obj.MergeSrc(url [, how]);
Parameters:
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.
Remarks:
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:
obj.PostData();
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:
obj.Reload();
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. |
| Events |
OnElementCreated |
Syntax:
OnElementCreated( index)
Parameters:
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..
Remarks:
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:
OnPrintCompleted()
Remarks:
Fired when the printing operation completes both
successfully or not. |
|
OnLabelPrinted |
Syntax:
OnLabelPrinted( number)
Parameters:
number - Long integer, the total number of the labels
printed up to now.
Remarks:
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)
Parameters:
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.
Remarks:
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)
Parameters:
index - Long integer, the index of the selected element.
Remarks:
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( )
Remarks:
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( )
Remarks:
Fired just before the first label is printed. |
|
OnDownloadCompleted |
Syntax:
OnDownloadCompleted( index, success)
Parameters:
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.
Remarks:
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)
Parameters:
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.
Remarks:
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)
Parameters:
text - Debug text, containing human readable information.
Remarks:
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)
Parameters:
number - the number of labels printed.
Remarks:
Fired when the printing operation fails. |
|
OnElementClicked |
Syntax:
OnElementClicked( index, href)
Parameters:
index - the index of the element that has been clicked.
href - The value of the Href property of the element.
Remarks:
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. |
