## ToolPanel

ToolPanel — Defines a widget that hold a set of V_Sim panel.

## Synopsis

    GtkWidget*          toolPanelNew                        (gchar *id,
                                                             gchar *name,
                                                             gchar *tabName);
    GtkWidget*          toolPanelNew_withIconFromStock      (gchar *id,
                                                             gchar *name,
                                                             gchar *tabName,
                                                             const gchar *stock);
    GtkWidget*          toolPanelNew_withIconFromPath       (gchar *id,
                                                             gchar *name,
                                                             gchar *tabName,
                                                             const gchar *iconPath);
    void                toolPanelAttach                     (ToolPanel *toolPanel,
                                                             DockWindow *dock);
    void                toolPanelDetach                     (ToolPanel *toolPanel);
    void                toolPanelSet_container              (ToolPanel *toolPanel,
                                                             DockWindow *window);
    void                toolPanelSet_containerId            (ToolPanel *toolPanel,
                                                             const gchar *id);
    GtkWindow*          toolPanelGet_containerWindow        (ToolPanel *toolPanel);
    void                toolPanelSet_dockable               (ToolPanel *toolPanel,
                                                             gboolean value);
    DockWindow*         toolPanelGet_container              (ToolPanel *toolPanel);
    const gchar*        toolPanelGet_containerId            (ToolPanel *toolPanel);
    GtkWidget*          toolPanelGet_headerWidget           (ToolPanel *toolPanel);
    const gchar*        toolPanelGet_id                     (ToolPanel *toolPanel);
    const gchar*        toolPanelGet_label                  (ToolPanel *toolPanel);
    VisuData*           toolPanelGet_visuData               (ToolPanel *toolPanel);
    gboolean            toolPanelGet_visible                (ToolPanel *toolPanel);

    GList*              toolPanelClassGet_allToolPanels     ();
    GList*              toolPanelClassGet_allWindows        ();
    DockWindow*         toolPanelClassGet_commandPanel      ();
    DockWindow*         toolPanelClassGet_container         (const gchar *id);
    ToolPanel*          toolPanelClassGet_toolPanelById     (const gchar *id);
    void                toolPanelClassGet_windowCharacteristics
                                                            (DockWindow *dock,
                                                             gchar **id,
                                                             gboolean *visibility,
                                                             gint *x,
                                                             gint *y,
                                                             gint *width,
                                                             gint *height);
    void                toolPanelClassSet_headerVisibility  (gboolean status);
    void                toolPanelClassSet_visuData          (VisuData *dataObj);
    void                toolPanelClassSet_windowPosition    (const gchar *id,
                                                             guint x,
                                                             guint y);
    void                toolPanelClassSet_windowSize        (const gchar *id,
                                                             guint width,
                                                             guint height);
    void                toolPanelClassSet_windowVisibility  (const gchar *id,
                                                             gboolean visible);

                        DockWindow;
    GtkWidget*          dockWindowGet_container             (DockWindow *dock);
    GtkWidget*          dockWindowGet_notebook              (DockWindow *dock);
    GtkWidget*          dockWindowGet_window                (DockWindow *dock);

## Description

This widget is a complex association of a GtkComboBox and a GtkNotebook with V_Sim panels. It can have its own window or be attached into the main command panel.

This widget also has a built-in menu to exchange V_Sim panel between different instances of a ToolPanel. A ToolPanel is refered by its name and has a position and a size. These values can be stored in the parameter files.

## Details

### toolPanelNew ()

    GtkWidget*          toolPanelNew                        (gchar *id,
                                                             gchar *name,
                                                             gchar *tabName);

Create a new ToolPanel with the given `id`, displaying `name` in the combo box of a DockWindow and `tabName` in the tab of the page notebook.

`id` : | a string without space and non internationalised ;
`name` : | a string in UTF-8 that can be internationalised ;
`tabName` : | a shorter name than `name`, in UTF-8 that can be internationalised.
Returns : | a newly created widget.

### toolPanelNew_withIconFromStock ()

    GtkWidget*          toolPanelNew_withIconFromStock      (gchar *id,
                                                             gchar *name,
                                                             gchar *tabName,
                                                             const gchar *stock);

Create a new ToolPanel with the given `id`, displaying `name` in the combo box of a DockWindow and `tabName` in the tab of the page notebook. The displayed icon will be taken from the `stock`.

`id` : | a string without space and non internationalised ;
`name` : | a string in UTF-8 that can be internationalised ;
`tabName` : | a shorter name than `name`, in UTF-8 that can be internationalised ;
`stock` : | the name of a stock icon.
Returns : | a newly created widget.

### toolPanelNew_withIconFromPath ()

    GtkWidget*          toolPanelNew_withIconFromPath       (gchar *id,
                                                             gchar *name,
                                                             gchar *tabName,
                                                             const gchar *iconPath);

