## visu_windowInterface

visu_windowInterface

## Synopsis

    typedef             GenericRenderingWindow;
    int                 visuRenderingWindowInit             (char *windowRef,
                                                             char *iconRef,
                                                             char *window_name,
                                                             char *class_name,
                                                             int width,
                                                             int height);
    void                setObserveEventListener             (GenericRenderingWindow window);
    void                setInteractiveHandlers              (GenericRenderingWindow window,
                                                             VisuInteractive *inter);
    void                setPickEventListener                (GenericRenderingWindow window);
    void                removeEventListener                 (GenericRenderingWindow window);
    void                checkWindowSize                     (GenericRenderingWindow window,
                                                             unsigned int *width,
                                                             unsigned int *height);
    void                visuRenderingWindowFree_backgroundImage
                                                            (GenericRenderingWindow window,
                                                             gpointer image);
    gpointer            visuRenderingWindowGet_backgroundImage
                                                            (GenericRenderingWindow window,
                                                             guchar **rowData,
                                                             gboolean *hasAlphaChannel,
                                                             int *width,
                                                             int *height);
    GenericRenderingWindow visuRenderingWindowGet_current   ();
    void                visuRenderingWindowGet_backgroundColor
                                                            (GenericRenderingWindow window,
                                                             float rgb[3]);
    VisuData*           visuRenderingWindowGet_visuData     (GenericRenderingWindow window);
    void                visuRenderingWindowSet_visuData     (GenericRenderingWindow window,
                                                             VisuData *data);
    void                visuRenderingWindowSet_default      (GenericRenderingWindow window);
    gboolean            visuRenderingWindowDump             (GenericRenderingWindow window,
                                                             DumpType *format,
                                                             char *fileName,
                                                             gint width,
                                                             gint height,
                                                             GError **error,
                                                             voidDataFunc functionWait,
                                                             gpointer data);

## Description

A longer description goes here.

## Details

### GenericRenderingWindow

    typedef gpointer GenericRenderingWindow;

This is an alias to store a pointer to the object that represent the redering window. If the window is rendered by GTK, for instance, GenericRenderingWindow is equivalent to a RenderingWindow object.

### visuRenderingWindowInit ()

    int                 visuRenderingWindowInit             (char *windowRef,
                                                             char *iconRef,
                                                             char *window_name,
                                                             char *class_name,
                                                             int width,
                                                             int height);

This routine will call the backend windowing method to create a rendering window.

`windowRef` : | a title for the window ;
`iconRef` : | a path to an icon (may be NULL) ;
`window_name` : | a string to identify the window inside a class of window ;
`class_name` : | a string to identify the class of the window ;
`width` : | the width ;
`height` : | the height.
Returns : | 0 if everything went right.

### setObserveEventListener ()

    void                setObserveEventListener             (GenericRenderingWindow window);

Bring up the interactive mode listeners (clic, drag...) for observe mode and connect then to the given methods pointed by `userCallbacks`.

`window` : | a pointer on a valid rendering window object (see RenderingWindow if GTK is used for rendering).

### setInteractiveHandlers ()

    void                setInteractiveHandlers              (GenericRenderingWindow window,
                                                             VisuInteractive *inter);

Set the listeners needed for the `inter` argument.

`window` : | a pointer on a valid rendering window object (see RenderingWindow if GTK is used for rendering) ;
`inter` : | an interactive descriptive session.

### setPickEventListener ()

    void                setPickEventListener                (GenericRenderingWindow window);

Bring up the interactive mode listeners (clic, drag...) for pick mode and connect then to the given methods pointed by `userCallbacks`.

`window` : | a pointer on a valid rendering window object (see RenderingWindow if GTK is used for rendering).

### removeEventListener ()

    void                removeEventListener                 (GenericRenderingWindow window);

Remove all listeners responsible for the interactive mode.

`window` : | a pointer on a valid rendering window object (see RenderingWindow if GTK is used for rendering).

### checkWindowSize ()

    void                checkWindowSize                     (GenericRenderingWindow window,
                                                             unsigned int *width,
                                                             unsigned int *height);

