|
|
All functions should work (I.E. not crash) on any system. If the underlying OS function is not supported on the system running this program, the function will exit without an error. Use xgGetOSVersion to find out if the function will perform something usefull or not. Note that the test application will run on any OS version that PocketC supports. The only difference is that a pre-3.5 system will draw everything in black and white.
All functions that require OS 3.5 are marked as such. They will still execute
without an error on older versions, but they will just return. This makes the
test faster since it is native instead of
HISTORY
0.07 12/18/2000 - Source Release (No changes, just source and missing .lib file)
0.06 4/19/2000 - Added resource bitmaps through xgDBOpen, xgDBClose and xgBitmapR (MUCH FASTER then xgBitmap!)
0.05 4/19/2000 - (bug fix, but never released)
0.04 4/19/2000 - Added xgSetDepth to set the display to 2, 4 or 8 bits
0.03 4/14/2000 - Fixed definition of xgPickColor and added Color Bitmap Editor (12x12)
0.02 4/11/2000 - Added color bitmaps and PickColor dialog
0.01 4/9/2000 - First public release
LEGAL
You know the drill, I provide this for your use. You may do
anything you wish with it (including using it in a commercial product), but you
may not sell it. If you do use it in a commercial product, please give me (Gary
A. Clark) credit. Of course, I cannot be held responsible for any damage or loss
of data on your system from using this library.
FILES
xGrfxLib.html - Your reading it. :)
xGrfxLib.prc - The
Extended Graphics Library for PocketC.
xGrfxLib.lib - Used by the Desktop
Environment.
xGrfxTest.c - Sample PocketC application using all features of
xGrfxLib.
cbe12.c - Source code to Color Bitmap Editor (12x12)
cbe12.pdb - Compiled version of Color Bitmap Editor (12x12)
BITMAPS
A bitmap is a string that follows a special format. The
first two characters indicate the width of the bitmap. To make it easier to work
with strings, only printable characters are used. To do this, only the lower 6
bits are used and this value is offset by 32 (a space character). To calculate
the first to characters, use the following formulas:
first = (width>>6) + 32
second = (width & 63) + 32
From this point on, the pixels are layed out one per character. Again, only the low 6 bits are used so only 64 colors are allowed. To choose which 64 colors, use the xgSetBitPal function, once for each bitmap index. For example, xgSetBitPal(33,0) would set the twelveth bitmap index to the first system pallete entry (white by default). To calculate the character to put in the string, add 32. To get the 33rd bitmap entry, you would use 33+32 which is 65 or the character 'A'.
The xgBitmap function uses the same arguments as the PocketC bitmap function
except it has one extra character argument. This argument indicates which bitmap
pallete entry is transparent. Using a character that is out of the 64 value
range starting with space will effectively turn it off. I use '~' to indicate no
transparency.
CBE12
The Color Bitmap Editor (12x12) program will edit bitmaps for use with xGrfxLib.
Its not very robust, but it does the job and shows an example of how the library
can be used in a real application. The program will save bitmaps to the palm
clipboard when you exit the program by pressing the 'stop' button in the lower
left corner. When starting, the bitmap will be loaded from the clipboard and
must be in the same format.
Most of the screen is covered with a zoomed view of the bitmap. Select a color from the palette and start tapping the zoomed view to set the color of pixels. Just above the palette are two rectangles. The one on the left is the bitmap at its normal size and the one on the right shows the current color. Tap the current color rectangle to get the color chooser dialog and change the color for that palette entry.
Since the palette is not saved with the bitmap, you will need to choose your
colors each time. Another option is to modify the init() function in CBE12 and
set your choices at that time.
FUNCTIONS
xgGetLibVersion()
Used to check the version of
this library. View as a hex number with the first two digits as the major
version number and the next two as the minor. 0x0123 would be version 1.23.
xgGetOSVersion(int w)
Used to check the version of the operating
system. Since PocketC does not support long (32 bit) values, the w paramater
determines which word of the version is returned. A value of zero returns the
low word and any other value will return the high word.
xgSetFore(char c) (OS 3.5 required)
Used to set the forground
color. Most PocketC functions will use this value to draw in.
xgSetBack(char c) (OS 3.5 required)
Used to set the background
color. Used by text() and bitmap().
xgSetTextColor(char c) (OS 3.5 required)
Color to display text in.
xgPixel(int x,int y) (OS 3.5 required)
Draw one pixel.
xgSetBitPal(char i, int c) (OS 3.5 required)
Set entry i in the
bitmap pallete to the system pallete index c. (see BITMAPS above for more
information)
xgGetBitPal(char i) (OS 3.5 required)
Get the bitmap pallete entry
at index i. (see BITMAPS above for more information)
xgBitmap(int x, int y, string s, int t) (OS 3.5 required)
Draw the
bitmap defined by s at x,y with transparency set to the bitmap index of t. (see
BITMAPS above for more information)
xgPickColor(int i,string title) (OS 3.5 required)
Display the
system Pick Color dialog with i as the default color and the dialog title set to
title.
xgSetDepth(int d) (OS 3.5 required)
Set the depth of the display as follows:
1) 2-bit monochrome (4 shades of gray)
2) 4-bit monochrome (16 shades of gray)
3) 8-bit color
xgDBOpen(string name)
Open the named database. It should be a resource database with bitmaps in it. Returns -1 if database cannot be opened.
xgDBClose()
Close the database opened with xgDBOpen.
xgBitmapR(int x, int y, int res)
Paint the given bitmap resource with the top left corner at x,y. Returns -1 if resource is not found.
CONTACT
If you have any comments, suggestions or bug reports, please
contact me through the PocketC message board (Palm OS Development) or though
email at garyc@jeld-wen.com.