add docstrings

jwahlstrand · jwahlstrand · commit 2e31153c3762 · 2025-07-13T12:12:34.000-04:00
diff --git a/docs/src/manual/textwidgets.md b/docs/src/manual/textwidgets.md
@@ -67,6 +67,8 @@ ent.visibility = false
 ```
 To get notified by changes to the entry one can listen to the "changed" event.
 
+The `GtkEntry` widget includes a progress bar. Methods `fraction`, `pulse`, and `pulse_step` control its appearance and work the same as for [GtkProgressBar](@ref).
+
 ## [GtkSearchEntry](https://docs.gtk.org/gtk4/class.SearchEntry.html)
 
 A special variant of the entry that can be used as a search box is `GtkSearchEntry`. It is equipped
diff --git a/gen/gen_gtk4.jl b/gen/gen_gtk4.jl
@@ -14,7 +14,7 @@ constructor_skiplist=[:new_first]
 object_skiplist=[:CClosureExpression,:ClosureExpression,:ParamSpecExpression,:PrintUnixDialog,:PageSetupUnixDialog]
 obj_constructor_skiplist=[:new_from_resource,:new_with_mnemonic,:new_with_text,:new_with_entry,:new_with_model_and_entry,:new_for_resource,:new_from_icon_name]
 
-GI.export_struct_exprs!(ns,path, "gtk4", struct_skiplist, [:BitsetIter,:BuildableParser]; doc_xml = d, object_skiplist = object_skiplist, constructor_skiplist = constructor_skiplist, output_boxed_cache_init = false, output_boxed_types_def = false, output_object_cache_define = false, output_object_cache_init = false, object_constructor_skiplist = obj_constructor_skiplist, doc_skiplist = [:Builder], exclude_deprecated = false)
+GI.export_struct_exprs!(ns,path, "gtk4", struct_skiplist, [:BitsetIter,:BuildableParser]; doc_xml = d, object_skiplist = object_skiplist, constructor_skiplist = constructor_skiplist, output_boxed_cache_init = false, output_boxed_types_def = false, output_object_cache_define = false, output_object_cache_init = false, object_constructor_skiplist = obj_constructor_skiplist, doc_skiplist = [:Builder, :Notebook, :Grid, :Stack, :StackSwitcher, :SpinButton, :StackSidebar, :Image, :Picture, :ProgressBar, :Spinner], exclude_deprecated = false)
 
 ## object methods
 skiplist=[:create_closure,:activate_cell,:event,:start_editing,:filter_keypress,:append_node,:im_context_filter_keypress,:get_backlog,:get,:get_default,:get_for_display,:get_current_event_state,:get_axes,:append_fill,:append_stroke,:push_fill,:push_stroke]
diff --git a/src/buttons.jl b/src/buttons.jl
@@ -53,6 +53,11 @@ end
 
 ## GtkSwitch
 
+"""
+    GtkSwitch(active = false; kwargs...)
+
+Create a `GtkSwitch` widget set to the on position if `active` is `true`.
+"""
 function GtkSwitch(active::Bool; kwargs...)
     b = GtkSwitch(; kwargs...)
     G_.set_active(b, active)
diff --git a/src/displays.jl b/src/displays.jl
@@ -23,11 +23,46 @@ end
 
 # GtkImage (for fixed-size images, such as icons)
 
+@doc """
+    GtkImage(; kwargs...)
+    GtkImage(image::GdkPixbuf; kwargs...)
+    GtkImage(image::GdkPaintable; kwargs...)
+    GtkImage(image::GIcon; kwargs...)
+
+Create a `GtkImage` widget, which displays an image as an icon. If an `image`
+is provided it will be displayed. Keyword arguments allow you to set GObject
+properties.
+
+    GtkImage(filename::AbstractString; kwargs...)
+
+Try to load an image from a file and create a `GtkImage` displaying it.
+
+See also the [GTK docs](https://docs.gtk.org/gtk4/class.Picture.html).
+""" GtkImage
+
 GtkImage(::Nothing; kwargs...) = error("Ambiguous argument for constructor, please directly call one of the constructors in G_.")
 empty!(img::GtkImage) = (G_.clear(img); img)
 
 # GtkPicture (for displaying an image at its natural size)
 
+@doc """
+    GtkPicture(; kwargs...)
+    GtkPicture(image::GdkPixbuf; kwargs...)
+    GtkPicture(image::GdkPaintable; kwargs...)
+
+Create a `GtkPicture` widget, which displays an image at its natural size. If
+an `image` is provided it will be displayed. Keyword arguments allow you to
+set GObject properties.
+
+    GtkPicture(filename::AbstractString; kwargs...)
+    GtkPicture(file::GFile; kwargs...)
+
+Try to load an image from a file and create a `GtkPicture` displaying it.
+
+See also the [GTK docs](https://docs.gtk.org/gtk4/class.Picture.html).
+""" GtkPicture
+
+
 GtkPicture(::Nothing; kwargs...) = error("Ambiguous argument for constructor, please directly call one of the constructors in G_.")
 
 GtkVideo(::Nothing; kwargs...) = error("Ambiguous argument for constructor, please directly call one of the constructors in G_.")
@@ -36,10 +71,33 @@ GtkVideo(::Nothing; kwargs...) = error("Ambiguous argument for constructor, plea
 
 ## GtkProgressBar
 
+@doc """
+    GtkProgressBar(; kwargs...)
+
+Create a `GtkProgressBar`, which shows a progress bar and optionally a text
+label. Keyword arguments allow you to set GObject properties.
+
+The method or property `fraction` can be used to set or get the fraction of
+the operation that is complete (it must be between 0 and 1).
+
+See also the [GTK docs](https://docs.gtk.org/gtk4/class.ProgressBar.html).
+""" GtkProgressBar
+
 pulse(progress::GtkProgressBar) = G_.pulse(progress)
 
 ## GtkSpinner
 
+@doc """
+    GtkSpinner(; kwargs...)
+
+Create a `GtkSpinner`, which optionally shows a spinning icon to indicate to
+the user that some operation is running. The state of the widget can be
+controlled through the property "spinning" or using the methods `start` and
+`stop`. Keyword arguments allow you to set GObject properties.
+
+See also the [GTK docs](https://docs.gtk.org/gtk4/class.Spinner.html).
+""" GtkSpinner
+
 """
     start(spinner::GtkSpinner)
 
diff --git a/src/gen/gdk4_methods b/src/gen/gdk4_methods
@@ -2129,9 +2129,8 @@ begin
         ret = ccall(("gdk_memory_texture_builder_set_bytes", libgtk4), Nothing, (Ptr{GObject}, Ptr{GBytes}), instance, _bytes_maybe)
         nothing
     end
-    function set_color_state(instance::GdkMemoryTextureBuilder, _color_state::Maybe(GdkColorState))
-        _color_state_maybe = nothing_to_null(_color_state)
-        ret = ccall(("gdk_memory_texture_builder_set_color_state", libgtk4), Nothing, (Ptr{GObject}, Ptr{GdkColorState}), instance, _color_state_maybe)
+    function set_color_state(instance::GdkMemoryTextureBuilder, _color_state::GdkColorState)
+        ret = ccall(("gdk_memory_texture_builder_set_color_state", libgtk4), Nothing, (Ptr{GObject}, Ptr{GdkColorState}), instance, _color_state)
         nothing
     end
     function set_format(instance::GdkMemoryTextureBuilder, _format)
diff --git a/src/gen/glib_consts b/src/gen/glib_consts
@@ -79,7 +79,7 @@ const MAXUINT16 = 0xffff
 const MAXUINT32 = 0xffffffff
 const MAXUINT64 = 0xffffffffffffffff
 const MAXUINT8 = 0xff
-const MICRO_VERSION = 2
+const MICRO_VERSION = 3
 const MININT16 = -32768
 const MININT32 = -2147483648
 const MININT64 = -9223372036854775808
diff --git a/src/gen/gtk4_consts b/src/gen/gtk4_consts
@@ -34,18 +34,18 @@ const ACCESSIBLE_ATTRIBUTE_VARIANT_TITLE_CAPS = "title-caps"
 const ACCESSIBLE_ATTRIBUTE_VARIANT_UNICASE = "unicase"
 const ACCESSIBLE_ATTRIBUTE_WEIGHT = "weight"
 const ACCESSIBLE_VALUE_UNDEFINED = -1
-const BINARY_AGE = 1805
+const BINARY_AGE = 1806
 const IM_MODULE_EXTENSION_POINT_NAME = "gtk-im-module"
 const INPUT_ERROR = -1
-const INTERFACE_AGE = 5
+const INTERFACE_AGE = 6
 const INVALID_LIST_POSITION = 0xffffffff
 const LEVEL_BAR_OFFSET_FULL = "full"
 const LEVEL_BAR_OFFSET_HIGH = "high"
 const LEVEL_BAR_OFFSET_LOW = "low"
 const MAJOR_VERSION = 4
 const MAX_COMPOSE_LEN = 7
 const MEDIA_FILE_EXTENSION_POINT_NAME = "gtk-media-file"
-const MICRO_VERSION = 5
+const MICRO_VERSION = 6
 const MINOR_VERSION = 18
 const PAPER_NAME_A3 = "iso_a3"
 const PAPER_NAME_A4 = "iso_a4"
diff --git a/src/gen/gtk4_structs b/src/gen/gtk4_structs
@@ -6947,7 +6947,6 @@ begin
     @doc "See the [GTK docs](https://docs.gtk.org/gtk4/class.GestureSwipe.html)." GtkGestureSwipe
     @doc "See the [GTK docs](https://docs.gtk.org/gtk4/class.GestureZoom.html)." GtkGestureZoom
     @doc "See the [GTK docs](https://docs.gtk.org/gtk4/class.GraphicsOffload.html)." GtkGraphicsOffload
-    @doc "See the [GTK docs](https://docs.gtk.org/gtk4/class.Grid.html)." GtkGrid
     @doc "See the [GTK docs](https://docs.gtk.org/gtk4/class.GridLayout.html)." GtkGridLayout
     @doc "See the [GTK docs](https://docs.gtk.org/gtk4/class.GridLayoutChild.html)." GtkGridLayoutChild
     @doc "See the [GTK docs](https://docs.gtk.org/gtk4/class.GridView.html)." GtkGridView
@@ -6958,7 +6957,6 @@ begin
     @doc "See the [GTK docs](https://docs.gtk.org/gtk4/class.IconPaintable.html)." GtkIconPaintable
     @doc "See the [GTK docs](https://docs.gtk.org/gtk4/class.IconTheme.html)." GtkIconTheme
     @doc "See the [GTK docs](https://docs.gtk.org/gtk4/class.IconView.html)." GtkIconView
-    @doc "See the [GTK docs](https://docs.gtk.org/gtk4/class.Image.html)." GtkImage
     @doc "See the [GTK docs](https://docs.gtk.org/gtk4/class.InfoBar.html)." GtkInfoBar
     @doc "See the [GTK docs](https://docs.gtk.org/gtk4/class.Inscription.html)." GtkInscription
     @doc "See the [GTK docs](https://docs.gtk.org/gtk4/class.KeyvalTrigger.html)." GtkKeyvalTrigger
@@ -6992,7 +6990,6 @@ begin
     @doc "See the [GTK docs](https://docs.gtk.org/gtk4/class.NativeDialog.html)." GtkNativeDialog
     @doc "See the [GTK docs](https://docs.gtk.org/gtk4/class.NeverTrigger.html)." GtkNeverTrigger
     @doc "See the [GTK docs](https://docs.gtk.org/gtk4/class.NoSelection.html)." GtkNoSelection
-    @doc "See the [GTK docs](https://docs.gtk.org/gtk4/class.Notebook.html)." GtkNotebook
     @doc "See the [GTK docs](https://docs.gtk.org/gtk4/class.NotebookPage.html)." GtkNotebookPage
     @doc "See the [GTK docs](https://docs.gtk.org/gtk4/class.NothingAction.html)." GtkNothingAction
     @doc "See the [GTK docs](https://docs.gtk.org/gtk4/class.NumericSorter.html)." GtkNumericSorter
@@ -7005,7 +7002,6 @@ begin
     @doc "See the [GTK docs](https://docs.gtk.org/gtk4/class.Paned.html)." GtkPaned
     @doc "See the [GTK docs](https://docs.gtk.org/gtk4/class.PasswordEntry.html)." GtkPasswordEntry
     @doc "See the [GTK docs](https://docs.gtk.org/gtk4/class.PasswordEntryBuffer.html)." GtkPasswordEntryBuffer
-    @doc "See the [GTK docs](https://docs.gtk.org/gtk4/class.Picture.html)." GtkPicture
     @doc "See the [GTK docs](https://docs.gtk.org/gtk4/class.Popover.html)." GtkPopover
     @doc "See the [GTK docs](https://docs.gtk.org/gtk4/class.PopoverMenu.html)." GtkPopoverMenu
     @doc "See the [GTK docs](https://docs.gtk.org/gtk4/class.PopoverMenuBar.html)." GtkPopoverMenuBar
@@ -7015,7 +7011,6 @@ begin
     @doc "See the [GTK docs](https://docs.gtk.org/gtk4/class.PrintOperation.html)." GtkPrintOperation
     @doc "See the [GTK docs](https://docs.gtk.org/gtk4/class.PrintSettings.html)." GtkPrintSettings
     @doc "See the [GTK docs](https://docs.gtk.org/gtk4/class.Printer.html)." GtkPrinter
-    @doc "See the [GTK docs](https://docs.gtk.org/gtk4/class.ProgressBar.html)." GtkProgressBar
     @doc "See the [GTK docs](https://docs.gtk.org/gtk4/class.PropertyExpression.html)." GtkPropertyExpression
     @doc "See the [GTK docs](https://docs.gtk.org/gtk4/class.Range.html)." GtkRange
     @doc "See the [GTK docs](https://docs.gtk.org/gtk4/class.RecentManager.html)." GtkRecentManager
@@ -7046,12 +7041,7 @@ begin
     @doc "See the [GTK docs](https://docs.gtk.org/gtk4/class.Snapshot.html)." GtkSnapshot
     @doc "See the [GTK docs](https://docs.gtk.org/gtk4/class.SortListModel.html)." GtkSortListModel
     @doc "See the [GTK docs](https://docs.gtk.org/gtk4/class.Sorter.html)." GtkSorter
-    @doc "See the [GTK docs](https://docs.gtk.org/gtk4/class.SpinButton.html)." GtkSpinButton
-    @doc "See the [GTK docs](https://docs.gtk.org/gtk4/class.Spinner.html)." GtkSpinner
-    @doc "See the [GTK docs](https://docs.gtk.org/gtk4/class.Stack.html)." GtkStack
     @doc "See the [GTK docs](https://docs.gtk.org/gtk4/class.StackPage.html)." GtkStackPage
-    @doc "See the [GTK docs](https://docs.gtk.org/gtk4/class.StackSidebar.html)." GtkStackSidebar
-    @doc "See the [GTK docs](https://docs.gtk.org/gtk4/class.StackSwitcher.html)." GtkStackSwitcher
     @doc "See the [GTK docs](https://docs.gtk.org/gtk4/class.Statusbar.html)." GtkStatusbar
     @doc "See the [GTK docs](https://docs.gtk.org/gtk4/class.StringFilter.html)." GtkStringFilter
     @doc "See the [GTK docs](https://docs.gtk.org/gtk4/class.StringList.html)." GtkStringList
diff --git a/src/gen/pango_consts b/src/gen/pango_consts
@@ -8,9 +8,9 @@ const GLYPH_INVALID_INPUT = 0xffffffff
 const GLYPH_UNKNOWN_FLAG = 0x10000000
 const SCALE = 1024
 const VERSION_MAJOR = 1
-const VERSION_MICRO = 3
+const VERSION_MICRO = 4
 const VERSION_MINOR = 56
-const VERSION_STRING = "1.56.3"
+const VERSION_STRING = "1.56.4"
 @cenum(Alignment::Int32, Alignment_LEFT = 0, Alignment_CENTER = 1, Alignment_RIGHT = 2)
 (GLib.g_type(::Type{T}) where T <: Alignment) = ccall(("pango_alignment_get_type", libpango), GType, ())
 @cenum(AttrType::Int32, AttrType_INVALID = 0, AttrType_LANGUAGE = 1, AttrType_FAMILY = 2, AttrType_STYLE = 3, AttrType_WEIGHT = 4, AttrType_VARIANT = 5, AttrType_STRETCH = 6, AttrType_SIZE = 7, AttrType_FONT_DESC = 8, AttrType_FOREGROUND = 9, AttrType_BACKGROUND = 10, AttrType_UNDERLINE = 11, AttrType_STRIKETHROUGH = 12, AttrType_RISE = 13, AttrType_SHAPE = 14, AttrType_SCALE = 15, AttrType_FALLBACK = 16, AttrType_LETTER_SPACING = 17, AttrType_UNDERLINE_COLOR = 18, AttrType_STRIKETHROUGH_COLOR = 19, AttrType_ABSOLUTE_SIZE = 20, AttrType_GRAVITY = 21, AttrType_GRAVITY_HINT = 22, AttrType_FONT_FEATURES = 23, AttrType_FOREGROUND_ALPHA = 24, AttrType_BACKGROUND_ALPHA = 25, AttrType_ALLOW_BREAKS = 26, AttrType_SHOW = 27, AttrType_INSERT_HYPHENS = 28, AttrType_OVERLINE = 29, AttrType_OVERLINE_COLOR = 30, AttrType_LINE_HEIGHT = 31, AttrType_ABSOLUTE_LINE_HEIGHT = 32, AttrType_TEXT_TRANSFORM = 33, AttrType_WORD = 34, AttrType_SENTENCE = 35, AttrType_BASELINE_SHIFT = 36, AttrType_FONT_SCALE = 37)
diff --git a/src/gen/pango_functions b/src/gen/pango_functions
@@ -221,11 +221,17 @@ begin
         _attrs = collect(unsafe_wrap(Vector{_PangoLogAttr}, _attrs, m_attrs_len[]))
         _attrs
     end
-    function extents_to_pixels(_inclusive::Maybe(PangoRectangleLike), _nearest::Maybe(PangoRectangleLike))
-        _inclusive_maybe = nothing_to_null(_inclusive)
-        _nearest_maybe = nothing_to_null(_nearest)
-        ret = ccall(("pango_extents_to_pixels", libpango), Nothing, (Ptr{_PangoRectangle}, Ptr{_PangoRectangle}), _inclusive_maybe, _nearest_maybe)
-        nothing
+    function extents_to_pixels(_inclusive::_PangoRectangle, _nearest::_PangoRectangle)
+        m_inclusive = Ref{_PangoRectangle}()
+        m_inclusive[] = Base.cconvert(_PangoRectangle, _inclusive)
+        m_nearest = Ref{_PangoRectangle}()
+        m_nearest[] = Base.cconvert(_PangoRectangle, _nearest)
+        ret = ccall(("pango_extents_to_pixels", libpango), Nothing, (Ptr{_PangoRectangle}, Ptr{_PangoRectangle}), m_inclusive, m_nearest)
+        _inclusive = m_inclusive[]
+        _inclusive = convert(_PangoRectangle, _inclusive)
+        _nearest = m_nearest[]
+        _nearest = convert(_PangoRectangle, _nearest)
+        (_inclusive, _nearest)
     end
     function find_base_dir(_text::Union{AbstractString, Symbol}, _length::Integer)
         ret = ccall(("pango_find_base_dir", libpango), UInt32, (Cstring, Int32), _text, _length)
diff --git a/src/gen/pango_methods b/src/gen/pango_methods
@@ -1124,7 +1124,7 @@ begin
     end
     function get_face(instance::PangoFont)
         ret = ccall(("pango_font_get_face", libpango), Ptr{GObject}, (Ptr{GObject},), instance)
-        ret2 = convert(PangoFontFace, ret, false)
+        ret2 = convert_if_not_null(PangoFontFace, ret, false)
         ret2
     end
     function get_font_map(instance::PangoFont)
diff --git a/src/input.jl b/src/input.jl
@@ -6,6 +6,11 @@ pulse(progress::GtkEntry) = G_.progress_pulse(progress)
 pulse_step(progress::GtkEntry, frac) = G_.set_progress_pulse_step(progress, frac)
 pulse_step(progress::GtkEntry) = G_.get_progress_pulse_step(progress)
 
+"""
+    GtkEntryBuffer(initial_text = nothing)
+
+Create an object that holds the text shown in a `GtkEntry`.
+"""
 function GtkEntryBuffer(initial_text = nothing)
     G_.EntryBuffer_new(initial_text, -1)
 end
@@ -78,7 +83,32 @@ function configure!(adj::GtkAdjustment; value = nothing, lower = nothing, upper
 end
 
 ## GtkSpinButton
+@doc """
+    GtkSpinButton(min::Real, max::Real, step::Real; kwargs...)
+
+Create a `GtkSpinButton` widget, which shows an entry and buttons that
+increment and decrement the number shown in the entry. Minimum (`min`) and
+maximum (`max`) arguments restrict the range of allowable values, while the
+`step` argument controls the increment when the widget's buttons are used.
+Keyword arguments allow you to set GObject properties.
+
+    GtkSpinButton(adjustment::GtkAdjustment, climb_rate::Real, digits::Integer; kwargs...)
 
+Create a `GtkSpinButton` widget using an `adjustment` to set the range and step
+size. Additional arguments set widget properties: `climb_rate` controls the
+rate of acceleration when the widget's buttons are held down, while `digits`
+controls the number of decimal places displayed.
+
+See also [`GtkAdjustment`](@ref)
+and the [GTK docs](https://docs.gtk.org/gtk4/class.SpinButton.html).
+""" GtkSpinButton
+
+"""
+    GtkSpinButton(scale::AbstractRange; kwargs...)
+
+Create a `GtkSpinButton` with minimum and maximum allowed values and the
+default step size corresponding to `scale`.
+"""
 GtkSpinButton(scale::AbstractRange; kwargs...) = GtkSpinButton(minimum(scale), maximum(scale), step(scale); kwargs...)
 
 """
diff --git a/src/layout.jl b/src/layout.jl
