1  /* GIO - GLib Input, Output and Streaming Library
       2   *
       3   * Copyright (C) 2006-2007 Red Hat, Inc.
       4   *
       5   * SPDX-License-Identifier: LGPL-2.1-or-later
       6   *
       7   * This library is free software; you can redistribute it and/or
       8   * modify it under the terms of the GNU Lesser General Public
       9   * License as published by the Free Software Foundation; either
      10   * version 2.1 of the License, or (at your option) any later version.
      11   *
      12   * This library is distributed in the hope that it will be useful,
      13   * but WITHOUT ANY WARRANTY; without even the implied warranty of
      14   * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
      15   * Lesser General Public License for more details.
      16   *
      17   * You should have received a copy of the GNU Lesser General
      18   * Public License along with this library; if not, see <http://www.gnu.org/licenses/>.
      19   *
      20   * Author: Alexander Larsson <alexl@redhat.com>
      21   */
      22  
      23  #ifndef __G_ICON_H__
      24  #define __G_ICON_H__
      25  
      26  #if !defined (__GIO_GIO_H_INSIDE__) && !defined (GIO_COMPILATION)
      27  #error "Only <gio/gio.h> can be included directly."
      28  #endif
      29  
      30  #include <gio/giotypes.h>
      31  
      32  G_BEGIN_DECLS
      33  
      34  #define G_TYPE_ICON            (g_icon_get_type ())
      35  #define G_ICON(obj)            (G_TYPE_CHECK_INSTANCE_CAST ((obj), G_TYPE_ICON, GIcon))
      36  #define G_IS_ICON(obj)	       (G_TYPE_CHECK_INSTANCE_TYPE ((obj), G_TYPE_ICON))
      37  #define G_ICON_GET_IFACE(obj)  (G_TYPE_INSTANCE_GET_INTERFACE ((obj), G_TYPE_ICON, GIconIface))
      38  
      39  typedef struct _GIconIface GIconIface;
      40  
      41  /**
      42   * GIconIface:
      43   * @g_iface: The parent interface.
      44   * @hash: A hash for a given #GIcon.
      45   * @equal: Checks if two #GIcons are equal.
      46   * @to_tokens: Serializes a #GIcon into tokens. The tokens must not
      47   * contain any whitespace. Don't implement if the #GIcon can't be
      48   * serialized (Since 2.20).
      49   * @from_tokens: Constructs a #GIcon from tokens. Set the #GError if
      50   * the tokens are malformed. Don't implement if the #GIcon can't be
      51   * serialized (Since 2.20).
      52   * @serialize: Serializes a #GIcon into a #GVariant. Since: 2.38
      53   *
      54   * GIconIface is used to implement GIcon types for various
      55   * different systems. See #GThemedIcon and #GLoadableIcon for
      56   * examples of how to implement this interface.
      57   */
      58  struct _GIconIface
      59  {
      60    GTypeInterface g_iface;
      61  
      62    /* Virtual Table */
      63  
      64    guint       (* hash)        (GIcon   *icon);
      65    gboolean    (* equal)       (GIcon   *icon1,
      66                                 GIcon   *icon2);
      67  
      68    /**
      69     * GIconIface::to_tokens:
      70     * @icon: The #GIcon
      71     * @tokens: (element-type utf8) (out caller-allocates):
      72     *   The array to fill with tokens
      73     * @out_version: (out): version of serialized tokens
      74     *
      75     * Serializes the @icon into string tokens.
      76     * This is can be invoked when g_icon_new_for_string() is called.
      77     *
      78     * Returns: %TRUE if serialization took place, %FALSE otherwise
      79     *
      80     * Since: 2.20
      81     */
      82    gboolean    (* to_tokens)   (GIcon   *icon,
      83                                 GPtrArray *tokens,
      84                                 gint    *out_version);
      85  
      86    /**
      87     * GIconIface::from_tokens:
      88     * @tokens: (array length=num_tokens): An array of tokens
      89     * @num_tokens: The number of tokens in @tokens
      90     * @version: Version of the serialized tokens
      91     * @error: Return location for errors, or %NULL to ignore
      92     *
      93     * Constructs a #GIcon from a list of @tokens.
      94     *
      95     * Returns: (nullable) (transfer full): the #GIcon or %NULL on error
      96     *
      97     * Since: 2.20
      98     */
      99    GIcon *     (* from_tokens) (gchar  **tokens,
     100                                 gint     num_tokens,
     101                                 gint     version,
     102                                 GError **error);
     103  
     104    GVariant *  (* serialize)   (GIcon   *icon);
     105  };
     106  
     107  GIO_AVAILABLE_IN_ALL
     108  GType    g_icon_get_type  (void) G_GNUC_CONST;
     109  
     110  GIO_AVAILABLE_IN_ALL
     111  guint    g_icon_hash            (gconstpointer  icon);
     112  GIO_AVAILABLE_IN_ALL
     113  gboolean g_icon_equal           (GIcon         *icon1,
     114                                   GIcon         *icon2);
     115  GIO_AVAILABLE_IN_ALL
     116  gchar   *g_icon_to_string       (GIcon         *icon);
     117  GIO_AVAILABLE_IN_ALL
     118  GIcon   *g_icon_new_for_string  (const gchar   *str,
     119                                   GError       **error);
     120  
     121  GIO_AVAILABLE_IN_2_38
     122  GVariant * g_icon_serialize     (GIcon         *icon);
     123  GIO_AVAILABLE_IN_2_38
     124  GIcon *    g_icon_deserialize   (GVariant      *value);
     125  
     126  G_END_DECLS
     127  
     128  #endif /* __G_ICON_H__ */