[graphic-forms-cvs] r192 - in trunk: docs/manual src src/demos/textedit src/tests/uitoolkit src/uitoolkit/widgets
junrue at common-lisp.net
junrue at common-lisp.net
Tue Jul 11 20:33:24 UTC 2006
Author: junrue
Date: Tue Jul 11 16:33:21 2006
New Revision: 192
Modified:
trunk/docs/manual/api.texinfo
trunk/docs/manual/miscellaneous.texinfo
trunk/src/demos/textedit/textedit-window.lisp
trunk/src/packages.lisp
trunk/src/tests/uitoolkit/layout-tester.lisp
trunk/src/uitoolkit/widgets/edit.lisp
trunk/src/uitoolkit/widgets/event.lisp
trunk/src/uitoolkit/widgets/menu-item.lisp
trunk/src/uitoolkit/widgets/menu.lisp
trunk/src/uitoolkit/widgets/thread-context.lisp
trunk/src/uitoolkit/widgets/timer.lisp
trunk/src/uitoolkit/widgets/top-level.lisp
trunk/src/uitoolkit/widgets/widget-generics.lisp
trunk/src/uitoolkit/widgets/widget-with-items.lisp
trunk/src/uitoolkit/widgets/widget.lisp
trunk/src/uitoolkit/widgets/window.lisp
Log:
cleanup of clear vs. delete terminology, and got rid of remove-*
Modified: trunk/docs/manual/api.texinfo
==============================================================================
--- trunk/docs/manual/api.texinfo (original)
+++ trunk/docs/manual/api.texinfo Tue Jul 11 16:33:21 2006
@@ -127,6 +127,7 @@
@sc{nil} otherwise.
@end defun
+ at anchor{location}
@deffn Macro location rect
This macro returns the @var{location} slot of a @ref{rectangle}.
@end deffn
@@ -1281,24 +1282,15 @@
Returns T if the object is in the checked state; nil otherwise.
@end deffn
- at deffn GenericFunction clear-all self
-Clears all content from @code{self}.
- at end deffn
-
- at deffn GenericFunction clear-item self index
-Clears the @ref{item} at the zero-based @var{index}.
- at end deffn
-
@deffn GenericFunction clear-selection self
-Sets the selection status of @code{self} to @samp{not selected} or
- at samp{empty}. For a @ref{control} with a text field component,
-such as an @ref{edit} control, this function deletes selected
-text.
+Sets the selection status of @code{self} (or @ref{item}s within
+ at var{self}) to the @samp{unselected} state.
@end deffn
- at deffn GenericFunction clear-span self @ref{span}
-Clears the items from @var{self} whose zero-based indices lie within
-the specified @var{span}.
+ at deffn GenericFunction clear-selection-span self @ref{span}
+Sets the selection status of @ref{item}s within @var{self}, whose
+zero-based indices lie within @var{span}, to the @samp{unselected}
+state.
@end deffn
@deffn GenericFunction client-size self
@@ -1351,6 +1343,26 @@
presses @sc{enter}.
@end deffn
+ at deffn GenericFunction delete-all self
+Removes all content from @code{self}.
+ at end deffn
+
+ at deffn GenericFunction delete-item self index
+Removes the @ref{item} at the zero-based @var{index}.
+ at end deffn
+
+ at deffn GenericFunction delete-item-span self @ref{span}
+Removes the items from @var{self} whose zero-based indices lie within
+the specified @var{span}.
+ at end deffn
+
+ at deffn GenericFunction delete-selection self
+Removes the subset of items from @var{self} that are in the
+ at samp{selected} state. For a @ref{control} with a text field
+component, such as an @ref{edit} control, this function deletes
+selected text.
+ at end deffn
+
@deffn GenericFunction display-to-object self pnt
Return a point that is the result of transforming the specified point
from display-relative coordinates to this object's coordinate system.
@@ -1660,6 +1672,7 @@
other cases there is no text component at all.
@end deffn
+ at anchor{undo-available-p}
@deffn GenericFunction undo-available-p self => boolean
Returns T if @code{self} has @sc{undo} capability and has an
operation that can be undone; @sc{nil} otherwise.
Modified: trunk/docs/manual/miscellaneous.texinfo
==============================================================================
--- trunk/docs/manual/miscellaneous.texinfo (original)
+++ trunk/docs/manual/miscellaneous.texinfo Tue Jul 11 16:33:21 2006
@@ -10,4 +10,54 @@
@node Miscellaneous Topics
@chapter Miscellaneous Topics
- at strong{TBD}
+ at menu
+* terminology:: Some notes about terminology conventions.
+ at end menu
+
+
+ at node terminology
+ at section terminology
+
+This chapter documents terminology conventions observed in
+Graphic-Forms. These conventions should be interpreted with the
+traditional Common Lisp conventions in mind (such as
+ at url{http://www.cliki.net/Naming%20conventions}).
+
+ at table @option
+
+ at item accessor names
+For clearer identification of accessors, Graphic-Forms
+uses the suffix @samp{-of} whenever possible.
+
+ at item function and method names
+Functions and methods should be named using a verb to suggest
+action. It may be tempting (especially for former Java programmers) to
+use the Java getter/setter naming conventions for accessor-like
+functions, but the author prefers @samp{obtain} rather than
+ at samp{get}, and he prefers @sc{setf}'able places which therefore can
+have @sc{setf} functions defined for them. For status querying
+functions, the author suggests @samp{available-p}, such as
+ at ref{undo-available-p}.
+
+ at item @samp{clear} versus @samp{delete}
+Related to the @samp{function and method names} issues, there is
+a distinction between @samp{clear} and @samp{delete} which hinges on
+the difference between the primary content of a @ref{widget} and
+secondary state information. An example of primary content is text
+within an @ref{edit} @ref{control}. An example of secondary state
+information (relevant to this topic at least) is the @ref{span} of
+selected text in an edit control. With that in mind, Graphic-Forms
+functions @samp{delete} content but @samp{clear} secondary state. This
+choice is intended in part to align with the semantics of
+ at sc{CL:delete}, including the notion of that function being a
+destructive operation.
+
+ at item macro names
+Macros should be named consistent with established Common Lisp
+practice, with an exception being allowed for convenience wrappers
+around structure accessors (see @ref{location}). Otherwise, the
+temptation to define an unorthodox macro name is a symptom that maybe
+the code in question should not be a macro in the first place.
+
+ at end table
+
Modified: trunk/src/demos/textedit/textedit-window.lisp
==============================================================================
--- trunk/src/demos/textedit/textedit-window.lisp (original)
+++ trunk/src/demos/textedit/textedit-window.lisp Tue Jul 11 16:33:21 2006
@@ -108,7 +108,7 @@
(defun textedit-edit-delete (disp item)
(declare (ignore disp item))
- (gfw:clear-selection *textedit-control*))
+ (gfw:delete-selection *textedit-control*))
(defun textedit-edit-paste (disp item)
(declare (ignore disp item))
Modified: trunk/src/packages.lisp
==============================================================================
--- trunk/src/packages.lisp (original)
+++ trunk/src/packages.lisp Tue Jul 11 16:33:21 2006
@@ -331,10 +331,8 @@
#:check
#:check-all
#:checked-p
- #:clear-all
- #:clear-item
#:clear-selection
- #:clear-span
+ #:clear-selection-span
#:client-size
#:close-obj
#:code
@@ -353,6 +351,10 @@
#:default-widget
#:defmenu
#:delay-of
+ #:delete-all
+ #:delete-item
+ #:delete-selection
+ #:delete-span
#:disabled-image
#:dispatcher
#:display-to-object
@@ -455,9 +457,6 @@
#:redraw
#:redrawing-p
#:release-mouse
- #:remove-all
- #:remove-item
- #:remove-span
#:reparentable-p
#:replace-selection
#:resizable-p
Modified: trunk/src/tests/uitoolkit/layout-tester.lisp
==============================================================================
--- trunk/src/tests/uitoolkit/layout-tester.lisp (original)
+++ trunk/src/tests/uitoolkit/layout-tester.lisp Tue Jul 11 16:33:21 2006
@@ -169,7 +169,7 @@
:initform nil)))
(defmethod gfw:event-activate ((d child-menu-dispatcher) menu)
- (gfw:clear-all menu)
+ (gfw:delete-all menu)
(gfw:mapchildren *layout-tester-win*
(lambda (parent child)
(declare (ignore parent))
@@ -336,7 +336,7 @@
(defun flow-mod-callback (disp menu)
(declare (ignore disp))
- (gfw:clear-all menu)
+ (gfw:delete-all menu)
(let ((it nil)
(margin-menu (gfw:defmenu ((:item "Left"
:callback #'enable-left-flow-margin-items
Modified: trunk/src/uitoolkit/widgets/edit.lisp
==============================================================================
--- trunk/src/uitoolkit/widgets/edit.lisp (original)
+++ trunk/src/uitoolkit/widgets/edit.lisp Tue Jul 11 16:33:21 2006
@@ -48,9 +48,6 @@
(let ((bits (gfs::get-window-long (gfs:handle self) gfs::+gwl-style+)))
(= (logand bits gfs::+es-autovscroll+) gfs::+es-autovscroll+)))
-(defmethod clear-selection ((self edit))
- (gfs::send-message (gfs:handle self) gfs::+wm-clear+ 0 0))
-
(defmethod compute-style-flags ((self edit) &rest extra-data)
(declare (ignore extra-data))
(let ((std-flags (logior +default-child-style+ gfs::+ws-tabstop+))
@@ -83,6 +80,9 @@
(defmethod cut-text ((self edit))
(gfs::send-message (gfs:handle self) gfs::+wm-cut+ 0 0))
+(defmethod delete-selection ((self edit))
+ (gfs::send-message (gfs:handle self) gfs::+wm-clear+ 0 0))
+
(defmethod enable-scrollbars ((self edit) horizontal vertical)
(let ((bits (gfs::get-window-long (gfs:handle self) gfs::+gwl-style+)))
(if horizontal
Modified: trunk/src/uitoolkit/widgets/event.lisp
==============================================================================
--- trunk/src/uitoolkit/widgets/event.lisp (original)
+++ trunk/src/uitoolkit/widgets/event.lisp Tue Jul 11 16:33:21 2006
@@ -211,7 +211,7 @@
(defmethod process-message (hwnd (msg (eql gfs::+wm-destroy+)) wparam lparam)
(declare (ignore wparam lparam))
- (remove-widget (thread-context) hwnd)
+ (delete-widget (thread-context) hwnd)
0)
(defmethod process-message (hwnd (msg (eql gfs::+wm-char+)) wparam lparam)
@@ -454,7 +454,7 @@
(defmethod process-subclass-message (hwnd (msg (eql gfs::+wm-destroy+)) wparam lparam)
(declare (ignore wparam lparam))
- (remove-widget (thread-context) hwnd)
+ (delete-widget (thread-context) hwnd)
(call-next-method))
;;;
Modified: trunk/src/uitoolkit/widgets/menu-item.lisp
==============================================================================
--- trunk/src/uitoolkit/widgets/menu-item.lisp (original)
+++ trunk/src/uitoolkit/widgets/menu-item.lisp Tue Jul 11 16:33:21 2006
@@ -196,7 +196,7 @@
(defmethod gfs:dispose ((it menu-item))
(setf (dispatcher it) nil)
- (remove-menuitem (thread-context) it)
+ (delete-menuitem (thread-context) it)
(let ((id (item-id it))
(owner (owner it)))
(unless (null owner)
Modified: trunk/src/uitoolkit/widgets/menu.lisp
==============================================================================
--- trunk/src/uitoolkit/widgets/menu.lisp (original)
+++ trunk/src/uitoolkit/widgets/menu.lisp Tue Jul 11 16:33:21 2006
@@ -142,13 +142,13 @@
(defun menu-cleanup-callback (menu item)
(let ((tc (thread-context)))
- (remove-widget tc (gfs:handle menu))
- (remove-menuitem tc item)))
+ (delete-widget tc (gfs:handle menu))
+ (delete-menuitem tc item)))
(defmethod gfs:dispose ((m menu))
(visit-menu-tree m #'menu-cleanup-callback)
(let ((hwnd (gfs:handle m)))
- (remove-widget (thread-context) hwnd)
+ (delete-widget (thread-context) hwnd)
(if (not (gfs:null-handle-p hwnd))
(if (zerop (gfs::destroy-menu hwnd))
(error 'gfs:win32-error :detail "destroy-menu failed"))))
Modified: trunk/src/uitoolkit/widgets/thread-context.lisp
==============================================================================
--- trunk/src/uitoolkit/widgets/thread-context.lisp (original)
+++ trunk/src/uitoolkit/widgets/thread-context.lisp Tue Jul 11 16:33:21 2006
@@ -133,7 +133,7 @@
"Add the specified widget to the widget table using its native handle as the key."
(setf (gethash (cffi:pointer-address (gfs:handle w)) (slot-value tc 'widgets-by-hwnd)) w))
-(defmethod remove-widget ((tc thread-context) hwnd)
+(defmethod delete-widget ((tc thread-context) hwnd)
"Remove the widget object corresponding to the specified native window handle."
(when (not (slot-value tc 'wip))
(remhash (cffi:pointer-address hwnd) (slot-value tc 'widgets-by-hwnd))))
@@ -154,7 +154,7 @@
(if (find :keyboard-navigation (style-of widget))
(setf (kbdnav-widgets tc) (push widget (kbdnav-widgets tc)))))
-(defmethod remove-kbdnav-widget ((tc thread-context) (widget widget))
+(defmethod delete-kbdnav-widget ((tc thread-context) (widget widget))
(setf (kbdnav-widgets tc)
(remove-if (lambda (hwnd) (cffi:pointer-eq (gfs:handle widget) hwnd))
(kbdnav-widgets tc)
@@ -170,7 +170,7 @@
(setf widget (find-if (lambda (w) (/= (gfs::is-dialog-message (gfs:handle w) msg-ptr)))
(rest widgets)))
(when (and widget (/= (gfs::is-dialog-message (gfs:handle widget) msg-ptr) 0))
- (let ((tmp (remove-kbdnav-widget tc widget)))
+ (let ((tmp (delete-kbdnav-widget tc widget)))
(setf (kbdnav-widgets tc) (push widget tmp)))
(return-from intercept-kbdnav-message widget))))
nil)
@@ -183,7 +183,7 @@
"Stores a menu item using its id as the key."
(setf (gethash (item-id it) (slot-value tc 'menuitems-by-id)) it))
-(defmethod remove-menuitem ((tc thread-context) (it menu-item))
+(defmethod delete-menuitem ((tc thread-context) (it menu-item))
"Removes the menu item using its id as the key."
(maphash
#'(lambda (k v)
@@ -206,7 +206,7 @@
"Stores a timer using its id as the key."
(setf (gethash (id-of timer) (slot-value tc 'timers-by-id)) timer))
-(defmethod remove-timer ((tc thread-context) (timer timer))
+(defmethod delete-timer ((tc thread-context) (timer timer))
"Removes the timer using its id as the key."
(maphash
#'(lambda (k v)
Modified: trunk/src/uitoolkit/widgets/timer.lisp
==============================================================================
--- trunk/src/uitoolkit/widgets/timer.lisp (original)
+++ trunk/src/uitoolkit/widgets/timer.lisp Tue Jul 11 16:33:21 2006
@@ -78,7 +78,7 @@
(defmethod gfs:dispose ((self timer))
(let ((tc (thread-context)))
- (remove-timer tc self)
+ (delete-timer tc self)
(gfs::kill-timer (utility-hwnd tc) (id-of self))))
(defmethod initialize-instance :after ((self timer) &key)
Modified: trunk/src/uitoolkit/widgets/top-level.lisp
==============================================================================
--- trunk/src/uitoolkit/widgets/top-level.lisp (original)
+++ trunk/src/uitoolkit/widgets/top-level.lisp Tue Jul 11 16:33:21 2006
@@ -130,7 +130,7 @@
(let ((m (menu-bar win)))
(unless (null m)
(visit-menu-tree m #'menu-cleanup-callback)
- (remove-widget (thread-context) (gfs:handle m))))
+ (delete-widget (thread-context) (gfs:handle m))))
(call-next-method))
(defmethod initialize-instance :after ((win top-level) &key owner text &allow-other-keys)
Modified: trunk/src/uitoolkit/widgets/widget-generics.lisp
==============================================================================
--- trunk/src/uitoolkit/widgets/widget-generics.lisp (original)
+++ trunk/src/uitoolkit/widgets/widget-generics.lisp Tue Jul 11 16:33:21 2006
@@ -84,17 +84,11 @@
(defgeneric checked-p (self)
(:documentation "Returns T if the object is in the checked state; nil otherwise."))
-(defgeneric clear-all (self)
- (:documentation "Clears all content from self."))
-
-(defgeneric clear-item (self index)
- (:documentation "Clears the item at the zero-based index."))
-
(defgeneric clear-selection (self)
- (:documentation "Sets the object's selection status to empty or not selected."))
+ (:documentation "The set of selected items in self is made empty."))
-(defgeneric clear-span (self sp)
- (:documentation "Clears the items whose zero-based indices lie within the specified span."))
+(defgeneric clear-selection-span (self span)
+ (:documentation "Sets a subset of self's current selection to the unselected state."))
(defgeneric client-size (self)
(:documentation "Returns a size object that describes the region of the object that can be drawn within or can display data."))
@@ -132,6 +126,18 @@
(defgeneric default-widget (self)
(:documentation "Returns the child widget or item that has the default emphasis."))
+(defgeneric delete-all (self)
+ (:documentation "Removes all content from the object."))
+
+(defgeneric delete-item (self index)
+ (:documentation "Removes the item at the zero-based index from the object."))
+
+(defgeneric delete-item-span (self span)
+ (:documentation "Removes the sequence of items represented by the specified span object."))
+
+(defgeneric delete-selection (self)
+ (:documentation "Removes items from self that are in the selected state."))
+
(defgeneric disabled-image (self)
(:documentation "Returns the image used to render this item with a disabled look."))
@@ -282,15 +288,6 @@
(defgeneric redrawing-p (self)
(:documentation "Returns T if the object is set to allow processing of paint events."))
-(defgeneric remove-all (self)
- (:documentation "Removes all items from the object."))
-
-(defgeneric remove-item (self index)
- (:documentation "Removes the item at the zero-based index from the object."))
-
-(defgeneric remove-span (self sp)
- (:documentation "Removes the sequence of items represented by the specified span object."))
-
(defgeneric reparentable-p (self)
(:documentation "Returns T if the window system allows this object to be reparented; nil otherwise."))
Modified: trunk/src/uitoolkit/widgets/widget-with-items.lisp
==============================================================================
--- trunk/src/uitoolkit/widgets/widget-with-items.lisp (original)
+++ trunk/src/uitoolkit/widgets/widget-with-items.lisp Tue Jul 11 16:33:21 2006
@@ -38,17 +38,17 @@
(if (gfs:disposed-p self)
(error 'gfs:disposed-error)))
-(defmethod clear-all ((self widget-with-items))
+(defmethod delete-all ((self widget-with-items))
(let ((count (length (items self))))
(unless (zerop count)
- (clear-span self (gfs:make-span :start 0 :end (1- count))))))
+ (delete-item-span self (gfs:make-span :start 0 :end (1- count))))))
-(defmethod clear-item :before ((self widget-with-items) index)
+(defmethod delete-item :before ((self widget-with-items) index)
(declare (ignore index))
(if (gfs:disposed-p self)
(error 'gfs:disposed-error)))
-(defmethod clear-item ((self widget-with-items) index)
+(defmethod delete-item ((self widget-with-items) index)
(let* ((items (items self))
(it (elt items index)))
(delete it (items self) :test #'items-equal-p)
@@ -56,14 +56,14 @@
(error 'gfs:disposed-error))
(gfs:dispose it)))
-(defmethod clear-span :before ((self widget-with-items) (sp gfs:span))
+(defmethod delete-item-span :before ((self widget-with-items) (sp gfs:span))
(declare (ignore sp))
(if (gfs:disposed-p self)
(error 'gfs:disposed-error)))
-(defmethod clear-span ((self widget-with-items) (sp gfs:span))
+(defmethod delete-item-span ((self widget-with-items) (sp gfs:span))
(dotimes (i (1+ (- (gfs:span-end sp) (gfs:span-start sp))))
- (clear-item self (gfs:span-start sp))))
+ (delete-item self (gfs:span-start sp))))
(defmethod item-index :before ((self widget-with-items) (it item))
(declare (ignore it))
Modified: trunk/src/uitoolkit/widgets/widget.lisp
==============================================================================
--- trunk/src/uitoolkit/widgets/widget.lisp (original)
+++ trunk/src/uitoolkit/widgets/widget.lisp Tue Jul 11 16:33:21 2006
@@ -133,11 +133,12 @@
(declare (ignore self))
nil)
-(defmethod clear-all :before ((self widget))
+(defmethod clear-selection :before ((self widget))
(if (gfs:disposed-p self)
(error 'gfs:disposed-error)))
-(defmethod clear-selection :before ((self widget))
+(defmethod clear-selection-span :before ((self widget) span)
+ (declare (ignore span))
(if (gfs:disposed-p self)
(error 'gfs:disposed-error)))
@@ -167,6 +168,24 @@
(if (gfs:disposed-p self)
(error 'gfs:disposed-error)))
+(defmethod delete-all :before ((self widget))
+ (if (gfs:disposed-p self)
+ (error 'gfs:disposed-error)))
+
+(defmethod delete-item :before ((self widget) index)
+ (declare (ignore index))
+ (if (gfs:disposed-p self)
+ (error 'gfs:disposed-error)))
+
+(defmethod delete-item-span :before ((self widget) span)
+ (declare (ignore span))
+ (if (gfs:disposed-p self)
+ (error 'gfs:disposed-error)))
+
+(defmethod delete-selection :before ((self widget))
+ (if (gfs:disposed-p self)
+ (error 'gfs:disposed-error)))
+
(defmethod gfs:dispose ((self widget))
(unless (null (dispatcher self))
(event-dispose (dispatcher self) self))
Modified: trunk/src/uitoolkit/widgets/window.lisp
==============================================================================
--- trunk/src/uitoolkit/widgets/window.lisp (original)
+++ trunk/src/uitoolkit/widgets/window.lisp Tue Jul 11 16:33:21 2006
@@ -166,7 +166,7 @@
new-size))
(defmethod gfs:dispose ((self window))
- (remove-kbdnav-widget (thread-context) self)
+ (delete-kbdnav-widget (thread-context) self)
(call-next-method))
(defmethod enable-layout :before ((win window) flag)
More information about the Graphic-forms-cvs
mailing list