GNU Info

(widget)Widget Properties

---

Next: Defining New Widgets Prev: Sexp Types Up: Top

---

Enter node , (file) or (file)node

Properties
==========

   You can examine or set the value of a widget by using the widget
object that was returned by `widget-create'.

 - Function: widget-value widget
     Return the current value contained in WIDGET.  It is an error to
     call this function on an uninitialized widget.

 - Function: widget-value-set widget value
     Set the value contained in WIDGET to VALUE.  It is an error to
     call this function with an invalid VALUE.

   *Important:* You _must_ call `widget-setup' after modifying the
value of a widget before the user is allowed to edit the widget again.
It is enough to call `widget-setup' once if you modify multiple
widgets.  This is currently only necessary if the widget contains an
editing field, but may be necessary for other widgets in the future.

   If your application needs to associate some information with the
widget objects, for example a reference to the item being edited, it
can be done with `widget-put' and `widget-get'.  The property names
must begin with a `:'.

 - Function: widget-put widget property value
     In WIDGET set PROPERTY to VALUE.  PROPERTY should be a symbol,
     while VALUE can be anything.

 - Function: widget-get widget property
     In WIDGET return the value for PROPERTY.  PROPERTY should be a
     symbol, the value is what was last set by `widget-put' for
     PROPERTY.

 - Function: widget-member widget property
     Non-nil if WIDGET has a value (even nil) for property PROPERTY.

   Occasionally it can be useful to know which kind of widget you have,
i.e. the name of the widget type you gave when the widget was created.

 - Function: widget-type widget
     Return the name of WIDGET, a symbol.

   Widgets can be in two states: active, which means they are
modifiable by the user, or inactive, which means they cannot be
modified by the user.  You can query or set the state with the
following code:

     ;; Examine if WIDGET is active or not.
     (if (widget-apply WIDGET :active)
         (message "Widget is active.")
       (message "Widget is inactive.")
     
     ;; Make WIDGET inactive.
     (widget-apply WIDGET :deactivate)
     
     ;; Make WIDGET active.
     (widget-apply WIDGET :activate)

   A widget is inactive if it, or any of its ancestors (found by
following the `:parent' link), have been deactivated.  To make sure a
widget is really active, you must therefore activate both it and all
its ancestors.

     (while widget
       (widget-apply widget :activate)
       (setq widget (widget-get widget :parent)))

   You can check if a widget has been made inactive by examining the
value of the `:inactive' keyword.  If this is non-nil, the widget itself
has been deactivated.  This is different from using the `:active'
keyword, in that the latter tells you if the widget *or* any of its
ancestors have been deactivated.  Do not attempt to set the `:inactive'
keyword directly.  Use the `:activate' `:deactivate' keywords instead.