newObjects Active Label Image object

Drawing object (element).

oImage = VisiLabel.Element(x);
oImage = VisiLabel(x); 

The Image object displays pictures on the label. The images displayed by such an object can be loaded dynamically in the same manner as the IMG elements in a HTML page. Furthermore unlike the HTML pages the Active Label's Image object supports something more - upload to URL. This feature allows the developers to implement embedded label design functionality on the WEB pages of their applications and for example to allow the user put an image from the local machine and then upload the image to the server when the design task is complete. These features work in protocol independent manner and can be used with any installed protocol and not only HTTP! The dynamic download works with HTTP/HTTPS, ALP, RES, MK, FILE, FTP and any other internet protocol you may have. The dynamic uploads require the protocol to support data posting it works with HTTP/HTTPS, ALP and any other internet protocol capable to accept data posts. See the remarks section in the end of the page for more details about the Image object behavior.

Text command:

The text commands are used to represent objects and their settings in the saved label data. When the label is saved or uploaded (see How to Download and Upload) text commands are generated and packed in the specified format (see Misc.SaveFormat). The representation of the entire label with its elements can be also obtained programmatically through VisiLabel.TextCommands and VisiLabel.ObjectParams. The commands have simple syntax and can be generated from the application (just like a HTML output) where appropriate allowing the developer implement different tasks in any suitable way. The label can be instantiated from set of text commands (see the list of the different options to do this). The text commands can be feed into the control programmatically (see VisiLabel.TextCommands) or a download can be invoked (see VisiLabel.Src and VisiLabel.MergeSrc).

An Image element object is represented by a IMAGE text command. 

Members reference:

Properties
X Sets/Gets the horizontal position of the element's reference point. See the label coordinate space. The property is long integer.
Syntax:
obj.X = value;
v = obj.X;
Y Sets/Gets the vertical position of the element's reference point. See the label coordinate space. The property is long integer.
Syntax:
obj.Y = value;
v = obj.Y;
Width Long integer. Specifies the width of the bounding rectangle for the image. The image is stretched to this width.
Syntax:
obj.Width = 3000; // Sets the element width to 3 cm.
v = obj.Width;
Height Long integer. Specifies the height of the bounding rectangle of the image. The image is stretched to this height.
Syntax:
obj.Height = 3000; // Sets the element width to 3 cm.
v = obj.Height;
SizeAdjust Long integer. Specifies how to stretch the image.
Syntax:
obj.SizeAdjust = 2; // Keep the aspect ratio by stretching the image to match the width specified but adjust height to keep the aspect ratio.
v = obj.SizeAdjust
Remarks:
The supported values are:
0 - (default) do not keep aspect ratio stretch the image to the specified Width and Height.
1 - Obey the specified height but keep the aspect ratio. The visual width of the image will be adjusted - e.g. the image may appear wider or narrower then the Width specifies.
2 - Obey the specified width but keep the aspect ratio. The visual height of the image will be adjusted - e.g. the image may appear shorter or higher than Height specifies.
Comments: This has been inspired by the WEB techniques where you can restrict the width or the height of the image elements separately. We believe it is more convenient especially if you have images from a database and they vary in height and width. It should be easier to design a label to accommodate various images with previously unknown aspect ratio this way - you can count on at least one of the sizes - width or the height and thus design the label layout with this in mind. Of course for a good design you must have an idea about how much the aspect ratio will vary between the different images that may appear from the database. The best approach is to find out what is the maximum aspect ratio, size the image element according to it and finally set the appropriate SizeAdjust to make sure the image will appear shorter/thinner than the bounding rectangle. This way you will have the most appropriate space reserved on the label no matter what images will be put there from the application's database.
Transformation properties
See the Remarks section below about information about how and when the transformations are applied.
TransResizeWidth Long integer. Specifies the width to which the actual image is to be resized internally. Default value 0 - no resize.
Syntax:
obj.TransResizeWidth = 100; // resize to 100 pixels width
vwidth = obj.TransResizeWidth; // Obtain the current width
Remarks:
The value is in pixels. It actually concerns the quality of the image data kept by the object in memory. On the screen and on the printer the image is displayed according to the Width and Height properties which are specified in the measurement units like hundreds of millimeter for instance. Thus this property specifies the size (width) in pixels for the internal image data buffer and thus allows the application to control the size of the data kept by the label.
When to use: This is especially useful if you need to lower the size of the label data. For instance an image obtained from a scanner or a photo is too big and unpractical (it could be 10MB and even bigger), because most labels are printed on low resolution printers and relatively small. Thus if you intend to upload this image (see the Dst property) and keep it on the server there is no need to preserve its original size and quality. 
The immediate effect on the screen/printer is change of the quality of the displayed image.
TransResizeHeight Long integer. Specifies the height to which the actual image is to be resized internally. Default value 0 - no resize.
Syntax:
obj.TransResizeHeight = 100; // resize to 100 pixels width
vwidth = obj.TransResizeHeight; // Obtain the current width
Remarks:
See the remarks about the TransResizeWidth above..
TransMirror Boolean. If set to true the image data in memory is mirrored. Default value is false (no mirror).
Syntax:
obj.TransMirror = true; // Mirror the image
b = obj.TransMirror;

