gtk4/auto/gl_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#![allow(deprecated)]
5
6use crate::{
7 ffi, Accessible, AccessibleRole, Align, Buildable, ConstraintTarget, LayoutManager, Overflow,
8 Widget,
9};
10use glib::{
11 object::ObjectType as _,
12 prelude::*,
13 signal::{connect_raw, SignalHandlerId},
14 translate::*,
15};
16use std::boxed::Box as Box_;
17
18glib::wrapper! {
19 /// Allows drawing with OpenGL.
20 ///
21 /// <picture>
22 /// <source srcset="glarea-dark.png" media="(prefers-color-scheme: dark)">
23 /// <img alt="An example GtkGLArea" src="glarea.png">
24 /// </picture>
25 ///
26 /// [`GLArea`][crate::GLArea] sets up its own [`gdk::GLContext`][crate::gdk::GLContext], and creates a custom
27 /// GL framebuffer that the widget will do GL rendering onto. It also ensures
28 /// that this framebuffer is the default GL rendering target when rendering.
29 /// The completed rendering is integrated into the larger GTK scene graph as
30 /// a texture.
31 ///
32 /// In order to draw, you have to connect to the [`render`][struct@crate::GLArea#render]
33 /// signal, or subclass [`GLArea`][crate::GLArea] and override the GtkGLAreaClass.render
34 /// virtual function.
35 ///
36 /// The [`GLArea`][crate::GLArea] widget ensures that the [`gdk::GLContext`][crate::gdk::GLContext] is associated with
37 /// the widget's drawing area, and it is kept updated when the size and
38 /// position of the drawing area changes.
39 ///
40 /// ## Drawing with GtkGLArea
41 ///
42 /// The simplest way to draw using OpenGL commands in a [`GLArea`][crate::GLArea] is to
43 /// create a widget instance and connect to the [`render`][struct@crate::GLArea#render] signal:
44 ///
45 /// The `render()` function will be called when the [`GLArea`][crate::GLArea] is ready
46 /// for you to draw its content:
47 ///
48 /// The initial contents of the framebuffer are transparent.
49 ///
50 /// **⚠️ The following code is in c ⚠️**
51 ///
52 /// ```c
53 /// static gboolean
54 /// render (GtkGLArea *area, GdkGLContext *context)
55 /// {
56 /// // inside this function it's safe to use GL; the given
57 /// // GdkGLContext has been made current to the drawable
58 /// // surface used by the `GtkGLArea` and the viewport has
59 /// // already been set to be the size of the allocation
60 ///
61 /// // we can start by clearing the buffer
62 /// glClearColor (0, 0, 0, 0);
63 /// glClear (GL_COLOR_BUFFER_BIT);
64 ///
65 /// // record the active framebuffer ID, so we can return to it
66 /// // with `glBindFramebuffer (GL_FRAMEBUFFER, screen_fb)` should
67 /// // we, for instance, intend on utilizing the results of an
68 /// // intermediate render texture pass
69 /// GLuint screen_fb = 0;
70 /// glGetIntegerv (GL_FRAMEBUFFER_BINDING, &screen_fb);
71 ///
72 /// // draw your object
73 /// // draw_an_object ();
74 ///
75 /// // we completed our drawing; the draw commands will be
76 /// // flushed at the end of the signal emission chain, and
77 /// // the buffers will be drawn on the window
78 /// return TRUE;
79 /// }
80 ///
81 /// void setup_glarea (void)
82 /// {
83 /// // create a GtkGLArea instance
84 /// GtkWidget *gl_area = gtk_gl_area_new ();
85 ///
86 /// // connect to the "render" signal
87 /// g_signal_connect (gl_area, "render", G_CALLBACK (render), NULL);
88 /// }
89 /// ```
90 ///
91 /// If you need to initialize OpenGL state, e.g. buffer objects or
92 /// shaders, you should use the [`realize`][struct@crate::Widget#realize] signal;
93 /// you can use the [`unrealize`][struct@crate::Widget#unrealize] signal to clean up.
94 /// Since the [`gdk::GLContext`][crate::gdk::GLContext] creation and initialization may fail, you
95 /// will need to check for errors, using [`GLAreaExt::error()`][crate::prelude::GLAreaExt::error()].
96 ///
97 /// An example of how to safely initialize the GL state is:
98 ///
99 /// **⚠️ The following code is in c ⚠️**
100 ///
101 /// ```c
102 /// static void
103 /// on_realize (GtkGLArea *area)
104 /// {
105 /// // We need to make the context current if we want to
106 /// // call GL API
107 /// gtk_gl_area_make_current (area);
108 ///
109 /// // If there were errors during the initialization or
110 /// // when trying to make the context current, this
111 /// // function will return a GError for you to catch
112 /// if (gtk_gl_area_get_error (area) != NULL)
113 /// return;
114 ///
115 /// // You can also use gtk_gl_area_set_error() in order
116 /// // to show eventual initialization errors on the
117 /// // GtkGLArea widget itself
118 /// GError *internal_error = NULL;
119 /// init_buffer_objects (&error);
120 /// if (error != NULL)
121 /// {
122 /// gtk_gl_area_set_error (area, error);
123 /// g_error_free (error);
124 /// return;
125 /// }
126 ///
127 /// init_shaders (&error);
128 /// if (error != NULL)
129 /// {
130 /// gtk_gl_area_set_error (area, error);
131 /// g_error_free (error);
132 /// return;
133 /// }
134 /// }
135 /// ```
136 ///
137 /// If you need to change the options for creating the [`gdk::GLContext`][crate::gdk::GLContext]
138 /// you should use the [`create-context`][struct@crate::GLArea#create-context] signal.
139 ///
140 /// ## Properties
141 ///
142 ///
143 /// #### `allowed-apis`
144 /// The allowed APIs.
145 ///
146 /// Readable | Writeable
147 ///
148 ///
149 /// #### `api`
150 /// The API currently in use.
151 ///
152 /// Readable
153 ///
154 ///
155 /// #### `auto-render`
156 /// If set to [`true`] the ::render signal will be emitted every time
157 /// the widget draws.
158 ///
159 /// This is the default and is useful if drawing the widget is faster.
160 ///
161 /// If set to [`false`] the data from previous rendering is kept around and will
162 /// be used for drawing the widget the next time, unless the window is resized.
163 /// In order to force a rendering [`GLAreaExt::queue_render()`][crate::prelude::GLAreaExt::queue_render()] must be called.
164 /// This mode is useful when the scene changes seldom, but takes a long time
165 /// to redraw.
166 ///
167 /// Readable | Writeable
168 ///
169 ///
170 /// #### `context`
171 /// The [`gdk::GLContext`][crate::gdk::GLContext] used by the [`GLArea`][crate::GLArea] widget.
172 ///
173 /// The [`GLArea`][crate::GLArea] widget is responsible for creating the [`gdk::GLContext`][crate::gdk::GLContext]
174 /// instance. If you need to render with other kinds of buffers (stencil,
175 /// depth, etc), use render buffers.
176 ///
177 /// Readable
178 ///
179 ///
180 /// #### `has-depth-buffer`
181 /// If set to [`true`] the widget will allocate and enable a depth buffer for the
182 /// target framebuffer.
183 ///
184 /// Setting this property will enable GL's depth testing as a side effect. If
185 /// you don't need depth testing, you should call `glDisable(GL_DEPTH_TEST)`
186 /// in your `GtkGLArea::render` handler.
187 ///
188 /// Readable | Writeable
189 ///
190 ///
191 /// #### `has-stencil-buffer`
192 /// If set to [`true`] the widget will allocate and enable a stencil buffer for the
193 /// target framebuffer.
194 ///
195 /// Readable | Writeable
196 ///
197 ///
198 /// #### `use-es`
199 /// If set to [`true`] the widget will try to create a [`gdk::GLContext`][crate::gdk::GLContext] using
200 /// OpenGL ES instead of OpenGL.
201 ///
202 /// Readable | Writeable
203 /// <details><summary><h4>Widget</h4></summary>
204 ///
205 ///
206 /// #### `can-focus`
207 /// Whether the widget or any of its descendents can accept
208 /// the input focus.
209 ///
210 /// This property is meant to be set by widget implementations,
211 /// typically in their instance init function.
212 ///
213 /// Readable | Writeable
214 ///
215 ///
216 /// #### `can-target`
217 /// Whether the widget can receive pointer events.
218 ///
219 /// Readable | Writeable
220 ///
221 ///
222 /// #### `css-classes`
223 /// A list of css classes applied to this widget.
224 ///
225 /// Readable | Writeable
226 ///
227 ///
228 /// #### `css-name`
229 /// The name of this widget in the CSS tree.
230 ///
231 /// This property is meant to be set by widget implementations,
232 /// typically in their instance init function.
233 ///
234 /// Readable | Writeable | Construct Only
235 ///
236 ///
237 /// #### `cursor`
238 /// The cursor used by @widget.
239 ///
240 /// Readable | Writeable
241 ///
242 ///
243 /// #### `focus-on-click`
244 /// Whether the widget should grab focus when it is clicked with the mouse.
245 ///
246 /// This property is only relevant for widgets that can take focus.
247 ///
248 /// Readable | Writeable
249 ///
250 ///
251 /// #### `focusable`
252 /// Whether this widget itself will accept the input focus.
253 ///
254 /// Readable | Writeable
255 ///
256 ///
257 /// #### `halign`
258 /// How to distribute horizontal space if widget gets extra space.
259 ///
260 /// Readable | Writeable
261 ///
262 ///
263 /// #### `has-default`
264 /// Whether the widget is the default widget.
265 ///
266 /// Readable
267 ///
268 ///
269 /// #### `has-focus`
270 /// Whether the widget has the input focus.
271 ///
272 /// Readable
273 ///
274 ///
275 /// #### `has-tooltip`
276 /// Enables or disables the emission of the [`query-tooltip`][struct@crate::Widget#query-tooltip]
277 /// signal on @widget.
278 ///
279 /// A true value indicates that @widget can have a tooltip, in this case
280 /// the widget will be queried using [`query-tooltip`][struct@crate::Widget#query-tooltip] to
281 /// determine whether it will provide a tooltip or not.
282 ///
283 /// Readable | Writeable
284 ///
285 ///
286 /// #### `height-request`
287 /// Overrides for height request of the widget.
288 ///
289 /// If this is -1, the natural request will be used.
290 ///
291 /// Readable | Writeable
292 ///
293 ///
294 /// #### `hexpand`
295 /// Whether to expand horizontally.
296 ///
297 /// Readable | Writeable
298 ///
299 ///
300 /// #### `hexpand-set`
301 /// Whether to use the `hexpand` property.
302 ///
303 /// Readable | Writeable
304 ///
305 ///
306 /// #### `layout-manager`
307 /// The [`LayoutManager`][crate::LayoutManager] instance to use to compute
308 /// the preferred size of the widget, and allocate its children.
309 ///
310 /// This property is meant to be set by widget implementations,
311 /// typically in their instance init function.
312 ///
313 /// Readable | Writeable
314 ///
315 ///
316 /// #### `limit-events`
317 /// Makes this widget act like a modal dialog, with respect to
318 /// event delivery.
319 ///
320 /// Global event controllers will not handle events with targets
321 /// inside the widget, unless they are set up to ignore propagation
322 /// limits. See [`EventControllerExt::set_propagation_limit()`][crate::prelude::EventControllerExt::set_propagation_limit()].
323 ///
324 /// Readable | Writeable
325 ///
326 ///
327 /// #### `margin-bottom`
328 /// Margin on bottom side of widget.
329 ///
330 /// This property adds margin outside of the widget's normal size
331 /// request, the margin will be added in addition to the size from
332 /// [`WidgetExt::set_size_request()`][crate::prelude::WidgetExt::set_size_request()] for example.
333 ///
334 /// Readable | Writeable
335 ///
336 ///
337 /// #### `margin-end`
338 /// Margin on end of widget, horizontally.
339 ///
340 /// This property supports left-to-right and right-to-left text
341 /// directions.
342 ///
343 /// This property adds margin outside of the widget's normal size
344 /// request, the margin will be added in addition to the size from
345 /// [`WidgetExt::set_size_request()`][crate::prelude::WidgetExt::set_size_request()] for example.
346 ///
347 /// Readable | Writeable
348 ///
349 ///
350 /// #### `margin-start`
351 /// Margin on start of widget, horizontally.
352 ///
353 /// This property supports left-to-right and right-to-left text
354 /// directions.
355 ///
356 /// This property adds margin outside of the widget's normal size
357 /// request, the margin will be added in addition to the size from
358 /// [`WidgetExt::set_size_request()`][crate::prelude::WidgetExt::set_size_request()] for example.
359 ///
360 /// Readable | Writeable
361 ///
362 ///
363 /// #### `margin-top`
364 /// Margin on top side of widget.
365 ///
366 /// This property adds margin outside of the widget's normal size
367 /// request, the margin will be added in addition to the size from
368 /// [`WidgetExt::set_size_request()`][crate::prelude::WidgetExt::set_size_request()] for example.
369 ///
370 /// Readable | Writeable
371 ///
372 ///
373 /// #### `name`
374 /// The name of the widget.
375 ///
376 /// Readable | Writeable
377 ///
378 ///
379 /// #### `opacity`
380 /// The requested opacity of the widget.
381 ///
382 /// Readable | Writeable
383 ///
384 ///
385 /// #### `overflow`
386 /// How content outside the widget's content area is treated.
387 ///
388 /// This property is meant to be set by widget implementations,
389 /// typically in their instance init function.
390 ///
391 /// Readable | Writeable
392 ///
393 ///
394 /// #### `parent`
395 /// The parent widget of this widget.
396 ///
397 /// Readable
398 ///
399 ///
400 /// #### `receives-default`
401 /// Whether the widget will receive the default action when it is focused.
402 ///
403 /// Readable | Writeable
404 ///
405 ///
406 /// #### `root`
407 /// The [`Root`][crate::Root] widget of the widget tree containing this widget.
408 ///
409 /// This will be `NULL` if the widget is not contained in a root widget.
410 ///
411 /// Readable
412 ///
413 ///
414 /// #### `scale-factor`
415 /// The scale factor of the widget.
416 ///
417 /// Readable
418 ///
419 ///
420 /// #### `sensitive`
421 /// Whether the widget responds to input.
422 ///
423 /// Readable | Writeable
424 ///
425 ///
426 /// #### `tooltip-markup`
427 /// Sets the text of tooltip to be the given string, which is marked up
428 /// with Pango markup.
429 ///
430 /// Also see [`Tooltip::set_markup()`][crate::Tooltip::set_markup()].
431 ///
432 /// This is a convenience property which will take care of getting the
433 /// tooltip shown if the given string is not `NULL`:
434 /// [`has-tooltip`][struct@crate::Widget#has-tooltip] will automatically be set to true
435 /// and there will be taken care of [`query-tooltip`][struct@crate::Widget#query-tooltip] in
436 /// the default signal handler.
437 ///
438 /// Note that if both [`tooltip-text`][struct@crate::Widget#tooltip-text] and
439 /// [`tooltip-markup`][struct@crate::Widget#tooltip-markup] are set, the last one wins.
440 ///
441 /// Readable | Writeable
442 ///
443 ///
444 /// #### `tooltip-text`
445 /// Sets the text of tooltip to be the given string.
446 ///
447 /// Also see [`Tooltip::set_text()`][crate::Tooltip::set_text()].
448 ///
449 /// This is a convenience property which will take care of getting the
450 /// tooltip shown if the given string is not `NULL`:
451 /// [`has-tooltip`][struct@crate::Widget#has-tooltip] will automatically be set to true
452 /// and there will be taken care of [`query-tooltip`][struct@crate::Widget#query-tooltip] in
453 /// the default signal handler.
454 ///
455 /// Note that if both [`tooltip-text`][struct@crate::Widget#tooltip-text] and
456 /// [`tooltip-markup`][struct@crate::Widget#tooltip-markup] are set, the last one wins.
457 ///
458 /// Readable | Writeable
459 ///
460 ///
461 /// #### `valign`
462 /// How to distribute vertical space if widget gets extra space.
463 ///
464 /// Readable | Writeable
465 ///
466 ///
467 /// #### `vexpand`
468 /// Whether to expand vertically.
469 ///
470 /// Readable | Writeable
471 ///
472 ///
473 /// #### `vexpand-set`
474 /// Whether to use the `vexpand` property.
475 ///
476 /// Readable | Writeable
477 ///
478 ///
479 /// #### `visible`
480 /// Whether the widget is visible.
481 ///
482 /// Readable | Writeable
483 ///
484 ///
485 /// #### `width-request`
486 /// Overrides for width request of the widget.
487 ///
488 /// If this is -1, the natural request will be used.
489 ///
490 /// Readable | Writeable
491 /// </details>
492 /// <details><summary><h4>Accessible</h4></summary>
493 ///
494 ///
495 /// #### `accessible-role`
496 /// The accessible role of the given [`Accessible`][crate::Accessible] implementation.
497 ///
498 /// The accessible role cannot be changed once set.
499 ///
500 /// Readable | Writeable
501 /// </details>
502 ///
503 /// ## Signals
504 ///
505 ///
506 /// #### `create-context`
507 /// Emitted when the widget is being realized.
508 ///
509 /// This allows you to override how the GL context is created.
510 /// This is useful when you want to reuse an existing GL context,
511 /// or if you want to try creating different kinds of GL options.
512 ///
513 /// If context creation fails then the signal handler can use
514 /// [`GLAreaExt::set_error()`][crate::prelude::GLAreaExt::set_error()] to register a more detailed error
515 /// of how the construction failed.
516 ///
517 ///
518 ///
519 ///
520 /// #### `render`
521 /// Emitted every time the contents of the [`GLArea`][crate::GLArea] should be redrawn.
522 ///
523 /// The @context is bound to the @area prior to emitting this function,
524 /// and the buffers are painted to the window once the emission terminates.
525 ///
526 ///
527 ///
528 ///
529 /// #### `resize`
530 /// Emitted once when the widget is realized, and then each time the widget
531 /// is changed while realized.
532 ///
533 /// This is useful in order to keep GL state up to date with the widget size,
534 /// like for instance camera properties which may depend on the width/height
535 /// ratio.
536 ///
537 /// The GL context for the area is guaranteed to be current when this signal
538 /// is emitted.
539 ///
540 /// The default handler sets up the GL viewport.
541 ///
542 ///
543 /// <details><summary><h4>Widget</h4></summary>
544 ///
545 ///
546 /// #### `destroy`
547 /// Signals that all holders of a reference to the widget should release
548 /// the reference that they hold.
549 ///
550 /// May result in finalization of the widget if all references are released.
551 ///
552 /// This signal is not suitable for saving widget state.
553 ///
554 ///
555 ///
556 ///
557 /// #### `direction-changed`
558 /// Emitted when the text direction of a widget changes.
559 ///
560 ///
561 ///
562 ///
563 /// #### `hide`
564 /// Emitted when @widget is hidden.
565 ///
566 ///
567 ///
568 ///
569 /// #### `keynav-failed`
570 /// Emitted if keyboard navigation fails.
571 ///
572 /// See [`WidgetExt::keynav_failed()`][crate::prelude::WidgetExt::keynav_failed()] for details.
573 ///
574 ///
575 ///
576 ///
577 /// #### `map`
578 /// Emitted when @widget is going to be mapped.
579 ///
580 /// A widget is mapped when the widget is visible (which is controlled with
581 /// [`visible`][struct@crate::Widget#visible]) and all its parents up to the toplevel widget
582 /// are also visible.
583 ///
584 /// The `::map` signal can be used to determine whether a widget will be drawn,
585 /// for instance it can resume an animation that was stopped during the
586 /// emission of [`unmap`][struct@crate::Widget#unmap].
587 ///
588 ///
589 ///
590 ///
591 /// #### `mnemonic-activate`
592 /// Emitted when a widget is activated via a mnemonic.
593 ///
594 /// The default handler for this signal activates @widget if @group_cycling
595 /// is false, or just makes @widget grab focus if @group_cycling is true.
596 ///
597 ///
598 ///
599 ///
600 /// #### `move-focus`
601 /// Emitted when the focus is moved.
602 ///
603 /// The `::move-focus` signal is a [keybinding signal](class.SignalAction.html).
604 ///
605 /// The default bindings for this signal are <kbd>Tab</kbd> to move forward,
606 /// and <kbd>Shift</kbd>+<kbd>Tab</kbd> to move backward.
607 ///
608 /// Action
609 ///
610 ///
611 /// #### `query-tooltip`
612 /// Emitted when the widget’s tooltip is about to be shown.
613 ///
614 /// This happens when the [`has-tooltip`][struct@crate::Widget#has-tooltip] property
615 /// is true and the hover timeout has expired with the cursor hovering
616 /// above @widget; or emitted when @widget got focus in keyboard mode.
617 ///
618 /// Using the given coordinates, the signal handler should determine
619 /// whether a tooltip should be shown for @widget. If this is the case
620 /// true should be returned, false otherwise. Note that if @keyboard_mode
621 /// is true, the values of @x and @y are undefined and should not be used.
622 ///
623 /// The signal handler is free to manipulate @tooltip with the therefore
624 /// destined function calls.
625 ///
626 ///
627 ///
628 ///
629 /// #### `realize`
630 /// Emitted when @widget is associated with a [`gdk::Surface`][crate::gdk::Surface].
631 ///
632 /// This means that [`WidgetExt::realize()`][crate::prelude::WidgetExt::realize()] has been called
633 /// or the widget has been mapped (that is, it is going to be drawn).
634 ///
635 ///
636 ///
637 ///
638 /// #### `show`
639 /// Emitted when @widget is shown.
640 ///
641 ///
642 ///
643 ///
644 /// #### `state-flags-changed`
645 /// Emitted when the widget state changes.
646 ///
647 /// See [`WidgetExt::state_flags()`][crate::prelude::WidgetExt::state_flags()].
648 ///
649 ///
650 ///
651 ///
652 /// #### `unmap`
653 /// Emitted when @widget is going to be unmapped.
654 ///
655 /// A widget is unmapped when either it or any of its parents up to the
656 /// toplevel widget have been set as hidden.
657 ///
658 /// As `::unmap` indicates that a widget will not be shown any longer,
659 /// it can be used to, for example, stop an animation on the widget.
660 ///
661 ///
662 ///
663 ///
664 /// #### `unrealize`
665 /// Emitted when the [`gdk::Surface`][crate::gdk::Surface] associated with @widget is destroyed.
666 ///
667 /// This means that [`WidgetExt::unrealize()`][crate::prelude::WidgetExt::unrealize()] has been called
668 /// or the widget has been unmapped (that is, it is going to be hidden).
669 ///
670 ///
671 /// </details>
672 ///
673 /// # Implements
674 ///
675 /// [`GLAreaExt`][trait@crate::prelude::GLAreaExt], [`WidgetExt`][trait@crate::prelude::WidgetExt], [`trait@glib::ObjectExt`], [`AccessibleExt`][trait@crate::prelude::AccessibleExt], [`BuildableExt`][trait@crate::prelude::BuildableExt], [`ConstraintTargetExt`][trait@crate::prelude::ConstraintTargetExt], [`WidgetExtManual`][trait@crate::prelude::WidgetExtManual], [`AccessibleExtManual`][trait@crate::prelude::AccessibleExtManual]
676 #[doc(alias = "GtkGLArea")]
677 pub struct GLArea(Object<ffi::GtkGLArea, ffi::GtkGLAreaClass>) @extends Widget, @implements Accessible, Buildable, ConstraintTarget;
678
679 match fn {
680 type_ => || ffi::gtk_gl_area_get_type(),
681 }
682}
683
684impl GLArea {
685 pub const NONE: Option<&'static GLArea> = None;
686
687 /// Creates a new [`GLArea`][crate::GLArea] widget.
688 ///
689 /// # Returns
690 ///
691 /// a new [`GLArea`][crate::GLArea]
692 #[doc(alias = "gtk_gl_area_new")]
693 pub fn new() -> GLArea {
694 assert_initialized_main_thread!();
695 unsafe { Widget::from_glib_none(ffi::gtk_gl_area_new()).unsafe_cast() }
696 }
697
698 // rustdoc-stripper-ignore-next
699 /// Creates a new builder-pattern struct instance to construct [`GLArea`] objects.
700 ///
701 /// This method returns an instance of [`GLAreaBuilder`](crate::builders::GLAreaBuilder) which can be used to create [`GLArea`] objects.
702 pub fn builder() -> GLAreaBuilder {
703 GLAreaBuilder::new()
704 }
705}
706
707impl Default for GLArea {
708 fn default() -> Self {
709 Self::new()
710 }
711}
712
713// rustdoc-stripper-ignore-next
714/// A [builder-pattern] type to construct [`GLArea`] objects.
715///
716/// [builder-pattern]: https://doc.rust-lang.org/1.0.0/style/ownership/builders.html
717#[must_use = "The builder must be built to be used"]
718pub struct GLAreaBuilder {
719 builder: glib::object::ObjectBuilder<'static, GLArea>,
720}
721
722impl GLAreaBuilder {
723 fn new() -> Self {
724 Self {
725 builder: glib::object::Object::builder(),
726 }
727 }
728
729 /// The allowed APIs.
730 #[cfg(feature = "v4_12")]
731 #[cfg_attr(docsrs, doc(cfg(feature = "v4_12")))]
732 pub fn allowed_apis(self, allowed_apis: gdk::GLAPI) -> Self {
733 Self {
734 builder: self.builder.property("allowed-apis", allowed_apis),
735 }
736 }
737
738 /// If set to [`true`] the ::render signal will be emitted every time
739 /// the widget draws.
740 ///
741 /// This is the default and is useful if drawing the widget is faster.
742 ///
743 /// If set to [`false`] the data from previous rendering is kept around and will
744 /// be used for drawing the widget the next time, unless the window is resized.
745 /// In order to force a rendering [`GLAreaExt::queue_render()`][crate::prelude::GLAreaExt::queue_render()] must be called.
746 /// This mode is useful when the scene changes seldom, but takes a long time
747 /// to redraw.
748 pub fn auto_render(self, auto_render: bool) -> Self {
749 Self {
750 builder: self.builder.property("auto-render", auto_render),
751 }
752 }
753
754 /// If set to [`true`] the widget will allocate and enable a depth buffer for the
755 /// target framebuffer.
756 ///
757 /// Setting this property will enable GL's depth testing as a side effect. If
758 /// you don't need depth testing, you should call `glDisable(GL_DEPTH_TEST)`
759 /// in your `GtkGLArea::render` handler.
760 pub fn has_depth_buffer(self, has_depth_buffer: bool) -> Self {
761 Self {
762 builder: self.builder.property("has-depth-buffer", has_depth_buffer),
763 }
764 }
765
766 /// If set to [`true`] the widget will allocate and enable a stencil buffer for the
767 /// target framebuffer.
768 pub fn has_stencil_buffer(self, has_stencil_buffer: bool) -> Self {
769 Self {
770 builder: self
771 .builder
772 .property("has-stencil-buffer", has_stencil_buffer),
773 }
774 }
775
776 /// If set to [`true`] the widget will try to create a [`gdk::GLContext`][crate::gdk::GLContext] using
777 /// OpenGL ES instead of OpenGL.
778 /// Use [`allowed-apis`][struct@crate::GLArea#allowed-apis]
779 #[cfg_attr(feature = "v4_12", deprecated = "Since 4.12")]
780 pub fn use_es(self, use_es: bool) -> Self {
781 Self {
782 builder: self.builder.property("use-es", use_es),
783 }
784 }
785
786 /// Whether the widget or any of its descendents can accept
787 /// the input focus.
788 ///
789 /// This property is meant to be set by widget implementations,
790 /// typically in their instance init function.
791 pub fn can_focus(self, can_focus: bool) -> Self {
792 Self {
793 builder: self.builder.property("can-focus", can_focus),
794 }
795 }
796
797 /// Whether the widget can receive pointer events.
798 pub fn can_target(self, can_target: bool) -> Self {
799 Self {
800 builder: self.builder.property("can-target", can_target),
801 }
802 }
803
804 /// A list of css classes applied to this widget.
805 pub fn css_classes(self, css_classes: impl Into<glib::StrV>) -> Self {
806 Self {
807 builder: self.builder.property("css-classes", css_classes.into()),
808 }
809 }
810
811 /// The name of this widget in the CSS tree.
812 ///
813 /// This property is meant to be set by widget implementations,
814 /// typically in their instance init function.
815 pub fn css_name(self, css_name: impl Into<glib::GString>) -> Self {
816 Self {
817 builder: self.builder.property("css-name", css_name.into()),
818 }
819 }
820
821 /// The cursor used by @widget.
822 pub fn cursor(self, cursor: &gdk::Cursor) -> Self {
823 Self {
824 builder: self.builder.property("cursor", cursor.clone()),
825 }
826 }
827
828 /// Whether the widget should grab focus when it is clicked with the mouse.
829 ///
830 /// This property is only relevant for widgets that can take focus.
831 pub fn focus_on_click(self, focus_on_click: bool) -> Self {
832 Self {
833 builder: self.builder.property("focus-on-click", focus_on_click),
834 }
835 }
836
837 /// Whether this widget itself will accept the input focus.
838 pub fn focusable(self, focusable: bool) -> Self {
839 Self {
840 builder: self.builder.property("focusable", focusable),
841 }
842 }
843
844 /// How to distribute horizontal space if widget gets extra space.
845 pub fn halign(self, halign: Align) -> Self {
846 Self {
847 builder: self.builder.property("halign", halign),
848 }
849 }
850
851 /// Enables or disables the emission of the [`query-tooltip`][struct@crate::Widget#query-tooltip]
852 /// signal on @widget.
853 ///
854 /// A true value indicates that @widget can have a tooltip, in this case
855 /// the widget will be queried using [`query-tooltip`][struct@crate::Widget#query-tooltip] to
856 /// determine whether it will provide a tooltip or not.
857 pub fn has_tooltip(self, has_tooltip: bool) -> Self {
858 Self {
859 builder: self.builder.property("has-tooltip", has_tooltip),
860 }
861 }
862
863 /// Overrides for height request of the widget.
864 ///
865 /// If this is -1, the natural request will be used.
866 pub fn height_request(self, height_request: i32) -> Self {
867 Self {
868 builder: self.builder.property("height-request", height_request),
869 }
870 }
871
872 /// Whether to expand horizontally.
873 pub fn hexpand(self, hexpand: bool) -> Self {
874 Self {
875 builder: self.builder.property("hexpand", hexpand),
876 }
877 }
878
879 /// Whether to use the `hexpand` property.
880 pub fn hexpand_set(self, hexpand_set: bool) -> Self {
881 Self {
882 builder: self.builder.property("hexpand-set", hexpand_set),
883 }
884 }
885
886 /// The [`LayoutManager`][crate::LayoutManager] instance to use to compute
887 /// the preferred size of the widget, and allocate its children.
888 ///
889 /// This property is meant to be set by widget implementations,
890 /// typically in their instance init function.
891 pub fn layout_manager(self, layout_manager: &impl IsA<LayoutManager>) -> Self {
892 Self {
893 builder: self
894 .builder
895 .property("layout-manager", layout_manager.clone().upcast()),
896 }
897 }
898
899 /// Makes this widget act like a modal dialog, with respect to
900 /// event delivery.
901 ///
902 /// Global event controllers will not handle events with targets
903 /// inside the widget, unless they are set up to ignore propagation
904 /// limits. See [`EventControllerExt::set_propagation_limit()`][crate::prelude::EventControllerExt::set_propagation_limit()].
905 #[cfg(feature = "v4_18")]
906 #[cfg_attr(docsrs, doc(cfg(feature = "v4_18")))]
907 pub fn limit_events(self, limit_events: bool) -> Self {
908 Self {
909 builder: self.builder.property("limit-events", limit_events),
910 }
911 }
912
913 /// Margin on bottom side of widget.
914 ///
915 /// This property adds margin outside of the widget's normal size
916 /// request, the margin will be added in addition to the size from
917 /// [`WidgetExt::set_size_request()`][crate::prelude::WidgetExt::set_size_request()] for example.
918 pub fn margin_bottom(self, margin_bottom: i32) -> Self {
919 Self {
920 builder: self.builder.property("margin-bottom", margin_bottom),
921 }
922 }
923
924 /// Margin on end of widget, horizontally.
925 ///
926 /// This property supports left-to-right and right-to-left text
927 /// directions.
928 ///
929 /// This property adds margin outside of the widget's normal size
930 /// request, the margin will be added in addition to the size from
931 /// [`WidgetExt::set_size_request()`][crate::prelude::WidgetExt::set_size_request()] for example.
932 pub fn margin_end(self, margin_end: i32) -> Self {
933 Self {
934 builder: self.builder.property("margin-end", margin_end),
935 }
936 }
937
938 /// Margin on start of widget, horizontally.
939 ///
940 /// This property supports left-to-right and right-to-left text
941 /// directions.
942 ///
943 /// This property adds margin outside of the widget's normal size
944 /// request, the margin will be added in addition to the size from
945 /// [`WidgetExt::set_size_request()`][crate::prelude::WidgetExt::set_size_request()] for example.
946 pub fn margin_start(self, margin_start: i32) -> Self {
947 Self {
948 builder: self.builder.property("margin-start", margin_start),
949 }
950 }
951
952 /// Margin on top side of widget.
953 ///
954 /// This property adds margin outside of the widget's normal size
955 /// request, the margin will be added in addition to the size from
956 /// [`WidgetExt::set_size_request()`][crate::prelude::WidgetExt::set_size_request()] for example.
957 pub fn margin_top(self, margin_top: i32) -> Self {
958 Self {
959 builder: self.builder.property("margin-top", margin_top),
960 }
961 }
962
963 /// The name of the widget.
964 pub fn name(self, name: impl Into<glib::GString>) -> Self {
965 Self {
966 builder: self.builder.property("name", name.into()),
967 }
968 }
969
970 /// The requested opacity of the widget.
971 pub fn opacity(self, opacity: f64) -> Self {
972 Self {
973 builder: self.builder.property("opacity", opacity),
974 }
975 }
976
977 /// How content outside the widget's content area is treated.
978 ///
979 /// This property is meant to be set by widget implementations,
980 /// typically in their instance init function.
981 pub fn overflow(self, overflow: Overflow) -> Self {
982 Self {
983 builder: self.builder.property("overflow", overflow),
984 }
985 }
986
987 /// Whether the widget will receive the default action when it is focused.
988 pub fn receives_default(self, receives_default: bool) -> Self {
989 Self {
990 builder: self.builder.property("receives-default", receives_default),
991 }
992 }
993
994 /// Whether the widget responds to input.
995 pub fn sensitive(self, sensitive: bool) -> Self {
996 Self {
997 builder: self.builder.property("sensitive", sensitive),
998 }
999 }
1000
1001 /// Sets the text of tooltip to be the given string, which is marked up
1002 /// with Pango markup.
1003 ///
1004 /// Also see [`Tooltip::set_markup()`][crate::Tooltip::set_markup()].
1005 ///
1006 /// This is a convenience property which will take care of getting the
1007 /// tooltip shown if the given string is not `NULL`:
1008 /// [`has-tooltip`][struct@crate::Widget#has-tooltip] will automatically be set to true
1009 /// and there will be taken care of [`query-tooltip`][struct@crate::Widget#query-tooltip] in
1010 /// the default signal handler.
1011 ///
1012 /// Note that if both [`tooltip-text`][struct@crate::Widget#tooltip-text] and
1013 /// [`tooltip-markup`][struct@crate::Widget#tooltip-markup] are set, the last one wins.
1014 pub fn tooltip_markup(self, tooltip_markup: impl Into<glib::GString>) -> Self {
1015 Self {
1016 builder: self
1017 .builder
1018 .property("tooltip-markup", tooltip_markup.into()),
1019 }
1020 }
1021
1022 /// Sets the text of tooltip to be the given string.
1023 ///
1024 /// Also see [`Tooltip::set_text()`][crate::Tooltip::set_text()].
1025 ///
1026 /// This is a convenience property which will take care of getting the
1027 /// tooltip shown if the given string is not `NULL`:
1028 /// [`has-tooltip`][struct@crate::Widget#has-tooltip] will automatically be set to true
1029 /// and there will be taken care of [`query-tooltip`][struct@crate::Widget#query-tooltip] in
1030 /// the default signal handler.
1031 ///
1032 /// Note that if both [`tooltip-text`][struct@crate::Widget#tooltip-text] and
1033 /// [`tooltip-markup`][struct@crate::Widget#tooltip-markup] are set, the last one wins.
1034 pub fn tooltip_text(self, tooltip_text: impl Into<glib::GString>) -> Self {
1035 Self {
1036 builder: self.builder.property("tooltip-text", tooltip_text.into()),
1037 }
1038 }
1039
1040 /// How to distribute vertical space if widget gets extra space.
1041 pub fn valign(self, valign: Align) -> Self {
1042 Self {
1043 builder: self.builder.property("valign", valign),
1044 }
1045 }
1046
1047 /// Whether to expand vertically.
1048 pub fn vexpand(self, vexpand: bool) -> Self {
1049 Self {
1050 builder: self.builder.property("vexpand", vexpand),
1051 }
1052 }
1053
1054 /// Whether to use the `vexpand` property.
1055 pub fn vexpand_set(self, vexpand_set: bool) -> Self {
1056 Self {
1057 builder: self.builder.property("vexpand-set", vexpand_set),
1058 }
1059 }
1060
1061 /// Whether the widget is visible.
1062 pub fn visible(self, visible: bool) -> Self {
1063 Self {
1064 builder: self.builder.property("visible", visible),
1065 }
1066 }
1067
1068 /// Overrides for width request of the widget.
1069 ///
1070 /// If this is -1, the natural request will be used.
1071 pub fn width_request(self, width_request: i32) -> Self {
1072 Self {
1073 builder: self.builder.property("width-request", width_request),
1074 }
1075 }
1076
1077 /// The accessible role of the given [`Accessible`][crate::Accessible] implementation.
1078 ///
1079 /// The accessible role cannot be changed once set.
1080 pub fn accessible_role(self, accessible_role: AccessibleRole) -> Self {
1081 Self {
1082 builder: self.builder.property("accessible-role", accessible_role),
1083 }
1084 }
1085
1086 // rustdoc-stripper-ignore-next
1087 /// Build the [`GLArea`].
1088 #[must_use = "Building the object from the builder is usually expensive and is not expected to have side effects"]
1089 pub fn build(self) -> GLArea {
1090 assert_initialized_main_thread!();
1091 self.builder.build()
1092 }
1093}
1094
1095/// Trait containing all [`struct@GLArea`] methods.
1096///
1097/// # Implementors
1098///
1099/// [`GLArea`][struct@crate::GLArea]
1100pub trait GLAreaExt: IsA<GLArea> + 'static {
1101 /// Binds buffers to the framebuffer.
1102 ///
1103 /// Ensures that the @self framebuffer object is made the current draw
1104 /// and read target, and that all the required buffers for the @self
1105 /// are created and bound to the framebuffer.
1106 ///
1107 /// This function is automatically called before emitting the
1108 /// [`render`][struct@crate::GLArea#render] signal, and doesn't normally need to be
1109 /// called by application code.
1110 #[doc(alias = "gtk_gl_area_attach_buffers")]
1111 fn attach_buffers(&self) {
1112 unsafe {
1113 ffi::gtk_gl_area_attach_buffers(self.as_ref().to_glib_none().0);
1114 }
1115 }
1116
1117 /// Gets the allowed APIs.
1118 ///
1119 /// See [`set_allowed_apis()`][Self::set_allowed_apis()].
1120 ///
1121 /// # Returns
1122 ///
1123 /// the allowed APIs
1124 #[cfg(feature = "v4_12")]
1125 #[cfg_attr(docsrs, doc(cfg(feature = "v4_12")))]
1126 #[doc(alias = "gtk_gl_area_get_allowed_apis")]
1127 #[doc(alias = "get_allowed_apis")]
1128 #[doc(alias = "allowed-apis")]
1129 fn allowed_apis(&self) -> gdk::GLAPI {
1130 unsafe {
1131 from_glib(ffi::gtk_gl_area_get_allowed_apis(
1132 self.as_ref().to_glib_none().0,
1133 ))
1134 }
1135 }
1136
1137 /// Gets the API that is currently in use.
1138 ///
1139 /// If the GL area has not been realized yet, 0 is returned.
1140 ///
1141 /// # Returns
1142 ///
1143 /// the currently used API
1144 #[cfg(feature = "v4_12")]
1145 #[cfg_attr(docsrs, doc(cfg(feature = "v4_12")))]
1146 #[doc(alias = "gtk_gl_area_get_api")]
1147 #[doc(alias = "get_api")]
1148 fn api(&self) -> gdk::GLAPI {
1149 unsafe { from_glib(ffi::gtk_gl_area_get_api(self.as_ref().to_glib_none().0)) }
1150 }
1151
1152 /// Returns whether the area is in auto render mode or not.
1153 ///
1154 /// # Returns
1155 ///
1156 /// [`true`] if the @self is auto rendering, [`false`] otherwise
1157 #[doc(alias = "gtk_gl_area_get_auto_render")]
1158 #[doc(alias = "get_auto_render")]
1159 #[doc(alias = "auto-render")]
1160 fn is_auto_render(&self) -> bool {
1161 unsafe {
1162 from_glib(ffi::gtk_gl_area_get_auto_render(
1163 self.as_ref().to_glib_none().0,
1164 ))
1165 }
1166 }
1167
1168 /// Retrieves the [`gdk::GLContext`][crate::gdk::GLContext] used by @self.
1169 ///
1170 /// # Returns
1171 ///
1172 /// the [`gdk::GLContext`][crate::gdk::GLContext]
1173 #[doc(alias = "gtk_gl_area_get_context")]
1174 #[doc(alias = "get_context")]
1175 fn context(&self) -> Option<gdk::GLContext> {
1176 unsafe { from_glib_none(ffi::gtk_gl_area_get_context(self.as_ref().to_glib_none().0)) }
1177 }
1178
1179 /// Gets the current error set on the @self.
1180 ///
1181 /// # Returns
1182 ///
1183 /// the `GError`
1184 #[doc(alias = "gtk_gl_area_get_error")]
1185 #[doc(alias = "get_error")]
1186 fn error(&self) -> Option<glib::Error> {
1187 unsafe { from_glib_none(ffi::gtk_gl_area_get_error(self.as_ref().to_glib_none().0)) }
1188 }
1189
1190 /// Returns whether the area has a depth buffer.
1191 ///
1192 /// # Returns
1193 ///
1194 /// [`true`] if the @self has a depth buffer, [`false`] otherwise
1195 #[doc(alias = "gtk_gl_area_get_has_depth_buffer")]
1196 #[doc(alias = "get_has_depth_buffer")]
1197 #[doc(alias = "has-depth-buffer")]
1198 fn has_depth_buffer(&self) -> bool {
1199 unsafe {
1200 from_glib(ffi::gtk_gl_area_get_has_depth_buffer(
1201 self.as_ref().to_glib_none().0,
1202 ))
1203 }
1204 }
1205
1206 /// Returns whether the area has a stencil buffer.
1207 ///
1208 /// # Returns
1209 ///
1210 /// [`true`] if the @self has a stencil buffer, [`false`] otherwise
1211 #[doc(alias = "gtk_gl_area_get_has_stencil_buffer")]
1212 #[doc(alias = "get_has_stencil_buffer")]
1213 #[doc(alias = "has-stencil-buffer")]
1214 fn has_stencil_buffer(&self) -> bool {
1215 unsafe {
1216 from_glib(ffi::gtk_gl_area_get_has_stencil_buffer(
1217 self.as_ref().to_glib_none().0,
1218 ))
1219 }
1220 }
1221
1222 /// Retrieves the required version of OpenGL.
1223 ///
1224 /// See [`set_required_version()`][Self::set_required_version()].
1225 ///
1226 /// # Returns
1227 ///
1228 ///
1229 /// ## `major`
1230 /// return location for the required major version
1231 ///
1232 /// ## `minor`
1233 /// return location for the required minor version
1234 #[doc(alias = "gtk_gl_area_get_required_version")]
1235 #[doc(alias = "get_required_version")]
1236 fn required_version(&self) -> (i32, i32) {
1237 unsafe {
1238 let mut major = std::mem::MaybeUninit::uninit();
1239 let mut minor = std::mem::MaybeUninit::uninit();
1240 ffi::gtk_gl_area_get_required_version(
1241 self.as_ref().to_glib_none().0,
1242 major.as_mut_ptr(),
1243 minor.as_mut_ptr(),
1244 );
1245 (major.assume_init(), minor.assume_init())
1246 }
1247 }
1248
1249 /// Returns whether the [`GLArea`][crate::GLArea] should use OpenGL ES.
1250 ///
1251 /// See [`set_use_es()`][Self::set_use_es()].
1252 ///
1253 /// # Deprecated since 4.12
1254 ///
1255 /// Use [`api()`][Self::api()]
1256 ///
1257 /// # Returns
1258 ///
1259 /// [`true`] if the [`GLArea`][crate::GLArea] should create an OpenGL ES context
1260 /// and [`false`] otherwise
1261 #[cfg_attr(feature = "v4_12", deprecated = "Since 4.12")]
1262 #[allow(deprecated)]
1263 #[doc(alias = "gtk_gl_area_get_use_es")]
1264 #[doc(alias = "get_use_es")]
1265 #[doc(alias = "use-es")]
1266 fn uses_es(&self) -> bool {
1267 unsafe { from_glib(ffi::gtk_gl_area_get_use_es(self.as_ref().to_glib_none().0)) }
1268 }
1269
1270 /// Ensures that the [`gdk::GLContext`][crate::gdk::GLContext] used by @self is associated with
1271 /// the [`GLArea`][crate::GLArea].
1272 ///
1273 /// This function is automatically called before emitting the
1274 /// [`render`][struct@crate::GLArea#render] signal, and doesn't normally need
1275 /// to be called by application code.
1276 #[doc(alias = "gtk_gl_area_make_current")]
1277 fn make_current(&self) {
1278 unsafe {
1279 ffi::gtk_gl_area_make_current(self.as_ref().to_glib_none().0);
1280 }
1281 }
1282
1283 /// Marks the currently rendered data (if any) as invalid, and queues
1284 /// a redraw of the widget.
1285 ///
1286 /// This ensures that the [`render`][struct@crate::GLArea#render] signal
1287 /// is emitted during the draw.
1288 ///
1289 /// This is only needed when [`set_auto_render()`][Self::set_auto_render()] has
1290 /// been called with a [`false`] value. The default behaviour is to
1291 /// emit [`render`][struct@crate::GLArea#render] on each draw.
1292 #[doc(alias = "gtk_gl_area_queue_render")]
1293 fn queue_render(&self) {
1294 unsafe {
1295 ffi::gtk_gl_area_queue_render(self.as_ref().to_glib_none().0);
1296 }
1297 }
1298
1299 /// Sets the allowed APIs to create a context with.
1300 ///
1301 /// You should check [`api`][struct@crate::GLArea#api] before drawing
1302 /// with either API.
1303 ///
1304 /// By default, all APIs are allowed.
1305 /// ## `apis`
1306 /// the allowed APIs
1307 #[cfg(feature = "v4_12")]
1308 #[cfg_attr(docsrs, doc(cfg(feature = "v4_12")))]
1309 #[doc(alias = "gtk_gl_area_set_allowed_apis")]
1310 #[doc(alias = "allowed-apis")]
1311 fn set_allowed_apis(&self, apis: gdk::GLAPI) {
1312 unsafe {
1313 ffi::gtk_gl_area_set_allowed_apis(self.as_ref().to_glib_none().0, apis.into_glib());
1314 }
1315 }
1316
1317 /// Sets whether the [`GLArea`][crate::GLArea] is in auto render mode.
1318 ///
1319 /// If @auto_render is [`true`] the [`render`][struct@crate::GLArea#render] signal will
1320 /// be emitted every time the widget draws. This is the default and is
1321 /// useful if drawing the widget is faster.
1322 ///
1323 /// If @auto_render is [`false`] the data from previous rendering is kept
1324 /// around and will be used for drawing the widget the next time,
1325 /// unless the window is resized. In order to force a rendering
1326 /// [`queue_render()`][Self::queue_render()] must be called. This mode is
1327 /// useful when the scene changes seldom, but takes a long time to redraw.
1328 /// ## `auto_render`
1329 /// a boolean
1330 #[doc(alias = "gtk_gl_area_set_auto_render")]
1331 #[doc(alias = "auto-render")]
1332 fn set_auto_render(&self, auto_render: bool) {
1333 unsafe {
1334 ffi::gtk_gl_area_set_auto_render(
1335 self.as_ref().to_glib_none().0,
1336 auto_render.into_glib(),
1337 );
1338 }
1339 }
1340
1341 /// Sets an error on the area which will be shown instead of the
1342 /// GL rendering.
1343 ///
1344 /// This is useful in the [`create-context`][struct@crate::GLArea#create-context]
1345 /// signal if GL context creation fails.
1346 /// ## `error`
1347 /// a new `GError`, or [`None`] to unset the error
1348 #[doc(alias = "gtk_gl_area_set_error")]
1349 fn set_error(&self, error: Option<&glib::Error>) {
1350 unsafe {
1351 ffi::gtk_gl_area_set_error(self.as_ref().to_glib_none().0, error.to_glib_none().0);
1352 }
1353 }
1354
1355 /// Sets whether the [`GLArea`][crate::GLArea] should use a depth buffer.
1356 ///
1357 /// If @has_depth_buffer is [`true`] the widget will allocate and
1358 /// enable a depth buffer for the target framebuffer. Otherwise
1359 /// there will be none.
1360 /// ## `has_depth_buffer`
1361 /// [`true`] to add a depth buffer
1362 #[doc(alias = "gtk_gl_area_set_has_depth_buffer")]
1363 #[doc(alias = "has-depth-buffer")]
1364 fn set_has_depth_buffer(&self, has_depth_buffer: bool) {
1365 unsafe {
1366 ffi::gtk_gl_area_set_has_depth_buffer(
1367 self.as_ref().to_glib_none().0,
1368 has_depth_buffer.into_glib(),
1369 );
1370 }
1371 }
1372
1373 /// Sets whether the [`GLArea`][crate::GLArea] should use a stencil buffer.
1374 ///
1375 /// If @has_stencil_buffer is [`true`] the widget will allocate and
1376 /// enable a stencil buffer for the target framebuffer. Otherwise
1377 /// there will be none.
1378 /// ## `has_stencil_buffer`
1379 /// [`true`] to add a stencil buffer
1380 #[doc(alias = "gtk_gl_area_set_has_stencil_buffer")]
1381 #[doc(alias = "has-stencil-buffer")]
1382 fn set_has_stencil_buffer(&self, has_stencil_buffer: bool) {
1383 unsafe {
1384 ffi::gtk_gl_area_set_has_stencil_buffer(
1385 self.as_ref().to_glib_none().0,
1386 has_stencil_buffer.into_glib(),
1387 );
1388 }
1389 }
1390
1391 /// Sets the required version of OpenGL to be used when creating
1392 /// the context for the widget.
1393 ///
1394 /// This function must be called before the area has been realized.
1395 /// ## `major`
1396 /// the major version
1397 /// ## `minor`
1398 /// the minor version
1399 #[doc(alias = "gtk_gl_area_set_required_version")]
1400 fn set_required_version(&self, major: i32, minor: i32) {
1401 unsafe {
1402 ffi::gtk_gl_area_set_required_version(self.as_ref().to_glib_none().0, major, minor);
1403 }
1404 }
1405
1406 /// Sets whether the @self should create an OpenGL or an OpenGL ES context.
1407 ///
1408 /// You should check the capabilities of the [`gdk::GLContext`][crate::gdk::GLContext] before drawing
1409 /// with either API.
1410 ///
1411 /// # Deprecated since 4.12
1412 ///
1413 /// Use [`set_allowed_apis()`][Self::set_allowed_apis()]
1414 /// ## `use_es`
1415 /// whether to use OpenGL or OpenGL ES
1416 #[cfg_attr(feature = "v4_12", deprecated = "Since 4.12")]
1417 #[allow(deprecated)]
1418 #[doc(alias = "gtk_gl_area_set_use_es")]
1419 #[doc(alias = "use-es")]
1420 fn set_use_es(&self, use_es: bool) {
1421 unsafe {
1422 ffi::gtk_gl_area_set_use_es(self.as_ref().to_glib_none().0, use_es.into_glib());
1423 }
1424 }
1425
1426 /// Emitted when the widget is being realized.
1427 ///
1428 /// This allows you to override how the GL context is created.
1429 /// This is useful when you want to reuse an existing GL context,
1430 /// or if you want to try creating different kinds of GL options.
1431 ///
1432 /// If context creation fails then the signal handler can use
1433 /// [`set_error()`][Self::set_error()] to register a more detailed error
1434 /// of how the construction failed.
1435 ///
1436 /// # Returns
1437 ///
1438 /// a newly created [`gdk::GLContext`][crate::gdk::GLContext];
1439 /// the [`GLArea`][crate::GLArea] widget will take ownership of the returned value.
1440 #[doc(alias = "create-context")]
1441 fn connect_create_context<F: Fn(&Self) -> Option<gdk::GLContext> + 'static>(
1442 &self,
1443 f: F,
1444 ) -> SignalHandlerId {
1445 unsafe extern "C" fn create_context_trampoline<
1446 P: IsA<GLArea>,
1447 F: Fn(&P) -> Option<gdk::GLContext> + 'static,
1448 >(
1449 this: *mut ffi::GtkGLArea,
1450 f: glib::ffi::gpointer,
1451 ) -> *mut gdk::ffi::GdkGLContext {
1452 let f: &F = &*(f as *const F);
1453 f(GLArea::from_glib_borrow(this).unsafe_cast_ref()).to_glib_full()
1454 }
1455 unsafe {
1456 let f: Box_<F> = Box_::new(f);
1457 connect_raw(
1458 self.as_ptr() as *mut _,
1459 c"create-context".as_ptr() as *const _,
1460 Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
1461 create_context_trampoline::<Self, F> as *const (),
1462 )),
1463 Box_::into_raw(f),
1464 )
1465 }
1466 }
1467
1468 /// Emitted every time the contents of the [`GLArea`][crate::GLArea] should be redrawn.
1469 ///
1470 /// The @context is bound to the @area prior to emitting this function,
1471 /// and the buffers are painted to the window once the emission terminates.
1472 /// ## `context`
1473 /// the [`gdk::GLContext`][crate::gdk::GLContext] used by @area
1474 ///
1475 /// # Returns
1476 ///
1477 /// [`true`] to stop other handlers from being invoked for the event.
1478 /// [`false`] to propagate the event further.
1479 #[doc(alias = "render")]
1480 fn connect_render<F: Fn(&Self, &gdk::GLContext) -> glib::Propagation + 'static>(
1481 &self,
1482 f: F,
1483 ) -> SignalHandlerId {
1484 unsafe extern "C" fn render_trampoline<
1485 P: IsA<GLArea>,
1486 F: Fn(&P, &gdk::GLContext) -> glib::Propagation + 'static,
1487 >(
1488 this: *mut ffi::GtkGLArea,
1489 context: *mut gdk::ffi::GdkGLContext,
1490 f: glib::ffi::gpointer,
1491 ) -> glib::ffi::gboolean {
1492 let f: &F = &*(f as *const F);
1493 f(
1494 GLArea::from_glib_borrow(this).unsafe_cast_ref(),
1495 &from_glib_borrow(context),
1496 )
1497 .into_glib()
1498 }
1499 unsafe {
1500 let f: Box_<F> = Box_::new(f);
1501 connect_raw(
1502 self.as_ptr() as *mut _,
1503 c"render".as_ptr() as *const _,
1504 Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
1505 render_trampoline::<Self, F> as *const (),
1506 )),
1507 Box_::into_raw(f),
1508 )
1509 }
1510 }
1511
1512 /// Emitted once when the widget is realized, and then each time the widget
1513 /// is changed while realized.
1514 ///
1515 /// This is useful in order to keep GL state up to date with the widget size,
1516 /// like for instance camera properties which may depend on the width/height
1517 /// ratio.
1518 ///
1519 /// The GL context for the area is guaranteed to be current when this signal
1520 /// is emitted.
1521 ///
1522 /// The default handler sets up the GL viewport.
1523 /// ## `width`
1524 /// the width of the viewport
1525 /// ## `height`
1526 /// the height of the viewport
1527 #[doc(alias = "resize")]
1528 fn connect_resize<F: Fn(&Self, i32, i32) + 'static>(&self, f: F) -> SignalHandlerId {
1529 unsafe extern "C" fn resize_trampoline<P: IsA<GLArea>, F: Fn(&P, i32, i32) + 'static>(
1530 this: *mut ffi::GtkGLArea,
1531 width: std::ffi::c_int,
1532 height: std::ffi::c_int,
1533 f: glib::ffi::gpointer,
1534 ) {
1535 let f: &F = &*(f as *const F);
1536 f(
1537 GLArea::from_glib_borrow(this).unsafe_cast_ref(),
1538 width,
1539 height,
1540 )
1541 }
1542 unsafe {
1543 let f: Box_<F> = Box_::new(f);
1544 connect_raw(
1545 self.as_ptr() as *mut _,
1546 c"resize".as_ptr() as *const _,
1547 Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
1548 resize_trampoline::<Self, F> as *const (),
1549 )),
1550 Box_::into_raw(f),
1551 )
1552 }
1553 }
1554
1555 #[cfg(feature = "v4_12")]
1556 #[cfg_attr(docsrs, doc(cfg(feature = "v4_12")))]
1557 #[doc(alias = "allowed-apis")]
1558 fn connect_allowed_apis_notify<F: Fn(&Self) + 'static>(&self, f: F) -> SignalHandlerId {
1559 unsafe extern "C" fn notify_allowed_apis_trampoline<P: IsA<GLArea>, F: Fn(&P) + 'static>(
1560 this: *mut ffi::GtkGLArea,
1561 _param_spec: glib::ffi::gpointer,
1562 f: glib::ffi::gpointer,
1563 ) {
1564 let f: &F = &*(f as *const F);
1565 f(GLArea::from_glib_borrow(this).unsafe_cast_ref())
1566 }
1567 unsafe {
1568 let f: Box_<F> = Box_::new(f);
1569 connect_raw(
1570 self.as_ptr() as *mut _,
1571 c"notify::allowed-apis".as_ptr() as *const _,
1572 Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
1573 notify_allowed_apis_trampoline::<Self, F> as *const (),
1574 )),
1575 Box_::into_raw(f),
1576 )
1577 }
1578 }
1579
1580 #[cfg(feature = "v4_12")]
1581 #[cfg_attr(docsrs, doc(cfg(feature = "v4_12")))]
1582 #[doc(alias = "api")]
1583 fn connect_api_notify<F: Fn(&Self) + 'static>(&self, f: F) -> SignalHandlerId {
1584 unsafe extern "C" fn notify_api_trampoline<P: IsA<GLArea>, F: Fn(&P) + 'static>(
1585 this: *mut ffi::GtkGLArea,
1586 _param_spec: glib::ffi::gpointer,
1587 f: glib::ffi::gpointer,
1588 ) {
1589 let f: &F = &*(f as *const F);
1590 f(GLArea::from_glib_borrow(this).unsafe_cast_ref())
1591 }
1592 unsafe {
1593 let f: Box_<F> = Box_::new(f);
1594 connect_raw(
1595 self.as_ptr() as *mut _,
1596 c"notify::api".as_ptr() as *const _,
1597 Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
1598 notify_api_trampoline::<Self, F> as *const (),
1599 )),
1600 Box_::into_raw(f),
1601 )
1602 }
1603 }
1604
1605 #[doc(alias = "auto-render")]
1606 fn connect_auto_render_notify<F: Fn(&Self) + 'static>(&self, f: F) -> SignalHandlerId {
1607 unsafe extern "C" fn notify_auto_render_trampoline<P: IsA<GLArea>, F: Fn(&P) + 'static>(
1608 this: *mut ffi::GtkGLArea,
1609 _param_spec: glib::ffi::gpointer,
1610 f: glib::ffi::gpointer,
1611 ) {
1612 let f: &F = &*(f as *const F);
1613 f(GLArea::from_glib_borrow(this).unsafe_cast_ref())
1614 }
1615 unsafe {
1616 let f: Box_<F> = Box_::new(f);
1617 connect_raw(
1618 self.as_ptr() as *mut _,
1619 c"notify::auto-render".as_ptr() as *const _,
1620 Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
1621 notify_auto_render_trampoline::<Self, F> as *const (),
1622 )),
1623 Box_::into_raw(f),
1624 )
1625 }
1626 }
1627
1628 #[doc(alias = "context")]
1629 fn connect_context_notify<F: Fn(&Self) + 'static>(&self, f: F) -> SignalHandlerId {
1630 unsafe extern "C" fn notify_context_trampoline<P: IsA<GLArea>, F: Fn(&P) + 'static>(
1631 this: *mut ffi::GtkGLArea,
1632 _param_spec: glib::ffi::gpointer,
1633 f: glib::ffi::gpointer,
1634 ) {
1635 let f: &F = &*(f as *const F);
1636 f(GLArea::from_glib_borrow(this).unsafe_cast_ref())
1637 }
1638 unsafe {
1639 let f: Box_<F> = Box_::new(f);
1640 connect_raw(
1641 self.as_ptr() as *mut _,
1642 c"notify::context".as_ptr() as *const _,
1643 Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
1644 notify_context_trampoline::<Self, F> as *const (),
1645 )),
1646 Box_::into_raw(f),
1647 )
1648 }
1649 }
1650
1651 #[doc(alias = "has-depth-buffer")]
1652 fn connect_has_depth_buffer_notify<F: Fn(&Self) + 'static>(&self, f: F) -> SignalHandlerId {
1653 unsafe extern "C" fn notify_has_depth_buffer_trampoline<
1654 P: IsA<GLArea>,
1655 F: Fn(&P) + 'static,
1656 >(
1657 this: *mut ffi::GtkGLArea,
1658 _param_spec: glib::ffi::gpointer,
1659 f: glib::ffi::gpointer,
1660 ) {
1661 let f: &F = &*(f as *const F);
1662 f(GLArea::from_glib_borrow(this).unsafe_cast_ref())
1663 }
1664 unsafe {
1665 let f: Box_<F> = Box_::new(f);
1666 connect_raw(
1667 self.as_ptr() as *mut _,
1668 c"notify::has-depth-buffer".as_ptr() as *const _,
1669 Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
1670 notify_has_depth_buffer_trampoline::<Self, F> as *const (),
1671 )),
1672 Box_::into_raw(f),
1673 )
1674 }
1675 }
1676
1677 #[doc(alias = "has-stencil-buffer")]
1678 fn connect_has_stencil_buffer_notify<F: Fn(&Self) + 'static>(&self, f: F) -> SignalHandlerId {
1679 unsafe extern "C" fn notify_has_stencil_buffer_trampoline<
1680 P: IsA<GLArea>,
1681 F: Fn(&P) + 'static,
1682 >(
1683 this: *mut ffi::GtkGLArea,
1684 _param_spec: glib::ffi::gpointer,
1685 f: glib::ffi::gpointer,
1686 ) {
1687 let f: &F = &*(f as *const F);
1688 f(GLArea::from_glib_borrow(this).unsafe_cast_ref())
1689 }
1690 unsafe {
1691 let f: Box_<F> = Box_::new(f);
1692 connect_raw(
1693 self.as_ptr() as *mut _,
1694 c"notify::has-stencil-buffer".as_ptr() as *const _,
1695 Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
1696 notify_has_stencil_buffer_trampoline::<Self, F> as *const (),
1697 )),
1698 Box_::into_raw(f),
1699 )
1700 }
1701 }
1702
1703 #[cfg_attr(feature = "v4_12", deprecated = "Since 4.12")]
1704 #[doc(alias = "use-es")]
1705 fn connect_use_es_notify<F: Fn(&Self) + 'static>(&self, f: F) -> SignalHandlerId {
1706 unsafe extern "C" fn notify_use_es_trampoline<P: IsA<GLArea>, F: Fn(&P) + 'static>(
1707 this: *mut ffi::GtkGLArea,
1708 _param_spec: glib::ffi::gpointer,
1709 f: glib::ffi::gpointer,
1710 ) {
1711 let f: &F = &*(f as *const F);
1712 f(GLArea::from_glib_borrow(this).unsafe_cast_ref())
1713 }
1714 unsafe {
1715 let f: Box_<F> = Box_::new(f);
1716 connect_raw(
1717 self.as_ptr() as *mut _,
1718 c"notify::use-es".as_ptr() as *const _,
1719 Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
1720 notify_use_es_trampoline::<Self, F> as *const (),
1721 )),
1722 Box_::into_raw(f),
1723 )
1724 }
1725 }
1726}
1727
1728impl<O: IsA<GLArea>> GLAreaExt for O {}