## BamfMatcher BamfMatcher — The base class for all matchers |

## Synopsis

    #define             BAMF_MATCHER_SIGNAL_VIEW_OPENED
    #define             BAMF_MATCHER_SIGNAL_VIEW_CLOSED
    #define             BAMF_MATCHER_SIGNAL_ACTIVE_APPLICATION_CHANGED
    #define             BAMF_MATCHER_SIGNAL_ACTIVE_WINDOW_CHANGED
    #define             BAMF_MATCHER_SIGNAL_STACKING_ORDER_CHANGED
    struct              BamfMatcher;
    struct              BamfMatcherClass;
    BamfMatcher *       bamf_matcher_get_default            (void);
    BamfApplication *   bamf_matcher_get_active_application (BamfMatcher *matcher);
    BamfWindow *        bamf_matcher_get_active_window      (BamfMatcher *matcher);
    BamfApplication *   bamf_matcher_get_application_for_xid
                                                            (BamfMatcher *matcher,
                                                             guint32 xid);
    BamfApplication *   bamf_matcher_get_application_for_window
                                                            (BamfMatcher *matcher,
                                                             BamfWindow *window);
    gboolean            bamf_matcher_application_is_running (BamfMatcher *matcher,
                                                             const gchar *desktop_file);
    GList *             bamf_matcher_get_applications       (BamfMatcher *matcher);
    void                bamf_matcher_register_favorites     (BamfMatcher *matcher,
                                                             const gchar **favorites);
    GList *             bamf_matcher_get_running_applications
                                                            (BamfMatcher *matcher);
    GList *             bamf_matcher_get_tabs               (BamfMatcher *matcher);
    GArray *            bamf_matcher_get_xids_for_application
                                                            (BamfMatcher *matcher,
                                                             const gchar *desktop_file);
    GList *             bamf_matcher_get_windows            (BamfMatcher *matcher);
    GList *             bamf_matcher_get_window_stack_for_monitor
                                                            (BamfMatcher *matcher,
                                                             gint monitor);
    BamfApplication *   bamf_matcher_get_application_for_desktop_file
                                                            (BamfMatcher *matcher,
                                                             const gchar *desktop_file_path,
                                                             gboolean create_if_not_found);

## Object Hierarchy

      GObject
       +----BamfMatcher

## Signals

      "active-application-changed"
      "active-window-changed"
      "stacking-order-changed"
      "view-closed"
      "view-opened"

## Description

BamfMatcher is the base class that all matchers need to derive from.

## Details

### BAMF_MATCHER_SIGNAL_VIEW_OPENED

    #define BAMF_MATCHER_SIGNAL_VIEW_OPENED                "view-opened"

### BAMF_MATCHER_SIGNAL_VIEW_CLOSED

    #define BAMF_MATCHER_SIGNAL_VIEW_CLOSED                "view-closed"

### BAMF_MATCHER_SIGNAL_ACTIVE_APPLICATION_CHANGED

    #define BAMF_MATCHER_SIGNAL_ACTIVE_APPLICATION_CHANGED "active-application-changed"

### BAMF_MATCHER_SIGNAL_ACTIVE_WINDOW_CHANGED

    #define BAMF_MATCHER_SIGNAL_ACTIVE_WINDOW_CHANGED      "active-window-changed"

### BAMF_MATCHER_SIGNAL_STACKING_ORDER_CHANGED

    #define BAMF_MATCHER_SIGNAL_STACKING_ORDER_CHANGED     "stacking-order-changed"

### struct BamfMatcher

    struct BamfMatcher;

### struct BamfMatcherClass

    struct BamfMatcherClass {
      GObjectClass parent_class;
    };

### bamf_matcher_get_default ()

    BamfMatcher *       bamf_matcher_get_default            (void);

Returns the default matcher. This matcher is owned by bamf and shared between other callers.

Returns : | A new BamfMatcher. [transfer full]

### bamf_matcher_get_active_application ()

    BamfApplication *   bamf_matcher_get_active_application (BamfMatcher *matcher);

Used to fetch the active BamfApplication.

`matcher` : | a BamfMatcher
Returns : | The active BamfApplication. [transfer none]

### bamf_matcher_get_active_window ()

    BamfWindow *        bamf_matcher_get_active_window      (BamfMatcher *matcher);

Used to fetch the active BamfWindow.

`matcher` : | a BamfMatcher
Returns : | The active BamfWindow. [transfer none]

### bamf_matcher_get_application_for_xid ()

    BamfApplication *   bamf_matcher_get_application_for_xid
                                                            (BamfMatcher *matcher,
                                                             guint32 xid);

Used to fetch the BamfApplication containing the passed xid.

`matcher` : | a BamfMatcher
`xid` : | The XID to search for
Returns : | The BamfApplication representing the xid passed, or NULL if none exists. [transfer none]

### bamf_matcher_get_application_for_window ()

    BamfApplication *   bamf_matcher_get_application_for_window
                                                            (BamfMatcher *matcher,
                                                             BamfWindow *window);

