## visu_gtk visu_gtk — Basic GUI routines, for preview, standard dialogs... |

## Synopsis

    GtkWidget *         (*VisuGtkWidgetFunc)                (void);
    void                (*VisuGtkInitWidgetFunc)            (GtkWindow **panel,
                                                             GtkWindow **renderWindow,
                                                             GtkWidget **renderArea);
    void                visuGtkRaise_warning                (gchar *action,
                                                             gchar *message,
                                                             GtkWindow *window);
    void                visuGtkRaise_warningLong            (gchar *action,
                                                             gchar *message,
                                                             GtkWindow *window);
    gboolean            (*VisuGtkSetFilesFunc)              (VisuData *data,
                                                             GtkWindow *parent);
    void                visuGtkSet_renderingSpecificMethods (VisuRendering *method,
                                                             VisuGtkSetFilesFunc methodLoad);
    VisuGtkSetFilesFunc  visuGtkGet_renderingSpecificOpen   (VisuRendering *method);
                        VisuGtkPreview;
    VisuGtkPreview*     visuGtkPreview_add                  (VisuGtkPreview *preview,
                                                             GtkFileChooser *chooser);
    void                visuGtkPreview_update               (VisuGtkPreview *preview,
                                                             const char *filenames[]);
    gchar**             visuGtkGet_selectedDirectory        (GtkWindow *parent,
                                                             gboolean multiple,
                                                             const gchar *dir);
    gboolean            visuGtkGet_fileFromDefaultFileChooser
                                                            (VisuData *data,
                                                             GtkWindow *parent);
    void                visuGtkMain                         (VisuGtkInitWidgetFunc panelFunc);
    gboolean            visuGtkRun_commandLine              (gpointer data);
    void                visuGtkWait                         (void);
    GList*              visuGtkCreate_fileChooserFilter     (GList *list,
                                                             GtkWidget *fileChooser);
    enum                VisuGtkDirType;
    gchar*              visuGtkGet_lastOpenDirectory        (void);
    void                visuGtkSet_lastOpenDirectory        (const char *directory,
                                                             VisuGtkDirType type);
    GdkPixbuf*          visuGtkCreate_pixbuf                (const gchar *filename);
    void                visuGtkCreate_main                  (GtkWindow **panel,
                                                             GtkWindow **renderWindow,
                                                             GtkWidget **renderArea);
    GtkWindow*          visuGtkGet_panel                    (void);
    GtkWindow*          visuGtkGet_render                   (void);
    GtkWidget*          visuGtkGet_renderArea               (void);

## Description

## Details

### VisuGtkWidgetFunc ()

    GtkWidget *         (*VisuGtkWidgetFunc)                (void);

This prototype is used whenever a method is required to create a GtkWidget.

Returns : | a newly created GtkWidget.. transfer full.

### VisuGtkInitWidgetFunc ()

    void                (*VisuGtkInitWidgetFunc)            (GtkWindow **panel,
                                                             GtkWindow **renderWindow,
                                                             GtkWidget **renderArea);

This prototype is used whenever a method is required to initialise the GTK interface of V_Sim. `panel` must be set to point on the window of the command panel, `renderWindow` must point to the window containing the rendering area (can be the same than `panel`) and `renderArea` contains the widget that does the OpenGL rendering.

`panel` : | a location for a GtkWindow ;
`renderWindow` : | a location for a GtkWindow ;
`renderArea` : | a location for a GtkWidget.

### visuGtkRaise_warning ()

    void                visuGtkRaise_warning                (gchar *action,
                                                             gchar *message,
                                                             GtkWindow *window);

Raise a warning window with the action in bold and the message written underneath.

`action` : | a string ;
`message` : | another string ;
`window` : | the parent window to raise the warning on.

### visuGtkRaise_warningLong ()

    void                visuGtkRaise_warningLong            (gchar *action,
                                                             gchar *message,
                                                             GtkWindow *window);

Same as `visuGtkRaise_warning()` except that the message is displayed in a text buffer, ideal for a log.

`action` : | a string ;
`message` : | another string ;
`window` : | the parent window to raise the warning on.

### VisuGtkSetFilesFunc ()

    gboolean            (*VisuGtkSetFilesFunc)              (VisuData *data,
                                                             GtkWindow *parent);

Methods that conform to this prototype is used to set filename(s) to be loaded when the 'load' button is pushed. They can use a GtkFileChooser to prompt the user for file names.

