Mnemonics 

'PICTURE'

Define/Draw Picture

GUI Display/Printer 

Formats

1.

Display/Output Picture:

'PICTURE'([x,y,x,y,] file_and_attrib$[,display_opt])

2.

List Embedded Pictures:

variable$='PICTURE'(*)

Where:

*

Use an * (asterisk) to have the system return a list of its embedded pictures (e.g. X$='PICTURE'(*) PRINT X$).

x,y,x,y

Point/position coordinates for top left and bottom right, in graphical units. Numeric expressions. Optional when used in List_View text.

file_and_attrib$

The graphic file must be specified as either one of the following:

     •  A filename of a graphic (e.g. C:\your_PATH\your.bmp). String expression. The icon filename must have .ico as an extension.

     •  A string consisting of a # and the channel containing the graphic; i.e. the channel opened via *BITMAP*.

Note:
If printing to a *PDF* channel on macOS or AIX, only .jpg images are supported. On Linux, .jpg and .png images are supported.

(Support for .png images on Linux was added in PxPlus 2019.)

Attributes can be specified by appending them after the file, separated by commas. Supported attributes are:

G

Specifies that all colors of RGB value 192,192,192 (Light Gray) are considered to be transparent.

T

Specifies that the color of the first pixel in the upper left corner of the image is to be transparent.

Note:
When using the 'T' option, the color will be taken from the original image, regardless of rotation, cropping or flipping. If inverted, the transparency color will also be inverted.

R:nn (or ROTATE:nn)

Specifies that the image is to be rotated 'nn' degrees counter clockwise.

(added in PxPlus v10.10)

C:x1:y1:x2:y2 (or CROP:x1:y1:x2:y2)

Specifies that the image is to be cropped starting at x1/y1 through x2/y2.

Where:

x1, y1, x2, y2 are the number of pixels from the top left corner of the image.

(added in PxPlus v10.10)

F:V, F:H or F:B

(or FLIP:HORIZONTAL | VERTICAL | BOTH)

Specifies that the image must be flipped horizontally (left/right), vertically (up/down), or both.

(added in PxPlus v10.20)

I (or INVERT)

Specifies that the colors are to be inverted.

(added in PxPlus v10.20)

B (or BLACK&WHITE)

Specifies that the image is to be converted to Gray Scale (black and white).

(added in PxPlus v11.00)

<URL>

(*PDF* Only)

Changes the picture into a hyperlink.

Where:

URL is the destination of the hyperlink. See Hyperlinks.

Note:
This option requires the use of the Haru PDF library; therefore, the 'HP' system parameter must be set.

(added in PxPlus 2019)

display_opt

Numeric code used to define style and alignment for use when displaying graphic. Supported options are:

       0 = Align at top-left (See Note below)
       1 = Center/crop within region
       2 = Scale to fit (See Note below)
       3 = Tile bitmaps to fill the given area (See Note below)
       4 = Halftone for enhanced legibility (may lighten black images)
       5 = Scale with proper aspect ratio but output in top left of region
       6 = Scale with proper aspect ratio but centered in the region
       7 = Scale picture to completely fill region and center (See Note below) (added in PxPlus 2019)

Note:
For options 0, 2 and 3:
The image is cropped to fit within the region for the screen and *WINPRT* output. Cropping is not supported with *PDF*; therefore, pictures sent to *PDF* that are larger than their defined region (based on 72 pixels to the inch) will be auto-scaled to avoid displaying outside the defined region.

For option 3 (tiled):
When sending to *PDF*, only images that fit completely inside the region will be output (based on 72 pixels per inch).

For option 7:
Once the image is scaled to cover, any overage is cropped. (This option is not supported for *PDF*, which uses option 6 instead.)

Description

Use 'PICTURE' to draw (print) a picture on the device (e.g. terminal). x,y,x,y coordinates define placement and size (top left and bottom right corners). Use graphical units or @X(col) and @Y(line) functions for the various coordinates.

For displaying image transparency, place a G or T at the end of the image filename.

Example:

print 'picture'(1,1,100,100,"myimage.bmp,T",0)
button 10,@(40,2,10,1.6)="{myicon.ico,T,F:V}&Name"

Note:
PxPlus supports alpha channel transparency processing of bitmap images for the 'PICTURE' mnemonic (for console output only, not printer and PDF).

(Alpha channel support was added in PxPlus 2017.)

For internal images (i.e. those specified with an ! (exclamation point) within braces {!imagename}), it is not necessary to use the G option because the system always assumes this transparency on an internal bitmap unless it is overridden with T. See Internal vs. External Images for information on the handling of internal and external images.

Transparent images are only supported when the picture does not need to be scaled. A scaled image cannot be masked since the scaling process will alter color codes.

Note:
The transparency options are not intended for printed output (i.e. *WINPRT*, *BITMAP*, *PDF*) and can produce incorrect results. Under UNIX/Linux, the use of these options with *PDF* will generate an Error #99: Feature not supported.

To remove an image at x,y,x,y coordinates, use a NULL pathname.

Example:

print 'picture'(1,1,100,100,"")

(The ability to use a NULL pathname was added in PxPlus v10.10.)

Hyperlinks

Picture Hyperlinks

If using the LibHaru *PDF* interface, i.e. 'HP' is On, and you print to a *PDF* channel using 'PICTURE' with the <URL> attribute, the picture will become a hyperlink with URL as the destination.

PDF viewer applications will attempt to guess whether a URL is a Web link or a file link. To prevent the PDF viewer application from being incorrect, the recommendation is that you prefix Web links with http://, https:// or ftp:// and prefix file links with file:///.

If you are creating a file link and using the file:/// prefix, you must use an absolute path to the file. However, if you want to use a relative path to the file, do not use the file:/// prefix and instead just specify the relative path. For example, if the open PDF file is in the directory C:\myapp\reports and you want to link to another PDF file called abc.pdf located in C:\myapp\reports\2016, the URL must be specified as 2016\abc.pdf.

Example:

open (pdf_chan)"*PDF*;file=C:\my_app\abc\report.pdf"
print (pdf_chan)'picture'(1,1,100,100,"C:\my_app\abc\resources\mylogo.png,<https://www.mycompany.com>",2)
print (pdf_chan)'picture'(500,800,700,880,"C:\my_app\resources\mapbutton.png,<file:///c:/my_app/abc/map.pdf>")
close (pdf_chan)

(Support for picture hyperlinks in PDFs if using LibHaru was added in PxPlus 2019.)