Used to fetch the BamfApplication containing the passed window.

`matcher` : | a BamfMatcher
`window` : | The window to look for
Returns : | The BamfApplication representing the xid passed, or NULL if none exists. [transfer none]

### bamf_matcher_application_is_running ()

    gboolean            bamf_matcher_application_is_running (BamfMatcher *matcher,
                                                             const gchar *desktop_file);

### bamf_matcher_get_applications ()

    GList *             bamf_matcher_get_applications       (BamfMatcher *matcher);

Used to fetch all BamfApplication's running or not. Application authors who wish to only see running applications should use bamf_matcher_get_running_applications instead. The reason this method is needed is bamf will occasionally track applications which are not currently running for nefarious purposes.

`matcher` : | a BamfMatcher
Returns : | A list of BamfApplication's. [element-type Bamf.Application][transfer container]

### bamf_matcher_register_favorites ()

    void                bamf_matcher_register_favorites     (BamfMatcher *matcher,
                                                             const gchar **favorites);

Used to effect how bamf performs matching. Desktop files passed to this method will be prefered by bamf to system desktop files.

`matcher` : | a BamfMatcher
`favorites` : | an array of strings, each containing an absolute path to a .desktop file. [array]

### bamf_matcher_get_running_applications ()

    GList *             bamf_matcher_get_running_applications
                                                            (BamfMatcher *matcher);

Used to fetch all BamfApplication's which are running.

`matcher` : | a BamfMatcher
Returns : | A list of BamfApplication's. [element-type Bamf.Application][transfer container]

### bamf_matcher_get_tabs ()

    GList *             bamf_matcher_get_tabs               (BamfMatcher *matcher);

Used to fetch all BamfView's representing tabs. Currently unused.

`matcher` : | a BamfMatcher
Returns : | A list of BamfTab's. [element-type Bamf.Tab][transfer container]

### bamf_matcher_get_xids_for_application ()

    GArray *            bamf_matcher_get_xids_for_application
                                                            (BamfMatcher *matcher,
                                                             const gchar *desktop_file);

Used to fetch all xid's associated with an application. Useful for performing window

`matcher` : | a BamfMatcher
Returns : | A list of xids. [element-type guint32][transfer full]

### bamf_matcher_get_windows ()

    GList *             bamf_matcher_get_windows            (BamfMatcher *matcher);

Used to fetch all windows that BAMF knows about.

`matcher` : | a BamfMatcher
Returns : | A list of BamfWindow's. [element-type Bamf.Window][transfer container]

### bamf_matcher_get_window_stack_for_monitor ()

    GList *             bamf_matcher_get_window_stack_for_monitor
                                                            (BamfMatcher *matcher,
                                                             gint monitor);

Used to fetch all windows that BAMF knows about in the requested screen, in stacking bottom-to-top order. If the `monitor` is set to a negative value, then it fetches all the available windows in all monitors.

`matcher` : | a BamfMatcher
`monitor` : | the monitor you want the stack from, negative value to get all
Returns : | A list of BamfWindow's. [element-type Bamf.Window][transfer container]

### bamf_matcher_get_application_for_desktop_file ()

    BamfApplication *   bamf_matcher_get_application_for_desktop_file
                                                            (BamfMatcher *matcher,
                                                             const gchar *desktop_file_path,
                                                             gboolean create_if_not_found);

`matcher` : | a BamfMatcher
`desktop_file_path` : | Path to the desktop file
`create_if_not_found` : | Create a BamfApplication if one isn't found
Returns : | A BamfApplication for given desktop file. [transfer none]

## Signal Details

### The `"active-application-changed"` signal

    void                user_function                      (BamfMatcher     *bamfmatcher,
                                                            BamfApplication *arg1,
                                                            BamfApplication *arg2,
                                                            gpointer         user_data)

`bamfmatcher` : | the object which received the signal.
`user_data` : | user data set when the signal handler was connected.

### The `"active-window-changed"` signal

    void                user_function                      (BamfMatcher *bamfmatcher,
                                                            BamfWindow  *arg1,
                                                            BamfWindow  *arg2,
                                                            gpointer     user_data)

`bamfmatcher` : | the object which received the signal.
`user_data` : | user data set when the signal handler was connected.

### The `"stacking-order-changed"` signal

    void                user_function                      (BamfMatcher *bamfmatcher,
                                                            gpointer     user_data)

`bamfmatcher` : | the object which received the signal.
`user_data` : | user data set when the signal handler was connected.

### The `"view-closed"` signal

    void                user_function                      (BamfMatcher *bamfmatcher,
                                                            BamfView    *arg1,
                                                            gpointer     user_data)

`bamfmatcher` : | the object which received the signal.
`user_data` : | user data set when the signal handler was connected.

### The `"view-opened"` signal

    void                user_function                      (BamfMatcher *bamfmatcher,
                                                            BamfView    *arg1,
                                                            gpointer     user_data)

`bamfmatcher` : | the object which received the signal.
`user_data` : | user data set when the signal handler was connected.