=================================================================== RCS file: /cvs/ace/ace/docs/toolkit.html,v retrieving revision 1.1 retrieving revision 1.2 diff -p -u -r1.1 -r1.2 --- ace/docs/toolkit.html 1999/02/20 20:34:48 1.1 +++ /cvs/ace/ace/docs/toolkit.html 2001/05/07 03:09:55 1.2 @@ -23,15 +23,11 @@ the standard GIF format and integrated i integrated with text2c. The toolkit has functions that access these resources when the program needs them.

-

All Ace programs use the Xpm -library. Most Linux distributions include this as a standard -module; make sure you install it, or visit ftp.x.org to get the -sources. In addition, the utilities use the gd library to read -the GIF files; the solitaire programs do not include any part of the -gd library or any gif images or code.

+

All Ace programs use the +PNG library and ZLib. Your +system may have them installed, otherwise you'll need to download and +install them.

The library consists of three main parts: A collection of standard images (including, of course, the deck of cards), functionality to @@ -45,31 +41,28 @@ it. In my case, I use #include "car Makefile worry about how to tell gcc where to include it from. -

If your program responds to keypresses, you'll also need to include -X11/keysym.h to get the keycode definitions (like -XK_F1). - -

Your program should, in main(), call two functions: +

Your program should, in main(), call three functions: 

-  init_table(argc, argv, width, height);
+  init_ace(argc, argv);
+  init_table(width, height);
   table_loop();