`data` : | a VisuData to store the informations ;
`parent` : | the parent window of the dialog.
Returns : | FALSE if no filename as been set, TRUE if the calling method should call `gtkMainLoadAndRender_file()` with a g_idle_add method.

### visuGtkSet_renderingSpecificMethods ()

    void                visuGtkSet_renderingSpecificMethods (VisuRendering *method,
                                                             VisuGtkSetFilesFunc methodLoad);

This function is used by a client to add gtk methods to a rendering method. The `methodLoad` argument is called to when the 'load' button is pushed.

`method` : | a RenderingMethod object;
`methodLoad` : | a VisuUiMainSetFilesFunc method (can be NULL).

### visuGtkGet_renderingSpecificOpen ()

    VisuGtkSetFilesFunc  visuGtkGet_renderingSpecificOpen   (VisuRendering *method);

This method is used to retrieve the VisuUiMainSetFilesFunc associate with the specified `method`.

`method` : | a RenderingMethod object.
Returns : | a load method if one has been specified for `method` or `gtkMainClassSet_fileFromDefaultFileChooser()`.

### VisuGtkPreview

    typedef struct {
      GtkWidget *check;
      GtkWidget *image;
      GtkWidget *table;
      GtkWidget *vbox;

      gpointer data;
    } VisuGtkPreview;

A container for the relevant widgets of the preview area.

GtkWidget *`check`; | the widget used to allow or not preview ;
GtkWidget *`image`; | the GtkImage with the preview ;
GtkWidget *`table`; | a GtkTable with file informations ;
GtkWidget *`vbox`; | the GtkVBox with all the stuff for previewing.
gpointer `data`; |

### visuGtkPreview_add ()

    VisuGtkPreview*     visuGtkPreview_add                  (VisuGtkPreview *preview,
                                                             GtkFileChooser *chooser);

Create the widgets to have a preview attached to `filechooser`. But the signal raised by `filechooser` when previewing is needed is not attached and this must be done by the user with custom routine.

`preview` : | a location on VisuGtkPreview (uninitialised) ;
`chooser` : | the filechooser the preview must be attached to.
Returns : | `preview` itself.

### visuGtkPreview_update ()

    void                visuGtkPreview_update               (VisuGtkPreview *preview,
                                                             const char *filenames[]);

This routine update the content of the given `preview` by making a rendering in a pixmap of the given filenames. The number of given filenames must match the number required by the current rendering method. Only the nodes, the box and the background (plus fog) is actually previewed.

`preview` : | a location on VisuGtkPreview (initialised) ;
`filenames` : | an array of filenames.

### visuGtkGet_selectedDirectory ()

    gchar**             visuGtkGet_selectedDirectory        (GtkWindow *parent,
                                                             gboolean multiple,
                                                             const gchar *dir);

General procedure to get the location of one or more directories. In the multiple case, all selected directories shares a common ancestor since the selection is done through the same selector that for single directory but with multiple selection activated. If `dir` is NULL the last opened (and stored) directory is used (see `visuGtkGet_lastOpenDirectory()` and `visuGtkSet_lastOpenDirectory()`).

`parent` : | if NULL, the command panel window is used ;
`multiple` : | if TRUE, multiple directories can be selected ;
`dir` : | if not NULL, give the opening directory.
Returns : | a newly allocated array of paths, NULL terminated. Use `g_strfreev()` to free it after use. If no directory is selected, then NULL is returned.

### visuGtkGet_fileFromDefaultFileChooser ()

    gboolean            visuGtkGet_fileFromDefaultFileChooser
                                                            (VisuData *data,
                                                             GtkWindow *parent);

This method is a default method to launch a file chooser that select a single file, with the filters of the current RenderingMethod. It creates a modal dialog, and wait for its reponse. If OK is clicked, the selected filename is stored. If Cancel is clicked, nothing is done. The dialog is destroyed after use.

`data` : | an allocated VisuData to store the file names ;
`parent` : | the parent window of the dialog.
Returns : | FALSE if no file has been set, TRUE if the calling method should call `gtkMainLoadAndRender_file()` with a `g_idle_add()` method.

### visuGtkMain ()

    void                visuGtkMain                         (VisuGtkInitWidgetFunc panelFunc);

