Using Contacts

If you are an application programmer, your basic view of a contact — the generic contact protocol — is quite simple and consists of only a few functions.

make-contact creates a new instance of any contact subclass. This function is a syntactically-identical extension of the basic CLOS make-instance function. Keyword arguments to make-contact provide initial slot values for the new instance, most of which can be defaulted. However, a parent argument must be given; specifying a contact-display as the parent creates a top-level contact.

\framebox[5.5in]{ \hspace*{\fill} {\bf Note} \hspace*{\fill} \parbox[t]{4.5in}{ ... ...so available as the value of the contact's {\tt display} slot.} \hspace*{\fill}}

Usually (and always for top-level contacts), you must also specify the contact's width and height. A non-top-level contact may find that its initial values for x, y, width, height, and border-width have been modified by the geometry management policy of its parent (see Section [*]). 

(setf a-blinker
      (make-contact
        'blinker                  ; Make an instance of the blinker class
        :parent display           ; Required argument
        :width  300               ; Usually required
        :height 400               ; Usually required
        :background 0))           ; Optional, defaults to parent's

The (setf contact-state) function changes the state value of the contact. 

(setf (contact-state a-blinker) :mapped)    ; Make it viewable
(setf (contact-state a-blinker) :withdrawn) ; Make it invisible

change-geometry requests a change to one or more components of the contact's geometry. The keyword arguments to change-geometry — x, y, width, height, and border-width — specify the changed component(s); omitting a keyword means ``Leave the current value unchanged.'' But the actual effect of the request depends on the geometry management policy applied to the contact (See Section [*]). If the request is refused, then the return values give acceptable alternatives for x, y, width, height, and border-width. You may want to give an accept-p keyword value of t, which means ``Go ahead and replace my request with whatever alternative geometry may be returned.'' 

(change-geometry a-blinker
                 :x 100           ; Request new upper-left position...
                 :y 200
                 :accept-p t)     ; ...but accept closest alternative

(change-geometry b :accept-p t)   ; Just validate current values

\framebox[5.5in]{ \hspace*{\fill} {\bf Note} \hspace*{\fill} \parbox[t]{4.5in}{ ... ...hese slots directly. Always use {\tt change-geometry} instead.} \hspace*{\fill}}

The change-priority function requests a change to the contact's stacking priority relative to other windows. The stacking priority determines which window is ``on top'' of other windows. This request is also subject to geometry management policy.

The destroy function is called only when the contact will no longer be referenced. This frees any display resources allocated to the contact.

In addition to the generic protocol, the application programmer interface to a contact includes its callback protocol, plus any special class-dependent functions (typically, for initialization).