3.1 Generic properties

Because CAPI elements are just like CLOS classes, many elements share a common set of properties. The remainder of this section describes the properties that all the classes described in this chapter inherit.

3.1.1 Scroll bars

The CAPI lets you specify horizontal or vertical scroll bars for any subclass of the simple-pane element (including all of the classes described in this chapter).

Horizontal and vertical scroll bars can be specified using the keywords :horizontal-scroll and :vertical-scroll. By default, both :vertical-scroll and :horizontal-scroll are nil.

3.1.2 Background and foreground colors

All subclasses of the simple pane element can have different foreground and background colors, using the :background and :foreground initargs. For example, including

:background :blue

:foreground :yellow

in the make-instance of a text pane would result in a pane with a blue background and yellow text.

3.1.3 Fonts

The CAPI interface supports the use of other fonts for text in title panes and other CAPI objects, such as buttons, through the use of the :font keyword. If the CAPI cannot find the specified font it reverts to the default font. The :font keyword applies to data following the :text keyword. The value is a graphics ports font-description object specifying various attributes of the font.

On systems running X Windows, the xlsfonts command can be used to list which fonts are available. The X logical font descriptor can be explicitly passed as a string to the :font initarg, which will convert them.

Here is an example of a title-pane with an explicit font:

(contain

 (make-instance 'title-pane

                :text "A title pane"

                :font (gp:make-font-description

                       :family "Times"

                       :size 12

                       :weight :medium

                       :slant :roman)))

Here is an example of using :font to produce a title pane with larger lettering. Note that the CAPI automatically resized the pane to fit around the text.

(contain

 (make-instance 'title-pane

                :text "A large piece of text"

                :font (gp:make-font-description

                       :family "Times"

                       :size 34

                       :weight :medium

                       :slant :roman)))

Figure 3.1 An example of the use of font descriptions

3.1.4 Mnemonics

This section applies to Microsoft Windows and GTK+ only.

Underlined letters in menus, titles and buttons are called mnemonics. The user can select the element by pressing the corresponding key.

3.1.4.1 Controlling Mnemonics

For individual buttons, menus, menu items and title panes, you can use the :mnemonic initarg to control them. For example:

(capi:contain (make-instance 'capi:push-button

                             :data "FooBar"

                             :mnemonic #\B))

For more information on mnemonics in buttons, see Mnemonics in buttons.

For information on controlling mnemonics in button panels, see Mnemonics in button panels. For information on controlling mnemonics in menus, see Mnemonics in menus.

The initarg :mnemonic-title allows you to specify the mnemonic in the title for many pane classes including list-panel, text-input-pane and option-pane. Also grid-layout supports mnemonic-title when has-title-column-p is true. For the details see titled-object.

3.1.4.2 Mnemonics on Microsoft Windows

On Microsoft Windows the user can make the mnemonics visible by holding down the Alt key.

Windows can hide mnemonics when the user is not using the keyboard. This is controlled in Windows 8 by

Control Panel > Ease of Access > Ease of Access Center > Make the keyboard easier to use > Underline keyboard shortcuts and access keys

and in Windows XP by

Control Panel > Display > Appearance > Effects > Hide underlined letters...

3.1.5 Focus

The focus is where keyboard gestures are sent.

You can specify that a pane should or should not get the focus by using the initarg :accepts-focus-p (defined for element). By default interactive elements except menus accept focus, and non-interactive elements do not accept focus, so normally you do not need to use :accepts-focus-p.

3.1.5.1 Initial focus

By default, when a window first appears the focus is in the top-left pane that accepts focus. You can override this by using the initarg :initial-focus or using the accessor pane-initial-focus on interfaces and layouts, and using the initarg :initial-focus-item for choices (check-button-panel for example).

3.1.5.2 Querying the focus

The function pane-descendant-child-with-focus can find a child pane that has the focus, when given as argument a pane with children such as a layout, an interface, or certain choices including a button-panel and toolbar.

The function pane-has-focus-p can be used to determine if a specific pane has the focus.

3.1.5.3 Setting the focus dynamically

The function set-pane-focus can be used to set the focus to a pane inside an active window. If you need to ensure that the window is active, you can use activate-pane, which activates the window and sets the focus. For panes that have children (as described in Querying the focus) the actual pane that receives the focus is the "initial focus", as described Initial focus.

When set-pane-focus is called, just before it actually sets the focus, it calls the generic function pane-got-focus with the interface and the pane. You can define your own method (specialized on your own interface class) to perform any processing that may be required.

3.1.6 Mouse cursor

The mouse cursor of a pane can be specified by the initarg :cursor or accessor simple-pane-cursor. The cursor to be used needs to be a result of a call to load-cursor.

It is possible to set an "override" cursor in an interface, which sets the cursors in all its panes. That is typically used to temporarily set the cursor while the interface is in a different input state from the normal state. This feature does not work on Cocoa.