2008-05-26

GdiPlusX undocumented functions

The GdiPlusX library is intended to be compatible with the .net framework’s system.drawing namespace. that means that you can use the msdn online documentation for the “system.drawing” in order to obtain accurate information about the gdiplusx classes. objects and functions. more than that, you can also convert the huge amount of samples published in various forums, blogs, articles and e-magazines to be used in vfp. it really does not matter if the sample was published in vb, c or asp. the conversion to vfp is really intuitive.

When gdiplusx was coded, we used a .net conversion tool, called reflector, which showed us all the source codes involved in each function, bringing us the possibility to code calling the same api functions, working with the same parameters.

But, during the coding phase, we had some great discussions about things that could be enhanced in order to ease user’s lives. We had a premise not changing the behavior of any function, even if we disagreed with some things there, in order to keep the full compatibility. On the other hand, we have decided that we could add new functions

Below is a short list of some functions that have been added to gdiplusx, that are not present in the .net original classes. most of them have already been used in some samples posted in this blog, but till now, no documentation was published. so, here are some of those new functions, that came to my mind. probably bo or craig will remember to add something here. i hope to be updating this post with some other improvements that only vfp users have available.

Of course, we know that GdiPlusX still needs some documentation, and we’re working on it. but for now, we hope that the list below will bring you some help.

 


 

XfcGraphics class

DrawStringJustified
Draws the specified text string at the specified location with the specified brush and font objects in a full justified format.

             Parameters: tcstring, ;
                        tofont as xfcfont, ;
                        tobrush as xfcbrush, ;
                        torectangle as xfcrectangle

             Where:
                        tcstring: text to be drawn
                        tofont: gdi+x font object
                        tobrush: gdi+x brush object
                        torectangle: gdi+x rectangle object with position and dimensions to draw

             Returns: nothing

             See also: 
             Full-justified text with gdiplus-x 
             Full justified texts in your reports with gdiplus x

             Samples: fulljustified.scx  /  fulljustify.prg

             Code sample:

local lctext
text to
lctext
noshow
this library
was intended to provide visual foxpro 9.0 developers with an object based library to wrap the 600+ functions included with the gdi+ api. the intent is to mimic the system.drawing namespace in the .net framework. all classes in the library are based on the classes included in the system.drawing namespace and other classes that are dependencies for classes in the system.drawing namespace. some additional additional functionality has been added to take advantage of features built in to vfp 9.0

endtext

do locfile("system.app")

with _screen.system.drawing
   local
logfx as xfcgraphics
   logfx = .graphics.fromhwnd(
_screen.hwnd
)
   logfx.drawstringjustified(lctext, .
font.new(“tahoma”,12);

      , .brushes.red, .rectangle.new(0,0,250,400))
endwith


 

XfcBitmap class

ToClipboard
Sends the current bitmap to the clipboard

            Parameters: none

            Returns: nothing

            See also: 
            Send images to the clipboard with gdiplus-x revisited

            Code sample:


do locfile("system.app")
with _screen
.system.drawing

   local
lobmp as xfcbitmap
   lobmp = .
bitmap.fromfile(getpict
())
   lobmp.toclipboard()
endwith


FromClipboard
Creates a gdi+ bitmap object from the clipboard data

            Parameters: none

            Returns: gdi+ bitmap object

            Code sample:

do locfile("system.app")
with _screen.system.drawing
   local
lobmp as xfcbitmap
  
lobmp = .
bitmap
.fromclipboard()
   lobmp.
save
("c:\fromclip.png", .imaging.imageformat.png)
endwith


FromVarbinary
Creates an image object from the specified varbinary string. useful to start manipulating an image directly without having to convert the binaries from the image to a file.

            Parameters: tcbinary

            Returns: gdiplusx bitmap object

 

            Code sample:

 


do locfile("system.app")
with _screen.system.drawing
   local
lcbinary
  lcbinary =
filetostr(getpict
())
   local
lobmp as xfcbitmap
   lobmp = .
bitmap
.fromvarbinary(lcbinary)
   lobmp.
save
("c:\fromvarbinary.png", .imaging.imageformat.png)
endwith

 

 

 


FromScreen

            Captures the specified window or object image to a new gdi+ bitmap object

 

            Parameters:

                thwnd, tix, tiy, tiwidth, tiheight, tlensurevisible
                toform [, tix, tiy, tiwidth, tiheight [, tlensurevisible]]
                tocontrol [, tlensurevisible]

            Returns: gdi+ bitmap object

            See also: capture screens with gdiplus-x

            Code sample:

 

 
