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

+@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

-@deffn GenericFunction clear-all self -Clears all content from @code{self}. -@end deffn - -@deffn GenericFunction clear-item self index -Clears the @ref{item} at the zero-based @var{index}. -@end deffn - @deffn GenericFunction clear-selection self -Sets the selection status of @code{self} to @samp{not selected} or -@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 +@var{self}) to the @samp{unselected} state. @end deffn

-@deffn GenericFunction clear-span self @ref{span} -Clears the items from @var{self} whose zero-based indices lie within -the specified @var{span}. +@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

+@deffn GenericFunction delete-all self +Removes all content from @code{self}. +@end deffn + +@deffn GenericFunction delete-item self index +Removes the @ref{item} at the zero-based @var{index}. +@end deffn + +@deffn GenericFunction delete-item-span self @ref{span} +Removes the items from @var{self} whose zero-based indices lie within +the specified @var{span}. +@end deffn + +@deffn GenericFunction delete-selection self +Removes the subset of items from @var{self} that are in the +@samp{selected} state. For a @ref{control} with a text field +component, such as an @ref{edit} control, this function deletes +selected text. +@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

+@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

-@strong{TBD} +@menu +* terminology:: Some notes about terminology conventions. +@end menu + + +@node terminology +@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 +@url{http://www.cliki.net/Naming%20conventions%7D). + +@table @option + +@item accessor names +For clearer identification of accessors, Graphic-Forms +uses the suffix @samp{-of} whenever possible. + +@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 +@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 +@ref{undo-available-p}. + +@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 +@sc{CL:delete}, including the notion of that function being a +destructive operation. + +@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. + +@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)