Class (GI Class)

Pango-1.0 ▶ Pango ▶ Layout

A Pango.Layout structure represents an entire paragraph of text.

While complete access to the layout capabilities of Pango is provided using the detailed interfaces for itemization and shaping, using that functionality directly involves writing a fairly large amount of code. Pango.Layout provides a high-level driver for formatting entire paragraphs of text at once. This includes paragraph-level functionality such as line breaking, justification, alignment and ellipsization.

A Pango.Layout is initialized with a Pango.Context, UTF-8 string and set of attributes for that string. Once that is done, the set of formatted lines can be extracted from the object, the layout can be rendered, and conversion between logical character positions within the layout's text, and the physical position of the resulting glyphs can be made.

There are a number of parameters to adjust the formatting of a Pango.Layout. The following image shows adjustable parameters (on the left) and font metrics (on the right):

Pango Layout Parameters

The following images demonstrate the effect of alignment and justification on the layout of text:
align=left align=left, justify
align=center align=center, justify
align=right align=right, justify

It is possible, as well, to ignore the 2-D setup, and simply treat the results of a Pango.Layout as a list of lines.

Hierarchy (View Summary)

Index

Constructors

constructor

Properties

$signals $gtype

Methods

_init connect connect_after context_changed copy emit get_alignment get_attributes get_auto_dir get_baseline get_caret_pos get_character_count get_context get_cursor_pos get_direction get_ellipsize get_extents get_font_description get_height get_indent get_iter get_justify get_justify_last_line get_line get_line_count get_line_readonly get_line_spacing get_lines get_lines_readonly get_log_attrs get_log_attrs_readonly get_pixel_extents get_pixel_size get_serial get_single_paragraph_mode get_size get_spacing get_tabs get_text get_unknown_glyphs_count get_width get_wrap index_to_line_x index_to_pos is_ellipsized is_wrapped move_cursor_visually serialize set_alignment set_attributes set_auto_dir set_ellipsize set_font_description set_height set_indent set_justify set_justify_last_line set_line_spacing set_markup set_markup_with_accel set_single_paragraph_mode set_spacing set_tabs set_text set_width set_wrap write_to_file xy_to_index deserialize new

Methods - Inherited from GObject

bind_property bind_property_full block_signal_handler disconnect force_floating freeze_notify get_data get_property get_qdata getv is_floating notify notify_by_pspec ref ref_sink run_dispose set set_data set_property steal_data steal_qdata stop_emission_by_name thaw_notify unblock_signal_handler unref vfunc_constructed vfunc_dispatch_properties_changed vfunc_dispose vfunc_finalize vfunc_get_property vfunc_notify vfunc_set_property watch_closure _classInit compat_control find_property install_properties install_property interface_find_property interface_install_property interface_list_properties list_properties newv override_property

Constructors

Properties

$signals: Pango.Layout.SignalSignatures

Compile-time signal type information.

This instance property is generated only for TypeScript type checking. It is not defined at runtime and should not be accessed in JS code.

$gtype: GType<Pango.Layout>

Methods