It initializses the GTK part of V_Sim. During this initialisation, the `panelFunc` is called. It should create all the windows needed by V_Sim, like the command panel and the rendering area. The return widget is the widget returned itself by `panelFunc`. It must be the main widget: it is the command panel if used, the window containing the rendering area if no command panel or the rendering area itself if no container window.

`panelFunc` : | function to be called to create the different windows.
Returns : | the main widget for V_Sim, returned itself by `panelFunc`.

### visuGtkRun_commandLine ()

    gboolean            visuGtkRun_commandLine              (gpointer data);

Call the get routines from the command line module and deal with them. This method is not aware of the panels and is intended to be called only when the command panel is not used. In the opposite case, use `visu_ui_main_runCommandLine()` instead.

`data` : | a pointer to the command panel (see VisuUiMain).
Returns : | FALSE always.

### visuGtkWait ()

    void                visuGtkWait                         (void);

It runs the Gtk event loop, flushing it before returning.

### visuGtkCreate_fileChooserFilter ()

    GList*              visuGtkCreate_fileChooserFilter     (GList *list,
                                                             GtkWidget *fileChooser);

Create a list of GtkFileFilter created from the given list of file formats and attach it to the given `fileChooser`.

`list` : | a GList of ToolFileFormat ;
`fileChooser` : | a file chooser to associate filters with.
Returns : | a list of FileFilterCustom. This list should be freed after use.

### enum VisuGtkDirType

    typedef enum
      {
        VISU_DIR_FILE,
        VISU_DIR_SURFACE,
        VISU_DIR_DATAFILE,
        VISU_DIR_CONF,
        VISU_DIR_BROWSER,
        /*< private >*/
        N_VISU_DIR
      } VisuGtkDirType;

V_Sim remembers the last open directory when presenting a new file selector. This enum is used to specify different kind of directories. Like that saving a configuration file in a given directory will not affect the prefered directory for browsing a list of files.

`VISU_DIR_FILE` | default kind of directory ;
`VISU_DIR_SURFACE` | directory for surfaces ;
`VISU_DIR_DATAFILE` | directory for data files ;
`VISU_DIR_CONF` | directory for configuration files ;
`VISU_DIR_BROWSER` | directory used in the browser.
`N_VISU_DIR` | private.

### visuGtkGet_lastOpenDirectory ()

    gchar*              visuGtkGet_lastOpenDirectory        (void);

V_Sim stores the last open directory to set the file chooser to this one the next time it will come. Use `visuGtkSet_lastOpenDirectory()` to store it after a GTK_RESPONSE_OK has been returned by a file chooser and then initialise each new with this routine.

Returns : | a string owned by V_Sim.

### visuGtkSet_lastOpenDirectory ()

    void                visuGtkSet_lastOpenDirectory        (const char *directory,
                                                             VisuGtkDirType type);

V_Sim stores the last open directory to set the file chooser to this one the next time it will come. Use this routine each time a file chooser returns GTK_RESPONSE_OK. The given string will be copied and can be freed after use.

`directory` : | a full path to a directory ;
`type` : | the kind of directory to set the remember flag on.

### visuGtkCreate_pixbuf ()

    GdkPixbuf*          visuGtkCreate_pixbuf                (const gchar *filename);

Replace the `create_pixbuf()` routine from Glade. It looks only in the default pixmap directory of V_Sim to find the given file.

`filename` : | a file name (must be a base name).
Returns : | a newly created GdkPixbuf on success.

### visuGtkCreate_main ()

    void                visuGtkCreate_main                  (GtkWindow **panel,
                                                             GtkWindow **renderWindow,
                                                             GtkWidget **renderArea);

A convenient routine that creates a VisuRenderingWindow alone. To create also a command panel, `visu_uiMainClass_createMain()` should be used instead.

`panel` : | a location for a GtkWindow, will be NULL at return time ;
`renderWindow` : | a location for a GtkWindow ;
`renderArea` : | a location for a GtkWidget.

### visuGtkGet_panel ()

    GtkWindow*          visuGtkGet_panel                    (void);

A convenient function to get the command panel window.

Returns : | a GtkWindow.

### visuGtkGet_render ()

    GtkWindow*          visuGtkGet_render                   (void);

A convenient function to get the rendering area window.

Returns : | a GtkWindow.

### visuGtkGet_renderArea ()

    GtkWidget*          visuGtkGet_renderArea               (void);

A convenient function to get the rendering area widget.

Returns : | a GtkWidget.