diff options
author | Matthias Clasen <mclasen@redhat.com> | 2021-02-26 09:32:18 -0500 |
---|---|---|
committer | Emmanuele Bassi <ebassi@gnome.org> | 2021-03-11 16:37:33 +0000 |
commit | 5950bcd7541538daad859a107434cf5e955501df (patch) | |
tree | f33e1db1c4cbadb588614e8c3f444b1ff5b57cfc /gtk/gtkframe.c | |
parent | 067b43fb5bb3baffd07904ab7d0c09903f340eef (diff) | |
download | gtk+-5950bcd7541538daad859a107434cf5e955501df.tar.gz |
frame: Convert docs
Convert link syntax, add an example image, add property
annotations.
Diffstat (limited to 'gtk/gtkframe.c')
-rw-r--r-- | gtk/gtkframe.c | 147 |
1 files changed, 86 insertions, 61 deletions
diff --git a/gtk/gtkframe.c b/gtk/gtkframe.c index ebe0111c95..392fed5abf 100644 --- a/gtk/gtkframe.c +++ b/gtk/gtkframe.c @@ -34,27 +34,29 @@ #include "gtklabel.h" /** - * SECTION:gtkframe - * @Short_description: A widget with a decorative frame and optional label - * @Title: GtkFrame + * GtkFrame: * - * The frame widget is a widget that surrounds its child with a decorative - * frame and an optional label. If present, the label is drawn inside - * the top edge of the frame. The horizontal position of the label can - * be controlled with gtk_frame_set_label_align(). + * `GtkFrame` is a widget that surrounds its child with a decorative + * frame and an optional label. * - * GtkFrame clips its child. You can use this to add rounded corners to - * widgets, but be aware that it also cuts off shadows. + * ![An example GtkFrame](frame.png) + * + * If present, the label is drawn inside the top edge of the frame. + * The horizontal position of the label can be controlled with + * [method@Gtk.Frame.set_label_align]. + * + * `GtkFrame` clips its child. You can use this to add rounded corners + * to widgets, but be aware that it also cuts off shadows. * * # GtkFrame as GtkBuildable * - * The GtkFrame implementation of the GtkBuildable interface supports + * The `GtkFrame` implementation of the `GtkBuildable` interface supports * placing a child in the label position by specifying “label” as the * “type” attribute of a <child> element. A normal content child can * be specified without specifying a <child> type attribute. * * An example of a UI definition fragment with GtkFrame: - * |[ + * ```xml * <object class="GtkFrame"> * <child type="label"> * <object class="GtkLabel" id="frame_label"/> @@ -63,7 +65,7 @@ * <object class="GtkEntry" id="frame_content"/> * </child> * </object> - * ]| + * ``` * * # CSS nodes * @@ -73,7 +75,7 @@ * ╰── <child> * ]| * - * GtkFrame has a main CSS node with name “frame”, which is used to draw the + * `GtkFrame` has a main CSS node with name “frame”, which is used to draw the * visible border. You can set the appearance of the border using CSS properties * like “border-style” on this node. */ @@ -158,6 +160,11 @@ gtk_frame_class_init (GtkFrameClass *class) class->compute_child_allocation = gtk_frame_real_compute_child_allocation; + /** + * GtkFrame:label: (attributes org.gtk.Property.get=gtk_frame_get_label org.gtk.Property.set=gtk_frame_set_label) + * + * Text of the frame's label. + */ frame_props[PROP_LABEL] = g_param_spec_string ("label", P_("Label"), @@ -165,6 +172,11 @@ gtk_frame_class_init (GtkFrameClass *class) NULL, GTK_PARAM_READWRITE|G_PARAM_EXPLICIT_NOTIFY); + /** + * GtkFrame:label-xalign: (attributes org.gtk.Property.get=gtk_frame_get_label_align org.gtk.Property.set=gtk_frame_set_label_align) + * + * The horizontal alignment of the label. + */ frame_props[PROP_LABEL_XALIGN] = g_param_spec_float ("label-xalign", P_("Label xalign"), @@ -173,6 +185,11 @@ gtk_frame_class_init (GtkFrameClass *class) 0.0, GTK_PARAM_READWRITE|G_PARAM_EXPLICIT_NOTIFY); + /** + * GtkFrame:label-widget: (attributes org.gtk.Property.get=gtk_frame_get_label_widget org.gtk.Property.set=gtk_frame_set_label_widget) + * + * Widget to display in place of the usual frame label. + */ frame_props[PROP_LABEL_WIDGET] = g_param_spec_object ("label-widget", P_("Label widget"), @@ -180,6 +197,11 @@ gtk_frame_class_init (GtkFrameClass *class) GTK_TYPE_WIDGET, GTK_PARAM_READWRITE); + /** + * GtkFrame:child: (attributes org.gtk.Property.get=gtk_frame_get_child org.gtk.Property.set=gtk_frame_set_child) + * + * The child widget. + */ frame_props[PROP_CHILD] = g_param_spec_object ("child", P_("Child"), @@ -302,12 +324,13 @@ gtk_frame_get_property (GObject *object, /** * gtk_frame_new: * @label: (allow-none): the text to use as the label of the frame - * - * Creates a new #GtkFrame, with optional label @label. + * + * Creates a new `GtkFrame`, with optional label @label. + * * If @label is %NULL, the label is omitted. - * - * Returns: a new #GtkFrame widget - **/ + * + * Returns: a new `GtkFrame` widget + */ GtkWidget* gtk_frame_new (const char *label) { @@ -315,13 +338,13 @@ gtk_frame_new (const char *label) } /** - * gtk_frame_set_label: - * @frame: a #GtkFrame + * gtk_frame_set_label: (attributes org.gtk.Method.set_property=label) + * @frame: a `GtkFrame` * @label: (allow-none): the text to use as the label of the frame * - * Removes the current #GtkFrame:label-widget. If @label is not %NULL, creates a - * new #GtkLabel with that text and adds it as the #GtkFrame:label-widget. - **/ + * Creates a new `GtkLabel` with the @label and sets it as the frame's + * label widget. + */ void gtk_frame_set_label (GtkFrame *frame, const char *label) @@ -335,19 +358,18 @@ gtk_frame_set_label (GtkFrame *frame, } /** - * gtk_frame_get_label: - * @frame: a #GtkFrame - * - * If the frame’s label widget is a #GtkLabel, returns the - * text in the label widget. (The frame will have a #GtkLabel - * for the label widget if a non-%NULL argument was passed - * to gtk_frame_new().) - * + * gtk_frame_get_label: (attributes org.gtk.Method.get_property=label) + * @frame: a `GtkFrame` + * + * Returns the frame labels text. + * + * If the frame's label widget is not a `GtkLabel`, %NULL + * is returned. + * * Returns: (nullable): the text in the label, or %NULL if there - * was no label widget or the label widget was not - * a #GtkLabel. This string is owned by GTK and - * must not be modified or freed. - **/ + * was no label widget or the label widget was not a `GtkLabel`. + * This string is owned by GTK and must not be modified or freed. + */ const char * gtk_frame_get_label (GtkFrame *frame) { @@ -379,13 +401,15 @@ update_accessible_relation (GtkFrame *frame) } /** - * gtk_frame_set_label_widget: - * @frame: a #GtkFrame + * gtk_frame_set_label_widget: (attributes org.gtk.Method.get_property=label-widget) + * @frame: a `GtkFrame` * @label_widget: (nullable): the new label widget - * - * Sets the #GtkFrame:label-widget for the frame. This is the widget that - * will appear embedded in the top edge of the frame as a title. - **/ + * + * Sets the label widget for the frame. + * + * This is the widget that will appear embedded in the top edge + * of the frame as a title. + */ void gtk_frame_set_label_widget (GtkFrame *frame, GtkWidget *label_widget) @@ -419,15 +443,14 @@ gtk_frame_set_label_widget (GtkFrame *frame, } /** - * gtk_frame_get_label_widget: - * @frame: a #GtkFrame + * gtk_frame_get_label_widget: (attributes org.gtk.Method.get_property=label-widget) + * @frame: a `GtkFrame` * - * Retrieves the label widget for the frame. See - * gtk_frame_set_label_widget(). + * Retrieves the label widget for the frame. * * Returns: (nullable) (transfer none): the label widget, or %NULL if * there is none. - **/ + */ GtkWidget * gtk_frame_get_label_widget (GtkFrame *frame) { @@ -439,15 +462,16 @@ gtk_frame_get_label_widget (GtkFrame *frame) } /** - * gtk_frame_set_label_align: - * @frame: a #GtkFrame + * gtk_frame_set_label_align: (attributes org.gtk.Method.set_property=label-xalign) + * @frame: a `GtkFrame` * @xalign: The position of the label along the top edge * of the widget. A value of 0.0 represents left alignment; * 1.0 represents right alignment. * - * Sets the X alignment of the frame widget’s label. The - * default value for a newly created frame is 0.0. - **/ + * Sets the X alignment of the frame widget’s label. + * + * The default value for a newly created frame is 0.0. + */ void gtk_frame_set_label_align (GtkFrame *frame, float xalign) @@ -466,12 +490,13 @@ gtk_frame_set_label_align (GtkFrame *frame, } /** - * gtk_frame_get_label_align: - * @frame: a #GtkFrame - * - * Retrieves the X alignment of the frame’s label. See - * gtk_frame_set_label_align(). - **/ + * gtk_frame_get_label_align: (attributes org.gtk.Method.get_property=label-xalign) + * @frame: a `GtkFrame` + * + * Retrieves the X alignment of the frame’s label. + * + * Returns: the frames X alignment + */ float gtk_frame_get_label_align (GtkFrame *frame) { @@ -641,8 +666,8 @@ gtk_frame_get_request_mode (GtkWidget *widget) } /** - * gtk_frame_set_child: - * @frame: a #GtkFrame + * gtk_frame_set_child: (attributes org.gtk.Method.set_property=child) + * @frame: a `GtkFrame` * @child: (allow-none): the child widget * * Sets the child widget of @frame. @@ -673,8 +698,8 @@ gtk_frame_set_child (GtkFrame *frame, } /** - * gtk_frame_get_child: - * @frame: a #GtkFrame + * gtk_frame_get_child: (attributes org.gtk.Method.get_property=child) + * @frame: a `GtkFrame` * * Gets the child widget of @frame. * |