15.3.645  src/lib/x-kit/widget/leaf/canvas.api

## canvas.api
#
#     "The canvas widget provides a drawing surface that
#      can also be used as a basis for building new widgets."
#        -- p24, Gansner+Reppy's 1993 eXene widget manual,
#           http:://mythryl.org/pub/exene/1993-widgets.ps 
#
# Use 'drawable_of' to get the actual X "drawable"
# associated with the canvas.  For the set of types and
# functions available for drawing on a drawable see:
#
#     src/lib/x-kit/xclient/xclient.api
#
# Note that the X-server side canvas does not actually
# exist until the canvas is realized;  attempting
# to draw on it prior to that will block the thread.
#
# 

# Compiled by:
#     src/lib/x-kit/widget/xkit-widget.sublib

# This api is implemented in:
#
#     src/lib/x-kit/widget/leaf/canvas.pkg

stipulate
    package xc =  xclient;              # xclient               is from   src/lib/x-kit/xclient/xclient.pkg
    #
    package xg =  xgeometry;            # xgeometry             is from   src/lib/std/2d/xgeometry.pkg
    #
    package wg =  widget;               # widget                is from   src/lib/x-kit/widget/basic/widget.pkg
herein

    api Canvas {

        Canvas;

        canvas
            :
            (wg::Root_Window, wg::View, List(wg::Arg))
            ->
            wg::Widget_Size_Preference
            ->
            (Canvas, xg::Size, xc::Kidplug);

        make_canvas
            :
            wg::Root_Window
            ->
            wg::Widget_Size_Preference
            ->
            ( Canvas,                                   # Canvas on which to draw.
              xg::Size,                                 # Current size of canvas.
              xc::Kidplug
            );

        as_widget:    Canvas -> wg::Widget;

        size_of:      Canvas -> xg::Size;
            # 
            # Return current size of canvas.  Since changes
            # in canvas size are reported to the widget via
            # X resize events, this call is rarely needed.

        drawable_of:  Canvas -> xc::Drawable;
            #
            # The actual x-kit drawing commands all take
            # a drawable as parameter, not a canvas.


        # Modify the attributes of the canvas 
        #
        set_background_color:  Canvas -> Null_Or( xc::Rgb ) -> Void;
            #
            # Set the background color attribute of the window.
            #   
            # This does not immediately affect the window's contents,
            # but if it is done before the window is mapped the window
            # will come up with the right color.


        set_cursor:  Canvas -> Null_Or( xc::Xcursor ) -> Void;

    };
end;

## COPYRIGHT (c) 1991 by AT&T Bell Laboratories  See SMLNJ-COPYRIGHT file for details.
## Subsequent changes by Jeff Prothero Copyright (c) 2010-2013,
## released per terms of SMLNJ-COPYRIGHT.