Chapter 2. Classes
Section 2.1. Foundations
class: (create <toplevel>)
returns: instance
A toplevel is like a frame except that it exists as a free-standing window
on the X display. A toplevel can display a title and may or may not
allow the user to resize it. A toplevel can be iconified or withdrawn
from the screen entirely. When iconified a toplevel may display
a different string.
The actual appearance of the toplevel will be determined in part by
the window manager used.
Methods:
Inherited methods:
class: (create <frame> parent)
returns: instance
A frame provides a simple container for other widgets.
Frames are primarily useful for
building more complex window layouts and consequently
have only a few visual attributes that may be changed.
Inherited methods:
Section 2.2. Labels, Buttons, and Menus
class: (create <label> parent)
returns: instance
A label displays static (non-editable) text or an image.
Text is displayed in a uniform font (determined by set-font!)
and is displayed as multiple lines if the text contains newlines
or its length exceeds the wrap length (see set-wrap-length!).
The text displayed by a label can be changed by the set-title!
method. By default labels are not responsive to user interaction,
but this can be changed via bind.
Support for bitmap, GIF, PPM, and PGM images is in the works.
Inherited methods:
class: (create <button> parent)
returns: instance
A button displays a text string or image and performs the
action specified by set-action! when pressed. By default
a button can be pressed by clicking mouse button 1 when
the mouse cursor is over the button, or by pressing Return or
Space when the button has keyboard focus.
Other default bindings arrange to change the appearance of the
button when the mouse enters or leaves the button or when the
button has keyboard focus.
When the button is pressed, its 3-D border is changed so that it
appears to have been pressed. These behaviors
can be changed by the bind method.
Buttons can be made responsive or unresponsive to user input
via the set-enabled! method.
Text is displayed in a uniform font (determined by set-font!)
and is displayed as multiple lines if the text contains newlines
or its length exceeds the wrap length (see set-wrap-length!).
The text displayed by a button can be changed by the set-title!
method.
Inherited methods:
class: (create <radiobutton> parent)
returns: instance
A radiobutton displays a text string or image and a small diamond called
the indicator, whichs shows whether or not the button is selected.
When a radiobutton is selected the indicator is colored and all
other radiobuttons with the same parent are unselected. Thus a group
of mutually-exclusive radiobuttons can be made by creating a frame
and creating the radiobuttons as children of the frame.
The set-draw-indicator! method determines whether the state
of the radiobutton
is depicted by drawing an indicator or by changing the appearance of the
whole button.
The action specified by set-action! is performed if
mouse button 1 is clicked when
the mouse cursor is over the radiobutton, or if the button has
keyboard focus and Return or Space is pressed.
Other default bindings arrange to change the appearance of the
radiobutton when the mouse enters or leaves the radiobutton or when the
radiobutton has keyboard focus.
When the radiobutton is pressed, its 3-D border is changed so that it
appears to have been pressed.
These behaviors can be changed by the bind method.
Radiobuttons can be made responsive or unresponsive to user input
via the set-enabled! method.
Text is displayed in a uniform font (determined by set-font!)
and is displayed as multiple lines if the text contains newlines
or its length exceeds the wrap length (see set-wrap-length!).
The text displayed by a radiobutton can be changed by the set-title!
method.
Methods:
Inherited methods:
class: (create <checkbutton> parent)
returns: instance
A checkbutton displays a text string or image and a small square called
the indicator, whichs shows whether or not the button is selected.
When the button is selected the indicator is colored.
The set-draw-indicator! method determines whether the state
is depicted by drawing an indicator or by changing the appearance of the
whole button.
The action specified by set-action! is performed if
mouse button 1 is clicked when
the mouse cursor is over the checkbutton, or if the button has
keyboard focus and Return or Space is pressed.
Other default bindings arrange to change the appearance of the
checkbutton when the mouse enters or leaves the checkbutton or when the
checkbutton has keyboard focus.
When the checkbutton is pressed, its 3-D border is changed so that it
appears to have been pressed.
These behaviors can be changed by the bind method.
Checkbuttons can be made responsive or unresponsive to user input
via the set-enabled! method.
Text is displayed in a uniform font (determined by set-font!)
and is displayed as multiple lines if the text contains newlines
or its length exceeds the wrap length (see set-wrap-length!).
The text displayed by a checkbutton can be changed by the set-title!
method.
Methods:
Inherited methods:
class: (create <option-button> parent default)
returns: instance
An option button allows the user to select an item from a list
of choices presented as a menu that appears over the button.
An option button displays the currently selected text string or image.
Text is displayed in a uniform font (determined by set-font!)
and is displayed as multiple lines if the text contains newlines
or its length exceeds the wrap length (see set-wrap-length!).
The text displayed by a button can be changed by the set-title!
method.
Because the underlying widget library (Tcl/Tk) behaves differently
under Windows,
option buttons do not respond to the usual SWL event notification
methods.
Methods:
Inherited methods:
class: (create <menu> items)
returns: instance
A menu displays a list of labels that perform actions or post cascaded
menus when selected.
A list of items may be supplied when a menu is created,
or installed via the set-menu-items! method.
The items are expected to be instances of the various menu item
classes described later.
The order of items in the list determines their order on the menu.
The make-menu macro simplifies the construction of instances of
<menu>.
Tear-off menus are disabled until a Tk bug with tear-offs is fixed.
Methods:
Inherited methods:
class: (create <command-menu-item>)
returns: instance
The command-menu-item displays a string or image and invokes the
specified action when selected from the menu.
Inherited methods:
class: (create <cascade-menu-item>)
returns: instance
A cascade-menu-item displays a string or image and displays a sub-menu
when selected from the menu.
When a menu is used as the menu bar of a <toplevel>, the
first level cascade-menu-items form the row of menus items visible in the
menu bar.
Methods:
Inherited methods:
class: (create <separator-menu-item>)
returns: instance
A separator-menu-item is drawn as a line separating the menu items
it is placed between. It has no associated action and exists purely
for decoration.
Methods:
Inherited methods:
class: (create <radio-menu-item>)
returns: instance
A radio-menu-item displays a string and a selector or an image that
indicates whether or not the option represented by this item is selected.
Radio-menu-items on the same menu are mutually exlusive: at most one
can be selected.
Methods:
Inherited methods:
class: (create <check-menu-item>)
returns: instance
A check-menu-item displays a string and a selector or an image that
indicates whether or not the option represented by this item is selected.
Check-menu-items on the same menu are not mutually exlusive: zero or more
may be selected.
Methods:
Inherited methods:
Section 2.3. Attributes
class: (create <font> family size style)
returns: instance
Fonts are represented by instances of the <font> class.
(See also the make-font macro.)
A font is characterized by three parameters:
- family
- is a symbol that describes the typeface
(eg. times, helvetica, fixed, etc.).
If the requested family is not known to the local display,
the behavior is unspecified.
See swl:font-families.
- size
- is an integer indicating the font size.
Positive values indicate size in points, negative values
indicate size in pixels.
- style
- is a list of symbols describing other
desired attributes of the font. The list may contain
zero or more of the following symbols: normal,
bold, roman, italic,
underline, and overstrike.
If the list contains duplicates or opposites (eg. roman
and italic), the behavior is unspecified.
The display engine attempts to find the closest match for the
requested font. Unfortunately the underlying graphics toolkit
provides no apparent way to determine whether a precise match was
found or some substitution was made. By comparing actual font
attributes with the requested values, it is possible to determine
when the family or slant (roman or italic)
request could not be satisfied. However, there seems to be no way
to determine when a font was scaled to meet the requested size.
Scaling bitmap fonts often yields poor results.
Methods:
Inherited methods:
class: (create <rgb> r g b)
class: (make <rgb> red green blue)
returns: instance
An instance of <rgb> contains three integer values
representing the red, green and blue components of
a particular color.
Methods:
Inherited methods:
class: (create <photo>)
returns: instance
This class manipulates full color images which can
be used as the image: attribute
for widgets such as <label> that can display images.
The filename argument specifies the name of a file
containing the (GIF or PPM) photo data.
Methods:
Inherited methods:
class: (create <bitmap>)
returns: instance
This class manipulates monochrome bitmap images which can
be used as the image: attribute
for widgets such as <label> that can display images.
The filename argument specifies the name of a file
containing the (X11) bitmap data.
Methods:
Inherited methods:
Section 2.4. Displaying and Editing Text
class: (create <listbox> parent)
returns: instance
A listbox displays a list of strings, one per line, in a uniform font.
Items may be inserted, deleted, or retrieved from the listbox using
methods described below. The position of each item in the listbox
is described by a zero-based index. The special index end refers
to the last item in the listbox.
Multiple items in the listbox
may be selected and the selection may be exported as the X selection.
Listboxes can be scrolled horizontally and vertically.
A cursor is displayed as an underline when the listbox
has input focus.
Methods:
Inherited methods:
class: (create <entry> parent)
returns: instance
An entry displays a single line of text that may be edited using
the arrow keys and emacs-like key bindings.
Text is displayed in a single font that may be changed by set-font!.
Text in an entry can be selected and the selection can exported
as the X selection if desired. When an entry has input focus it
displays an insertion cursor. An entry can be scrolled
horizontally when the string is too long to be displayed in the window.
The contents of an entry can be retrieved as a Scheme string.
Several entry methods take an argument specifying position in the
entry.
Positions in the entry are numbered from zero. The symbol
end can be used to refer to the last position in the entry.
Methods:
Inherited methods:
class: (create <text> parent)
returns: instance
The text widget
displays multiple lines of text which may be edited. Text within
the widget can be selected, and the selection can be exported as
the X selection if desired. When a text widget has input focus
it displays an insertion cursor. Text widgets can be scrolled
both horizontally and vertically to show contents that do not fit
within the window.
Positions within a text widget are represented by pairs of
natural numbers (column . line), the symbol end which
refers to the end of the text,
by instances of the <floating-mark> and <fixed-mark> classes
returned by the floating-mark and fixed-mark methods
of the text widget, and by the symbolic marks insert (the position
of the insertion cursor), and end (the end of the buffer).
In addition to text, the text widget can display embedded sub-windows
provided they have the same parent as the text widget, or have the
text widget as their parent.
The font, foreground and background color, 3-D relief, stippling
effects, and event bindings of individual ranges in the text
widget can be manipulated by a mechanism that has been temporarily
disabled.
Methods:
Inherited methods:
class: (create <markup>)
returns: instance
Markups can be applied to regions of text in a <text> widget
to control the display and behavioral properties of that region.
A given markup may be applied to regions of text in several different
text widgets.
See the apply-markup method for more detail.
Markups exist in a stacking order (latest applied is topmost) that
determines which display properties are visible. Many text display
attributes can be set on a markup which is otherwise transparent.
Setting a markup attribute to #f makes it transparent again for
that attribute. For example, setting the font of a markup to #f
permits the font of underlying markups (or the text widget) to show
through.
By default the event notification methods can be changed dynamically
for markups. Since several markups may apply to a range of text
it may be desirable to invoke the notification methods of more than one markup
for a given event. To permit notification methods of other markups to be invoked,
a notification method can simply return #f. Any other return value
prevents other methods from running. Markups are notified of events by stacking order.
Methods:
Inherited methods:
class: (create <floating-mark> txt-proc)
returns: instance
Instances of the <floating-mark> class are used to refer to positions
between two characters in a text widget.
A <floating-mark> moves when text is inserted at the position
of the mark and may move when text is inserted or deleted elsewhere
in the widget.
The floating-mark method of the <text> widget creates
a new mark at the given position (which is either an index or another
mark).
(send text-widget floating-mark position)
Inherited methods:
class: (create <fixed-mark> txt-proc)
returns: instance
Instances of the <fixed-mark> class are used to refer to positions
between two characters in a text widget.
A <fixed-mark> does not move when text is inserted at the position
of the mark but may move when text is inserted or deleted elsewhere
in the widget.
The fixed-mark method of the <text> widget creates
a new mark at the given position (which is either an index or another
mark).
Inherited methods:
class: (create <tab-stop> position alignment)
class: (make <tab-stop> position alignment)
returns: instance
A tab stop has a pixel position and an alignment
that is either left, right, center, or numeric.
A numeric tab centers text with respect to the decimal point.
Methods:
Inherited methods:
Section 2.5. Control Widgets
class: (create <scrollbar> parent)
returns: instance
The size and position of the scrollbar's slider provides information
about what is visible in an associated window. Clicking on the arrows
at either end of the scrollbar, or dragging on the slider typically
scrolls the view in the associated window. Like scales, scrollbars
can be oriented horizontally or vertically.
Soon we will provide classes that abstract the process of
linking a scrollbar with another widget.
Methods:
Inherited methods:
class: (create <scale> parent)
returns: instance
A scale allows the user to interactively select a value
from a range of integer or floating point
values by dragging a slider bar along a trough whose length
represents the range.
The slider can be moved by
clicking or dragging the mouse or using the arrow keys
when the slider has keyboard focus.
When the slider's value changes, the value is passed to the
procedure specified by set-action!.
A scale can display the currently selected value underneath the slider
and can also show tick marks. Scales can be oriented horizontally
or vertically.
Methods:
Inherited methods:
Section 2.6. Drawing
class: (create <canvas> parent)
returns: instance
A canvas
provides screen real-estate on which a variety of figures can be
drawn: rectangles, ovals, arcs, lines, images, polygons, text,
and sub-windows. Items on the canvas can be moved, raised,
lowered, etc. Canvases can generate Encapsulated PostScript
representations of part or all of their area.
Canvases can be scrolled vertically and horizontally.
See the descriptions of the various canvas items for more details on the
kinds of figures that can appear on a canvas.
Methods:
Inherited methods:
class: (create <rectangle> canvas x1 y1 x2 y2)
returns: instance
A rectangle appears as a rectangular region on the canvas and may be
filled, have an outline or both.
The region covered by the rectangle is defined by
x1, y1, x2, y2.
The thickness and color of the outline
can be specified as well.
Inherited methods:
class: (create <oval> canvas x1 y1 x2 y2)
returns: instance
An oval appears as a circle or oval on the canvas that
may be filled with a color, or have an outline, or both.
The oval is inscribed within the rectangular region defined by
x1, y1, x2, y2.
The thickness and color of the oval's outline
can be specified as well.
Inherited methods:
class: (create <arc> canvas x1 y1 x2 y2)
returns: instance
An arc is a section of an
oval delimited by two angles (see set-start! and set-end!).
The arc is inscribed within the rectangular region defined by
x1, y1, x2, y2.
An arc can be displayed as a pieslice, chord, or arc
(see set-style!) and can be filled with a color or have an
outline or both. The thickness and color of the outline
can be specified as well.
Methods:
Inherited methods:
class: (create <line> canvas x1 y1 x2 y2 more ...)
returns: instance
Lines are displayed as one or more connected line segments or
curves. The init method requires coordinates for a series of
two or more end-points of a series of connected line segments (or
curves). Lines can have arrow heads at either or both ends, and the
shape of the arrowhead can be adjusted. The end-points of a
line can drawn rounded, projecting, etc. The joints between line
segments (or curves) can be drawn beveled, mitered, or rounded.
The line can be smoothed as a spline, and the degree of
smoothness can be specified. Width can also be specified.
Methods:
Inherited methods:
class: (create <polygon> canvas x1 y1 x2 y2 x3 y3 more ...)
returns: instance
A polygon is a closed figure with three or more points
and may be filled or drawn with an outline.
Methods:
Inherited methods:
class: (create <canvas-text> canvas x1 y1)
returns: instance
A canvas-text displays a string of characters in a canvas window.
The main differences between this and a <text> widget are that
<canvas-text> is a graphics object (so other figures can show
through or partially occlude the displayed string), and this
class lacks some of the fancier text-manipulation ability of
<text>.
Methods:
Inherited methods:
class: (create <canvas-image> canvas x1 y1)
returns: instance
Images can display bitmaps, and images in GIF, or PPM, and PGM format.
They are not yet finished.
Methods:
Inherited methods:
class: (create <canvas-sub-window> canvas x1 y1)
returns: instance
A canvas-sub-window allows other widgets to be placed on a canvas
anchored at a particular point. We hope to make this process
transparent soon.
Methods:
Inherited methods: