wxruby3 0.9.0-x64-mingw-ucrt → 0.9.2-x64-mingw-ucrt

data/lib/wx/doc/gen/dc.rb

@@ -10,7 +10,7 @@ module Wx
   # 
   # {Wx::DC#blit} and {Wx::DC#stretch_blit}).
   # The description of the values below refer to how a generic src source pixel and the corresponding dst destination pixel gets combined together to produce the final pixel. E.g. {Wx::RasterOperationMode::CLEAR} and {Wx::RasterOperationMode::SET} completely ignore the source and the destination pixel and always put zeroes or ones in the final surface.
-  # Note that not all modes are supported under all platforms. Notably wxGTK3 and {Wx::Mac} only support the following modes:
+  # Note that not all modes are supported under all platforms. Notably WXGTK3 and WXOSX only support the following modes:
   # 
   # - {Wx::RasterOperationMode::COPY}
   # - {Wx::RasterOperationMode::OR}
@@ -137,22 +137,21 @@ module Wx
   # In addition to the versions of the methods documented below, there are also versions which accept single {Wx::Point} parameter instead of the two {Wx::Coord} ones or {Wx::Point} and {Wx::Size} instead of the four {Wx::Coord} parameters.
   # Beginning with wxWidgets 2.9.0 the entire {Wx::DC} code has been reorganized. All platform dependent code (actually all drawing code) has been moved into backend classes which derive from a common {Wx::DCImpl} class. The user-visible classes such as {Wx::ClientDC} and {Wx::PaintDC} merely forward all calls to the backend implementation.
   # 
-  # == Device and logical units
+  # ## Device and logical units
   # 
   # In the {Wx::DC} context there is a distinction between logical units and device units.
   # <b>Device</b> units are the units native to the particular device; e.g. for a screen, a device unit is a pixel. For a printer, the device unit is defined by the resolution of the printer (usually given in DPI: dot-per-inch).
   # All {Wx::DC} functions use instead <b>logical</b> units, unless where explicitly stated. Logical units are arbitrary units mapped to device units using the current mapping mode (see {Wx::DC#set_map_mode}).
   # This mechanism allows reusing the same code which prints on e.g. a window on the screen to print on e.g. a paper.
   # 
-  # == Support for Transparency / Alpha Channel
+  # ## Support for Transparency / Alpha Channel
   # 
   # In general {Wx::DC} methods don't support alpha transparency and the alpha component of {Wx::Colour} is simply ignored and you need to use {Wx::GraphicsContext} for full transparency support. There are, however, a few exceptions: first, under macOS and GTK+ 3 colours with alpha channel are supported in all the normal {Wx::DC}-derived classes as they use {Wx::GraphicsContext} internally. Second, under all platforms {Wx::SVGFileDC} also fully supports alpha channel. In both of these cases the instances of {Wx::Pen} or {Wx::Brush} that are built from {Wx::Colour} use the colour's alpha values when stroking or filling.
   # 
-  # == Support for Transformation Matrix
+  # ## Support for Transformation Matrix
   # 
   # On some platforms (currently under MSW, GTK+ 3, macOS) {Wx::DC} has support for applying an arbitrary affine transformation matrix to its coordinate system (since 3.1.1 this feature is also supported by {Wx::GCDC} in all ports). Call {Wx::DC#can_use_transform_matrix} to check if this support is available and then call {Wx::DC#set_transform_matrix} if it is. If the transformation matrix is not supported, {Wx::DC#set_transform_matrix} always simply returns false and doesn't do anything.
   # This feature is only available when {Wx::Setup::USE_DC_TRANSFORM_MATRIX} build option is enabled.
-  # === 
   # 
   # Category:  Device Contexts, Graphics Device Interface (GDI)
   # 
@@ -172,53 +171,89 @@ module Wx
   class DC < Object
   
     # Convert device X coordinate to logical coordinate, using the current mapping mode, user scale factor, device origin and axis orientation.
-    # Affine transformation applied to the coordinate system with {Wx::DC#set_transform_matrix} is not taken into account.
+    # <div class="wxrb-note">
+    # <b>Note:</b>
+    # <p>Affine transformation applied to the coordinate system with {Wx::DC#set_transform_matrix} is not taken into account. 
+    # </p>
+    # </div>
     # @param x [Integer] 
     # @return [Integer]
     def device_to_logical_x(x) end
     
     # Convert device X coordinate to relative logical coordinate, using the current mapping mode and user scale factor but ignoring the axis orientation.
     # Use this for converting a horizontal distance like for example a width.
