org.gnome.gtk
Class Widget

java.lang.Object
  org.freedesktop.bindings.Proxy
      org.gnome.glib.Object
          org.gnome.gtk.Object
              org.gnome.gtk.Widget

Direct Known Subclasses:

Calendar, CellView, Container, DrawingArea, Entry, Misc, ProgressBar, Range, Ruler, Separator

public abstract class Widget
extends Object

The base class of all GTK Widgets. Graphical user interface toolkits have long been built up from individual controls and presentation mechanisms that are nested together. These elements are collectively called Widgets. Quite a lot of Widgets contain other Widgets; those are called Containers.

Since:

4.0.0

Author:

Andrew Cowie, Vreixo Formoso

Nested Class Summary

static interface	Widget.BUTTON_PRESS_EVENT Signal fired when the user clicks one of their mouse buttons.
static interface	Widget.BUTTON_RELEASE_EVENT The signal emitted when the user releases a pressed mouse button.
static interface	Widget.ENTER_NOTIFY_EVENT Signal emitted when the mouse enters the Widget.
static interface	Widget.EXPOSE_EVENT The signal emitted when a portion or all of the Widget has been exposed and needs [re]drawing.
static interface	Widget.FOCUS_IN_EVENT Signal emitted when focus enters this Widget.
static interface	Widget.FOCUS_OUT_EVENT Signal emitted when the keyboard focus leaves this Widget.
static interface	Widget.HIDE The signal emitted when a Widget is hidden.
static interface	Widget.KEY_PRESS_EVENT Handler interface for key press events.
static interface	Widget.KEY_RELEASE_EVENT Handler interface for key release events.
static interface	Widget.LEAVE_NOTIFY_EVENT Signal emitted when the mouse pointer leaves the Widget.
static interface	Widget.UNMAP_EVENT The signal emitted when a Window becomes invisible.
static interface	Widget.VISIBILITY_NOTIFY_EVENT A signal providing notification that the Widget has been obscured or unobscured.

Method Summary

void	activate() Cause this Widget to be activated.
void	connect(Widget.BUTTON_PRESS_EVENT handler) Hook up a BUTTON_PRESS_EVENT handler.
void	connect(Widget.BUTTON_RELEASE_EVENT handler) Hook up a BUTTON_RELEASE_EVENT handler.
void	connect(Widget.ENTER_NOTIFY_EVENT handler) Hook up a handler to receive ENTER_NOTIFY_EVENT signals on this Widget.
void	connect(Widget.EXPOSE_EVENT handler) Hook up a handler to receive EXPOSE_EVENT signals on this Widget.
void	connect(Widget.FOCUS_IN_EVENT handler) Hook up a handler to receive FOCUS_IN_EVENT signals.
void	connect(Widget.FOCUS_OUT_EVENT handler) Hook up a handler to receive FOCUS_OUT_EVENT events on this Widget
void	connect(Widget.HIDE handler) Connect a HIDE handler.
void	connect(Widget.KEY_PRESS_EVENT handler) Hook up a handler to receive KEY_PRESS_EVENT signals on this Widget.
void	connect(Widget.KEY_RELEASE_EVENT handler) Hook up a handler to receive KEY_RELEASE_EVENT signals on this Widget
void	connect(Widget.LEAVE_NOTIFY_EVENT handler) Hook up a handler to receive LEAVE_NOTIFY_EVENT signals.
void	connect(Widget.UNMAP_EVENT handler) Connect a UNMAP_EVENT handler.
void	connect(Widget.VISIBILITY_NOTIFY_EVENT handler) Connect a VISIBILITY_NOTIFY_EVENT handler.
Allocation	getAllocation() Get the details of the rectangle that represents the size that the windowing system down to GTK on down to the parent containers of this Widget have allocated to it.
boolean	getHasFocus() Does this Widget currently have the keyboard focus?
Container	getParent() Return the Container that this Widget is packed into.
Requisition	getRequisition() Get the size that will be (is being) requested by this Widget.
Widget	getToplevel() Get the Widget at the top of the container hierarchy to which this Widget belongs.
Window	getWindow() Get the underlying resource being used to power display of, and interaction with, this Widget.
void	grabFocus() Make this Widget have the keyboard focus for the Window it is within.
void	hide() Hide the Widget, making it invisible to the user.
void	modifyBackground(StateType state, Color color) Adjust the background colour being used when drawing this Widget.
void	modifyText(StateType state, Color color) Set the colour used for text rendered by this Widget.
void	setCanFocus(boolean setting) Whether the Widget can (is willing to) accept the keyboard input focus.
void	setSensitive(boolean sensitive) Set whether the Widget is greyed out or not.
void	setSizeRequest(int width, int height) Set the minimum size that will be requested by this Widget of its parent Container.
void	setTooltipMarkup(java.lang.String markup) Tooltips are notes that will be displayed if a user hovers the mouse pointer over a Widget.
void	setTooltipText(java.lang.String text) Tooltips are notes that will be displayed if a user hovers the mouse pointer over a Widget.
void	show() Cause this Widget to be mapped to the screen.
void	showAll() Cause this Widget, and any Widgets it contains, to be mapped to the screen.

