PongXML object

If you want to do something more complex with PonG, you may want to use the PongXML object. This object loads the XML file and can display a dialog on request. It also has the advantage that if you request a dialog while the first dialog is still running, the existing one will just be raised again, rather then another dialog starting. You can also have more control over what PonG does this way.

For a simple case scenarion, you will need the pong_xml_new function, and the pong_xml_show_dialog. The first takes the filename as an argument, and the second shows the dialog. If the dialog is already shown, it just shows and raises it again. So a basically equivalent case to the pong_run_simple_dialog example would be:

void
show_preferences (void)
{
  static PongXML *xml = NULL;

  if (xml == NULL) {
    xml = pong_xml_new ("mypongfile.pong");
  }

  if (xml == NULL) {
    g_warning ("Cannot load mypongfile.pong");
    return;
  }

  pong_xml_show_dialog (xml);
}
	  

If you need to load a .pong file from memory, you can use the pong_xml_from_memory function which takes a buffer and the size of the buffer as arguments.

When you are done with the object you can just use gtk_object_unref, just like on any other GTK+ object. Do note however that if the dialog is still on screen, it also holds a reference to the PongXML object and the object may not actually die until the user closes the dialog. If you wish to close the dialog, you can use the pong_xml_close_dialog method with the PongXML object as argument.

Also note that "show_dialog" and "close_dialog" are signals, so you can bind these if you need something to happen on those actions. However note that "close_dialog" is not a good signal to track if the dialog is up or not, for that use the "destroy" signal of the dialog. "close_dialog" simply means that some code requested the dialog to be closed.

You will also probably want to set the dialog widget to be parented (transient for) your main window. The dialog is a widget of type GnomeDialog so you can use gnome_dialog_set_parent. You can get the dialog widget from the PongXML object by use of the pong_xml_get_dialog_widget function, which returns a GtkWidget * pointer.

The documentation for this object is in the inline API guide, though I didn't get that to work for 1.0.0, so you may want to read the source code, it has documentation inline using the standard gtk-doc format.