ffi-tk 2009.11.29

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

@@ -0,0 +1,70 @@
+module Tk
+  # Utility methods for managing the input focus.
+  module Focus
+    module_function
+
+    def focus(window = None, option = None)
+      if window == None
+        Tk.execute('focus')
+      else
+        case option
+        when None
+          Tk.execute('focus', window)
+        when :displayof
+          Tk.execute('focus', '-displayof', window)
+        when :force
+          Tk.execute_only('focus', '-force', window)
+        when :lastfor
+          Tk.execute('focus', '-lastfor', window)
+        else
+          raise ArgumentError, "option must be one of: None, :displayof, :force, :lastfor"
+        end
+      end
+    end
+
+    # This method changes the focus model for the application to an implicit one
+    # where the window under the mouse gets the focus.
+    # After this method is called, whenever the mouse enters a window Tk will
+    # automatically give it the input focus.
+    # The focus command may be used to move the focus to a window other than the
+    # one under the mouse, but as soon as the mouse moves into a new window the
+    # focus will jump to that window.
+    #
+    # Note: at present there is no built-in support for returning the
+    # application to an explicit focus model; to do this you will have to write
+    # a script that deletes the bindings created by tk_focusFollowsMouse.
+    def follows_mouse
+      Tk.execute_only(:tk_focusFollowsMouse)
+    end
+
+    # A method used for keyboard traversal.
+    # It returns the "next" window after +window+ in focus order.
+    #
+    # The focus order is determined by the stacking order of windows and the
+    # structure of the window hierarchy.
+    # Among siblings, the focus order is the same as the stacking order, with
+    # the lowest window being first.
+    #
+    # If a window has children, the window is visited first, followed by its
+    # children (recursively), followed by its next sibling.
+    #
+    # Top-level windows other than +window+ are skipped, so that it never
+    # returns a window in a different top-level from +window+.
+    #
+    # After computing the next window, it examines the window's :takefocus
+    # option to see whether it should be skipped.
+    #
+    # If so, it continues on to the next window in the focus order, until it
+    # eventually finds a window that will accept the focus or returns back to
+    # window.
+    def next(window)
+      Tk.execute(:tk_focusNext, window)
+    end
+
+    # Similar to [Focus.next], except that it returns the window just before
+    # +window+ in the focus order.
+    def prev(window)
+      Tk.execute(:tk_focusPrev, window)
+    end
+  end
+end

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

@@ -0,0 +1,124 @@
+module Tk
+  # Create and inspect fonts.
+  # The font command provides several facilities for dealing with fonts, such as
+  # defining named fonts and inspecting the actual attributes of a font.
+  class Font
+    def initialize(string_or_hash)
+      if string_or_hash.respond_to?(:to_str)
+        string_or_hash =~ /^(.*)\s+(\d+)?$/
+
+        params = {}
+        params[:family] = $1.to_s
+        params[:size] = $2.to_i if $2
+
+        @font = Font.create(params)
+      elsif string_or_hash.respond_to?(:to_hash)
+        @font = Font.create(string_or_hash)
+      else
+        raise ArgumentError
+      end
+    end
+
+    def actual(options = {})
+      Font.actual(@font, options)
+    end
+
+    def actual_hash(options = {})
+      Font.actual(@font, options)
+    end
+
+    def measure(text, options = {})
+      Font.measure(@font, text, options)
+    end
+
+    def metrics(option, options = {})
+      Font.metrics(@font, option, options)
+    end
+
+    def configure(argument = None)
+      Font.configure(@font, argument)
+    end
+
+    def to_tcl
+      TclString.new(@font)
+    end
+
+    FONT_CONFIGURE_HINTS = {
+      underline:  :boolean,
+      overstrike: :boolean,
+      weight:     :symbol,
+      slant:      :symbol,
+    }
+
+    def self.execute(command, *args)
+      Tk.execute(:font, command, *args)
+    end
+
+    def self.execute_only(command, *args)
+      Tk.execute_only(:font, command, *args)
+    end
+
+    # NOTE:
+    #   the signature has been simplified to a required +font+ argument and a
+    #   simple +options+ hash.
+    #   The original signature is:
+    #     `font actual font ?-displayof window? ?option? ?--? ?char?`
+    #   But it just makes things very painful.
+    # @options
+    #  :displayof window
+    #  :char char
+    #  :option name
+    def self.actual(font, options = {})
+      window = options.fetch(:displayof, None)
+      option = options.fetch(:option, None)
+      char = options.fetch(:char, None)
+
+      args = []
+      args << "-displayof" << window unless window == None
+      args << option.to_tcl_option unless option == None
+      args << "--" << char.to_tcl unless char == None
+
+      array = execute(:actual, font, *args)
+      array.tcl_options_to_hash(FONT_CONFIGURE_HINTS)
+    end
+
+    def self.configure(fontname, argument = None)
+      Configure.common(
+        self, [:configure, fontname], argument, FONT_CONFIGURE_HINTS)
+    end
+
+    def self.create(fontname, options = None)
+      if fontname.respond_to?(:to_tcl_options)
+        fontname, options = None, fontname
+        options = options.to_tcl_options
+      end
+
+      execute(:create, fontname, options)
+    end
+
+    def self.delete(*fontnames)
+      execute(:delete, *fontnames)
+    end
+
+    # The return value is a list of the case-insensitive names of all font
+    # families that exist on window's display.
+    # If the window argument is omitted, it defaults to the main window.
+    def self.families(options = {})
+      execute(:families, options.to_tcl_options)
+    end
+
+    def self.measure(font, text, options = {})
+      execute(:measure, font, options.to_tcl_options, text)
+    end
+
+    def self.metrics(font, option, options = {})
+      execute(:metrics, font, options.to_tcl_options, option.to_tcl_option)
+    end
+
+    # The return value is a list of all the named fonts that are currently
+    # defined.
+    def self.names
+      execute(:names).to_a
+    end
+  end
+end

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