_init

  • Forces recomputation of any state in the Pango.Layout that might depend on the layout's context.

    This function should be called if you make changes to the context subsequent to creating the layout.

    Returns void

  • Gets whether to calculate the base direction for the layout according to its contents.

    See Pango.Layout.set_auto_dir.

    Returns boolean

    true if the bidirectional base direction is computed from the layout's contents, false otherwise

  • Gets the Y position of baseline of the first line in layout.

    Returns number

    baseline of first line, from top of layout

  • Returns the number of Unicode characters in the the text of layout.

    Returns number

    the number of Unicode characters in the text of layout

  • Given an index within a layout, determines the positions that of the strong and weak cursors if the insertion point is at that index.

    The position of each cursor is stored as a zero-width rectangle with the height of the run extents.

    Cursor positions

    The strong cursor location is the location where characters of the directionality equal to the base direction of the layout are inserted. The weak cursor location is the location where characters of the directionality opposite to the base direction of the layout are inserted.

    The following example shows text with both a strong and a weak cursor.

    Strong and weak cursors

    The strong cursor has a little arrow pointing to the right, the weak cursor to the left. Typing a 'c' in this situation will insert the character after the 'b', and typing another Hebrew character, like 'ג', will insert it at the end.

    Parameters

    • index_: number

      the byte index of the cursor

    Returns [Pango.Rectangle, Pango.Rectangle]

  • Computes the logical and ink extents of layout.

    Logical extents are usually what you want for positioning things. Note that both extents may have non-zero x and y. You may want to use those to offset where you render the layout. Not doing that is a very typical bug that shows up as right-to-left layouts not being correctly positioned in a layout with a set width.

    The extents are given in layout coordinates and in Pango units; layout coordinates begin at the top left corner of the layout.

    Returns [Pango.Rectangle, Pango.Rectangle]

  • Gets the paragraph indent width in Pango units.

    A negative value indicates a hanging indentation.

    Returns number

    the indent in Pango units

  • Gets whether each complete line should be stretched to fill the entire width of the layout.

    Returns boolean

    the justify value

  • Gets whether the last line should be stretched to fill the entire width of the layout.

    Returns boolean

    the justify value

  • Retrieves a particular line from a Pango.Layout.

    This is a faster alternative to Pango.Layout.get_line, but the user is not expected to modify the contents of the line (glyphs, glyph widths, etc.).

    Parameters

    • line: number

      the index of a line, which must be between 0 and pango_layout_get_line_count(layout) - 1, inclusive.

    Returns LayoutLine

    the requested Pango.LayoutLine, or null if the index is out of range. This layout line can be ref'ed and retained, but will become invalid if changes are made to the Pango.Layout. No changes should be made to the line.

  • Returns the lines of the layout as a list.

    This is a faster alternative to Pango.Layout.get_lines, but the user is not expected to modify the contents of the lines (glyphs, glyph widths, etc.).

    Returns LayoutLine[]

    a GLib.SList containing the lines in the layout. This points to internal data of the Pango.Layout and must be used with care. It will become invalid on any change to the layout's text or properties. No changes should be made to the lines.

  • Retrieves an array of logical attributes for each character in the layout.

    This is a faster alternative to Pango.Layout.get_log_attrs. The returned array is part of layout and must not be modified. Modifying the layout will invalidate the returned array.

    The number of attributes returned in n_attrs will be one more than the total number of characters in the layout, since there need to be attributes corresponding to both the position before the first character and the position after the last character.

    Returns LogAttr[]

    an array of logical attributes

  • Returns the current serial number of layout.

    The serial number is initialized to an small number larger than zero when a new layout is created and is increased whenever the layout is changed using any of the setter functions, or the Pango.Context it uses has changed. The serial may wrap, but will never have the value 0. Since it can wrap, never compare it with "less than", always use "not equals".

    This can be used to automatically detect changes to a Pango.Layout, and is useful for example to decide whether a layout needs redrawing. To force the serial to be increased, use Pango.Layout.context_changed.

    Returns number

    The current serial number of layout.

  • Gets the amount of spacing between the lines of the layout.

    Returns number

    the spacing in Pango units