Methods inherited from class org.freedesktop.bindings.Proxy

toString

Methods inherited from class java.lang.Object

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

Method Detail

activate

public void activate()

Cause this Widget to be activated. This has the same effect as when the user presses the Return key while the Widget is in focus. Calling this method on a ToggleButton will toggle its state, for example. Whatever signals would normally result from the user activating this Widget by hand will be emitted.

Note that this method only works if this Widget is activatable; not all are, making this more an optional characteristic that some, but not all Widgets share.

The Widget must already be showing on the screen for this method to work (ie, you must invoke show() before you can activate() it). Parent Containers must also have been shown.

Throws:

java.lang.UnsupportedOperationException - if the Widget is not activatable.

Since:

4.0.5

connect

public void connect(Widget.BUTTON_PRESS_EVENT handler)

Hook up a BUTTON_PRESS_EVENT handler.

Since:

4.0.6

connect

public void connect(Widget.BUTTON_RELEASE_EVENT handler)

Hook up a BUTTON_RELEASE_EVENT handler.

Since:

4.0.6

connect

public void connect(Widget.ENTER_NOTIFY_EVENT handler)

Hook up a handler to receive ENTER_NOTIFY_EVENT signals on this Widget.

Since:

4.0.2

connect

public void connect(Widget.EXPOSE_EVENT handler)

Hook up a handler to receive EXPOSE_EVENT signals on this Widget.

Since:

4.0.7

connect

public void connect(Widget.FOCUS_IN_EVENT handler)

Hook up a handler to receive FOCUS_IN_EVENT signals.

Since:

4.0.6

connect

public void connect(Widget.FOCUS_OUT_EVENT handler)

Hook up a handler to receive FOCUS_OUT_EVENT events on this Widget

Since:

4.0.2

connect

public void connect(Widget.HIDE handler)

Connect a HIDE handler.

Since:

4.0.6

connect

public void connect(Widget.KEY_PRESS_EVENT handler)

Hook up a handler to receive KEY_PRESS_EVENT signals on this Widget. For general typing this is the one you want, but for critical events (like pressing Enter to activate a Button that is going to delete things, you might want to postpone action until KEY_RELEASE_EVENT.

Since:

4.0.3

connect

public void connect(Widget.KEY_RELEASE_EVENT handler)

Hook up a handler to receive KEY_RELEASE_EVENT signals on this Widget

Since:

4.0.3

connect

public void connect(Widget.LEAVE_NOTIFY_EVENT handler)

Hook up a handler to receive LEAVE_NOTIFY_EVENT signals.

Since:

4.0.7

connect

public void connect(Widget.UNMAP_EVENT handler)

Connect a UNMAP_EVENT handler.

Since:

4.0.5

connect

public void connect(Widget.VISIBILITY_NOTIFY_EVENT handler)

Connect a VISIBILITY_NOTIFY_EVENT handler.

Since:

4.0.5

getAllocation

public Allocation getAllocation()

Get the details of the rectangle that represents the size that the windowing system down to GTK on down to the parent containers of this Widget have allocated to it. Note that the Widget must already have been realized for the request-allocation cycle to have taken place (ie, the top level Window and all its children must have been show()n. In some circumstances the main loop may need to have iterated).

Since:

4.0.6

getHasFocus

public boolean getHasFocus()

Does this Widget currently have the keyboard focus?

This can be quite useful when one Widget takes action in a signal handler which changes the state of another Widget. Take for example two related Entry Widgets. The second Entry's CHANGED signal will fire when the first Entry's CHANGED handler calls second.setText(); if it changes the first Entry then you have an infinite loop on your hands. By checking for has-focus at the beginning of both handlers, then only the Widget that the user changed will carry out it's logic; the other will realize it doesn't have focus and can quickly pass.

Since:

4.0.6

getParent

public Container getParent()

Return the Container that this Widget is packed into. If the Widget doesn't have a parent, or you're already at a top level Widget (ie, a Window) then expect null.

Since:

4.0.2

getRequisition

public Requisition getRequisition()

Get the size that will be (is being) requested by this Widget.

In addition to getting the Requisition object for this Widget, this method will also ask the Widget to actually calculate its requirements. This can be a relatively expensive operation as font metrics need to be worked out relative to the Display's physical characteristics (this implies that the request calculation won't have any effect if the Widget is not yet been FIXME to a Screen).

Implementation note: calling this method will invoke gtk_widget_size_request(). The returned Requisition object is "live" however, so once you've got it you can use its getter methods freely without needing to keep calling this method.

Since:

4.0.6

getToplevel

public Widget getToplevel()

Get the Widget at the top of the container hierarchy to which this Widget belongs.

It's is somewhat common to want to find the ultimately enclosing top level Window that this Widget belongs to. Assuming that the Widget has actually been packed into a Container hierarchy that tops out at a Window (or Dialog, etc) then that is what you'll get. So yes, you can do:

 w = (Window) obj.getToplevel();
 

as you'll get a ClassCastException or NullPointerException if you're wrong about obj being in a Window yet.

To manually walk up the hierarchy one level at a time, use getParent().

Returns:

Will return this if the Widget isn't (yet) in a hierarchy.

Since:

4.0.6

getWindow

public Window getWindow()

Get the underlying resource being used to power display of, and interaction with, this Widget.

If you're looking for the top Window in a Widget hierarchy, see getToplevel(). This method is to get a reference to the lower level GDK mechanisms used by this Widget, not to navigate up a hierarchy of Widgets to find the top-level Window they are packed into.

If what you need are the event handling facilities that go with Widgets that have their own native resources, consider creating an EventBox and putting this Widget into it.

If you call this in a class where you're building Windows, then you will probably end up having to use the fully qualified name org.gnome.gdk.Window when declaring variables. That's an unavoidable consequence of the class mapping algorithm we used: GdkWindow is the name of the underlying type being returned, and so Window it is.

Returns:

the org.gnome.gdk.Window associated with this Widget, or null if this Widget is (as yet) without one.

Since:

4.0.4

grabFocus

public void grabFocus()

Make this Widget have the keyboard focus for the Window it is within.

Obviously, if this is going to actually have affect, this Widget needs to be in a Window. Furthermore, the Widget needs to be able to take input focus, that is, it must have the can-focus property set (which is inherent to the particular Widget subclass, not something you can change).

Since:

4.0.6

hide

public void hide()

Hide the Widget, making it invisible to the user. This can be used to "deactivate" sections of your UI, pending some activity or action that will cause it to be returned to the Window. Note that hiding does not remove it from its parent Container - it just makes the Widget invisible for the time being.

You can call show() to make a hidden Widget visible [again].

Since:

4.0.4

modifyBackground

public void modifyBackground(StateType state,
                             Color color)

Adjust the background colour being used when drawing this Widget. This leaves all other style properties unchanged.

If you need to change the background colour behind the text in an Entry or TextView, see modifyBase().

This is one of a family of "modify" methods; see modifyStyle() for further details about the interaction of the various theming and style mechanisms.

Since:

4.0.5

modifyText

public void modifyText(StateType state,
                       Color color)

Set the colour used for text rendered by this Widget. This is the foreground colour; to change the background colour behind text use modifyBase().

This is one of a family of "modify" methods; see modifyStyle() for further details about the interaction of the various theming and style mechanisms.

Since:

4.0.6

setCanFocus

public void setCanFocus(boolean setting)

Whether the Widget can (is willing to) accept the keyboard input focus. There's no default, as such; Widgets able to take keyboard focus will (already) have it true, and others not. The can-focus property is mostly internal, but it is occasionally useful to use a widget that can focus in an environment where you don't want it to take input. Calling setCanFocus(false) will do the trick.

Since:

4.0.6

setSensitive

public void setSensitive(boolean sensitive)

Set whether the Widget is greyed out or not. Being insensitive is the term GTK uses for a Widget that is still in its parent layout and still visible on the screen, but no longer responding to user input and de-emphasized on the screen.

