MateApp

## MateApp MateApp — The main application widget. |

## Synopsis

    #include <libmateui/libmateui.h>

    #define             MATE_APP_MENUBAR_NAME
    #define             MATE_APP_TOOLBAR_NAME
    struct              MateApp;
    GtkWidget *         mate_app_new                       (const gchar *appname,
                                                             const gchar *title);
    void                mate_app_construct                 (MateApp *app,
                                                             const gchar *appname,
                                                             const gchar *title);
    void                mate_app_set_menus                 (MateApp *app,
                                                             GtkMenuBar *menubar);
    void                mate_app_set_toolbar               (MateApp *app,
                                                             GtkToolbar *toolbar);
    void                mate_app_set_statusbar             (MateApp *app,
                                                             GtkWidget *statusbar);
    void                mate_app_set_statusbar_custom      (MateApp *app,
                                                             GtkWidget *container,
                                                             GtkWidget *statusbar);
    void                mate_app_set_contents              (MateApp *app,
                                                             GtkWidget *contents);
    void                mate_app_add_toolbar               (MateApp *app,
                                                             GtkToolbar *toolbar,
                                                             const gchar *name,
                                                             MateComponentDockItemBehavior behavior,
                                                             MateComponentDockPlacement placement,
                                                             gint band_num,
                                                             gint band_position,
                                                             gint offset);
    GtkWidget *         mate_app_add_docked                (MateApp *app,
                                                             GtkWidget *widget,
                                                             const gchar *name,
                                                             MateComponentDockItemBehavior behavior,
                                                             MateComponentDockPlacement placement,
                                                             gint band_num,
                                                             gint band_position,
                                                             gint offset);
    void                mate_app_add_dock_item             (MateApp *app,
                                                             MateComponentDockItem *item,
                                                             MateComponentDockPlacement placement,
                                                             gint band_num,
                                                             gint band_position,
                                                             gint offset);
    void                mate_app_enable_layout_config      (MateApp *app,
                                                             gboolean enable);
    MateComponentDock *        mate_app_get_dock                  (MateApp *app);
    MateComponentDockItem *    mate_app_get_dock_item_by_name     (MateApp *app,
                                                             const gchar *name);

## Object Hierarchy

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

## Implemented Interfaces

MateApp implements AtkImplementorIface and GtkBuildable.

## Properties

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

## Description

The `MateApp` widget and associated functions provides the easiest way to create an almost complete MATE application in libmateui. 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 `mate_app_set_contents()` and start the main loop (with `gtk_main()`).

## Details

### MATE_APP_MENUBAR_NAME

    #define MATE_APP_MENUBAR_NAME "Menubar"

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

### MATE_APP_TOOLBAR_NAME

    #define MATE_APP_TOOLBAR_NAME "Toolbar"

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

### struct MateApp

    struct MateApp;

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

### mate_app_new ()

    GtkWidget *         mate_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 MateApp object.

### mate_app_construct ()

    void                mate_app_construct                 (MateApp *app,
                                                             const gchar *appname,
                                                             const gchar *title);

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

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

### mate_app_set_menus ()

    void                mate_app_set_menus                 (MateApp *app,
                                                             GtkMenuBar *menubar);

Sets the menu bar of the application window.

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

### mate_app_set_toolbar ()

    void                mate_app_set_toolbar               (MateApp *app,
                                                             GtkToolbar *toolbar);

Sets the main toolbar of the application window.

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

### mate_app_set_statusbar ()

    void                mate_app_set_statusbar             (MateApp *app,
                                                             GtkWidget *statusbar);

Sets the status bar of the application window.

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

### mate_app_set_statusbar_custom ()

    void                mate_app_set_statusbar_custom      (MateApp *app,
                                                             GtkWidget *container,
                                                             GtkWidget *statusbar);

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

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

### mate_app_set_contents ()

    void                mate_app_set_contents              (MateApp *app,
                                                             GtkWidget *contents);

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

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

### mate_app_add_toolbar ()

    void                mate_app_add_toolbar               (MateApp *app,
                                                             GtkToolbar *toolbar,
                                                             const gchar *name,
                                                             MateComponentDockItemBehavior behavior,
                                                             MateComponentDockPlacement placement,
                                                             gint band_num,
                                                             gint band_position,
                                                             gint offset);

Create a new MateComponentDockItem 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 MateApp 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.

### mate_app_add_docked ()

    GtkWidget *         mate_app_add_docked                (MateApp *app,
                                                             GtkWidget *widget,
                                                             const gchar *name,
                                                             MateComponentDockItemBehavior behavior,
                                                             MateComponentDockPlacement 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 MateApp widget.
`widget` : | Widget to be added to the MateApp.
`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.

### mate_app_add_dock_item ()

    void                mate_app_add_dock_item             (MateApp *app,
                                                             MateComponentDockItem *item,
                                                             MateComponentDockPlacement 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 MateApp 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.

### mate_app_enable_layout_config ()

    void                mate_app_enable_layout_config      (MateApp *app,
                                                             gboolean enable);

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

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

### mate_app_get_dock ()

    MateComponentDock *        mate_app_get_dock                  (MateApp *app);

Retrieves the MateComponentDock widget contained in `app`.

`app` : | A MateApp widget
Returns : | The relevant MateComponentDock widget.

### mate_app_get_dock_item_by_name ()

    MateComponentDockItem *    mate_app_get_dock_item_by_name     (MateApp *app,
                                                             const gchar *name);

Retrieve the dock item whose name matches `name`.

`app` : | A MateApp 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