@@ -0,0 +1,85 @@
+module Tk
+  module_function
+
+  # Pop up a dialog box for the user to select a file to open.
+  #
+  # This method is usually associated with the "Open" command in the "File"
+  # menu.
+  # Its purpose is for the user to select an existing file only.
+  # If the user enters a non-existing file, the dialog box gives the user an
+  # error prompt and requires the user to give an alternative selection.
+  # If an application allows the user to create new files, it should do so by
+  # providing a separate "New" command in the "File" menu.
+  #
+  # If a user selects a file, the full pathname of the file is returned.
+  # If the user cancels the dialog, nil is returned.
+  #
+  # The following options may be given:
+  #
+  #   defaultextension: extension
+  #     Specifies a string that will be appended to the filename if the user
+  #     enters a filename without an extension.
+  #     The default value is the empty string, which means no extension will be
+  #     appended to the filename in any case.
+  #     This option is ignored on Mac OS X, which does not require extensions to
+  #     filenames, and the UNIX implementation guesses reasonable values for
+  #     this from the :filetypes option when this is not supplied.
+  #
+  #   filetypes: file_pattern_list
+  #     If a File types listbox exists in the file dialog on the particular
+  #     platform, this option gives the filetypes in this listbox.
+  #     When the user choose a filetype in the listbox, only the files of that
+  #     type are listed.
+  #     If this option is unspecified, or if it is set to the empty list, or if
+  #     the File types listbox is not supported by the particular platform then
+  #     all files are listed regardless of their types.
+  #
+  #   initialdir: directory
+  #     Specifies that the files in directory should be displayed when the
+  #     dialog pops up.
+  #     If this parameter is not specified, then the files in the current
+  #     working directory are displayed.
+  #     If the parameter specifies a relative path, the return value will
+  #     convert the relative path to an absolute path.
+  #
+  #   initialfile: filename
+  #     Specifies a filename to be displayed in the dialog when it pops up.
+  #
+  #   message: string
+  #     Specifies a message to include in the client area of the dialog.
+  #     This is only available on Mac OS X.
+  #
+  #   multiple: boolean
+  #     Allows the user to choose multiple files from the dialog.
+  #
+  #   parent: window
+  #     Makes window the logical parent of the file dialog.
+  #     The file dialog is displayed on top of its parent window.
+  #     On Mac OS X, this turns the file dialog into a sheet attached to the
+  #     parent window.
+  #
+  #   title: string
+  #     Specifies a string to display as the title of the dialog box.
+  #     If this option is not specified, then a default title is displayed.
+  #
+  # On the Unix and Macintosh platforms, extensions are matched using glob-style
+  # pattern matching.
+  # On the Windows platform, extensions are matched by the underlying operating
+  # system.
+  #
+  # The types of possible extensions are:
+  #   * the special extension "*" matches any file
+  #   * the special extension "" matches any files that do not have an extension
+  #     (i.e., the filename contains no full stop character)
+  #   * any character string that does not contain any wild card characters ("*"
+  #     and "?").
+  #
+  # Due to the different pattern matching rules on the various platforms, to
+  # ensure portability, wild card characters are not allowed in the extensions,
+  # except as in the special extension "*".
+  # Extensions without a full stop character (e.g. "~") are allowed but may not
+  # work on all platforms.
+  def get_open_file(options = None)
+    Tk.execute(:tk_getOpenFile, options.to_tcl_options?)
+  end
+end

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

