ffi-tk 2009.11.29

data/lib/ffi-tk/command/place.rb

@@ -0,0 +1,91 @@
+module Tk
+  # Geometry manager for fixed or rubber-sheet placement
+  #
+  # The placer is a geometry manager for Tk. It provides simple fixed placement
+  # of windows, where you specify the exact size and location of one window,
+  # called the slave, within another window, called the master.
+  # The placer also provides rubber-sheet placement, where you specify the size
+  # and location of the slave in terms of the dimensions of the master, so that
+  # the slave changes size and location in response to changes in the size of
+  # the master.
+  # Lastly, the placer allows you to mix these styles of placement so that, for
+  # example, the slave has a fixed width and height but is centered inside the
+  # master.
+  module Place
+    # Arrange for the placer to manage the geometry of a +window+.
+    # The remaining arguments consist of a hash that specifies the way in which
+    # +window+'s geometry is managed.
+    # Option may have any of the values accepted by [Place.configure].
+    def self.place(window, options = {})
+      args = options.map{|k,v| ["-#{k}", v] }.flatten
+      Tk.execute_only('place', window, *args)
+    end
+
+    # Query or modify the geometry options of the slave given by window.
+    # If no option is specified, this command returns a list describing the
+    # available options (see Tk_ConfigureInfo for information on the format of
+    # this list).
+    # If option is specified with no value, then the command returns a list
+    # describing the one named option (this list will be identical to the
+    # corresponding sublist of the value returned if no option is specified).
+    # If one or more options are specified, then the command modifies the given
+    # option(s) to have the given value(s); in this case the command returns
+    # nil.
+    def self.configure(window, options = None)
+      if options == None
+        Tk.execute('place', 'configure', window)
+      else
+        Tk.execute_only('place', 'configure', window, options)
+      end
+    end
+
+    def self.forget(window)
+      Tk.execute_only('place', 'forget', window)
+    end
+
+    def self.info(window)
+      info = Tk.execute('place', 'info', window).to_s
+
+      array = info.split.each_slice(2).map{|key, value|
+        case key = key[1..-1].to_sym
+        when :anchor, :in
+          [key, value]
+        when :bordermode
+          [key, value.to_sym]
+        when :height, :width, :x, :y
+          [key, value.to_i]
+        when :relheight, :relwidth, :relx, :rely
+          [key, value.to_f]
+        else
+          raise "Unknown info pair: %p => %p" % [key, value]
+        end
+      }
+
+      Hash[array]
+    end
+
+    def self.slaves(window)
+      Tk.execute('place', 'slaves', window)
+    end
+
+    def place(options = {})
+      Place.place(self, options)
+    end
+
+    def place_configure(options = None)
+      Place.configure(self, options)
+    end
+
+    def place_forget
+      Place.forget(self)
+    end
+
+    def place_info
+      Place.info(self)
+    end
+
+    def place_slaves
+      Place.slaves(self)
+    end
+  end
+end

data/lib/ffi-tk/command/popup.rb

@@ -0,0 +1,14 @@
+module Tk
+  # This procedure posts a menu at a given position on the screen and configures
+  # Tk so that the menu and its cascaded children can be traversed with the
+  # mouse or the keyboard.
+  # +menu+ is the name of a menu widget and +x+ and +y+ are the root coordinates
+  # at which to display the menu.
+  # If +entry+ is omitted, the menu's upper left corner is positioned at the
+  # given point.
+  # Otherwise +entry gives the index of an entry in +menu+ and the menu will be
+  # positioned so that the +entry+ is positioned over the given point.
+  def self.popup(menu, x, y, entry = None)
+    Tk.execute_only(:tk_popup, menu, x, y, entry)
+  end
+end

data/lib/ffi-tk/command/raise.rb

@@ -0,0 +1,25 @@
+module Tk
+  # Change a window's position in the stacking order
+  #
+  # FIXME: this will shadow Kernel#raise, alternatives?
+  module Raise
+    def raise(above = None)
+      Raise.raise(self, above)
+    end
+
+    module_function
+
+    # If the +above+ argument is omitted then the command raises window so that
+    # it is above all of its siblings in the stacking order (it will not be
+    # obscured by any siblings and will obscure any siblings that overlap it).
+    #
+    # If +above+ is specified then it must be the path name of a window that is
+    # either a sibling of window or the descendant of a sibling of window.
+    # In this case the raise command will insert window into the stacking order
+    # just above +above+ or the ancestor of +above+ that is a sibling of
+    # window); this could end up either raising or lowering window.
+    def raise(window, above = None)
+      Tk.execute_only(:raise, window, above)
+    end
+  end
+end