get_text

  • get_text(): string

    Gets the text in the layout.

    The returned text should not be freed or modified.

    Returns string

    the text in the layout

  • Counts the number of unknown glyphs in layout.

    This function can be used to determine if there are any fonts available to render all characters in a certain string, or when used in combination with Pango.AttrType.FALLBACK, to check if a certain font supports all the characters in the string.

    Returns number

    The number of unknown glyphs in layout

  • Converts from byte index_ within the layout to line and X position.

    The X position is measured from the left edge of the line.

    Parameters

    • index_: number

      the byte index of a grapheme within the layout

    • trailing: boolean

      an integer indicating the edge of the grapheme to retrieve the position of. If > 0, the trailing edge of the grapheme, if 0, the leading of the grapheme

    Returns [number, number]

  • Converts from an index within a Pango.Layout to the onscreen position corresponding to the grapheme at that index.

    The returns is represented as rectangle. Note that pos->x is always the leading edge of the grapheme and pos->x + pos->width the trailing edge of the grapheme. If the directionality of the grapheme is right-to-left, then pos->width will be negative.

    Parameters

    • index_: number

      byte index within layout

    Returns Pango.Rectangle

  • Queries whether the layout had to ellipsize any paragraphs.

    This returns true if the ellipsization mode for layout is not Pango.EllipsizeMode.NONE, a positive width is set on layout, and there are paragraphs exceeding that width that have to be ellipsized.

    Returns boolean

    true if any paragraphs had to be ellipsized, false otherwise

  • Queries whether the layout had to wrap any paragraphs.

    This returns true if a positive width is set on layout, and there are paragraphs exceeding the layout width that have to be wrapped.

    Returns boolean

    true if any paragraphs had to be wrapped, false otherwise

  • Computes a new cursor position from an old position and a direction.

    If direction is positive, then the new position will cause the strong or weak cursor to be displayed one position to right of where it was with the old cursor position. If direction is negative, it will be moved to the left.

    In the presence of bidirectional text, the correspondence between logical and visual order will depend on the direction of the current run, and there may be jumps when the cursor is moved off of the end of a run.

    Motion here is in cursor positions, not in characters, so a single call to this function may move the cursor over multiple characters when multiple characters combine to form a single grapheme.

    Parameters

    • strong: boolean

      whether the moving cursor is the strong cursor or the weak cursor. The strong cursor is the cursor corresponding to text insertion in the base direction for the layout.

    • old_index: number

      the byte index of the current cursor position

    • old_trailing: number

      if 0, the cursor was at the leading edge of the grapheme indicated by old_index, if > 0, the cursor was at the trailing edge.

    • direction: number

      direction to move cursor. A negative value indicates motion to the left

    Returns [number, number]

  • Sets whether to calculate the base direction for the layout according to its contents.

    When this flag is on (the default), then paragraphs in layout that begin with strong right-to-left characters (Arabic and Hebrew principally), will have right-to-left layout, paragraphs with letters from other scripts will have left-to-right layout. Paragraphs with only neutral characters get their direction from the surrounding paragraphs.

    When false, the choice between left-to-right and right-to-left layout is done according to the base direction of the layout's Pango.Context. (See Pango.Context.set_base_dir).

    When the auto-computed direction of a paragraph differs from the base direction of the context, the interpretation of Pango.Alignment.LEFT and Pango.Alignment.RIGHT are swapped.

    Parameters

    • auto_dir: boolean

      if true, compute the bidirectional base direction from the layout's contents

    Returns void

  • Sets the type of ellipsization being performed for layout.

    Depending on the ellipsization mode ellipsize text is removed from the start, middle, or end of text so they fit within the width and height of layout set with Pango.Layout.set_width and Pango.Layout.set_height.

    If the layout contains characters such as newlines that force it to be layed out in multiple paragraphs, then whether each paragraph is ellipsized separately or the entire layout is ellipsized as a whole depends on the set height of the layout.

    The default value is Pango.EllipsizeMode.NONE.

    See Pango.Layout.set_height for details.

    Parameters

    Returns void

  • Sets the height to which the Pango.Layout should be ellipsized at.

    There are two different behaviors, based on whether height is positive or negative.

    If height is positive, it will be the maximum height of the layout. Only lines would be shown that would fit, and if there is any text omitted, an ellipsis added. At least one line is included in each paragraph regardless of how small the height value is. A value of zero will render exactly one line for the entire layout.

    If height is negative, it will be the (negative of) maximum number of lines per paragraph. That is, the total number of lines shown may well be more than this value if the layout contains multiple paragraphs of text. The default value of -1 means that the first line of each paragraph is ellipsized. This behavior may be changed in the future to act per layout instead of per paragraph. File a bug against pango at https://gitlab.gnome.org/gnome/pango if your code relies on this behavior.

    Height setting only has effect if a positive width is set on layout and ellipsization mode of layout is not Pango.EllipsizeMode.NONE. The behavior is undefined if a height other than -1 is set and ellipsization mode is set to Pango.EllipsizeMode.NONE, and may change in the future.

    Parameters

    • height: number

      the desired height of the layout in Pango units if positive, or desired number of lines if negative.

    Returns void

  • Sets the width in Pango units to indent each paragraph.

    A negative value of indent will produce a hanging indentation. That is, the first line will have the full width, and subsequent lines will be indented by the absolute value of indent.

    The indent setting is ignored if layout alignment is set to Pango.Alignment.CENTER.

    The default value is 0.

    Parameters

    • indent: number

      the amount by which to indent

    Returns void

  • Sets whether each complete line should be stretched to fill the entire width of the layout.

    Stretching is typically done by adding whitespace, but for some scripts (such as Arabic), the justification may be done in more complex ways, like extending the characters.

    Note that this setting is not implemented and so is ignored in Pango older than 1.18.

    Note that tabs and justification conflict with each other: Justification will move content away from its tab-aligned positions.

    The default value is false.

    Also see Pango.Layout.set_justify_last_line.

    Parameters

    • justify: boolean

      whether the lines in the layout should be justified

    Returns void

  • Sets whether the last line should be stretched to fill the entire width of the layout.

    This only has an effect if Pango.Layout.set_justify has been called as well.

    The default value is false.

    Parameters

    • justify: boolean

      whether the last line in the layout should be justified

    Returns void

  • Sets a factor for line spacing.

    Typical values are: 0, 1, 1.5, 2. The default values is 0.

    If factor is non-zero, lines are placed so that

    baseline2 = baseline1 + factor * height2

    where height2 is the line height of the second line (as determined by the font(s)). In this case, the spacing set with Pango.Layout.set_spacing is ignored.

    If factor is zero (the default), spacing is applied as before.

    Note: for semantics that are closer to the CSS line-height property, see Pango.attr_line_height_new.

    Parameters

    • factor: number

      the new line spacing factor

    Returns void

  • Sets the layout text and attribute list from marked-up text.

    See Pango Markup).

    Replaces the current text and attribute list.

    This is the same as Pango.Layout.set_markup_with_accel, but the markup text isn't scanned for accelerators.

    Parameters

    • markup: string

      marked-up text

    • length: number

      length of marked-up text in bytes, or -1 if markup is NUL-terminated

    Returns void

  • Sets the layout text and attribute list from marked-up text.

    See Pango Markup).

    Replaces the current text and attribute list.

    If accel_marker is nonzero, the given character will mark the character following it as an accelerator. For example, accel_marker might be an ampersand or underscore. All characters marked as an accelerator will receive a Pango.Underline.LOW attribute, and the first character so marked will be returned in accel_char. Two accel_marker characters following each other produce a single literal accel_marker character.

    Parameters

    • markup: string

      marked-up text (see Pango Markup)

    • length: number

      length of marked-up text in bytes, or -1 if markup is NUL-terminated

    • accel_marker: string

      marker for accelerators in the text

    Returns string

  • Sets the single paragraph mode of layout.

    If setting is true, do not treat newlines and similar characters as paragraph separators; instead, keep all text in a single paragraph, and display a glyph for paragraph separator characters. Used when you want to allow editing of newlines on a single text line.

    The default value is false.

    Parameters

    • setting: boolean

      new setting

    Returns void

  • Sets the amount of spacing in Pango units between the lines of the layout.

    When placing lines with spacing, Pango arranges things so that

    line2.top = line1.bottom + spacing

    The default value is 0.

    Note: Since 1.44, Pango is using the line height (as determined by the font) for placing lines when the line spacing factor is set to a non-zero value with Pango.Layout.set_line_spacing. In that case, the spacing set with this function is ignored.

    Note: for semantics that are closer to the CSS line-height property, see Pango.attr_line_height_new.

    Parameters

    • spacing: number

      the amount of spacing

    Returns void

  • Sets the tabs to use for layout, overriding the default tabs.

    Pango.Layout will place content at the next tab position whenever it meets a Tab character (U+0009).

    By default, tabs are every 8 spaces. If tabs is null, the default tabs are reinstated. tabs is copied into the layout; you must free your copy of tabs yourself.

    Note that tabs and justification conflict with each other: Justification will move content away from its tab-aligned positions. The same is true for alignments other than Pango.Alignment.LEFT.

    Parameters

    Returns void

