element

element Class

Summary

The class element is the superclass of all CAPI objects that appear in a window.

Package

capi

Superclasses

capi-object

Subclasses

simple-pane
menu

Initargs

`:parent`	The element containing this element.
`:interface`	The interface containing this element.
`:accepts-focus-p`	Specifies that the element should accept input.
`:help-key`	An object used for lookup of help. Default value `t`.
`:widget-name`	A string designator.
`:initial-constraints`
	Specifies constraints (geometry hints) that apply to the element during the creation of the element's interface, but not after the interface is displayed.
`:x`	A geometry hint specifying the initial `x` position of the element in a pinboard.
`:y`	A geometry hint specifying the initial `y` position of the element in a pinboard.
`:external-min-width`
	A geometry hint specifying the minimum width of the element in its parent.
`:external-min-height`
	A geometry hint specifying the minimum height of the element in its parent.
`:external-max-width`
	A geometry hint specifying the maximum width of the element in its parent.
`:external-max-height`
	A geometry hint specifying the maximum height of the element in its parent.
`:visible-min-width`	A geometry hint specifying the minimum visible width of the element.
`:visible-min-height`
	A geometry hint specifying the minimum visible height of the element.
`:visible-max-width`	A geometry hint specifying the maximum visible width of the element.
`:visible-max-height`
	A geometry hint specifying the maximum height of the element.
`:internal-min-width`
	A geometry hint specifying the minimum width of the display region.
`:internal-min-height`
	A geometry hint specifying the minimum height of the display region.
`:internal-max-width`
	A geometry hint specifying the maximum width of the display region.
`:internal-max-height`
	A geometry hint specifying the maximum height of the display region.

Accessors

element-parent
element-widget-name

Readers

element-interface
help-key

Description

The class element contains the slots parent and interface which contain the element and the interface that the element is contained in respectively. The writer method element-parent can be used to re-parent an element into another parent (or to remove it from a container entirely by setting its parent to nil). Note that an element should not be used in more than one place at a time.

The initarg accepts-focus-p specifies that the element can accept input. The default value is t. In some subclasses including display-pane and title-pane the default value of accepts-focus-p is nil. A pane accepts the input focus if and only if the function accepts-focus-p returns true.

accepts-focus-p also influences whether a pane is a tabstop on Microsoft Windows, where a pane acts as a tabstop if and only if the function accepts-focus-p returns true and the :accepts-focus-p initarg value is :force. On Motif and Cocoa, a pane acts as a tabstop if and only if the function accepts-focus-p returns true.

help-key is used to determine how help is displayed for the pane. The value nil means that no help is displayed. Otherwise, help-key is passed to the help-callback, except when help-key is t, when the name of the pane is passed to the help-callback. For details of help-callback, see interface.

widget-name specifies the widget name of the element. This is used to match resources on GTK+ and Motif. Note that this name will be in the path only if the element has a representation. tab-layout and pinboard-layout always have a representation, as do all elements that show anything on the screen. Other layouts may or may not have a representation and so you should not supply widget-name for these.

The actual widget name is the result of a call to cl:string, except when widget-name is a symbol, in which case the symbol name is downcased to derive the widget name.

If widget-name is not supplied, the system constructs a default widget name which is the name of the class of the widget (downcased), except for top level interfaces on GTK+ where the application-class is prepended followed by a dot.

Example GTK+ resource files are in lib/8-0-0-0/examples/gtk/.

Note: When widget-name is supplied, the GTK+ library does not prepend the application-class.

The accessor element-widget-name gets and (with setf) sets the widget-name. widget-name is used when the widget is created, that is when display is called on the top level interface of the element. Setting widget-name afterwards has no effect.

All elements accept initargs (listed above) representing hints as to the initial size and position of the element. By default elements have a minimum pixel size of one by one, and a maximum size of nil (meaning no maximum), but the hints can be specified to change these values. For the detailed interpretation of, and possible values for, these hints see 6.4.1 Width and height hints.

Notes

Some classes have default initargs providing useful hints. For example, display-pane has :text-height as the default value of :visible-min-height, ensuring that the text is visible.
The ratios, x-ratios and y-ratios settings in some layouts (for example grid-layout) also control the actual size of the pane when the constraints are not specified. In particular, if nil is used in the ratios then the associated pane(s) will be fixed at their minimum size.

Examples

(capi:display (make-instance 'capi:interface
                              :title "Test"
                              :visible-min-width 300))

(capi:display (make-instance 'capi:interface
                              :title "Test"
                              :visible-min-width 300
                              :visible-max-height 200))

Here is a simple example that demonstrates the use of the element-parent accessor to place elements.

(setq pinboard (capi:contain
                (make-instance 
                 'capi:pinboard-layout)
                :visible-min-width 520
                :visible-min-height 395))
 
(setq object 
      (make-instance
       'capi:image-pinboard-object
       :x 10 :y 10
       :image
       (example-file "capi/graphics/Setup.bmp")
       :parent pinboard))
 
(capi:apply-in-pane-process
 pinboard #'(setf capi:element-parent) nil object)
 
(capi:apply-in-pane-process
 pinboard #'(setf capi:element-parent) pinboard object)

These final two examples illustrate the effect of initial-constraints.

Create a pane that starts at least 600 pixels high, but can be made shorter by the user:

(capi:contain
 (make-instance 'capi:output-pane
                :initial-constraints '(:visible-min-height 600)))

Compare with this, which creates a pane at least 600 pixels high but which cannot be made shorter.

(capi:contain
 (make-instance 'capi:output-pane
                :visible-min-height 600))