<<TableOfContents>>

= PicUtil - Pictures Utility APL+Win Workspace =

== OVERVIEW ==
This workspace contains useful functions when dealing with APL Picture element.


== DESCRIPTION ==
Here is a description of the functions:

{{{
CaptureToPic   Given the name of a form that is fully visible, it will capture it
               and generate a hidden picture element called 'CAPTURE.PIC'
               Clipping coordinates on the left of the function are optional.
               USAGE: [R,C,H,W] CaptureToPic 'your form name'

CaptureToClip  Given the name of a form that is fully visible, it will give it
               the Focus and Copy it to the clipboard. No clipping allowed.
               USAGE: CaptureToClip 'your form name'

FormToPic      Capture a form that is invisible or larger then the screen,
               and generate a hidden picture element called 'CAPTURE.PIC'
               The title bar and the menu area are not captured.
               Clipping coordinates on the left of the function are optional.
               USAGE: [R,C,H,W] FormToPic 'your form name'

PrintPic       Print a picture to the default printer. The Portrait or Landscape
               orientation is automatically selected. The picture will be centered
               and adjusted to fit all the page. The picture don't need to be visible
               See the Comments of the Function for a Description of the Options
               USAGE: [Options] PrintPic 'your picture name'

PrintForm      Combination of this WS functions to show how they
               can be used to print a form.
               USAGE: PrintForm 'your form name'

PicToFile      Given the name of a Picture element Create a Bitmap File
               USAGE: 'your picture name' PicToFile 'your file name'

FileToPic      Show a Bitmap File in a Picture element (FILE.PIC)
               The Picture Name on the Left is Optional
               USAGE: ['your picture name'] FileToPic 'your file name'

FileToHandle   Get a Bitmap Handle from a Bitmap File
               USAGE: (hbmp hpic wpic) ← FileToHandle 'your file name'

GetExactColor  When you deploy your application on many computers and have a
               background color that you want to erase with EraseBkgd, you may want
               to check if the display adapter was able to show it correctly.
               USAGE: 'Exact Color' ← GetExactColor 'background color'

EraseBkgd      Remove some colors of the picture element.
               Mainly to save ink on the inkjet printers.
               USAGE: 'background colors' EraseBkgd 'your picture name'

Zip            Sometimes you want to keep the bitmaps you are using into your WS
               because you don't want other people to easily access them. This
               function will compress them so they don't take too much space.
               USAGE: zipimage ← Zip ('your picture name' ⎕WI 'image')

UnZip          Will Uncompress the files created by Zip.
               USAGE: 'your picture name' ⎕WI 'bitmap' (UnZip zipimage)

FileToZip      Compress a Bitmap File into a Zip Format
               USAGE: zipimage ← FileToZip 'your file name'

PicToZip       Get a Zip Format from a Picture element
               USAGE: zipimage ← PicToZip 'your picture name'

ZipToHandle    Get a Bitmap Handle from the result of the Zip function
               USAGE: (hbmp hpic wpic) ← ZipToHandle zipimage

ZipToPic       From a Zip Format show a Picture element (ZIP.PIC)
               The Picture Name on the Left is Optional
               USAGE: ['your picture name'] ZipToPic zipimage

ClipPic        Clip and Resize a Picture element from a set of Clipping Coordinates
               USAGE: (R,C,H,W) ClipPic 'your picture name'

GrayPic        Transform the Colors of a Picture element into 256 Shades of Gray
               The Result is returned into the Same Picture element
               USAGE: GrayPic 'your picture name'

DefaultPrinterMenu   Update the 'Change Default Printer' Menu in DemoForm
                     USAGE: See DemoForm for an example
}}}

== EXAMPLES ==
Here is some examples of what you can do:
{{{
      ⍝ To Get a sample Form to work with
      DemoForm

      ⍝ To Capture that visible Form
      CaptureToPic 'DemoForm'

      ⍝ To see the result of the Capture
      'CAPTURE' ⎕WI 'Show'

      ⍝ To Print the Capture
      PrintPic 'CAPTURE.PIC'

      ⍝ To remove the Background color of the Capture
      (GetExactColor (1↑'DemoForm' ⎕WI 'color')) EraseBkgd 'CAPTURE.PIC'

      ⍝ To Print again without the Background Color
      PrintPic 'CAPTURE.PIC'

      ⍝ To Print a visible Form (previous functions combined)
      PrintForm 'DemoForm'

      ⍝ To Erase the result of the Previous Capture
      'CAPTURE' ⎕WI 'Delete'

      ⍝ To make the Form invisible
      'DemoForm' ⎕WI 'Hide'

      ⍝ To Capture that invisible Form
      FormToPic 'DemoForm'

      ⍝ To Print the Capture
      PrintPic 'CAPTURE.PIC'

      ⍝ To Show a Zip Format in a Picture element
      ZipToPic zipdellogo

      ⍝ To Save a Picture element to a Bitmap File
      'ZIP.PIC' PicToFile 'C:\DELLOGO.BMP'

      ⍝ To Show a Picture element from a Bitmap File
      FileToPic 'C:\DELLOGO.BMP'

      ⍝ To Zip a Bitmap File
      zipmat ← FileToZip 'C:\DELLOGO.BMP'
}}}
== VERSION ==
{{{
January 2002  - First Release of WS

March 2002    - Correction made in the number of argument for 'ReadFile'
                and 'WriteFile' (last one was not required).

              - The Zip function was added an optional argument to choose between
                a short version (contributed by Eric Lescasse) and the original
                iterative procedure (mainly for large file to prevent WS full).

              - FileToHandle was modified to use ⎕WCALL 'LoadImage' to get the bitmap
                handle instead of '?Bitmap'.

              - All functions were tested and modified to work with a global index
                origin of either 0 or 1.

May 2002      - The calculation of the Printer Ratio was modify in PrintPic. If the
                top margin was 0, the picture was not properly centered on the paper.
}}}
== DOWNLOAD ==
The workspace in APL+Win version 5 can be downloaded here:  [[attachment:PicUtil.w3]]

== INFORMATION ==
||Original author: ||Pierre Gilbert ||
||Responsible: ||PierreGilbert ||
||Email: || <<MailTo(apgil AT SPAMFREE videotron DOT ca)>> ||

----
CategoryApl2000