do locfile
("system.app")
with _screen
.system.drawing
   local
lobmp as xfcbitmap
   lobmp = .
bitmap.fromscreen()
   lobmp.
save("c:\fromscreen.png", .imaging.imageformat.png)
endwith

 

 


GetMonoChrome
Returns a monochrome gdi+ bitmap (1bpp) of this image object.

            The image must be saved in the bmp image format in order to keep the 1bpp format. because the resulting bitmap is in an indexed pixel format, gdi+ cannot create a xfcgraphics object in order to draw on it. this function is recommended to be used immediately before saving to a file, in order to obtain the minimum file size. for some specific tiff compression types, a monochrome image of 1bpp is required too, see more details in these articles:

            Parameters: none

            Returns: gdi+ bitmap object

            See also: convert images to monochrome with gdiplus x
                         using tiffs with the new gdi+ classes – update
                         tiffs and the latest release of gdiplusx

            Code sample:


do locfile("system.app")
with _screen
.system.drawing
   local
lobmp as xfcbitmap
   lobmp = .
bitmap.fromfile(getpict
())
   local
lomonoch as xfcbitmap
   lomonoch = lobmp.getmonochrome() 
 
 lomonoch.save("c:\monoch.bmp", .imaging.imageformat.bmp)
endwith


GetPictureVal
Returns a string containing the pictureval of this image object, according to the imageformat passed. you can retrieve the binaries of the image with no disk access, in any image format supported by gdi+

            Parameters: imageformat object
                            
encoderparameter object (optional)

            Returns: string

            See also: manipulate images with no disk access with gdiplusx

            Code sample:

 

do locfile("system.app")
local lobmp as xfcbitmap
* obtaining the pictureval directly
with _screen
.system
.drawing
   lobmp = .bitmap.fromfile(getpict())
   thisform.image1.pictureval = lobmp.getpictureval (.imaging.imageformat.bmp)

endwith


GetPicturevalFromHBitmap
Returns a string containing the pictureval of this image object using the hbitmap gdi technique. the binaries retrieved are always in bmp format, what makes it a big string in most times. but, in most cases, this technique runs about 40% faster than using getpictureval() function shown above. the imagecanvas objects uses this function to obtain the binaries from the images drawn.

            Parameters: none

            Returns: string

            See also: manipulate images with no disk access with gdiplusx

do locfile("system.app")
local lobmp as xfcbitmap
* obtaining the pictureval directly
with _screen
.system
.drawing
   lobmp = .
bitmap.fromfile(getpict
())
   thisform.image1.pictureval = lobmp.getpicturevalfromhbitmap()
endwith


ApplyColorMatrix
Applies the received color matrix to the current bitmap object. 
This is very useful, and provides an easy and quick way to apply image transformations in just one step, without having to use the imageattributes class.

             Parameters:
                        tocolormatrix

 

             Returns: null

             See also: special effects on images with gdiplusx- part1
                           special effects on images with gdiplusx – part2
                           draw logos in your images with gdiplusx - part 2

             Code sample:

do locfile("system.app")
with _screen.system.drawing
   local lobmp as xfcbitmap
   lobmp = .
bitmap.fromfile(getpict())

   local loclrmatrix as xfccolormatrix
   loclrmatrix = .imaging.colormatrix.new(;
      0.33, 0.33, 0.33, 0, 0, ;
      0.33, 0.33, 0.33, 0, 0, ;
      0.33, 0.33, 0.33, 0, 0, ;
      0, 0, 0, 1, 0, ;
      0, 0, 0, 0, 1)�
   lobmp.applycolormatrix(loclrmatrix)
   lobmp.
save("c:\clrmatrix.png", .imaging.imageformat.png)

endwith

 


GetMask
Returns a bitmap object with the mask from the current bitmap. 
In fact this function returns a bitmap with all the transparent parts of the image. useful when you need to convert a png image that contains transparencies to be used in the bmp image format.

             Parameters: none

             Returns: gdi+ bitmap object

             See also: convert your buttons to bmps keeping transparency with gdiplusx


ToPrinter
Sends the image object to the printer

             Parameters: tnstretch, tcprintername, tnorientation, tnalignment

                        tnstretch
                        *   specifies how an image is sized to fit inside a control.
                        *   0 - clip. the image is clipped to fit the page. (default)
                        *   1 - isometric. the image resizes to fit the page while maintaining its original proportions.
                        *   2 - stretch. the image resizes to fit the page, but does not maintain its original proportions.

                        tcprintername
                        *   specifies the name of the printer, the same of getprinter()

                        tnorientation:
                        *   0 - portrait
                        *   1 - landscape

                        tnalignment
                        *   specifies a numerical value representing the alignment of the image in the page.
                        *   0 - vertically centered left.
                        *   1 - vertically centered right.
                        *   2 - centered. centers image vertically and horizontally.
                        *   4 - top left. aligns image in top left corner of the page.
                        *   5 - top right. aligns image in top right corner of the page.
                        *   6 - top center. aligns image at the top and horizontally centered on the page.
                        *   7 - bottom left. aligns image in the bottom left corner of the page.
                        *   8 - bottom right. aligns image in bottom right corner of the page.
                        *   9 - bottom center. aligns image at the bottom and vertically centered on the page.

            Returns: nothing

            Code sample:

do locfile("system.app")
with _screen.system.drawing
   local
lobmp as xfcbitmap
   lobmp = .
bitmap.fromfile(getpict
())
   lobmp.toprinter()
endwith


 

XfcColorMatrix class

MatrixMultiply
Returns a new color matrix object resulting of the multiplication of two color matrices. this is very useful when more than one color matrix is needed to be applied to an image. multiplying the color matrices before they are applied to the image will bring a huge gain of performance.

            Parameters: tocolormatrixone, ;
                        tocolormatrixtwo

            Returns: a new color matrix containing the resultant matrix

            Code sample:

do locfile("system.app")
with _screen.system.drawing
   local lobmp as xfcbitmap
   lobmp = .
bitmap.fromfile(getpict())
   local loclrmatrix1 as xfccolormatrix && greyscale matrix
   loclrmatrix1 = .imaging.colormatrix.new(;
      0.33, 0.33, 0.33, 0, 0, ;
      0.33, 0.33, 0.33, 0, 0, ;
      0.33, 0.33, 0.33, 0, 0, ;
      0, 0, 0, 1, 0, ;
      0, 0, 0, 0, 1)
  local loclrmatrix2 as xfccolormatrix && half brightness matrix
  loclrmatrix2 = .imaging.colormatrix.new(;
      0.5, 0, 0, 0, 0, ;
      0, 0.5, 0, 0, 0, ;
      0, 0, 0.5, 0, 0, ;
      0, 0, 0, 1, 0, ;
      0, 0, 0, 0, 1)

   local lonewclrmatrix as xfccolormatrix
   lonewclrmatrix = loclrmatrix1.multiply(loclrmatrix1, loclrmatrix2)
   lobmp.applycolormatrix(lonewclrmatrix)
   lobmp.save("c:\multclrmatrix.png", .imaging.imageformat.png)
endwith


XfcSize class

toRectangle
Returns a xfcrectangle object from the current xfcsizef object

 


 

XfcSizeF class

toRectangleF
Returns a xfcrectanglef object from the current xfcsizef object

3 comments:

  1. Excellent article as always Cesar. Thank you very much. The only undocumented function I knew about was "GetMask" :)

    Something you did not say in your post: GDIPLUSX is even better than the original NET classes, as it has less bugs, more functionality, and bugs are fixed instead of being converted into "features". :)
    Hi Carlos,
    Thanks for the kind words.
    In fact, some of the functions that have been added to GdiPlusX have a great influence from you. Thanks for the valuable feedback and suggestions you've been providing !
    Saludos !

    ReplyDelete
  2. Hi Cesar, thanks for the great article and this program has been great to use for us.

    i've quick question and hoping you've solution for this, printing any image to this printer "HP LaserJet 4350 PCL 6" throws an exception ("Declare DLL call caused an exception.") and don't how to troubleshoot this.

    reproducing the problem is very easy just install HP printer driver for this and print any image.
    printer driver can be downloaded here

    ftp://ftp.hp.com/pub/softlib/software10/COL9171/lj-24656-6/lj4200-4300seriespcl6vista2k2003xp2008.exe
     
    Hi Rk,
    In my opinion, your problems have nothing to do with GdiPlusX. I suggest you to download the most recent version of that specific driver from the manufacturer, or try using one of the drivers that Windows brings.
    Good luck!

    ReplyDelete
  3. Hi Cesar

    I've a problem with GDiPlux that what ever setting i use (tnstretch) i cannot print full page that fits nicely without making the image too small OR cut out any parts of it. if i print with windows built in image viewer it prints nicely and whole image nicely streched to fit the page.

    Any advise on that please ?Thanks

    ReplyDelete