Package ch.bailu.gtk.glib

Class VariantBuilder

java.lang.Object
ch.bailu.gtk.type.Type
ch.bailu.gtk.type.Pointer
ch.bailu.gtk.type.Record
ch.bailu.gtk.glib.VariantBuilder
All Implemented Interfaces:
PointerInterface
public class VariantBuilder extends Record
A utility type for constructing container-type #GVariant instances.

This is an opaque structure and may only be accessed using the
following functions.

#GVariantBuilder is not threadsafe in any way. Do not attempt to
access it from more than one thread.

https://docs.gtk.org/glib/struct.VariantBuilder.html

  • Constructor Details

    • VariantBuilder

      public VariantBuilder(PointerContainer pointer)

    • VariantBuilder

      public VariantBuilder(@Nonnull VariantType type)
      Allocates and initialises a new #GVariantBuilder.

      You should call g_variant_builder_unref() on the return value when it
      is no longer needed. The memory will not be automatically freed by
      any other call.

      In most cases it is easier to place a #GVariantBuilder directly on
      the stack of the calling function and initialise it with
      g_variant_builder_init().
      Parameters:
      type - a container type

  • Method Details

    • getClassHandler

      public static ClassHandler getClassHandler()

    • add

      public void add(@Nonnull Str format_string, Object... _elipse)
      Adds to a #GVariantBuilder.

      This call is a convenience wrapper that is exactly equivalent to
      calling g_variant_new() followed by g_variant_builder_add_value().

      Note that the arguments must be of the correct width for their types
      specified in @format_string. This can be achieved by casting them. See
      the [GVariant varargs documentation][gvariant-varargs].

      This function might be used as follows: 
      <!-- language="C" -->
 GVariant *
 make_pointless_dictionary (void)
 {
   GVariantBuilder builder;
   int i;
 
   g_variant_builder_init (&builder, G_VARIANT_TYPE_ARRAY);
   for (i = 0; i < 16; i++)
     {
       gchar buf[3];
 
       sprintf (buf, "%d", i);
       g_variant_builder_add (&builder, "{is}", i, buf);
     }
 
   return g_variant_builder_end (&builder);
 }
      Parameters:
      format_string - a #GVariant varargs format string
      _elipse - arguments, as per @format_string

    • add

      public void add(String format_string, Object... _elipse)
      Adds to a #GVariantBuilder.

      This call is a convenience wrapper that is exactly equivalent to
      calling g_variant_new() followed by g_variant_builder_add_value().

      Note that the arguments must be of the correct width for their types
      specified in @format_string. This can be achieved by casting them. See
      the [GVariant varargs documentation][gvariant-varargs].

      This function might be used as follows: 
      <!-- language="C" -->
 GVariant *
 make_pointless_dictionary (void)
 {
   GVariantBuilder builder;
   int i;
 
   g_variant_builder_init (&builder, G_VARIANT_TYPE_ARRAY);
   for (i = 0; i < 16; i++)
     {
       gchar buf[3];
 
       sprintf (buf, "%d", i);
       g_variant_builder_add (&builder, "{is}", i, buf);
     }
 
   return g_variant_builder_end (&builder);
 }
      Parameters:
      format_string - a #GVariant varargs format string
      _elipse - arguments, as per @format_string

    • addParsed

      public void addParsed(@Nonnull Str format, Object... _elipse)
      Adds to a #GVariantBuilder.

      This call is a convenience wrapper that is exactly equivalent to
      calling g_variant_new_parsed() followed by
      g_variant_builder_add_value().

      Note that the arguments must be of the correct width for their types
      specified in @format_string. This can be achieved by casting them. See
      the [GVariant varargs documentation][gvariant-varargs].

      This function might be used as follows: 
      <!-- language="C" -->
 GVariant *
 make_pointless_dictionary (void)
 {
   GVariantBuilder builder;
   int i;
 
   g_variant_builder_init (&builder, G_VARIANT_TYPE_ARRAY);
   g_variant_builder_add_parsed (&builder, "{'width', <%i>}", 600);
   g_variant_builder_add_parsed (&builder, "{'title', <%s>}", "foo");
   g_variant_builder_add_parsed (&builder, "{'transparency', <0.5>}");
   return g_variant_builder_end (&builder);
 }
      Parameters:
      format - a text format #GVariant
      _elipse - arguments as per @format

    • addParsed

      public void addParsed(String format, Object... _elipse)
      Adds to a #GVariantBuilder.

      This call is a convenience wrapper that is exactly equivalent to
      calling g_variant_new_parsed() followed by
      g_variant_builder_add_value().

      Note that the arguments must be of the correct width for their types
      specified in @format_string. This can be achieved by casting them. See
      the [GVariant varargs documentation][gvariant-varargs].

      This function might be used as follows: 
      <!-- language="C" -->
 GVariant *
 make_pointless_dictionary (void)
 {
   GVariantBuilder builder;
   int i;
 
   g_variant_builder_init (&builder, G_VARIANT_TYPE_ARRAY);
   g_variant_builder_add_parsed (&builder, "{'width', <%i>}", 600);
   g_variant_builder_add_parsed (&builder, "{'title', <%s>}", "foo");
   g_variant_builder_add_parsed (&builder, "{'transparency', <0.5>}");
   return g_variant_builder_end (&builder);
 }
      Parameters:
      format - a text format #GVariant
      _elipse - arguments as per @format

    • addValue

      public void addValue(@Nonnull Variant value)
      Adds @value to @builder.

      It is an error to call this function in any way that would create an
      inconsistent value to be constructed. Some examples of this are
      putting different types of items into an array, putting the wrong
      types or number of items in a tuple, putting more than one value into
      a variant, etc.

      If @value is a floating reference (see g_variant_ref_sink()),
      the @builder instance takes ownership of @value.
      Parameters:
      value - a #GVariant

    • clear

      public void clear()
      Releases all memory associated with a #GVariantBuilder without
      freeing the #GVariantBuilder structure itself.

      It typically only makes sense to do this on a stack-allocated
      #GVariantBuilder if you want to abort building the value part-way
      through. This function need not be called if you call
      g_variant_builder_end() and it also doesn't need to be called on
      builders allocated with g_variant_builder_new() (see
      g_variant_builder_unref() for that).

      This function leaves the #GVariantBuilder structure set to all-zeros.
      It is valid to call this function on either an initialised
      #GVariantBuilder or one that is set to all-zeros but it is not valid
      to call this function on uninitialised memory.

    • close

      public void close()
      Closes the subcontainer inside the given @builder that was opened by
      the most recent call to g_variant_builder_open().

      It is an error to call this function in any way that would create an
      inconsistent value to be constructed (ie: too few values added to the
      subcontainer).

    • end

      public Variant end()
      Ends the builder process and returns the constructed value.

      It is not permissible to use @builder in any way after this call
      except for reference counting operations (in the case of a
      heap-allocated #GVariantBuilder) or by reinitialising it with
      g_variant_builder_init() (in the case of stack-allocated). This
      means that for the stack-allocated builders there is no need to
      call g_variant_builder_clear() after the call to
      g_variant_builder_end().

      It is an error to call this function in any way that would create an
      inconsistent value to be constructed (ie: insufficient number of
      items added to a container with a specific number of children
      required). It is also an error to call this function if the builder
      was created with an indefinite array or maybe type and no children
      have been added; in this case it is impossible to infer the type of
      the empty array.
      Returns:
      a new, floating, #GVariant

    • init

      public void init(@Nonnull VariantType type)
      Initialises a #GVariantBuilder structure.

      @type must be non-%NULL. It specifies the type of container to
      construct. It can be an indefinite type such as
      %G_VARIANT_TYPE_ARRAY or a definite type such as "as" or "(ii)".
      Maybe, array, tuple, dictionary entry and variant-typed values may be
      constructed.

      After the builder is initialised, values are added using
      g_variant_builder_add_value() or g_variant_builder_add().

      After all the child values are added, g_variant_builder_end() frees
      the memory associated with the builder and returns the #GVariant that
      was created.

      This function completely ignores the previous contents of @builder.
      On one hand this means that it is valid to pass in completely
      uninitialised memory. On the other hand, this means that if you are
      initialising over top of an existing #GVariantBuilder you need to
      first call g_variant_builder_clear() in order to avoid leaking
      memory.

      You must not call g_variant_builder_ref() or
      g_variant_builder_unref() on a #GVariantBuilder that was initialised
      with this function. If you ever pass a reference to a
      #GVariantBuilder outside of the control of your own code then you
      should assume that the person receiving that reference may try to use
      reference counting; you should use g_variant_builder_new() instead of
      this function.
      Parameters:
      type - a container type

    • open

      public void open(@Nonnull VariantType type)
      Opens a subcontainer inside the given @builder. When done adding
      items to the subcontainer, g_variant_builder_close() must be called. @type
      is the type of the container: so to build a tuple of several values, @type
      must include the tuple itself.

      It is an error to call this function in any way that would cause an
      inconsistent value to be constructed (ie: adding too many values or
      a value of an incorrect type).

      Example of building a nested variant: 
      <!-- language="C" -->
 GVariantBuilder builder;
 guint32 some_number = get_number ();
 g_autoptr (GHashTable) some_dict = get_dict ();
 GHashTableIter iter;
 const gchar *key;
 const GVariant *value;
 g_autoptr (GVariant) output = NULL;
 
 g_variant_builder_init (&builder, G_VARIANT_TYPE ("(ua{sv})"));
 g_variant_builder_add (&builder, "u", some_number);
 g_variant_builder_open (&builder, G_VARIANT_TYPE ("a{sv}"));
 
 g_hash_table_iter_init (&iter, some_dict);
 while (g_hash_table_iter_next (&iter, (gpointer *) &key, (gpointer *) &value))
   {
     g_variant_builder_open (&builder, G_VARIANT_TYPE ("{sv}"));
     g_variant_builder_add (&builder, "s", key);
     g_variant_builder_add (&builder, "v", value);
     g_variant_builder_close (&builder);
   }
 
 g_variant_builder_close (&builder);
 
 output = g_variant_builder_end (&builder);
      Parameters:
      type - the #GVariantType of the container

    • ref

      public VariantBuilder ref()
      Increases the reference count on @builder.

      Don't call this on stack-allocated #GVariantBuilder instances or bad
      things will happen.
      Returns:
      a new reference to @builder

    • unref

      public void unref()
      Decreases the reference count on @builder.

      In the event that there are no more references, releases all memory
      associated with the #GVariantBuilder.

      Don't call this on stack-allocated #GVariantBuilder instances or bad
      things will happen.

    • getTypeID

      public static long getTypeID()

    • getParentTypeID

      public static long getParentTypeID()

    • getTypeSize

      public static TypeSystem.TypeSize getTypeSize()

    • getParentTypeSize

      public static TypeSystem.TypeSize getParentTypeSize()

    • getInstanceSize

      public static int getInstanceSize()