[Pythoncard-users] Button documentation

Below is the start of some documentation for the Button widget. Feel free to
make suggestions on wording, layout, etc. I'm not good at documenation, so
your suggestions can't be any worse than what I've done.

Button is the simplest widget, but most of the other widgets share its
attributes and events, so if we can get the Button documenation to a point
that we are happy with, we can put the text into an HTML layout and then
document the remaining widgets following the same style. I don't have time
today, but tomorrow I'm going to look at some other reference works and see
if there is a more appropriate format.

You can look at spec.py and widget.py to see the specification the framework
actually uses and the actual Button class and its methods.

ka
---

Button
    Attributes:

    backgroundColor
        color: tuple (r, g, b), "named color", or hex color string "#FF00FF"
        color is always returned as an rgb tuple

    command
        string

    enabled
        boolean

    font
        Font

    foregroundColor
        color: tuple (r, g, b), "named color", or hex color string "#FF00FF"
        color is always returned as an rgb tuple

    label   (mandatory)
        string

    name    (mandatory, read-only)
        string

    position
        tuple (x, y)
                specifying -1 for either x or y will use the default x or y
position

    size
        tuple (width, height)
                specifying -1 for either width or height will use the
default
                    width or height

    toolTip
        string

    visible
        boolean


    # I need to revise some of the widget.py code before documenting the
'methods' completely. This section is more of a note to myself than what
would go into the online docs.

    Methods:

        getId()
            this should be a read-only attribute



The following are also methods, but I think they will be changed. In the
case of addEventListener and notifyEventListeners you won't see them
anymore, because they will start with a leading underscore and I think
setFocus() will just be another attribute.


        setFocus()
            see if this works as an attribute
            focus = 1 or 0


        addEventListener, notifyEventListeners should start with an
underscore



   Events:
      gainFocus
      loseFocus
      mouseClick
      mouseContextDoubleClick
      mouseContextDown
      mouseContextUp
      mouseDoubleClick
      mouseDown
      mouseDrag
      mouseEnter
      mouseLeave
      mouseMiddleDoubleClick
      mouseMiddleDown
      mouseMiddleUp
      mouseMove
      mouseUp


    Handling events:
      Events are handled by defining a method handler in the background
class. The method name takes the form of 'on_widgetName_event'. For example,
to handle a 'mouseClick' for a Button widget with a name of 'button1' you
would create a method:

      def on_button1_mouseClick(self, target, event):
          print 'hello ' + target.name

      Which outputs:

>>> hello button1



    Event order:
        gainFocus, mouseDown, mouseUp, mouseClick


        The best way to see events in action is to just start a sample like
'proof' with the Message Watcher (-m command-line option), then uncheck the
"Hide unused" checkbox. For example, here is a sequence copied from the
Message Watcher, after clicking on 'Button 1' I moved the mouse and clicked
on 'Button 2':

mouseClick : button1
(mouseMove : button1)
(mouseMove : button1)
(mouseMove : button1)
(mouseLeave : button1)
(mouseEnter : button2)
(mouseMove : button2)
(mouseMove : button2)
(mouseMove : button2)
(mouseMove : button2)
(mouseMove : button2)
(mouseMove : button2)
(mouseMove : button2)
(mouseMove : button2)
(mouseMove : button2)
(mouseMove : button2)
(loseFocus : button1)
(gainFocus : button2)
(mouseDown : button2)
(mouseUp : button2)
(mouseClick : button2)
(mouseMove : button2)


     The messages in parenthesis are messages (events) not handled by a
method (handler) in the background, so only the 'mouseClick' for 'button1'
had a handler in the example above.


    Example initialization string in a resource (.rsrc.py) file:

        {'type':'Button',
         'name':'button1',
         'position':(10, 10),
         'label':'Button 1'
        }