Mini Shell

1. What is pyharu?
Pyharu is a pure python interface to haru(Haru Free PDF Library,
http://libharu.org/). All of the C API is usable.
No OO interface yet, but maybe in the feature, or you can write one by
yourself and send me to be inculded in pyharu ;)
Pyharu runs on different python versions, and even in different OS
without recompilation.

2. How to install?
1) To use pyharu, ctypes is needed , which is included since python 2.5.
But you have to install or compile by yourself in case you use python 2.3 or 2.4.
You can find details on ctypes website: http://python.net/crew/theller/ctypes

2) To use this interface, built Haru as a shared-library (DLL on windows,
so on linux). The binary package for win32(libharu_x_x_x_dll_win32.zip)
from official website DOES NOT work with this interface, so I included
my home-made one with PNG and zlib feature enabled.
The function in correct DLL looks like "HPDF_Page_GetTextRaise",
but NOT "HPDF_Page_GetTextRaise@4".

3) copy haru directory (including all files in it) to a directory, where is
in python's sys.path, for example d:\python\lib\site-packages

4) put libhpdf.dll(libhpdf.so) under a directory which is in environment
variant PATH, or put it in haru\dll\. I prefer to the last solution.
5) that is all

3. How to use?
1) Currently, pyharu supplies only the api that is similar to the C api, so
please read the haru document for API details.
2) All the example programs in haru C src has been ported, and you can find
them in demo directory. These demonstration programs are helpful too.
If you want to run them, you should copy the directories under libharu-xxx\demo\
to here
3) To run a python program, just type
python png_demo.py

4. difference between C API and pyharu API
the following python functions has a same form as their C brothers.
But they returns 3 value( actually, aTuple).

return of func, point.x, point.y=HPDF_Image_GetSize2 (HPDF_Image image, HPDF_Point *size)
return of func, pos.x, pos.y=HPDF_Page_GetCurrentPos2 (HPDF_Page page, HPDF_Point *pos)
return of func, pos.x, pos.y=HPDF_Page_GetCurrentTextPos2 (HPDF_Page page, HPDF_Point *pos)

And in fact, you don't need to pass the 2nd parameter to function:
return of func, point.x, point.y=HPDF_Image_GetSize2 (HPDF_Image image)
return of func, pos.x, pos.y=HPDF_Page_GetCurrentPos2 (HPDF_Page page)
return of func, pos.x, pos.y=HPDF_Page_GetCurrentTextPos2 (HPDF_Page page)

5. known problems
1) demo\text_demo.py, there are 2 bugs
one, Traceback (most recent call last):
  File "H:\libharu-2.0.8\pyharu\demo\text_demo.py", line 357, in <module>
    main()
  File "H:\libharu-2.0.8\pyharu\demo\text_demo.py", line 208, in main
    "RenderingMode=PDF_FILL")
  File "H:\libharu-2.0.8\pyharu\demo\text_demo.py", line 62, in show_description
    c = HPDF_Page_GetRGBFill (page)
ValueError: Procedure called with not enough arguments (4 bytes missing) or wrong calling convention

Often, that msg happends when we load a Cdll with Windll method, vice versa. But why here?

two, if I comment out "c = HPDF_Page_GetRGBFill (page)", the yieled pdf has a unexpected layout

2) ttfont_demo.C and ttfont_demo.py, in other words, that is the problem with haru
ttfont_demo.exe  .\ttfont\PenguinAttack.ttf -E
ttfont_demo.exe  .\ttfont\PenguinAttack.ttf
no characters appear

ttfont_demo.exe  c:\winnt\fonts\arial.ttf -E
many rectangles appear

ttfont_demo.exe  c:\winnt\fonts\arial.ttf -E
no characters appear

3) try to make_rawimage.exe, fails. So that maybe the problem in haru too.
make_rawimage.py fails too
python H:\libharu-2.0.8\pyharu\demo\make_rawimage.py png_demo.pdf 11.pdf
ERROR: Invalid PNG image format., detail_no=0          <==crazy haru

6. I don't use linux, but this interface should run linux without modification.
If I am wrong, please tell me. Thanks.
But first of all, you should make sure that you have installed correct
dynamic link lib(libhpdf.dll or libhpdf.so), please read part 2.4

7. How to update?
Please go to http://groups.google.com/group/pythoncia for the new version.
But that is only necessary when haru's API(not the implement of API) has
changed- I mean 'change or rename', but not 'add new function'
If haru does not change its API, but improve internal functions or fix
some internal bugs, what you only need to do is to overwrite the old DLL/so
on your PC with the new one.

8. What does the pyharu version number means?
Well, I just use the version number of haru that I am using.
That helps me to rember my development progress.

9. License
pyharu has a same license as haru, ie,  ZLIB/LIBPNG License.

The license of pyharu is as follows.

Copyright (C) 2008 Li Jun
This software is provided 'as-is', without any express or implied warranty.

In no event will the authors be held liable for any damages arising from the
use of this software.

Permission is granted to anyone to use this software for any purpose,including
commercial applications, and to alter it and redistribute it freely, subject
to the following restrictions:

 1. The origin of this software must not be misrepresented; you must not claim
    that you wrote the original software. If you use this software in a
    product, an acknowledgment in the product documentation would be
    appreciated but is not required.
 2. Altered source versions must be plainly marked as such, and must not be
    misrepresented as being the original software.
 3. This notice may not be removed or altered from any source distribution.


A. Discuss and bug report
http://groups.google.com/group/pythoncia
Since other projects by me is discussed here, please add [haru] in your post title.