1wxDC(3)                    Erlang Module Definition                    wxDC(3)
2
3
4

NAME

6       wxDC - Functions for wxDC class
7

DESCRIPTION

9       A wxDC is a "device context" onto which graphics and text can be drawn.
10       It is intended to represent different output devices and offers a  com‐
11       mon abstract API for drawing on any of them.
12
13       wxWidgets offers an alternative drawing API based on the modern drawing
14       backends GDI+, CoreGraphics, Cairo and Direct2D. See wxGraphicsContext,
15       wxGraphicsRenderer  and related classes. There is also a wxGCDC linking
16       the APIs by offering the wxDC API on top of a wxGraphicsContext.
17
18       wxDC is an abstract base class and cannot be created directly. Use  wx‐
19       PaintDC,  wxClientDC, wxWindowDC, wxScreenDC, wxMemoryDC or wxPrinterDC
20       (not implemented in wx). Notice that device contexts which are  associ‐
21       ated  with  windows (i.e. wxClientDC, wxWindowDC and wxPaintDC) use the
22       window font and colours by default (starting with wxWidgets 2.9.0)  but
23       the  other  device context classes use system-default values so you al‐
24       ways must set the appropriate fonts and colours before using them.
25
26       In addition to the versions of the methods documented below, there  are
27       also  versions  which  accept single {X,Y} parameter instead of the two
28       wxCoord ones or {X,Y} and {Width,Height} instead of  the  four  wxCoord
29       parameters.
30
31       Beginning  with  wxWidgets  2.9.0 the entire wxDC code has been reorga‐
32       nized. All platform dependent code (actually all drawing code) has been
33       moved  into  backend classes which derive from a common wxDCImpl class.
34       The user-visible classes such as wxClientDC and wxPaintDC  merely  for‐
35       ward all calls to the backend implementation.
36
37       Device and logical units
38
39       In  the  wxDC  context there is a distinction between logical units and
40       device units.
41
42       Device units are the units native to the particular device; e.g. for  a
43       screen, a device unit is a pixel. For a printer, the device unit is de‐
44       fined by the resolution of the printer (usually given in DPI:  dot-per-
45       inch).
46
47       All  wxDC  functions use instead logical units, unless where explicitly
48       stated. Logical units are arbitrary units mapped to device units  using
49       the current mapping mode (see setMapMode/2).
50
51       This mechanism allows reusing the same code which prints on e.g. a win‐
52       dow on the screen to print on e.g. a paper.
53
54       Support for Transparency / Alpha Channel
55
56       In general wxDC methods don't support alpha transparency and the  alpha
57       component  of wx_color() is simply ignored and you need to use wxGraph‐
58       icsContext for full transparency support. There are, however, a few ex‐
59       ceptions:  first, under macOS and GTK+ 3 colours with alpha channel are
60       supported in all the normal wxDC-derived classes as they use wxGraphic‐
61       sContext  internally.  Second, under all platforms wxSVGFileDC (not im‐
62       plemented in wx) also fully supports alpha channel. In  both  of  these
63       cases  the instances of wxPen or wxBrush that are built from wx_color()
64       use the colour's alpha values when stroking or filling.
65
66       Support for Transformation Matrix
67
68       On some platforms (currently under MSW, GTK+ 3, macOS) wxDC has support
69       for  applying  an arbitrary affine transformation matrix to its coordi‐
70       nate system (since 3.1.1 this feature is also supported  by  wxGCDC  in
71       all  ports).  Call  CanUseTransformMatrix()  (not implemented in wx) to
72       check if this support is available and then  call  SetTransformMatrix()
73       (not  implemented  in wx) if it is. If the transformation matrix is not
74       supported, SetTransformMatrix() (not implemented in wx)  always  simply
75       returns false and doesn't do anything.
76
77       This feature is only available when wxUSE_DC_TRANSFORM_MATRIX build op‐
78       tion is enabled.
79
80       See: Overview dc, wxGraphicsContext, wxDCFontChanger  (not  implemented
81       in  wx),  wxDCTextColourChanger (not implemented in wx), wxDCPenChanger
82       (not implemented in wx), wxDCBrushChanger (not implemented in wx), wxD‐
83       CClipper (not implemented in wx)
84
85       wxWidgets docs: wxDC
86

DATA TYPES

88       wxDC() = wx:wx_object()
89

EXPORTS

