Changeset 25768 in project


Ignore:
Timestamp:
01/05/12 14:23:25 (9 years ago)
Author:
juergen
Message:

canvas-draw updated

File:
1 edited

Legend:

Unmodified
Added
Removed
  • wiki/eggref/4/canvas-draw

    r23243 r25768  
    1313See [[http://www.chust.org/fossils/canvas-draw/doc/trunk/api/main.wiki|the official API docs]].
    1414
    15 === License
     15Here is a condensed version to be usable with the online and offline
     16Chicken documentation.
     17
     18==== main Module
     19
     20===== Usage
     21
     22(require-extension canvas-draw)
     23
     24This module re-exports most bindings from the base, play and primitives
     25modules.
     26
     27To create canvasses you also have to import bindings from at least one
     28of the context modules: iup, native, gl, clipboard, printer, picture,
     29server, client, pdf, ps, svg, metafile, debug, cgm, dgn, dxf, emf, wmf.
     30
     31The foreign types and conversion procedures defined in base are not
     32re-exported.
     33
     34==== base Module
     35
     36===== Usage
     37
     38(require-extension canvas-draw-base)
     39
     40Basic CD library support. Initializes the CD library when loaded.
     41
     42===== Data Types
     43
     44<procedure>(canvas? [v any/c]) -> boolean?</procedure>
     45
     46Check whether a value is a CD canvas.
     47
     48<procedure>(context? [v any/c]) -> boolean?</procedure>
     49
     50Check whether a value is a CD driver context.
     51
     52<procedure>(state? [v any/c]) -> boolean?</procedure>
     53
     54Check whether a value is a CD canvas state.
     55
     56===== Canvas Management
     57
     58<procedure>(context-capabilities [context context?]) -> (listof symbol?)</procedure>
     59
     60Returns a list of flags describing the capabilities supported by the
     61given context.
     62
     63The following flags may show up in the list:
     64
     65* 'flush
     66* 'clear
     67* 'play
     68* 'y-axis
     69* 'clip-area
     70* 'clip-polygon
     71* 'region
     72* 'rectangle
     73* 'chord
     74* 'image/rgb
     75* 'image/rgba
     76* 'image/map
     77* 'get-image/rgb
     78* 'image/server
     79* 'background
     80* 'background-opacity
     81* 'write-mode
     82* 'line-style
     83* 'line-width
     84* 'fprimtives
     85* 'hatch
     86* 'stipple
     87* 'pattern
     88* 'font
     89* 'font-dimensions
     90* 'text-size
     91* 'text-orientation
     92* 'palette
     93* 'line-cap
     94* 'line-join
     95* 'path
     96* 'bezier
     97
     98[use-context+ (parameter/c any)]
     99
     100A parameter determining whether calls to make-canvas should use extended
     101variants of the passed context drivers.
     102
     103Defaults to #f.
     104
     105<procedure>(make-canvas [context context?] [data (or/c string? pointer?)]) -> canvas?</procedure>
     106
     107Creates a new canvas with the given driver context. The data is context
     108specific and is either a string describing the setup of the new canvas
     109or a pointer to some native data object.
     110
     111<procedure>(call-with-canvas [canvas canvas?] [proc (-> canvas? any)]) -> any</procedure>
     112<procedure>(call-with-canvas [context context?] [data (or/c string?  pointer?)] [proc (-> canvas? any)]) -> any</procedure>
     113
     114Calls the given procedure with the given canvas and makes sure the
     115canvas is synchronized with external resources around the call.
     116
     117If called in the three argument form, a fresh canvas is created using
     118the given context and is automatically destroyed upon return from the
     119given procedure.
     120
     121<procedure>(canvas-context [canvas canvas?]) -> context?</procedure>
     122
     123Retrieves the context from a given canvas.
     124
     125<procedure>(canvas-simulate! [canvas canvas?] [flags (listof symbol?)]) -> (listof symbol?)</procedure>
     126
     127Sets flags determining which operations should be simulated by the given
     128canvas. Returns the previous set of flags.
     129
     130The following flags may show up in the list:
     131
     132* 'line
     133* 'rectangle
     134* 'box
     135* 'arc
     136* 'sector
     137* 'chord
     138* 'polyline
     139* 'polygon
     140* 'text
     141* 'all
     142* 'lines
     143* 'fills
     144
     145<procedure>(canvas-attribute [canvas canvas?] [name (or/c symbol?  string?)]) -> (or/c string? #f)</procedure>
     146
     147Retrieves the value of a context specific canvas attribute.
     148
     149<procedure>(canvas-attribute-set! [canvas canvas?] [name (or/c symbol?  string?)] [value (or/c string? #f)]) -> void?</procedure>
     150
     151Alternatively
     152(set! (canvas-attribute [canvas canvas?] [name (or/c symbol? string?)]) [value (or/c string? #f)]) -> void?
     153
     154Sets the value of a context specific canvas attribute.
     155
     156<procedure>(canvas-state [canvas canvas?]) -> state?</procedure>
     157
     158Extracts a representation of the current state from a canvas.
     159
     160<procedure>(canvas-state-set! [canvas canvas?] [state state?]) -> void?</procedure>
     161
     162Alternatively
     163(set! (canvas-state [canvas canvas?]) [state state?]) -> void?
     164
     165Restores the given state of a canvas.
     166
     167<procedure>(canvas-clear! [canvas canvas?]) -> void?</procedure>
     168
     169Clears a canvas to the background color.
     170
     171<procedure>(canvas-flush [canvas canvas?]) -> void?</procedure>
     172
     173Flushes all pending drawing operations in a canvas to its backend.
     174
     175===== Coordinate System
     176
     177<procedure>(canvas-size [canvas canvas?]) -> (values integer? integer?  real?  real?)</procedure>
     178
     179Retrieves the width and height of the given canvas in pixels and
     180millimeters.
     181
     182<procedure>(canvas-mm->px [canvas canvas?] [x/mm real?] [y/mm real?]) -> (values integer? integer?)</procedure>
     183
     184Converts a position given in millimeters into a pixel position in the
     185given canvas.
     186
     187<procedure>(canvas-px->mm [canvas canvas?] [x/px integer?] [y/px integer?]) -> (values real? real?)</procedure>
     188
     189Converts a position given in pixels into a physical position in the
     190given canvas.
     191
     192<procedure>(canvas-origin [canvas canvas?]) -> (values integer?  integer?)</procedure>
     193
     194Retrieves the position of the canvas' origin.
     195
     196<procedure>(canvas-origin-set! [canvas canvas?] [x integer?] [y integer?]) -> void?</procedure>
     197
     198Defines the position of the canvas' origin.
     199
     200<procedure>(canvas-transform [canvas canvas?]) -> (or/c (-> real? real?  (values integer? integer?)) #f)</procedure>
     201
     202Retrieves the active coordinate transformation of the given canvas.
     203
     204<procedure>(canvas-transform-set! [canvas canvas?] [proc (or/c (-> real?  real?  (values integer? integer?)) #f)]) -> void?</procedure>
     205
     206Alternatively
     207(set! (canvas-transform [canvas canvas?]) [proc (or/c (-> real? real?  (values integer? integer?)) #f)]) -> void?
     208
     209Defines the active coordinate transformation for the given canvas. The
     210given procedure must represent a linear transformation.
     211
     212<procedure>(canvas-transform-compose! [canvas canvas?] [proc (-> real?  real?  (values integer? integer?))]) -> void?</procedure>
     213
     214Modifies the active coordinate transformation for the given canvas by
     215left-multiplication with the given transformation. The given procedure
     216must represent a linear transformation.
     217
     218<procedure>(canvas-transform-translate! [canvas canvas?] [dx real?] [dy real?]) -> void?</procedure>
     219
     220Modifies the active coordinate transformation for the given canvas
     221applying a translation.
     222
     223<procedure>(canvas-transform-scale! [canvas canvas?] [sx real?] [sy real?]) -> void?</procedure>
     224
     225Modifies the active coordinate transformation for the given canvas
     226applying a scaling.
     227
     228<procedure>(canvas-transform-rotate! [canvas canvas?] [alpha real?]) -> void?  </procedure>
     229Modifies the active coordinate transformation for the given canvas
     230applying a rotation around the origin.
     231
     232===== General Attributes
     233
     234<procedure>(canvas-foreground [canvas canvas?]) -> integer?</procedure>
     235
     236Retrieves the foreground color of the given canvas.
     237
     238<procedure>(canvas-foreground-set! [canvas canvas?] [color integer?]) -> void?</procedure>
     239
     240Alternatively
     241(set! (canvas-foreground [canvas canvas?]) [color integer?]) -> void?
     242
     243Sets the foreground color of the given canvas.
     244
     245<procedure>(canvas-background [canvas canvas?]) -> integer?</procedure>
     246
     247Retrieves the background color of the given canvas.
     248
     249<procedure>(canvas-background-set! [canvas canvas?] [color integer?]) -> void?</procedure>
     250
     251Alternatively
     252(set! (canvas-background [canvas canvas?]) [color integer?]) -> void?
     253
     254Sets the background color of the given canvas.
     255
     256<procedure>(canvas-write-mode [canvas canvas?]) -> symbol?</procedure>
     257
     258Retrieves the write mode of the given canvas.
     259
     260The mode may be one of the following symbols:
     261
     262* 'replace
     263* 'xor
     264* 'not-xor
     265
     266<procedure>(canvas-write-mode-set! [canvas canvas?] [mode symbol?]) -> void?</procedure>
     267
     268Alternatively
     269(set! (canvas-write-mode [canvas canvas?]) [mode symbol?]) -> void?
     270
     271Sets the write mode of the given canvas.
     272
     273===== Clipping
     274
     275<procedure>(canvas-clip-mode [canvas canvas?]) -> (or/c symbol?  #f)</procedure>
     276
     277Retrieves the clipping mode of the given canvas.
     278
     279The mode may be one of the following values:
     280
     281* 'area
     282* 'polygon
     283* 'region
     284* #f
     285
     286In fact, #t is never returned but may be used when setting the clipping
     287mode.
     288
     289<procedure>(canvas-clip-mode-set! [canvas canvas?] [mode (or/c symbol?  #f)]) -> void?</procedure>
     290(set! (canvas-clip-mode [canvas canvas?]) [mode (or/c symbol? #f)])
     291-> void?
     292
     293Sets the clipping mode of the given canvas.
     294
     295<procedure>(canvas-clip-area [canvas canvas?]) -> (values real? real?  real?  real?)</procedure>
     296
     297Retrieves the current rectangular clipping area of the given canvas.
     298
     299<procedure>(canvas-clip-area-set! [canvas canvas?] [x0 double?] [x1 double?] [y0 double?] [y1 double?]) -> void?</procedure>
     300
     301Sets the current rectangular clipping area of the given canvas.
     302
     303The base module only exports checking type conversion functions instead
     304of foreign types since the latter cannot be exported. To define the
     305types canvas, nonnull-canvas, context, nonnull-context, state and
     306nonnull-state in your own module, include the file
     307"canvas-draw-types.scm".
     308
     309<procedure>((canvas->pointer [nonnull? any/c]) [canvas (or/c canvas?  #f)]) -> (or/c pointer? #f)</procedure>
     310
     311Checking conversion from canvasses to pointers.
     312
     313Not re-exported from the main module.
     314
     315<procedure>((pointer->canvas [nonnull? any/c]) [canvas (or/c pointer?  #f)]) -> (or/c canvas? #f)</procedure>
     316
     317Checking conversion from pointers to canvasses.
     318
     319Not re-exported from the main module.
     320
     321<procedure>((context->pointer [nonnull? any/c]) [context (or/c context?  #f)]) -> (or/c pointer? #f)</procedure>
     322
     323Checking conversion from contexts to pointers.
     324
     325Not re-exported from the main module.
     326
     327<procedure>((pointer->context [nonnull? any/c]) [context (or/c pointer?  #f)]) -> (or/c context? #f)</procedure>
     328
     329Checking conversion from pointers to contexts.
     330
     331Not re-exported from the main module.
     332
     333<procedure>((state->pointer [nonnull? any/c]) [state (or/c state? #f)]) -> (or/c pointer? #f)</procedure>
     334
     335Checking conversion from states to pointers.
     336
     337Not re-exported from the main module.
     338
     339<procedure>((pointer->state [nonnull? any/c]) [state (or/c pointer?  #f)]) -> (or/c state? #f)</procedure>
     340
     341Checking conversion from pointers to states.
     342
     343Not re-exported from the main module.
     344
     345==== play Module
     346
     347===== Usage
     348
     349(require-extension canvas-draw-play)
     350
     351Replay functionality.
     352
     353===== Context Content Replay
     354
     355<procedure>(canvas-play! [canvas canvas?] [context context?] [x0 integer?] [x1 integer?] [y0 integer?] [y1 integer?] [data (or/c string? pointer?)])</procedure>
     356-> void?
     357
     358Replays the drawing contained in the context withe the given data in the
     359given canvas.
     360
     361==== primitives Module
     362
     363===== Usage
     364
     365(require-extension canvas-draw-primitives)
     366
     367Drawing primitives.
     368
     369===== Points
     370
     371<procedure>(canvas-pixel! [canvas canvas?] [x integer?] [y integer?] [color integer? (canvas-foreground canvas)]) -> void?</procedure>
     372
     373Draws a single pixel of the given color on the given canvas.
     374
     375<procedure>(canvas-mark! [canvas canvas?] [x integer?] [y integer?]) -> void?</procedure>
     376
     377Draws a marker symbol on the given canvas.
     378
     379<procedure>(canvas-mark-type [canvas canvas?]) -> symbol?</procedure>
     380
     381Retrieves the current marker symbol type for the given canvas. Possible
     382values are
     383
     384* '+ or 'plus
     385* '* or 'star
     386* '0 or 'circle
     387* 'O or 'hollow-circle
     388* 'X or 'x
     389* 'box
     390* 'hollow-box
     391* 'diamond
     392* 'hollow-diamond
     393
     394<procedure>(canvas-mark-type-set! [canvas canvas?] [mark-type symbol?]) -> void?</procedure>
     395
     396Alternatively
     397(set! (canvas-mark-type [canvas canvas?]) [mark-type symbol?]) -> void?
     398
     399Sets the current marker symbol type for the given canvas.
     400
     401<procedure>(canvas-mark-size [canvas canvas?]) -> integer?</procedure>
     402
     403Retrieves the current marker symbol size for the given canvas.
     404
     405<procedure>(canvas-mark-size-set! [canvas canvas?] [size integer?]) -> void?</procedure>
     406
     407Alternatively
     408(set! (canvas-mark-size [canvas canvas?]) [size integer?]) -> void?
     409
     410Sets the current marker symbol size for the given canvas.
     411
     412===== Lines
     413
     414<procedure>(canvas-line! [canvas canvas?] [x0 real?] [y0 real?] [x1 real?] [y1 real?]) -> void?</procedure>
     415
     416Draws a line on the given canvas.
     417
     418<procedure>(canvas-rectangle! [canvas canvas?] [x0 real?] [x1 real?] [y0 real?] [y1 real?]) -> void?</procedure>
     419
     420Draws a hollow rectangle on the given canvas.
     421
     422<procedure>(canvas-arc! [canvas canvas?] [x real?] [y real?] [width real?] [height real?] [alpha0 real?] [alpha1 real?]) -> void?</procedure>
     423
     424Draws a hollow ellipsis segment on the given canvas.
     425
     426<procedure>(canvas-line-style [canvas canvas?]) -> symbol?</procedure>
     427
     428Retrieves the current line style of the given canvas. Possible values
     429are
     430
     431* 'continuous
     432* 'dashed
     433* 'dotted
     434* 'dash-dotted
     435* 'dash-dot-dotted
     436* 'custom
     437
     438<procedure>(canvas-line-style-set! [canvas canvas?] [line-style (or/c symbol?  list?)]) -> symbol?</procedure>
     439
     440Alternatively
     441(set! (canvas-line-style [canvas canvas?]) [line-style (or/c symbol?  list?)]) -> symbol?
     442
     443Sets the current line style of the given canvas and returns the previous
     444value.
     445
     446In addition to the possible return values of canvas-line-style a custom
     447line-style can be fully specified using the form (list 'custom [len
     448integer?] ...).
     449
     450<procedure>(canvas-line-width [canvas canvas?]) -> integer?</procedure>
     451
     452Retrieves the current line width of the given canvas.
     453
     454<procedure>(canvas-line-width-set! [canvas canvas?] [line-width integer?]) -> integer?</procedure>
     455
     456Alternatively
     457(set! (canvas-line-width [canvas canvas?]) [line-width integer?]) -> integer?
     458
     459Sets the current line width of the given canvas and returns the previous
     460value.
     461
     462<procedure>(canvas-line-join [canvas canvas?]) -> symbol?</procedure>
     463
     464Retrieves the current line join style of the given canvas. Possible
     465values are
     466
     467* 'miter
     468* 'bevel
     469* 'round
     470
     471<procedure>(canvas-line-join-set! [canvas canvas?] [line-join symbol?]) -> symbol?</procedure>
     472
     473Alternatively
     474(set! (canvas-line-join [canvas canvas?]) [line-join symbol?]) -> symbol?
     475
     476Sets the current line join style of the given canvas and returns the
     477previous value.
     478
     479<procedure>(canvas-line-cap [canvas canvas?]) -> symbol?</procedure>
     480
     481Retrieves the current line cap style of the given canvas.
     482
     483* 'flat
     484* 'square
     485* 'round
     486
     487<procedure>(canvas-line-cap-set! [canvas canvas?] [line-cap symbol?]) -> symbol?</procedure>
     488
     489Alternatively
     490(set! (canvas-line-cap [canvas canvas?]) [line-cap symbol?]) -> symbol?
     491
     492Sets the current line cap style of the given canvas and returns the
     493previous value.
     494
     495===== Filled Areas
     496
     497<procedure>(canvas-box! [canvas canvas?] [x0 real?] [x1 real?] [y0 real?] [y1 real?]) -> void?</procedure>
     498
     499Draws a filled rectangle on the given canvas.
     500
     501<procedure>(canvas-sector! [canvas canvas?] [x real?] [y real?] [width real?] [height real?] [alpha0 real?] [alpha1 real?]) -> void?</procedure>
     502
     503Draws a filled ellipsis sector on the given canvas.
     504
     505<procedure>(canvas-chord! [canvas canvas?] [x real?] [y real?] [width real?] [height real?] [alpha0 real?] [alpha1 real?]) -> void?</procedure>
     506
     507Draws a filled ellipsis arc on the given canvas.
     508
     509<procedure>(canvas-background-opacity [canvas canvas?]) -> symbol?</procedure>
     510
     511Retrieves the current background opacity of the given canvas. Possible
     512values are
     513
     514* 'transparent
     515* 'opaque
     516
     517<procedure>(canvas-background-opacity-set! [canvas canvas?] [background-opacity symbol?]) -> symbol?</procedure>
     518(set! (canvas-background-opacity-set! [canvas canvas?])
     519[background-opacity symbol?]) -> symbol?
     520
     521Sets the current background opacity of the given canvas and returns the
     522previous value.
     523
     524<procedure>(canvas-fill-mode [canvas canvas?]) -> symbol?</procedure>
     525
     526Retrieves the current polygon fill mode of the given canvas. Possible
     527values are
     528
     529* 'even-odd
     530* 'winding
     531
     532<procedure>(canvas-fill-mode-set! [canvas canvas?] [fill-mode symbol?]) -> symbol?</procedure>
     533
     534Alternatively
     535(set! (canvas-fill-mode [canvas canvas?]) [fill-mode symbol?]) -> symbol?
     536
     537Sets the current polygon fill mode of the given canvas and returns the
     538previous value.
     539
     540<procedure>(canvas-interior-style [canvas canvas?]) -> (or/c symbol?  list?)</procedure>
     541
     542Retrieves the current interior style of the given canvas. Possible
     543values are
     544
     545* 'solid
     546* '(hatch horizontal)
     547* '(hatch vertical)
     548* '(hatch forward-diagonal)
     549* '(hatch backward-diagonal)
     550* '(hatch cross)
     551* '(hatch diagonal-cross)
     552* (list 'stipple [width integer?] [height integer?] [data blob?])
     553* (list 'pattern/rgb [width integer?] [height integer?] [data blob?])
     554* (list 'pattern/rgba [width integer?] [height integer?] [data blob?])
     555* #f
     556
     557<procedure>(canvas-interior-style-set! [canvas canvas?] [interior-style (or/c symbol? list?)]) -> void?</procedure>
     558
     559Alternatively
     560(set! (canvas-interior-style [canvas canvas?]) [interior-style (or/c symbol? list?)]) -> void?
     561
     562Sets the current interior style of the given canvas and returns the
     563previous value.
     564
     565===== Text
     566
     567<procedure>(canvas-text! [canvas canvas?] [x real?] [y real?] [text string?]) -> void?</procedure>
     568
     569Draws a string of text on the given canvas.
     570
     571<procedure>(canvas-font [canvas canvas?]) -> string?</procedure>
     572
     573Retrieves the current font of the given canvas.
     574
     575<procedure>(canvas-font-set! [canvas canvas?] [font string?]) -> void?</procedure>
     576
     577Alternatively
     578(set! (canvas-font [canvas canvas?]) [font string?]) -> void?
     579
     580Sets the current font of the given canvas and returns the previous
     581value.
     582
     583<procedure>(canvas-text-alignment [canvas canvas?]) -> symbol?</procedure>
     584
     585Retrieves the current text alignment of the given canvas. Possible
     586values are
     587
     588* 'north
     589* 'south
     590* 'east
     591* 'west
     592* 'north-east
     593* 'north-west
     594* 'south-east
     595* 'south-west
     596* 'center
     597* 'base-left
     598* 'base-center
     599* 'base-right
     600
     601<procedure>(canvas-text-alignment-set! [canvas canvas?] [text-alignment symbol?]) -> void?</procedure>
     602
     603Alternatively
     604(set! (canvas-text-alignment [canvas canvas?]) [text-alignment symbol?]) -> void?
     605
     606Sets the current text alignment of the given canvas and returns the
     607previous value.
     608
     609(canvas-text-orientation [canvas canvas?]) -> real?
     610
     611Retrieves the current text orientation of the given canvas.
     612
     613<procedure>(canvas-text-orientation-set! [canvas canvas?] [orientation real?]) -> void?</procedure>
     614
     615Alternatively
     616(set! (canvas-text-orientation [canvas canvas?]) [orientation real?]) -> void?
     617
     618Sets the current text orientation of the given canvas and returns the
     619previous value.
     620
     621<procedure>(canvas-font-dimensions [canvas canvas?]) -> (values integer?  integer? integer? integer?)</procedure>
     622
     623Returns the maximum width, height, ascent and descent of the current
     624font of the given canvas.
     625
     626<procedure>(canvas-text-size [canvas canvas?] [text string?]) -> (values integer? integer?)</procedure>
     627
     628Computes the width and height of the given text when drawn on the given
     629canvas.
     630
     631<procedure>(canvas-text-box [canvas canvas?] [x integer?] [y integer?] [text string?]) -> (values integer? integer? integer?  integer?)</procedure>
     632
     633Computes the bounding box of the given text when drawn on the given
     634canvas. Returns the minimum and maximum x and y coordinates.
     635
     636===== Vertices
     637
     638<procedure>(call-with-canvas-in-mode [canvas canvas?] [mode symbol?] [proc (-> canvas? any)]) -> any</procedure>
     639
     640Calls proc with the given canvas and ready to receive vertex data in the
     641given mode. Returns whatever proc returns.
     642
     643Possible modes are
     644
     645* 'open-lines
     646* 'closed-lines
     647* 'fill
     648* 'clip
     649* 'bezier
     650* 'region
     651* 'path
     652
     653<procedure>(canvas-path-set! [canvas canvas?] [path-action symbol?]) -> void?</procedure>
     654
     655Configures the action between sequences of vertex data sent to the given
     656canvas. Possible actions are
     657
     658* 'new
     659* 'move-to
     660* 'line-to
     661* 'arc
     662* 'curve-to
     663* 'close
     664* 'fill
     665* 'stroke
     666* 'fill+stroke
     667* 'clip
     668
     669<procedure>(canvas-vertex! [canvas canvas?] [x real?] [y real?]) -> void?</procedure>
     670
     671Sends a vertex to the given canvas.
     672
     673===  License
    16674
    17675[[http://www.chust.org/fossils/canvas-draw/doc/trunk/LICENSE.txt|BSD license]]
Note: See TracChangeset for help on using the changeset viewer.