org.gnome.gtk

## Class Window

- Object
- - org.freedesktop.bindings.Pointer
  - - org.freedesktop.bindings.Proxy
    - - org.gnome.glib.Object
      - - org.gnome.gtk.Widget
        - - org.gnome.gtk.Container
          - - org.gnome.gtk.Bin
            - - org.gnome.gtk.Window

- Direct Known Subclasses:
    Assistant, Dialog, OffscreenWindow, Plug

      public class Window
      extends Bin

  The top level Widget that contains other Widgets. Typical examples are application windows, dialog boxes, and popup menus.

  It is common to invoke `hide()` on a new top level Window immediately after instantiating it, as in:

       w = new Window();
       w.hide();
       ...
       // construct Widgets to create user interface and add to w
       ...
       w.showAll();

  this prevents the Window from being drawn as a small empty square and then resizing one or more times as its component Widgets are added to create the desired user interface during the initial cycles of the main loop.

  `hide()` is also important when Windows are being closed; see the comments in the description of `Window.DeleteEvent`.

  Since:
    4.0.0
  Author:
    Andrew Cowie, Srichand Pendyala, Sebastian Mancke

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static interface` | `Window.ConfigureEvent` Event emitted when the Window's size or position changes.
    `static interface` | `Window.DeleteEvent` This signal arises when a user tries to close a top level window.

    - ### Nested classes/interfaces inherited from class org.gnome.gtk.Widget

      `Widget.ButtonPressEvent, Widget.ButtonReleaseEvent, Widget.Destroy, Widget.Draw, Widget.EnterNotifyEvent, Widget.FocusInEvent, Widget.FocusOutEvent, Widget.Hide, Widget.KeyPressEvent, Widget.KeyReleaseEvent, Widget.LeaveNotifyEvent, Widget.MapEvent, Widget.MotionNotifyEvent, Widget.PopupMenu, Widget.QueryTooltip, Widget.ScrollEvent, Widget.SizeAllocate, Widget.UnmapEvent, Widget.VisibilityNotifyEvent`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `Window()` Create a new Window.
    `Window(WindowType type)` Create a new Window of the specified type.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `addAcceleratorGroup(AcceleratorGroup group)` Set the AcceleratorGroup object for this top level Window.
    `void` | `connect(Window.ConfigureEvent handler)` Hook up a `Window.ConfigureEvent` handler.
    `void` | `connect(Window.DeleteEvent handler)`
    `int` | `getHeight()` Get the height of the Window.
    `boolean` | `getMaximized()` Enquire whether or not this Window is maximized.
    `int` | `getPositionX()` Get the position of the Window frame (x co-ordinate).
    `int` | `getPositionY()` Get the position of the Window frame (y co-ordinate).
    `Screen` | `getScreen()` Get the Screen that this Window is on.
    `int` | `getWidth()` Get the width of the Window.
    `void` | `move(int x, int y)` Request that the Window be moved to the specified co-ordinates.
    `void` | `present()` Present the Window to the user.
    `void` | `resize(int width, int height)` Resize the Window to the given `width` and `height`.
    `void` | `setDecorated(boolean setting)` By default, Windows are decorated with a title bar, minimize/maximize/close buttons, a border, resize handles, etc.
    `void` | `setDefaultSize(int width, int height)` Sets the default size of a Window.
    `void` | `setFullscreen(boolean setting)` Request that the window manager to place the Window in the fullscreen state or return it to normal state.
    `void` | `setGravity(Gravity gravity)` Set the interpretation of co-ordinates passed to `move(int, int)` and returned by `getPosition()`.
    `void` | `setHasResizeGrip(boolean setting)` Toggle whether or not this Window is showing a resize grip at the bottom right of the drawn Window.
    `void` | `setIcon(Icon icon)` Set the icon image to be used for this Window.
    `void` | `setIcon(Pixbuf icon)` Set the icon image to be used for this Window.
    `void` | `setKeepAbove(boolean setting)` Request that this Window be kept on top of all other windows.
    `void` | `setKeepBelow(boolean setting)` Request that this Window be behind all other windows showing on the desktop.
    `void` | `setMaximize(boolean setting)` Request the window manager maximize (grow to cover the whole screen) or restore (return to normal) this Window.
    `void` | `setModal(boolean modal)` Set whether the Window is to be modal or not.
    `void` | `setPosition(WindowPosition position)` Set a new constraint for the position that the Window will be rendered on the screen.
    `void` | `setResizable(boolean setting)` Set whether the user can resize this Window.
    `void` | `setSkipPagerHint(boolean setting)` Request that GNOME not include this Window in pagers.
    `void` | `setSkipTaskbarHint(boolean setting)` Request that GNOME not include this Window in lists of open windows.
    `void` | `setStick(boolean setting)` Request that the Window be visible on all user workspaces.
    `void` | `setTitle(String title)` Sets the title that will be displayed in the Window's title bar.
    `void` | `setTransientFor(Window parent)` Make this Window as transient to another.
    `void` | `setTypeHint(WindowTypeHint hint)` Indicate to the window manager what type of use this Window will be put to.

    - ### Methods inherited from class org.gnome.gtk.Bin

      `getChild`

    - ### Methods inherited from class org.gnome.gtk.Container

      `add, getChildren, remove, setBorderWidth`

    - ### Methods inherited from class org.gnome.gtk.Widget

      `activate, addEvents, connect, connect, connect, connect, connect, connect, connect, connect, connect, connect, connect, connect, connect, connect, connect, connect, connect, connect, connect, destroy, getAllocatedHeight, getAllocatedWidth, getAllocation, getCanDefault, getCanFocus, getHasFocus, getName, getParent, getPreferredHeightForWidthMinimum, getPreferredHeightForWidthNatural, getPreferredHeightMinimum, getPreferredHeightNatural, getPreferredWidthForHeightMinimum, getPreferredWidthForHeightNatural, getPreferredWidthMinimum, getPreferredWidthNatural, getRequestMode, getRequisition, getSensitive, getStyleContext, getToplevel, getWindow, grabAdd, grabDefault, grabFocus, grabRemove, hide, isSensitive, overrideBackground, overrideColor, overrideFont, queueDraw, queueDrawArea, realize, setAlignHorizontal, setAlignVertical, setCanDefault, setCanFocus, setEvents, setExpandHorizontal, setExpandVertical, setName, setSensitive, setSizeRequest, setTooltipMarkup, setTooltipText, show, showAll`

    - ### Methods inherited from class org.freedesktop.bindings.Pointer

      `toString`

    - ### Methods inherited from class Object

      `equals, getClass, hashCode, notify, notifyAll, wait, wait, wait`

- - ### Constructor Detail

    - #### Window

          public Window()

      Create a new Window.

    - #### Window

          public Window(WindowType type)

      Create a new Window of the specified type. In general you don't need to use this; see the comments in `WindowType`; in particular, `POPUP` is not for dialog windows!
      Since:
        4.0.0

  - ### Method Detail

    - #### addAcceleratorGroup

          public void addAcceleratorGroup(AcceleratorGroup group)

      Set the AcceleratorGroup object for this top level Window. You'll need this to set key bindings for Menus and Actions. See `AcceleratorGroup` for help on how to set key bindings.
      Since:
        4.0.16

    - #### connect

          public void connect(Window.ConfigureEvent handler)

      Hook up a `Window.ConfigureEvent` handler.
      Since:
        4.0.8

    - #### connect

          public void connect(Window.DeleteEvent handler)

    - #### getHeight

          public int getHeight()

      Get the height of the Window.

      See `getWidth()` for a discussion of the problems that are inherent in using this method.

      Since:
        4.0.5

    - #### getMaximized

          public boolean getMaximized()

      Enquire whether or not this Window is maximized.

      While this is in the form of a getter, maximize is not a property, as such. This method only works (ie, reports `true`) if the Window is actually on the screen (ie has been mapped via a `show()` call), and really is currently maximized.

      In other words, this won't do you any good when initializing your program. It doesn't refer to a future state that will be realized in due course - which means, incidentally that it won't tell you if you already called `setMaximize(true)` to register your intent to have the window be maximized on presentation.

      Since:
        4.0.4

    - #### getPositionX

          public int getPositionX()

      Get the position of the Window frame (x co-ordinate). This is relative to the Window's gravity setting; since the default is `Gravity.NORTH_WEST` this usually means horizontal distance from the top-left corner, which is the normal usage on X displays.

      Apparently this is not entirely reliable; X itself does not provide an authoritative means to determine the dimensions of any decorations the window manager might have applied around a Window, and so GTK does its best to guess the necessary adjustments that "should work with sane window managers". We leave it as an exercise to the reader to define sanity.

      Since:
        4.0.4

    - #### getPositionY

          public int getPositionY()

      Get the position of the Window frame (y co-ordinate). See `getPositionX()` for details.
      Since:
        4.0.4

    - #### getScreen

          public Screen getScreen()

      Get the Screen that this Window is on.

    - #### getWidth

          public int getWidth()

      Get the width of the Window.

      There are some problems with using this:

      - If the Window hasn't been mapped to the screen yet then you will get GTK's current estimate of what it expects to the geometry of the Window might be. This is still highly dependent on what the window manager and the X server actually end up agreeing to allocate.
      - People frequently call this because they want to manually position the Window. In GNOME we discourage doing this. It is the window manager's job to position things, and this reflects among other things accessibility and user preference. Also, GTK is unable to take into account the size of any window decorations that may be present. Use `setPosition()`!
      - If you need to take a dynamic size dependent action you should hook up to the `Window.ConfigureEvent` signal which has more accurate information and which will allow you to react appropriately. If you instead use this you will be subject to a race condition as the size of the Window may change between you calling this method and taking action based on the returned value.
      In other words, although this method can be useful for debugging, it's mostly here to tell you what to use instead.
      Since:
        4.0.5

    - #### move

          public void move(int x,
                  int y)

      Request that the Window be moved to the specified co-ordinates. As with other Window operations, the window manager running on the display may or may not service the request; in particular you sometimes find that initial placement is overridden by the window manager.

      `x` and `y` are in pixels.

      Chances are `setPosition()` will do what you want more easily than manually moving the Window.

      The co-ordinates `x`, `y` are with respect to the reference point specified by the "gravity" in effect for this Window; since the default is `NORTH_WEST` , x and y mean what you want them to: horizontal and vertical distance of the top-left corner of the Window from the top-left corner, respectively.

      Since:
        4.0.4

    - #### present

          public void present()

      Present the Window to the user. This will raise the window to the top of the stack, deiconify it, and even bring it to the current virtual workspace (all depending, as ever, on how co-operative your window manager is). This is also invokes the equivalent of `show()` to [re]map the Window.

      This method is ideal for cases where a Window is already showing somewhere and you need to [re]present it to the user. It's also what you should use if you have already called `show()` to force the Window to map but then immediately called `hide()` while you finished building the Window.

      Since:
        4.0.5

    - #### resize

          public void resize(int width,
                    int height)

      Resize the Window to the given `width` and `height`.

      The size specified here needs to meet or exceed the current aggregate size request for this Window as determined by the children packed into it. If that's a problem, then influence the size request with `setSizeRequest()`.

      If you call this before the Window is realized, then the settings provided here will override those specified with `setDefaultSize()`.

      Since:
        4.0.8

    - #### setDecorated

          public void setDecorated(boolean setting)

      By default, Windows are decorated with a title bar, minimize/maximize/close buttons, a border, resize handles, etc. This isn't done by your program, though - it's automatically by the window manager which is a part of your desktop. Some window managers allow GTK to disable these decorations, creating a borderless window. If you set the decorated property to `false` using this method, GTK will do its best to convince the window manager not to decorate the Window.

      - You will have no problem creating undecorated Windows on a GNOME desktop.
      - Apparently, turning off decorations will not work if the Window is already visible on some systems. So if you're going to use `setDecorated(false)`, call it before invoking `show()` on the Window.
      Since:
        4.0.0

    - #### setDefaultSize

          public void setDefaultSize(int width,
                            int height)

      Sets the default size of a Window. If the Window's "natural" size (the size request resulting from the aggregate requests of all the Widgets contained in this Window) is larger than the default, the default will be ignored. The default size of a Window only affects the first time a Window is shown; if a Window is hidden and re-shown, it will remember the size it had prior to hiding, rather than using the default size.

      Depending on your needs, `resize()` could be more appropriate, especially if the Window is already realized. `resize()` changes the current size of the Window, rather than the size to be used on initial display which is what this method is for.

      You probably want to call this after you've done the bulk of your packing.

      Incidentally, Windows can't be 0x0; the minimum size is 1x1.

      Parameters:
        `width` - The default minimum width you'd like to set. A value of 0 will be silently bumped to 1. A value of -1 will unset any previous default width setting.
        `height` - Same.
      Since:
        4.0.1

    - #### setFullscreen

          public void setFullscreen(boolean setting)

      Request that the window manager to place the Window in the fullscreen state or return it to normal state.

      Note that you shouldn't assume the Window is definitely fullscreen (or restored) afterwards because other entities (e.g. the user or window manager itself) could toggle it again. Further, not all window managers honour requests to fullscreen windows. Be prepared for these eventualities.

      Parameters:
        `setting` - `true` to request fullscreen mode, `false` to request that the window be returned to normal management.
      Since:
        4.0.4

    - #### setGravity

          public void setGravity(Gravity gravity)

      Set the interpretation of co-ordinates passed to `move(int, int)` and returned by `getPosition()`.

      The window manager specification has long been notorious for not actually being a spec; it's more a collection of guesses, assumptions, and outright lies. Unsurprisingly, then, even a window manager that wants to do the right thing can't get it right because there isn't actually a correct answer. Gravity is a case in point, apparently. You might as well consider that things are broken and stick with the default, NORTH_WEST. If you insist on using this anyway, keep in mind that users may experience widely varying results.

      Since:
        4.0.4

    - #### setHasResizeGrip

          public void setHasResizeGrip(boolean setting)

      Toggle whether or not this Window is showing a resize grip at the bottom right of the drawn Window. While ordinarily you'd want to leave this alone, a resize grip will displace a right-hand Scrollbar and may need to be removed for visual consistency. Note that when maximized, windows will not have resize grips.
      Since:
        4.1.1

    - #### setIcon

          public void setIcon(Icon icon)

      Set the icon image to be used for this Window. The icon will appear in the window switcher (what appears when you press `Alt+Tab`).
      Since:
        4.1.1

    - #### setIcon

          public void setIcon(Pixbuf icon)

      Set the icon image to be used for this Window. The icon will appear in the window switcher (what appears when you press `Alt+Tab`), window list applet and, in most themes, as an identifying image in the top left corner of the window title bar.

      Most often you will simply create an image with `Pixbuf(filename)` and pass it in.

      A 48x48 PNG image is generally the optimal size to work with; you rarely need icons larger but a lower resolution image will be forced to scale up with the usual poor quality result.

      You should specify the image in its natural form, whatever that is, as GTK itself will scale the image depending on the various sizes it is called upon to provide by the theme engine and the window manager.

      Since:
        4.0.5

    - #### setKeepAbove

          public void setKeepAbove(boolean setting)

      Request that this Window be kept on top of all other windows.

      Note that the request to apply the "keep above" state may be overridden or ignored by the window manager. Likewise, the user may toggle this state between the program requesting it and the program subsequently proceeding on the expectation that it is set. As a result you should not write code that assumes this request has been successful.

      The window manager specifications are fairly explicit that these settings are a user preference. In particular, "keep above" should not be used as a gimmick to attempt to draw attention to a Window.

      Usability note: while it always seems like such a good idea to put your favourite window on top of everything else, in practise this can pale. You will find that your current "favourite" changes frequently, and not being able to rely on the normal window management behaviour to bring whatever you are now working on over top of the Window you have kept above will quickly result in you being annoyed that you can't get rid if it. All the usual arguments against modal windows also apply.

      Since a proper window manager like `Metacity` gives you quick and immediate access to the "keep on top" mode via a right click on the Window's title bar decoration, you really only should need this on the rare occasions when you have turned off decorations. So yes, there are are legitimate uses for this, but they are few and far between.

      Parameters:
        `setting` - `true` to request keep above be on, `false` to request normal behaviour.
      Since:
        4.0.4

    - #### setKeepBelow

          public void setKeepBelow(boolean setting)

      Request that this Window be behind all other windows showing on the desktop.

      You can call this before `show()`ing a Window, in which case the initial presentation will be behind other windows.

      The caveats and notes discussed in `setKeepAbove()` apply here. Once again, while there are legitimate uses for this method, please think about the impact on user's overall desktop experience before employing it.

      Parameters:
        `setting` - `true` to request this Window be kept behind all other windows on the desktop, `false` for normal behaviour.
      Since:
        4.0.4

    - #### setMaximize

          public void setMaximize(boolean setting)

      Request the window manager maximize (grow to cover the whole screen) or restore (return to normal) this Window.

      The difference between this and `setFullscreen(true)` is that a maximized Window still has the title at the top of the screen (along with other window decorations, depending on the theme), and the panel(s) are still visible; a fullscreen window is over top of everything. While there are legitimate uses for both, maximizing is somewhat preferable since it does not obscure the panels.

      The default for new Windows in ordinary circumstances is that they are not maximized.

      Note that maximizing is generally done by the user via the global `Alt+F10` accelerator or the `[□]` button in the window title bar. The only reason to call this programmatically is if restoring the application to the maximized state in order to maintaining the user's preference from a previous run of the program. You can accordingly call this method before a Window is mapped to indicate to the Window manager that you want it to be maximized when shown.

      As with all the other window manager operations, this is a request and may or may not be honoured by the window manager depending on what constraints it is operating under.

      Since:
        4.0.4

    - #### setModal

          public void setModal(boolean modal)

      Set whether the Window is to be modal or not. Modal Windows prevent interaction with other application Windows.

      Non-modal Windows give user more flexibility to perform other tasks within your application in any order she or he wants. Leaving Windows non-modal is thus preferred. Making a Window modal should only be done when the application really requires user to not interact with other Windows. Its main usage is in critical Dialogs where an urgent response from the user is required.

      If you make a Window modal, you should provide a clear way to close the Window, such as "Close" or "Cancel" Button.

      Finally, it is convenient to make modal Windows to be transient for the parent, by calling `setTransientFor()`. That way, the modal Window will be always on top, even if the user tries to interact with the parent, which is a good way to indicate to them that they must close the modal Window before going on. Usage of modal Windows without marking them transient leads to a severe usability problem: if the user tries to interact with the parent Window when the modal Window is hidden below that parent, the situation will appear as if the application is frozen.

      Parameters:
        `modal` - `true` to make the Window modal. The default is `false`.
      Since:
        4.0.5

    - #### setPosition

          public void setPosition(WindowPosition position)

      Set a new constraint for the position that the Window will be rendered on the screen. Note that this is not always honoured by window managers, but it's a good start.

      Somewhat unusually, if the new value for `position` is `CENTER_ALWAYS`, then this call will also result in the Window being moved to the new centered position.

      Since:
        4.0.3
      See Also:
        `WindowPosition`

    - #### setResizable

          public void setResizable(boolean setting)

      Set whether the user can resize this Window. Windows are resizable by default.

      You'd probably best have a very good reason for suppressing this. GTK's box packing model and size request/size allocation cycle will draw a Window at the optimum size necessary for all the Widgets packed into it to fit and so that all text labels draw properly, etc. That said, sometimes a user wants to see more of a certain column or to expand the area given to the Window so that some dynamic element within (perhaps an image) will scale larger. It is very frustrating for a user to find that the developer has prohibited them from doing such things.

      Since:
        4.0.6

    - #### setSkipPagerHint

          public void setSkipPagerHint(boolean setting)

      Request that GNOME not include this Window in pagers. Pagers are applets and other utilities which show thumbnails of windows as an aide to navigation and switching. The "Workspace Switcher" applet included with `gnome-panel` is a pager.

      If you're trying to keep this Window off of the list of windows shown as buttons in a panel, then you're probably looking for `setSkipTaskbarHint()` instead, although this can be a nice touch too.

      Note that if the WindowTypeHint of a Window has been set appropriately, you will not need to call this. Therefore use `setTypeHint()` instead.

      Since:
        4.0.8

    - #### setSkipTaskbarHint

          public void setSkipTaskbarHint(boolean setting)

      Request that GNOME not include this Window in lists of open windows. These are notably the "Window List" and "Window Selector" applets included with `gnome-panel` and the on-screen-display popup presented by the window manager. This is useful when creating special purpose auxiliary windows that are not the main program.

      Like other "hint" setting methods, this is only a request to the external environment and could potentially be ignored.

      You may also need `setSkipPagerHint()`.

      Note that if the WindowTypeHint of a Window has been set appropriately, you will not need to call this. Therefore use `setTypeHint()` instead.

      Since:
        4.0.8

    - #### setStick

          public void setStick(boolean setting)

      Request that the Window be visible on all user workspaces.

      Many window managers provide the concept of "workspaces" or "virtual desktops" whereby the user can switch from one to another and use this as a means of organizing their work. Ordinarily, an application's Windows will only show in the workspace they appeared in (or to which they were moved by the user). By calling `setStick(true)`, the Window will always be visible, regardless of which workspace is switched to. While not all window managers have this capability, in general this will work.

      Note that the request to stick may not succeed, or may subsequently be reversed by the user.

      Some desktops show a thumbnail of each workspace and when a window is stuck, it will "appear" in each workspace thumbnail. This does not mean there are suddenly four copies of your application running or anything silly like that.

      Parameters:
        `setting` - `true` to request the Window be stuck, `false` to request a return to the normal default state.
      Since:
        4.0.4

    - #### setTitle

          public void setTitle(String title)

      Sets the title that will be displayed in the Window's title bar.

      The title of a Window is an important usability factor. It should help the user distinguish this Window from others they may have open - and that gets tough when many, many applications are running. The key is to get the most relevant information is first. Examples of good titles are:

      - Invoice.odt
      - Invoice.odt - OpenOffice
      - andrew@procyon:~/src
      - Audio Configuration

      This is important because the list of Windows titles the user is looking at may have been truncated with the result that you can't tell the difference between different Windows of the same application. For example, these are no good if you can only see the first 20 characters of the title:

      - OpenOffice 2.0.4 brought to you by the letter B! - Invoice.odt
      - OpenOffice 2.0.4 brought to you by the letter B! - LoveLetter.odt

      Don't forget that Windows also have an icon, and that icon will show in the list too, so you don't even really need the application name - leaving more room for the details that help identify this Window uniquely.

      Since:
        4.0.0
      See Also:
        GNOME Human Interface Guidelines

    - #### setTransientFor

          public void setTransientFor(Window parent)

      Make this Window as transient to another. When marked this way, the window manager will keep the Window above the parent, even if the user tries to interact with the parent.

      This is specially useful with modal Windows; see `setModal()`.

      Parameters:
        `parent` - The Window this will be transient for, or `null` to prevent this Window for being treated as transient (that's the default, so you only need to call this when explicitly setting a Window as transient).
      Since:
        4.0.5

    - #### setTypeHint

          public void setTypeHint(WindowTypeHint hint)

      Indicate to the window manager what type of use this Window will be put to. While the default is `NORMAL`, you may find the greatest utility from calling this with the `UTILITY` hint.
      Since:
        4.0.8