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