API for seesaw.core - Seesaw

by Dave Ray

Full namespace name: seesaw.core

Overview

Core functions and macros for Seesaw. Although there are many more
Seesaw namespaces, usually what you want is in here. Most functions
in other namespaces have a core wrapper which adds additional
capability or makes them easier to use.

Public Variables and Functions

ConfigAction

var

Protocol to hook into :action option

ConfigIcon

var

Protocol to hook into :icon option

ConfigModel

var

Protocol to hook into :model option

ConfigText

var

Protocol to hook into :text option

SelectionModeConfig

var

Hook protocol for :selection-mode option

action

var

Alias of seesaw.action/action:
Construct a new Action object. Supports the following properties:

    :enabled?  Whether the action is enabled
    :selected? Whether the action is selected (for use with radio buttons, 
               toggle buttons, etc.
    :name      The name of the action, i.e. the text that will be displayed
               in whatever widget it's associated with
    :command   The action command key. An arbitrary string identifier associated
               with the action.
    :tip       The action's tooltip
    :icon      The action's icon. See (seesaw.core/icon)
    :key       A keystroke associated with the action. See (seesaw.keystroke/keystroke).
    :mnemonic  The mnemonic for the button, either a character or a keycode.
                Usually allows the user to activate the button with alt-mnemonic.
                See (seesaw.util/to-mnemonic-keycode).
    :handler   A single-argument function that performs whatever operations are
               associated with the action. The argument is a ActionEvent instance.

  Instances of action can be passed to the :action option of most buttons, menu items,
  etc.

  Actions can be later configured with the same properties above with (seesaw.core/config!).

  Returns an instance of javax.swing.Action.

  See:
    http://download.oracle.com/javase/6/docs/api/javax/swing/Action.html

action-option

var

Default handler for the :action option. Internal use.

add!

function

Usage: (add! container subject & more)

Add one or more widgets to a widget container. The container and each widget
argument are passed through (to-widget) as usual. Each widget can be a single
widget, or a widget/constraint pair with a layout-specific constraint.

The container is properly revalidated and repainted after removal.

Examples:

  ; Add a label and a checkbox to a panel
  (add! (vertical-panel) "Hello" (button ...))

  ; Add a label and a checkbox to a border panel with layout constraints
  (add! (border-panel) ["Hello" :north] [(button ...) :center])

Returns the target container *after* it's been passed through (to-widget).

alert

function

Usage: (alert source message)
       (alert message)

Show a simple message alert dialog. Take an optional parent component, source,
used for dialog placement, and a message which is passed through (resource).

Examples:

  (alert "Hello!")
  (alert e "Hello!")

See:
  http://download.oracle.com/javase/6/docs/api/javax/swing/JOptionPane.html#showMessageDialog%28java.awt.Component,%20java.lang.Object%29

all-frames

function

Usage: (all-frames)

Returns a sequence of all of the frames (includes java.awt.Frame) known by the JVM.

This function is really only useful for debugging and repl development, namely:

  ; Clear out all frames
  (dispose! (all-frames))

Otherwise, it is highly unreliable. Frames will hang around after disposal, pile up
and generally cause trouble.

You've been warned.

assert-ui-thread

function

Usage: (assert-ui-thread message)

Verify that the current thread is the Swing UI thread and throw
IllegalStateException if it's not. message is included in the exception
message.

Returns nil.

See:
  http://download.oracle.com/javase/6/docs/api/javax/swing/SwingUtilities.html#isEventDispatchThread%28%29

border-panel

function

Usage: (border-panel & opts)

Create a panel with a border layout. In addition to the usual options,
supports:

  :north  widget for north position (passed through make-widget)
  :south  widget for south position (passed through make-widget)
  :east   widget for east position (passed through make-widget)
  :west   widget for west position (passed through make-widget)
  :center widget for center position (passed through make-widget)

  :hgap   horizontal gap between widgets
  :vgap   vertical gap between widgets

The :items option is a list of widget/direction pairs which can be used
if you don't want to use the direction options directly. For example, both
of these are equivalent:

  (border-panel :north "North" :south "South")

is the same as:

  (border-panel :items [["North" :north] ["South" :south]])

This is for consistency with other containers.

See:

  http://download.oracle.com/javase/6/docs/api/java/awt/BorderLayout.html

button

function

Usage: (button & args)

Construct a generic button. In addition to default widget options, supports
the following:

    :halign    Horizontal alignment. One of :left, :right, :leading, :trailing,
               :center
    :valign    Vertical alignment. One of :top, :center, :bottom
    :selected? Whether the button is initially selected. Mostly for checked
               and radio buttons/menu-items.
    :margin    The button margins as insets. See (seesaw.util/to-insets)
    :group     A button-group that the button should be added to.
    :resource  A resource prefix (see below).
    :mnemonic  The mnemonic for the button, either a character or a keycode.
                Usually allows the user to activate the button with alt-mnemonic.
                See (seesaw.util/to-mnemonic-keycode).

Resources and i18n:

  A button's base properties can be set from a resource prefix, i.e. a namespace-
  qualified keyword that refers to a resource bundle loadable by j18n.

Examples:

  ; Create a button with text "Next" with alt-N mnemonic shortcut that shows
  ; an alert when clicked.
  (button :text "Next"
          :mnemonic \N
          :listen [:action #(alert "NEXT!")])

See:
  http://download.oracle.com/javase/6/docs/api/javax/swing/JButton.html
  (seesaw.core/button-group)

button-group

function

Usage: (button-group & opts)

Creates a button group, i.e. a group of mutually exclusive toggle buttons,
radio buttons, toggle-able menus, etc. Takes the following options:

  :buttons A sequence of buttons to include in the group. They are *not*
           passed through (make-widget), i.e. they must be button or menu
           instances.

The mutual exclusion of the buttons in the group will be maintained automatically.
The currently "selected" button can be retrieved and set with (selection) and
(selection!) as usual.

Note that a button can be added to a group when the button is created using the
:group option of the various button and menu creation functions.

Examples:

  (let [bg (button-group)]
    (flow-panel :items [(radio :id :a :text "A" :group bg)
                        (radio :id :b :text "B" :group bg)]))

  ; now A and B are mutually exclusive

  ; Check A
  (selection bg (select root [:#a]))

  ; Listen for selection changes. Note that the selection MAY BE NIL!
  (listen bg :selection
    (fn [e]
      (if-let [s (selection e)]
        (println "Selected " (text s)))))

Returns an instance of javax.swing.ButtonGroup

See:
  http://download.oracle.com/javase/6/docs/api/javax/swing/ButtonGroup.html

canvas

function

Usage: (canvas & opts)

Creates a paintable canvas, i.e. a JPanel with paintComponent overridden.
Painting is configured with the :paint property which can take the
following values:

  nil - disables painting. The widget will be filled with its background
    color unless it is not opaque.

  (fn [c g]) - a paint function that takes the widget and a Graphics2D as
    arguments. Called after super.paintComponent.

  {:before fn :after fn :super? bool} - a map with :before and :after functions which
    are called before and after super.paintComponent respectively. If super?
    is false, super.paintComponent is not called.

Notes:

  The :paint option is actually supported by *all* Seesaw widgets.

  (seesaw.core/config!) can be used to change the :paint property at any time.

  Some customizations are also possible and maybe easier with
  the creative use of borders.

Examples:

  (canvas :paint #(.drawString %2 "I'm a canvas" 10 10))

See:
  (seesaw.graphics)
  (seesaw.examples.canvas)
  http://download.oracle.com/javase/6/docs/api/javax/swing/JComponent.html#paintComponent%28java.awt.Graphics%29

card-panel

function

Usage: (card-panel & opts)

Create a panel with a card layout. Options:

  :items A list of pairs with format [widget, identifier]
         where identifier is a string or keyword.

See:

  (seesaw.core/show-card!)
  http://download.oracle.com/javase/6/docs/api/java/awt/CardLayout.html

checkbox

function

Usage: (checkbox & args)

Same as (seesaw.core/button), but creates a checkbox. Use :selected? option
to set initial state.

See:
  (seesaw.core/button)

function

Usage: (checkbox-menu-item & args)

Create a checked menu item for use in (seesaw.core/menu). Supports same options as
(seesaw.core/button)

combobox

function

Usage: (combobox & args)

Create a combo box (JComboBox). Additional options:

  :model Instance of ComboBoxModel, or sequence of values used to construct
         a default model.
  :renderer Cell renderer used for display. See (seesaw.cells/to-cell-renderer).

Note that the current selection can be retrieved and set with the (selection) and
(selection!) functions. Calling (seesaw.core/text) on a combobox will return
(str (selection cb)). (seesaw.core/text!) is not supported.

Notes:

See:
  http://download.oracle.com/javase/6/docs/api/javax/swing/JComboBox.html

config

var

Alias of seesaw.config/config:
Retrieve the value of an option from target. For example:
  
    (config button1 :text)
    => "I'm a button!"
  
  Target must satisfy the Configurable protocol. In general, it may be a widget, 
  or convertible to widget with (to-widget). For example, the target can be an event 
  object.

  Returns the option value. 
  Throws IllegalArgumentException if an unknown option is requested.

  See:
    (seesaw.core/config!)

config!

var

Alias of seesaw.config/config!:
Applies options in the argument list to one or more targets. For example:

    (config! button1 :enabled? false :text "I' disabled")

  or:

    (config! [button1 button2] :enabled? false :text "We're disabled")
 
  Targets must satisfy the Configurable protocol. In general, they may be widgets, 
  or convertible to widgets with (to-widget). For example, the target can be an event 
  object.

  Returns the input targets.
  Throws IllegalArgumentException if an unknown option is encountered.

  See:
    (seesaw.core/config)

construct

macro

Usage: (construct factory-class)

*experimental. subject to change.*

A macro that returns a proxied instance of the given class. This is
used by Seesaw to construct widgets that can be fiddled with later,
e.g. installing a paint handler, etc.

custom-dialog

function

Usage: (custom-dialog & {:keys [width height visible? modal? on-close size], :or {width 100, height 100, visible? false}, :as opts})

Create a dialog and display it.

    (custom-dialog ... options ...)

Besides the default & frame options, options can also be one of:

  :parent  The window which the new dialog should be positioned relatively to.
  :modal?  A boolean value indicating whether this dialog is to be a
            modal dialog.  If :modal? *and* :visible? are set to
            true (:visible? is true per default), the function will
            block with a dialog. The function will return once the user:
            a) Closes the window by using the system window
               manager (e.g. by pressing the "X" icon in many OS's)
            b) A function from within an event calls (dispose!) on the dialog
            c) A function from within an event calls RETURN-FROM-DIALOG
                with a return value.
            In the case of a) and b), this function returns nil. In the
            case of c), this function returns the value passed to
            RETURN-FROM-DIALOG. Default: true.


Returns a JDialog. Use (seesaw.core/show!) to display the dialog.

Notes:

See:
  (seesaw.core/show!)
  (seesaw.core/return-from-dialog)
  http://download.oracle.com/javase/6/docs/api/javax/swing/JDialog.html

dialog

function

Usage: (dialog & {:as opts})

Display a JOptionPane. This is a dialog which displays some
input/question to the user, which may be answered using several
standard button configurations or entirely custom ones.

    (dialog ... options ...)

Options can be any of:

  :content      May be a string or a component (or a panel with even more
                components) which is to be displayed.

  :option-type  In case :options is *not* specified, this may be one of
                :default, :yes-no, :yes-no-cancel, :ok-cancel to specify
                which standard button set is to be used in the dialog.

  :type        The type of the dialog. One of :warning, :error, :info, :plain, or :question.

  :options     Custom buttons/options can be provided using this argument.
               It must be a seq of "make-widget"'able objects which will be
               displayed as options the user can choose from. Note that in this
               case, :success-fn, :cancel-fn & :no-fn will *not* be called.
               Use the handlers on those buttons & RETURN-FROM-DIALOG to close
               the dialog.

  :default-option  The default option instance which is to be selected. This should be an element
                   from the :options seq.

  :success-fn  A function taking the JOptionPane as its only
               argument. It will be called when no :options argument
               has been specified and the user has pressed any of the "Yes" or "Ok" buttons.
               Default: a function returning :success.

  :cancel-fn   A function taking the JOptionPane as its only
               argument. It will be called when no :options argument
               has been specified and the user has pressed the "Cancel" button.
               Default: a function returning nil.

  :no-fn       A function taking the JOptionPane as its only
               argument. It will be called when no :options argument
               has been specified and the user has pressed the "No" button.
               Default: a function returning :no.

Any remaining options will be passed to dialog.

Examples:

  ; display a dialog with only an "Ok" button.
  (dialog :content "You may now press Ok")

  ; display a dialog to enter a users name and return the entered name.
  (dialog :content
   (flow-panel :items ["Enter your name" (text :id :name :text "Your name here")])
               :option-type :ok-cancel
               :success-fn (fn [p] (text (select (to-root p) [:#name]))))

The dialog is not immediately shown. Use (seesaw.core/show!) to display the dialog.
If the dialog is modal this will return the result of :success-fn, :cancel-fn or
:no-fn depending on what button the user pressed.

Alternatively if :options has been specified, returns the value which has been
passed to (seesaw.core/return-from-dialog).

See:
  (seesaw.core/show!)
  (seesaw.core/return-from-dialog)

dispose!

function

Usage: (dispose! targets)

Dispose the given frame, dialog or window. target can be anything that can
be converted to a root-level object with (to-root).

Returns its input.

See:
 http://download.oracle.com/javase/6/docs/api/java/awt/Window.html#dispose%28%29

editor-pane

function

Usage: (editor-pane & opts)

Create a JEditorPane. Custom options:

  :page         A URL (string or java.net.URL) with the contents of the editor
  :content-type The content-type, for example "text/html" for some crappy
                HTML rendering.
  :editor-kit   The EditorKit. See Javadoc.

Notes:

  An editor pane can fire 'hyperlink' events when elements are click,
  say like a hyperlink in an html doc. You can listen to these with the
  :hyperlink event:

    (listen my-editor :hyperlink (fn [e] ...))

  where the event is an instance of javax.swing.event.HyperlinkEvent.
  From there you can inspect the event, inspect the clicked element,
  etc.

See:
  http://download.oracle.com/javase/6/docs/api/javax/swing/JEditorPane.html
  http://docs.oracle.com/javase/6/docs/api/javax/swing/event/HyperlinkEvent.html

flow-panel

function

Usage: (flow-panel & opts)

Create a panel with a flow layout. Options:

  :items  List of widgets (passed through make-widget)
  :hgap   horizontal gap between widgets
  :vgap   vertical gap between widgets
  :align  :left, :right, :leading, :trailing, :center
  :align-on-baseline?

See http://download.oracle.com/javase/6/docs/api/java/awt/FlowLayout.html

form-panel

function

Usage: (form-panel & opts)

*Don't use this. GridBagLaout is an abomination* I suggest using Seesaw's
MigLayout (seesaw.mig) or JGoogies Forms (seesaw.forms) support instead.

A panel that uses a GridBagLayout. Also aliased as (grid-bag-panel) if you
want to be reminded of GridBagLayout. The :items property should be a list
of vectors of the form:

    [widget & options]

where widget is something widgetable and options are key/value pairs
corresponding to GridBagConstraints fields. For example:

  [["Name"         :weightx 0]
   [(text :id :name) :weightx 1 :fill :horizontal]]

This creates a label/field pair where the field expands.

See http://download.oracle.com/javase/6/docs/api/java/awt/GridBagLayout.html

frame

function

Usage: (frame & {:keys [width height visible? size], :as opts})

Create a JFrame. Options:

  :id       id of the window, used by (select).
  :title    the title of the window
  :icon     the icon of the frame (varies by platform)
  :width    initial width. Note that calling (pack!) will negate this setting
  :height   initial height. Note that calling (pack!) will negate this setting
  :size     initial size. Note that calling (pack!) will negate this setting
  :minimum-size minimum size of frame, e.g. [640 :by 480]
  :content  passed through (make-widget) and used as the frame's content-pane
  :visible?  whether frame should be initially visible (default false)
  :resizable? whether the frame can be resized (default true)
  :on-close   default close behavior. One of :exit, :hide, :dispose, :nothing

returns the new frame.

Examples:

  ; Create a frame, pack it and show it.
  (-> (frame :title "HI!" :content "I'm a label!")
    pack!
    show!)

  ; Create a frame with an initial size (note that pack! isn't called)
  (show! (frame :title "HI!" :content "I'm a label!" :width 500 :height 600))

Notes:
  Unless :visible? is set to true, the frame will not be displayed until (show!)
  is called on it.

  Call (pack!) on the frame if you'd like the frame to resize itself to fit its
  contents. Sometimes this doesn't look like crap.

See:
  (seesaw.core/show!)
  (seesaw.core/hide!)
  (seesaw.core/move!)
  http://download.oracle.com/javase/6/docs/api/javax/swing/JFrame.html

full-screen!

function

Usage: (full-screen! device window)
       (full-screen! window)

Make the given window/frame full-screen. Pass nil to return all windows
to normal size.

full-screen-window

function

Usage: (full-screen-window device)
       (full-screen-window)

Returns the window/frame that is currently in full-screen mode or nil if
none.

full-screen?

function

Usage: (full-screen? device window)
       (full-screen? window)

Returns true if the given window/frame is in full-screen mode

grid-panel

function

Usage: (grid-panel & {:keys [rows columns], :as opts})

Create a panel where widgets are arranged horizontally. Options:

  :rows    Number of rows, defaults to 0, i.e. unspecified.
  :columns Number of columns.
  :items   List of widgets (passed through make-widget)
  :hgap    horizontal gap between widgets
  :vgap    vertical gap between widgets

Note that it's usually sufficient to just give :columns and ignore :rows.

See http://download.oracle.com/javase/6/docs/api/java/awt/GridLayout.html

group-by-id

function

Usage: (group-by-id root)

Group the widgets in a hierarchy starting at some root into a map
keyed by :id. Widgets with no id are ignored. If an id appears twice,
the 'later' widget wins.

  root is any (to-widget)-able object.

Examples:

  Suppose you have a form with with widgets with ids :name, :address,
  :phone, :city, :state, :zip.
  You'd like to quickly grab all those widgets and do something with
  them from an event handler:

    (fn [event]
      (let [{:keys [name address phone city state zip]} (group-by-id event)
        ... do something ...))

  This is functionally equivalent to, but faster than:

    (let [name (select event [:#name])
          address (select event [:#address])
          phone (select event [:#phone])
          ... and so on ...]
        ... do something ...)

See:
  (seesaw.core/select)

height

function

Usage: (height w)

Returns the height of the given widget in pixels

hide!

function

Usage: (hide! targets)

Hide a frame, dialog or widget.

 Returns its input.

See:
  http://download.oracle.com/javase/6/docs/api/java/awt/Window.html#setVisible%28boolean%29

horizontal-panel

function

Usage: (horizontal-panel & opts)

Create a panel where widgets are arranged horizontally. Options:

  :items List of widgets (passed through make-widget)

See http://download.oracle.com/javase/6/docs/api/javax/swing/BoxLayout.html

id-for

var

Deprecated. See (seesaw.core/id-of)

id-of

function

Usage: (id-of w)

Returns the id of the given widget if the :id property was specified at
 creation. The widget parameter is passed through (to-widget) first so
 events and other objects can also be used. The id is always returned as
 a string, even it if was originally given as a keyword.

Returns the id as a keyword, or nil.

See:
  (seesaw.core/select).

input

function

Usage: (input & args)

Show an input dialog:

  (input [source] message & options)

source  - optional parent component
message - The message to show the user. May be a string, or list of strings, widgets, etc.
options - additional options

Additional options:

  :title     The dialog title
  :value     The initial, default value to show in the dialog
  :choices   List of values to choose from rather than freeform entry
  :type      :warning, :error, :info, :plain, or :question
  :icon      Icon to display (Icon, URL, etc)
  :to-string A function which creates the string representation of the values
             in :choices. This let's you choose arbitrary clojure data structures
             without while keeping things looking nice. Defaults to str.

Examples:

  ; Ask for a string input
  (input "Bang the keyboard like a monkey")

  ; Ask for a choice from a set
  (input "Pick a color" :choices ["RED" "YELLO" "GREEN"])

  ; Choose from a list of maps using a custom string function for the display.
  ; This will display only the city names, but the return value will be one of
  ; maps in the :choices list. Yay!
  (input "Pick a city"
    :choices [{ :name "New York"  :population 8000000 }
              { :name "Ann Arbor" :population 100000 }
              { :name "Twin Peaks" :population 5201 }]
    :to-string :name)

Returns the user input or nil if they hit cancel.

See:
  http://download.oracle.com/javase/6/docs/api/javax/swing/JOptionPane.html

invoke-later

macro

Usage: (invoke-later & args)

Alias for seesaw.invoke/invoke-later

invoke-now

macro

Usage: (invoke-now & args)

Alias for seesaw.invoke/invoke-now

invoke-soon

macro

Usage: (invoke-soon & args)

Alias for seesaw.invoke/invoke-soon

label

function

Usage: (label & args)

Create a label. Supports all default properties. Can take two forms:

    (label "My Label")  ; Single text argument for the label

or with full options:

    (label :id :my-label :text "My Label" ...)

Additional options:

  :h-text-position Horizontal text position, :left, :right, :center, etc.
  :v-text-position Horizontal text position, :top, :center, :bottom, etc.
  :resource        Namespace-qualified keyword which is a resource prefix for the
                   labels properties

Resources and i18n:

  A label's base properties can be set from a resource prefix, i.e. a namespace-
  qualified keyword that refers to a resource bundle loadable by j18n.

See:
  http://download.oracle.com/javase/6/docs/api/javax/swing/JLabel.html

left-right-split

function

Usage: (left-right-split left right & args)

Create a left/right (horizontal) splitpane with the given widgets. See
(seesaw.core/splitter) for additional options. Options are given after
the two widgets.

Notes:

See:
  (seesaw.core/splitter)
  http://download.oracle.com/javase/6/docs/api/javax/swing/JSplitPane.html

listbox

function

Usage: (listbox & args)

Create a list box (JList). Additional options:

  :model A ListModel, or a sequence of values with which a DefaultListModel
         will be constructed.
  :renderer A cell renderer to use. See (seesaw.cells/to-cell-renderer).

Notes:

  Retrieving and setting the current selection of the list box is fully
  supported by the (selection) and (selection!) functions.

See:
  http://download.oracle.com/javase/6/docs/api/javax/swing/JList.html

listen

var

Alias of seesaw.event/listen:

*note: use seesaw.core/listen rather than calling this directly*

Install listeners for one or more events on the given target. For example:

  (listen (button "foo")
    :mouse-entered     (fn [e] ...)
    :focus-gained      (fn [e] ...)
    :key-pressed       (fn [e] ...)
    :mouse-wheel-moved (fn [e] ...))

one function can be registered for multiple events by using a set
of event names instead of one:

  (listen (text)
    #{:remove-update :insert-update} (fn [e] ...))

Note in this case that it's smart enough to add a document listener
to the JTextFields document.

Similarly, an event can be registered for all events in a particular swing
listener interface by just using the keyword-ized prefix of the interface
name. For example, to get all callbacks in the MouseListener interface:

  (listen my-widget :mouse (fn [e] ...))

Returns a function which, when called, removes all listeners registered
with this call.

When the target is a JTable and listener type is :selection, only
row selection events are reported. Also note that the source table is
*not* retrievable from the event object.

function

Usage: (make-widget v)

Try to create a new widget based on the following rules:

  nil -> nil
  java.awt.Component -> return argument unchanged (like to-widget)
  java.util.EventObject -> return the event source (like to-widget)

  java.awt.Dimension -> return Box/createRigidArea
  java.swing.Action    -> return a button using the action
  :separator -> create a horizontal JSeparator
  :fill-h -> Box/createHorizontalGlue
  :fill-v -> Box/createVerticalGlue
  [:fill-h n] -> Box/createHorizontalStrut with width n
  [:fill-v n] -> Box/createVerticalStrut with height n
  [width :by height] -> create rigid area with given dimensions
  java.net.URL -> a label with the image located at the url
  Anything else -> a label with the text from passing the object through str

function

Usage: (menu & opts)

Create a new menu. In addition to all options applicable to (seesaw.core/button)
the following additional options are supported:

  :items Sequence of menu item-like things (actions, icons, JMenuItems, etc)

Notes:

See:
  (seesaw.core/button)
  http://download.oracle.com/javase/6/docs/api/javax/swing/JMenu.html

function

Usage: (menu-item & args)

Create a menu item for use in (seesaw.core/menu). Supports same options as
(seesaw.core/button)

menubar

function

Usage: (menubar & opts)

Create a new menu bar, suitable for the :menubar property of (frame).
Additional options:

  :items Sequence of menus, see (menu).

Notes:

See:
  (seesaw.core/frame)
  http://download.oracle.com/javase/6/docs/api/javax/swing/JMenuBar.html

model-option

var

Default handler for the :model option. Delegates to the ConfigModel protocol

move!

function

Usage: (move! target how & [loc])

Move a widget relatively or absolutely. target is a 'to-widget'-able object,
type is :by or :to, and loc is a two-element vector or instance of
java.awt.Point. The how type parameter has the following interpretation:

  :to The absolute position of the widget is set to the given point
  :by The position of th widget is adjusted by the amount in the given point
      relative to its current position.
  :to-front Move the widget to the top of the z-order in its parent.

Returns target.

Examples:

  ; Move x to the point (42, 43)
  (move! x :to [42, 43])

  ; Move x to y position 43 while keeping x unchanged
  (move! x :to [:*, 43])

  ; Move x relative to its current position. Assume initial position is (42, 43).
  (move! x :by [50, -20])
  ; ... now x's position is [92, 23]

Notes:
  For widgets, this function will generally only have an affect on widgets whose container
  has a nil layout! This function has similar functionality to the :bounds
  and :location options, but is a little more flexible and readable.

See:
  (seesaw.core/xyz-panel)
  http://download.oracle.com/javase/6/docs/api/java/awt/Component.html#setLocation(int, int)

native!

function

Usage: (native!)

Set native look and feel and other options to try to make things look right.
This function must be called very early, like before any other Seesaw or Swing
calls!

Note that on OSX, you can set the application name in the menu bar (usually
displayed as the main class name) by setting the -Xdock:<name-of-your-app>
parameter to the JVM at startup. Sorry, I don't know of a way to do it
dynamically.

See:

http://developer.apple.com/library/mac/#documentation/Java/Conceptual/Java14Development/07-NativePlatformIntegration/NativePlatformIntegration.html

pack!

function

Usage: (pack! targets)

Pack a frame or window, causing it to resize to accommodate the preferred
size of its contents.

Returns its input.

See:
  http://download.oracle.com/javase/6/docs/api/java/awt/Window.html#pack%28%29

paintable

macro

Usage: (paintable cls & opts)

*Deprecated. Just use :paint directly on any widget.*

 Macro that generates a paintable widget, i.e. a widget that can be drawn on
 by client code. target is a Swing class literal indicating the type that will
 be constructed.

 All other options will be passed along to the given Seesaw widget
 as usual and will be applied to the generated class.

 Notes:
   If you just want a panel to draw on, use (seesaw.core/canvas). This macro is
   intended for customizing the appearance of existing widget types.

 Examples:

   ; Create a raw JLabel and paint over it.
   (paintable javax.swing.JLabel :paint (fn [c g] (.fillRect g 0 0 20 20))

 See:
   (seesaw.core/canvas)
   (seesaw.graphics)
   http://download.oracle.com/javase/6/docs/api/javax/swing/JComponent.html#paintComponent%28java.awt.Graphics%29

password

function

Usage: (password & opts)

Create a password field. Options are the same as single-line text fields with
the following additions:

  :echo-char The char displayed for the characters in the password field

Returns an instance of JPasswordField.

Example:

  (password :echo-char \X)

Notes:

See:
  http://download.oracle.com/javase/6/docs/api/javax/swing/JPasswordField.html

function

Usage: (popup & opts)

Create a new popup menu. Additional options:

  :items Sequence of menu item-like things (actions, icons, JMenuItems, etc)

Note that in many cases, the :popup option is what you want if you want to
show a context menu on a widget. It handles all the yucky mouse stuff and
fixes various eccentricities of Swing.

Notes:

See:
  http://download.oracle.com/javase/6/docs/api/javax/swing/JPopupMenu.html

progress-bar

function

Usage: (progress-bar & {:keys [orientation value min max], :as opts})

Show a progress-bar which can be used to display the progress of long running tasks.

    (progress-bar ... options ...)

Besides the default options, options can also be one of:

  :orientation   The orientation of the progress-bar. One of :horizontal, :vertical. Default: :horizontal.
  :value         The initial numerical value that is to be set. Default: 0.
  :min           The minimum numerical value which can be set. Default: 0.
  :max           The maximum numerical value which can be set. Default: 100.
  :paint-string? A boolean value indicating whether to paint a string containing
                 the progress' percentage. Default: false.
  :indeterminate? A boolean value indicating whether the progress bar is to be in
                  indeterminate mode (for when the exact state of the task is not
                  yet known). Default: false.

Examples:

  ; vertical progress bar from 0 to 100 starting with inital value at 15.
  (progress-bar :orientation :vertical :min 0 :max 100 :value 15)

Returns a JProgressBar.

Notes:

See:
  http://download.oracle.com/javase/6/docs/api/javax/swing/JProgressBar.html

radio

function

Usage: (radio & args)

Same as (seesaw.core/button), but creates a radio button. Use :selected? option
to set initial state.

See:
  (seesaw.core/button)

function

Usage: (radio-menu-item & args)

Create a radio menu item for use in (seesaw.core/menu). Supports same options as
(seesaw.core/button).

Notes:
  Use (seesaw.core/button-group) or the :group option to enforce mutual exclusion
  across menu items.

remove!

function

Usage: (remove! container subject & more)

Remove one or more widgets from a container. container and each widget
are passed through (to-widget) as usual, but no new widgets are created.

The container is properly revalidated and repainted after removal.

Examples:

  (def lbl (label "HI"))
  (def p (border-panel :north lbl))
  (remove! p lbl)

Returns the target container *after* it's been passed through (to-widget).

repaint!

function

Usage: (repaint! targets)

Request a repaint of one or a list of widget-able things.

Example:

  ; Repaint just one widget
  (repaint! my-widget)

  ; Repaint all widgets in a hierarcy
  (repaint! (select [:*] root))

Returns targets.

replace!

function

Usage: (replace! container old-widget new-widget)

Replace old-widget with new-widget from container. container and old-widget
are passed through (to-widget). new-widget is passed through make-widget.
Note that the layout constraints of old-widget are retained for the new widget.
This is different from the behavior you'd get with just remove/add in Swing.

The container is properly revalidated and repainted after replacement.

Examples:

  ; Replace a label with a new label.
  (def lbl (label "HI"))
  (def p (border-panel :north lbl))
  (replace! p lbl "Goodbye")

Returns the target container *after* it's been passed through (to-widget).

request-focus!

function

Usage: (request-focus! target)

Request focus for the given widget-able thing. This will try to give
keyboard focus to the given widget. Returns its input.

The widget must be :focusable? for this to succeed.

Example:
  (request-focus! my-widget)

  ; Move focus on click
  (listen my-widget :focus-gained request-focus!)

See:
  http://docs.oracle.com/javase/6/docs/api/javax/swing/JComponent.html#requestFocusInWindow()

return-from-dialog

function

Usage: (return-from-dialog dlg result)

Return from the given dialog with the specified value. dlg may be anything
that can be converted into a dialog as with (to-root). For example, an
event, or a child widget of the dialog. Result is the value that will
be returned from the blocking (dialog), (custom-dialog), or (show!)
call.

Examples:

  ; A button with an action listener that will cause the dialog to close
  ; and return :ok to the invoker.
  (button
    :text "OK"
    :listen [:action (fn [e] (return-from-dialog e :ok))])

Notes:
  The dialog must be modal and created from within the DIALOG fn with
  :modal? set to true.

See:
  (seesaw.core/dialog)
  (seesaw.core/custom-dialog)

scroll!

function

Usage: (scroll! target modifier arg)

Scroll a widget. Obviously, the widget must be contained in a scrollable.
Returns the widget.

The basic format of the function call is:

  (scroll! widget modifier argument)

widget is passed through (to-widget) as usual. Currently, the only accepted
value for modifier is :to. The interpretation and set of accepted values for
argument depends on the type of widget:

  All Widgets:

    :top           - Scroll to the top of the widget
    :bottom        - Scroll to the bottom of the widget
    java.awt.Point - Scroll so the given pixel point is visible
    java.awt.Rectangle - Scroll so the given rectangle is visible
    [:point x y]   - Scroll so the given pixel point is visible
    [:rect x y w h] - Scroll so the given rectable is visible

  listboxes (JList):

    [:row n] - Scroll so that row n is visible

  tables (JTable):

    [:row n]        - Scroll so that row n is visible
    [:column n]     - Scroll so that column n is visible
    [:cell row col] - Scroll so that the given cell is visible

  text widgets:

    [:line n] - Scroll so that line n is visible
    [:position n] - Scroll so that position n (character offset) is visible

    Note that for text widgets, the caret will also be moved which in turn
    causes the selection to change.

Examples:

  (scroll! w :to :top)
  (scroll! w :to :bottom)
  (scroll! w :to [:point 99 10])
  (scroll! w :to [:rect  99 10 100 100])

  (scroll! listbox :to [:row 99])

  (scroll! table :to [:row 99])
  (scroll! table :to [:column 10])
  (scroll! table :to [:cell 99 10])

  (scroll! text :to [:line 200])
  (scroll! text :to [:position 2000])

See:
  (seesaw.scroll/scroll!*)
  (seesaw.examples.scroll)

scrollable

function

Usage: (scrollable target & opts)

Wrap target in a JScrollPane and return the scroll pane.

The first argument is always the widget that should be scrolled. It's followed
by zero or more options *for the scroll pane*.

Additional Options:

  :hscroll       - Controls appearance of horizontal scroll bar.
                   One of :as-needed (default), :never, :always
  :vscroll       - Controls appearance of vertical scroll bar.
                   One of :as-needed (default), :never, :always
  :row-header    - Row header widget or viewport
  :column-header - Column header widget or viewport
  :lower-left    - Widget in lower-left corner
  :lower-right   - Widget in lower-right corner
  :upper-left    - Widget in upper-left corner
  :upper-right   - Widget in upper-right corner

Examples:

  ; Vanilla scrollable
  (scrollable (listbox :model ["Foo" "Bar" "Yum"]))

  ; Scrollable with some options on the JScrollPane
  (scrollable (listbox :model ["Foo" "Bar" "Yum"]) :id :#scrollable :border 5)

Notes:

See:
  http://download.oracle.com/javase/6/docs/api/javax/swing/JScrollPane.html

select

function

Usage: (select root selector)

Select a widget using the given selector expression. Selectors are *always*
 expressed as a vector. root is the root of the widget hierarchy to select
 from, usually either a (frame) or other container.

  (select root [:#id])          Look up widget by id. A single widget is
                                always returned.

  (select root [:tag])          Look up widgets by "tag". In Seesaw tag is
                                treated as the exact simple class name of a
                                widget, so :JLabel would match both
                                javax.swing.JLabel *and* com.me.JLabel.
                                Be careful!

  (select root [:<class-name>]) Look up widgets by *fully-qualified* class name.
                                Matches sub-classes as well. Always returns a
                                sequence of widgets.

  (select root [:<class-name!>]) Same as above, but class must match exactly.

  (select root [:*])             Root and all the widgets under it

Notes:
  This function will return a single widget *only* in the case where the selector
  is a single identifier, e.g. [:#my-id]. In *all* other cases, a sequence of
  widgets is returned. This is for convenience. Select-by-id is the common case
  where a single widget is almost always desired.

Examples:

  To find a widget by id from an event handler, use (to-root) on the event to get
  the root and then select on the id:

    (fn [e]
      (let [my-widget (select (to-root e) [:#my-widget])]
        ...))

  Disable all JButtons (excluding subclasses) in a hierarchy:

    (config! (select root [:<javax.swing.JButton>]) :enabled? false)

  More:

    ; All JLabels, no sub-classes allowed
    (select root [:<javax.swing.JLabel!>])

    ; All JSliders that are descendants of a JPanel with id foo
    (select root [:JPanel#foo :JSlider])

    ; All JSliders (and sub-classes) that are immediate children of a JPanel with id foo
    (select root [:JPanel#foo :> :<javax.swing.JSlider>])

    ; All widgets with class foo. Set the class of a widget with the :class option
    (flow-panel :class :my-class) or (flow-panel :class #{:class1 :class2})
    (select root [:.my-class])
    (select root [:.class1.class2])

    ; Select all text components with class input
    (select root [:<javax.swing.text.JTextComponent>.input])

    ; Select all descendants of all panels with class container
    (select root [:JPanel.container :*])

See:
  (seesaw.selector/select)
  https://github.com/cgrand/enlive

select-with

function

Usage: (select-with target)

Returns an object with the following properties:

 * Equivalent to (partial seesaw.core/select (to-widget target)), i.e. it
   returns a function that performs a select on the target.
 * Calling (to-widget) on it returns the same value as (to-widget target).

This basically allows you to pack a widget and the select function into a single
package for convenience. For example:

  (defn make-frame [] (frame ...))

  (defn add-behaviors [$]
    (let [widget-a ($ [:#widget-a])
          buttons  ($ [:.button])
          ...]
      ...)
    $)

  (defn -main []
    (-> (make-frame) select-with add-behaviors pack! show!))

See:
  (seesaw.core/select)
  (seesaw.core/to-widget)

selection

function

Usage: (selection target)
       (selection target options)

Gets the selection of a widget. target is passed through (to-widget)
so event objects can also be used. The default behavior is to return
a *single* selection value, even if the widget supports multiple selection.
If there is no selection, returns nil.

options is an option map which supports the following flags:

  multi? - If true the return value is a seq of selected values rather than
    a single value.

Examples:

(def t (table))
(listen t :selection
  (fn [e]
    (let [selected-rows (selection t {:multi? true})]
      (println "Currently selected rows: " selected-rows))))

See:
  (seesaw.core/selection!)
  (seesaw.selection/selection)

selection!

function

Usage: (selection! target new-selection)
       (selection! target opts new-selection)

Sets the selection on a widget. target is passed through (to-widget)
so event objects can also be used. The arguments are the same as
(selection). By default, new-selection is a single new selection value.
If new-selection is nil, the selection is cleared.

options is an option map which supports the following flags:

  multi? - if true new-expression is a list of values to selection,
    the same as the list returned by (selection).

Always returns target.

See:
  (seesaw.core/selection)
  (seesaw.selection/selection!)

separator

function

Usage: (separator & opts)

Create a separator.

Notes:

See:
  http://download.oracle.com/javase/6/docs/api/javax/swing/JSeparator.html

show!

function

Usage: (show! targets)

Show a frame, dialog or widget.

 If target is a modal dialog, the call will block and show! will return the
 dialog's result. See (seesaw.core/return-from-dialog).

 Returns its input.

See:
  http://download.oracle.com/javase/6/docs/api/java/awt/Window.html#setVisible%28boolean%29

show-card!

function

Usage: (show-card! panel id)

Show a particular card in a card layout. id can be a string or keyword.
 panel is returned.

See:

  (seesaw.core/card-panel)
  http://download.oracle.com/javase/6/docs/api/java/awt/CardLayout.html

slider

function

Usage: (slider & {:keys [orientation value min max minor-tick-spacing major-tick-spacing snap-to-ticks? paint-ticks? paint-labels? paint-track? inverted?], :as kw})

Show a slider which can be used to modify a value.

    (slider ... options ...)

Besides the default options, options can also be one of:

  :orientation   The orientation of the slider. One of :horizontal, :vertical.
  :value         The initial numerical value that is to be set.
  :min           The minimum numerical value which can be set.
  :max           The maximum numerical value which can be set.
  :minor-tick-spacing  The spacing between minor ticks. If set, will also set :paint-ticks? to true.
  :major-tick-spacing  The spacing between major ticks. If set, will also set :paint-ticks? to true.
  :snap-to-ticks?  A boolean value indicating whether the slider should snap to ticks.
  :paint-ticks?    A boolean value indicating whether to paint ticks.
  :paint-labels?   A boolean value indicating whether to paint labels for ticks.
  :paint-track?    A boolean value indicating whether to paint the track.
  :inverted?       A boolean value indicating whether to invert the slider (to go from high to low).

Returns a JSlider.

Examples:

  ; ask & return single file
  (slider :value 10 :min -50 :max 50)

Notes:

See:
  http://download.oracle.com/javase/6/docs/api/javax/swing/JSlider.html

spinner

function

Usage: (spinner & args)

Create a spinner (JSpinner). Additional options:

  :model Instance of SpinnerModel, or one of the values described below.

Note that the value can be retrieved and set with the (selection) and
(selection!) functions. Listen to :selection to be notified of value
changes.

The value of model can be one of the following:

  * An instance of javax.swing.SpinnerModel
  * A java.util.Date instance in which case the spinner starts at that date,
    is unbounded, and moves by day.
  * A number giving the initial value for an unbounded number spinner
  * A value returned by (seesaw.core/spinner-model)

Notes:

See:
  http://download.oracle.com/javase/6/docs/api/javax/swing/JSpinner.html
  http://download.oracle.com/javase/6/docs/api/javax/swing/SpinnerModel.html
  (seesaw.core/spinner-model)
  test/seesaw/test/examples/spinner.clj

spinner-model

function

Usage: (spinner-model v & {:keys [from to by]})

A helper function for creating spinner models. Calls take the general
form:

    (spinner-model initial-value
      :from start-value :to end-value :by step)

Values can be one of:

  * java.util.Date where step is one of :day-of-week, etc. See
    java.util.Calendar constants.
  * a number

Any of the options beside the initial value may be omitted.

Note that on some platforms the :by parameter will be ignored for date
spinners.

See:
  (seesaw.core/spinner)
  http://download.oracle.com/javase/6/docs/api/javax/swing/SpinnerDateModel.html
  http://download.oracle.com/javase/6/docs/api/javax/swing/SpinnerNumberModel.html
  http://download.oracle.com/javase/6/docs/api/javax/swing/JSpinner.html

splitter

function

Usage: (splitter dir left right & opts)

Create a new JSplitPane. This is a lower-level function. Usually you want
(seesaw.core/top-bottom-split) or (seesaw.core/left-right-split). But here's
the additional options any three of these functions can take:

  :divider-location The initial divider location. See (seesaw.core/divider-location!).

Notes:

See:
  http://download.oracle.com/javase/6/docs/api/javax/swing/JSplitPane.html

style-text!

function

Usage: (style-text! target id start length)

Style a JTextPane
id identifies a style that has been added to the text pane.

See:

  (seesaw.core/text)
  http://download.oracle.com/javase/tutorial/uiswing/components/editorpane.html

styled-text

function

Usage: (styled-text & args)

Create a text pane.
Supports the following options:

  :text         text content.
  :wrap-lines?  If true wraps lines.
                This only works if the styled text is wrapped
                in (seesaw.core/scrollable). Doing so will cause
                a grey area to appear to the right of the text.
                This can be avoided by calling
                  (.setBackground (.getViewport s) java.awt.Color/white)
                on the scrollable s.
  :styles       Define styles, should be a list of vectors of form:
                [identifier & options]
                Where identifier is a string or keyword
                Options supported:
                  :font        A font family name as keyword or string.
                  :size        An integer.
                  :color       See (seesaw.color/to-color)
                  :background  See (seesaw.color/to-color)
                  :bold        bold if true.
                  :italic      italic if true.
                  :underline   underline if true.

See:
  (seesaw.core/style-text!)
  http://download.oracle.com/javase/6/docs/api/javax/swing/JTextPane.html

tabbed-panel

function

Usage: (tabbed-panel & opts)

Create a JTabbedPane. Supports the following properties:

  :placement Tab placement, one of :bottom, :top, :left, :right.
  :overflow  Tab overflow behavior, one of :wrap, :scroll.
  :tabs      A list of tab descriptors. See below

A tab descriptor is a map with the following properties:

  :title     Title of the tab or a component to be displayed.
  :tip       Tab's tooltip text
  :icon      Tab's icon, passed through (icon)
  :content   The content of the tab, passed through (make-widget) as usual.

Returns the new JTabbedPane.

Notes:

The currently selected tab can be retrieved with the (selection) function.
It returns a map similar to the tab descriptor with keys :title, :content,
and :index.

Similarly, a tab can be programmatically selected with the
(selection!) function, by passing one of the following values:

  * A number - The index of the tab to select
  * A string - The title of the tab to select
  * A to-widget-able - The content of the tab to select
  * A map as returned by (selection) with at least an :index, :title, or
    :content key.

Furthermore, you can be notified for when the active tab changes by
listening for the :selection event:

  (listen my-tabbed-panel :selection (fn [e] ...))

See:
  http://download.oracle.com/javase/6/docs/api/javax/swing/JTabbedPane.html
  (seesaw.core/selection)
  (seesaw.core/selection!)

table

function

Usage: (table & args)

Create a table (JTable). Additional options:

  :model A TableModel, or a vector. If a vector, then it is used as
         arguments to (seesaw.table/table-model).
  :show-grid? Whether to show the grid lines of the table.
  :show-horizontal-lines? Whether to show vertical grid lines
  :show-vertical-lines?   Whether to show horizontal grid lines
  :fills-viewport-height?
  :auto-reseize The behavior of columns when the table is resized. One of:
         :off                Do nothing to column widths
         :next-column        When a column is resized, take space from next column
         :subsequent-columns Change subsequent columns to presercve total width of table
         :last-column        Apply adjustments to last column only
         :all-columns        Proportionally resize all columns
    Defaults to :subsequent-columns. If you're wondering where your horizontal scroll
    bar is, try setting this to :off.

Example:

  (table
    :model [:columns [:age :height]
            :rows    [{:age 13 :height 45}
                      {:age 45 :height 13}]])

Notes:

See:
  seesaw.table/table-model
  seesaw.examples.table
  http://download.oracle.com/javase/6/docs/api/javax/swing/JTable.html

text

function

Usage: (text & args)

Create a text field or area. Given a single argument, creates a JTextField
using the argument as the initial text value. Otherwise, supports the
following additional properties:

  :text         Initial text content
  :multi-line?  If true, a JTextArea is created (default false)
  :editable?    If false, the text is read-only (default true)
  :margin
  :caret-color          Color of caret (see seesaw.color)
  :caret-position       Caret position as zero-based integer offset
  :disabled-text-color  A color value
  :selected-text-color  A color value
  :selection-color      A color value


The following properties only apply if :multi-line? is false:

  :columns Number of columns of text
  :halign  Horizontal text alignment (:left, :right, :center, :leading, :trailing)

The following properties only apply if :multi-line? is true:

  :wrap-lines?  If true (and :multi-line? is true) lines are wrapped.
                (default false)
  :tab-size     Tab size in spaces. Defaults to 8. Only applies if :multi-line?
                is true.
  :rows         Number of rows if :multi-line? is true (default 0).

To listen for document changes, use the :listen option:

  (text :listen [:document #(... handler ...)])

or attach a listener later with (listen):

  (text :id :my-text ...)
      ...
  (listen (select root [:#my-text]) :document #(... handler ...))

Given a single widget or document (or event) argument, retrieves the
text of the argument. For example:

    user=> (def t (text "HI"))
    user=> (text t)
    "HI"

See:
  http://download.oracle.com/javase/6/docs/api/javax/swing/JTextArea.html
  http://download.oracle.com/javase/6/docs/api/javax/swing/JTextField.html

text!

function

Usage: (text! targets value)

Set the text of widget(s) or document(s). targets is an object that can be
turned into a widget or document, or a list of such things. value is the new
text value to be applied. Returns targets.

target may be one of:

  A widget
  A widget-able thing like an event
  A Document
  A DocumentEvent

The resulting text in the widget depends on the type of value:

  A string                               - the string
  A URL, File, or anything "slurpable" - the slurped value
  Anythign else                          - (resource value)

Example:

    user=> (def t (text "HI"))
    user=> (text! t "BYE")
    user=> (text t)
    "BYE"

    ; Put the contents of a URL in editor
    (text! editor (java.net.URL. "http://google.com"))

Notes:

  This applies to the :text property of new text widgets and config! as well.

timer

var

Alias of seesaw.timer/timer:
Creates a new Swing timer that periodically executes the single-argument
  function f. The argument is a "state" of the timer. Each time the function
  is called its previous return value is passed to it. Kind of like (reduce)
  but spread out over time :) The following options are supported:

    :initial-value The first value passed to the handler function. Defaults to nil.
    :initial-delay Delay, in milliseconds, of first call. Defaults to 0.
    :delay         Delay, in milliseconds, between calls. Defaults to 1000.
    :repeats?      If true, the timer runs forever, otherwise, it's a
                  "one-shot" timer. Defaults to true.
    :start?        Whether to start the timer immediately. Defaults to true.

  See http://download.oracle.com/javase/6/docs/api/javax/swing/Timer.html

to-root

function

Usage: (to-root w)

Get the frame or window that contains the given widget. Useful for APIs
like JDialog that want a JFrame, when all you have is a widget or event.
Note that w is run through (to-widget) first, so you can pass event object
directly to this.

function

Usage: (to-widget v)

Try to convert the input argument to a widget based on the following rules:

  nil -> nil
  java.awt.Component -> return argument unchanged
  java.util.EventObject -> return the event source

See:
  (seeseaw.to-widget)

toggle

function

Usage: (toggle & args)

Same as (seesaw.core/button), but creates a toggle button. Use :selected? option
to set initial state.

See:
  (seesaw.core/button)

toggle-full-screen!

function

Usage: (toggle-full-screen! device window)
       (toggle-full-screen! window)

Toggle the full-screen state of the given window/frame.

function

Usage: (toolbar & opts)

Create a JToolBar. The following properties are supported:

  :floatable?  Whether the toolbar is floatable.
  :orientation Toolbar orientation, :horizontal or :vertical
  :items       Normal list of widgets to add to the toolbar. :separator
               creates a toolbar separator.

Notes:

See:
  http://download.oracle.com/javase/6/docs/api/javax/swing/JToolBar.html

top-bottom-split

function

Usage: (top-bottom-split top bottom & args)

Create a top/bottom (vertical) split pane with the given widgets. See
(seesaw.core/splitter) for additional options. Options are given after
the two widgets.

Notes:

See:
  (seesaw.core/splitter)
  http://download.oracle.com/javase/6/docs/api/javax/swing/JSplitPane.html

tree

function

Usage: (tree & args)

Create a tree (JTree). Additional options:

Notes:

See:

  http://download.oracle.com/javase/6/docs/api/javax/swing/JTree.html

user-data

function

Usage: (user-data w)

Convenience function to retrieve the value of the :user-data option
passed to the widget at construction. The widget parameter is passed
through (to-widget) first so events and other objects can also be
used.

Examples:

  (user-data (label :text "HI!" :user-data 99))
  ;=> 99

value

function

Usage: (value target)

Return the 'value' of a widget. target is passed through (to-widget) as usual.

Basically, there are two possibilities:

  * It's a container: A map of widget values keyed by :id is built
      recursively from all its children.
  * The 'natural' value for the widget is returned, usually the text,
    or the current selection of the widget.

See:
  (seesaw.core/value!)
  (seesaw.core/selection)
  (seesaw.core/group-by-id)

This idea is shamelessly borrowed from Clarity https://github.com/stathissideris/clarity

value!

function

Usage: (value! target v)

Set the 'value' of a widget. This is the dual of (seesaw.core/value). target
is passed through (to-widget) as usual.

Basically, there are two possibilities:

  * target is a container: The value is a map of widget values keyed by :id. These
      values are applied to all descendants of target.
  * otherwise, v is a new 'natural' value for the widget, usually the text,
    or the current selection of the widget.

In either case (to-widget target) is returned.

Examples:

  Imagine there's widget :foo, :bar, :yum in frame f:

    (value! f {:foo "new foo text" :bar 99 :yum "new yum text"})

See:
  (seesaw.core/value)
  (seesaw.core/selection)
  (seesaw.core/group-by-id)

This idea is shamelessly borrowed from Clarity https://github.com/stathissideris/clarity

vertical-panel

function

Usage: (vertical-panel & opts)

Create a panel where widgets are arranged vertically Options:

  :items List of widgets (passed through make-widget)

See http://download.oracle.com/javase/6/docs/api/javax/swing/BoxLayout.html

width

function

Usage: (width w)

Returns the width of the given widget in pixels

window

function

Usage: (window & {:keys [width height visible? size], :as opts})

Create a JWindow. NOTE: A JWindow is a top-level window with no decorations,
i.e. no title bar, no menu, no nothin'. Usually you want (seesaw.core/frame)
if your just showing a normal top-level app.

Options:

  :id       id of the window, used by (select).
  :width    initial width. Note that calling (pack!) will negate this setting
  :height   initial height. Note that calling (pack!) will negate this setting
  :size     initial size. Note that calling (pack!) will negate this setting
  :minimum-size minimum size of frame, e.g. [640 :by 480]
  :content  passed through (make-widget) and used as the frame's content-pane
  :visible?  whether frame should be initially visible (default false)

returns the new window

Examples:

  ; Create a window, pack it and show it.
  (-> (window :content "I'm a label!")
    pack!
    show!)

  ; Create a frame with an initial size (note that pack! isn't called)
  (show! (window :content "I'm a label!" :width 500 :height 600))

Notes:
  Unless :visible? is set to true, the window will not be displayed until (show!)
  is called on it.

  Call (pack!) on the frame if you'd like the window to resize itself to fit its
  contents. Sometimes this doesn't look like crap.

See:
  (seesaw.core/show!)
  (seesaw.core/hide!)
  (seesaw.core/move!)
  http://download.oracle.com/javase/6/docs/api/javax/swing/JWindow.html

with-password*

function

Usage: (with-password* field handler)

Retrieve the password of a password field and passes it to the given handler
function as an array or characters. Upon completion, the array is zero'd out
and the value returned by the handler is returned.

This is the 'safe' way to access the password. The (text) function will work too
but that method is discouraged, at least by the JPasswordField docs.

Example:

  (with-password* my-password-field
    (fn [password-chars]
      (... do something with chars ...)))

See:
  (seesaw.core/password)
  (seesaw.core/text)
  http://download.oracle.com/javase/6/docs/api/javax/swing/JPasswordField.html

with-widgets

macro

Usage: (with-widgets widgets & body)

Macro to ease construction of multiple widgets. The first argument
is a vector of widget constructor forms, each with an :id option.
The name of the value of each :id is used to generate a binding in
the scope of the macro.

Examples:

  (with-widgets [(label :id :foo :text "foo")
                 (button :id :bar :text "bar")]
     ...)

  ; is equivalent to
  (let [foo (label :id :foo :text "foo")
        bar (button :id :bar :text "bar")]
     ...)

Notes:

If you're looking for something like this to reduce boilerplate with
selectors on multiple widgets, see (seesaw.core/group-by-id).

See:
  (seesaw.core/group-by-id)

xyz-panel

function

Usage: (xyz-panel & opts)

Creates a JPanel on which widgets can be positioned arbitrarily by client
code. No layout manager is installed.

Initial widget positions can be given with their :bounds property. After
construction they can be moved with the (seesaw.core/move!) function.

Examples:

  ; Create a panel with a label positions at (10, 10) with width 200 and height 40.
  (xyz-panel :items [(label :text "The Black Lodge" :bounds [10 10 200 40]))

  ; Move a widget up 50 pixels and right 25 pixels
  (move! my-label :by [25 -50])

Notes:

See:
  (seesaw.core/move!)

Logo & site design by Tom Hickey.
Clojure auto-documentation system by Tom Faulhaber.

Seesaw API Documentation

Table of Contents

API for seesaw.core - Seesaw

Overview

Public Variables and Functions

ConfigAction

ConfigIcon

ConfigModel

ConfigText

SelectionModeConfig

action

action-option

add!

alert

all-frames

assert-ui-thread

border-panel

button

button-group

canvas

card-panel

checkbox

checkbox-menu-item

combobox

config

config!

construct

custom-dialog

dialog

dispose!

editor-pane

flow-panel

form-panel

frame

full-screen!

full-screen-window

full-screen?

grid-panel

group-by-id

height

hide!

horizontal-panel

id-for

id-of

input

invoke-later

invoke-now

invoke-soon

label

left-right-split

listbox

listen

make-widget

menu

menu-item

menubar

model-option

move!

native!

pack!

paintable

password

popup

progress-bar

radio

radio-menu-item

remove!

repaint!

replace!

request-focus!

return-from-dialog

scroll!

scrollable

select

select-with

selection

selection!

separator

show!

show-card!