Mutter Reference Manual: Utility functions

## Utility functions Utility functions — Miscellaneous utility functions |

## Synopsis

    gboolean            meta_is_verbose                     (void);
    void                meta_set_verbose                    (gboolean setting);
    gboolean            meta_is_debugging                   (void);
    void                meta_set_debugging                  (gboolean setting);
    gboolean            meta_is_syncing                     (void);
    void                meta_set_syncing                    (gboolean setting);
    void                meta_set_replace_current_wm         (gboolean setting);
    void                meta_debug_spew_real                (const char *format,
                                                             ...);
    void                meta_verbose_real                   (const char *format,
                                                             ...);
    void                meta_bug                            (const char *format,
                                                             ...);
    void                meta_warning                        (const char *format,
                                                             ...);
    void                meta_fatal                          (const char *format,
                                                             ...);
    enum                MetaDebugTopic;
    void                meta_topic_real                     (MetaDebugTopic topic,
                                                             const char *format,
                                                             ...);
    void                meta_add_verbose_topic              (MetaDebugTopic topic);
    void                meta_remove_verbose_topic           (MetaDebugTopic topic);
    void                meta_push_no_msg_prefix             (void);
    void                meta_pop_no_msg_prefix              (void);
    gint                meta_unsigned_long_equal            (gconstpointer v1,
                                                             gconstpointer v2);
    guint               meta_unsigned_long_hash             (gconstpointer v);
    const char *        meta_frame_type_to_string           (MetaFrameType type);
    const char *        meta_gravity_to_string              (int gravity);
    #define             _                                   (x)
    #define             N_                                  (x)
    char *              meta_g_utf8_strndup                 (const gchar *src,
                                                             gsize n);
    void                meta_free_gslist_and_elements       (GSList *list_to_deep_free);
    GPid                meta_show_dialog                    (const char *type,
                                                             const char *message,
                                                             const char *timeout,
                                                             const char *display,
                                                             const char *ok_text,
                                                             const char *cancel_text,
                                                             const char *icon_name,
                                                             const int transient_for,
                                                             GSList *columns,
                                                             GSList *entries);
    #define             meta_debug_spew
    #define             meta_verbose
    #define             meta_topic
    enum                MetaLaterType;
    guint               meta_later_add                      (MetaLaterType when,
                                                             GSourceFunc func,
                                                             gpointer data,
                                                             GDestroyNotify notify);
    void                meta_later_remove                   (guint later_id);

## Description

## Details

### meta_is_verbose ()

    gboolean            meta_is_verbose                     (void);

### meta_set_verbose ()

    void                meta_set_verbose                    (gboolean setting);

### meta_is_debugging ()

    gboolean            meta_is_debugging                   (void);

### meta_set_debugging ()

    void                meta_set_debugging                  (gboolean setting);

### meta_is_syncing ()

    gboolean            meta_is_syncing                     (void);

Returns whether X synchronisation is currently enabled.

FIXME: This is *only* called by `meta_display_open()`, but by that time we have already turned syncing on or off on startup, and we don't have any way to do so while Mutter is running, so it's rather pointless.

Returns : | `TRUE` if we must wait for events whenever we send X requests; `FALSE` otherwise.

### meta_set_syncing ()

    void                meta_set_syncing                    (gboolean setting);

A handy way to turn on synchronisation on or off for every display.

`setting` : | whether to turn syncing on or off

### meta_set_replace_current_wm ()

    void                meta_set_replace_current_wm         (gboolean setting);

### meta_debug_spew_real ()

    void                meta_debug_spew_real                (const char *format,
                                                             ...);

### meta_verbose_real ()

    void                meta_verbose_real                   (const char *format,
                                                             ...);

### meta_bug ()

    void                meta_bug                            (const char *format,
                                                             ...);

### meta_warning ()

    void                meta_warning                        (const char *format,
                                                             ...);

### meta_fatal ()

    void                meta_fatal                          (const char *format,
                                                             ...);

### enum MetaDebugTopic

    typedef enum {
      META_DEBUG_VERBOSE         = -1,
      META_DEBUG_FOCUS           = 1 << 0,
      META_DEBUG_WORKAREA        = 1 << 1,
      META_DEBUG_STACK           = 1 << 2,
      META_DEBUG_THEMES          = 1 << 3,
      META_DEBUG_SM              = 1 << 4,
      META_DEBUG_EVENTS          = 1 << 5,
      META_DEBUG_WINDOW_STATE    = 1 << 6,
      META_DEBUG_WINDOW_OPS      = 1 << 7,
      META_DEBUG_GEOMETRY        = 1 << 8,
      META_DEBUG_PLACEMENT       = 1 << 9,
      META_DEBUG_PING            = 1 << 10,
      META_DEBUG_XINERAMA        = 1 << 11,
      META_DEBUG_KEYBINDINGS     = 1 << 12,
      META_DEBUG_SYNC            = 1 << 13,
      META_DEBUG_ERRORS          = 1 << 14,
      META_DEBUG_STARTUP         = 1 << 15,
      META_DEBUG_PREFS           = 1 << 16,
      META_DEBUG_GROUPS          = 1 << 17,
      META_DEBUG_RESIZING        = 1 << 18,
      META_DEBUG_SHAPES          = 1 << 19,
      META_DEBUG_COMPOSITOR      = 1 << 20,
      META_DEBUG_EDGE_RESISTANCE = 1 << 21,
      META_DEBUG_DBUS            = 1 << 22
    } MetaDebugTopic;

