### ----------------------------------------------------
### -- Gnome::Gtk3
### -- Licenses: Artistic-2.0
### -- Authors: Marcel Timmerman
### -- File: docs/content-docs/reference/Gdk3/Window.md
### ----------------------------------------------------
### -- Chunk 3 of 3
 favor of `g_object_set_data()`. However, for historical reasons GTK+ stores the **Gnome::Gdk3::Widget** that owns a **Gnome::Gdk3::Window** as user data on the **Gnome::Gdk3::Window**. So, custom widget implementations should use this function for that. If GTK+ receives an event for a **Gnome::Gdk3::Window**, and the user data for the window is non-`undefined`, GTK+ will assume the user data is a **Gnome::Gdk3::Widget**, and forward the event to that widget.

    method set-user-data ( Pointer $user_data )

  * $user_data; (type GObject.Object): user data

show
----

Like `show_unraised()`, but also raises the window to the top of the window stack (moves the window to the front of the Z-order).

This function maps a window so it’s visible onscreen. Its opposite is `hide()`.

When implementing a **Gnome::Gdk3::Widget**, you should call this function on the widget's **Gnome::Gdk3::Window** as part of the “map” method.

    method show ( )

show-unraised
-------------

Shows a **Gnome::Gdk3::Window** onscreen, but does not modify its stacking order. In contrast, `show()` will raise the window to the top of the window stack.

On the X11 platform, in Xlib terms, this function calls `XMapWindow()` (it also updates some internal GDK state, which means that you can’t really use `XMapWindow()` directly on a GDK window).

    method show-unraised ( )

show-window-menu
----------------

Asks the windowing system to show the window menu. The window menu is the menu shown when right-clicking the titlebar on traditional windows managed by the window manager. This is useful for windows using client-side decorations, activating it with a right-click on the window decorations.

Returns: `True` if the window menu was shown and `False` otherwise.

    method show-window-menu ( GdkEvent $event --> Bool )

  * $event; a **Gnome::Gdk3::Event** to show the menu for

stick
-----

“Pins” a window such that it’s on all workspaces and does not scroll with viewports, for window managers that have scrollable viewports. (When using **Gnome::Gdk3::Window**, `gtk_window_stick()` may be more useful.)

On the X11 platform, this function depends on window manager support, so may have no effect with many window managers. However, GDK will do the best it can to convince the window manager to stick the window. For window managers that don’t support this operation, there’s nothing you can do to force it to happen.

    method stick ( )

test-render-sync
----------------

Retrieves a pixel from window to force the windowing system to carry out any pending rendering commands.

This function is intended to be used to synchronize with rendering pipelines, to benchmark windowing system rendering operations.

    method test-render-sync ( )

test-simulate-button
--------------------

This function is intended to be used in GTK+ test programs. It will warp the mouse pointer to the given (x ,y ) coordinates within window and simulate a button press or release event. Because the mouse pointer needs to be warped to the target location, use of this function outside of test programs that run in their own virtual windowing system (e.g. Xvfb) is not recommended.

Also, gdk_test_simulate_button() is a fairly low level function, for most testing purposes, gtk_test_widget_click() is the right function to call which will generate a button press event followed by its accompanying button release event.

    method test-simulate-button (
      Int() $x, Int() $y, UInt() $button,
      GdkModifierType modifiers, GdkEventType $button_pressrelease
      --> Bool
    )

  * $x; x coordinate within window for the button event

  * $y; y coordinate within window for the button event

  * $button; Number of the pointer button for the event, usually 1, 2 or 3

  * modifiers; Keyboard modifiers the event is setup with

  * $button_pressrelease; either GDK_BUTTON_PRESS or GDK_BUTTON_RELEASE

test-simulate-key
-----------------

This function is intended to be used in GTK+ test programs. If (x ,y ) are > (-1,-1), it will warp the mouse pointer to the given (x ,y ) coordinates within window and simulate a key press or release event.

When the mouse pointer is warped to the target location, use of this function outside of test programs that run in their own virtual windowing system (e.g. Xvfb) is not recommended. If (x ,y ) are passed as (-1,-1), the mouse pointer will not be warped and window origin will be used as mouse pointer location for the event.

