## 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.