gtk4/auto/drawing_area.rs
1// This file was generated by gir (https://github.com/gtk-rs/gir)
2// from gir-files (https://github.com/gtk-rs/gir-files)
3// DO NOT EDIT
4
5use crate::{
6 ffi, Accessible, AccessibleRole, Align, Buildable, ConstraintTarget, LayoutManager, Overflow,
7 Widget,
8};
9use glib::{
10 object::ObjectType as _,
11 prelude::*,
12 signal::{connect_raw, SignalHandlerId},
13 translate::*,
14};
15use std::boxed::Box as Box_;
16
17glib::wrapper! {
18 /// Allows drawing with cairo.
19 ///
20 /// <picture>
21 /// <source srcset="drawingarea-dark.png" media="(prefers-color-scheme: dark)">
22 /// <img alt="An example GtkDrawingArea" src="drawingarea.png">
23 /// </picture>
24 ///
25 /// It’s essentially a blank widget; you can draw on it. After
26 /// creating a drawing area, the application may want to connect to:
27 ///
28 /// - The [`realize`][struct@crate::Widget#realize] signal to take any necessary actions
29 /// when the widget is instantiated on a particular display.
30 /// (Create GDK resources in response to this signal.)
31 ///
32 /// - The [`resize`][struct@crate::DrawingArea#resize] signal to take any necessary
33 /// actions when the widget changes size.
34 ///
35 /// - Call [`DrawingAreaExtManual::set_draw_func()`][crate::prelude::DrawingAreaExtManual::set_draw_func()] to handle redrawing the
36 /// contents of the widget.
37 ///
38 /// The following code portion demonstrates using a drawing
39 /// area to display a circle in the normal widget foreground
40 /// color.
41 ///
42 /// ## Simple GtkDrawingArea usage
43 ///
44 /// **⚠️ The following code is in c ⚠️**
45 ///
46 /// ```c
47 /// static void
48 /// draw_function (GtkDrawingArea *area,
49 /// cairo_t *cr,
50 /// int width,
51 /// int height,
52 /// gpointer data)
53 /// {
54 /// GdkRGBA color;
55 ///
56 /// cairo_arc (cr,
57 /// width / 2.0, height / 2.0,
58 /// MIN (width, height) / 2.0,
59 /// 0, 2 * G_PI);
60 ///
61 /// gtk_widget_get_color (GTK_WIDGET (area),
62 /// &color);
63 /// gdk_cairo_set_source_rgba (cr, &color);
64 ///
65 /// cairo_fill (cr);
66 /// }
67 ///
68 /// int
69 /// main (int argc, char **argv)
70 /// {
71 /// gtk_init ();
72 ///
73 /// GtkWidget *area = gtk_drawing_area_new ();
74 /// gtk_drawing_area_set_content_width (GTK_DRAWING_AREA (area), 100);
75 /// gtk_drawing_area_set_content_height (GTK_DRAWING_AREA (area), 100);
76 /// gtk_drawing_area_set_draw_func (GTK_DRAWING_AREA (area),
77 /// draw_function,
78 /// NULL, NULL);
79 /// return 0;
80 /// }
81 /// ```
82 ///
83 /// The draw function is normally called when a drawing area first comes
84 /// onscreen, or when it’s covered by another window and then uncovered.
85 /// You can also force a redraw by adding to the “damage region” of the
86 /// drawing area’s window using [`WidgetExt::queue_draw()`][crate::prelude::WidgetExt::queue_draw()].
87 /// This will cause the drawing area to call the draw function again.
88 ///
89 /// The available routines for drawing are documented in the
90 /// [Cairo documentation](https://www.cairographics.org/manual/); GDK
91 /// offers additional API to integrate with Cairo, like `cairo_set_source_rgba()`
92 /// or `cairo_set_source_pixbuf()`.
93 ///
94 /// To receive mouse events on a drawing area, you will need to use
95 /// event controllers. To receive keyboard events, you will need to set
96 /// the “can-focus” property on the drawing area, and you should probably
97 /// draw some user-visible indication that the drawing area is focused.
98 ///
99 /// If you need more complex control over your widget, you should consider
100 /// creating your own [`Widget`][crate::Widget] subclass.
101 ///
102 /// ## Properties
103 ///
104 ///
105 /// #### `content-height`
106 /// The content height.
107 ///
108 /// Readable | Writeable
109 ///
110 ///
111 /// #### `content-width`
112 /// The content width.
113 ///
114 /// Readable | Writeable
115 /// <details><summary><h4>Widget</h4></summary>
116 ///
117 ///
118 /// #### `can-focus`
119 /// Whether the widget or any of its descendents can accept
120 /// the input focus.
121 ///
122 /// This property is meant to be set by widget implementations,
123 /// typically in their instance init function.
124 ///
125 /// Readable | Writeable
126 ///
127 ///
128 /// #### `can-target`
129 /// Whether the widget can receive pointer events.
130 ///
131 /// Readable | Writeable
132 ///
133 ///
134 /// #### `css-classes`
135 /// A list of css classes applied to this widget.
136 ///
137 /// Readable | Writeable
138 ///
139 ///
140 /// #### `css-name`
141 /// The name of this widget in the CSS tree.
142 ///
143 /// This property is meant to be set by widget implementations,
144 /// typically in their instance init function.
145 ///
146 /// Readable | Writeable | Construct Only
147 ///
148 ///
149 /// #### `cursor`
150 /// The cursor used by @widget.
151 ///
152 /// Readable | Writeable
153 ///
154 ///
155 /// #### `focus-on-click`
156 /// Whether the widget should grab focus when it is clicked with the mouse.
157 ///
158 /// This property is only relevant for widgets that can take focus.
159 ///
160 /// Readable | Writeable
161 ///
162 ///
163 /// #### `focusable`
164 /// Whether this widget itself will accept the input focus.
165 ///
166 /// Readable | Writeable
167 ///
168 ///
169 /// #### `halign`
170 /// How to distribute horizontal space if widget gets extra space.
171 ///
172 /// Readable | Writeable
173 ///
174 ///
175 /// #### `has-default`
176 /// Whether the widget is the default widget.
177 ///
178 /// Readable
179 ///
180 ///
181 /// #### `has-focus`
182 /// Whether the widget has the input focus.
183 ///
184 /// Readable
185 ///
186 ///
187 /// #### `has-tooltip`
188 /// Enables or disables the emission of the [`query-tooltip`][struct@crate::Widget#query-tooltip]
189 /// signal on @widget.
190 ///
191 /// A true value indicates that @widget can have a tooltip, in this case
192 /// the widget will be queried using [`query-tooltip`][struct@crate::Widget#query-tooltip] to
193 /// determine whether it will provide a tooltip or not.
194 ///
195 /// Readable | Writeable
196 ///
197 ///
198 /// #### `height-request`
199 /// Overrides for height request of the widget.
200 ///
201 /// If this is -1, the natural request will be used.
202 ///
203 /// Readable | Writeable
204 ///
205 ///
206 /// #### `hexpand`
207 /// Whether to expand horizontally.
208 ///
209 /// Readable | Writeable
210 ///
211 ///
212 /// #### `hexpand-set`
213 /// Whether to use the `hexpand` property.
214 ///
215 /// Readable | Writeable
216 ///
217 ///
218 /// #### `layout-manager`
219 /// The [`LayoutManager`][crate::LayoutManager] instance to use to compute
220 /// the preferred size of the widget, and allocate its children.
221 ///
222 /// This property is meant to be set by widget implementations,
223 /// typically in their instance init function.
224 ///
225 /// Readable | Writeable
226 ///
227 ///
228 /// #### `limit-events`
229 /// Makes this widget act like a modal dialog, with respect to
230 /// event delivery.
231 ///
232 /// Global event controllers will not handle events with targets
233 /// inside the widget, unless they are set up to ignore propagation
234 /// limits. See [`EventControllerExt::set_propagation_limit()`][crate::prelude::EventControllerExt::set_propagation_limit()].
235 ///
236 /// Readable | Writeable
237 ///
238 ///
239 /// #### `margin-bottom`
240 /// Margin on bottom side of widget.
241 ///
242 /// This property adds margin outside of the widget's normal size
243 /// request, the margin will be added in addition to the size from
244 /// [`WidgetExt::set_size_request()`][crate::prelude::WidgetExt::set_size_request()] for example.
245 ///
246 /// Readable | Writeable
247 ///
248 ///
249 /// #### `margin-end`
250 /// Margin on end of widget, horizontally.
251 ///
252 /// This property supports left-to-right and right-to-left text
253 /// directions.
254 ///
255 /// This property adds margin outside of the widget's normal size
256 /// request, the margin will be added in addition to the size from
257 /// [`WidgetExt::set_size_request()`][crate::prelude::WidgetExt::set_size_request()] for example.
258 ///
259 /// Readable | Writeable
260 ///
261 ///
262 /// #### `margin-start`
263 /// Margin on start of widget, horizontally.
264 ///
265 /// This property supports left-to-right and right-to-left text
266 /// directions.
267 ///
268 /// This property adds margin outside of the widget's normal size
269 /// request, the margin will be added in addition to the size from
270 /// [`WidgetExt::set_size_request()`][crate::prelude::WidgetExt::set_size_request()] for example.
271 ///
272 /// Readable | Writeable
273 ///
274 ///
275 /// #### `margin-top`
276 /// Margin on top side of widget.
277 ///
278 /// This property adds margin outside of the widget's normal size
279 /// request, the margin will be added in addition to the size from
280 /// [`WidgetExt::set_size_request()`][crate::prelude::WidgetExt::set_size_request()] for example.
281 ///
282 /// Readable | Writeable
283 ///
284 ///
285 /// #### `name`
286 /// The name of the widget.
287 ///
288 /// Readable | Writeable
289 ///
290 ///
291 /// #### `opacity`
292 /// The requested opacity of the widget.
293 ///
294 /// Readable | Writeable
295 ///
296 ///
297 /// #### `overflow`
298 /// How content outside the widget's content area is treated.
299 ///
300 /// This property is meant to be set by widget implementations,
301 /// typically in their instance init function.
302 ///
303 /// Readable | Writeable
304 ///
305 ///
306 /// #### `parent`
307 /// The parent widget of this widget.
308 ///
309 /// Readable
310 ///
311 ///
312 /// #### `receives-default`
313 /// Whether the widget will receive the default action when it is focused.
314 ///
315 /// Readable | Writeable
316 ///
317 ///
318 /// #### `root`
319 /// The [`Root`][crate::Root] widget of the widget tree containing this widget.
320 ///
321 /// This will be `NULL` if the widget is not contained in a root widget.
322 ///
323 /// Readable
324 ///
325 ///
326 /// #### `scale-factor`
327 /// The scale factor of the widget.
328 ///
329 /// Readable
330 ///
331 ///
332 /// #### `sensitive`
333 /// Whether the widget responds to input.
334 ///
335 /// Readable | Writeable
336 ///
337 ///
338 /// #### `tooltip-markup`
339 /// Sets the text of tooltip to be the given string, which is marked up
340 /// with Pango markup.
341 ///
342 /// Also see [`Tooltip::set_markup()`][crate::Tooltip::set_markup()].
343 ///
344 /// This is a convenience property which will take care of getting the
345 /// tooltip shown if the given string is not `NULL`:
346 /// [`has-tooltip`][struct@crate::Widget#has-tooltip] will automatically be set to true
347 /// and there will be taken care of [`query-tooltip`][struct@crate::Widget#query-tooltip] in
348 /// the default signal handler.
349 ///
350 /// Note that if both [`tooltip-text`][struct@crate::Widget#tooltip-text] and
351 /// [`tooltip-markup`][struct@crate::Widget#tooltip-markup] are set, the last one wins.
352 ///
353 /// Readable | Writeable
354 ///
355 ///
356 /// #### `tooltip-text`
357 /// Sets the text of tooltip to be the given string.
358 ///
359 /// Also see [`Tooltip::set_text()`][crate::Tooltip::set_text()].
360 ///
361 /// This is a convenience property which will take care of getting the
362 /// tooltip shown if the given string is not `NULL`:
363 /// [`has-tooltip`][struct@crate::Widget#has-tooltip] will automatically be set to true
364 /// and there will be taken care of [`query-tooltip`][struct@crate::Widget#query-tooltip] in
365 /// the default signal handler.
366 ///
367 /// Note that if both [`tooltip-text`][struct@crate::Widget#tooltip-text] and
368 /// [`tooltip-markup`][struct@crate::Widget#tooltip-markup] are set, the last one wins.
369 ///
370 /// Readable | Writeable
371 ///
372 ///
373 /// #### `valign`
374 /// How to distribute vertical space if widget gets extra space.
375 ///
376 /// Readable | Writeable
377 ///
378 ///
379 /// #### `vexpand`
380 /// Whether to expand vertically.
381 ///
382 /// Readable | Writeable
383 ///
384 ///
385 /// #### `vexpand-set`
386 /// Whether to use the `vexpand` property.
387 ///
388 /// Readable | Writeable
389 ///
390 ///
391 /// #### `visible`
392 /// Whether the widget is visible.
393 ///
394 /// Readable | Writeable
395 ///
396 ///
397 /// #### `width-request`
398 /// Overrides for width request of the widget.
399 ///
400 /// If this is -1, the natural request will be used.
401 ///
402 /// Readable | Writeable
403 /// </details>
404 /// <details><summary><h4>Accessible</h4></summary>
405 ///
406 ///
407 /// #### `accessible-role`
408 /// The accessible role of the given [`Accessible`][crate::Accessible] implementation.
409 ///
410 /// The accessible role cannot be changed once set.
411 ///
412 /// Readable | Writeable
413 /// </details>
414 ///
415 /// ## Signals
416 ///
417 ///
418 /// #### `resize`
419 /// Emitted once when the widget is realized, and then each time the widget
420 /// is changed while realized.
421 ///
422 /// This is useful in order to keep state up to date with the widget size,
423 /// like for instance a backing surface.
424 ///
425 ///
426 /// <details><summary><h4>Widget</h4></summary>
427 ///
428 ///
429 /// #### `destroy`
430 /// Signals that all holders of a reference to the widget should release
431 /// the reference that they hold.
432 ///
433 /// May result in finalization of the widget if all references are released.
434 ///
435 /// This signal is not suitable for saving widget state.
436 ///
437 ///
438 ///
439 ///
440 /// #### `direction-changed`
441 /// Emitted when the text direction of a widget changes.
442 ///
443 ///
444 ///
445 ///
446 /// #### `hide`
447 /// Emitted when @widget is hidden.
448 ///
449 ///
450 ///
451 ///
452 /// #### `keynav-failed`
453 /// Emitted if keyboard navigation fails.
454 ///
455 /// See [`WidgetExt::keynav_failed()`][crate::prelude::WidgetExt::keynav_failed()] for details.
456 ///
457 ///
458 ///
459 ///
460 /// #### `map`
461 /// Emitted when @widget is going to be mapped.
462 ///
463 /// A widget is mapped when the widget is visible (which is controlled with
464 /// [`visible`][struct@crate::Widget#visible]) and all its parents up to the toplevel widget
465 /// are also visible.
466 ///
467 /// The `::map` signal can be used to determine whether a widget will be drawn,
468 /// for instance it can resume an animation that was stopped during the
469 /// emission of [`unmap`][struct@crate::Widget#unmap].
470 ///
471 ///
472 ///
473 ///
474 /// #### `mnemonic-activate`
475 /// Emitted when a widget is activated via a mnemonic.
476 ///
477 /// The default handler for this signal activates @widget if @group_cycling
478 /// is false, or just makes @widget grab focus if @group_cycling is true.
479 ///
480 ///
481 ///
482 ///
483 /// #### `move-focus`
484 /// Emitted when the focus is moved.
485 ///
486 /// The `::move-focus` signal is a [keybinding signal](class.SignalAction.html).
487 ///
488 /// The default bindings for this signal are <kbd>Tab</kbd> to move forward,
489 /// and <kbd>Shift</kbd>+<kbd>Tab</kbd> to move backward.
490 ///
491 /// Action
492 ///
493 ///
494 /// #### `query-tooltip`
495 /// Emitted when the widget’s tooltip is about to be shown.
496 ///
497 /// This happens when the [`has-tooltip`][struct@crate::Widget#has-tooltip] property
498 /// is true and the hover timeout has expired with the cursor hovering
499 /// above @widget; or emitted when @widget got focus in keyboard mode.
500 ///
501 /// Using the given coordinates, the signal handler should determine
502 /// whether a tooltip should be shown for @widget. If this is the case
503 /// true should be returned, false otherwise. Note that if @keyboard_mode
504 /// is true, the values of @x and @y are undefined and should not be used.
505 ///
506 /// The signal handler is free to manipulate @tooltip with the therefore
507 /// destined function calls.
508 ///
509 ///
510 ///
511 ///
512 /// #### `realize`
513 /// Emitted when @widget is associated with a [`gdk::Surface`][crate::gdk::Surface].
514 ///
515 /// This means that [`WidgetExt::realize()`][crate::prelude::WidgetExt::realize()] has been called
516 /// or the widget has been mapped (that is, it is going to be drawn).
517 ///
518 ///
519 ///
520 ///
521 /// #### `show`
522 /// Emitted when @widget is shown.
523 ///
524 ///
525 ///
526 ///
527 /// #### `state-flags-changed`
528 /// Emitted when the widget state changes.
529 ///
530 /// See [`WidgetExt::state_flags()`][crate::prelude::WidgetExt::state_flags()].
531 ///
532 ///
533 ///
534 ///
535 /// #### `unmap`
536 /// Emitted when @widget is going to be unmapped.
537 ///
538 /// A widget is unmapped when either it or any of its parents up to the
539 /// toplevel widget have been set as hidden.
540 ///
541 /// As `::unmap` indicates that a widget will not be shown any longer,
542 /// it can be used to, for example, stop an animation on the widget.
543 ///
544 ///
545 ///
546 ///
547 /// #### `unrealize`
548 /// Emitted when the [`gdk::Surface`][crate::gdk::Surface] associated with @widget is destroyed.
549 ///
550 /// This means that [`WidgetExt::unrealize()`][crate::prelude::WidgetExt::unrealize()] has been called
551 /// or the widget has been unmapped (that is, it is going to be hidden).
552 ///
553 ///
554 /// </details>
555 ///
556 /// # Implements
557 ///
558 /// [`DrawingAreaExt`][trait@crate::prelude::DrawingAreaExt], [`WidgetExt`][trait@crate::prelude::WidgetExt], [`trait@glib::ObjectExt`], [`AccessibleExt`][trait@crate::prelude::AccessibleExt], [`BuildableExt`][trait@crate::prelude::BuildableExt], [`ConstraintTargetExt`][trait@crate::prelude::ConstraintTargetExt], [`DrawingAreaExtManual`][trait@crate::prelude::DrawingAreaExtManual], [`WidgetExtManual`][trait@crate::prelude::WidgetExtManual], [`AccessibleExtManual`][trait@crate::prelude::AccessibleExtManual]
559 #[doc(alias = "GtkDrawingArea")]
560 pub struct DrawingArea(Object<ffi::GtkDrawingArea, ffi::GtkDrawingAreaClass>) @extends Widget, @implements Accessible, Buildable, ConstraintTarget;
561
562 match fn {
563 type_ => || ffi::gtk_drawing_area_get_type(),
564 }
565}
566
567impl DrawingArea {
568 pub const NONE: Option<&'static DrawingArea> = None;
569
570 /// Creates a new drawing area.
571 ///
572 /// # Returns
573 ///
574 /// a new [`DrawingArea`][crate::DrawingArea]
575 #[doc(alias = "gtk_drawing_area_new")]
576 pub fn new() -> DrawingArea {
577 assert_initialized_main_thread!();
578 unsafe { Widget::from_glib_none(ffi::gtk_drawing_area_new()).unsafe_cast() }
579 }
580
581 // rustdoc-stripper-ignore-next
582 /// Creates a new builder-pattern struct instance to construct [`DrawingArea`] objects.
583 ///
584 /// This method returns an instance of [`DrawingAreaBuilder`](crate::builders::DrawingAreaBuilder) which can be used to create [`DrawingArea`] objects.
585 pub fn builder() -> DrawingAreaBuilder {
586 DrawingAreaBuilder::new()
587 }
588}
589
590impl Default for DrawingArea {
591 fn default() -> Self {
592 Self::new()
593 }
594}
595
596// rustdoc-stripper-ignore-next
597/// A [builder-pattern] type to construct [`DrawingArea`] objects.
598///
599/// [builder-pattern]: https://doc.rust-lang.org/1.0.0/style/ownership/builders.html
600#[must_use = "The builder must be built to be used"]
601pub struct DrawingAreaBuilder {
602 builder: glib::object::ObjectBuilder<'static, DrawingArea>,
603}
604
605impl DrawingAreaBuilder {
606 fn new() -> Self {
607 Self {
608 builder: glib::object::Object::builder(),
609 }
610 }
611
612 /// The content height.
613 pub fn content_height(self, content_height: i32) -> Self {
614 Self {
615 builder: self.builder.property("content-height", content_height),
616 }
617 }
618
619 /// The content width.
620 pub fn content_width(self, content_width: i32) -> Self {
621 Self {
622 builder: self.builder.property("content-width", content_width),
623 }
624 }
625
626 /// Whether the widget or any of its descendents can accept
627 /// the input focus.
628 ///
629 /// This property is meant to be set by widget implementations,
630 /// typically in their instance init function.
631 pub fn can_focus(self, can_focus: bool) -> Self {
632 Self {
633 builder: self.builder.property("can-focus", can_focus),
634 }
635 }
636
637 /// Whether the widget can receive pointer events.
638 pub fn can_target(self, can_target: bool) -> Self {
639 Self {
640 builder: self.builder.property("can-target", can_target),
641 }
642 }
643
644 /// A list of css classes applied to this widget.
645 pub fn css_classes(self, css_classes: impl Into<glib::StrV>) -> Self {
646 Self {
647 builder: self.builder.property("css-classes", css_classes.into()),
648 }
649 }
650
651 /// The name of this widget in the CSS tree.
652 ///
653 /// This property is meant to be set by widget implementations,
654 /// typically in their instance init function.
655 pub fn css_name(self, css_name: impl Into<glib::GString>) -> Self {
656 Self {
657 builder: self.builder.property("css-name", css_name.into()),
658 }
659 }
660
661 /// The cursor used by @widget.
662 pub fn cursor(self, cursor: &gdk::Cursor) -> Self {
663 Self {
664 builder: self.builder.property("cursor", cursor.clone()),
665 }
666 }
667
668 /// Whether the widget should grab focus when it is clicked with the mouse.
669 ///
670 /// This property is only relevant for widgets that can take focus.
671 pub fn focus_on_click(self, focus_on_click: bool) -> Self {
672 Self {
673 builder: self.builder.property("focus-on-click", focus_on_click),
674 }
675 }
676
677 /// Whether this widget itself will accept the input focus.
678 pub fn focusable(self, focusable: bool) -> Self {
679 Self {
680 builder: self.builder.property("focusable", focusable),
681 }
682 }
683
684 /// How to distribute horizontal space if widget gets extra space.
685 pub fn halign(self, halign: Align) -> Self {
686 Self {
687 builder: self.builder.property("halign", halign),
688 }
689 }
690
691 /// Enables or disables the emission of the [`query-tooltip`][struct@crate::Widget#query-tooltip]
692 /// signal on @widget.
693 ///
694 /// A true value indicates that @widget can have a tooltip, in this case
695 /// the widget will be queried using [`query-tooltip`][struct@crate::Widget#query-tooltip] to
696 /// determine whether it will provide a tooltip or not.
697 pub fn has_tooltip(self, has_tooltip: bool) -> Self {
698 Self {
699 builder: self.builder.property("has-tooltip", has_tooltip),
700 }
701 }
702
703 /// Overrides for height request of the widget.
704 ///
705 /// If this is -1, the natural request will be used.
706 pub fn height_request(self, height_request: i32) -> Self {
707 Self {
708 builder: self.builder.property("height-request", height_request),
709 }
710 }
711
712 /// Whether to expand horizontally.
713 pub fn hexpand(self, hexpand: bool) -> Self {
714 Self {
715 builder: self.builder.property("hexpand", hexpand),
716 }
717 }
718
719 /// Whether to use the `hexpand` property.
720 pub fn hexpand_set(self, hexpand_set: bool) -> Self {
721 Self {
722 builder: self.builder.property("hexpand-set", hexpand_set),
723 }
724 }
725
726 /// The [`LayoutManager`][crate::LayoutManager] instance to use to compute
727 /// the preferred size of the widget, and allocate its children.
728 ///
729 /// This property is meant to be set by widget implementations,
730 /// typically in their instance init function.
731 pub fn layout_manager(self, layout_manager: &impl IsA<LayoutManager>) -> Self {
732 Self {
733 builder: self
734 .builder
735 .property("layout-manager", layout_manager.clone().upcast()),
736 }
737 }
738
739 /// Makes this widget act like a modal dialog, with respect to
740 /// event delivery.
741 ///
742 /// Global event controllers will not handle events with targets
743 /// inside the widget, unless they are set up to ignore propagation
744 /// limits. See [`EventControllerExt::set_propagation_limit()`][crate::prelude::EventControllerExt::set_propagation_limit()].
745 #[cfg(feature = "v4_18")]
746 #[cfg_attr(docsrs, doc(cfg(feature = "v4_18")))]
747 pub fn limit_events(self, limit_events: bool) -> Self {
748 Self {
749 builder: self.builder.property("limit-events", limit_events),
750 }
751 }
752
753 /// Margin on bottom side of widget.
754 ///
755 /// This property adds margin outside of the widget's normal size
756 /// request, the margin will be added in addition to the size from
757 /// [`WidgetExt::set_size_request()`][crate::prelude::WidgetExt::set_size_request()] for example.
758 pub fn margin_bottom(self, margin_bottom: i32) -> Self {
759 Self {
760 builder: self.builder.property("margin-bottom", margin_bottom),
761 }
762 }
763
764 /// Margin on end of widget, horizontally.
765 ///
766 /// This property supports left-to-right and right-to-left text
767 /// directions.
768 ///
769 /// This property adds margin outside of the widget's normal size
770 /// request, the margin will be added in addition to the size from
771 /// [`WidgetExt::set_size_request()`][crate::prelude::WidgetExt::set_size_request()] for example.
772 pub fn margin_end(self, margin_end: i32) -> Self {
773 Self {
774 builder: self.builder.property("margin-end", margin_end),
775 }
776 }
777
778 /// Margin on start of widget, horizontally.
779 ///
780 /// This property supports left-to-right and right-to-left text
781 /// directions.
782 ///
783 /// This property adds margin outside of the widget's normal size
784 /// request, the margin will be added in addition to the size from
785 /// [`WidgetExt::set_size_request()`][crate::prelude::WidgetExt::set_size_request()] for example.
786 pub fn margin_start(self, margin_start: i32) -> Self {
787 Self {
788 builder: self.builder.property("margin-start", margin_start),
789 }
790 }
791
792 /// Margin on top side of widget.
793 ///
794 /// This property adds margin outside of the widget's normal size
795 /// request, the margin will be added in addition to the size from
796 /// [`WidgetExt::set_size_request()`][crate::prelude::WidgetExt::set_size_request()] for example.
797 pub fn margin_top(self, margin_top: i32) -> Self {
798 Self {
799 builder: self.builder.property("margin-top", margin_top),
800 }
801 }
802
803 /// The name of the widget.
804 pub fn name(self, name: impl Into<glib::GString>) -> Self {
805 Self {
806 builder: self.builder.property("name", name.into()),
807 }
808 }
809
810 /// The requested opacity of the widget.
811 pub fn opacity(self, opacity: f64) -> Self {
812 Self {
813 builder: self.builder.property("opacity", opacity),
814 }
815 }
816
817 /// How content outside the widget's content area is treated.
818 ///
819 /// This property is meant to be set by widget implementations,
820 /// typically in their instance init function.
821 pub fn overflow(self, overflow: Overflow) -> Self {
822 Self {
823 builder: self.builder.property("overflow", overflow),
824 }
825 }
826
827 /// Whether the widget will receive the default action when it is focused.
828 pub fn receives_default(self, receives_default: bool) -> Self {
829 Self {
830 builder: self.builder.property("receives-default", receives_default),
831 }
832 }
833
834 /// Whether the widget responds to input.
835 pub fn sensitive(self, sensitive: bool) -> Self {
836 Self {
837 builder: self.builder.property("sensitive", sensitive),
838 }
839 }
840
841 /// Sets the text of tooltip to be the given string, which is marked up
842 /// with Pango markup.
843 ///
844 /// Also see [`Tooltip::set_markup()`][crate::Tooltip::set_markup()].
845 ///
846 /// This is a convenience property which will take care of getting the
847 /// tooltip shown if the given string is not `NULL`:
848 /// [`has-tooltip`][struct@crate::Widget#has-tooltip] will automatically be set to true
849 /// and there will be taken care of [`query-tooltip`][struct@crate::Widget#query-tooltip] in
850 /// the default signal handler.
851 ///
852 /// Note that if both [`tooltip-text`][struct@crate::Widget#tooltip-text] and
853 /// [`tooltip-markup`][struct@crate::Widget#tooltip-markup] are set, the last one wins.
854 pub fn tooltip_markup(self, tooltip_markup: impl Into<glib::GString>) -> Self {
855 Self {
856 builder: self
857 .builder
858 .property("tooltip-markup", tooltip_markup.into()),
859 }
860 }
861
862 /// Sets the text of tooltip to be the given string.
863 ///
864 /// Also see [`Tooltip::set_text()`][crate::Tooltip::set_text()].
865 ///
866 /// This is a convenience property which will take care of getting the
867 /// tooltip shown if the given string is not `NULL`:
868 /// [`has-tooltip`][struct@crate::Widget#has-tooltip] will automatically be set to true
869 /// and there will be taken care of [`query-tooltip`][struct@crate::Widget#query-tooltip] in
870 /// the default signal handler.
871 ///
872 /// Note that if both [`tooltip-text`][struct@crate::Widget#tooltip-text] and
873 /// [`tooltip-markup`][struct@crate::Widget#tooltip-markup] are set, the last one wins.
874 pub fn tooltip_text(self, tooltip_text: impl Into<glib::GString>) -> Self {
875 Self {
876 builder: self.builder.property("tooltip-text", tooltip_text.into()),
877 }
878 }
879
880 /// How to distribute vertical space if widget gets extra space.
881 pub fn valign(self, valign: Align) -> Self {
882 Self {
883 builder: self.builder.property("valign", valign),
884 }
885 }
886
887 /// Whether to expand vertically.
888 pub fn vexpand(self, vexpand: bool) -> Self {
889 Self {
890 builder: self.builder.property("vexpand", vexpand),
891 }
892 }
893
894 /// Whether to use the `vexpand` property.
895 pub fn vexpand_set(self, vexpand_set: bool) -> Self {
896 Self {
897 builder: self.builder.property("vexpand-set", vexpand_set),
898 }
899 }
900
901 /// Whether the widget is visible.
902 pub fn visible(self, visible: bool) -> Self {
903 Self {
904 builder: self.builder.property("visible", visible),
905 }
906 }
907
908 /// Overrides for width request of the widget.
909 ///
910 /// If this is -1, the natural request will be used.
911 pub fn width_request(self, width_request: i32) -> Self {
912 Self {
913 builder: self.builder.property("width-request", width_request),
914 }
915 }
916
917 /// The accessible role of the given [`Accessible`][crate::Accessible] implementation.
918 ///
919 /// The accessible role cannot be changed once set.
920 pub fn accessible_role(self, accessible_role: AccessibleRole) -> Self {
921 Self {
922 builder: self.builder.property("accessible-role", accessible_role),
923 }
924 }
925
926 // rustdoc-stripper-ignore-next
927 /// Build the [`DrawingArea`].
928 #[must_use = "Building the object from the builder is usually expensive and is not expected to have side effects"]
929 pub fn build(self) -> DrawingArea {
930 assert_initialized_main_thread!();
931 self.builder.build()
932 }
933}
934
935/// Trait containing all [`struct@DrawingArea`] methods.
936///
937/// # Implementors
938///
939/// [`DrawingArea`][struct@crate::DrawingArea]
940pub trait DrawingAreaExt: IsA<DrawingArea> + 'static {
941 /// Retrieves the content height of the [`DrawingArea`][crate::DrawingArea].
942 ///
943 /// # Returns
944 ///
945 /// The height requested for content of the drawing area
946 #[doc(alias = "gtk_drawing_area_get_content_height")]
947 #[doc(alias = "get_content_height")]
948 #[doc(alias = "content-height")]
949 fn content_height(&self) -> i32 {
950 unsafe { ffi::gtk_drawing_area_get_content_height(self.as_ref().to_glib_none().0) }
951 }
952
953 /// Retrieves the content width of the [`DrawingArea`][crate::DrawingArea].
954 ///
955 /// # Returns
956 ///
957 /// The width requested for content of the drawing area
958 #[doc(alias = "gtk_drawing_area_get_content_width")]
959 #[doc(alias = "get_content_width")]
960 #[doc(alias = "content-width")]
961 fn content_width(&self) -> i32 {
962 unsafe { ffi::gtk_drawing_area_get_content_width(self.as_ref().to_glib_none().0) }
963 }
964
965 /// Sets the desired height of the contents of the drawing area.
966 ///
967 /// Note that because widgets may be allocated larger sizes than they
968 /// requested, it is possible that the actual height passed to your draw
969 /// function is larger than the height set here. You can use
970 /// [`WidgetExt::set_valign()`][crate::prelude::WidgetExt::set_valign()] to avoid that.
971 ///
972 /// If the height is set to 0 (the default), the drawing area may disappear.
973 /// ## `height`
974 /// the height of contents
975 #[doc(alias = "gtk_drawing_area_set_content_height")]
976 #[doc(alias = "content-height")]
977 fn set_content_height(&self, height: i32) {
978 unsafe {
979 ffi::gtk_drawing_area_set_content_height(self.as_ref().to_glib_none().0, height);
980 }
981 }
982
983 /// Sets the desired width of the contents of the drawing area.
984 ///
985 /// Note that because widgets may be allocated larger sizes than they
986 /// requested, it is possible that the actual width passed to your draw
987 /// function is larger than the width set here. You can use
988 /// [`WidgetExt::set_halign()`][crate::prelude::WidgetExt::set_halign()] to avoid that.
989 ///
990 /// If the width is set to 0 (the default), the drawing area may disappear.
991 /// ## `width`
992 /// the width of contents
993 #[doc(alias = "gtk_drawing_area_set_content_width")]
994 #[doc(alias = "content-width")]
995 fn set_content_width(&self, width: i32) {
996 unsafe {
997 ffi::gtk_drawing_area_set_content_width(self.as_ref().to_glib_none().0, width);
998 }
999 }
1000
1001 /// Emitted once when the widget is realized, and then each time the widget
1002 /// is changed while realized.
1003 ///
1004 /// This is useful in order to keep state up to date with the widget size,
1005 /// like for instance a backing surface.
1006 /// ## `width`
1007 /// the width of the viewport
1008 /// ## `height`
1009 /// the height of the viewport
1010 #[doc(alias = "resize")]
1011 fn connect_resize<F: Fn(&Self, i32, i32) + 'static>(&self, f: F) -> SignalHandlerId {
1012 unsafe extern "C" fn resize_trampoline<
1013 P: IsA<DrawingArea>,
1014 F: Fn(&P, i32, i32) + 'static,
1015 >(
1016 this: *mut ffi::GtkDrawingArea,
1017 width: std::ffi::c_int,
1018 height: std::ffi::c_int,
1019 f: glib::ffi::gpointer,
1020 ) {
1021 let f: &F = &*(f as *const F);
1022 f(
1023 DrawingArea::from_glib_borrow(this).unsafe_cast_ref(),
1024 width,
1025 height,
1026 )
1027 }
1028 unsafe {
1029 let f: Box_<F> = Box_::new(f);
1030 connect_raw(
1031 self.as_ptr() as *mut _,
1032 c"resize".as_ptr() as *const _,
1033 Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
1034 resize_trampoline::<Self, F> as *const (),
1035 )),
1036 Box_::into_raw(f),
1037 )
1038 }
1039 }
1040
1041 #[doc(alias = "content-height")]
1042 fn connect_content_height_notify<F: Fn(&Self) + 'static>(&self, f: F) -> SignalHandlerId {
1043 unsafe extern "C" fn notify_content_height_trampoline<
1044 P: IsA<DrawingArea>,
1045 F: Fn(&P) + 'static,
1046 >(
1047 this: *mut ffi::GtkDrawingArea,
1048 _param_spec: glib::ffi::gpointer,
1049 f: glib::ffi::gpointer,
1050 ) {
1051 let f: &F = &*(f as *const F);
1052 f(DrawingArea::from_glib_borrow(this).unsafe_cast_ref())
1053 }
1054 unsafe {
1055 let f: Box_<F> = Box_::new(f);
1056 connect_raw(
1057 self.as_ptr() as *mut _,
1058 c"notify::content-height".as_ptr() as *const _,
1059 Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
1060 notify_content_height_trampoline::<Self, F> as *const (),
1061 )),
1062 Box_::into_raw(f),
1063 )
1064 }
1065 }
1066
1067 #[doc(alias = "content-width")]
1068 fn connect_content_width_notify<F: Fn(&Self) + 'static>(&self, f: F) -> SignalHandlerId {
1069 unsafe extern "C" fn notify_content_width_trampoline<
1070 P: IsA<DrawingArea>,
1071 F: Fn(&P) + 'static,
1072 >(
1073 this: *mut ffi::GtkDrawingArea,
1074 _param_spec: glib::ffi::gpointer,
1075 f: glib::ffi::gpointer,
1076 ) {
1077 let f: &F = &*(f as *const F);
1078 f(DrawingArea::from_glib_borrow(this).unsafe_cast_ref())
1079 }
1080 unsafe {
1081 let f: Box_<F> = Box_::new(f);
1082 connect_raw(
1083 self.as_ptr() as *mut _,
1084 c"notify::content-width".as_ptr() as *const _,
1085 Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
1086 notify_content_width_trampoline::<Self, F> as *const (),
1087 )),
1088 Box_::into_raw(f),
1089 )
1090 }
1091 }
1092}
1093
1094impl<O: IsA<DrawingArea>> DrawingAreaExt for O {}