Here, argc and argv are the parameters passed to main() and width and height are whatever width and height your window ("table") should be. You'll probably -want to calculate the size of the table based on the sizes of the -cards and margins (they're defined in cards.h). The -init_table() call does everything needed to get the X -interface running. The table_loop() call passes control over -to the Ace library, and does not return. Instead, the Ace library -manages the X interface, and calls functions you define when user -interaction occurs (see the events section below). +want to calculate the initial size of the table based on the sizes of +the cards and margins (they're defined in cards.h). The +init_*() calls do everything needed to get the X interface +running. The table_loop() call passes control over to the +Ace library, and does not return. Instead, the Ace library manages +the X interface, and calls functions you define when user interaction +occurs (see the events section below).

Makefiles and Linking

-You'll need to add -lXpm -lX11 to the end of your link line +You'll need to add -lpng -lz -lX11 to the end of your link line in your Makefile. You'll also need to link the Ace library, which for me means adding ../lib/cardlib.a but you'll need to do whatever is appropriate for where you installed the library. For @@ -80,22 +73,22 @@ Example: 
 sol : sol.o sol-help.o sol-img.o
-	$(CC) $(CFLAGS) -o $@ $^ -lcards -lXpm -lX11
+	$(CC) $(CFLAGS) -o $@ $^ -lcards -lpng -lz -lX11
Note in the example above that your game will probably consist of at least three files. First is the game itself (sol.o in this example). Next is the help file (sol-help.o), which started as HTML and was converted to C by text2c. Last is the image -library (sol-img.o) which is generated from your gifs by -gif2pack. To build these, you'll need rules like this: +library (sol-img.o) which is generated from your pngs by +make-imglib. To build these, you'll need rules like this: 
 %-help.c : %.html ../lib/text2c
 	../lib/text2c $*_help < $< > $@
 
-%-img.c : %.gif ../lib/gif2pack
-	../lib/gif2pack -b appimglib -o $@ $<
+%-img.c : %.png
+	../lib/make-imglib -i $(srcdir) -n appimglib - $@ $<
Of course, you'll need to adjust these for your situation. @@ -130,15 +123,23 @@ also set up for you. The best way to de redraw the entire window and let the Ace and X libraries worry about limiting you to the parts that were actually exposed.

+
void resize(int width, int height) + +
If you provide this function, your game becomes resizable, and +you will be responsible for repositioning all the images and stacks +according to the new size. You will probably need to call +stack_set_card_size (and read back the actual sizes with +stack_get_card_size and stack_get_fans).

+
void key(int k, int x, int y)
This function is called each time the user presses a key. If the key they pressed is a regular key with an ASCII equivalent (like `h'), -the ASCII code is passed as k, otherwise the X keycode (like -XK_F1) is passed. The location of the pointer is passed as x and y. -If you do not define this function, a default is provided which exits -when the user presses ESC or Ctrl-C. Your routine should do a similar -check to remain consistent with other Ace programs.

+the ASCII code is passed as k, otherwise the keyc ode (like +KEY_F(1) or KEY_UP) is passed. The location of the pointer is passed +as x and y. If you do not define this function, a default is provided +which exits when the user presses ESC or Ctrl-C. Your routine should +do a similar check to remain consistent with other Ace programs.

void click(int x, int y, int b) @@ -173,29 +174,36 @@ holding the button down.

CARD_WIDTH, CARD_HEIGHT, CARD_MARGIN -
These macros define the size of the cards, and the amount of -space you should allow for between cards and around the edge of the +
These macros define the default size of the cards, and the amount +of space you should allow for between cards and around the edge of the window. By using these macros, your program will have the same style as other programs written with this library.

CARD_FAN_DOWN, CARD_FAN_RIGHT, CARD_FAN_TBDOWN, CARD_FAN_TBRIGHT -
These macros define the offsets to be used when a stack of cards -is "fanned" in a given direction (only down and right are supported). -The TB versions are for a "tiny bit" of fanning; just enough -to hint at the value of the card, whereas the others offset them -enough to clearly see the value of the card.

+
These macros define the default offsets to be used when a stack +of cards is "fanned" in a given direction (only down and right are +supported). The TB versions are for a "tiny bit" of fanning; +just enough to hint at the value of the card, whereas the others +offset them enough to clearly see the value of the card.

+ +
void init_ace(int argc, char **argv) + +
This function initlizes the Ace library. It processes all +command line options and connects to the display. After calling this, +the global variables display_width and +display_height are valid, and table_width and +table_height are non-zero if the user requested a specific +size on the command line. If you need to see a command line option, +create an OptionDesc list for your game (see cards.h for details).

void init_table(int argc, char **argv, int table_width, int table_height)
This function sets up the interface to X and creates the initial -window. You should pass it the command line arguments main() -was called with, as well as the dimensions of the window. This -function must be called exactly once from main(). Upon -return, any arguments used by the library will be removed from the -argument list, leaving the extras behind.

+window. This function must be called exactly once from +main().

void table_loop() @@ -207,7 +215,7 @@ program (via events).

Picture *get_picture(char *name)
This function loads one of the images that you added to your -program with the gif2pack program (either the +program with the make-imglib program (either the application-specific ones, or the standard ones). This function searches one table prefixed by imglib (the standard set) and one prefixed by appimglib (the app-specific set). Note that @@ -217,7 +225,6 @@ native X format is deferred until it is Picture type is as follows: @@ -441,6 +448,22 @@ being able to see the value of the card. STACK_OFFSET_TBRIGHT, and STACK_OFFSET_TBDOWN. The TB versions are for a "tiny bit" of offset.

+
void stack_set_card_size(int width, int height) + +
Request that the card size be changed, such as after a resize. +Note that the values you give are requests - the library may need to +use a different size. Use stack_get_card_size to find out +what was really used.

+ +
void stack_get_card_size(int *width, int *height) + +
Find out how big the current cards are.

+ +
void stack_get_fans(int *down, int *right, int *tbdown, +int *tbright) + +
Get the offsets for fan_down, etc.

+
void stack_set_empty_picture(Stack *s, Picture *p)
This lets you specify a picture that is drawn when the stack is @@ -616,72 +639,29 @@ that are specific to that application. will be specific. Each application is allowed to create one additional library of pictures that can be linked into your program; the library has the other one. To add images, paint your images in -standard GIF format (no animations, limited to 64 colors per GIF, -transparency is supported). Then, call gif2pack like this: +standard PNG format (no animations, transparency is supported). Then, +call make-imglib like this: 
-gif2pack -b appimglib -o mypictures.c *.gif
+gif2pack -i $(srcdir) -n appimglib - mypictures.c *.png
-Of course, replace mypictures.c and *.gif with +Of course, replace mypictures.c and *.png with appropriate stuff for your application. This will create a C source -file that contains your image data and some statistics about your -images to speed up loading (such as the number of rows, number of -images, uncompressed data size, etc). Then, compile and link that +file that contains your image data. Then, compile and link that source with your other sources. By calling your picture library appimglib, the ace library functions will automatically use it. When you call get_picture, pass the name of the original -file (*.gif) you passed to gif2pack, including any -path information (like "card/7h.gif").

- -

Graphics - Behind the Scenes

- -

I had some goals in mind when I designed the graphics storage -system. They were (if I remember correctly): easy to edit the images, -easy to load the images in the app, don't take up a lot of space, and -avoid patent problems. So, I decided to use a compressed Xpm format -for storage in the application. Here's how everything works: - -

Calling X Directly

-If you must call X directly (to draw lines or whatnot), look in -table.c for a list of non-static variables you can use after -your init() function is called. These are: +If you must call X directly (to draw lines or whatnot), look in xwin.c +for a list of non-static variables you can use after your +init() function is called. These are: 
 extern Display *display;
@@ -699,6 +679,9 @@ during exposures, the clip mask in the g
 must mess with the clip mask, be careful to restore it if you can, or
 create your own GC to draw with.
 
+
If you do this, your program will not be portable to other
+windowing systems if/when that ever happens.
+
 
Online Help

 
 To add online help to your application, you need to write the help
@@ -754,10 +737,10 @@ start a new paragraph - but you should u
 
Line break.  The next "thing" will be at the left margin of the
 next line.  Multiple BR act like one BR.
 
-
<img src=dir/file.gif>
-
<img align=center src=dir/file.gif>
-
<img align=left src=dir/file.gif>
-
<img align=right src=dir/file.gif>
+
<img src=file>
+
<img align=center src=file>
+
<img align=left src=file>
+
<img align=right src=file>
 
 
An image.  No quotes around the file name, which is as you'd pass
 to get_picture (since that's what it does).  The
@@ -793,5 +776,5 @@ extern char my_help[];
 help("mygame-help.html", my_help);
-
Copyright © 1998 Copyright © 2001 DJ Delorie