-    # Affine transformation applied to the coordinate system with {Wx::DC#set_transform_matrix} is not taken into account.
+    # 
+    # <div class="wxrb-note">
+    # <b>Note:</b>
+    # <p>Affine transformation applied to the coordinate system with {Wx::DC#set_transform_matrix} is not taken into account. 
+    # </p>
+    # </div>
     # @param x [Integer] 
     # @return [Integer]
     def device_to_logical_x_rel(x) end
     
     # Converts device Y coordinate to logical coordinate, using the current mapping mode, user scale factor, device origin and axis orientation.
-    # Affine transformation applied to the coordinate system with {Wx::DC#set_transform_matrix} is not taken into account.
+    # <div class="wxrb-note">
+    # <b>Note:</b>
+    # <p>Affine transformation applied to the coordinate system with {Wx::DC#set_transform_matrix} is not taken into account. 
+    # </p>
+    # </div>
     # @param y [Integer] 
     # @return [Integer]
     def device_to_logical_y(y) end
     
     # Convert device Y coordinate to relative logical coordinate, using the current mapping mode and user scale factor but ignoring the axis orientation.
     # Use this for converting a vertical distance like for example a height.
-    # Affine transformation applied to the coordinate system with {Wx::DC#set_transform_matrix} is not taken into account.
+    # 
+    # <div class="wxrb-note">
+    # <b>Note:</b>
+    # <p>Affine transformation applied to the coordinate system with {Wx::DC#set_transform_matrix} is not taken into account. 
+    # </p>
+    # </div>
     # @param y [Integer] 
     # @return [Integer]
     def device_to_logical_y_rel(y) end
     
     # Converts logical X coordinate to device coordinate, using the current mapping mode, user scale factor, device origin and axis orientation.
-    # Affine transformation applied to the coordinate system with {Wx::DC#set_transform_matrix} is not taken into account.
+    # <div class="wxrb-note">
+    # <b>Note:</b>
+    # <p>Affine transformation applied to the coordinate system with {Wx::DC#set_transform_matrix} is not taken into account. 
+    # </p>
+    # </div>
     # @param x [Integer] 
     # @return [Integer]
     def logical_to_device_x(x) end
     
     # Converts logical X coordinate to relative device coordinate, using the current mapping mode and user scale factor but ignoring the axis orientation.
     # Use this for converting a horizontal distance like for example a width.
-    # Affine transformation applied to the coordinate system with {Wx::DC#set_transform_matrix} is not taken into account.
+    # 
+    # <div class="wxrb-note">
+    # <b>Note:</b>
+    # <p>Affine transformation applied to the coordinate system with {Wx::DC#set_transform_matrix} is not taken into account. 
+    # </p>
+    # </div>
     # @param x [Integer] 
     # @return [Integer]
     def logical_to_device_x_rel(x) end
     
     # Converts logical Y coordinate to device coordinate, using the current mapping mode, user scale factor, device origin and axis orientation.
-    # Affine transformation applied to the coordinate system with {Wx::DC#set_transform_matrix} is not taken into account.
+    # <div class="wxrb-note">
+    # <b>Note:</b>
+    # <p>Affine transformation applied to the coordinate system with {Wx::DC#set_transform_matrix} is not taken into account. 
+    # </p>
+    # </div>
     # @param y [Integer] 
     # @return [Integer]
     def logical_to_device_y(y) end
     
     # Converts logical Y coordinate to relative device coordinate, using the current mapping mode and user scale factor but ignoring the axis orientation.
     # Use this for converting a vertical distance like for example a height.
-    # Affine transformation applied to the coordinate system with {Wx::DC#set_transform_matrix} is not taken into account.
+    # 
+    # <div class="wxrb-note">
+    # <b>Note:</b>
+    # <p>Affine transformation applied to the coordinate system with {Wx::DC#set_transform_matrix} is not taken into account. 
+    # </p>
+    # </div>
     # @param y [Integer] 
     # @return [Integer]
     def logical_to_device_y_rel(y) end