data/lib/ffi-tk/command/scrollable.rb

@@ -0,0 +1,151 @@
+module Tk
+  module Scrollable
+
+    # Returns a list containing two elements.
+    # Each element is a real fraction between 0 and 1; together they describe
+    # the portion of the document's horizontal span that is visible in the
+    # window. For example, if the first element is .2 and the second element is
+    # .6, 20% of the text is off-screen to the left, the middle 40% is visible
+    # in the window, and 40% of the text is off-screen to the right.
+    # The fractions refer only to the lines that are actually visible in the
+    # window: if the lines in the window are all very short, so that they are
+    # entirely visible, the returned fractions will be 0 and 1, even if there
+    # are other lines in the text that are much wider than the window.
+    # These are the same values passed to scrollbars via the -xscrollcommand
+    # option.
+    def xview(index = None)
+      if None == index
+        execute(:xview).to_a(&:to_f)
+      else
+        execute_only(:xview, index)
+      end
+    end
+
+    # Adjusts the view in the window so that fraction of the horizontal span of
+    # the text is off-screen to the left.
+    # Fraction is a fraction between 0 and 1.
+    def xview_moveto(fraction)
+      execute_only(:xview, :moveto, fraction)
+    end
+
+    # This command shifts the view in the window left or right according to
+    # number and what.
+    # What must be units, pages or pixels.
+    # If what is units or pages then number │ must be an integer, otherwise
+    # number may be specified in any of the forms accept│ able to
+    # Tk_GetPixels, such as “2.0c” or “1i” (the result is rounded to the
+    # nearest │ integer value.
+    # If no units are given, pixels are assumed).
+    # If what is units, the │ view adjusts left or right by number
+    # average-width characters on the display; if │ it is pages then the view
+    # adjusts by number screenfuls; if it is pixels then the │ view adjusts by
+    # number pixels.
+    # If number is negative then characters farther to the left become visible;
+    # if it is positive then characters farther to the right become visible.
+    def xview_scroll(number, what)
+      execute_only(:xview, :scroll, number, what)
+    end
+
+    # Returns a list containing two elements, both of which are real fractions
+    # between 0 and 1.
+    # The first element gives the position of the first visible pixel of the
+    # first character (or image, etc) in the top line in the window, relative
+    # to the text as a whole (0.5 means it is halfway through the text, for
+    # example). The second element gives the position of the first pixel just
+    # after the last visible one in the bottom line of the window, relative to
+    # the text as a whole.
+    # These are the same values passed to scrollbars via the -yscrollcommand
+    # option.
+    #
+    # This command makes the first character on the line after the one given by
+    # number visible at the top of the window.
+    # Number must be an integer.
+    # This command used to be used for scrolling, but now it is obsolete.
+    def yview(index = None)
+      if None == index
+        execute(:yview).to_a(&:to_f)
+      else
+        execute_only(:yview, index)
+      end
+    end
+
+
+    # Adjusts the view in the window so that the pixel given by fraction
+    # appears at the top of the top line of the window.
+    # Fraction is a fraction between 0 and 1; 0 indicates the first pixel of
+    # the first character in the text, 0.33 indicates the pixel that is
+    # one-third the way through the text; and so on.
+    # Values close to 1 │ will indicate values close to the last pixel in the
+    # text (1 actually refers to one │ pixel beyond the last pixel), but in
+    # such cases the widget will never scroll │ beyond the last pixel, and so a
+    # value of 1 will effectively be rounded back to │ whatever fraction
+    # ensures the last pixel is at the bottom of the window, and some │ other
+    # pixel is at the top.
+    def yview_moveto(fraction)
+      execute_only(:yview, :moveto, fraction)
+    end
+
+    # This command adjust the view in the window up or down according to number
+    # and what.
+    # What must be units, pages or pixels.
+    # If what is units or pages then number │ must be an integer, otherwise
+    # number may be specified in any of the forms accept│ able to
+    # Tk_GetPixels, such as “2.0c” or “1i” (the result is rounded to the
+    # nearest │ integer value.
+    # If no units are given, pixels are assumed).
+    # If what is units, the │ view adjusts up or down by number lines on the
+    # display; if it is pages then the │ view adjusts by number screenfuls; if
+    # it is pixels then the view adjusts by number │ pixels.
+    # If number is negative then earlier positions in the text become visible;
+    # if it is positive then later positions in the text become visible.
+    def yview_scroll(number, what)
+      execute_only(:yview, :scroll, number, what)
+    end
+
+    # Changes the view in the widget's window to make index visible.
+    #
+    # The widget chooses where index appears in the window:
+    # [1] If index is already visible somewhere in the window then the command
+    #     does nothing.
+    # [2] If index is only a few lines off-screen above the window then it will
+    #     be positioned at the top of the window.
+    # [3] If index is only a few lines off-screen below the window then it will
+    #     be positioned at the bottom of the window.
+    # [4] Otherwise, index will be centered in the window.
+    #
+    # The [yview_pickplace] method has been obsoleted by the [see] method.
+    # [see] handles both x- and y-motion to make a location visible, whereas the
+    # [yview_pickplace] mode only handles motion in y).
+    def yview_pickplace(index)
+      execute(:yview, '-pickplace', index)
+    end
+
+    def yscrollbar(sbar)
+      @yscrollbar = sbar
+      @yscrollbar.orient :vertical
+
+      self.yscrollcommand {|*arg| @yscrollbar.set(*arg); true }
+      @yscrollbar.command {|action,fraction| self.yview_moveto(fraction) }
+      @yscrollbar
+    end
+
+    def xscrollbar(sbar)
+      @xscrollbar = sbar
+      @xscrollbar.orient :horizontal
+
+      self.xscrollcommand {|*arg| @xscrollbar.set(*arg); true }
+      @xscrollbar.command {|action,fraction| self.xview_moveto(fraction) }
+      @xscrollbar
+    end
+
+    def xscrollcommand(&block)
+      configure(:xscrollcommand => block) if block
+    end
+
+    def yscrollcommand(&block)
+      configure(:yscrollcommand => block) if block
+    end
+
+  end
+end
+