91       blit(This, Dest, Size, Source, Src) -> boolean()
92
93              Types:
94
95                 This = wxDC()
96                 Dest = {X :: integer(), Y :: integer()}
97                 Size = {W :: integer(), H :: integer()}
98                 Source = wxDC()
99                 Src = {X :: integer(), Y :: integer()}
100
101       blit(This, Dest, Size, Source, Src, Options :: [Option]) ->
102               boolean()
103
104              Types:
105
106                 This = wxDC()
107                 Dest = {X :: integer(), Y :: integer()}
108                 Size = {W :: integer(), H :: integer()}
109                 Source = wxDC()
110                 Src = {X :: integer(), Y :: integer()}
111                 Option =
112                     {rop, wx:wx_enum()} |
113                     {useMask, boolean()} |
114                     {srcPtMask, {X :: integer(), Y :: integer()}}
115
116              Copy from a source DC to this DC.
117
118              With this method you can specify the destination coordinates and
119              the size of area to copy which will be the  same  for  both  the
120              source  and target DCs. If you need to apply scaling while copy‐
121              ing, use StretchBlit() (not implemented in wx).
122
123              Notice that source DC coordinates xsrc and ysrc are  interpreted
124              using  the  current source DC coordinate system, i.e. the scale,
125              origin position and axis directions are taken into account  when
126              transforming them to physical (pixel) coordinates.
127
128              Remark:  There  is partial support for blit/6 in wxPostScriptDC,
129              under X.
130
131              See:  StretchBlit()  (not  implemented   in   wx),   wxMemoryDC,
132              wxBitmap, wxMask
133
134       calcBoundingBox(This, X, Y) -> ok
135
136              Types:
137
138                 This = wxDC()
139                 X = Y = integer()
140
141              Adds  the  specified  point to the bounding box which can be re‐
142              trieved with minX/1, maxX/1 and minY/1, maxY/1 functions.
143
144              See: resetBoundingBox/1
145
146       clear(This) -> ok
147
148              Types:
149
150                 This = wxDC()
151
152              Clears the device context using the current background brush.
153
154              Note that setBackground/2 method must be used to set  the  brush
155              used  by  clear/1,  the brush used for filling the shapes set by
156              setBrush/2 is ignored by it.
157
158              If no background brush was set, solid white  brush  is  used  to
159              clear the device context.
160
161       crossHair(This, Pt) -> ok
162
163              Types:
164
165                 This = wxDC()
166                 Pt = {X :: integer(), Y :: integer()}
167
168              This is an overloaded member function, provided for convenience.
169              It differs from the above function only in what  argument(s)  it
170              accepts.
171
172       destroyClippingRegion(This) -> ok
173
174              Types:
175
176                 This = wxDC()
177
178              Destroys  the  current clipping region so that none of the DC is
179              clipped.
180
181              See: setClippingRegion/3
182
183       deviceToLogicalX(This, X) -> integer()
184
185              Types:
186
187                 This = wxDC()
188                 X = integer()
189
190              Convert device X coordinate to  logical  coordinate,  using  the
191              current  mapping mode, user scale factor, device origin and axis
192              orientation.
193
194       deviceToLogicalXRel(This, X) -> integer()
195
196              Types:
197
198                 This = wxDC()
199                 X = integer()
200
201              Convert device X coordinate to relative logical coordinate,  us‐
202              ing  the current mapping mode and user scale factor but ignoring
203              the axis orientation.
204
205              Use this for converting a width, for example.
206
207       deviceToLogicalY(This, Y) -> integer()
208
209              Types:
210
211                 This = wxDC()
212                 Y = integer()
213
214              Converts device Y coordinate to logical  coordinate,  using  the
215              current  mapping mode, user scale factor, device origin and axis
216              orientation.
217
218       deviceToLogicalYRel(This, Y) -> integer()
219
220              Types:
221
222                 This = wxDC()
223                 Y = integer()
224
225              Convert device Y coordinate to relative logical coordinate,  us‐
226              ing  the current mapping mode and user scale factor but ignoring
227              the axis orientation.
228
229              Use this for converting a height, for example.
230
231       drawArc(This, PtStart, PtEnd, Centre) -> ok
232
233              Types:
234
235                 This = wxDC()
236                 PtStart = PtEnd = Centre = {X :: integer(), Y :: integer()}
237
238              This is an overloaded member function, provided for convenience.
239              It  differs  from the above function only in what argument(s) it
240              accepts.
241
242       drawBitmap(This, Bmp, Pt) -> ok
243
244              Types:
245
246                 This = wxDC()
247                 Bmp = wxBitmap:wxBitmap()
248                 Pt = {X :: integer(), Y :: integer()}
249
250       drawBitmap(This, Bmp, Pt, Options :: [Option]) -> ok
251
252              Types:
253
254                 This = wxDC()
255                 Bmp = wxBitmap:wxBitmap()
256                 Pt = {X :: integer(), Y :: integer()}
257                 Option = {useMask, boolean()}
258
259              This is an overloaded member function, provided for convenience.
260              It  differs  from the above function only in what argument(s) it
261              accepts.
262
263       drawCheckMark(This, Rect) -> ok
264
265              Types:
266
267                 This = wxDC()
268                 Rect =
269                     {X :: integer(),
270                      Y :: integer(),
271                      W :: integer(),
272                      H :: integer()}
273
274              This is an overloaded member function, provided for convenience.
275              It  differs  from the above function only in what argument(s) it
276              accepts.
277
278       drawCircle(This, Pt, Radius) -> ok
279
280              Types:
281
282                 This = wxDC()
283                 Pt = {X :: integer(), Y :: integer()}
284                 Radius = integer()
285
286              This is an overloaded member function, provided for convenience.
287              It  differs  from the above function only in what argument(s) it
288              accepts.
289
290       drawEllipse(This, Rect) -> ok
291
292              Types:
293
294                 This = wxDC()
295                 Rect =
296                     {X :: integer(),
297                      Y :: integer(),
298                      W :: integer(),
299                      H :: integer()}
300
301              This is an overloaded member function, provided for convenience.
302              It  differs  from the above function only in what argument(s) it
303              accepts.
304
305       drawEllipse(This, Pt, Size) -> ok
306
307              Types:
308
309                 This = wxDC()
310                 Pt = {X :: integer(), Y :: integer()}
311                 Size = {W :: integer(), H :: integer()}
312
313              This is an overloaded member function, provided for convenience.
314              It  differs  from the above function only in what argument(s) it
315              accepts.
316
317       drawEllipticArc(This, Pt, Sz, Sa, Ea) -> ok
318
319              Types:
320
321                 This = wxDC()
322                 Pt = {X :: integer(), Y :: integer()}
323                 Sz = {W :: integer(), H :: integer()}
324                 Sa = Ea = number()
325
326              This is an overloaded member function, provided for convenience.
327              It  differs  from the above function only in what argument(s) it
328              accepts.
329
330       drawIcon(This, Icon, Pt) -> ok
331
332              Types:
333
334                 This = wxDC()
335                 Icon = wxIcon:wxIcon()
336                 Pt = {X :: integer(), Y :: integer()}
337
338              This is an overloaded member function, provided for convenience.
339              It  differs  from the above function only in what argument(s) it
340              accepts.
341
342       drawLabel(This, Text, Rect) -> ok
343
344              Types:
345
346                 This = wxDC()
347                 Text = unicode:chardata()
348                 Rect =
349                     {X :: integer(),
350                      Y :: integer(),
351                      W :: integer(),
352                      H :: integer()}
353
354       drawLabel(This, Text, Rect, Options :: [Option]) -> ok
355
356              Types:
357
358                 This = wxDC()
359                 Text = unicode:chardata()
360                 Rect =
361                     {X :: integer(),
362                      Y :: integer(),
363                      W :: integer(),
364                      H :: integer()}
365                 Option = {alignment, integer()} | {indexAccel, integer()}
366
367              This is an overloaded member function, provided for convenience.
368              It  differs  from the above function only in what argument(s) it
369              accepts.
370
371       drawLine(This, Pt1, Pt2) -> ok
372
373              Types:
374
375                 This = wxDC()
376                 Pt1 = Pt2 = {X :: integer(), Y :: integer()}
377
378              This is an overloaded member function, provided for convenience.
379              It  differs  from the above function only in what argument(s) it
380              accepts.
381
382       drawLines(This, Points) -> ok
383
384              Types:
385
386                 This = wxDC()
387                 Points = [{X :: integer(), Y :: integer()}]
388
389       drawLines(This, Points, Options :: [Option]) -> ok
390
391              Types:
392
393                 This = wxDC()
394                 Points = [{X :: integer(), Y :: integer()}]
395                 Option = {xoffset, integer()} | {yoffset, integer()}
396
397              Draws lines using an array of points of size n  adding  the  op‐
398              tional offset coordinate.
399
400              The current pen is used for drawing the lines.
401
402       drawPolygon(This, Points) -> ok
403
404              Types:
405
406                 This = wxDC()
407                 Points = [{X :: integer(), Y :: integer()}]
408
409       drawPolygon(This, Points, Options :: [Option]) -> ok
410
411              Types:
412
413                 This = wxDC()
414                 Points = [{X :: integer(), Y :: integer()}]
415                 Option =
416                     {xoffset, integer()} |
417                     {yoffset, integer()} |
418                     {fillStyle, wx:wx_enum()}
419
420              Draws  a  filled  polygon  using  an  array of points of size n,
421              adding the optional offset coordinate.
422
423              The first and last points are automatically closed.
424
425              The last argument specifies the fill rule:  wxODDEVEN_RULE  (the
426              default) or wxWINDING_RULE.
427
428              The current pen is used for drawing the outline, and the current
429              brush for filling the shape.  Using  a  transparent  brush  sup‐
430              presses filling.
431
432       drawPoint(This, Pt) -> ok
433
434              Types:
435
436                 This = wxDC()
437                 Pt = {X :: integer(), Y :: integer()}
438
439              This is an overloaded member function, provided for convenience.
440              It differs from the above function only in what  argument(s)  it
441              accepts.
442
443       drawRectangle(This, Rect) -> ok
444
445              Types:
446
447                 This = wxDC()
448                 Rect =
449                     {X :: integer(),
450                      Y :: integer(),
451                      W :: integer(),
452                      H :: integer()}
453
454              This is an overloaded member function, provided for convenience.
455              It differs from the above function only in what  argument(s)  it
456              accepts.
457
458       drawRectangle(This, Pt, Sz) -> ok
459
460              Types:
461
462                 This = wxDC()
463                 Pt = {X :: integer(), Y :: integer()}
464                 Sz = {W :: integer(), H :: integer()}
465
466              This is an overloaded member function, provided for convenience.
467              It differs from the above function only in what  argument(s)  it
468              accepts.
469
470       drawRotatedText(This, Text, Point, Angle) -> ok
471
472              Types:
473
474                 This = wxDC()
475                 Text = unicode:chardata()
476                 Point = {X :: integer(), Y :: integer()}
477                 Angle = number()
478
479              This is an overloaded member function, provided for convenience.
480              It differs from the above function only in what  argument(s)  it
481              accepts.
482
483       drawRoundedRectangle(This, Rect, Radius) -> ok
484
485              Types:
486
487                 This = wxDC()
488                 Rect =
489                     {X :: integer(),
490                      Y :: integer(),
491                      W :: integer(),
492                      H :: integer()}
493                 Radius = number()
494
495              This is an overloaded member function, provided for convenience.
496              It differs from the above function only in what  argument(s)  it
497              accepts.
498
499       drawRoundedRectangle(This, Pt, Sz, Radius) -> ok
500
501              Types:
502
503                 This = wxDC()
504                 Pt = {X :: integer(), Y :: integer()}
505                 Sz = {W :: integer(), H :: integer()}
506                 Radius = number()
507
508              This is an overloaded member function, provided for convenience.
509              It differs from the above function only in what  argument(s)  it
510              accepts.
511
512       drawText(This, Text, Pt) -> ok
513
514              Types:
515
516                 This = wxDC()
517                 Text = unicode:chardata()
518                 Pt = {X :: integer(), Y :: integer()}
519
520              This is an overloaded member function, provided for convenience.
521              It differs from the above function only in what  argument(s)  it
522              accepts.
523
524       endDoc(This) -> ok
525
526              Types:
527
528                 This = wxDC()
529
530              Ends a document (only relevant when outputting to a printer).
531
532       endPage(This) -> ok
533
534              Types:
535
536                 This = wxDC()
537
538              Ends  a  document  page  (only  relevant  when  outputting  to a
539              printer).
540
541       floodFill(This, Pt, Col) -> boolean()
542
543              Types:
544
545                 This = wxDC()
546                 Pt = {X :: integer(), Y :: integer()}
547                 Col = wx:wx_colour()
548
549       floodFill(This, Pt, Col, Options :: [Option]) -> boolean()
550
551              Types:
552
553                 This = wxDC()
554                 Pt = {X :: integer(), Y :: integer()}
555                 Col = wx:wx_colour()
556                 Option = {style, wx:wx_enum()}
557
558              This is an overloaded member function, provided for convenience.
559              It  differs  from the above function only in what argument(s) it
560              accepts.
561
562       getBackground(This) -> wxBrush:wxBrush()
563
564              Types:
565
566                 This = wxDC()
567
568              Gets the brush used for painting the background.
569
570              See: setBackground/2
571
572       getBackgroundMode(This) -> integer()
573
574              Types:
575
576                 This = wxDC()
577
578              Returns the current background mode: wxPENSTYLE_SOLID or  wxPEN‐
579              STYLE_TRANSPARENT.
580
581              See: setBackgroundMode/2
582
583       getBrush(This) -> wxBrush:wxBrush()
584
585              Types:
586
587                 This = wxDC()
588
589              Gets the current brush.
590
591              See: setBrush/2
592
593       getCharHeight(This) -> integer()
594
595              Types:
596
597                 This = wxDC()
598
599              Gets the character height of the currently set font.
600
601       getCharWidth(This) -> integer()
602
603              Types:
604
605                 This = wxDC()
606
607              Gets the average character width of the currently set font.
608
609       getClippingBox(This) -> Result
610
611              Types:
612
613                 Result =
614                     {X :: integer(),
615                      Y :: integer(),
616                      Width :: integer(),
617                      Height :: integer()}
618                 This = wxDC()
619
620               Gets  the rectangle surrounding the current clipping region. If
621              no clipping region is set this function returns  the  extent  of
622              the device context. @remarks Clipping region is given in logical
623              coordinates. @param x If non-<span  class='literal'>NULL</span>,
624              filled in with the logical horizontal coordinate of the top left
625              corner of the clipping region if the function returns true or  0
626              otherwise.  @param  y  If non-<span class='literal'>NULL</span>,
627              filled in with the logical vertical coordinate of the  top  left
628              corner  of the clipping region if the function returns true or 0
629              otherwise.    @param    width    If    non-<span     class='lit‐
630              eral'>NULL</span>,  filled in with the width of the clipping re‐
631              gion if the function returns true or the  device  context  width
632              otherwise.    @param    height    If    non-<span    class='lit‐
633              eral'>NULL</span>, filled in with the height of the clipping re‐
634              gion  if  the function returns true or the device context height
635              otherwise.
636
637              Return: true if there is a clipping region or false if there  is
638              no active clipping region (note that this return value is avail‐
639              able only since wxWidgets 3.1.2,  this  function  didn't  return
640              anything in the previous versions).
641
642       getFont(This) -> wxFont:wxFont()
643
644              Types:
645
646                 This = wxDC()
647
648              Gets the current font.
649
650              Notice  that  even  although each device context object has some
651              default font after creation, this method would return a ?wxNull‐
652              Font  initially and only after calling setFont/2 a valid font is
653              returned.
654
655       getLayoutDirection(This) -> wx:wx_enum()
656
657              Types:
658
659                 This = wxDC()
660
661              Gets the current layout direction of the device context.
662
663              On platforms where RTL layout is  supported,  the  return  value
664              will  either be wxLayout_LeftToRight or wxLayout_RightToLeft. If
665              RTL layout is not supported, the return  value  will  be  wxLay‐
666              out_Default.
667
668              See: setLayoutDirection/2
669
670       getLogicalFunction(This) -> wx:wx_enum()
671
672              Types:
673
674                 This = wxDC()
675
676              Gets the current logical function.
677
678              See: setLogicalFunction/2
679
680       getMapMode(This) -> wx:wx_enum()
681
682              Types:
683
684                 This = wxDC()
685
686              Gets the current mapping mode for the device context.
687
688              See: setMapMode/2
689
690       getMultiLineTextExtent(This, String) ->
691                                 {W :: integer(), H :: integer()}
692
693              Types:
694
695                 This = wxDC()
696                 String = unicode:chardata()
697
698              Gets  the  dimensions of the string using the currently selected
699              font.
700
701              string is the text string to measure.
702
703              Return: The text extent as a {Width,Height} object.
704
705              Note: This function works with both single-line  and  multi-line
706              strings.
707
708              See: wxFont, setFont/2, getPartialTextExtents/2, getTextExtent/3
709
710       getMultiLineTextExtent(This, String, Options :: [Option]) ->
711                                 {W :: integer(),
712                                  H :: integer(),
713                                  HeightLine :: integer()}
714
715              Types:
716
717                 This = wxDC()
718                 String = unicode:chardata()
719                 Option = {font, wxFont:wxFont()}
720
721              Gets  the  dimensions of the string using the currently selected
722              font.
723
724              string is the text string to measure, heightLine, if  non  NULL,
725              is where to store the height of a single line.
726
727              The text extent is set in the given w and h pointers.
728
729              If  the  optional parameter font is specified and valid, then it
730              is used for the text extent calculation, otherwise the currently
731              selected font is used.
732
733              If  string  is empty, its horizontal extent is 0 but, for conve‐
734              nience when using this function for allocating enough space  for
735              a possibly multi-line string, its vertical extent is the same as
736              the height of an empty line of text. Please note that  this  be‐
737              haviour differs from that of getTextExtent/3.
738
739              Note:  This  function works with both single-line and multi-line
740              strings.
741
742              See: wxFont, setFont/2, getPartialTextExtents/2, getTextExtent/3
743
744       getPartialTextExtents(This, Text) -> Result
745
746              Types:
747
748                 Result = {Res :: boolean(), Widths :: [integer()]}
749                 This = wxDC()
750                 Text = unicode:chardata()
751
752              Fills the widths array with the widths  from  the  beginning  of
753              text to the corresponding character of text.
754
755              The  generic version simply builds a running total of the widths
756              of each character using getTextExtent/3, however if the  various
757              platforms  have a native API function that is faster or more ac‐
758              curate than the generic implementation then it  should  be  used
759              instead.
760
761              See: getMultiLineTextExtent/3, getTextExtent/3
762
763       getPen(This) -> wxPen:wxPen()
764
765              Types:
766
767                 This = wxDC()
768
769              Gets the current pen.
770
771              See: setPen/2
772
773       getPixel(This, Pos) -> Result
774
775              Types:
776
777                 Result = {Res :: boolean(), Colour :: wx:wx_colour4()}
778                 This = wxDC()
779                 Pos = {X :: integer(), Y :: integer()}
780
781              Gets in colour the colour at the specified location.
782
783              This  method  isn't available for wxPostScriptDC or wxMetafileDC
784              (not implemented in wx) nor for any DC in wxOSX port and  simply
785              returns false there.
786
787              Note: Setting a pixel can be done using drawPoint/2.
788
789              Note:  This method shouldn't be used with wxPaintDC as accessing
790              the DC while drawing can result in unexpected  results,  notably
791              in wxGTK.
792
793       getPPI(This) -> {W :: integer(), H :: integer()}
794
795              Types:
796
797                 This = wxDC()
798
799              Returns the resolution of the device in pixels per inch.
800
801       getSize(This) -> {W :: integer(), H :: integer()}
802
803              Types:
804
805                 This = wxDC()
806
807              This is an overloaded member function, provided for convenience.
808              It differs from the above function only in what  argument(s)  it
809              accepts.
810
811       getSizeMM(This) -> {W :: integer(), H :: integer()}
812
813              Types:
814
815                 This = wxDC()
816
817              This is an overloaded member function, provided for convenience.
818              It differs from the above function only in what  argument(s)  it
819              accepts.
820
821       getTextBackground(This) -> wx:wx_colour4()
822
823              Types:
824
825                 This = wxDC()
826
827              Gets the current text background colour.
828
829              See: setTextBackground/2
830
831       getTextExtent(This, String) -> {W :: integer(), H :: integer()}
832
833              Types:
834
835                 This = wxDC()
836                 String = unicode:chardata()
837
838              This is an overloaded member function, provided for convenience.
839              It differs from the above function only in what  argument(s)  it
840              accepts.
841
842       getTextExtent(This, String, Options :: [Option]) -> Result
843
844              Types:
845
846                 Result =
847                     {W :: integer(),
848                      H :: integer(),
849                      Descent :: integer(),
850                      ExternalLeading :: integer()}
851                 This = wxDC()
852                 String = unicode:chardata()
853                 Option = {theFont, wxFont:wxFont()}
854
855              Gets  the  dimensions of the string using the currently selected
856              font.
857
858              string is the text string to measure, descent is  the  dimension
859              from  the  baseline  of the font to the bottom of the descender,
860              and externalLeading is any extra vertical  space  added  to  the
861              font by the font designer (usually is zero).
862
863              The  text  extent  is  returned  in  w  and  h  pointers or as a
864              {Width,Height} object depending on which version of  this  func‐
865              tion is used.
866
867              If  the  optional parameter font is specified and valid, then it
868              is used for the text extent calculation. Otherwise the currently
869              selected font is.
870
871              If  string  is empty, its extent is 0 in both directions, as ex‐
872              pected.
873
874              Note: This function only works with single-line strings.
875
876              See: wxFont, setFont/2,  getPartialTextExtents/2,  getMultiLine‐
877              TextExtent/3
878
879       getTextForeground(This) -> wx:wx_colour4()
880
881              Types:
882
883                 This = wxDC()
884
885              Gets the current text foreground colour.
886
887              See: setTextForeground/2
888
889       getUserScale(This) -> {X :: number(), Y :: number()}
890
891              Types:
892
893                 This = wxDC()
894
895              Gets the current user scale factor.
896
897              See: setUserScale/3
898
899       gradientFillConcentric(This, Rect, InitialColour, DestColour) ->
900                                 ok
901
902              Types:
903
904                 This = wxDC()
905                 Rect =
906                     {X :: integer(),
907                      Y :: integer(),
908                      W :: integer(),
909                      H :: integer()}
910                 InitialColour = DestColour = wx:wx_colour()
911
912              Fill the area specified by rect with a radial gradient, starting
913              from initialColour at the centre of the  circle  and  fading  to
914              destColour on the circle outside.
915
916              The circle is placed at the centre of rect.
917
918              Note:  Currently  this  function  is very slow, don't use it for
919              real-time drawing.
920
921       gradientFillConcentric(This, Rect, InitialColour, DestColour,
922                              CircleCenter) ->
923                                 ok
924
925              Types:
926
927                 This = wxDC()
928                 Rect =
929                     {X :: integer(),
930                      Y :: integer(),
931                      W :: integer(),
932                      H :: integer()}
933                 InitialColour = DestColour = wx:wx_colour()
934                 CircleCenter = {X :: integer(), Y :: integer()}
935
936              Fill the area specified by rect with a radial gradient, starting
937              from  initialColour  at  the  centre of the circle and fading to
938              destColour on the circle outside.
939
940              circleCenter are the relative coordinates of centre of the  cir‐
941              cle in the specified rect.
942
943              Note:  Currently  this  function  is very slow, don't use it for
944              real-time drawing.
945
946       gradientFillLinear(This, Rect, InitialColour, DestColour) -> ok
947
948              Types:
949
950                 This = wxDC()
951                 Rect =
952                     {X :: integer(),
953                      Y :: integer(),
954                      W :: integer(),
955                      H :: integer()}
956                 InitialColour = DestColour = wx:wx_colour()
957
958       gradientFillLinear(This, Rect, InitialColour, DestColour,
959                          Options :: [Option]) ->
960                             ok
961
962              Types:
963
964                 This = wxDC()
965                 Rect =
966                     {X :: integer(),
967                      Y :: integer(),
968                      W :: integer(),
969                      H :: integer()}
970                 InitialColour = DestColour = wx:wx_colour()
971                 Option = {nDirection, wx:wx_enum()}
972
973              Fill the area specified by rect with a linear gradient, starting
974              from initialColour and eventually fading to destColour.
975
976              The nDirection specifies the direction of the colour change, de‐
977              fault is to use initialColour on the left part of the  rectangle
978              and destColour on the right one.
979
980       logicalToDeviceX(This, X) -> integer()
981
982              Types:
983
984                 This = wxDC()
985                 X = integer()
986
987              Converts  logical  X  coordinate to device coordinate, using the
988              current mapping mode, user scale factor, device origin and  axis
989              orientation.
990
991       logicalToDeviceXRel(This, X) -> integer()
992
993              Types:
994
995                 This = wxDC()
996                 X = integer()
997
998              Converts logical X coordinate to relative device coordinate, us‐
999              ing the current mapping mode and user scale factor but  ignoring
1000              the axis orientation.
1001
1002              Use this for converting a width, for example.
1003
1004       logicalToDeviceY(This, Y) -> integer()
1005
1006              Types:
1007
1008                 This = wxDC()
1009                 Y = integer()
1010
1011              Converts  logical  Y  coordinate to device coordinate, using the
1012              current mapping mode, user scale factor, device origin and  axis
1013              orientation.
1014
1015       logicalToDeviceYRel(This, Y) -> integer()
1016
1017              Types:
1018
1019                 This = wxDC()
1020                 Y = integer()
1021
1022              Converts logical Y coordinate to relative device coordinate, us‐
1023              ing the current mapping mode and user scale factor but  ignoring
1024              the axis orientation.
1025
1026              Use this for converting a height, for example.
1027
1028       maxX(This) -> integer()
1029
1030              Types:
1031
1032                 This = wxDC()
1033
1034              Gets  the  maximum horizontal extent used in drawing commands so
1035              far.
1036
1037       maxY(This) -> integer()
1038
1039              Types:
1040
1041                 This = wxDC()
1042
1043              Gets the maximum vertical extent used  in  drawing  commands  so
1044              far.
1045
1046       minX(This) -> integer()
1047
1048              Types:
1049
1050                 This = wxDC()
1051
1052              Gets  the  minimum horizontal extent used in drawing commands so
1053              far.
1054
1055       minY(This) -> integer()
1056
1057              Types:
1058
1059                 This = wxDC()
1060
1061              Gets the minimum vertical extent used  in  drawing  commands  so
1062              far.
1063
1064       isOk(This) -> boolean()
1065
1066              Types:
1067
1068                 This = wxDC()
1069
1070              Returns true if the DC is ok to use.
1071
1072       resetBoundingBox(This) -> ok
1073
1074              Types:
1075
1076                 This = wxDC()
1077
1078              Resets  the  bounding  box:  after  a call to this function, the
1079              bounding box doesn't contain anything.
1080
1081              See: calcBoundingBox/3
1082
1083       setAxisOrientation(This, XLeftRight, YBottomUp) -> ok
1084
1085              Types:
1086
1087                 This = wxDC()
1088                 XLeftRight = YBottomUp = boolean()
1089
1090              Sets the x and y axis orientation (i.e. the direction from  low‐
1091              est to highest values on the axis).
1092
1093              The  default orientation is x axis from left to right and y axis
1094              from top down.
1095
1096       setBackground(This, Brush) -> ok
1097
1098              Types:
1099
1100                 This = wxDC()
1101                 Brush = wxBrush:wxBrush()
1102
1103              Sets the current background brush for the DC.
1104
1105       setBackgroundMode(This, Mode) -> ok
1106
1107              Types:
1108
1109                 This = wxDC()
1110                 Mode = integer()
1111
1112              mode may be one of wxPENSTYLE_SOLID and wxPENSTYLE_TRANSPARENT.
1113
1114              This setting determines whether text will be drawn with a  back‐
1115              ground colour or not.
1116
1117       setBrush(This, Brush) -> ok
1118
1119              Types:
1120
1121                 This = wxDC()
1122                 Brush = wxBrush:wxBrush()
1123
1124              Sets the current brush for the DC.
1125
1126              If  the  argument is ?wxNullBrush (or another invalid brush; see
1127              wxBrush:isOk/1), the current brush is selected out of the device
1128              context  (leaving  wxDC  without  any valid brush), allowing the
1129              current brush to be destroyed safely.
1130
1131              See: wxBrush, wxMemoryDC, (for  the  interpretation  of  colours
1132              when drawing into a monochrome bitmap)
1133
1134       setClippingRegion(This, Rect) -> ok
1135
1136              Types:
1137
1138                 This = wxDC()
1139                 Rect =
1140                     {X :: integer(),
1141                      Y :: integer(),
1142                      W :: integer(),
1143                      H :: integer()}
1144
1145              This is an overloaded member function, provided for convenience.
1146              It differs from the above function only in what  argument(s)  it
1147              accepts.
1148
1149       setClippingRegion(This, Pt, Sz) -> ok
1150
1151              Types:
1152
1153                 This = wxDC()
1154                 Pt = {X :: integer(), Y :: integer()}
1155                 Sz = {W :: integer(), H :: integer()}
1156
1157              This is an overloaded member function, provided for convenience.
1158              It differs from the above function only in what  argument(s)  it
1159              accepts.
1160
1161       setDeviceOrigin(This, X, Y) -> ok
1162
1163              Types:
1164
1165                 This = wxDC()
1166                 X = Y = integer()
1167
1168              Sets  the device origin (i.e. the origin in pixels after scaling
1169              has been applied).
1170
1171              This function may be useful in Windows printing  operations  for
1172              placing a graphic on a page.
1173
1174       setFont(This, Font) -> ok
1175
1176              Types:
1177
1178                 This = wxDC()
1179                 Font = wxFont:wxFont()
1180
1181              Sets the current font for the DC.
1182
1183              If the argument is ?wxNullFont (or another invalid font; see wx‐
1184              Font:isOk/1), the current font is selected  out  of  the  device
1185              context (leaving wxDC without any valid font), allowing the cur‐
1186              rent font to be destroyed safely.
1187
1188              See: wxFont
1189
1190       setLayoutDirection(This, Dir) -> ok
1191
1192              Types:
1193
1194                 This = wxDC()
1195                 Dir = wx:wx_enum()
1196
1197              Sets the current layout direction for the device context.
1198
1199              See: getLayoutDirection/1
1200
1201       setLogicalFunction(This, Function) -> ok
1202
1203              Types:
1204
1205                 This = wxDC()
1206                 Function = wx:wx_enum()
1207
1208              Sets the current logical function for the device context.
1209
1210              Note: This function is not fully supported in all ports, due  to
1211              the  limitations of the underlying drawing model. Notably, wxIN‐
1212              VERT which was commonly used for drawing rubber bands  or  other
1213              moving  outlines in the past, is not, and will not, be supported
1214              by wxGTK3 and wxMac. The suggested alternative is to draw tempo‐
1215              rarily  objects  normally and refresh the (affected part of the)
1216              window to remove them later.
1217
1218              It determines how a source pixel (from a pen or brush colour, or
1219              source  device context if using blit/6) combines with a destina‐
1220              tion pixel in the current device context. Text  drawing  is  not
1221              affected by this function.
1222
1223              See ?wxRasterOperationMode enumeration values for more info.
1224
1225              The  default  is  wxCOPY,  which  simply  draws with the current
1226              colour. The others combine the current colour and the background
1227              using a logical operation.
1228
1229       setMapMode(This, Mode) -> ok
1230
1231              Types:
1232
1233                 This = wxDC()
1234                 Mode = wx:wx_enum()
1235
1236              The  mapping mode of the device context defines the unit of mea‐
1237              surement used to convert logical units to device units.
1238
1239              Note that in X, text drawing isn't handled consistently with the
1240              mapping mode; a font is always specified in point size. However,
1241              setting the user scale (see setUserScale/3) scales the text  ap‐
1242              propriately.  In  Windows,  scalable  TrueType  fonts are always
1243              used; in X, results depend on availability of fonts, but usually
1244              a reasonable match is found.
1245
1246              The  coordinate  origin  is  always  at  the  top  left  of  the
1247              screen/printer.
1248
1249              Drawing to a Windows printer device  context  uses  the  current
1250              mapping  mode,  but  mapping mode is currently ignored for Post‐
1251              Script output.
1252
1253       setPalette(This, Palette) -> ok
1254
1255              Types:
1256
1257                 This = wxDC()
1258                 Palette = wxPalette:wxPalette()
1259
1260              If this is a window DC or memory DC, assigns the  given  palette
1261              to the window or bitmap associated with the DC.
1262
1263              If  the  argument  is ?wxNullPalette, the current palette is se‐
1264              lected out of the device context, and the original  palette  re‐
1265              stored.
1266
1267              See: wxPalette
1268
1269       setPen(This, Pen) -> ok
1270
1271              Types:
1272
1273                 This = wxDC()
1274                 Pen = wxPen:wxPen()
1275
1276              Sets the current pen for the DC.
1277
1278              If  the  argument is ?wxNullPen (or another invalid pen; see wx‐
1279              Pen:isOk/1), the current pen is selected out of the device  con‐
1280              text  (leaving wxDC without any valid pen), allowing the current
1281              pen to be destroyed safely.
1282
1283              See: wxMemoryDC, for the interpretation of colours when  drawing
1284              into a monochrome bitmap
1285
1286       setTextBackground(This, Colour) -> ok
1287
1288              Types:
1289
1290                 This = wxDC()
1291                 Colour = wx:wx_colour()
1292
1293              Sets the current text background colour for the DC.
1294
1295       setTextForeground(This, Colour) -> ok
1296
1297              Types:
1298
1299                 This = wxDC()
1300                 Colour = wx:wx_colour()
1301
1302              Sets the current text foreground colour for the DC.
1303
1304              See:  wxMemoryDC, for the interpretation of colours when drawing
1305              into a monochrome bitmap
1306
1307       setUserScale(This, XScale, YScale) -> ok
1308
1309              Types:
1310
1311                 This = wxDC()
1312                 XScale = YScale = number()
1313
1314              Sets the user scaling factor, useful for applications which  re‐
1315              quire 'zooming'.
1316
1317       startDoc(This, Message) -> boolean()
1318
1319              Types:
1320
1321                 This = wxDC()
1322                 Message = unicode:chardata()
1323
1324              Starts a document (only relevant when outputting to a printer).
1325
1326              message is a message to show while printing.
1327
1328       startPage(This) -> ok
1329
1330              Types:
1331
1332                 This = wxDC()
1333
1334              Starts  a  document  page  (only  relevant  when outputting to a
1335              printer).
1336
1337
1338
1339wxWidgets team.                     wx 2.1                             wxDC(3)
Impressum