Gnome User Interface Library Reference Manual
<<< Previous Page | Home | Up | Next Page >>>

# GnomeApp

## Name

GnomeApp -- The toplevel GNOME container

## Synopsis

    #include <gnome.h>

    struct      GnomeApp;
    GtkWidget*  gnome_app_new                   (gchar *appname,
                                                 char *title);
    void        gnome_app_construct             (GnomeApp *app,
                                                 gchar *appname,
                                                 char *title);
    #define     GNOME_APP_MENUBAR_NAME
    #define     GNOME_APP_TOOLBAR_NAME
    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_contents          (GnomeApp *app,
                                                 GtkWidget *contents);
    void        gnome_app_add_toolbar           (GnomeApp *app,
                                                 GtkToolbar *toolbar,
                                                 const gchar *name,
                                                 GnomeDockItemBehavior behavior,
                                                 GnomeDockPlacement placement,
                                                 gint band_num,
                                                 gint band_position,
                                                 gint offset);
    void        gnome_app_add_docked            (GnomeApp *app,
                                                 GtkWidget *widget,
                                                 const gchar *name,
                                                 GnomeDockItemBehavior behavior,
                                                 GnomeDockPlacement placement,
                                                 gint band_num,
                                                 gint band_position,
                                                 gint offset);
    void        gnome_app_add_dock_item         (GnomeApp *app,
                                                 GnomeDockItem *item,
                                                 GnomeDockPlacement placement,
                                                 gint band_num,
                                                 gint band_position,
                                                 gint offset);
    void        gnome_app_enable_layout_config  (GnomeApp *app,
                                                 gboolean enable);
    GnomeDock*  gnome_app_get_dock              (GnomeApp *app);
    GnomeDockItem* gnome_app_get_dock_item_by_name
                                                (GnomeApp *app,
                                                 const gchar *name);

## Object Hierarchy

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

## Description

Toplevel GNOME applications would normally use one GnomeApp widget as their toplevel window. You can create as many GnomeApp widgets as you want, for example, some people use one GnomeApp per document their application loads.

Once you have created one instance of this widget, you would add your main application view information to this window by using gnome_app_set_contents() routine.

The GnomeApp has support for including a menubar, one or more toolbars and a statusbar for your application. It also takes care of intalling the accelerators for you when used in conjuction with the gnome-app-helper routines. The toolbars are inserted into GnomeDock widgets.

The `gnome-app-helper` module provides various helper routines to simplify the configuration of your menus and toolbars, but you can create those yourself and use the gnome_app_set_menus(), gnome_app_add_toolbar(), gnome_app_set_toolbar(), gnome_app_add_dock_item(), and gnome_app_add_docked().

## Details

### struct GnomeApp

    struct GnomeApp;

### gnome_app_new ()

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

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

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

### gnome_app_construct ()

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

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

`app` : | Pointer to newly-created GNOME app object.
`appname` : | Name of program, using in file names and paths.
`title` : | Window title for application.

### GNOME_APP_MENUBAR_NAME

    #define GNOME_APP_MENUBAR_NAME "Menubar"

### GNOME_APP_TOOLBAR_NAME

    #define GNOME_APP_TOOLBAR_NAME "Toolbar"

### gnome_app_set_menus ()

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

Sets the menu bar of the application window.

`app` : | Pointer to GNOME app object.
`menubar` : | Menu bar widget for main app window.

### gnome_app_set_toolbar ()

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

Sets the main toolbar of the application window.

`app` : | Pointer to GNOME app object.
`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` : | Pointer to GNOME app object
`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 GNOME app's main window.

`app` : | Pointer to GNOME app object.
`contents` : | Widget to be application content area.

### gnome_app_add_toolbar ()

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

Create a new &GnomeDockItem 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 ()

    void        gnome_app_add_docked            (GnomeApp *app,
                                                 GtkWidget *widget,
                                                 const gchar *name,
                                                 GnomeDockItemBehavior behavior,
                                                 GnomeDockPlacement 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.

### gnome_app_add_dock_item ()

    void        gnome_app_add_dock_item         (GnomeApp *app,
                                                 GnomeDockItem *item,
                                                 GnomeDockPlacement 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 ()

    GnomeDock*  gnome_app_get_dock              (GnomeApp *app);

Retrieves the &GnomeDock widget contained in the &GnomeApp.

`app` : | A &GnomeApp widget
Returns : | The &GnomeDock widget.

### gnome_app_get_dock_item_by_name ()

    GnomeDockItem* 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.

<<< Previous Page | Home | Up | Next Page >>>
GnomeAnimator | GnomeAppBar