@@ -0,0 +1,83 @@
+module Tk
+  module_function
+
+  # Pop up a dialog box for the user to select a file to save.
+  #
+  # This method is usually associated with the "Save as" command in the "File"
+  # menu.
+  # If the user enters a file that already exists, the dialog box prompts the
+  # user for confirmation whether the existing file should be overwritten or
+  # not.
+  #
+  # If a user selects a file, the full pathname of the file is returned.
+  # If the user cancels the dialog, nil is returned.
+  #
+  # The following options may be given:
+  #
+  #   defaultextension: extension
+  #     Specifies a string that will be appended to the filename if the user
+  #     enters a filename without an extension.
+  #     The default value is the empty string, which means no extension will be
+  #     appended to the filename in any case.
+  #     This option is ignored on Mac OS X, which does not require extensions to
+  #     filenames, and the UNIX implementation guesses reasonable values for
+  #     this from the :filetypes option when this is not supplied.
+  #
+  #   filetypes: file_pattern_list
+  #     If a File types listbox exists in the file dialog on the particular
+  #     platform, this option gives the filetypes in this listbox.
+  #     When the user choose a filetype in the listbox, only the files of that
+  #     type are listed.
+  #     If this option is unspecified, or if it is set to the empty list, or if
+  #     the File types listbox is not supported by the particular platform then
+  #     all files are listed regardless of their types.
+  #
+  #   initialdir: directory
+  #     Specifies that the files in directory should be displayed when the
+  #     dialog pops up.
+  #     If this parameter is not specified, then the files in the current
+  #     working directory are displayed.
+  #     If the parameter specifies a relative path, the return value will
+  #     convert the relative path to an absolute path.
+  #
+  #   initialfile: filename
+  #     Specifies a filename to be displayed in the dialog when it pops up.
+  #
+  #   message: string
+  #     Specifies a message to include in the client area of the dialog.
+  #     This is only available on Mac OS X.
+  #
+  #   multiple: boolean
+  #     Allows the user to choose multiple files from the dialog.
+  #
+  #   parent: window
+  #     Makes window the logical parent of the file dialog.
+  #     The file dialog is displayed on top of its parent window.
+  #     On Mac OS X, this turns the file dialog into a sheet attached to the
+  #     parent window.
+  #
+  #   title: string
+  #     Specifies a string to display as the title of the dialog box.
+  #     If this option is not specified, then a default title is displayed.
+  #
+  # On the Unix and Macintosh platforms, extensions are matched using glob-style
+  # pattern matching.
+  # On the Windows platform, extensions are matched by the underlying operating
+  # system.
+  #
+  # The types of possible extensions are:
+  #   * the special extension "*" matches any file
+  #   * the special extension "" matches any files that do not have an extension
+  #     (i.e., the filename contains no full stop character)
+  #   * any character string that does not contain any wild card characters ("*"
+  #     and "?").
+  #
+  # Due to the different pattern matching rules on the various platforms, to
+  # ensure portability, wild card characters are not allowed in the extensions,
+  # except as in the special extension "*".
+  # Extensions without a full stop character (e.g. "~") are allowed but may not
+  # work on all platforms.
+  def get_save_file(options = None)
+    Tk.execute(:tk_getSaveFile, options.to_tcl_options?)
+  end
+end

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

