PKguiSpace

This page contains instructions for using the library with GNU toolchain (with G++ compiler). The page is probably vague and not yet complete, but so is the PKgui library. This will change on version 1.0.

Note: The build of the library may be configured to use or not to use OpenGL, GLU, SDL_image and SDL_ttf. These instructions show how to make it work in the simplest possible way, that is by using everything as it is, including the support for OpenGL. The instructions do say, however, how to remove dependancy on SDL_image and SDL_ttf libraries, because this makes it faster to set up PKgui.

To make it work in a new project with the example application:

• Have a GNU toolchain (compiler, debugger, linker, 'make' program) installed on your machine. If on Linux, you probably already have one. If on Windows, download MinGW (this stands for Minimalistic GNU for Windows).
• Download and install SDL library. If you want to use *.ttf font files and image files other than *.bmp, also download SDL_ttf and SDL_image libraries. You can find those libraries on www.libsdl.org.
• There is no makefile provided for the project. Use an IDE, for example Eclipse+CDT or Code::Blocks. Install one of them if you do not have one and configure it to use the installed toolchain (both Eclipse+CDT and Code::Blocks probably will automatically detect and use the GNU toolchain).
• Download the PKgui by using "check out" command in your Subversion client. You will need the path to repository, which you can find after clicking "Source/SVN" tab on this page. When your Subversion client downloads all the files, there will be a 'pkgui' directory inside - this is the main directory of the library. It will contain some sources of an example application, collective header files of the library (the final one is PKgui.h) and and folders with the source of the library.
• Launch your IDE and create new C++ project from existing source in the 'pkgui' directory. You can safely add all the *.h and *.cpp files to the sources intended to be compiled. Refer to the IDE documentation if you have problems. 
• Make the linker link with the SDL and library and possibly some other libraries. To do this, in your IDE go to menu entry with flags for linker and insert (when working on Linux) SDLmain, SDL and glu32. Depending on the IDE, you may need to enter -lSDL instead. If you are using windows with MinGW, you will need to insert mingw32, SDLmain, opengl32 and glu32. If you do not link with the proper libraries you will get an error. In such case read it and determine which library do you need to add to the linker options. If you plan to use ttf fonts and non-bmp images, link with SDL_ttf and SDL_image as well. Otherwise make sure that you add two more compile options that add preprocessor definitions PKGUI_NO_SDL_TTF_DEPENDANCY and PKGUI_NO_SDL_IMAGE_DEPENDANCY. That will stob building the code that uses those two libraries.
• Build the library by clicking the BUILD button in your IDE. This will take a while. If it fails immediately or allmost immediately or the error messages contain words "SDL", "SDL_ttf" or "TTF_" it probably means that you did not configure the libraries correctly. Please make sure that the SDL (and possibly SDL_ttf) header files are in the directory where the compiler will look for them (typically in the 'include' folder of the compiler installation). Also make sure that the .a files are installed (typically in the 'lib' folder of the compiler installation). If the error appears late during the build and the error messages complain about missing elements with "PK" in their names, I probably forgot to add a file to the repository (which is very unlikely). Send me an email, I will fix the problem and send you back some instructions.
• Run the application It will show some widgets, which will probably not be very appealing, because (as of revision 29) the example application is just a rough test. However, the example application will grow and will become more complete. To see what can you do with the application, see these instructions.

 Enjoy using the library!

Integrating the PKgui into an existing project.

Make sure that you have read the above instructions before reading these.

• Install and set up linking with the SDL library in your project. If you want, also do it with SDL_ttf and SDL_image libraries.
• Basically make a subdirectory in the directory of your project.
• Use the "check out" command of your SVN client to download the recent version of PKgui to that subdirectory.
• Add all the PKgui *.h and *.cpp files to your project, excluding files of the example application. The example app files are all the files in "pkgui" directory which do not start with "PK".
• You are ready to compile the PKgui source code together with your project. Before you do that, however, you might want to include the PKgui.h file in one of your project sources, just to check if your project has any name clashes with SDL or PKgui (which is unlikely, but still may happen, expecially with macrodefinitions and old OS headers included by SDL, like windows.h).
• Look at the example application code to see how to initialize global PKgui state.
• To use PKgui in existing project at its initial stage, it is recommended that you use main loop implemented in PKGUI class (call main_loop member function). If you have a lof of you code, however, you might be interested in using PKgui in your custom main loop. In such case, again look at the example application, which has custom main loop.