The Shoes Manual

Events

Wondering how to catch stray mouse clicks or keyboard typing? Events are sent to a slot whenever a mouse moves inside the slot. Or whenever a key is pressed. Even when the slot is created or destroyed. You can attach a block to each of these events.

Mouse events include motion, click, hover and leave. Keyboard typing is represented by the keypress event. And the start and finish events indicate when a canvas comes into play or is discarded.

So, let's say you want to change the background of a slot whenever the mouse floats over it. We can use the hover event to change the background when the mouse comes inside the slot. And leave to change back when the mouse floats away.

 Shoes.app do
   s = stack width: 200, height: 200 do
     background red
     hover do
       s.clear { background blue }
     end
     leave do
       s.clear { background red }
     end
   end
 end

The click block is called when a mouse button is clicked. The button is the number of the mouse button which has been pressed. The left and top are the mouse coordinates at which the click happened.

To catch the moment when the mouse is unclicked, see the release event.

When a slot is removed, it's finish event occurs. The finish block is immediately handed self, the slot object which has been removed.

The hover event happens when the mouse enters the slot. The block gets self, meaning the object which was hovered over.

To catch the mouse exiting the slot, check out the leave event.

Whenever a key (or combination of keys) is pressed, the block gets called. The block is sent a key which is a string representing the character (such as the letter or number) on the key. For special keys and key combos, a Ruby symbol is sent, rather than a string.

So, for example, if Shift-a is pressed, the block will get the string "A".

However, if the F1 key is pressed, the :f1 symbol is received. For Shift-F1, the symbol would be :shift_f1.

The modifier keys are control, shift and alt. They appear in that order. If Shift-Control-Alt-PgUp is pressed, the symbol will be :control_shift_alt_page_up.

One thing about the shift key. You won't see the shift key on most keys. On US keyboards, Shift-7 is an ampersand. So you'll get the string "&" rather than :shift_5. And, if you press Shift-Alt-7 on such a keyboard, you'll get the symbol: :alt_&. You'll only see the shift modifier on the special keys listed a few paragraphs down.

 Shoes.app do
   @info = para "NO KEY is PRESSED."
   keypress do |k|
     @info.replace "#{k.inspect} was PRESSED."
   end
 end

Keep in mind that Shoes itself uses a few hotkeys. Alt-Period (:alt_.), Alt-Question (:alt_?) and Alt-Slash (:alt_/) are reserved for Shoes.

The list of special keys is as follows: :escape, :delete, :backspace, :tab, :page_up, :page_down, :home, :end, :left, :up, :right, :down, :f1, :f2, :f3, :f4, :f5, :f6, :f7, :f8, :f9, :f10, :f11 and :f12.

One caveat to all of those rules: normally the Return key gives you a string "\n". When pressed with modifier keys, however, you end up with :control_enter, :control_alt_enter, :shift_alt_enter and the like.

The leave event takes place when the mouse cursor exits a slot. The moment it no longer is inside the slot's edges. When that takes place, the block is called with self, the slot object which is being left.

Also see hover if you'd like to detect the mouse entering a slot.

The motion block gets called every time the mouse moves around inside the slot. The block is handed the cursor's left and top coordinates.

 Shoes.app width: 200, height: 200 do
   background black
   fill white
   @circ = oval 0, 0, 100, 100
   motion do |top, left|
     @circ.move top - 50, left - 50
   end
 end

The release block runs whenever the mouse is unclicked (on mouse up). When the finger is lifted. The button is the number of the button that was depressed. The left and top are the coordinates of the mouse at the time the button was released.

To catch the actual mouse click, use the click event.

The first time the slot is drawn, the start event fires. The block is handed self, the slot object which has just been drawn.

Next: Manipulation Blocks