@@ -0,0 +1,141 @@
+module Tk
+  # Confine pointer and keyboard events to a window sub-tree
+  #
+  #
+  # WARNING
+  #
+  # It is very easy to use global grabs to render a display completely unusable
+  # (e.g. by setting a grab on a widget which does not respond to events and not
+  # providing any mechanism for releasing the grab).
+  # Take extreme care when using them!
+  #
+  #
+  # DESCRIPTION
+  #
+  # This command implements simple pointer and keyboard grabs for Tk.
+  #
+  # Tk's grabs are different than the grabs described in the Xlib documentation.
+  # When a grab is set for a particular window, Tk restricts all pointer events
+  # to the grab window and its descendants in Tk's window hierarchy.
+  #
+  # Whenever the pointer is within the grab window's subtree, the pointer will
+  # behave exactly the same as if there had been no grab at all and all events
+  # will be reported in the normal fashion.
+  # When the pointer is outside window's tree, button presses and releases and
+  # mouse motion events are reported to window, and window entry and window exit
+  # events are ignored.
+  #
+  # The grab subtree “owns” the pointer: windows outside the grab subtree
+  # will be visible on the screen but they will be insensitive until the grab is
+  # released. The tree of windows underneath the grab window can include
+  # top-level windows, in which case all of those top-level windows and their
+  # descendants will continue to receive mouse events during the grab.
+  # Two forms of grabs are possible: local and global.
+  # A local grab affects only the grabbing application: events will be reported
+  # to other applications as if the grab had never occurred.
+  # Grabs are local by default.
+  #
+  # A global grab locks out all applications on the screen, so that only the
+  # given subtree of the grabbing application will be sensitive to pointer
+  # events (mouse button presses, mouse button releases, pointer motions, window
+  # entries, and window exits).
+  #
+  # During global grabs the window manager will not receive pointer events
+  # either. During local grabs, keyboard events (key presses and key releases)
+  # are delivered as usual: the window manager controls which application
+  # receives keyboard events, and if they are sent to any window in the grabbing
+  # application then they are redirected to the focus window.
+  # During a global grab Tk grabs the keyboard so that all keyboard events are
+  # always sent to the grabbing application.
+  #
+  # The focus command is still used to determine which window in the application
+  # receives the keyboard events.
+  # The keyboard grab is released when the grab is released.
+  #
+  # Grabs apply to particular displays.
+  # If an application has windows on multiple displays then it can establish a
+  # separate grab on each display.
+  # The grab on a particular display affects only the windows on that display.
+  # It is possible for different applications on a single display to have
+  # simultaneous local grabs, but only one application can have a global grab on
+  # a given display at once.
+  module Grab
+    # @see Grab.global
+    def grab_global(window)
+      Grab.globa(self)
+    end
+
+    # @see Grab.local
+    def grab_local
+      Grab.local(self)
+    end
+
+    # @see Grab.current
+    def grab_current
+      Grab.current(self)
+    end
+
+    # @see Grab.release
+    def grab_release
+      Grab.release(self)
+    end
+
+    # @see Grab.set_global
+    def grab_set_global
+      Grab.set_global(self)
+    end
+
+    # @see Grab.set_local
+    def grab_set_local
+      Grab.set_local(self)
+    end
+
+    module_function
+
+    # Same as [set_global], described below.
+    def global(window)
+      Tk.execute(:grab, '-global', window)
+    end
+
+    # Same as [set_local], described below.
+    def local(window)
+      Tk.execute(:grab, window)
+    end
+
+    # If window is specified, returns the name of the current grab window in
+    # this application for window's display, or an empty string if there is no
+    # such window.
+    # If window is omitted, the command returns a list whose elements are all
+    # of the windows grabbed by this application for all displays, or an empty
+    # string if the application has no grabs.
+    def current(window = None)
+      if None == window
+        Tk.execute(:grab, :current).to_a
+      else
+        Tk.execute(:grab, :current, window).to_s?
+      end
+    end
+
+    # Releases the grab on window if there is one, otherwise does nothing.
+    # Returns an empty string.
+    def release(window)
+      Tk.execute_only(:grab, :release, window)
+    end
+
+    # Sets a local grab on window.
+    # If a grab was already in effect for this application on +window+'s display
+    # then it is automatically released.
+    # Does nothing if there is already a local grab on +window+.
+    def set_local(window)
+      Tk.execute(:grab, :set, window)
+    end
+
+    # Sets a global grab on window.
+    # If a grab was already in effect for this application on +window+'s display
+    # then it is automatically released.
+    # Does nothing if there is already a global grab on +window+.
+    def set_global(window)
+      Tk.execute(:grab, :set, '-global', window)
+    end
+  end
+end