This is frequently used on Buttons and MenuItems to show that a given course of action is not currently available, but would be if the user did something different to the application. This can be a terrific hint to assist with discovery, but can be overdone; having everything insensitive and leaving the user no idea what to do next doesn't really help much.

Beware that setting the sensitive property cascades down through the hierarchy of any children packed into this Widget in the same way that showAll() is recursive. While this is usually great for desensitizing an entire Window, the catch is that if you resensitize that same Window every Widget within it will return to being sensitive; there's no "memory" of which might have been insensitive before. Thus if you heavily use a mix of sensitive and insensitive states in a Window and desensitize the whole thing while carrying out input validation in a worker thread, you will be left with the task of manually restoring the sensitive state of the various sub components of your UI should you need to return back to that Window to have the user re-enter something.

Parameters:

sensitive - true to have the Widget respond as normal, and false to de-activate the Widget and have it "grey out".

Since:

4.0.4

setSizeRequest

public void setSizeRequest(int width,
                           int height)

Set the minimum size that will be requested by this Widget of its parent Container.

A major feature of GTK is its adaptability in the face of different languages, fonts, and theme engines, with all of these factors impacting the number of pixels that will be necessary for drawing. The box packing model has each Widget request the size it calculates it needs at runtime of its parent. These requests flow up the Containers the Widget is packed into, with each Container collating the requests from its children. When it reaches the toplevel, GTK negotiates with the X server, and the result is the size allocation for the Window as a whole. The Window proceeds to inform each Container packed into it how much space it has been allocated, leaving it to the Containers to in turn allocate space to each of its children.

The whole point of all this is that in general you are not supposed to interfere with this process. It is virtually impossible to calculate the correct size for a Widget on a given user's desktop ahead of time, so don't try. This method is here for the unusual cases where you need to force a Widget to be a size other than what the default request-allocation process results in.

See Requisition and Allocation for further discussion of how the size-request/size-allocation process works and how you can get insight into it.

A value of -1 for either width or height will cause that dimension to revert to the "natural" size, that is, the size that would have been requested if you'd left things alone.

Passing 0,0 is a special case, meaning "as small as possible". This will have varying results and may not actually have much effect.

Incidentally, use setDefaultSize() for top level Windows, as that method still allows a user to make the Window smaller than the specified default.

Since:

4.0.6

setTooltipMarkup

public void setTooltipMarkup(java.lang.String markup)

Tooltips are notes that will be displayed if a user hovers the mouse pointer over a Widget. They are usually used with controls such as Buttons and Entries to brief the user about that Widget's function.

Parameters:

markup - The string with Pango markup you wish to be displayed when if the tooltip is popped up.

Since:

4.0.7

setTooltipText

public void setTooltipText(java.lang.String text)

Tooltips are notes that will be displayed if a user hovers the mouse pointer over a Widget. They are usually used with controls such as Buttons and Entries to brief the user about that Widget's function.

Parameters:

text - The string of plain text (i.e. without any Pango markup) you wish to be displayed when if the tooltip is popped up.

Since:

4.0.4

show

public void show()

Cause this Widget to be mapped to the screen. Flags a widget to be displayed. Any widget that isn't shown will not appear on the screen.

There are a bunch of quirks you need to be aware of:

• You have to show the Containers containing a Widget, in addition to the Widget itself, before it will appear on the display.
• When a toplevel Container is shown (ie, your Window), it is immediately realized and mapped, and any Widgets within it that are shown are then realized and mapped.
• You can't get information about the actual size that has been allocated to a Widget until it gets mapped to the screen.

If you want to show all the widgets in a container, it's actually much easier to just call showAll() on the container, rather than calling show manually one each individual Widget you've added to it.

Since:

4.0.0

showAll

public void showAll()

Cause this Widget, and any Widgets it contains, to be mapped to the screen. You typically call this on a Window after you've finished all the work necessary to set it up.

Quite frequently you also want to cause a Window to appear on the screen as well (ie, not be buried under a whole bunch of other applications' Windows), so calling Window's present() is usually next.

Don't be surprised if this takes a few hundred milliseconds. Realizing and mapping all the zillion elements that ultimately make up a Window is one of the most resource intensive operations that GTK, GDK, Pango, your X server, and your kernel have to churn through. Sometimes, you just gotta wait.

Since:

4.0.0