:right-sidebar: True

Frame
===================================================================

.. currentmodule:: gi.repository.Gtk





.. class:: Frame(**properties: ~typing.Any)
   :no-contents-entry:


Superclasses: :class:`~gi.repository.Gtk.Widget`, :class:`~gi.repository.GObject.InitiallyUnowned`, :class:`~gi.repository.GObject.Object`



Implemented Interfaces: :class:`~gi.repository.Gtk.Accessible`, :class:`~gi.repository.Gtk.Buildable`, :class:`~gi.repository.Gtk.ConstraintTarget`



``GtkFrame`` is a widget that surrounds its child with a decorative
frame and an optional label.


.. image:: https://docs.gtk.org/gtk4/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
:obj:`~gi.repository.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
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:

.. code-block::
   :dedent:

   <object class="GtkFrame">
     <child type="label">
       <object class="GtkLabel" id="frame_label"/>
     </child>
     <child>
       <object class="GtkEntry" id="frame_content"/>
     </child>
   </object>


CSS nodes
---------


.. code-block::
   :dedent:

   frame
   ├── <label widget>
   ╰── <child>


``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.

Accessibility
-------------

``GtkFrame`` uses the ``GTK_ACCESSIBLE_ROLE_GROUP`` role.



Constructors
------------

.. rst-class:: interim-class

.. class:: Frame
   :no-index:


   .. classmethod:: new(label: str | None = None) -> ~gi.repository.Gtk.Widget

      Creates a new ``GtkFrame``, with optional label ``label``.

      If ``label`` is :const:`None`, the label is omitted.







      :param label: the text to use as the label of the frame









Methods
-------

.. rst-class:: interim-class

.. class:: Frame
   :no-index:


   .. method:: get_child() -> ~gi.repository.Gtk.Widget | None

      Gets the child widget of ``frame``.










   .. method:: get_label() -> str | None

      Returns the frame labels text.

      If the frame's label widget is not a ``GtkLabel``, :const:`None`
      is returned.










   .. method:: get_label_align() -> float

      Retrieves the X alignment of the frame’s label.










   .. method:: get_label_widget() -> ~gi.repository.Gtk.Widget | None

      Retrieves the label widget for the frame.










   .. method:: set_child(child: ~gi.repository.Gtk.Widget | None = None) -> None

      Sets the child widget of ``frame``.







      :param child: the child widget





   .. method:: set_label(label: str | None = None) -> None

      Creates a new ``GtkLabel`` with the ``label`` and sets it as the frame's
      label widget.







      :param label: the text to use as the label of the frame





   .. method:: set_label_align(xalign: float) -> None

      Sets the X alignment of the frame widget’s label.

      The default value for a newly created frame is 0.0.







      :param 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.





   .. method:: set_label_widget(label_widget: ~gi.repository.Gtk.Widget | None = None) -> None

      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.







      :param label_widget: the new label widget









Properties
----------

.. rst-class:: interim-class

.. class:: Frame
   :no-index:
   

   .. attribute:: props.child
      :type: ~gi.repository.Gtk.Widget

      The child widget.







   .. attribute:: props.label
      :type: str

      Text of the frame's label.







   .. attribute:: props.label_widget
      :type: ~gi.repository.Gtk.Widget

      Widget to display in place of the usual frame label.







   .. attribute:: props.label_xalign
      :type: float

      The horizontal alignment of the label.













Virtual Methods
---------------

.. rst-class:: interim-class

.. class:: Frame
   :no-index:
   

   .. method:: do_compute_child_allocation(allocation: ~gi.repository.Gdk.Rectangle) -> None

      






      :param allocation: 








Fields
------

.. rst-class:: interim-class

.. class:: Frame
   :no-index:
   

   .. attribute:: parent_instance