## GnomeApp

GnomeApp — The main application widget.

## Synopsis

    #include <libgnomeui/libgnomeui.h>

    #define             GNOME_APP_MENUBAR_NAME
    #define             GNOME_APP_TOOLBAR_NAME
    struct              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 and GtkBuildable.

## Properties

      "app-id"                   gchar*                : 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.

### struct GnomeApp

    struct 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.

## Property Details

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

      "app-id"                   gchar*                : Read / Write / Construct

The application ID string.

Default value: NULL