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

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


FloodFill 
Fills an area of the current bitmap surface with the passed color. It is used to fill an area with a single specific color, starting from the determined coordinates.
            Parameters: tnX, tnY, toxfcColor
            Returns: nothing
do locfile("System.app") local lobmp as xfcbitmap * obtaining the pictureval directly
with _screen
.system.drawing 
   loBmp = .
bitmap.fromfile(GETPICT())    loBmp.FloodFill(10,100, .Color.Red)   
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