org.gnome.gtk
Class Widget

Object
  org.freedesktop.bindings.Pointer
      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

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:

UnsupportedOperationException - if the Widget is not activatable.

Since:

4.0.5

addEvents

public void addEvents(EventMask events)

Enable the given events. While most events are enabled by default, some need to be activated. Corresponding signal will document this procedure, if needed.

Take care that events are actually received by the underlying GDK Window resource being used. Such resource is in many cases shared by several Widgets, so enabling or disabling an event on one of these can affect all Widgets. If that is a problem for you, EventBox Widget can be used to ensure only it is affected by this method.

Since:

4.0.15

connect

public void connect(Widget.ButtonPressEvent handler)

Hook up a Widget.ButtonPressEvent handler.

Since:

4.0.6

connect

public void connect(Widget.ButtonReleaseEvent handler)

Hook up a Widget.ButtonReleaseEvent handler.

Since:

4.0.6

connect

public void connect(Widget.EnterNotifyEvent handler)

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

Since:

4.0.2

connect

public void connect(Widget.ExposeEvent handler)

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

Since:

4.0.7

connect

public void connect(Widget.FocusInEvent handler)

Hook up a handler to receive Widget.FocusInEvent signals.

Since:

4.0.6

connect

public void connect(Widget.FocusOutEvent handler)

Hook up a handler to receive Widget.FocusOutEvent events on this Widget

Since:

4.0.2

connect

public void connect(Widget.Hide handler)

Connect a Widget.Hide handler.

Since:

4.0.6

connect

public void connect(Widget.KeyPressEvent handler)

Hook up a handler to receive Widget.KeyPressEvent 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 Widget.KeyReleaseEvent.

Since:

4.0.3

connect

public void connect(Widget.KeyReleaseEvent handler)

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

Since:

4.0.3

connect

public void connect(Widget.LeaveNotifyEvent handler)

Hook up a handler to receive Widget.LeaveNotifyEvent signals.

Since:

4.0.7

connect

public void connect(Widget.MapEvent handler)

Hook up a Widget.MapEvent signal handler.

Since:

4.0.8

connect

public void connect(Widget.MotionNotifyEvent handler)

Hook up a Widget.MotionNotifyEvent handler.

Since:

4.0.15

connect

public void connect(Widget.PopupMenu handler)

Hookup a Widget.PopupMenu handler.

Since:

4.0.9

connect

public void connect(Widget.ScrollEvent handler)

Hook up a Widget.ScrollEvent handler.

Since:

4.0.12

connect

public void connect(Widget.UnmapEvent handler)

Connect a Widget.UnmapEvent handler.

Since:

4.0.5

connect

public void connect(Widget.VisibilityNotifyEvent handler)

Connect a Widget.VisibilityNotifyEvent 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

getCanDefault

public boolean getCanDefault()

Get the value of the can-default property. See setCanDefault() and grabDefault() for details.

Since:

4.0.8

getCanFocus

public boolean getCanFocus()

Get the value of the can-focus property. See setCanFocus() and grabFocus() for details.

Since:

4.0.8

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 Entry.Changed signal will fire when the first Entry's Entry.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

getName

public String getName()

Get the name of the Widget, if it has one.

Widgets can be identified by a name. You will most likely use this method a lot if you are using Glade. Every widget there is identified by a name. It is suggested to use sensible names; see Glade for a discussion of the implications of different nomenaclatures if that's what you are using, but in any case once you've retrieved the Widget with getWidget() you won't really need to know its name anymore.

Since:

4.0.11

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

getSensitive

public boolean getSensitive()

Is this Widget set to be sensitive?

The default is true of course.

The utility of this is somewhat limited, since it only returns the boolean value of this Widget's sensitive property, whereas whether a Widget is displayed sensitive (normal) or insensitive (grayed out) depends on both this property and the settings in the parent Widgets.

Since:

4.0.17

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.

While it is best to wait until the Widget is mapped to screen and user visible before manipulating underlying properties, there are rare cases when you need the [org.gnome.gdk] Window to be not-null before then; if so, you can call realize().

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

grabAdd

public void grabAdd()

Make this the current grabbed Widget. Interaction with other Widgets will be prevented. If this Widget is not sensitive, this call will do nothing.

Note that being the current grabbed widget means mouse and keyboard events will not be delivered to other widgets, so use this with care.