Create a new ToolPanel with the given `id`, displaying `name` in the combo box of a DockWindow and `tabName` in the tab of the page notebook. The displayed icon will be read from the `iconPath`.

`id` : | a string without space and non internationalised ;
`name` : | a string in UTF-8 that can be internationalised ;
`tabName` : | a shorter name than `name`, in UTF-8 that can be internationalised ;
`iconPath` : | a path to an icon (should be 20x20).
Returns : | a newly created widget.

### toolPanelAttach ()

    void                toolPanelAttach                     (ToolPanel *toolPanel,
                                                             DockWindow *dock);

Put the given `toolPanel` in the given `dock` window. It adds in this dock window a new page in the GtkNotebook using as tab header the widget returned by `toolPanelGet_headerWidget()`.

`toolPanel` : | a ToolPanel ;
`dock` : | a DockWindow.

### toolPanelDetach ()

    void                toolPanelDetach                     (ToolPanel *toolPanel);

Remove the given `toolPanel` from its current container and add it to the list of hidden tool panels. It can be added again using the pop-up menu of any DockWindow.

`toolPanel` : | a ToolPanel.

### toolPanelSet_container ()

    void                toolPanelSet_container              (ToolPanel *toolPanel,
                                                             DockWindow *window);

Change the container of a toolPanel. If it is currently attached to a DockWindow, it firstly detachs it.

`toolPanel` : | a ToolPanel ;
`window` : | a DockWindow.

### toolPanelSet_containerId ()

    void                toolPanelSet_containerId            (ToolPanel *toolPanel,
                                                             const gchar *id);

Change the container of a toolPanel using the given `id`. If it is currently attached to a DockWindow, it firstly detachs it.

`toolPanel` : | a ToolPanel ;
`id` : | a DockWindow identifier.

### toolPanelGet_containerWindow ()

    GtkWindow*          toolPanelGet_containerWindow        (ToolPanel *toolPanel);

Return the GtkWindow that the given `toolPanel` is rendered in or NULL if the `toolPanel` is currently dettached.

`toolPanel` : | a ToolPanel.
Returns : | a GtkWindow object.

### toolPanelSet_dockable ()

    void                toolPanelSet_dockable               (ToolPanel *toolPanel,
                                                             gboolean value);

A ToolPanel can be moved between different DockWindow or not. This ability is controlled by the dockable flag. Change it with this method. If `toolPanel` is set dockable, then, it can be hidden or moved to another or a new DockWindow with the pop-up memu that is triggered by a small button in the header widget (see `toolPanelGet_headerWidget()`).

`toolPanel` : | a ToolPanel ;
`value` : | a boolean.

### toolPanelGet_container ()

    DockWindow*         toolPanelGet_container              (ToolPanel *toolPanel);

Return the DockWindow that the given `toolPanel` is attached to or NULL if the `toolPanel` is currently dettached.

`toolPanel` : | a ToolPanel.
Returns : | a DockWindow object.

### toolPanelGet_containerId ()

    const gchar*        toolPanelGet_containerId            (ToolPanel *toolPanel);

Return the identifying string of the DockWindow that the given `toolPanel` is attached to or NULL if the `toolPanel` is currently dettached.

`toolPanel` : | a ToolPanel.
Returns : | a string owned by V_Sim.

### toolPanelGet_headerWidget ()

    GtkWidget*          toolPanelGet_headerWidget           (ToolPanel *toolPanel);

The ToolPanel should be used in a page of a GtkNotebook. This routine is used to get the widget that should be used in the tab. This widget is a container with an icon and a label.

`toolPanel` : | a ToolPanel.
Returns : | a container widget that should be put in the tab of a GtkNotebook.

### toolPanelGet_id ()

    const gchar*        toolPanelGet_id                     (ToolPanel *toolPanel);

The ToolPanel can be identifyed by an id (a string without space, usually using ASCII characters only).

`toolPanel` : | a ToolPanel.
Returns : | a constant string identifying this ToolPanel.

### toolPanelGet_label ()

    const gchar*        toolPanelGet_label                  (ToolPanel *toolPanel);

The ToolPanel has two label, a short one, used in the tab of a GtkNotebook and one longer. This routine gets the longer.

`toolPanel` : | a ToolPanel.
Returns : | an UTF-8 internationalised name (property of V_Sim, should not be freed).

### toolPanelGet_visuData ()

    VisuData*           toolPanelGet_visuData               (ToolPanel *toolPanel);

The `toolPanel` is supposed to work on a VisuData, this routine can be used to get it.

`toolPanel` : | a ToolPanel.
Returns : | the currently focused VisuData (can be NULL if none).

### toolPanelGet_visible ()

    gboolean            toolPanelGet_visible                (ToolPanel *toolPanel);

This is used to retrieve if the `toolPanel` is currently realised and the visualised page of the GtkNotebook it is associated to.

`toolPanel` : | a ToolPanel.
Returns : | TRUE if the given `toolPanel` is potentialy visible to the user.