Get the rendering window size by asking the X server.

`window` : | a pointer on a valid rendering window object (see RenderingWindow if GTK is used for rendering) ;
`width` : | a pointer to store the width of the window ;
`height` : | a pointer to store the height of the window.

### visuRenderingWindowFree_backgroundImage ()

    void                visuRenderingWindowFree_backgroundImage
                                                            (GenericRenderingWindow window,
                                                             gpointer image);

Free loaded image.

`window` : | a pointer on a valid rendering window object (see RenderingWindow if GTK is used for rendering) ;
`image` : | an opaque structure returned by `visuRenderigWindowGet_backgroundImage()`.

### visuRenderingWindowGet_backgroundImage ()

    gpointer            visuRenderingWindowGet_backgroundImage
                                                            (GenericRenderingWindow window,
                                                             guchar **rowData,
                                                             gboolean *hasAlphaChannel,
                                                             int *width,
                                                             int *height);

Use this method to load an image in memory (according to GdkPixbuf specification) and retrieve the row data in memory.

`window` : | a pointer on a valid rendering window object (see RenderingWindow if GTK is used for rendering) ;
`rowData` : | a pointer to be set on the data in memory ;
`hasAlphaChannel` : | a pointer to store if the loaded iage has an alpha channel ;
`width` : | store the width ;
`height` : | store the height.
Returns : | a pointer to an opaque structure that must be freed after use by a call to visuRenderigWindowFree_backgroundImage:().

### visuRenderingWindowGet_current ()

    GenericRenderingWindow visuRenderingWindowGet_current   ();

Method used to get a pointer to the current active window.

Returns : | a pointer to the current active window.

### visuRenderingWindowGet_backgroundColor ()

    void                visuRenderingWindowGet_backgroundColor
                                                            (GenericRenderingWindow window,
                                                             float rgb[3]);

This method is used to retrieve the color of the rendering window, depending on its style (see v_sim.rc for example if the rendering window is monitored by GTK).

`window` : | a pointer on a valid rendering window object (see RenderingWindow if GTK is used for rendering) ;
`rgb` : | an allocated array of three floating point values.

### visuRenderingWindowGet_visuData ()

    VisuData*           visuRenderingWindowGet_visuData     (GenericRenderingWindow window);

This method is used to get the VisuData attached to a window.

`window` : | a pointer on a valid rendering window object (see RenderingWindow if GTK is used for rendering).
Returns : | the VisuData attached to the `window` or NULL if none.

### visuRenderingWindowSet_visuData ()

    void                visuRenderingWindowSet_visuData     (GenericRenderingWindow window,
                                                             VisuData *data);

This method is used to attach a VisuData object to a given window. When, `data` is not NULL, this method emit the dataReadyForRendering signal, and all modules that needs to draw something should catch this signal and draw in the rendering window. If `data` is NULL, the dataNotReadyForRendering is emitted instead.

`window` : | a pointer on a valid rendering window object (see RenderingWindow if GTK is used for rendering) ;
`data` : | a VisuData to render in the given `window`.

### visuRenderingWindowSet_default ()

    void                visuRenderingWindowSet_default      (GenericRenderingWindow window);

Method used to set the window returned by `visuRenderingWindowGet_current()`.

`window` : | a pointer to a rendering area to become default.

### visuRenderingWindowDump ()

    gboolean            visuRenderingWindowDump             (GenericRenderingWindow window,
                                                             DumpType *format,
                                                             char *fileName,
                                                             gint width,
                                                             gint height,
                                                             GError **error,
                                                             voidDataFunc functionWait,
                                                             gpointer data);

Call this method to dump the given `window` to a file.

`window` : | a pointer on a valid rendering window object (see RenderingWindow if GTK is used for rendering) ;
`format` : | a DumpType object, corresponding to the write method ;
`fileName` : | a string that defined the file to write to ;
`width` : | an integer ;
`height` : | an integer ;
`error` : | a location to store some error (not NULL) ;
`functionWait` : | a method to call periodically during the dump ;
`data` : | some pointer on object to be passed to the wait function.
Returns : | TRUE if everything went right.