@@ -277,7 +312,11 @@ module Wx
     
     # @overload draw_arc(xStart, yStart, xEnd, yEnd, xc, yc)
     #   Draws an arc from the given start to the given end point.
-    #   {Wx::DC#draw_elliptic_arc} has more clear semantics and it is recommended to use it instead of this function.
+    #   <div class="wxrb-note">
+    #   <b>Note:</b>
+    #   <p>{Wx::DC#draw_elliptic_arc} has more clear semantics and it is recommended to use it instead of this function.
+    #   </p>
+    #   </div>
     #   
     #   The arc drawn is an arc of the circle centered at (xc, yc). Its start point is (xStart, yStart) whereas its end point is the point of intersection of the line passing by (xc, yc) and (xEnd, yEnd) with the circle passing by (xStart, yStart).
     #   The arc is drawn in a counter-clockwise direction between the start and the end points.
@@ -503,7 +542,12 @@ module Wx
     # @overload draw_rotated_text(text, x, y, angle)
     #   Draws the text rotated by angle degrees (positive angles are counterclockwise; the full angle is 360 degrees).
     #   Notice that, as with {Wx::DC#draw_text}, the text can contain multiple lines separated by the new line (<code>'\n'</code>) characters.
-    #   Under MSW only TrueType fonts can be drawn by this function. In particular, a font different from {Wx::NORMAL_FONT} should be used as the latter is not a TrueType font. {Wx::SWISS_FONT} is an example of a font which is.
+    #   
+    #   <div class="wxrb-note">
+    #   <b>Note:</b>
+    #   <p>Under MSW only TrueType fonts can be drawn by this function. In particular, a font different from {Wx::NORMAL_FONT} should be used as the latter is not a TrueType font. {Wx::SWISS_FONT} is an example of a font which is.
+    #   </p>
+    #   </div>
     #   @see Wx::DC#draw_text 
     #   @param text [String] 
     #   @param x [Integer] 
@@ -544,7 +588,12 @@ module Wx
     # @overload draw_spline(points)
     #   Draws a spline between all given points using the current pen.
     #   The number of points must be at least 2 for the spline to be drawn.
-    #   Drawn curve is not an interpolating curve - it does not go through all points. It may be considered a smoothing curve.
+    #   
+    #   <div class="wxrb-note">
+    #   <b>Note:</b>
+    #   <p>Drawn curve is not an interpolating curve - it does not go through all points. It may be considered a smoothing curve.
+    #   </p>
+    #   </div>
     #   @param points [Array<Wx::Point>,Array<Array<Integer>>] 
     #   @return [void]
     # @overload draw_spline(x1, y1, x2, y2, x3, y3)
@@ -562,7 +611,12 @@ module Wx
     #   Draws a text string at the specified point, using the current text font, and the current text foreground and background colours.
     #   The coordinates refer to the top-left corner of the rectangle bounding the string. See {Wx::DC#get_text_extent} for how to get the dimensions of a text string, which can be used to position the text more precisely and {Wx::DC#draw_label} if you need to align the string differently.
     #   Starting from wxWidgets 2.9.2 text parameter can be a multi-line string, i.e. contain new line characters, and will be rendered correctly.
-    #   The current logical function is ignored by this function.
+    #   
+    #   <div class="wxrb-note">
+    #   <b>Note:</b>
+    #   <p>The current logical function is ignored by this function. 
+    #   </p>
+    #   </div>
     #   @param text [String] 
     #   @param x [Integer] 
     #   @param y [Integer] 
@@ -577,7 +631,12 @@ module Wx
     # @overload gradient_fill_concentric(rect, initialColour, destColour)
     #   Fill the area specified by rect with a radial gradient, starting from initialColour at the centre of the circle and fading to destColour on the circle outside.
     #   The circle is placed at the centre of rect.
-    #   Currently this function is very slow, don't use it for real-time drawing.
+    #   
+    #   <div class="wxrb-note">
+    #   <b>Note:</b>
+    #   <p>Currently this function is very slow, don't use it for real-time drawing. 
+    #   </p>
+    #   </div>
     #   @param rect [Wx::Rect] 
     #   @param initialColour [Wx::Colour,String,Symbol] 
     #   @param destColour [Wx::Colour,String,Symbol] 
