8.3 Output Protocol

  • 8.3.1 Output Properties
  • 8.3.2 Output Protocol Functions
  • 8.3.3 Output Protocol Classes
  • 8.3.4 Associating a Medium with a Sheet
  • The output protocol is concerned with the appearance of displayed output on the window associated with a sheet. The sheet output protocol is responsible for providing a means of doing output to a sheet, and for delivering repaint requests to the sheet's client. [annotate]

    Sheets either participate fully in the output protocol or are mute for output. If any functions in the output protocol are called on a sheet that is mute for output, the sheet-is-mute-for-output error will be signalled. [annotate]

    8.3.1 Output Properties

    Each sheet retains some output state that logically describes how output is to be rendered on its window. Such information as the foreground and background ink, line thickness, and transformation to be used during drawing are provided by this state. This state may be stored in a medium associated with the sheet itself, be derived from a parent, or may have some global default, depending on the sheet itself. [annotate]

    [medium, Concept← A Glossary]
    [medium, Concept← A Glossary]
    [medium, Concept← A Glossary]
    [medium, Concept← 15.6 Buffering of Output, with-output-buffered]
    [medium, Concept← 15.6 Buffering of Output, (setf medium-buffering-output-p)]
    [medium, Concept← 15.6 Buffering of Output, medium-buffering-output-p]
    [medium, Concept← 14.5 Arbitrary Designs, draw-pattern*]
    [medium, Concept← 14.5 Arbitrary Designs, draw-design]
    [medium, Concept← 12.7.2 Medium-specific Drawing Functions, medium-draw-text*]
    [medium, Concept← 12.7.2 Medium-specific Drawing Functions, medium-draw-ellipse*]
    [medium, Concept← 12.7.2 Medium-specific Drawing Functions, medium-draw-rectangles*]
    [medium, Concept← 12.7.2 Medium-specific Drawing Functions, medium-draw-rectangle*]
    [medium, Concept← 12.7.2 Medium-specific Drawing Functions, medium-draw-polygon*]
    [medium, Concept← 12.7.2 Medium-specific Drawing Functions, medium-draw-lines*]
    [medium, Concept← 12.7.2 Medium-specific Drawing Functions, medium-draw-line*]
    [medium, Concept← 12.7.2 Medium-specific Drawing Functions, medium-draw-points*]
    [medium, Concept← 12.7.2 Medium-specific Drawing Functions, medium-draw-point*]
    [medium, Concept← 12.5.2 Compound Drawing Functions, draw-oval]
    [medium, Concept← 12.5.2 Compound Drawing Functions, draw-arrow]
    [medium, Concept← 12.5.1 Basic Drawing Functions, draw-text]
    [medium, Concept← 12.5.1 Basic Drawing Functions, draw-circle]
    [medium, Concept← 12.5.1 Basic Drawing Functions, draw-ellipse]
    [medium, Concept← 12.5.1 Basic Drawing Functions, draw-rectangle*]
    [medium, Concept← 12.5.1 Basic Drawing Functions, draw-polygon]
    [medium, Concept← 12.5.1 Basic Drawing Functions, draw-line]
    [medium, Concept← 12.5.1 Basic Drawing Functions, draw-points]
    [medium, Concept← 12.5.1 Basic Drawing Functions, draw-point]
    [medium, Concept← 11.2 Text Style Binding Forms, with-text-family]
    [medium, Concept← 11.2 Text Style Binding Forms, invoke-with-text-style]
    [medium, Concept← 11.2 Text Style Binding Forms, with-text-style]
    [medium, Concept← 11.1.1 Text Style Protocol and Text Style Suboptions, text-size]
    [medium, Concept← 11.1.1 Text Style Protocol and Text Style Suboptions, text-style-fixed-width-p]
    [medium, Concept← 11.1.1 Text Style Protocol and Text Style Suboptions, text-style-ascent]
    [medium, Concept← 10.2.2 Establishing Local Coordinate Systems, with-first-quadrant-coordinates]
    [medium, Concept← 10.2.2 Establishing Local Coordinate Systems, with-local-coordinates]
    [medium, Concept← 10.2.1 Transformation "Convenience" Forms, with-identity-transformation]
    [medium, Concept← 10.2.1 Transformation "Convenience" Forms, with-rotation]
    [medium, Concept← 10.2.1 Transformation "Convenience" Forms, with-scaling]
    [medium, Concept← 10.2.1 Transformation "Convenience" Forms, with-translation]
    [medium, Concept← 10.2 Drawing Option Binding Forms, invoke-with-drawing-options]
    [medium, Concept← 10.2 Drawing Option Binding Forms, with-drawing-options]
    [medium, Concept← 10.1 Medium Components, medium-current-text-style]
    [medium, Concept← 10.1 Medium Components, (setf medium-text-style)]
    [medium, Concept← 10.1 Medium Components, medium-text-style]
    [medium, Concept← 10.1 Medium Components, (setf medium-default-text-style)]
    [medium, Concept← 10.1 Medium Components, medium-default-text-style]
    [medium, Concept← 10.1 Medium Components, (setf medium-line-style)]
    [medium, Concept← 10.1 Medium Components, medium-line-style]
    [medium, Concept← 10.1 Medium Components, (setf medium-clipping-region)]
    [medium, Concept← 10.1 Medium Components, medium-clipping-region]
    [medium, Concept← 10.1 Medium Components, (setf medium-transformation)]
    [medium, Concept← 10.1 Medium Components, medium-transformation]
    [medium, Concept← 10.1 Medium Components, (setf medium-ink)]
    [medium, Concept← 10.1 Medium Components, medium-ink]
    [medium, Concept← 10.1 Medium Components, (setf medium-foreground)]
    [medium, Concept← 10.1 Medium Components, medium-foreground]
    [medium, Concept← 8.3.4.1 Grafting and Degrafting of Mediums, degraft-medium]
    [medium, Concept← 8.3.4.1 Grafting and Degrafting of Mediums, engraft-medium]
    [medium, Concept← 8.3.4.1 Grafting and Degrafting of Mediums, deallocate-medium]
    [medium, Concept← 8.3.4 Associating a Medium with a Sheet, medium-drawable]
    [medium, Concept← 8.3.4 Associating a Medium with a Sheet, medium-sheet]
    [medium, Concept← 8.3.1 Output Properties, medium-merged-text-style]
    [medium, Concept← 8.3.1 Output Properties, medium-default-text-style]
    [medium, Concept← 8.3.1 Output Properties, medium-text-style]
    [medium, Concept← 8.3.1 Output Properties, medium-line-style]
    [medium, Concept← 8.3.1 Output Properties, medium-clipping-region]
    [medium, Concept← 8.3.1 Output Properties, medium-transformation]
    [medium, Concept← 8.3.1 Output Properties, medium-ink]
    [medium, Concept← 8.3.1 Output Properties, medium-background]
    [medium, Concept← 8.3.1 Output Properties, medium-foreground]
    [medium, Concept← 8.3.1 Output Properties, mediump]

    If a sheet is mute for output, it is an error to set any of these values. [annotate]

    medium   [Protocol Class]
              

    The protocol class that corresponds to the output state for some kind of sheet. There is no single advertised standard medium class. If you want to create a new class that behaves like a medium, it should be a subclass of medium. All instantiable subclasses of medium must obey the medium protocol. [annotate]

    [annotate]

    mediump  object [Protocol Predicate]
              

    Returns true if object is a medium, otherwise returns false. [annotate]

    [annotate]

    basic-medium   [Class]
              

    The basic class on which all CLIM mediums are built, a subclass of medium. This class is an abstract class, intended only to be subclassed, not instantiated. [annotate]

    The following generic functions comprise the basic medium protocol. All mediums must implement methods for these generic functions. Often, a sheet class that supports the output protocol will implement a "trampoline" method that passes the operation on to sheet-medium of the sheet. [annotate]

    [annotate]

    medium-foreground  medium [Generic Function]
    (setf medium-foreground)  design medium [Generic Function]
    medium-background  medium [Generic Function]
    (setf medium-background)  design medium [Generic Function]
    medium-ink  medium [Generic Function]
    (setf medium-ink)  design medium [Generic Function]
              

    Returns (and, with setf, sets) the current drawing ink for the medium medium. This is described in detail in Chapter 10. [annotate]

    [annotate]

    medium-transformation  medium [Generic Function]
    (setf medium-transformation)  transformation medium [Generic Function]
              

    Returns (and, with setf, sets) the "user" transformation that converts the coordinates presented to the drawing functions by the programmer to the medium medium's coordinate system. By default, it is the identity transformation. This is described in detail in Chapter 10. [annotate]

    [annotate]

    medium-clipping-region  medium [Generic Function]
    (setf medium-clipping-region)  region medium [Generic Function]
              

    Returns (and, with setf, sets) the clipping region that encloses all output performed on the medium medium. It is returned and set in user coordinates. That is, to convert the user clipping region to medium coordinates, it must be transformed by the value of medium-transformation. For example, the values returned by [annotate]

    (let (cr1 cr2)
      ;; Ensure that the sheet's clipping region and transformation will be reset:
      (with-drawing-options (sheet :transformation +identity-transformation+
                                   :clipping-region +everywhere+)
        (setf (medium-clipping-region sheet) (make-rectangle* 0 0 10 10))
        (setf (medium-transformation sheet) (clim:make-scaling-transformation 2 2))
        (setf cr1 (medium-clipping-region sheet))
        (setf (medium-clipping-region sheet) (make-rectangle* 0 0 10 10))
        (setf (medium-transformation sheet) +identity-transformation+)
        (setf cr2 (medium-clipping-region sheet))
        (values cr1 cr2)))
    

    are two rectangles. The first one has edges of (0,0,5,5), while the second one has edges of (0,0,20,20). [annotate]

    By default, the user clipping region is the value of +everywhere+. [annotate]

    Major issue: What exactly are "user coordinates"? We need to define all of the coordinate systems in one place: device, window, stream, etc. --- SWM [annotate]

    [annotate]

    medium-line-style  medium [Generic Function]
    (setf medium-line-style)  line-style medium [Generic Function]
              

    Returns (and, with setf, sets) the current line style for the medium medium. This is described in detail in Chapter 10 and Section 10.3. [annotate]

    [annotate]

    medium-text-style  medium [Generic Function]
    (setf medium-text-style)  text-style medium [Generic Function]
              

    Returns (and, with setf, sets) the current text style for the medium medium of any textual output that may be displayed on the window. This is described in detail in Chapter 10. [annotate]

    [annotate]

    medium-default-text-style  medium [Generic Function]
    (setf medium-default-text-style)  text-style medium [Generic Function]
              

    Returns (and, with setf, sets) the default text style for output on the medium medium. This is described in detail in Chapter 10. [annotate]

    [annotate]

    medium-merged-text-style  medium [Generic Function]
              

    Returns the actual text style used in rendering text on the medium medium. It returns the result of [annotate]

     
    (merge-text-styles (medium-text-style medium)
                       (medium-default-text-style medium))
    

    Thus, those components of the current text style that are not nil will replace the defaults from medium's default text style. Unlike the preceding text style function, medium-merged-text-style is read-only. [annotate]

    [annotate]

    Note: How is that different from medium-current-text-style? [edit]-- Gilbert Baumann 2005-03-06 16:19Z
     

    8.3.2 Output Protocol Functions

    The output protocol functions on mediums (and sheets that support the standard output protocol) include those functions described in Section 12.7. [annotate]

    Minor issue: We need to do a little better than this. --- SWM [annotate]

    8.3.3 Output Protocol Classes

    The following classes implement the standard output protocols. None of the five following classes is instantiable. [annotate]

    standard-sheet-output-mixin   [Class]
              

    This class is mixed in to any sheet that provides the standard output protocol, such as repainting and graphics. [annotate]

    [annotate]

    sheet-mute-output-mixin   [Class]
              

    This class is mixed in to any sheet that provides none of the output protocol. [annotate]

    [annotate]

    permanent-medium-sheet-output-mixin   [Class]
              

    This class is mixed in to any sheet that always has a medium associated with it. It is a subclass of sheet-with-medium-mixin. [annotate]

    [annotate]

    temporary-medium-sheet-output-mixin   [Class]
              

    This class is mixed in to any sheet that may have a medium associated with it, but does not necessarily have a medium at any given instant. It is a subclass of sheet-with-medium-mixin. [annotate]

    [annotate]

    8.3.4 Associating a Medium with a Sheet

    Before a sheet may be used for output, it must be associated with a medium. Some sheets are permanently associated with media for output efficiency; for example, CLIM window stream sheets have a medium that is permanently allocated to the window. [annotate]

    However, many kinds of sheets only perform output infrequently, and therefore do not need to be associated with a medium except when output is actually required. Sheets without a permanently associated medium can be much more lightweight than they otherwise would be. For example, in a program that creates a sheet for the purpose of displaying a border for another sheet, the border sheet receives output only when the window's shape is changed. [annotate]

    To associate a sheet with a medium, the macro with-sheet-medium is used. Only sheets that are subclasses of sheet-with-medium-mixin may have a medium associated with them. [annotate]

    with-sheet-medium  (medium sheet) &body body [Macro]
              

    Within the body, the variable medium is bound to the sheet's medium. If the sheet does not have a medium permanently allocated, one will be allocated and associated with the sheet for the duration of the body (by calling engraft-medium), and then degrafted from the sheet and deallocated when the body has been exited. The values of the last form of the body are returned as the values of with-sheet-medium. [annotate]

    This macro will signal a runtime error if sheet is not a subclass of sheet-with-medium-mixin. [annotate]

    The medium argument is not evaluated, and must be a symbol that is bound to a medium. body may have zero or more declarations as its first forms. [annotate]

    [annotate]

    with-sheet-medium-bound  (sheet medium) &body body [Macro]
              

    with-sheet-medium-bound is used to associate the specific medium medium with the sheet sheet for the duration of the body body. Typically, a single medium will be allocated an passed to several different sheets that can use the same medium. [annotate]

    If the sheet already has a medium allocated to it, the new medium will not be grafted to the sheet, and with-sheet-medium-bound will simple evaluate the body. If the value of medium is nil, with-sheet-medium-bound is exactly equivalent to with-sheet-medium. The values of the last form of the body are returned as the values of with-sheet-medium-bound. [annotate]

    Note: The requirement of equivalence to WITH-SHEET-MEDIUM could possibly imply that MEDIUM must be a symbol. However, there is no requirement that MEDIUM be bound to the medium associated with SHEET over course of executing BODY. This suggests that MEDIUM need not be a symbol, and that a user who needs to know which MEDIUM is actually being used has to use WITH-SHEET-MEDIUM or SHEET-MEDIUM. And if SHEET already has a medium, should MEDIUM still be evaluated? [edit]-- Alastair Bridgewater 2015-06-27 04:46Z
     

    This macro will signal a runtime error if sheet is not a subclass of sheet-with-medium-mixin. [annotate]

    body may have zero or more declarations as its first forms. [annotate]

    [annotate]

    sheet-medium  sheet [Generic Function]
              

    Returns the medium associated with the sheet sheet. If sheet does not have a medium allocated to it, sheet-medium returns nil. [annotate]

    This function will signal an error if sheet is not a subclass of sheet-with-medium-mixin. [annotate]

    [annotate]

    medium-sheet  medium [Generic Function]
              

    Returns the sheet associated with the medium medium. If medium is not grafted to a sheet, medium-sheet returns nil. [annotate]

    [annotate]

    medium-drawable  medium [Generic Function]
              

    Returns an implementation-dependent object that corresponds to the actual host window that will be drawn on when the medium medium is drawn on. If medium is not grafted to a sheet or the medium's sheet is not currently mirrored on a display server, medium-drawable returns nil. [annotate]

    Note: It would be nice if it was left unspecified - so we could set a drawable without engrafting the medium to a sheet (i.e to a pixmap!) [edit]-- DK 2021-01-08 11:24Z
     

    Programmers can use this function to get a host window system object that can be manipulated using the functions of the host window system. This might be done in order to explicitly trade of performance against portability. [annotate]

    [annotate]

    port  (medium basic-medium) [Method]
              

    If medium is both grafted to a sheet and the sheet is currently mirrored on a display server, this returns the port with which medium is associated. Otherwise it returns nil. [annotate]

    [annotate]

    8.3.4.1 Grafting and Degrafting of Mediums

    The following generic functions are the protocol-level functions responsible for the allocating, deallocating, grafting, and degrafting of mediums. They are not intended for general use by programmers. [annotate]

    allocate-medium  port sheet [Generic Function]
              

    Allocates a medium from the port port's medium resource, or calls make-medium on the port to create a new medium if the resource is empty or the port does not maintain a resource of mediums. The resulting medium will have its default characteristics determined by sheet. [annotate]

    [annotate]

    deallocate-medium  port medium [Generic Function]
              

    Returns the medium medium to port's medium resource. [annotate]

    [annotate]

    make-medium  port sheet [Generic Function]
              

    Creates a new medium for the port port. The new medium will have its default characteristics determined by sheet. [annotate]

    [annotate]

    engraft-medium  medium port sheet [Generic Function]
              

    Grafts the medium medium to the sheet sheet on the port port. [annotate]

    The default method on basic-medium will set medium-sheet on medium to point to the sheet, and will set up the medium state (foreground ink, background ink, and so forth) from the defaults gotten from sheet. Each implementation may specialize this generic function in order to set up such things as per-medium ink caches, and so forth. [annotate]

    [annotate]

    degraft-medium  medium port sheet [Generic Function]
              

    Degrafts the medium medium from the sheet sheet on the port port. [annotate]

    The default method on basic-medium will set medium-sheet back to nil. Each implementation may specialize this generic function in order to clear any caches it has set up, and so forth. [annotate]

    [annotate]