Since:

4.0.11

grabDefault

public void grabDefault()

Make this Widget attempt to become the default. The default Widget is the one which is activated when the user presses Enter .

This will only work if the Widget is activatable (see activate()) and if the Widget has its can-default property enabled with setCanDefault(). The Widget also needs to have already been packed into a hierarchy which tops out at a Window.

If you're reading this you may in fact be looking for grabFocus() which affects where keyboard input is going, as opposed to this method which affects activation.

Since:

4.0.8

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

grabRemove

public void grabRemove()

Removes the "grab" status from this Widget if it is currently grabbed, otherwise this does nothing. See grabAdd().

Since:

4.0.11

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

isSensitive

public boolean isSensitive()

Will this Widget be shown as sensitive or insensitive? This is based on both its sensitive property, and that of all its parents.

You don't need to use this ordinarily (it's GTK that needs to know!) but if you're curious, well, here you go.

Since:

4.0.17

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

modifyBase

public void modifyBase(StateType state,
                       Color color)

Set the colour used for text background on this Widget. To change the foreground colour of the text, use modifyText().

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.8

modifyFont

public void modifyFont(FontDescription desc)

Set the font used for text rendered by this Widget.

This is one of a family of "modify" methods.

Since:

4.0.10

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

queueDraw

public void queueDraw()

Request that the entire Widget be redrawn. See queueDrawArea() for full details, but you only ever need this if doing your own drawing.

Since:

4.0.10

queueDrawArea

public void queueDrawArea(int x,
                          int y,
                          int width,
                          int height)

Request that an area of the Widget to be redrawn. This will eventually result in an Widget.ExposeEvent being sent to the Widget asking it to [re]render the area given by the passed in co-ordinates.

You only ever need this if doing your own custom Widget drawing, and then only sometimes.

The redraw will not happen immediately, but rather during the next iteration of the main loop. Also, note that several such requests may be combined into a single Widget.ExposeEvent by the X server and GDK.

Be aware that this will invalidate both this Widget and all its children. If you wish to limit your redrawing, you will be better off with one of the invalidate() calls in the underlying native resource.

Since:

4.0.10

realize

public void realize()

Cause the resources underlying the Widget to be assigned. Among other things, this will populate the [org.gnome.gdk] Window that backs this Widget.

In general you don't want to be calling this. This is largely an internal method; while you can trigger realization manually you rarely need to. You do need to show the Widget with show() (or better yet showAll() on one of its parents) once you've built it.

Almost anything that you would do that would invole you needing an [org.gnome.gdk] Window is best done in a Widget.ExposeEvent handler, at which point the Widget is already realized, mapped, and showing.

Since:

4.0.16

setCanDefault

public void setCanDefault(boolean setting)

Whether this Widget is willing to be the default Widget. The can-default property, like can-focus, is mostly internal; while telling GTK that this Widget isn't the one that should activated on Enter isn't that useful, setting this sometimes has an effect on whether or not the theme will draw a dotted line (or other markup) around a Button to indicate that the Widget is the current default Widget.

Normally, this setting is false, though activatable Widgets will already have it true. Disabling can-default will mean that a grabDefault() on this Widget will be ignored.

Since:

4.0.8

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

setColormap

public void setColormap(Colormap colormap)

Sets the Colormap of this widget.

The only useful application of this is to enable per-pixel translucency on top level Widgets. This involves getting the RGBA colormap from the associated screen, and also requires (if using cairo) using the clear operator to remove the standard background.

Since:

4.0.10

setEvents

public void setEvents(EventMask events)

Reset the list of events for this Widget. You probably want addEvents(). If you use this, you'll need to or() together all the events that this Widget needs to function.

Since:

4.0.15

setName

public void setName(String name)

Every Widget has a name as an optional identifier.

If using Glade then these names are used to retrieve widgets from the XML file. You can use this method you set the name of a Widget after it is retrieved.

If you are using Glade then you will most likely never need this method, as you will have them defined in Glade. And if you're not using Glade, then you probably won't need this method either, since you can refer to Widgets you create by reference.

Since:

4.0.11

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(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(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

Overview  Package   Class		java-gnome
PREV CLASS   NEXT CLASS	FRAMES    NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD	DETAIL: FIELD | CONSTR | METHOD