iup-ffi 0.13.0-x86_64-linux

data/lib/wrapped/canvas.rb

@@ -0,0 +1,698 @@
+module Iup
+
+  # A canvas is a working area for the application.  The API documentation
+  # can only hint at the use of this control. For more information see
+  # Tecgraf's documentation on the
+  # {Canvas}[https://www.tecgraf.puc-rio.br/iup/en/elem/iupcanvas.html] and
+  # on the {CD graphics library}[https://www.tecgraf.puc-rio.br/cd/], from
+  # which many of the drawing commands and primitives are taken, 
+  # documented under {CD drawing}[#CD+drawing].
+  #
+  # === Example
+  #
+  # In the following example, notice how the canvas is placed 
+  # in a dialog, which is mapped, and then #init is called on the 
+  # canvas before the dialog is shown.
+  #
+  #   class MyCanvas < Iup::Canvas
+  #     def initialize
+  #       super()
+  #   
+  #       self.scrollbar = 'yes' # explicit receivers are needed in subclass
+  #       self.xmax = 599
+  #       self.ymax = 399
+  #   
+  #       self.scroll_cb = ->(op, posx, posy){ # redraw on scroll
+  #         redraw(posx, posy)
+  #         Iup::DEFAULT
+  #       }
+  #   
+  #       self.resize_cb = ->(w, h){ # redraw on resize
+  #         self.dx = w
+  #         self.dy = h
+  #         activate # redraws the canvas
+  #         Iup::DEFAULT
+  #       }
+  #   
+  #       self.action = ->(posx, posy){ # called to redraw canvas
+  #         redraw(posx, posy)
+  #       }
+  #     end
+  #   
+  #     def redraw(posx, posy) # the redraw logic, uses some CD commands
+  #       iposx = posx.to_i
+  #       iposy = posy.to_i
+  #       # invert scroll reference (YMAX-DY - POSY)
+  #       iposy = 399-dy - iposy
+  #   
+  #       clear
+  #       self.foreground = Iup::CD_RED
+  #       line(0-iposx, 0-iposy, 599-iposx, 399-iposy)
+  #       line(0-iposx, 399-iposy, 599-iposx, 0-iposy)
+  #   
+  #       Iup::DEFAULT
+  #     end 
+  #   end
+  #   
+  #   Iup.mainloop do 
+  #     canvas = MyCanvas.new do |c| # 1. make the canvas
+  #       c.rastersize = '300x200'
+  #     end
+  #                      
+  #     dialog = Iup::Dialog.new(canvas) do |d| # 2. put it in a dialog
+  #       d.title = 'Scrollbar Test'
+  #     end.map # 3. map the dialog
+  #   
+  #     canvas.init # 4. init the canvas
+  #     canvas.rastersize = nil # release the minimum limitation
+  #   
+  #     dialog.show # 5. show the dialog
+  #   end
+  # 
+  # Also see BackgroundBox.
+  #
+  class Canvas < Iup::Widget 
+    include DragDropAttributes 
+    include ScrollBarAttributes
+
+    # Creates a new instance.
+    # If a block is given, the new instance is yielded to it.
+    # * +handle+ - an optional Canvas handle.
+    def initialize(handle = IupLib.IupCanvas(''))
+      @handle = handle
+
+      # run any provided block on instance, to set up further attributes
+      yield self if block_given?
+    end
+
+    # :category: CD drawing
+    # This must be called after the widget is mapped, to create and
+    # setup the canvas.
+    def init
+      @canvas = CdLib.cdCreateCanvas(CdLib.cdContextIup, @handle)
+    end
+
+    # -- attributes
+
+    ##
+    # :attr: border
+    # Sets border around canvas, values 'yes' / 'no'.
+    define_attribute :border
+
+    ##
+    # :attr: canfocus
+    # Enables the control to gain focus. Values 'yes' / 'no'.
+    define_attribute :canfocus
+
+    ##
+    # :attr: cursor
+    # Defines the mouse shape / cursor for the canvas.
+    # Available cursors are shown in the
+    # {Tecgraf documentation}[http://www.tecgraf.puc-rio.br/iup/en/attrib/iup_cursor.html].
+    define_attribute :cursor
+
+    ##
+    # :attr: drawsize
+    # Size of the drawing area in pixels, as "widthxheight".
+    define_attribute :drawsize
+
+    ##
+    # :attr: expand
+    # Allows canvas to fill available space in indicated direction.
+    # Values 'no' / 'horizontal' / 'vertical' / 'yes'.
+    define_attribute :expand
+
+    ##
+    # :attr: padding
+    # Margin in x and y directions, value as "mxn".
+    define_attribute :padding
+
+    ##
+    # :attr_reader: position
+    # returns position in pixels within client window as "x,y".
+    define_reader :position
+
+    ##
+    # :attr: rastersize
+    # Size of the canvas, in pixels, value as "widthxheight".
+    define_attribute :rastersize
+
+    ##
+    # :attr_reader: screenposition
+    # returns position in pixels on screen
+    define_reader :screenposition
+
+    ##
+    # :attr: tip
+    # Tooltip string.
+    define_attribute :tip
+
+    # redraws the underlying canvas.
+    def redraw
+      IupLib.IupRedraw @handle
+    end
+
+    # -- CD method calls
+ 
+    # :section: CD drawing
+
+    # --- initialisation
+
+    # call when canvas no longer needed.
+    def kill
+      CdLib.cdKillCanvas @canvas
+    end
+
+    # call to activate canvas. 
+    # (Not usually needed - depends on driver.)
+    def activate
+      CdLib.cdCanvasActivate @canvas
+    end
+
+    # call to deactivate canvas. 
+    # (Not usually needed - depends on driver.)
+    def deactivate
+      CdLib.cdCanvasDeactivate @canvas
+    end
+
+    # Used to set coordinates of a viewport (the canvas coordinates).
+    def viewport x1, y1, x2, y2
+      CdLib.wdCanvasViewport @canvas, x1, y1, x2, y2
+    end
+
+    # Used to set coordinates of a window (the world coordinates).
+    def window x1, y1, x2, y2
+      CdLib.wdCanvasWindow @canvas, x1, y1, x2, y2
+    end
+
+    # --- general attributes
+
+    ##
+    # :attr: foreground
+    # Accesses the foreground color.
+    #
+    # Color may be one of:
+    # * string, in form "r g b"
+    # * color constant, e.g. CD_BLACK, as listed in {CD colors}[../Iup.html#CD+colors]
+
+    #--
+    def foreground
+      CdLib.cdCanvasForeground(@canvas, Iup::CD_QUERY)
+    end
+
+    def foreground= color # :nodoc:
+      case color
+      when String # assume in form 'RR GG BB'
+        r, g, b = color.split(' ').collect(&:to_i)
+        CdLib.cdCanvasForeground(@canvas, CdLib.cdEncodeColor(r, g, b))
+      else
+        CdLib.cdCanvasForeground(@canvas, color)
+      end
+    end
+
+    ##
+    # :category: CD drawing
+    # :attr: background
+    # Accesses the background color.
+    #
+    # Color may be one of:
+    # * string, in form "r g b"
+    # * color constant, e.g. CD_BLACK, as listed in {CD colors}[../Iup.html#CD+colors]
+
+    # --
+    def background
+      CdLib.cdCanvasBackground(@canvas, Iup::CD_QUERY)
+    end
+
+    def background= color # :nodoc:
+      case color
+      when String # assume in form 'RR GG BB'
+        r, g, b = color.split(' ').collect(&:to_i)
+        CdLib.cdCanvasBackground(@canvas, CdLib.cdEncodeColor(r, g, b))
+      else
+        CdLib.cdCanvasBackground(@canvas, color)
+      end
+    end
+
+    ##
+    # :attr: writemode
+    # Accesses. the writing mode for all primitives. 
+    # See {CD write mode}[../Iup.html#CD+write+mode] for a list of available values.
+
+    # --
+    def writemode
+      CdLib.cdCanvasWriteMode(@canvas, Iup::CD_QUERY)
+    end
+
+    def writemode= mode # :nodoc:
+      CdLib.cdCanvasWriteMode(@canvas, mode)
+    end
+
+    # --- control
+
+    # Clears the canvas.
+    def clear
+      CdLib.cdCanvasClear @canvas
+    end
+
+
+    # --- begin/end blocks
+
+    # Begin the definition of a sequence of vertices to define a polygon.
+    # See {CD polygon mode}[../Iup.html#CD+polygon+mode] for polygon mode
+    # values.
+    #
+    # Filled polygons are defined using #begin_block, multiple calls to
+    # #vertex, and ended with #end_block.
+    def begin_block mode
+      CdLib.cdCanvasBegin @canvas, mode
+    end
+
+    # Specify a vertex at position (x, y).
+    # See #begin_block.
+    def vertex x, y
+      CdLib.cdCanvasVertex @canvas, x, y
+    end
+
+    # End the definition of a sequence of vertices.
+    # See #begin_block.
+    def end_block 
+      CdLib.cdCanvasEnd @canvas
+    end
+
+    # Specify action for next point on path.
+    # See {CD path action}[../Iup.html#CD+path+action] for path actions.
+    def pathset action
+      CdLib.cdCanvasPathSet @canvas, action
+    end
+
+    # --- marks
+
+    # Configures pixel (x, y) with color.
+    def pixel x, y, color
+      CdLib.cdCanvasPixel @canvas, x, y, color
+    end
+
+    # Draws a mark at position (x, y).
+    def mark x, y
+      CdLib.cdCanvasMark @canvas, x, y
+    end
+
+    ##
+    # :attr: marktype
+    # Accesses the marktype to display.
+    # See {CD mark type}[../Iup.html#CD+mark+type] for available marktype values.
+
+    # --
+    def marktype
+      CdLib.cdCanvasMarkType(@canvas, Iup::CD_QUERY)
+    end
+
+    def marktype= type # :nodoc:
+      CdLib.cdCanvasMarkType(@canvas, type)
+    end
+
+    ##
+    # :attr: marksize
+    # Accesses the mark size, given in pixels. Must be >= 1, default is 10.
+
+    # --
+    def marksize
+      CdLib.cdCanvasMarkSize(@canvas, Iup::CD_QUERY)
+    end
+
+    def marksize= size # :nodoc:
+      CdLib.cdCanvasMarkSize(@canvas, size)
+    end
+
+    # --- lines
+
+    # Draws a line from (x1, y1) to (x2, y2).
+    def line x1, y1, x2, y2
+      CdLib.cdCanvasLine @canvas, x1, y1, x2, y2
+    end
+
+    # Draws a rectangle bounding (xmin, ymin) to (xmax, ymax).
+    def rectangle xmin, xmax, ymin, ymax
+      CdLib.cdCanvasRect @canvas, xmin, xmax, ymin, ymax
+    end
+
+    # Draws an arc of an ellipse - a pie-shaped slice.
+    # Angles are in degrees, counterclockwise.
+    def arc xc, yc, w, h, angle1, angle2
+      CdLib.cdCanvasArc @canvas, xc, yc, w, h, angle1, angle2
+    end
+
+    ##
+    # :attr: linestyle
+    # Accesses linestyle value.
+    # See {CD line style}[../Iup.html#CD+line+style] for available linestyle values.
+
+    # --
+    def linestyle
+      CdLib.cdCanvasLineStyle(@canvas, Iup::CD_QUERY)
+    end
+
+    def linestyle= style # :nodoc:
+      CdLib.cdCanvasLineStyle(@canvas, style)
+    end
+
+    ##
+    # :attr: linewidth
+    # Accesses linewidth, in pixels.
+
+    # --
+    def linewidth
+      CdLib.cdCanvasLineWidth(@canvas, Iup::CD_QUERY)
+    end
+
+    def linewidth= width # :nodoc:
+      CdLib.cdCanvasLineWidth(@canvas, width)
+    end
+
+    ##
+    # :attr: linejoin
+    # Accesses linejoin value.
+    # See {CD line join}[../Iup.html#CD+line+join] for available linejoin values.
+
+    # --
+    def linejoin
+      CdLib.cdCanvasLineJoin(@canvas, Iup::CD_QUERY)
+    end
+
+    def linejoin= style # :nodoc:
+      CdLib.cdCanvasLineJoin(@canvas, style)
+    end
+
+    ##
+    # :attr: linecap
+    # Accesses linecap value.
+    # See {CD line cap}[../Iup.html#CD+line+cap] for available linecap values.
+
+    # --
+    def linecap
+      CdLib.cdCanvasLineCap(@canvas, Iup::CD_QUERY)
+    end
+
+    def linecap= style # :nodoc:
+      CdLib.cdCanvasLineCap(@canvas, style)
+    end
+
+    # -- filled areas
+
+    # Fills a rectangle, according to current interior style.
+    def box xmin, xmax, ymin, ymax
+      CdLib.cdCanvasBox @canvas, xmin, xmax, ymin, ymax
+    end
+
+    # Fills a sector, according to current interior style.
+    # A sector is an arc of an ellipse - a pie-shaped slice.
+    # Angles are in degrees, counterclockwise.
+    def sector xc, yc, w, h, angle1, angle2
+      CdLib.cdCanvasSector @canvas, xc, yc, w, h, angle1, angle2
+    end
+
+    # Fills a chord, according to current interior style.
+    # A chord is an arc of an ellipse - with the arc points connected.
+    # Angles are in degrees, counterclockwise.
+    def chord xc, yc, w, h, angle1, angle2
+      CdLib.cdCanvasChord @canvas, xc, yc, w, h, angle1, angle2
+    end
+
+    ##
+    # :attr: backopacity
+    # Accesses backopacity value.
+    # See {CD background opacity mode}[../Iup.html#CD+background+opacity+mode]
+    # for background opacity mode values.
+    
+    # --
+    def backopacity
+      CdLib.cdCanvasBackOpacity(@canvas, Iup::CD_QUERY)
+    end
+
+    def backopacity= opacity # :nodoc:
+      CdLib.cdCanvasBackOpacity(@canvas, opacity)
+    end
+
+    ##
+    # :attr: fillmode
+    # Accesses fillmode value.
+    # See {CD fill mode}[../Iup.html#CD+fill+mode] for fill mode values.
+    
+    # --
+    def fillmode 
+      CdLib.cdCanvasFillMode(@canvas, Iup::CD_QUERY)
+    end
+
+    def fillmode= mode # :nodoc:
+      CdLib.cdCanvasFillMode(@canvas, mode)
+    end
+
+    ##
+    # :attr: interiorstyle
+    # Accesses interiorstyle value.
+    # See {CD interior style}[../Iup.html#CD+interior+style] for interior style values.
+
+    # --
+    def interiorstyle
+      CdLib.cdCanvasInteriorStyle(@canvas, Iup::CD_QUERY)
+    end
+
+    def interiorstyle= style # :nodoc:
+      CdLib.cdCanvasInteriorStyle(@canvas, style)
+    end
+
+    ##
+    # :attr: hatch
+    # Accesses hatch value.
+    # See {CD hatch type}[../Iup.html#CD+hatch+type] for hatch style values.
+
+    # --
+    def hatch
+      CdLib.cdCanvasHatch(@canvas, Iup::CD_QUERY)
+    end
+
+    def hatch= style # :nodoc:
+      CdLib.cdCanvasHatch(@canvas, style)
+    end
+
+    # Defines a stipple pattern of a specified size:
+    # * +w+ - width of stipple pattern
+    # * +h+ - height of stipple pattern
+    # * +fgbg+ - a string representing the stipple pattern in binary
+    def stipple w, h, fgbg
+      CdLib.cdCanvasStipple @canvas, w, h, fgbg
+    end
+
+    # -- text
+
+    # Draw text str at position (x, y). Expects an ANSI-string.
+    def text x, y, str
+      CdLib.cdCanvasText @canvas, x, y, str
+    end
+
+    # Sets text font.
+    # * +typeface+ - 'Courier', 'Helvetica', 'Times' built-in, but any known font can be used
+    # * +style+ - see {CD text style}[../Iup.html#CD+text+style]
+    # * +size+ - the font height, default is 12.
+    def font typeface, style, size
+      CdLib.cdCanvasFont @canvas, typeface, style, size
+    end
+
+    ##
+    # :attr_writer: nativefont
+    # Sets the current font.
+
+    # --
+    def nativefont= font
+      CdLib.cdCanvasNativefont(@canvas, font)
+    end
+
+    ##
+    # :attr: textalignment
+    # Accesses the textalignment value.
+    # See {CD text alignment}[../Iup.html#CD+text+alignment].
+
+    # --
+    def textalignment 
+      CdLib.cdCanvasTextAlignment(@canvas, Iup::CD_QUERY)
+    end
+
+    def textalignment= alignment # :nodoc:
+      CdLib.cdCanvasTextAlignment(@canvas, alignment)
+    end
+
+    ##
+    # :attr: textorientation
+    # Accesses the textorientation value.
+    # The orientation is an angle in degrees to the horizontal.
+
+    # --
+    def textorientation 
+      CdLib.cdCanvasTextOrientation(@canvas, Iup::CD_QUERY)
+    end
+
+    def textorientation= orientation # :nodoc:
+      CdLib.cdCanvasTextOrientation(@canvas, orientation)
+    end
+
+    # -- vector text
+
+    # Draws str as vector text at position (x, y).
+    # Call #vectortext_size to set the text size before calling this method.
+    def vectortext x, y, str
+      CdLib.cdCanvasVectorText @canvas, x, y, str
+    end
+
+    # Defines the text direction using two points: (x1, y1) and (x2, y2).
+    def vectortext_direction x1, y1, x2, y2
+      CdLib.cdCanvasVectorTextDirection @canvas, x1, y1, x2, y2
+    end
+
+    # Modifies font size so str fits within a box width x height in size.
+    def vectortext_size width, height, str
+      CdLib.cdCanvasVectorTextSize @canvas, width, height, str
+    end
+
+    ##
+    # :attr: vectortext_charsize
+    # The font size.
+
+    # --
+    def vectortext_charsize
+      CdLib.cdCanvasVectorCharSize(@canvas, Iup::CD_QUERY)
+    end
+
+    def vectortext_charsize= size # :nodoc:
+      CdLib.cdCanvasVectorCharSize(@canvas, size)
+    end
+
+    # Directly modifies the font size.
+    def vectortext_fontsize size_x, size_y
+      CdLib.cdCanvasVectorFontSize @canvas, size_x, size_y
+    end
+
+    # Replaces current vector font with that loaded from given filename.
+    # Returns the font name, or null.
+    def vectortext_loadfont filename
+      CdLib.cdCanvasVectorFont @canvas, filename
+    end
+
+    # :section: Callbacks
+
+    ##
+    # :attr_writer: action
+    # Callback called when the canvas needs to be redrawn.
+    # Callback must respond to +call+ and accepts 2 arguments: (posx, posy)
+    # * +posx+ - position of horizonal scrollbar thumb
+    # * +posy+ - position of vertical scrollbar thumb
+    #
+    # Typically redraws canvas: see {CD drawing}[#CD+drawing].
+
+    # --
+    def action= callback
+      unless callback.arity == 2
+        raise ArgumentError, 'action must take 2 arguments: (posx, posy)'
+      end
+      cb = Proc.new do |ih, posx, posy|
+        callback.call posx, posy
+      end
+      define_callback cb, 'ACTION', :ff_i
+    end
+
+    include ButtonCallback
+
+    ##
+    # :attr_writer: focus_cb
+    # Callback called when the canvas gets or loses the keyboard focus.
+    # Callback must respond to +call+ and takes a single parameter: (focus)
+    # * +focus+ - non-zero if canvas gaining focus, else zero.
+
+    # --
+    def focus_cb= callback
+      unless callback.arity == 1
+        raise ArgumentError, 'focus_cb callback must take 1 argument, the focus'
+      end
+      cb = Proc.new do |ih, focus|
+        callback.call focus
+      end
+      define_callback cb, 'FOCUS_CB', :i_i
+    end
+
+    ##
+    # :attr_writer: keypress_cb
+    # Callback called when a key is pressed or released.
+    # Callback must respond to +call+ and takes a 2-argument callback: (character, pressed).
+    # * +character+ - code for character pressed/released
+    # * +pressed+ - 1 if key is pressed, 0 if released
+
+    # --
+    def keypress_cb= callback
+      unless callback.arity == 2
+        raise ArgumentError, 'keypress_cb callback must take 2 arguments: (char, press)'
+      end
+      cb = Proc.new do |ih, char, press|
+        callback.call char, press
+      end
+      define_callback cb, 'KEYPRESS_CB', :ii_i
+    end
+
+    ##
+    # :attr_writer: motion_cb
+    # Callback called when the mouse is moved.
+    # Callback must respond to +call+ and takes 3 arguments: (x, y, state)
+    # * +x+ - x position of mouse
+    # * +y+ - y position of mouse
+    # * +state+ - status of mouse buttons and certain keyboard keys at the moment the event was generated.
+
+    #--
+    def motion_cb= callback
+      unless callback.arity == 3
+        raise ArgumentError, 'motion_cb callback must take 3 arguments: (x, y, state)'
+      end
+      cb = Proc.new do |ih, x, y, state|
+        callback.call x, y, state
+      end
+      define_callback cb, 'MOTION_CB', :iis_i
+    end
+
+    ##
+    # :attr_writer: resize_cb
+    # Callback called when the canvas size is changed.
+    # Callback must respond to +call+ and takes 2 arguments: (width, height).
+    # * +width+ -internal width of canvas (client width)
+    # * +height+ - internal height of canvas (client height)
+
+    # --
+    def resize_cb= callback # :nodoc:
+      unless callback.arity == 2
+        raise ArgumentError, 'resize_cb callback must take 2 arguments: (width, height)'
+      end
+      cb = Proc.new do |ih, width, height|
+        callback.call width, height
+      end
+      define_callback cb, 'RESIZE_CB', :ii_i
+    end
+
+    ##
+    # :attr_writer: wheel_cb
+    # Callback called when the mouse wheel is rotated.
+    # Callback must respond to +call+ and accepts a 4-argument callback: (delta, x, y, status).
+    # * +delta+ - the amount the wheel was rotated in notches.
+    # * +x+ - x position in the canvas where the event has occurred, in pixels.
+    # * +y+ - y position in the canvas where the event has occurred, in pixels.
+    # * +status+ - status of mouse buttons and certain keyboard keys at the moment the event was generated.
+
+    # --
+    def wheel_cb= callback
+      unless callback.arity == 4
+        raise ArgumentError, 'wheel_cb callback must take 4 arguments: (delta, x, y, status)'
+      end
+      cb = Proc.new do |ih, delta, x, y, status_ptr|
+        status = FFI::Pointer.new(status_ptr).read_string
+        callback.call delta, x, y, status
+      end
+      define_callback cb, 'WHEEL_CB', :fiis_i
+    end
+  end
+end