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:

  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.Destroy handler)

  Hook up a Widget.Destroy handler.

  Since:

  4.0.20

• connect

  public void connect(Widget.Draw handler)

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

  Since:

  4.0.20

• 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.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.QueryTooltip handler)

  Connect a tooltip query to the widget. This will cause the widget to be be monitored for motion and leave notifications. Also note that this cannot be turned off.

  Since:

  4.1.3

• connect

  public void connect(Widget.ScrollEvent handler)

  Hook up a Widget.ScrollEvent handler.

  Since:

  4.0.12

• connect

  public void connect(Widget.SizeAllocate handler)

  Hook up a Widget.SizeAllocate handler.

  Since:

  4.1.1

• 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

• destroy

  public void destroy()

  Ask everything connected to this object to release its references. Use this in preference to Container's remove() if you don't need the Widget any more.

  We didn't expose this for a long time in java-gnome; after all, memory management of both Java references and GObject Ref counts is handled automatically by the diabolical cunning of this most excellent library. It turns out, however, that this does not free() the GtkWidget's memory; it really only does what it says: ask other GtkWidget to drop whatever Refs they may be holding to this object. Thus if this GtkWidget is in a GtkContainer and you call destroy() the GtkContainer will drop its Refs to this GtkWidget thereby breaking its parent-child relationship.

  Note that Java's references remain, so the object will not, in fact, be eligable for finalizing until you drop all your references; ie, the Java side Proxy Object goes out of scope. Nevertheless calling this will speed up release of resources associated with a Widget, so it's a good idea. Once you've done so, finalize() will be traversed a short time later and the GObject will be released.

  Since:

  4.0.20

• getAllocatedHeight

  public int getAllocatedHeight()

  Retreive the height that has been allocated to this Widget. See also getAllocatedWidth().

  Since:

  4.1.1

• getAllocatedWidth

  public int getAllocatedWidth()

  Retreive the width that has been allocated to this Widget, in pixels. This is meant to be used by Widget.Draw handlers when they need to know their canvas size.

  Since:

  4.1.1

• 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

• getPreferredHeightForWidthMinimum

  public int getPreferredHeightForWidthMinimum(int width)

  Since:

  4.1.1

• getPreferredHeightForWidthNatural

  public int getPreferredHeightForWidthNatural(int width)

  Since:

  4.1.1

• getPreferredHeightMinimum

  public int getPreferredHeightMinimum()

  Since:

  4.1.1

• getPreferredHeightNatural

  public int getPreferredHeightNatural()

  Since:

  4.1.1

• getPreferredWidthForHeightMinimum

  public int getPreferredWidthForHeightMinimum(int height)

  Since:

  4.1.1

• getPreferredWidthForHeightNatural

  public int getPreferredWidthForHeightNatural(int height)

  Since:

  4.1.1

• getPreferredWidthMinimum

  public int getPreferredWidthMinimum()

  Since:

  4.1.1

• getPreferredWidthNatural

  public int getPreferredWidthNatural()

  Since:

  4.1.1

• getRequestMode

  public SizeRequestMode getRequestMode()

  Does the Widget prefer that it be given height for a given width, or vice versa?

  Part of GTK 3's height-for-width geometry management system.

  Returns:

• 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).

  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

• getStyleContext

  public StyleContext getStyleContext()

  Get the StyleContext of a Widget. You will be able to change the values of the style after getting this object.

  Since:

  4.1.2

• 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

• overrideBackground

  public void overrideBackground(StateFlags state,
                        RGBA color)

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

  Since:

  4.0.20

• overrideColor

  public void overrideColor(StateFlags state,
                   RGBA color)

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

  Since:

  4.0.20

• overrideFont

  public void overrideFont(FontDescription desc)

  Set the font used for text rendered by this Widget.

  Since:

  4.0.20

• 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.Draw signal 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.Draw signal 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.Draw handler, at which point the Widget is already realized, mapped, and showing.

  Since:

  4.0.16

• setAlignHorizontal

  public void setAlignHorizontal(Align align)

  Set the horizontal positioning of a Widget in its parent Container.

  This is the halign property.

  This is part of how the GTK 2.x Alignment Widget has been replaced.

  Since:

  4.1.1

• setAlignVertical

  public void setAlignVertical(Align align)

  Set the vertical positioning of a Widget in its parent Container.

  This is the valign property.

  Since:

  4.1.1

• 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

• 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

• setExpandHorizontal

  public void setExpandHorizontal(boolean setting)

  Will this Widget be given any additional space that it's parent Container has? The default is false which means that as a child this Widget will be allocated its natural size reqeust, but not more.

  This is the hexpand property.

  Since:

  4.1.1

• setExpandVertical

  public void setExpandVertical(boolean setting)

  This is the vexpand property.

  Since:

  4.1.1

• 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