Also, gdk_test_simulate_key() is a fairly low level function, for most testing purposes, gtk_test_widget_send_key() is the right function to call which will generate a key press event followed by its accompanying key release event.

    method test-simulate-key (
      Int() $x, Int() $y, UInt $keyval,
      GdkModifierType $modifiers, GdkEventType $key_pressrelease
      --> Bool
    )

  * $x; x coordinate within window for the key event

  * $y; y coordinate within window for the key event

  * $keyval; A GDK keyboard value from **Gnome::Gdk3::Keysyms**

  * $modifiers; Keyboard modifiers the event is setup with

  * $key_pressrelease; either GDK_KEY_PRESS or GDK_KEY_RELEASE

thaw-updates
------------

Thaws a window frozen with `freeze_updates()`.

    method thaw-updates ( )

unfullscreen
------------

Moves the window out of fullscreen mode. If the window was not fullscreen, does nothing.

On X11, asks the window manager to move *window* out of the fullscreen state, if the window manager supports this operation. Not all window managers support this, and some deliberately ignore it or don’t have a concept of “fullscreen”; so you can’t rely on the unfullscreenification actually happening. But it will happen with most standard window managers, and GDK makes a best effort to get it to happen.

    method unfullscreen ( )

unmaximize
----------

Unmaximizes the window. If the window wasn’t maximized, then this function does nothing.

On X11, asks the window manager to unmaximize *window*, if the window manager supports this operation. Not all window managers support this, and some deliberately ignore it or don’t have a concept of “maximized”; so you can’t rely on the unmaximization actually happening. But it will happen with most standard window managers, and GDK makes a best effort to get it to happen.

On Windows, reliably unmaximizes the window.

    method unmaximize ( )

unstick
-------

Reverse operation for `stick()`; see `stick()`, and `gtk_window_unstick()`.

    method unstick ( )

withdraw
--------

Withdraws a window (unmaps it and asks the window manager to forget about it). This function is not really useful as `hide()` automatically withdraws toplevel windows before hiding them.

    method withdraw ( )

Signals
=======

There are two ways to connect to a signal. The first option you have is to use `register-signal()` from **Gnome::GObject::Object**. The second option is to use `connect-object()` directly from **Gnome::GObject::Signal**.

First method
------------

The positional arguments of the signal handler are all obligatory as well as their types. The named attributes `:$widget` and user data are optional.

    # handler method
    method mouse-event ( GdkEvent $event, :$widget ) { ... }

    # connect a signal on window object
    my Gnome::Gtk3::Window $w .= new( ... );
    $w.register-signal( self, 'mouse-event', 'button-press-event');

Second method
-------------

    my Gnome::Gtk3::Window $w .= new( ... );
    my Callable $handler = sub (
      N-GObject $native, GdkEvent $event, OpaquePointer $data
    ) {
      ...
    }

    $w.connect-object( 'button-press-event', $handler);

Also here, the types of positional arguments in the signal handler are important. This is because both methods `register-signal()` and `connect-object()` are using the signatures of the handler routines to setup the native call interface.

Supported signals
-----------------

### create-surface

The *create-surface* signal is emitted when an offscreen window needs its surface (re)created, which happens either when the window is first drawn to, or when the window is being resized. The first signal handler that returns a non-`undefined` surface will stop any further signal emission, and its surface will be used.

Note that it is not possible to access the window's previous surface from within any callback of this signal. Calling `gdk_offscreen_window_get_surface()` will lead to a crash.

Returns: the newly created **cairo_surface_t** for the offscreen window

    method handler (
      Int $width,
      Int $height,
      Int :$_handle_id,
      Gnome::GObject::Object :_widget($window),
      *%user-options
      --> Unknown type CAIRO_GOBJECT_TYPE_SURFACE
    );

  * $window; the offscreen window on which the signal is emitted

  * $width; the width of the offscreen surface to create

  * $height; the height of the offscreen surface to create

  * $_handle_id; the registered event handler id

Properties
==========

An example of using a string type property of a **Gnome::Gtk3::Label** object. This is just showing how to set/read a property, not that it is the best way to do it. This is because a) The class initialization often provides some options to set some of the properties and b) the classes provide many methods to modify just those properties. In the case below one can use **new(:label('my text label'))** or **.set-text('my text label')**.

    my Gnome::Gtk3::Label $label .= new;
    my Gnome::GObject::Value $gv .= new(:init(G_TYPE_STRING));
    $label.get-property( 'label', $gv);
    $gv.set-string('my text label');

Supported properties
--------------------

### Cursor: cursor

The mouse pointer for a **Gnome::Gdk3::Window**. See `set_cursor()` and `get_cursor()` for details.

    Widget type: GDK_TYPE_CURSOR

The **Gnome::GObject::Value** type of property *cursor* is `G_TYPE_OBJECT`.