set_text

  • set_text(text: string, length: number): void

    Sets the text of the layout.

    This function validates text and renders invalid UTF-8 with a placeholder glyph.

    Note that if you have used Pango.Layout.set_markup or Pango.Layout.set_markup_with_accel on layout before, you may want to call Pango.Layout.set_attributes to clear the attributes set on the layout from the markup as this function does not clear attributes.

    Parameters

    • text: string

      the text

    • length: number

      maximum length of text, in bytes. -1 indicates that the string is nul-terminated and the length should be calculated. The text will also be truncated on encountering a nul-termination even when length is positive.

    Returns void

  • Sets the width to which the lines of the Pango.Layout should wrap or get ellipsized.

    The default value is -1: no width set.

    Parameters

    • width: number

      the desired width in Pango units, or -1 to indicate that no wrapping or ellipsization should be performed.

    Returns void

  • Converts from X and Y position within a layout to the byte index to the character at that logical position.

    If the Y position is not inside the layout, the closest position is chosen (the position will be clamped inside the layout). If the X position is not within the layout, then the start or the end of the line is chosen as described for Pango.LayoutLine.x_to_index. If either the X or Y positions were not inside the layout, then the function returns false; on an exact hit, it returns true.

    Parameters

    • x: number

      the X offset (in Pango units) from the left edge of the layout

    • y: number

      the Y offset (in Pango units) from the top edge of the layout

    Returns [boolean, number, number]

    true if the coordinates were inside text, false otherwise

