org.gnome.glib

## Class Glib

- Object
- - org.gnome.glib.Glib

- Direct Known Subclasses:
    Enchant, Gtk, Notify, Rsvg, Screenshot

      public class Glib
      extends Object

  Static methods to initialize the Java bindings around GLib.
  Since:
    4.0.0
  Author:
    Andrew Cowie, Serkan Kaba, Guillaume Mazoyer
  See Also:
    XDG Base Directory Specification

- - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `static String` | `formatSizeForDisplay(long size)` Format a size into a human readable String.
    `static String` | `getProgramName()` Get the internal program name set with `setProgramName()`, if any.
    `static String` | `getRealName()` Returns the real name of the user running the application from `/etc/passwd` file.
    `static String[]` | `getSystemConfigDirs()` Get a list of system-wide XDG configuration directories.
    `static String[]` | `getSystemDataDirs()` Get a list of system-wide XDG data directories.
    `static String` | `getUserCacheDir()` Get the XDG user specific cache directory.
    `static String` | `getUserConfigDir()` Get the XDG user specific configuration directory.
    `static String` | `getUserDataDir()` Get the XDG user specific data directory.
    `static String` | `getUserName()` Returns the username (i.e Linux login name) running the application.
    `static String` | `getUserSpecialDir(UserDirectory directory)` Get the XDG user specific special directory.
    `static void` | `idleAdd(Handler handler)` Queue an idle handler to be run during the next iteration of the main loop.
    `static String` | `markupEscapeText(String str)` Perform basic escaping on a String so that it can be safely passed to XML.
    `static void` | `reloadUserSpecialDirsCache()` Reset the cache used for `getUserSpecialDir()`.
    `static void` | `setProgramName(String name)` Change the internal program name used by GLib and GTK for internal error messages.

    - ### Methods inherited from class Object

      `equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Method Detail

    - #### formatSizeForDisplay

          public static String formatSizeForDisplay(long size)

      Format a size into a human readable String. This is useful when representing file sizes and data transfer rates.

      Sizes use the nearest prefix (KB, MB, GB). The prefix units are base 2 so 1 MB is 1024 * 1024 bytes.

      Note that the returned String depends on the localization. E.g. if the system is configured to use French, the formatted size will use French size prefix.

      Since:
        4.0.16

    - #### getProgramName

          public static String getProgramName()

      Get the internal program name set with `setProgramName()`, if any.
      Since:
        4.1.2

    - #### getRealName

          public static String getRealName()

      Returns the real name of the user running the application from `/etc/passwd` file. If it can't be determined `"Unknown"` is returned.

      The warning about encoding in `getUserName()` also applies.

      Since:
        4.0.15

    - #### getSystemConfigDirs

          public static String[] getSystemConfigDirs()

      Get a list of system-wide XDG configuration directories.
      Since:
        4.0.15

    - #### getSystemDataDirs

          public static String[] getSystemDataDirs()

      Get a list of system-wide XDG data directories.
      Since:
        4.0.15

    - #### getUserCacheDir

          public static String getUserCacheDir()

      Get the XDG user specific cache directory. In all likelihood this will be `~/.cache`.
      Since:
        4.0.15

    - #### getUserConfigDir

          public static String getUserConfigDir()

      Get the XDG user specific configuration directory. In all likelihood this will be `~/.config`.
      Since:
        4.0.15

    - #### getUserDataDir

          public static String getUserDataDir()

      Get the XDG user specific data directory. In all likelihood this will be `~/.local/share`.
      Since:
        4.0.15

    - #### getUserName

          public static String getUserName()

      Returns the username (i.e Linux login name) running the application.

      WARNING:
      This method assumes that your system uses UTF-8 as encoding. Please file a bug if this assumption is not valid for your system.

      Since:
        4.0.15

    - #### getUserSpecialDir

          public static String getUserSpecialDir(UserDirectory directory)

      Get the XDG user specific special directory. Directory constants are defined in `UserDirectory`. System wide defaults are defined in `/etc/xdg/user-dirs.defaults` and can be overridden in `~/.config/user-dir.dirs`.

      If you've already queried the "special" directories then those values are cached; they certainly don't change often. If you're writing a program that absolutely needs to be aware if those settings have changed after you're already used this, then you can force up to date information by calling `Glib.reloadUserSpecialDirsCache()`.

      Since:
        4.0.15

    - #### idleAdd

          public static void idleAdd(Handler handler)

      Queue an idle handler to be run during the next iteration of the main loop.

      Like all graphical user interfaces, GTK is not thread safe; GUI code must be run from the main thread, that is, the thread that Application's `run()` [which calls `Gtk.main()`] was invoked from.

      In order to make a change to a widget from a worker thread, you must embed the call(s) in an idle handler, as follows:

           Glib.idleAdd(new Handler() {
               public boolean run() {
                   b.setLabel("Press Me");
                   return false;
               }
           });

      where `b` is a Button you'd previously initialzed and added to your UI. More generally, you'd just call some `doStuff()` method and do your updates there.

      The return value in the handler indicates whether or not the idle function has done it's work; return `true` to indicate you want the handler to be re-invoked. Note that you are blocking the main loop when your idle handler is running, so if you're doing serious computation you're best doing that in a worker thread and not in the idle handler callback.

      Since:
        4.1.2

    - #### markupEscapeText

          public static String markupEscapeText(String str)

      Perform basic escaping on a String so that it can be safely passed to XML.

      This will escape `&`, `>`, `<`, etc which is necessary when passing arbitrary input to methods which use Pango Markup such as Labels with markup enabled via `setUseMarkup()` and directly with CellRendererText's `setMarkup()` or Layout's `setMarkup()`

      Since:
        4.0.17

    - #### reloadUserSpecialDirsCache

          public static void reloadUserSpecialDirsCache()

      Reset the cache used for `getUserSpecialDir()`.

      WARNING:
      This may cause memory leaks if the return values change between calls.

      Since:
        4.0.15

    - #### setProgramName

          public static void setProgramName(String name)

      Change the internal program name used by GLib and GTK for internal error messages. Occasionally (especially as we develop new functionality) you or we will do something wrong, and GLib will complain loudly about it to the console, for example:

           (gnome-panel:5581): Gtk-WARNING **: gtk_widget_size_allocate(): attempt to...

      where "`gnome-panel`" was the name set by that program with this method call, and `5581` was the process id originating the message. As you can see, the whole thing is pretty ugly (not to mention having no context), which is why one of the design goals of java-gnome is to fully proxy the entire underlying library and have none of the internals from GLib or GTK be exposed to the Java developer. If we do our job right, your users should never see a message like that; at worst it would be reported as a Java stack trace.

      You don't really need to call this, but it's here if you want to make it clearer in the `.xsession-errors` log what the culprit application is.

      Warning
      If you wish to use this, it must be called before anything else. This is the only method in java-gnome that can be called before `Gtk.init()`.

      Since:
        4.0.14