### toolPanelClassGet_allToolPanels ()

    GList*              toolPanelClassGet_allToolPanels     ();

This routine can be used to know all existing ToolPanel.

Returns : | a newly created list (use `g_list_free()` on it after use).

### toolPanelClassGet_allWindows ()

    GList*              toolPanelClassGet_allWindows        ();

This routine can be used to know all existing DockWindow.

Returns : | a newly created list (use `g_list_free()` on it after use).

### toolPanelClassGet_commandPanel ()

    DockWindow*         toolPanelClassGet_commandPanel      ();

There is always a DockWindow that is inside the command panel. This routine gets it.

Returns : | the DockWindow that is inside the command panel.

### toolPanelClassGet_container ()

    DockWindow*         toolPanelClassGet_container         (const gchar *id);

This routine associates a DockWindow identifier to the object pointer.

`id` : | a DockWindow identifier.
Returns : | the DockWindow that corresponds to this identifier. The dock window is built if not currently exist.

### toolPanelClassGet_toolPanelById ()

    ToolPanel*          toolPanelClassGet_toolPanelById     (const gchar *id);

This routine associates a ToolPanel identifier to the object pointer.

`id` : | a ToolPanel identifier.
Returns : | the ToolPanel that corresponds to this identifier or NULL if none exists.

### toolPanelClassGet_windowCharacteristics ()

    void                toolPanelClassGet_windowCharacteristics
                                                            (DockWindow *dock,
                                                             gchar **id,
                                                             gboolean *visibility,
                                                             gint *x,
                                                             gint *y,
                                                             gint *width,
                                                             gint *height);

A routine to know everything about a DockWindow.

`dock` : | a DockWindow object ;
`id` : | a location to store the identifier (owned by V_Sim) ;
`visibility` : | a location to store the status of the dock, hidden or not ;
`x` : | a location to store its x position on the root window ;
`y` : | a location to store its y position on the root window ;
`width` : | a location to store its width ;
`height` : | a location to store its height.

### toolPanelClassSet_headerVisibility ()

    void                toolPanelClassSet_headerVisibility  (gboolean status);

The header can be represented using the full image and label always or only the image when the tab is not on top.

`status` : | a boolean.

### toolPanelClassSet_visuData ()

    void                toolPanelClassSet_visuData          (VisuData *dataObj);

Set the currently focussed VisuData. It then can be retrieve using `toolPanelGet_visuData()`.

`dataObj` : | a VisuData object.

### toolPanelClassSet_windowPosition ()

    void                toolPanelClassSet_windowPosition    (const gchar *id,
                                                             guint x,
                                                             guint y);

Change the position of the given DockWindow. The position is possibly adapted to avoid been out of screen.

`id` : | a DockWindow identifier ;
`x` : | the requested x position ;
`y` : | the requested y position.

### toolPanelClassSet_windowSize ()

    void                toolPanelClassSet_windowSize        (const gchar *id,
                                                             guint width,
                                                             guint height);

Change the size of the given DockWindow. The size is possibly adapted to avoid been out of screen.

`id` : | a DockWindow identifier ;
`width` : | the requested width ;
`height` : | the requested height.

### toolPanelClassSet_windowVisibility ()

    void                toolPanelClassSet_windowVisibility  (const gchar *id,
                                                             gboolean visible);

Change the visibility of a DockWindow. If hidden, the dock is added to the list of hidden DockWindow that can be shown again using the pop-up menu on every visible DockWindow. The 'Main' dock window can not be hidden.

`id` : | a DockWindow identifier ;
`visible` : | a boolean.

### DockWindow

    typedef struct _DockWindow DockWindow;

Short name for the structure of containers of ToolPanel.

### dockWindowGet_container ()

    GtkWidget*          dockWindowGet_container             (DockWindow *dock);

A dock window is a small utility window with a list of ToolPanel. This window can be embedded in a container or have its own GtkWindow. This routine get the top-level container inside a given DockWindow. If you prefer to get the GtkWindow containing the DockWindow use `dockWindowGet_window()` instead.

`dock` : | a dock window descriptor.
Returns : | a top-level container (usually a GtkVBox).

### dockWindowGet_notebook ()

    GtkWidget*          dockWindowGet_notebook              (DockWindow *dock);

A dock window is a small utility window with a list of ToolPanel. All ToolPanel are contained in a GtkNotebook. This routine gets it.

`dock` : | a dock window descriptor.
Returns : | the GtkNotebook containing the ToolPanel of this DockWindow.

### dockWindowGet_window ()

    GtkWidget*          dockWindowGet_window                (DockWindow *dock);

A dock window is a small utility window with a list of ToolPanel. This window can be embedded in a container or have its own GtkWindow. This routine get the GtkWindow containing the DockWindow in the case the dock is stand-alone. If not NULL is returned.

`dock` : | a dock window descriptor.
Returns : | a top-level container (usually a GtkWindow) or NULL.