@@ -585,7 +644,12 @@ module Wx
     # @overload gradient_fill_concentric(rect, initialColour, destColour, circleCenter)
     #   Fill the area specified by rect with a radial gradient, starting from initialColour at the centre of the circle and fading to destColour on the circle outside.
     #   circleCenter are the relative coordinates of centre of the circle in the specified rect.
-    #   Currently this function is very slow, don't use it for real-time drawing.
+    #   
+    #   <div class="wxrb-note">
+    #   <b>Note:</b>
+    #   <p>Currently this function is very slow, don't use it for real-time drawing. 
+    #   </p>
+    #   </div>
     #   @param rect [Wx::Rect] 
     #   @param initialColour [Wx::Colour,String,Symbol] 
     #   @param destColour [Wx::Colour,String,Symbol] 
@@ -607,12 +671,20 @@ module Wx
     #   - {Wx::FloodFillStyle::FLOOD_SURFACE}: The flooding occurs until a colour other than the given colour is encountered.
     #   - {Wx::FloodFillStyle::FLOOD_BORDER}: The area to be flooded is bounded by the given colour.
     #   
-    #   Currently this method is not implemented in wxOSX and does nothing there.
+    #   Currently this method is not implemented in WXOSX and does nothing there.
     #   false if the operation failed.
     #   
-    #   The present implementation for non-Windows platforms may fail to find colour borders if the pixels do not match the colour exactly. However the function will still return true.
+    #   <div class="wxrb-note">
+    #   <b>Note:</b>
+    #   <p>The present implementation for non-Windows platforms may fail to find colour borders if the pixels do not match the colour exactly. However the function will still return true.
+    #   </p>
+    #   </div>
     #   
-    #   This method shouldn't be used with {Wx::PaintDC} under non-Windows platforms as it uses {Wx::DC#get_pixel} internally and this may give wrong results, notably in wxGTK. If you need to flood fill {Wx::PaintDC}, create a temporary {Wx::MemoryDC}, flood fill it and then blit it to, or draw as a bitmap on, {Wx::PaintDC}. See the example of doing this in the drawing sample and {Wx::BufferedPaintDC} class.
+    #   <div class="wxrb-note">
+    #   <b>Note:</b>
+    #   <p>This method shouldn't be used with {Wx::PaintDC} under non-Windows platforms as it uses {Wx::DC#get_pixel} internally and this may give wrong results, notably in WXGTK. If you need to flood fill {Wx::PaintDC}, create a temporary {Wx::MemoryDC}, flood fill it and then blit it to, or draw as a bitmap on, {Wx::PaintDC}. See the example of doing this in the drawing sample and {Wx::BufferedPaintDC} class. 
+    #   </p>
+    #   </div>
     #   @param x [Integer] 
     #   @param y [Integer] 
     #   @param colour [Wx::Colour,String,Symbol] 
@@ -647,7 +719,12 @@ module Wx
     # @overload get_clipping_box(x, y)
     #   Gets the rectangle surrounding the current clipping region.
     #   If no clipping region is set this function returns the extent of the device context.
-    #   Clipping region is given in logical coordinates.
+    #   
+    #   <div class="wxrb-remark">
+    #   <b>Remark:</b>
+    #   <p>Clipping region is given in logical coordinates.
+    #   </p>
+    #   </div>>
     #   
     #   true if there is a clipping region or false if there is no active clipping region (note that this return value is available only since wxWidgets 3.1.2, this function didn't return anything in the previous versions).
     #   @param x [Integer]  If non-NULL, filled in with the logical horizontal coordinate of the top left corner of the clipping region if the function returns true or 0 otherwise.
@@ -664,10 +741,17 @@ module Wx
     #   Sets the clipping region for this device context to the intersection of the given region described by the parameters of this method and the previously set clipping region.
     #   The clipping region is an area to which drawing is restricted. Possible uses for the clipping region are for clipping text or for speeding up window redraws when only a known area of the screen is damaged.
     #   
