# HG changeset patch # User stephent # Date 998821514 0 # Node ID 2cf5d151eeb95ba6619dc91d83378114d3107d5b # Parent 98b3721724bdf3b0ba13a937f28c6319b178a12b [xemacs-hg @ 2001-08-26 10:25:11 by stephent] Update docs for widgets and lisp/README. <15240.52706.361788.550139@turnbull.sk.tsukuba.ac.jp> diff -r 98b3721724bd -r 2cf5d151eeb9 lisp/ChangeLog --- a/lisp/ChangeLog Sun Aug 26 09:42:24 2001 +0000 +++ b/lisp/ChangeLog Sun Aug 26 10:25:14 2001 +0000 @@ -1,3 +1,32 @@ +2001-08-26 Stephen J. Turnbull + + * README: Partial update. + +2001-08-26 Stephen J. Turnbull + + * wid-edit.el (widget-specify-secret): + (widget-get): + (widget-default-get): + (widget-match-inline): + (widget-create): + (widget-create-child-and-convert): + (widget-create-child): + (widget-convert-text): + (widget-convert-button): + (widget-field-activate): + (widget-beginning-of-line): + (widget-end-of-line): + (widget-kill-line): + (widget-field-buffer): + (widget-field-start): + (widget-field-end): + (widget-field-find): + (widget-before-change): + (`group' Widget): + ('list Widget): + ('vector Widget): + Document usage conditions, fix typos. + 2001-06-19 Ben Wing * term\AT386.el: diff -r 98b3721724bd -r 2cf5d151eeb9 lisp/README --- a/lisp/README Sun Aug 26 09:42:24 2001 +0000 +++ b/lisp/README Sun Aug 26 10:25:14 2001 +0000 @@ -1,3 +1,77 @@ +The files in this directory contain source code for the core XEmacs +facilities written in Emacs Lisp. *.el files are Elisp source, and +*.elc files are byte-compiled versions of the corresponding *.el +files. Byte-compiled files are architecture-independent. + +Functions used only by files in this directory are considered +"internal" and are subject to change at any time. All commands, and +most functions with docstrings, are part of the exported API. In +particular, it is considered good style to use the Common Lisp +facilities provided in cl*.el. (Yes, that's ambiguous. Sorry, we +don't have a full specification of the API, as the Lispref is +chronically incomplete. Anything described in the Lispref is part of +the API, of course.) + +Libraries which implement applications and enhancements are placed in +the "packages", which are distributed separately from the core +sources. + +#### Someone please update this. +#### Partially updated 2001-08-25 by sjt. Needs more work. Mike? + +When XEmacs starts up, it adds certain directories in various +hierarchies containing Lisp libraries to `load-path' (the list of +directories to be searched when loading files). These are: this +directory, its subdirectory ./mule (in Mule-enabled XEmacs only), the +site-lisp directory (deprecated), and all the lisp/PACKAGE +subdirectories of the xemacs-packages, mule-packages, and +site-packages hierarchies. See setup-paths.el. + +#### Is the following true or relevant any more? +bogus> Directories whose names begin with "-" or "." are not added to +bogus> the default load-path. + +Some files which you might reasonably want to alter when installing or +customizing XEmacs at your site are: + + paths.el You may need to change the default pathnames here, + but probably not. This is loaded before XEmacs is + dumped. + + site-init.el #### obsolete and removed? + To pre-load additional libraries into XEmacs and dump + them in the executable, load them from this file. + Read the instructions in this file for a description + of how to do this. + + site-load.el #### description is obsolete + This is like site-init.el, but if you want the + docstrings of your preloaded libraries to be kept in + the DOC file instead of in the executable, you should + load them from this file instead. To do this, you must + also cause them to be scanned when the DOC file is + generated by editing ../src/Makefile.in.in and + rerunning configure. + #### new semantics + This file will preload additional libraries listed in + ../site-packages and dump them into XEmacs. + + ../site-packages List of additional libraries read by site-load.el. + + site-start.el This is loaded each time XEmacs starts up, before the + user's .emacs file. (Sysadmin must create.) Can be + inhibited for a given invocation with `--no-site-file'. + + default.el This is loaded each time XEmacs starts up, after the + user's .emacs file, unless .emacs sets the variable + inhibit-default-init to t. (Sysadmin must create.) + Can be inhibited for a given invocation with `-q'. + + version.el This contains the version information for XEmacs. + +======================================================================== +Original text follows: + The files in this directory contain source code for the XEmacs facilities written in Emacs Lisp. *.el files are Elisp source, and *.elc files are byte-compiled versions of the corresponding *.el diff -r 98b3721724bd -r 2cf5d151eeb9 lisp/wid-edit.el --- a/lisp/wid-edit.el Sun Aug 26 09:42:24 2001 +0000 +++ b/lisp/wid-edit.el Sun Aug 26 10:25:14 2001 +0000 @@ -343,7 +343,10 @@ (widget-specify-secret widget)) (defun widget-specify-secret (field) - "Replace text in FIELD with value of `:secret', if non-nil." + "Replace text in FIELD with value of `:secret', if non-nil. + +It is an error to use this function after creating the widget but before +invoking `widget-setup'." (let ((secret (widget-get field :secret)) (size (widget-get field :size))) (when secret @@ -552,7 +555,7 @@ widget-shadow-subrs) (defun widget-get (widget property) "In WIDGET, get the value of PROPERTY. -The value could either be specified when the widget was created, or +The value may have been specified when the widget was created, or later with `widget-put'." (let ((missing t) value tmp) @@ -603,12 +606,12 @@ :value-to-internal value))) (defun widget-default-get (widget) - "Extract the defaylt value of WIDGET." + "Extract the default value of WIDGET." (or (widget-get widget :value) (widget-apply widget :default-get))) (defun widget-match-inline (widget vals) - ;; In WIDGET, match the start of VALS. + "In WIDGET, match the start of VALS." (cond ((widget-get widget :inline) (widget-apply widget :match-inline vals)) ((and (listp vals) @@ -845,14 +848,14 @@ ;;;###autoload (defun widget-create (type &rest args) - "Create widget of TYPE. + "Create a widget of type TYPE. The optional ARGS are additional keyword arguments." (let ((widget (apply 'widget-convert type args))) (widget-apply widget :create) widget)) (defun widget-create-child-and-convert (parent type &rest args) - "As part of the widget PARENT, create a child widget TYPE. + "As a child of widget PARENT, create a widget of type TYPE. The child is converted, using the keyword arguments ARGS." (let ((widget (apply 'widget-convert type args))) (widget-put widget :parent parent) @@ -864,7 +867,8 @@ widget)) (defun widget-create-child (parent type) - "Create widget of TYPE." + "As a child of widget PARENT, create a widget of type TYPE. +The child is not converted." (let ((widget (copy-sequence type))) (widget-put widget :parent parent) (unless (widget-get widget :indent) @@ -913,7 +917,7 @@ (setq args (nthcdr 2 args)) (widget-put widget :args args) (setq args nil)))) - ;; Then Convert the widget. + ;; Then convert the widget. (setq type widget) (while type (let ((convert-widget (plist-get (cdr type) :convert-widget))) @@ -946,11 +950,12 @@ (defun widget-convert-text (type from to &optional button-from button-to &rest args) - "Return a widget of type TYPE with endpoint FROM TO. -Optional ARGS are extra keyword arguments for TYPE. -and TO will be used as the widgets end points. If optional arguments -BUTTON-FROM and BUTTON-TO are given, these will be used as the widgets -button end points. + "Return a widget of type TYPE with endpoints FROM and TO. +No text will be inserted in the buffer. Instead the positions FROM and TO +will be used as the widget's end points. The widget is ``wrapped around'' +the text between them. +If optional arguments BUTTON-FROM and BUTTON-TO are given, these will be +used as the widget's button end points. Optional ARGS are extra keyword arguments for TYPE." (let ((widget (apply 'widget-convert type :delete 'widget-leave-text args)) (from (copy-marker from)) @@ -964,11 +969,11 @@ widget)) (defun widget-convert-button (type from to &rest args) - "Return a widget of type TYPE with endpoint FROM TO. + "Return a widget of type TYPE with endpoints FROM and TO. Optional ARGS are extra keyword arguments for TYPE. -No text will be inserted to the buffer, instead the text between FROM -and TO will be used as the widgets end points, as well as the widgets -button end points." +No text will be inserted in the buffer. Instead the positions FROM and TO +will be used as the widget's end points, as well as the widget's button's +end points. The widget is ``wrapped around'' the text between them." (apply 'widget-convert-text type from to from to args)) (defun widget-leave-text (widget) @@ -1054,7 +1059,7 @@ (defun widget-field-activate (pos &optional event) - "Invoke the ediable field at point." + "Invoke the editable field at point." (interactive "@d") (let ((field (widget-field-find pos))) (if field @@ -1312,7 +1317,10 @@ (widget-move (- arg))) (defun widget-beginning-of-line () - "Go to beginning of field or beginning of line, whichever is first." + "Go to beginning of field or beginning of line, whichever is first. + +It is an error to use this function after creating the widget but before +invoking `widget-setup'." (interactive "_") (let* ((field (widget-field-find (point))) (start (and field (widget-field-start field)))) @@ -1321,7 +1329,10 @@ (call-interactively 'beginning-of-line)))) (defun widget-end-of-line () - "Go to end of field or end of line, whichever is first." + "Go to end of field or end of line, whichever is first. + +It is an error to use this function after creating the widget but before +invoking `widget-setup'." (interactive "_") (let* ((field (widget-field-find (point))) (end (and field (widget-field-end field)))) @@ -1330,7 +1341,10 @@ (call-interactively 'end-of-line)))) (defun widget-kill-line () - "Kill to end of field or end of line, whichever is first." + "Kill to end of field or end of line, whichever is first. + +It is an error to use this function after creating the widget but before +invoking `widget-setup'." (interactive) (let* ((field (widget-field-find (point))) (newline (save-excursion (forward-line 1) (point))) @@ -1425,17 +1439,26 @@ (make-variable-buffer-local 'widget-field-was) (defun widget-field-buffer (widget) - "Return the start of WIDGET's editing field." + "Return the buffer containing WIDGET. + +It is an error to use this function after creating the widget but before +invoking `widget-setup'." (let ((extent (widget-get widget :field-extent))) (and extent (extent-object extent)))) (defun widget-field-start (widget) - "Return the start of WIDGET's editing field." + "Return the start of WIDGET's editing field. + +It is an error to use this function after creating the widget but before +invoking `widget-setup'." (let ((extent (widget-get widget :field-extent))) (and extent (extent-start-position extent)))) (defun widget-field-end (widget) - "Return the end of WIDGET's editing field." + "Return the end of WIDGET's editing field. + +It is an error to use this function after creating the widget but before +invoking `widget-setup'." (let ((extent (widget-get widget :field-extent))) ;; Don't subtract one if local-map works at the end of the extent. (and extent (if (or widget-field-add-space @@ -1445,7 +1468,10 @@ (defun widget-field-find (pos) "Return the field at POS. -Unlike (get-char-property POS 'field) this, works with empty fields too." +Unlike (get-char-property POS 'field) this, works with empty fields too. + +Warning: using this function after creating the widget but before invoking +`widget-setup' will always fail." (let ((field-extent (map-extents (lambda (extent ignore) extent) nil pos pos nil nil 'field))) @@ -1467,6 +1493,8 @@ ; (setq found field)))) ; found)) +;; Warning: using this function after creating the widget but before +;; invoking `widget-setup' will always fail. (defun widget-before-change (from to) ;; Barf if the text changed is outside the editable fields. (unless inhibit-read-only @@ -2966,7 +2994,7 @@ ;;; The `group' Widget. (define-widget 'group 'default - "A widget which group other widgets inside." + "A widget which groups other widgets inside." :convert-widget 'widget-types-convert-widget :format "%v" :value-create 'widget-group-value-create @@ -3518,12 +3546,12 @@ (characterp value))) (define-widget 'list 'group - "A lisp list." + "A Lisp list." :tag "List" :format "%{%t%}:\n%v") (define-widget 'vector 'group - "A lisp vector." + "A Lisp vector." :tag "Vector" :format "%{%t%}:\n%v" :match 'widget-vector-match diff -r 98b3721724bd -r 2cf5d151eeb9 man/ChangeLog --- a/man/ChangeLog Sun Aug 26 09:42:24 2001 +0000 +++ b/man/ChangeLog Sun Aug 26 10:25:14 2001 +0000 @@ -1,3 +1,8 @@ +2001-08-26 Stephen J. Turnbull + + * widget.texi (Basic Types, Defining New Widgets): + Distinguish between :action and :notify. + 2001-07-28 Stephen J. Turnbull * XEmacs 21.5.2 "artichoke" is released. diff -r 98b3721724bd -r 2cf5d151eeb9 man/widget.texi --- a/man/widget.texi Sun Aug 26 09:42:24 2001 +0000 +++ b/man/widget.texi Sun Aug 26 10:25:14 2001 +0000 @@ -542,7 +542,9 @@ The function is called with two or three arguments. The first argument is the widget itself, the second argument is the widget that was changed, and the third argument is the event leading to the change, if -any. +any. In editable fields, this includes all insertions, deletions, +@emph{etc}. To watch only for ``final'' actions, redefine the +@code{:action} callback. @item :menu-tag Tag used in the menu when the widget is used as an option in a @@ -1469,7 +1471,9 @@ @item :action Function to handle user initiated events. By default, @code{:notify} -the parent. +the parent. Actions normally do not include mere edits, but refer to +things like invoking buttons or hitting enter in an editable field. To +watch for any change, redefine the @code{:notify} callback. The following predefined function can be used here: