## GnomeApp GnomeApp — The main application widget. |

## Synopsis

    #include <libgnomeui/libgnomeui.h>

    #define     GNOME_APP_MENUBAR_NAME
    #define     GNOME_APP_TOOLBAR_NAME
                GnomeApp;
    GtkWidget*  gnome_app_new                   (const gchar *appname,
                                                 const gchar *title);
    void        gnome_app_construct             (GnomeApp *app,
                                                 const gchar *appname,
                                                 const gchar *title);
    void        gnome_app_set_menus             (GnomeApp *app,
                                                 GtkMenuBar *menubar);
    void        gnome_app_set_toolbar           (GnomeApp *app,
                                                 GtkToolbar *toolbar);
    void        gnome_app_set_statusbar         (GnomeApp *app,
                                                 GtkWidget *statusbar);
    void        gnome_app_set_statusbar_custom  (GnomeApp *app,
                                                 GtkWidget *container,
                                                 GtkWidget *statusbar);
    void        gnome_app_set_contents          (GnomeApp *app,
                                                 GtkWidget *contents);
    void        gnome_app_add_toolbar           (GnomeApp *app,
                                                 GtkToolbar *toolbar,
                                                 const gchar *name,
                                                 BonoboDockItemBehavior behavior,
                                                 BonoboDockPlacement placement,
                                                 gint band_num,
                                                 gint band_position,
                                                 gint offset);
    GtkWidget*  gnome_app_add_docked            (GnomeApp *app,
                                                 GtkWidget *widget,
                                                 const gchar *name,
                                                 BonoboDockItemBehavior behavior,
                                                 BonoboDockPlacement placement,
                                                 gint band_num,
                                                 gint band_position,
                                                 gint offset);
    void        gnome_app_add_dock_item         (GnomeApp *app,
                                                 BonoboDockItem *item,
                                                 BonoboDockPlacement placement,
                                                 gint band_num,
                                                 gint band_position,
                                                 gint offset);
    void        gnome_app_enable_layout_config  (GnomeApp *app,
                                                 gboolean enable);
    BonoboDock* gnome_app_get_dock              (GnomeApp *app);
    BonoboDockItem* gnome_app_get_dock_item_by_name
                                                (GnomeApp *app,
                                                 const gchar *name);

## Object Hierarchy

      GObject
       +----GInitiallyUnowned
             +----GtkObject
                   +----GtkWidget
                         +----GtkContainer
                               +----GtkBin
                                     +----GtkWindow
                                           +----GnomeApp

## Implemented Interfaces

GnomeApp implements AtkImplementorIface.

## Properties

      "app-id"               gchararray            : Read / Write / Construct

## Description

The `GnomeApp` widget and associated functions provides the easiest way to create an almost complete GNOME application in libgnomeui. Simple create an instance of the widget, append any menus, toolbar(s) and a status bar, as required (this will probably be done with some functions from the following pages). Then fill in the main contents with a call to `gnome_app_set_contents()` and start the main loop (with `gtk_main()`).

## Details

### GNOME_APP_MENUBAR_NAME

    #define GNOME_APP_MENUBAR_NAME "Menubar"

The name of the menubar as it is passed to libbonobo.

### GNOME_APP_TOOLBAR_NAME

    #define GNOME_APP_TOOLBAR_NAME "Toolbar"

The name of the default toolbar that is added to the application widget by default.

### GnomeApp

    typedef struct _GnomeApp GnomeApp;

A widget representing an entire GNOME application, including the main window, menus, toolbar(s) and status bar.

### gnome_app_new ()

    GtkWidget*  gnome_app_new                   (const gchar *appname,
                                                 const gchar *title);

Create a new (empty) application window. You must specify the `appname` (used internally as an identifier). The `title` param can be left as NULL, in which case the window's title will not be set.

`appname` : | Name of program, used in file names and paths.
`title` : | Window title for application.
Returns : | Pointer to new GnomeApp object.

### gnome_app_construct ()

    void        gnome_app_construct             (GnomeApp *app,
                                                 const gchar *appname,
                                                 const gchar *title);

Constructor for language bindings; you don't normally need this.

`app` : | A newly created GnomeApp object.
`appname` : | Name of program, using in file names and paths.
`title` : | Window title for application.

### gnome_app_set_menus ()

    void        gnome_app_set_menus             (GnomeApp *app,
                                                 GtkMenuBar *menubar);

Sets the menu bar of the application window.

`app` : | A GnomeApp instance.
`menubar` : | Menu bar widget for main application window.

### gnome_app_set_toolbar ()

    void        gnome_app_set_toolbar           (GnomeApp *app,
                                                 GtkToolbar *toolbar);

Sets the main toolbar of the application window.

`app` : | A GnomeApp instance.
`toolbar` : | Toolbar widget for main app window.

### gnome_app_set_statusbar ()

    void        gnome_app_set_statusbar         (GnomeApp *app,
                                                 GtkWidget *statusbar);

Sets the status bar of the application window.

`app` : | A GnomeApp instance
`statusbar` : | Statusbar widget for main app window

### gnome_app_set_statusbar_custom ()

    void        gnome_app_set_statusbar_custom  (GnomeApp *app,
                                                 GtkWidget *container,
                                                 GtkWidget *statusbar);

Sets the status bar of the application window, but use `container` as its container.

`app` : | A GnomeApp instance
`container` : | container widget containing the statusbar
`statusbar` : | Statusbar widget for main app window

### gnome_app_set_contents ()

    void        gnome_app_set_contents          (GnomeApp *app,
                                                 GtkWidget *contents);

Sets the content area of the main window of `app`.

`app` : | A GnomeApp instance.
`contents` : | Widget to be application content area.

### gnome_app_add_toolbar ()

    void        gnome_app_add_toolbar           (GnomeApp *app,
                                                 GtkToolbar *toolbar,
                                                 const gchar *name,
                                                 BonoboDockItemBehavior behavior,
                                                 BonoboDockPlacement placement,
                                                 gint band_num,
                                                 gint band_position,
                                                 gint offset);

Create a new BonoboDockItem widget containing `toolbar`, and add it to `app`'s dock with the specified layout information. Notice that, if automatic layout configuration is enabled, the layout is overridden by the saved configuration, if any.

`app` : | A GnomeApp widget
`toolbar` : | Toolbar to be added to `app`'s dock
`name` : | Name for the dock item that will contain `toolbar`
`behavior` : | Behavior for the new dock item
`placement` : | Placement for the new dock item
`band_num` : | Number of the band where the dock item should be placed
`band_position` : | Position of the new dock item in band `band_num`
`offset` : | Offset from the previous dock item in the band; if there is no previous item, offset from the beginning of the band.

### gnome_app_add_docked ()

    GtkWidget*  gnome_app_add_docked            (GnomeApp *app,
                                                 GtkWidget *widget,
                                                 const gchar *name,
                                                 BonoboDockItemBehavior behavior,
                                                 BonoboDockPlacement placement,
                                                 gint band_num,
                                                 gint band_position,
                                                 gint offset);

Add `widget` as a dock item according to the specified layout information. Notice that, if automatic layout configuration is enabled, the layout is overridden by the saved configuration, if any.

`app` : | A GnomeApp widget.
`widget` : | Widget to be added to the GnomeApp.
`name` : | Name for the new dock item.
`behavior` : | Behavior for the new dock item.
`placement` : | Placement for the new dock item.
`band_num` : | Number of the band where the dock item should be placed.
`band_position` : | Position of the new dock item in band `band_num`.
`offset` : | Offset from the previous dock item in the band; if there is no previous item, offset from the beginning of the band.
Returns : | The dock item used to contain the widget.

### gnome_app_add_dock_item ()

    void        gnome_app_add_dock_item         (GnomeApp *app,
                                                 BonoboDockItem *item,
                                                 BonoboDockPlacement placement,
                                                 gint band_num,
                                                 gint band_position,
                                                 gint offset);

Add `item` according to the specified layout information. Notice that, if automatic layout configuration is enabled, the layout is overridden by the saved configuration, if any.

`app` : | A GnomeApp widget.
`item` : | Dock item to be added to `app`'s dock.
`placement` : | Placement for the dock item.
`band_num` : | Number of the band where the dock item should be placed.
`band_position` : | Position of the dock item in band `band_num`.
`offset` : | Offset from the previous dock item in the band; if there is no previous item, offset from the beginning of the band.

### gnome_app_enable_layout_config ()

    void        gnome_app_enable_layout_config  (GnomeApp *app,
                                                 gboolean enable);

Specify whether `app` should automatically save the dock's layout configuration via gnome-config whenever it changes or not.

`app` : | A GnomeApp widget.
`enable` : | Boolean specifying whether automatic configuration saving is enabled.

### gnome_app_get_dock ()

    BonoboDock* gnome_app_get_dock              (GnomeApp *app);

Retrieves the BonoboDock widget contained in `app`.

`app` : | A GnomeApp widget
Returns : | The relevant BonoboDock widget.

### gnome_app_get_dock_item_by_name ()

    BonoboDockItem* gnome_app_get_dock_item_by_name
                                                (GnomeApp *app,
                                                 const gchar *name);

Retrieve the dock item whose name matches `name`.

`app` : | A GnomeApp widget.
`name` : | Name of the dock item to retrieve.
Returns : | The retrieved dock item.

## Properties

### The "`app-id`" property

      "app-id"               gchararray            : Read / Write / Construct

The application ID string.

Default value: NULL