+    #   <div class="wxrb-remark">
+    #   <b>Remark:</b>
+    #   <p>
+    #   
     #   - Clipping region should be given in logical coordinates.
     #   - Calling this function can only make the clipping region smaller, never larger.
     #   - You need to call {Wx::DC#destroy_clipping_region} first if you want to set the clipping region exactly to the region specified.
     #   - If resulting clipping region is empty, then all drawing on the DC is clipped out (all changes made by drawing operations are masked out).
+    #   
+    #   </p>
+    #   </div>>
     #   @see Wx::DC#destroy_clipping_region
     #   @see  Wx::Region 
     #   @param x [Integer] 
@@ -706,7 +790,7 @@ module Wx
     
     # Returns the various font characteristics.
     # This method allows retrieving some of the font characteristics not returned by {Wx::DC#get_text_extent}, notably internal leading and average character width.
-    # Currently this method returns correct results only under wxMSW, in the other ports the internal leading will always be 0 and the average character width will be computed as the width of the character 'x'.
+    # Currently this method returns correct results only under WXMSW, in the other ports the internal leading will always be 0 and the average character width will be computed as the width of the character 'x'.
     # @return [Wx::FontMetrics]
     def get_font_metrics; end
     alias_method :font_metrics, :get_font_metrics
@@ -716,7 +800,12 @@ module Wx
     # The text extent is set in the given w and h pointers.
     # If the optional parameter font is specified and valid, then it is used for the text extent calculation, otherwise the currently selected font is used.
     # If string is empty, its horizontal extent is 0 but, for convenience when using this function for allocating enough space for a possibly multi-line string, its vertical extent is the same as the height of an empty line of text. Please note that this behaviour differs from that of {Wx::DC#get_text_extent}.
-    # This function works with both single-line and multi-line strings.
+    # 
+    # <div class="wxrb-note">
+    # <b>Note:</b>
+    # <p>This function works with both single-line and multi-line strings.
+    # </p>
+    # </div>
     # @see Wx::Font
     # @see  Wx::DC#set_font
     # @see  Wx::DC#get_partial_text_extents
@@ -731,7 +820,11 @@ module Wx
     # string is the text string to measure.
     # The text extent as a {Wx::Size} object.
     # 
-    # This function works with both single-line and multi-line strings.
+    # <div class="wxrb-note">
+    # <b>Note:</b>
+    # <p>This function works with both single-line and multi-line strings.
+    # </p>
+    # </div>
     # @see Wx::Font
     # @see  Wx::DC#set_font
     # @see  Wx::DC#get_partial_text_extents
@@ -746,7 +839,12 @@ module Wx
     # The text extent is returned in w and h pointers or as a {Wx::Size} object depending on which version of this function is used.
     # If the optional parameter font is specified and valid, then it is used for the text extent calculation. Otherwise the currently selected font is.
     # If string is empty, its extent is 0 in both directions, as expected.
-    # This function only works with single-line strings.
+    # 
+    # <div class="wxrb-note">
+    # <b>Note:</b>
+    # <p>This function only works with single-line strings.
+    # </p>
+    # </div>
     # @see Wx::Font
     # @see  Wx::DC#set_font
     # @see  Wx::DC#get_partial_text_extents
@@ -806,7 +904,7 @@ module Wx
     alias_method :background_mode=, :set_background_mode
     
     # Sets the current font for the DC.
-    # The font parameter should be valid, although in wxMSW port (only) the argument {Wx::NULL_FONT} is also accepted and resets the device context font to the default value used by the system (which is not generally useful).
+    # The font parameter should be valid, although in WXMSW port (only) the argument {Wx::NULL_FONT} is also accepted and resets the device context font to the default value used by the system (which is not generally useful).
     # @see Wx::Font 
     # @param font [Wx::Font,Wx::FontInfo] 
     # @return [void]
@@ -887,7 +985,11 @@ module Wx
     # With this method you can specify the destination coordinates and the size of area to copy which will be the same for both the source and target DCs. If you need to apply scaling while copying, use {Wx::DC#stretch_blit}.
     # Notice that source DC coordinates xsrc and ysrc are interpreted using the current source DC coordinate system, i.e. the scale, origin position and axis directions are taken into account when transforming them to physical (pixel) coordinates.
     # 
