Pgm

Pgm — A library to create rich application user interfaces.

Synopsis


#include <pgm/pgm.h>

void                pgm_init                            (int *argc,
                                                         char **argv[]);
gboolean            pgm_init_check                      (int *argc,
                                                         char **argv[]);
void                pgm_deinit                          (void);
void                pgm_version                         (guint *major,
                                                         guint *minor,
                                                         guint *micro,
                                                         guint *nano);
gchar *             pgm_version_string                  (void);
gboolean            pgm_events_pending                  (void);
void                pgm_main                            (void);
void                pgm_main_quit                       (void);
void                pgm_main_iteration                  (void);
void                pgm_main_iteration_do               (gboolean blocking);

Description

Pigment initialization

Pigment is a media rendering library written in C providing an abstraction layer to easily design GUI (Graphical User Interfaces) like simple games, media center/set-top box applications, etc. It has a pluggable backend system so that the same application can run on various hardware and software platforms using rendering libraries such as OpenGL or DirectFB on operating systems such as Windows, GNU/Linux or Mac OS X.

Pigment has been designed to handle common issues like non square pixels displays, non square pixels images or video sources, positioning abstraction and scalable user interface support. Moreover, Pigment is a fully thread safe library which means that you can call methods on Pigment objects from multiple threads at the same time even if the rendering backend is not thread safe itself like some OpenGL implementations are for example.

The Pigment library has to be initialized with pgm_init() before it can be used. You should pass pointers to the main argc and argv variables so that Pigment can process its own command line options, as shown in the following example.

Example 1. Initializing the library

int
main (int argc, char *argv[])
{
  pgm_init (&argc, &argv);
  ...
}


The pgm_deinit() call is used to clean up all internal resources used by Pigment.

Use pgm_version() to query the library version at runtime or use the PGM_VERSION_* macros to find the version at compile time. Optionally pgm_version_string() returns a printable string.

Pigment is a GUI toolkit based on an event-driven programming model. When the user is doing nothing, Pigment sits in the main loop and waits for input. If the user performs some action, like a mouse button click, then the main loop "wakes up" and delivers an event to Pigment. When a viewport receives an event, it emits a signal to notify your program that something happened by invoking functions you connected to the signal with g_signal_connect(). Functions connected to a signal are often termed callbacks. When your callbacks are invoked, you would typically take some action, for example when a key of the keyboard is pressed you might update the properties of your drawables. After a callback finishes, Pigment will return to the main loop and await more user input.

Last reviewed on 2007-09-25 (0.3.1)

Details

pgm_init ()

void                pgm_init                            (int *argc,
                                                         char **argv[]);

Initializes the Pigment library.

Note

This function will terminate your program if it was unable to initialize Pigment for some reason. If you want your program to fall back, use pgm_init_check() instead.

argc :

the address of the argc parameter of your main function.

argv :

the address of the argv parameter of your main function.

pgm_init_check ()

gboolean            pgm_init_check                      (int *argc,
                                                         char **argv[]);

Initializes the Pigment library without terminating the program if it was unable to initialize successfully.

argc :

the address of the argc parameter of your main function.

argv :

the address of the argv parameter of your main function.

Returns :

TRUE if Pigment was initialized successfully, FALSE otherwise.

pgm_deinit ()

void                pgm_deinit                          (void);

Deinitializes the Pigment library. This is not going to free Pigment objects, you need to explicitely unref these objects using gst_object_unref().


pgm_version ()

void                pgm_version                         (guint *major,
                                                         guint *minor,
                                                         guint *micro,
                                                         guint *nano);

Gets the version number of the Pigment library.

major :

a pointer to a guint to store the major version number.

minor :

a pointer to a guint to store the minor version number.

micro :

a pointer to a guint to store the micro version number.

nano :

a pointer to a guint to store the nano version number.

pgm_version_string ()

gchar *             pgm_version_string                  (void);

Returns a string that is useful for describing this version of Pigment to the outside world: user agent strings, logging, etc.

Returns :

a newly allocated string describing this version of Pigment.

pgm_events_pending ()

gboolean            pgm_events_pending                  (void);

Checks if any events are pending. This can be used to update the GUI, while doing some time intensive computation.

Example 2. Updating the GUI during a long computation.

  // computation going on
  ...
  while (pgm_events_pending ())
    pgm_main_iteration ();
  ...
  // computation continued


Returns :

TRUE if any events are pending, FALSE otherwise.

pgm_main ()

void                pgm_main                            (void);

Runs the main loop until pgm_main_quit() is called. It's ok to use the GLib main loop directly instead, though it involves slightly more typing. See GMainLoop in the GLib documentation.


pgm_main_quit ()

void                pgm_main_quit                       (void);

Quits the main loop.


pgm_main_iteration ()

void                pgm_main_iteration                  (void);

Runs a single iteration of the main loop. If no events are waiting to be processed, Pigment will block until the next event is noticed. If you don't want to block, look at pgm_main_iteration_do() or check if any events are pending with pgm_events_pending() first.


pgm_main_iteration_do ()

void                pgm_main_iteration_do               (gboolean blocking);

Runs a single iteration of the main loop. If no events are available, either returns or blocks dependent on the value of blocking.

blocking :

TRUE if you want Pigment to block if no events are pending.

See Also

#PgmViewport, PgmDrawable.