Remarks:
The image will show mirrored. 
TransFlip Boolean. If set to true the image data in memory is flipped upside down.. Default value is false (no flip).
Syntax:
obj.TransMirror = true; // Mirror the image
b = obj.TransMirror;

Remarks:
The image will show flipped. 
TransRotate Long integer. Rotates the image to 0, 90, 180, 270 degrees (clockwise). Default value is 0.
Syntax:
obj.TransRotate = 90; // rotates the image 90 degrees right.
currot = obj.TransRotate;

Remarks:
Only orthogonal rotations are currently supported. Any rotation different from 0, 90, 180, 270 degrees will have no effect.
TransNegative Boolean. If set to true negates the image. Default value is false.
Syntax:
obj.TransNegative = true; // Negates the image
b = obj.TransNegative;
 
TransGamma Long integer. Specifies the gamma correction in percents 0 - 100. Default value is 0 - no correction.
Syntax:
obj.TransGamma = 30; // 30% gamma correction
gamma = obj.TransGamma;
TransNoise Long Integer. Applies noise effect if greater than 0. The intensity of the effect can be from 0 to 255. Default is 0 - do nothing.
Syntax:
obj.TransNoise = 50; // Noise effect with 50 
noise = obj.TransNoise;
TransBrightness Long integer. Changes the brightness of the image. Can be from -100 to +100 with default of 0 - no change.
Syntax:
obj.TransBrightness = 50; // Make the image 50% brighter;
currentbrightness = obj.TransBrightness;
TransContrast Long integer. Changes the contrast of the image. Can be from -100 to +100 with default of 0 - no change.
Syntax:
obj.TransContrast = 50; // Make the image 50% more contrast;
currentcontrast = obj.TransContrast;
TransColorizeEffect Long integer. Specifies the magnitude of the colorization to be applied to the image 0 to 100. Default is 0 - no colorization. The TransColorizeHue and TransColorizeSat properties specify the Hue and Saturation for the effect (If TransColorizeEffect is 0 they will have no effect).
Syntax:
obj.TransColorizeHue = 20;
obj.TransColorizeSat = 50;
obj.TransColorizeEffect = 50; // Colorize with intensity 50;
Remarks:
This property must be used together with TransColorizeHue and TransColorizeSat to specify actual transformation. 
TransColorizeHue Long integer. Can be from 0 to 255. Specifies the Hue for the Colorize effect. See TransColorizeEffect for details.
TransColorizeSat Long integer. Can be from 0 to 255. Specifies the Saturation for the Colorize effect. See TransColorizeEffect for details.
TransRedAdjust Long integer. Can be from -255 to +255. Each property specifies the the Red, Green and Blue color adjustment respectively. Default is 0 - no adjustment.
Syntax:
obj.TransGreenAdjust = 30; // intensifies the Green component.
curadjgreen = obj.TransGreenAdjust;
 
TransGreenAdjust
TransBlueAdjust
TransGray Boolean. If set to true makes the image grayscale. Default is false - do nothing.
Syntax:
obj.TransGray = true;
isgray = obj.TransGray; 

Remarks:
This property is useful if you want to keep images for printing (monochrome) and does not keep the color data.
TransDither Long integer. Specifies the dithering effect. Default is 0 - no dithering.
Syntax:
obj.TransDither = 2; // Ordered dithering 4x4
dither = obj.TransDither; 

Remarks:
The supported dithering methods are:
1 - Floyd-Steinberg
2 - Ordered 4x4
3 - Burkes
4 - Stucki
5 - Javis
6 - Sierra
7 - Stevenson-Arce
8 - Bayer 4x4
For the practical purposes in Active Label the dithering is another way to make the image black and white which is practical if you want lower the image quality and data size to the level required for printing on low resolution printers. For instance this is good for thermal printers.
TransThreshold Long integer. Applies threshold effect. Can be from -1 to 255. Default is -1 - no effect.
Syntax:
obj.TransThreshold = 10; // Threshold 10.
thr = obj.TransThreshold; 
Standard drawing object (element) properties
ElementType Returns an integer constant which describes the element type:
1 - Text Label
2 - Text box
3 - Simple shape
4 - Symbol
5 - Image
6 - Barcode
Syntax:
et = obj.ElementType;
Remarks:
This property is a must when you want to enumerate the elements on the label and perform certain actions on some of them (for example invoke save for the image elements, or check the correctness of the text elements and so on). 
VisiLabel Returns the VisiLabel object on which the element resides.
Index Returns the element's index in the elements stack. 
Syntax:
i = obj.Index;
For example you can use later VisiLabel.Element(i) to obtain the same element.
PropInfo Implements simple type information interface which allows the application to obtain a list of properties supported by the object.
Syntax:

v = obj.PropInfo( nProp [, infoType]);
Parameters:
nProp - >= 0 integer value - the property index for which to obtain infromation. See the remarks.
infoType - What information to return. Currently supported values are:
   0 - the name of the property
   1 - the type of the property as VARTYPE constant.
   2 - the property description.
Remarks:
This is used mostly for internal purposes, but can be useful for some advanced applications as well. The PropInfo can be called with nProp argument ranging from 0 to a certain positive number N. For values greater than N PropInfo returns null. Through it you can obtain a list of the properties supported by the drawing object and some other information about them.
Note that not all the properties you can see in the documentation are described by the PropInfo property. It returns information only for the properties that are best suitable for run-time changes - for example linked to fields in the internal data source. A good example is the Selected property - it is not returned by the PropInfo for any kind of element because it is useful only in interactive mode and makes no sense otherwise.
Name Sets/gets the name of the element
Syntax:
obj.Name = "some name";
v = obj.Name;

Remarks:
It is recommended to keep the element names constant once the label design is complete. For instance when using data to print set of labels, linking the name of an element to a field will change its data linkage once the name is changed. This can be used as a trick, but it will need extreme caution and careful planning.  
Selected Makes the element selected/non-selected in interactive mode.
Syntax:
obj.Selected = value;
issel = obj.Selected;

the property is Boolean.
Remarks:
Makes sense only in interactive editing mode (see Edit object). Most often used by applications/WEB pages that display a list of the elements on the label and allow the user to select an element by clicking its entry in the list. Can be used also for any purpose that requires the application to direct the user's attention to a particular element. 
Locked Changes the locked state of a drawing object (element).
Syntax:
obj.Locked = value;
v = obj.Locked;


