I have taken their work and adapted it for use with paragui. All the decent organization is Tony and Ian's. Mistakes are my own. Please do not contact them with any questions regarding this document as they had nothing to do with the final version.
Paragui is built upon SDL (http://www.libsdl.org/) which is is a cross-platform multimedia library designed to provide low level access to audio, keyboard, mouse, joystick, 3D hardware via OpenGL, and 2D video framebuffer. Thus Paragui is very cross-platform as well full featured. The power of SDL is available in Paragui.
The primary authors of SDL are:
Special thanks go to Sam Lantinga <slouken@libsdl.org> for the great SDL library <http://www.libsdl.org>.
The primary authors of Paragui are:
Alexander Pipelka <pipelka@teleweb.at>
Sebastian Haag <ulf82@users.sf.net>: Win32 maintenance bug fix wizard overall improvements
Keith Swyer <ksswyer@hotmail.com>: MacOS support CodeWarrior 7 project files
David Hedbor <david@hedbor.org>: GCC 3.0/Win32 testing VisualC++ workspaces bug fixes C++ standards checking SDL_rotozoom integration
Marek Habersack <grendel@vip.net.pl>: PG_PopupMenu STLport integration
Ales Teska <ales.teska@dbinvest.cz>: new freetype font rendering XML layout loader various small changes
Jaroslav Vozab <vozab@dbsystem.cz>: PG_RichEdit, PG_WidgetListEx new text rendering
Antonin Hildebrand <woid@centrum.cz>: Win32 testing
Mike Dunston <atani@atani-software.net>: PG_SpinnerBox first version of zipped themes
Michael Moerz <aon.912411198@aon.at>: Debian packaging
Jacek Poplawski - OpenGL ideas Donald Molaro - bug fixes
rotozoom.cpp is based on the LGPL package SDL_rotozoom by A. Schiffler <aschiffler@home.com>. Reworked to fit into the ParaGUI framework by David Hedbor <david@hedbor.org>.
PhysicsFS <http://icculus.org/physfs/> is copyrighted by Ryan C. Gordon <icculus@clutteredmind.org> under the LGPL.
Thanks to the many people providing patches, fixes & ideas:
Andrew Ford Brian T. Crowder Oliver Lietz Henrik Edwards Paolo Ciccone David Hunt Jens Rieks Dave Robillard Ray Kelm Francis Irving Pete Shinners Franck Guillaud
Sorry, if I forgot anyone. If I did, then please email me (follinge@piconap.com).
This tutorial is an attempt to document as much as possible of Paragui, but it is by no means complete. This tutorial assumes a good understanding of C++, and how to create C++ programs. It would be a great benefit for the reader to have previous SDL programming experience, but it shouldn't be necessary. If you are learning Paragui as your first widget set, please comment on how you found this tutorial, and what you had trouble with. There are also Python and Ruby, and other language bindings available, and I believe C bindings in the works. Check the bindings directory in the toplevel of the Paragui source code for details.
To begin our introduction to Paragui, we'll start with the simplest program possible.
#include "pgapplication.h" int main() { // construct the application object PG_Application app; //app.EnableBackground(true); app.LoadTheme("default"); // init 1024x768 if(!app.InitScreen(800,600, 0, SDL_SWSURFACE)){ printf("Resolution not supported\n"); exit(-1); } // Enter main loop app.Run(); return EXIT_SUCCESS; }
g++ `paragui-config --cflags` -c hello.cpp g++ hello.o -o hello `paragui-config --libs`
The first line will compile the hello.o file. It takes the output of paragui-config, which is a program that is used to get the compilation flags. The next line compiles the hello.o into an executable.
All programs will of course include "pgapplication.h" which contains the class that represents an application in ParaGUI. It handles the main loop and screen attibutes.
An application must have a maximum of one PG_Application. If you try to create more than one PG_Application the constructor will exit your application with an console error message.
The first line, main() {, is boilerplate C++.
The next line, PG_Application app, creates the paragui application object.
The next line, app.LoadTheme("default"), loads the theme. Themes are one of the greatest features of paragui as they allow you to change the look and feel of an application without recoding C++. Themes will be explained later. For now, its enough to know that you should include this line as boilerplate code.
This line pops up a window or it exits the application gracefully if the window can not be popped up for some reason.
Finally, app.Run(). This line is a bit confusing for people who are unused to dealing with gui toolkits. Why do I need to run my app? Actually, the next line is a little misleading. The application can run without the next line, but it won't be interactive unless you add a great deal of more code.
The app.Run() line inverts the usual way that an application runs. When one writes a script style application, one instruction after the next is executing.
In the initial parts of this application, we have seen that this is true. However, in a gui application, most of the app's time is spent waiting for user input.
Designers of toolkits were clever and made a shortcut so that instead of writing code each time to handle all that input, it would be automatically handled by the toolkit. Details of input handling will be explained in subsequent chapters on callbacks.
FIXME: Start here and make this paragui style:
This passing of control is done using the idea of "signals". (Note that these signals are not the same as the Unix system signals, and are not implemented using them, although the terminology is almost identical.) When an event occurs, such as the press of a mouse button, the appropriate signal will be "emitted" by the widget that was pressed. This is how GTK does most of its useful work. There are signals that all widgets inherit, such as "destroy", and there are signals that are widget specific, such as "toggled" on a toggle button.
To make a button perform an action, we set up a signal handler to catch these signals and call the appropriate function. This is done by using a function such as: