Struct gtk::Container [−][src]
pub struct Container(_);
Expand description
A GTK+ user interface is constructed by nesting widgets inside widgets.
Container widgets are the inner nodes in the resulting tree of widgets:
they contain other widgets. So, for example, you might have a Window
containing a Frame containing a Label. If you wanted an image instead
of a textual label inside the frame, you might replace the Label widget
with a Image widget.
There are two major kinds of container widgets in GTK+. Both are subclasses of the abstract GtkContainer base class.
The first type of container widget has a single child widget and derives
from Bin. These containers are decorators, which
add some kind of functionality to the child. For example, a Button makes
its child into a clickable button; a Frame draws a frame around its child
and a Window places its child widget inside a top-level window.
The second type of container can have more than one child; its purpose is to
manage layout. This means that these containers assign
sizes and positions to their children. For example, a GtkHBox arranges its
children in a horizontal row, and a Grid arranges the widgets it contains
in a two-dimensional grid.
For implementations of Container the virtual method GtkContainerClass.forall()
is always required, since it’s used for drawing and other internal operations
on the children.
If the Container implementation expect to have non internal children
it’s needed to implement both GtkContainerClass.add() and GtkContainerClass.remove().
If the GtkContainer implementation has internal children, they should be added
with WidgetExt::set_parent() on init() and removed with WidgetExt::unparent()
in the GtkWidgetClass.destroy() implementation.
See more about implementing custom widgets at https://wiki.gnome.org/HowDoI/CustomWidgets
Height for width geometry management
GTK+ uses a height-for-width (and width-for-height) geometry management system. Height-for-width means that a widget can change how much vertical space it needs, depending on the amount of horizontal space that it is given (and similar for width-for-height).
There are some things to keep in mind when implementing container widgets
that make use of GTK+’s height for width geometry management system. First,
it’s important to note that a container must prioritize one of its
dimensions, that is to say that a widget or container can only have a
SizeRequestMode that is SizeRequestMode::HeightForWidth or
SizeRequestMode::WidthForHeight. However, every widget and container
must be able to respond to the APIs for both dimensions, i.e. even if a
widget has a request mode that is height-for-width, it is possible that
its parent will request its sizes using the width-for-height APIs.
To ensure that everything works properly, here are some guidelines to follow when implementing height-for-width (or width-for-height) containers.
Each request mode involves 2 virtual methods. Height-for-width apis run
through WidgetExt::preferred_width() and then through WidgetExt::preferred_height_for_width().
When handling requests in the opposite SizeRequestMode it is important that
every widget request at least enough space to display all of its content at all times.
When WidgetExt::preferred_height() is called on a container that is height-for-width,
the container must return the height for its minimum width. This is easily achieved by
simply calling the reverse apis implemented for itself as follows:
⚠️ The following code is in C ⚠️
static void
foo_container_get_preferred_height (GtkWidget *widget,
gint *min_height,
gint *nat_height)
{
if (i_am_in_height_for_width_mode)
{
gint min_width;
GTK_WIDGET_GET_CLASS (widget)->get_preferred_width (widget,
&min_width,
NULL);
GTK_WIDGET_GET_CLASS (widget)->get_preferred_height_for_width
(widget,
min_width,
min_height,
nat_height);
}
else
{
... many containers support both request modes, execute the
real width-for-height request here by returning the
collective heights of all widgets that are stacked
vertically (or whatever is appropriate for this container)
...
}
}
Similarly, when WidgetExt::preferred_width_for_height() is called for a container or widget
that is height-for-width, it then only needs to return the base minimum width like so:
⚠️ The following code is in C ⚠️
static void
foo_container_get_preferred_width_for_height (GtkWidget *widget,
gint for_height,
gint *min_width,
gint *nat_width)
{
if (i_am_in_height_for_width_mode)
{
GTK_WIDGET_GET_CLASS (widget)->get_preferred_width (widget,
min_width,
nat_width);
}
else
{
... execute the real width-for-height request here based on
the required width of the children collectively if the
container were to be allocated the said height ...
}
}
Height for width requests are generally implemented in terms of a virtual allocation
of widgets in the input orientation. Assuming an height-for-width request mode, a container
would implement the get_preferred_height_for_width() virtual function by first calling
WidgetExt::preferred_width() for each of its children.
For each potential group of children that are lined up horizontally, the values returned by
WidgetExt::preferred_width() should be collected in an array of GtkRequestedSize structures.
Any child spacing should be removed from the input for_width and then the collective size should be
allocated using the gtk_distribute_natural_allocation() convenience function.
The container will then move on to request the preferred height for each child by using
WidgetExt::preferred_height_for_width() and using the sizes stored in the GtkRequestedSize array.
To allocate a height-for-width container, it’s again important
to consider that a container must prioritize one dimension over the other. So if
a container is a height-for-width container it must first allocate all widgets horizontally
using a GtkRequestedSize array and gtk_distribute_natural_allocation() and then add any
extra space (if and where appropriate) for the widget to expand.
After adding all the expand space, the container assumes it was allocated sufficient
height to fit all of its content. At this time, the container must use the total horizontal sizes
of each widget to request the height-for-width of each of its children and store the requests in a
GtkRequestedSize array for any widgets that stack vertically (for tabular containers this can
be generalized into the heights and widths of rows and columns).
The vertical space must then again be distributed using gtk_distribute_natural_allocation()
while this time considering the allocated height of the widget minus any vertical spacing
that the container adds. Then vertical expand space should be added where appropriate and available
and the container should go on to actually allocating the child widgets.
See [GtkWidget’s geometry management section][geometry-management] to learn more about implementing height-for-width geometry management for widgets.
Child properties
GtkContainer introduces child properties.
These are object properties that are not specific
to either the container or the contained widget, but rather to their relation.
Typical examples of child properties are the position or pack-type of a widget
which is contained in a Box.
Use gtk_container_class_install_child_property() to install child properties
for a container class and gtk_container_class_find_child_property() or
gtk_container_class_list_child_properties() to get information about existing
child properties.
To set the value of a child property, use gtk_container_child_set_property(),
gtk_container_child_set() or gtk_container_child_set_valist().
To obtain the value of a child property, use
gtk_container_child_get_property(), gtk_container_child_get() or
gtk_container_child_get_valist(). To emit notification about child property
changes, use WidgetExt::child_notify().
GtkContainer as GtkBuildable
The GtkContainer implementation of the GtkBuildable interface supports
a <packing> element for children, which can contain multiple <property>
elements that specify child properties for the child.
Since 2.16, child properties can also be marked as translatable using the same “translatable”, “comments” and “context” attributes that are used for regular properties.
Since 3.16, containers can have a <focus-chain> element containing multiple
<widget> elements, one for each child that should be added to the focus
chain. The ”name” attribute gives the id of the widget.
An example of these properties in UI definitions:
<object class="GtkBox">
<child>
<object class="GtkEntry" id="entry1"/>
<packing>
<property name="pack-type">start</property>
</packing>
</child>
<child>
<object class="GtkEntry" id="entry2"/>
</child>
<focus-chain>
<widget name="entry1"/>
<widget name="entry2"/>
</focus-chain>
</object>
This is an Abstract Base Class, you cannot instantiate it.
Implements
ContainerExt, WidgetExt, glib::ObjectExt, BuildableExt, WidgetExtManual, BuildableExtManual
Trait Implementations
This method returns an ordering between self and other values if one exists. Read more
This method tests less than (for self and other) and is used by the < operator. Read more
This method tests less than or equal to (for self and other) and is used by the <=
operator. Read more
This method tests greater than (for self and other) and is used by the > operator. Read more
Returns the type identifier of Self.
Auto Trait Implementations
impl RefUnwindSafe for Containerimpl UnwindSafe for ContainerBlanket Implementations
Mutably borrows from an owned value. Read more
Upcasts an object to a superclass or interface T. Read more
Upcasts an object to a reference of its superclass or interface T. Read more
Tries to downcast to a subclass or interface implementor T. Read more
Tries to downcast to a reference of its subclass or interface implementor T. Read more
Tries to cast to an object of type T. This handles upcasting, downcasting
and casting between interface and interface implementors. All checks are performed at
runtime, while downcast and upcast will do many checks at compile-time already. Read more
Tries to cast to reference to an object of type T. This handles upcasting, downcasting
and casting between interface and interface implementors. All checks are performed at
runtime, while downcast and upcast will do many checks at compile-time already. Read more
Casts to T unconditionally. Read more
Casts to &T unconditionally. Read more
Returns true if the object is an instance of (can be cast to) T.
pub fn set_properties_from_value(
&self,
property_values: &[(&str, Value)]
) -> Result<(), BoolError>pub fn set_property<'a, N, V>(
&self,
property_name: N,
value: V
) -> Result<(), BoolError> where
V: ToValue,
N: Into<&'a str>, pub fn set_property_from_value<'a, N>(
&self,
property_name: N,
value: &Value
) -> Result<(), BoolError> where
N: Into<&'a str>, Safety Read more
Safety Read more
Safety Read more
Safety Read more
pub fn connect_notify<F>(&self, name: Option<&str>, f: F) -> SignalHandlerId where
F: 'static + Fn(&T, &ParamSpec) + Send + Sync, pub fn connect_notify_local<F>(
&self,
name: Option<&str>,
f: F
) -> SignalHandlerId where
F: 'static + Fn(&T, &ParamSpec), pub unsafe fn connect_notify_unsafe<F>(
&self,
name: Option<&str>,
f: F
) -> SignalHandlerId where
F: Fn(&T, &ParamSpec), pub fn has_property<'a, N>(&self, property_name: N, type_: Option<Type>) -> bool where
N: Into<&'a str>, pub fn find_property<'a, N>(&self, property_name: N) -> Option<ParamSpec> where
N: Into<&'a str>, pub fn connect<'a, N, F>(
&self,
signal_name: N,
after: bool,
callback: F
) -> Result<SignalHandlerId, BoolError> where
F: Fn(&[Value]) -> Option<Value> + Send + Sync + 'static,
N: Into<&'a str>, Same as connect but takes a SignalId instead of a signal name.
pub fn connect_local<'a, N, F>(
&self,
signal_name: N,
after: bool,
callback: F
) -> Result<SignalHandlerId, BoolError> where
F: Fn(&[Value]) -> Option<Value> + 'static,
N: Into<&'a str>, Same as connect_local but takes a SignalId instead of a signal name.
pub unsafe fn connect_unsafe<'a, N, F>(
&self,
signal_name: N,
after: bool,
callback: F
) -> Result<SignalHandlerId, BoolError> where
F: Fn(&[Value]) -> Option<Value>,
N: Into<&'a str>, Same as connect_unsafe but takes a SignalId instead of a signal name.
Emit signal by signal id.
Emit signal with details by signal id.
Emit signal by it’s name.
pub fn bind_property<'a, O, N, M>(
&'a self,
source_property: N,
target: &'a O,
target_property: M
) -> BindingBuilder<'a> where
O: ObjectType,
N: Into<&'a str>,
M: Into<&'a str>, Same as emit but takes Value for the arguments.
Same as emit_by_name but takes Value for the arguments.
Returns a SendValue clone of self.
impl<'a, T, C> FromValueOptional<'a> for T where
C: ValueTypeChecker<Error = ValueTypeMismatchOrNoneError>,
T: FromValue<'a, Checker = C>,