Author: junrue
Date: Mon Aug 28 16:33:21 2006
New Revision: 240
Modified:
trunk/docs/manual/reference.texinfo
trunk/docs/manual/widget-functions.texinfo
trunk/docs/manual/widget-types.texinfo
Log:
refined controls section of manual, added more doc for list-box
Modified: trunk/docs/manual/reference.texinfo
==============================================================================
--- trunk/docs/manual/reference.texinfo (original)
+++ trunk/docs/manual/reference.texinfo Mon Aug 28 16:33:21 2006
@@ -89,6 +89,21 @@
The @ref{point} location of the mouse cursor.
@end macro
+@macro control-callback-initarg{classname,callbackname}
+@deffn Initarg :callback
+The function supplied via this initarg will be used as
+the implementation of @sc{@ref{\callbackname\}} in an
+@ref{event-dispatcher} configured for the \classname\.
+See also @var{callback-event-name}.
+@end deffn
+@end macro
+
+@macro control-parent-initarg{classname}
+@deffn Initarg :parent
+This initarg specifies the @ref{parent} of the \classname\.
+@end deffn
+@end macro
+
@macro begin-control-subclass{classname,descr,callbackname}
@anchor{\classname\}
@deftp Class \classname\ callback-event-name
Modified: trunk/docs/manual/widget-functions.texinfo
==============================================================================
--- trunk/docs/manual/widget-functions.texinfo (original)
+++ trunk/docs/manual/widget-functions.texinfo Mon Aug 28 16:33:21 2006
@@ -8,10 +8,12 @@
@node Widget functions
@subsection Widget functions
-@deffn GenericFunction ancestor-p ancestor descendant
-Returns T if ancestor is an ancestor of descendant; nil otherwise.
+@anchor{ancestor-p}
+@deffn GenericFunction ancestor-p ancestor descendant => boolean
+Returns T if @var{ancestor} is the parent of @var{descendant}; nil otherwise.
@end deffn
+@anchor{append-item}
@deffn GenericFunction append-item self text image dispatcher &optional disabled checked
Adds the new item with the specified @code{text}, @code{image}, and
@ref{event-dispatcher} to the object, and returns the newly-created item.
Modified: trunk/docs/manual/widget-types.texinfo
==============================================================================
--- trunk/docs/manual/widget-types.texinfo (original)
+++ trunk/docs/manual/widget-types.texinfo Mon Aug 28 16:33:21 2006
@@ -61,13 +61,13 @@
@anchor{item}
@deftp Class item item-id
-The @code{item} class is the base class for all non-windowed user
-interface objects serving as subcomponents of a
-@ref{item-manager} object. It derives from @ref{event-source}.
-@deffn Initarg :item-id
-@end deffn
-@deffn Accessor item-id
-@end deffn
+This is the base class for all non-windowed user
+interface objects serving as subcomponents of an
+@ref{item-manager}. It derives from @ref{event-source}.
+@table @var
+@item item-id
+An identifier for the item managed internally by Graphic-Forms.
+@end table
@end deftp
@anchor{item-manager}
@@ -104,7 +104,7 @@
@anchor{menu}
@deftp Class menu
This class represents a container for menu items and submenus. It
-derives from @ref{item-manager}.
+derives from @ref{widget} and @ref{item-manager}.
@end deftp
@anchor{menu-item}
@@ -146,17 +146,14 @@
@subsection Controls
@begin-control-subclass{button,
-This @ref{control} class represents selectable controls that generate
+This @ref{control} subclass represents selectable controls that generate
an event when clicked.,
event-select}
-@deffn Initarg :callback
-The @sc{function} value supplied via this initarg will be
-used as the implementation of @ref{event-select} in an
-@ref{event-dispatcher} configured for the @code{button}.
-@end deffn
+@control-callback-initarg{button,event-select}
@deffn Initarg :image
-Supplies an image to be used as the @code{button}'s label.
+Supplies an image to be used as the button's label.
@end deffn
+@control-parent-initarg{button}
@deffn Initarg :style
@table @code
@item :cancel-button
@@ -165,26 +162,26 @@
action should be interpreted as the user discarding the content of the
dialog.
@item :check-box
-This style specifies a @code{button} having a small box, which may
-contain a check mark depending on the @code{button}'s selection state,
+This style specifies a button having a small box, which may
+contain a check mark depending on the button's selection state,
adjacent to a text label.
@item :default-button
Placing a @code{:default-button} in a dialog enables the @sc{return}
key @ref{accelerator} for dismissing the dialog. This action should be
interpreted as the user accepting the content of the dialog. Also, the
-@code{button} is rendered with an extra thick border.
+button is rendered with an extra thick border.
@item :push-button
This style specifies a traditional push button control. No special
keyboard accelerators are enabled.
@item :radio-button
-This style specifies a @code{button} having a small circle, which may
-be filled or unfilled depending on the @code{button}'s selection
-state, adjacent to a text label. Radio @code{button}s are typically
+This style specifies a button having a small circle, which may
+be filled or unfilled depending on the button's selection
+state, adjacent to a text label. Radio buttons are typically
used in groups and are managed such that only one member of the group
is enabled at a time.
@item :toggle-button
This style specifies a control that when unselected looks like a push
-@code{button}. But when in the selected state, the @code{button}
+button. But when in the selected state, the button
maintains a sunken look. It is similar in function to a
@code{:check-box}.
@item :tri-state
@@ -194,7 +191,7 @@
@end table
@end deffn
@deffn Initarg :text
-Supplies the text for the @code{button} label.
+Supplies the text for the button label.
@end deffn
@end-control-subclass
@@ -202,67 +199,65 @@
@deftp Class control brush-color brush-handle font pixel-point maximum-size minimum-size text-color
The base class for widgets having pre-defined native behavior. It derives from
@ref{widget}.@*@*
-@strong{Note:} application code should not manipulate @code{control} slots
-directly, unless defining a new @code{control} type as an extension to
+@strong{Note:} application code should not manipulate control slots
+directly, unless defining a new control type as an extension to
Graphic-Forms.
@table @var
@item brush-color
-If set, this @ref{color} object is used as the @code{control}'s background color
-when the @code{control} needs to be redrawn.
+If set, this @ref{color} object is used as the control's background color
+when the control needs to be redrawn.
@item brush-handle
This is a native handle for a Win32 @sc{brush} that is used when customizing
-the @code{control}'s background color.
+the control's background color.
@item font
-This is a @ref{font} object for customizing the text of a @code{control}.
+This is a @ref{font} object for customizing the text of a control.
@item pixel-point
This is a @ref{point} object specifying a pixel in an @ref{image}
-associated with a @code{control}, for the purpose of determining what
+associated with a control, for the purpose of determining what
color to use for transparency.
@item maximum-size
This is a @ref{size} object that places a maximum constraint on the
-size that a @ref{layout-manager} may set for the @code{control}. It
+size that a @ref{layout-manager} may set for the control. It
may be @sc{nil} if no such constraint has been set.
@item minimum-size
This is a @ref{size} object that places a minimum constraint on the
-size that a @ref{layout-manager} may set for the @code{control}. It
+size that a @ref{layout-manager} may set for the control. It
may be @sc{nil} if no such constraint has been set.
@item text-color
-If set, this color object is used as the @code{control}'s foreground text
-color when the @code{control} needs to be redrawn.
+If set, this color object is used as the control's foreground text
+color when the control needs to be redrawn.
@end table
@deffn Initarg :callback
-This initarg associates a @sc{function} with an @ref{event-dispatcher}
+This initarg associates a function with an @ref{event-dispatcher}
subclass that is generated behind the scenes and then instantiated to
-serve as the @code{control}'s event dispatcher. Each @code{control}
+serve as the control's event dispatcher. Each control
subclass specifies the particular event function (e.g., @ref{event-select})
that this callback will implement; see the documentation for specific
-@code{control} subclasses for more information on this initarg.
+control subclasses for more information on this initarg.
@end deffn
+@control-parent-initarg{control}
@end deftp
@begin-control-subclass{edit,
This subclass of @ref{control} represents a rectangular area that
permits the user to enter and edit text. The @ref{event-focus-gain}
-and @ref{event-focus-loss} methods of each @code{edit control}'s
+and @ref{event-focus-loss} methods of each edit control's
@ref{event-dispatcher} are invoked when focus is given or taken
away. The @ref{event-modify} method is invoked when the user edits
content.,
event-modify}
-@deffn Initarg :callback
-The @sc{function} value supplied via this initarg will be
-used as the implementation of @ref{event-modify} in an
-@ref{event-dispatcher} configured for the @code{edit control}.
-@end deffn
+@control-callback-initarg{edit,event-modify}
+@control-parent-initarg{edit}
@deffn Initarg :style
@table @code
@item :auto-hscroll
-Specifies that the @code{edit control} will scroll text content to the
+Specifies that the edit control will scroll text content to the
right by 10 characters when the user types a character at the end
-of the line. For single-line @code{edit control}s, this style is set
+of the line. For single-line edit controls, this style is set
by the library. See @ref{auto-hscroll-p}, @ref{auto-vscroll-p}, and
@ref{enable-auto-scrolling}.
@item :auto-vscroll
-Specifies that the @code{edit control} will scroll text up by a page
+Specifies that the edit control will scroll text up by a page
when the user types @sc{enter} on the last line. This style keyword
is only meaningful when @code{:multi-line} is also specified. See
@ref{auto-hscroll-p}, @ref{auto-vscroll-p}, and
@@ -274,21 +269,21 @@
instead of the one literally typed. The character can be changed via
the @ref{echo-character} @sc{setf} method.
@item :multi-line
-By default, @code{edit control}s are single-line text fields. By specifying
+By default, edit controls are single-line text fields. By specifying
@code{:multi-line}, multiple lines of text can be supplied. When the
-@code{edit control} is in a @ref{dialog}, the @sc{enter} key will invoke
+edit control is in a @ref{dialog}, the @sc{enter} key will invoke
the default @ref{button}'s @ref{event-dispatcher}, unless
@code{:want-return} is also specified. If @code{:auto-hscroll} is not
specified, then text will be automatically word-wrapped.
@item :no-border
-By default, an @code{edit control} is rendered with a border; this style
+By default, an edit control is rendered with a border; this style
keyword disables that feature.
@item :no-hide-selection
This specifies that any selection remain rendered even when the
-@code{edit control} loses input focus. By default, the selection
+edit control loses input focus. By default, the selection
is hidden when focus is lost.
@item :read-only
-Specifies that the @code{edit control}'s contents cannot be modified by
+Specifies that the edit control's contents cannot be modified by
the user.
@item :vertical-scrollbar
Specifies that a vertical scrollbar should be displayed.
@@ -301,13 +296,14 @@
@end table
@end deffn
@deffn Initarg :text
-Supplies the initial text for the @code{edit control}.
+Supplies the initial text for the edit control.
@end deffn
@end-control-subclass
@begin-control-subclass-no-callback{label,
This @ref{control} subclass represents non-selectable controls that
display a string\, image\, or etched line.}
+@control-parent-initarg{label}
@deffn Initarg :image
Supply an @ref{image} object as the value of this initarg to configure
the label to display the image rather than text.
@@ -347,8 +343,50 @@
@end-control-subclass
@begin-control-subclass{list-box,
-This @ref{control} class represents a list of selectable items.,
+This @ref{control} subclass represents a list of selectable items; it
+also inherits @ref{item-manager}. The list is always visible\, unlike
+a combo-box.,
event-select}
+@control-callback-initarg{list-box,event-select}
+@deffn Initarg :collator
+This initarg accepts a predicate function of two arguments
+returning a @sc{boolean}, for the purpose of ordering the list-box
+items. The arguments passed are the application-supplied data objects
+used to populate the list-box.
+@end deffn
+@deffn Initarg :initial-items
+This initarg accepts a list of objects for initially populating the
+contents of the list-box. @sc{print-object} will be called for
+each object to produce the corresponding item's display string.
+The list-box will hold references to the supplied objects. See
+also @ref{append-item}.
+@end deffn
+@control-parent-initarg{list-box}
+@deffn Initarg :style
+@table @code
+@item :extend-select
+This style keyword causes the list-box to allow multiple items to
+be selected by use of the @sc{shift} key and the mouse or special
+keys.
+@item :multiple-select
+This style keyword enables individual toggling of multiple item
+selections within the list-box. Without this style, the list-box will
+only allow a single selection.
+@item :no-select
+This style keyword means that the list-box will display items but
+not allow any selections.
+@item :tab-stops
+This style keyword configures the list-box to to expand tab characters
+when rendering item strings.
+@item :want-keys
+This style keyword allows the application to perform special processing
+when the list-box has focus and the user presses a key.
+@item :want-scrollbar
+This style keyword causes the list-box to show a disabled vertical
+scrollbar when it does not contain enough items to scroll. Otherwise
+in such a case, the scrollbar will be hidden.
+@end table
+@end deffn
@end-control-subclass