Methods - Inherited from GObject

  • Creates a binding between source_property on source and target_property on target.

    Whenever the source_property is changed the target_property is updated using the same value. For instance:

      g_object_bind_property (action, "active", widget, "sensitive", 0);

    Will result in the "sensitive" property of the widget GObject.Object instance to be updated with the same value of the "active" property of the action GObject.Object instance.

    If flags contains GObject.BindingFlags.BIDIRECTIONAL then the binding will be mutual: if target_property on target changes then the source_property on source will be updated as well.

    The binding will automatically be removed when either the source or the target instances are finalized. To remove the binding without affecting the source and the target you can just call g_object_unref() on the returned GObject.Binding instance.

    Removing the binding by calling g_object_unref() on it must only be done if the binding, source and target are only used from a single thread and it is clear that both source and target outlive the binding. Especially it is not safe to rely on this if the binding, source or target can be finalized from different threads. Keep another reference to the binding and use g_binding_unbind() instead to be on the safe side.

    A GObject.Object can have multiple bindings.

    Parameters

    Returns GObject.Binding

    the GObject.Binding instance representing the binding between the two GObject.Object instances. The binding is released whenever the GObject.Binding reference count reaches zero.

  • Complete version of g_object_bind_property().

    Creates a binding between source_property on source and target_property on target, allowing you to set the transformation functions to be used by the binding.

    If flags contains GObject.BindingFlags.BIDIRECTIONAL then the binding will be mutual: if target_property on target changes then the source_property on source will be updated as well. The transform_from function is only used in case of bidirectional bindings, otherwise it will be ignored

    The binding will automatically be removed when either the source or the target instances are finalized. This will release the reference that is being held on the GObject.Binding instance; if you want to hold on to the GObject.Binding instance, you will need to hold a reference to it.

    To remove the binding, call g_binding_unbind().

    A GObject.Object can have multiple bindings.

    The same user_data parameter will be used for both transform_to and transform_from transformation functions; the notify function will be called once, when the binding is removed. If you need different data for each transformation function, please use g_object_bind_property_with_closures() instead.

    Parameters

    • source_property: string

      the property on source to bind

    • target: GObject.Object

      the target GObject.Object

    • target_property: string

      the property on target to bind

    • flags: GObject.BindingFlags

      flags to pass to GObject.Binding

    • Optionaltransform_to: BindingTransformFunc

      the transformation function from the source to the target, or null to use the default

    • Optionaltransform_from: BindingTransformFunc

      the transformation function from the target to the source, or null to use the default

    • Optionalnotify: DestroyNotify

      a function to call when disposing the binding, to free resources used by the transformation functions, or null if not required

    Returns GObject.Binding

    the GObject.Binding instance representing the binding between the two GObject.Object instances. The binding is released whenever the GObject.Binding reference count reaches zero.

  • Creates a binding between source_property on source and target_property on target, allowing you to set the transformation functions to be used by the binding.

    This function is the language bindings friendly version of g_object_bind_property_full(), using GClosures instead of function pointers.

    Parameters

    Returns GObject.Binding

    the GObject.Binding instance representing the binding between the two GObject.Object instances. The binding is released whenever the GObject.Binding reference count reaches zero.

  • Disconnects a handler from an instance so it will not be called during any future or currently ongoing emissions of the signal it has been connected to.

    Parameters

    • id: number

      Handler ID of the handler to be disconnected

    Returns void

  • This function is intended for GObject.Object implementations to re-enforce a [floating][floating-ref] object reference. Doing this is seldom required: all GInitiallyUnowneds are created with a floating reference which usually just needs to be sunken by calling g_object_ref_sink().

    Returns void

  • Increases the freeze count on object. If the freeze count is non-zero, the emission of "notify" signals on object is stopped. The signals are queued until the freeze count is decreased to zero. Duplicate notifications are squashed so that at most one GObject.Object::notify signal is emitted for each property modified while the object is frozen.

    This is necessary for accessors that modify multiple properties to prevent premature notification while the object is still being modified.

    Returns void

  • Gets a named field from the objects table of associations (see g_object_set_data()).

    Parameters

    • key: string

      name of the key for that association

    Returns any

    the data if found, or null if no such data exists.

  • Gets a property of an object.

    The value can be:

    • an empty GObject.Value initialized by G_VALUE_INIT, which will be automatically initialized with the expected type of the property (since GLib 2.60)
    • a GObject.Value initialized with the expected type of the property
    • a GObject.Value initialized with a type to which the expected type of the property can be transformed

    In general, a copy is made of the property contents and the caller is responsible for freeing the memory by calling GObject.Value.unset.

    Note that GObject.Object.get_property is really intended for language bindings, GObject.Object.get is much more convenient for C programming.

    Parameters

    • property_name: string

      The name of the property to get

    • value: any

      Return location for the property value. Can be an empty GObject.Value initialized by G_VALUE_INIT (auto-initialized with expected type since GLib 2.60), a GObject.Value initialized with the expected property type, or a GObject.Value initialized with a transformable type

    Returns any

  • This function gets back user data pointers stored via g_object_set_qdata().

    Parameters

    • quark: number

      A GLib.Quark, naming the user data pointer

    Returns any

    The user data pointer set, or null

  • Gets n_properties properties for an object. Obtained properties will be set to values. All properties must be valid. Warnings will be emitted and undefined behaviour may result if invalid properties are passed in.

    Parameters

    • names: string[]

      the names of each property to get

    • values: any[]

      the values of each property to get

    Returns void

  • Emits a "notify" signal for the property property_name on object.

    When possible, eg. when signaling a property change from within the class that registered the property, you should use g_object_notify_by_pspec() instead.

    Note that emission of the notify signal may be blocked with g_object_freeze_notify(). In this case, the signal emissions are queued and will be emitted (in reverse order) when g_object_thaw_notify() is called.

    Parameters

    • property_name: string

      the name of a property installed on the class of object.

    Returns void

  • Emits a "notify" signal for the property specified by pspec on object.

    This function omits the property name lookup, hence it is faster than g_object_notify().

    One way to avoid using g_object_notify() from within the class that registered the properties, and using g_object_notify_by_pspec() instead, is to store the GParamSpec used with g_object_class_install_property() inside a static array, e.g.:

      typedef enum
      {
        PROP_FOO = 1,
        PROP_LAST
      } MyObjectProperty;

      static GParamSpec *properties[PROP_LAST];

      static void
      my_object_class_init (MyObjectClass *klass)
      {
        properties[PROP_FOO] = g_param_spec_int ("foo", NULL, NULL,
                                                 0, 100,
                                                 50,
                                                 G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS);
        g_object_class_install_property (gobject_class,
                                         PROP_FOO,
                                         properties[PROP_FOO]);
      }

    and then notify a change on the "foo" property with:

      g_object_notify_by_pspec (self, properties[PROP_FOO]);

    Parameters

    Returns void

  • Increases the reference count of object.

    Since GLib 2.56, if GLIB_VERSION_MAX_ALLOWED is 2.56 or greater, the type of object will be propagated to the return type (using the GCC typeof() extension), so any casting the caller needs to do on the return type must be explicit.

    Returns GObject.Object

    the same object

  • Increase the reference count of object, and possibly remove the [floating][floating-ref] reference, if object has a floating reference.

    In other words, if the object is floating, then this call "assumes ownership" of the floating reference, converting it to a normal reference by clearing the floating flag while leaving the reference count unchanged. If the object is not floating, then this call adds a new normal reference increasing the reference count by one.

    Since GLib 2.56, the type of object will be propagated to the return type under the same conditions as for g_object_ref().

    Returns GObject.Object

    object

  • Releases all references to other objects. This can be used to break reference cycles.

    This function should only be called from object system implementations.

    Returns void

  • Sets multiple properties of an object at once. The properties argument should be a dictionary mapping property names to values.

    Parameters

    • properties: { [key: string]: any }

      Object containing the properties to set

    Returns void

  • Each object carries around a table of associations from strings to pointers. This function lets you set an association.

    If the object already had an association with that name, the old association will be destroyed.

    Internally, the key is converted to a GLib.Quark using g_quark_from_string(). This means a copy of key is kept permanently (even after object has been finalized) — so it is recommended to only use a small, bounded set of values for key in your program, to avoid the GLib.Quark storage growing unbounded.

    Parameters

    • key: string

      name of the key

    • Optionaldata: any

      data to associate with that key

    Returns void

  • Sets a property on an object.

    Parameters

    • property_name: string

      The name of the property to set

    • value: any

      The value to set the property to

    Returns void

  • Remove a specified datum from the object's data associations, without invoking the association's destroy handler.

    Parameters

    • key: string

      name of the key

    Returns any

    the data if found, or null if no such data exists.

  • This function gets back user data pointers stored via g_object_set_qdata() and removes the data from object without invoking its destroy() function (if any was set). Usually, calling this function is only required to update user data pointers with a destroy notifier, for example:

    void
    object_add_to_user_list (GObject     *object,
                             const gchar *new_string)
    {
      // the quark, naming the object data
      GQuark quark_string_list = g_quark_from_static_string ("my-string-list");
      // retrieve the old string list
      GList *list = g_object_steal_qdata (object, quark_string_list);

      // prepend new string
      list = g_list_prepend (list, g_strdup (new_string));
      // this changed 'list', so we need to set it again
      g_object_set_qdata_full (object, quark_string_list, list, free_string_list);
    }
    static void
    free_string_list (gpointer data)
    {
      GList *node, *list = data;

      for (node = list; node; node = node->next)
        g_free (node->data);
      g_list_free (list);
    }

    Using g_object_get_qdata() in the above example, instead of g_object_steal_qdata() would have left the destroy function set, and thus the partial string list would have been freed upon g_object_set_qdata_full().

    Parameters

    • quark: number

      A GLib.Quark, naming the user data pointer

    Returns any

    The user data pointer set, or null

  • Stops a signal's emission by the given signal name. This will prevent the default handler and any subsequent signal handlers from being invoked.

    Parameters

    • detailedName: string

      Name of the signal to stop emission of

    Returns void

  • Reverts the effect of a previous call to g_object_freeze_notify(). The freeze count is decreased on object and when it reaches zero, queued "notify" signals are emitted.

    Duplicate notifications for each property are squashed so that at most one GObject.Object::notify signal is emitted for each property, in the reverse order in which they have been queued.

    It is an error to call this function when the freeze count is zero.

    Returns void

  • Decreases the reference count of object. When its reference count drops to 0, the object is finalized (i.e. its memory is freed).

    If the pointer to the GObject.Object may be reused in future (for example, if it is an instance variable of another object), it is recommended to clear the pointer to null rather than retain a dangling pointer to a potentially invalid GObject.Object instance. Use g_clear_object() for this.

    Returns void

  • the constructed function is called by g_object_new() as the final step of the object creation process. At the point of the call, all construction properties have been set on the object. The purpose of this call is to allow for object initialisation steps that can only be performed after construction properties have been set. constructed implementors should chain up to the constructed call of their parent class to allow it to complete its initialisation.

    Returns void

  • the dispose function is supposed to drop all references to other objects, but keep the instance otherwise intact, so that client method invocations still work. It may be run multiple times (due to reference loops). Before returning, dispose should chain up to the dispose method of the parent class.

    Returns void

  • instance finalization function, should finish the finalization of the instance begun in dispose and chain up to the finalize method of the parent class.

    Returns void

  • Emits a "notify" signal for the property property_name on object.

    When possible, eg. when signaling a property change from within the class that registered the property, you should use g_object_notify_by_pspec() instead.

    Note that emission of the notify signal may be blocked with g_object_freeze_notify(). In this case, the signal emissions are queued and will be emitted (in reverse order) when g_object_thaw_notify() is called.

    Parameters

    Returns void

  • the generic setter for all properties of this type. Should be overridden for every type with properties. If implementations of set_property don't emit property change notification explicitly, this will be done implicitly by the type system. However, if the notify signal is emitted explicitly, the type system will not emit it a second time.

    Parameters

    Returns void

  • This function essentially limits the life time of the closure to the life time of the object. That is, when the object is finalized, the closure is invalidated by calling g_closure_invalidate() on it, in order to prevent invocations of the closure with a finalized (nonexisting) object. Also, g_object_ref() and g_object_unref() are added as marshal guards to the closure, to ensure that an extra reference count is held on object during invocation of the closure. Usually, this function will be called on closures that use this object as closure data.

    Parameters

    Returns void

Static_classInit

  • Add a property to an interface; this is only useful for interfaces that are added to GObject-derived types. Adding a property to an interface forces all objects classes with that interface to have a compatible property. The compatible property could be a newly created GObject.ParamSpec, but normally g_object_class_override_property() will be used so that the object class only needs to provide an implementation and inherits the property description, default value, bounds, and so forth from the interface property.

    This function is meant to be called from the interface's default vtable initialization function (the class_init member of GObject.TypeInfo.) It must not be called after after class_init has been called for any object types implementing this interface.

    If pspec is a floating reference, it will be consumed.

    Parameters

    Returns void

  • Parameters

    • property_id: number

      the new property ID

    • name: string

      the name of a property registered in a parent class or in an interface of this class.

    Returns void

Interfaces

ConstructorProps
SignalSignatures