`META_DEBUG_VERBOSE` | verbose logging
`META_DEBUG_FOCUS` | focus
`META_DEBUG_WORKAREA` | workarea
`META_DEBUG_STACK` | stack
`META_DEBUG_THEMES` | themes
`META_DEBUG_SM` | session management
`META_DEBUG_EVENTS` | events
`META_DEBUG_WINDOW_STATE` | window state
`META_DEBUG_WINDOW_OPS` | window operations
`META_DEBUG_GEOMETRY` | geometry
`META_DEBUG_PLACEMENT` | window placement
`META_DEBUG_PING` | ping
`META_DEBUG_XINERAMA` | Xinerama
`META_DEBUG_KEYBINDINGS` | keybindings
`META_DEBUG_SYNC` | sync
`META_DEBUG_ERRORS` | errors
`META_DEBUG_STARTUP` | startup
`META_DEBUG_PREFS` | preferences
`META_DEBUG_GROUPS` | groups
`META_DEBUG_RESIZING` | resizing
`META_DEBUG_SHAPES` | shapes
`META_DEBUG_COMPOSITOR` | compositor
`META_DEBUG_EDGE_RESISTANCE` | edge resistance
`META_DEBUG_DBUS` |

### meta_topic_real ()

    void                meta_topic_real                     (MetaDebugTopic topic,
                                                             const char *format,
                                                             ...);

### meta_add_verbose_topic ()

    void                meta_add_verbose_topic              (MetaDebugTopic topic);

Ensure log messages for the given topic `topic` will be printed.

`topic` : | Topic for which logging will be started

### meta_remove_verbose_topic ()

    void                meta_remove_verbose_topic           (MetaDebugTopic topic);

Stop printing log messages for the given topic `topic`. Note that this method does not stack with `meta_add_verbose_topic()`; i.e. if two calls to `meta_add_verbose_topic()` for the same topic are made, one call to `meta_remove_verbose_topic()` will remove it.

`topic` : | Topic for which logging will be stopped

### meta_push_no_msg_prefix ()

    void                meta_push_no_msg_prefix             (void);

### meta_pop_no_msg_prefix ()

    void                meta_pop_no_msg_prefix              (void);

### meta_unsigned_long_equal ()

    gint                meta_unsigned_long_equal            (gconstpointer v1,
                                                             gconstpointer v2);

### meta_unsigned_long_hash ()

    guint               meta_unsigned_long_hash             (gconstpointer v);

### meta_frame_type_to_string ()

    const char *        meta_frame_type_to_string           (MetaFrameType type);

Converts a frame type enum value to the name string that would appear in the theme definition file.

`type` : | a MetaFrameType
Returns : | the string value

### meta_gravity_to_string ()

    const char *        meta_gravity_to_string              (int gravity);

### _()

    #define _(x) dgettext (GETTEXT_PACKAGE, x)

### N_()

    #define N_(x) x

### meta_g_utf8_strndup ()

    char *              meta_g_utf8_strndup                 (const gchar *src,
                                                             gsize n);

### meta_free_gslist_and_elements ()

    void                meta_free_gslist_and_elements       (GSList *list_to_deep_free);

`list_to_deep_free` : | list to deep free

### meta_show_dialog ()

    GPid                meta_show_dialog                    (const char *type,
                                                             const char *message,
                                                             const char *timeout,
                                                             const char *display,
                                                             const char *ok_text,
                                                             const char *cancel_text,
                                                             const char *icon_name,
                                                             const int transient_for,
                                                             GSList *columns,
                                                             GSList *entries);

`type` : | type of dialog
`message` : | message
`timeout` : | timeout
`display` : | display
`ok_text` : | text for Ok button
`cancel_text` : | text for Cancel button
`icon_name` : | icon name
`transient_for` : | window XID of parent
`columns` : | columns
`entries` : | entries

### meta_debug_spew

    #define meta_debug_spew meta_debug_spew_real

### meta_verbose

    #define meta_verbose    meta_verbose_real

### meta_topic

    #define meta_topic      meta_topic_real

### enum MetaLaterType

    typedef enum {
      META_LATER_RESIZE,
      META_LATER_CALC_SHOWING,
      META_LATER_CHECK_FULLSCREEN,
      META_LATER_SYNC_STACK,
      META_LATER_BEFORE_REDRAW,
      META_LATER_IDLE
    } MetaLaterType;

`META_LATER_RESIZE` | call in a resize processing phase that is done before GTK+ repainting (including window borders) is done.
`META_LATER_CALC_SHOWING` | used by Mutter to compute which windows should be mapped
`META_LATER_CHECK_FULLSCREEN` | used by Mutter to see if there's a fullscreen window
`META_LATER_SYNC_STACK` | used by Mutter to send it's idea of the stacking order to the server
`META_LATER_BEFORE_REDRAW` | call before the stage is redrawn
`META_LATER_IDLE` | call at a very low priority (can be blocked by running animations or redrawing applications)

### meta_later_add ()

    guint               meta_later_add                      (MetaLaterType when,
                                                             GSourceFunc func,
                                                             gpointer data,
                                                             GDestroyNotify notify);

Sets up a callback to be called at some later time. `when` determines the particular later occasion at which it is called. This is much like `g_idle_add()`, except that the functions interact properly with clutter event handling. If a "later" function is added from a clutter event handler, and is supposed to be run before the stage is redrawn, it will be run before that redraw of the stage, not the next one.

`when` : | enumeration value determining the phase at which to run the callback
`func` : | callback to run later
`data` : | data to pass to the callback
`notify` : | function to call to destroy `data` when it is no longer in use, or `NULL`
Returns : | an integer ID (guaranteed to be non-zero) that can be used to cancel the callback and prevent it from being run.

### meta_later_remove ()

    void                meta_later_remove                   (guint later_id);

Removes a callback added with `meta_later_add()`

`later_id` : | the integer ID returned from `meta_later_add()`