the property is Boolean.
Remarks:
This property is used in interactive editing mode (see Edit object). If the VisiLabel.Edit.ProtectLockedElements is set to true then all the locked elements cannot be changed. This allows implementation of visual editing over label design templates where some elements are constant and cannot be changed.
Hidden Changes the visible state of a drawing object (element).
Syntax:
obj.Hidden = value;
v = obj.Hidden;


the property is Boolean. When set to true the element is invisible on the screen and on the printer.
Remarks:
This property is useful in various situations. For example it can be linked to a field in the internal data source to make a particular element visible or invisible depending on the data in the current record.
CodePage Sets/gets the code page as numeric value. The code page is used for all the text translations from UNICODE to ANSI and reverse.
Syntax:
obj.CodePage = value;
cp = obj.CodePage;

Remarks:
By default the system's code page is used. This is usually enough for the most applications, but if you need to place texts in different languages on the label you may need to change the code page of some of the text elements.
Href String. An arbitrary textual value that can be used for a hyperlink if the application that hosts the label desires so.
Syntax:
obj.Href = "../anotherlabel.activelabel"; // points to another label in the parent directory.
vhref = obj.Href;

Remarks:
The Active Label Browser application treats this property as a hyperlink. It is relative to the source location from which the label on which the element resides is loaded. On WEB pages your application may use this property to invoke navigation to another label - i.e. changing the label displayed when the user clicks over certain element on it. However note that on WEB pages all the navigational properties (Src and Dst) are relative to the WEB page's location and not the label load location. See also OnElementClicked event.
Connectivity properties
Src Read/Write, String
Gets/sets an URL, relative or virtual path from which the image is loaded. When set the image pointed by the property is downloaded/read.
Syntax:
objVisiLabel("MyImage").Src = "http://myserver/img.jpg";
oImage.Src = "C:\Images\img.gif";
var s = oImage.Src;
Remarks:
When set the download occurs asynchronously and an OnDownloadCompleted event is fired by the VisiLabel object when it is finished. The immediate download can be disabled using the DisableConnectivity property. See also How to Download and Upload.
Dst Read/Write, String
Gets/sets an URL, relative or virtual path to which the image is uploaded. When set the upload starts immediately.
Syntax:
oImage.Dst = "http://server/myscript.asp";
oImage.Dst = "/labels/uplimage.asp";
var strLastUpload = oImage.Dst;
objVisiLabel("MyImageElement").Dst = "-- some url --";

Remarks:
When set the upload starts immediately and when finished an OnPostCompleted event is fired by te 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 (image in this case). Furthermore that script/application can respond to the upload with the new image location and thus automatically change the reference into the label to its new saved location. See details in How to Download and Upload.
ObjectState Read-only, long integer
Returns the load state of the object. 
Syntax:
var state = oImage.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.
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:
oImage.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 some 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:
1. This property can be used also to turn off all the URL parameters (incl. the standard ones). If it is set to empty string no parameters will be sent. To enable the standard parameters, but pass no custom parameters set it to "?". Any other value will pass the standard parameters and the value through the URL of the post/upload request.
2. For information on the standard parameters see How to Download and Upload.
3. As the standard parameters contain a lot of information it is rarely needed to customize the parameters. If you need to - you should format them as "Name=Value&...&NameN=ValueN" name/value pairs - just like parameters for ASP, JSP or PHP pages.
Methods
ShowProperties Displays the property sheets of the element giving the user the opportunity to change the element's settings and visual appearance through them.
Syntax:

obj.ShowProperties();
Remarks:
In interactive editing mode this can be done also by double clicking over an element or by pressing enter for the selected element.
PostData Syntax:
obj.PostData();
Invokes upload/post operation of the image 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.
ApplyTransform Synax:
result = obj.AplyTransform();
Applies the specified transformations and clears all the properties after that. Note that the transformation properties take effect immediately, so there is no actual need to call this method because it will double (apply once more) the specified transformations. See the most useful method ClearTransform.
ClearTransform Synax:
obj.ClearTransform();
Clears all the transformation properties - i.e. sets them to their default (neutral) values, but does not return the image data to its initial state. In other words the transformations set before that point remain permanently applied to the image data in memory. This is usually needed in pages or forms that provide the user with means to edit the label interactively by adding images to it and adjusting them with a few transformations. If you want to upload the transformed image and use it when the designed label is shown again (on other pages or forms) there is no more need of the transformations applied over the original image, thus you will want to clear them before saving/uploading the label. You can read more in How to Download and Upload. Also we recommend you review the installed samples.

Remarks

The image transformations

If you have experience with the effects and the filters in Microsoft Internet Explorer you will find certain similarities between them and the way the transformations are applied over the pictures shown by an Image object. The transformation properties allow you define which transformations apply to the image. The transformations are applied automatically when the picture is loaded. This means, for example, that if you change at run-time the Src property of an Image object a new picture will be loaded from the specified URL and the same transformations will be applied to it.

The need of such a behavior is dictated by the Active Label's purpose. For instance the main purpose of the Active Label control is to allow the WEB application to print a set of labels based on the same design over a data set (an example: think for instance about labels for pictured T-shirts, and assume you want to print a small thumbnail of the specific T-shirt on its label). When the actual printing occurs you will have the data supplied and the labels will print in one turn without further interaction. Thus if you want a different image on each label the transformation over it should occur automatically when it is changed.

As you may have noticed Active Label allows image objects to upload the images hold by them - see How to Download and Upload for details. Thus your application may implement management functionality which allows certain operators to design labels, and using the Active Label ActiveX upload images to the server where they will be kept in the application database and reused for each label where they are placed. You can apply transformations and then commence upload. In such case the transformed image will be uploaded. Therefore after the image element finishes the upload it is sensible to clear the transformations because the image is saved on the server with them already applied and when you save/upload the label design itself you will want to refer the uploaded image and not the original (which, for example, has been selected by the operator from the local hard drive). For detailed information about the upload process see How to Download and Upload . Note that Active Label can be instructed from the server side to change the reference of the image element to the uploaded image location automatically. No matter if the developer decides to use or not use this feature he/she has the opportunity to manage the entire process of the usage of pictures on labels - from the insertion of original image through the transformations to the upload to the server and consequent usage on the labels. This gives the developer the opportunity to control the quality and data size of the image data preserved permanently on the server. By using the transformations the developer has many options. Obviously the best choice is to keep relatively small images - small enough to save space and good enough for all the purposes for which they will be needed (the same images can be used on labels in the WEB pages etc.). Lets illustrate this with an idea that seems to be good for quite many applications.  If the images will be used on WEB pages only - as small illustrations that help the operators to identify the items and also on labels printed with thermal printers then you do not need top quality images. An single image with size about 200-300 pixels will be good enough for all the purposes and small enough to not occupy too much space in the database. Thus the application can specify TransResizeHeight/Width in the pages where the labels are designed. The operator who designs the label puts an image from the hard disk, the application resizes it and uploads it to the server. Then when you put it on pages you specify size in the <IMG> tag as appropriate for the WEB page design and on the labels you do the same but you also apply some other effects - such as grayscale or dithering. Furthermore the above example can be enriched by providing the operator who puts the images on the label designs by means to apply some of the other transformations and thus allow him/her tune the image better before uploading it. 

As a conclusion it is better to think about the Active Label mostly as it is a kind of a WEB browser and not a stand-alone design application. The typical desktop applications save what you see, while the browsers save a document in which some elements may change, but they always follow the rules you define. By using the transformations wisely before upload and after that when the uploaded images are used again you can combine characteristics of the both in the way you need them.

 

 

 

newObjects Copyright 2001-2006 newObjects [ ]