data/lib/ffi-tk/command/selection.rb

@@ -0,0 +1,132 @@
+module Tk
+  # This command provides a Tcl interface to the X selection mechanism and
+  # implements the full selection functionality described in the X Inter-Client
+  # Communication Conventions Manual (ICCCM).
+  #
+  # Note that for management of the CLIPBOARD selection (see below), the
+  # clipboard command may also be used.
+  module Selection
+    def selection_clear(options = {})
+      Selection.clear({displayof: self}.merge(options))
+    end
+
+    def selection_get(options = {})
+      Selection.get({displayof: self}.merge(options))
+    end
+
+    def selection_handle(options = {}, &command)
+      Selection.handle(self, options, &command)
+    end
+
+    def selection_own(options, &command)
+      Selection.own(self, options, &command)
+    end
+
+    module_function
+
+    # If selection exists anywhere on window's display, clear it so that no
+    # window owns the selection anymore.
+    # Selection specifies the X selection that should be cleared, and should be
+    # an atom name such as PRIMARY or CLIPBOARD; see the Inter-Client
+    # Communication Conventions Manual for complete details.
+    # Selection defaults to PRIMARY and window defaults to ".".
+    def clear(options = {})
+      Tk.execute_only(:selection, :clear, options.to_tcl_options)
+    end
+
+    # Retrieves the value of selection from window's display and returns it as a
+    # result. Selection defaults to PRIMARY and window defaults to “.”.
+    # Type specifies the form in which the selection is to be returned (the
+    # desired “target” for conversion, in ICCCM terminology), and should be
+    # an atom name such as STRING or FILE_NAME; see the Inter-Client
+    # Communication Conventions Manual for complete details.
+    # Type defaults to STRING.
+    # The selection owner may choose to return the selection in any of several
+    # different representation formats, such as STRING, UTF8_STRING, ATOM,
+    # INTEGER, etc.
+    # (this format is different than the selection type; see the ICCCM for all
+    # the confusing details).
+    # If the selection is returned in a non-string format, such as INTEGER or
+    # ATOM, the selection command converts it to string format as a collection
+    # of fields separated by spaces: atoms are converted to their textual names,
+    # and anything else is converted to hexadecimal integers.
+    # Note that selection get does not retrieve the selection in the UTF8_STRING
+    # format unless told to.
+    def get(options = {})
+      Tk.execute(:selection, :get, options.to_tcl_options).to_s
+    end
+
+    # Creates a handler for selection requests, such that command will be
+    # executed whenever selection s is owned by window and someone attempts to
+    # retrieve it in the form given by type t (e.g.
+    # t is specified in the selection get command).
+    # S defaults to PRIMARY, t defaults to STRING, and f defaults to STRING.
+    # If command is an empty string then any existing handler for window, t, and
+    # s is removed.
+    # Note that when the selection is handled as type STRING it is also
+    # automatically handled as type UTF8_STRING as well.
+    #
+    # When selection is requested, window is the selection owner, and type is
+    # the requested type, command will be executed as a Tcl command with two
+    # additional numbers appended to it (with space separators).
+    # The two additional numbers are offset and maxChars: offset specifies a
+    # starting character position in the selection and maxChars gives the
+    # maximum number of characters to retrieve.
+    # The command should return a value consisting of at most maxChars of the
+    # selection, starting at position offset.
+    # For very large selections (larger than maxChars) the selection will be
+    # retrieved using several invocations of command with increasing offset
+    # values. If command returns a string whose length is less than maxChars,
+    # the return value is assumed to include all of the remainder of the
+    # selection; if the length of command's result is equal to maxChars then
+    # command will be invoked again, until it eventually returns a result
+    # shorter than maxChars.
+    # The value of maxChars will always be relatively large (thousands of
+    # characters). If command returns an error then the selection retrieval is
+    # rejected just as if the selection did not exist at all.
+    # The format argument specifies the representation that should be used to
+    # transmit the selection to the requester (the second column of Table 2 of
+    # the ICCCM), and defaults to STRING.
+    #
+    # If format is STRING, the selection is transmitted as 8-bit ASCII
+    # characters (i.e. just in the form returned by command, in the system
+    # encoding; the UTF8_STRING format always uses UTF-8 as its encoding).
+    #
+    # If format is ATOM, then the return value from command is divided into
+    # fields separated by white space; each field is converted to its atom
+    # value, and the 32-bit atom value is transmitted instead of the atom name.
+    # For any other format, the return value from command is divided into fields
+    # separated by white space and each field is converted to a 32-bit integer;
+    # an array of integers is transmitted to the selection requester.
+    #
+    # The format argument is needed only for compatibility with selection
+    # requesters that do not use Tk.
+    # If Tk is being used to retrieve the selection then the value is converted
+    # back to a string at the requesting end, so format is irrelevant.
+    def handle(window, options = {}, &command)
+      command = register_command(:selection_handle, &command)
+      Tk.execute_only(options.to_tcl_options, window, command)
+    end
+
+    # The first form of selection own returns the path name of the window in
+    # this application that owns selection on the display containing window, or
+    # an empty string if no window in this application owns the selection.
+    # Selection defaults to PRIMARY and window defaults to ".".
+    def own(window = None, options = {}, &command)
+      if window == None
+        Tk.execute(:selection, :own)
+      elsif window.is_a?(Hash)
+        options = window
+
+        if cmd = (options[:command] || command)
+          command = register_command(:selection_own, &cmd)
+          Tk.execute(:selection, :own, {command: command}.merge(options).to_tcl_options)
+        else
+          Tk.execute(:selection, :own, options.to_tcl_options)
+        end
+      else
+        Tk.execute(:selection, :own, options.to_tcl_options, window)
+      end
+    end
+  end
+end