-    # There is partial support for {Wx::DC#blit} in {Wx::PRT::PostScriptDC}, under X.
+    # <div class="wxrb-remark">
+    # <b>Remark:</b>
+    # <p>There is partial support for {Wx::DC#blit} in {Wx::PRT::PostScriptDC}, under X.
+    # </p>
+    # </div>>
     # @see Wx::DC#stretch_blit
     # @see  Wx::MemoryDC
     # @see  Wx::Bitmap
@@ -1052,7 +1154,12 @@ module Wx
     
     # Returns the factor used for converting logical pixels to physical ones.
     # Returns the same value as {Wx::Window#get_dpi_scale_factor} for the device contexts associated with a window and the same value as {Wx::Bitmap#get_scale_factor} for the associated bitmap for {Wx::MemoryDC}.
-    # Beware that since wxWidgets 3.1.6, this function does not return the same value as {Wx::Window#get_content_scale_factor} for the device contexts associated with the window. Unlike {Wx::Window} method, it always returns the effective scale factor instead of always returning 1 on platforms where logical pixels are the same as physical ones, such as MSW.
+    # 
+    # <div class="wxrb-note">
+    # <b>Note:</b>
+    # <p>Beware that since wxWidgets 3.1.6, this function does not return the same value as {Wx::Window#get_content_scale_factor} for the device contexts associated with the window. Unlike {Wx::Window} method, it always returns the effective scale factor instead of always returning 1 on platforms where logical pixels are the same as physical ones, such as MSW.
+    # </p>
+    # </div>
     # @return [Float]
     def get_content_scale_factor; end
     alias_method :content_scale_factor, :get_content_scale_factor
@@ -1086,10 +1193,19 @@ module Wx
     alias_method :map_mode, :get_map_mode
     
     # Gets in colour the colour at the specified location.
-    # This method isn't available for {Wx::PRT::PostScriptDC} or {Wx::MetafileDC} nor for any DC in wxOSX port and simply returns false there.
-    # Setting a pixel can be done using {Wx::DC#draw_point}.
-    # 
-    # This method shouldn't be used with {Wx::PaintDC} as accessing the DC while drawing can result in unexpected results, notably in wxGTK.
+    # This method isn't available for {Wx::PRT::PostScriptDC} or {Wx::MetafileDC} nor for any DC in WXOSX port and simply returns false there.
+    # 
+    # <div class="wxrb-note">
+    # <b>Note:</b>
+    # <p>Setting a pixel can be done using {Wx::DC#draw_point}.
+    # </p>
+    # </div>
+    # 
+    # <div class="wxrb-note">
+    # <b>Note:</b>
+    # <p>This method shouldn't be used with {Wx::PaintDC} as accessing the DC while drawing can result in unexpected results, notably in WXGTK. 
+    # </p>
+    # </div>
     # @param x [Integer] 
     # @param y [Integer] 
     # @param colour [Wx::Colour] 
@@ -1190,7 +1306,11 @@ module Wx
     def set_device_origin(x, y) end
     
     # Sets the current logical function for the device context.
-    # This function is not fully supported in all ports, due to the limitations of the underlying drawing model. Notably, {Wx::RasterOperationMode::INVERT} which was commonly used for drawing rubber bands or other moving outlines in the past, is not, and will not, be supported by wxGTK3 and {Wx::Mac}. The suggested alternative is to draw temporarily objects normally and refresh the (affected part of the) window to remove them later.
+    # <div class="wxrb-note">
+    # <b>Note:</b>
+    # <p>This function is not fully supported in all ports, due to the limitations of the underlying drawing model. Notably, {Wx::RasterOperationMode::INVERT} which was commonly used for drawing rubber bands or other moving outlines in the past, is not, and will not, be supported by WXGTK3 and WXOSX. The suggested alternative is to draw temporarily objects normally and refresh the (affected part of the) window to remove them later.
+    # </p>
+    # </div>
     # 
     # It determines how a source pixel (from a pen or brush colour, or source device context if using {Wx::DC#blit}) combines with a destination pixel in the current device context. Text drawing is not affected by this function.
     # See {Wx::RasterOperationMode} enumeration values for more info.
@@ -1268,8 +1388,6 @@ module Wx
   # Simple collection of various font metrics.
   # This object is returned by {Wx::DC#get_font_metrics}.
   # 
-  # === 
-  # 
   # Category:  Device Contexts, Graphics Device Interface (GDI)
   # 
   #