data/lib/ffi-tk/command/set_palette.rb

@@ -0,0 +1,9 @@
+module Tk
+  def self.set_palette(background, *rest)
+    if rest.empty?
+      Tk.execute(:tk_setPalette, background)
+    else
+      Tk.execute(:tk_setPalette, background, *rest)
+    end
+  end
+end

data/lib/ffi-tk/command/tk_cmd.rb

@@ -0,0 +1,155 @@
+# Manipulate Tk internal state
+module Tk
+  module TkCmd
+    # @see TkCmd.appname
+    def tk_appname
+      TkCmd.appname(self)
+    end
+
+    # @see TkCmd.appname
+    def tk_appname=(new_name)
+      TkCmd.appname(self, new_name)
+    end
+
+    # @see TkCmd.caret
+    def tk_caret(options = None)
+      TkCmd.caret(self, options)
+    end
+
+    # @see TkCmd.scaling
+    def tk_scaling
+      TkCmd.scaling(None, self)
+    end
+
+    # @see TkCmd.scaling
+    def tk_scaling=(number)
+      TkCmd.scaling(number, self)
+    end
+
+    # @see TkCmd.inactive
+    def tk_inactive(reset = None)
+      TkCmd.inactive(reset, self)
+    end
+
+    # @see TkCmd.useinputmethods
+    def tk_useinputmethods
+      TkCmd.useinputmethods(None, self)
+    end
+
+    # @see TkCmd.useinputmethods
+    def tk_useinputmethods=(boolean)
+      TkCmd.useinputmethods(boolean, self)
+    end
+
+    def tk_windowingsystem
+      TkCmd.windowingsystem
+    end
+
+    module_function
+
+    # If newName is not specified, this command returns the name of the
+    # application (the name that may be used in send commands to communicate
+    # with the application).
+    # If newName is specified, then the name of the application is changed to
+    # newName. If the given name is already in use, then a suffix of the form “
+    # #2” or “ #3” is appended in order to make the name unique.
+    # The command's result is the name actually chosen.
+    # newName should not start with a capital letter.
+    # This will interfere with option processing, since names starting with
+    # capitals are assumed to be classes; as a result, Tk may not be able to
+    # find some options for the application.
+    # If sends have been disabled by deleting the send command, this command
+    # will reenable them and recreate the send command.
+    def appname(new_name = None)
+      Tk.execute(:tk, :appname, new_name)
+    end
+
+    # Sets and queries the caret location for the display of the specified Tk
+    # window window.
+    # The caret is the per-display cursor location used for indicating global
+    # focus (e.g.
+    # to comply with Microsoft Accessibility guidelines), as well as for
+    # location of the over-the-spot XIM (X Input Methods) or Windows IME
+    # windows. If no options are specified, the last values used for setting
+    # the caret are return in option-value pair format.
+    # -x and -y represent window-relative coordinates, and -height is the
+    # height of the current cursor location, or the height of the specified
+    # window if none is given.
+    def caret(window, options = None)
+      if None == options
+        Tk.execute(:tk, :caret, window).tcl_options_to_hash
+      else
+        Tk.execute_only(:tk, :caret, window, options.to_tcl_options)
+      end
+    end
+
+    # Sets and queries the current scaling factor used by Tk to convert between
+    # physical units (for example, points, inches, or millimeters) and pixels.
+    # The number argument is a floating point number that specifies the
+    # number of pixels per point on window's display.
+    # If the window argument is omitted, it defaults to the main window.
+    # If the number argument is omitted, the current value of the scaling
+    # factor is returned.
+    # A “point” is a unit of measurement equal to 1/72 inch.
+    # A scaling factor of 1.0 corresponds to 1 pixel per point, which is
+    # equivalent to a standard 72 dpi monitor.
+    # A scaling factor of 1.25 would mean 1.25 pixels per point, which is the
+    # setting for a 90 dpi monitor; setting the scaling factor to 1.25 on a 72
+    # dpi monitor would cause everything in the application to be displayed
+    # 1.25 times as large as normal.
+    # The initial value for the scaling factor is set when the application
+    # starts, based on properties of the installed monitor, but it can be
+    # changed at any time.
+    # Measurements made after the scaling factor is changed will use the new
+    # scaling factor, but it is undefined whether existing widgets will resize
+    # themselves dynamically to accommodate the new scaling factor.
+    def scaling(number = None, window = None)
+      if None == window
+        Tk.execute(:tk, :scaling, number)
+      else
+        Tk.execute(:tk, :scaling, '-displayof', window, number)
+      end
+    end
+
+    # Returns a positive integer, the number of milliseconds since the last
+    # time the user interacted with the system.
+    # If the -displayof option is given then the return value refers to the
+    # display of window; otherwise it refers to the display of the
+    # application's main window.
+    # tk inactive will return -1, if querying the user inactive time is not
+    # supported by the system, and in safe interpreters.
+    # If the literal string reset is given as an additional argument, the timer
+    # is reset and an empty string is returned.
+    # Resetting the inactivity time is forbidden in safe interpreters and will
+    # throw and error if tried.
+    def inactive(reset = None, window = None)
+      if None == window
+        Tk.execute(:tk, :inactive, reset)
+      else
+        Tk.execute(:tk, :inactive, '-displayof', window, reset)
+      end
+    end
+
+    # Sets and queries the state of whether Tk should use XIM (X Input Methods)
+    # for filtering events.
+    # The resulting state is returned.
+    # XIM is used in some locales (i.e., Japanese, Korean), to handle special
+    # input devices.
+    # This feature is only significant on X.
+    # If XIM support is not available, this will always return 0.
+    # If the window argument is omitted, it defaults to the main window.
+    # If the boolean argument is omitted, the current state is returned.
+    # This is turned on by default for the main display.
+    def useinputmethods(boolean = None, window = None)
+      if None == window
+        Tk.execute(:tk, :useinputmethods, boolean ? true : false)
+      else
+        Tk.execute(:tk, :useinputmethods, '-displayof', window, boolean ? true : false)
+      end
+    end
+
+    def windowingsystem
+      Tk.execute(:tk, :windowingsystem).to_sym
+    end
+  end
+end