The Shoes Manual

Common Methods

A few methods are shared by every little element in Shoes. Moving, showing, hiding. Removing an element. Basic and very general things. This list encompasses those common commands.

One of the most general methods of all is the style method (which is also covered as the style method for slots.)

 Shoes.app do
   stack do
     # Background, text and a button: both are elements!
     @back  = background green
     @text  = banner "A Message for You, Rudy"
     @press = button "Stop your messin about!"
     # And so, both can be styled.
     @text.style size: 12, stroke: red, margin: 10
     @press.style width: 400
     @back.style height: 10
   end
 end

For specific commands, see the other links to the left in the Elements section. Like if you want to pause or play a video file, check the Video section, since pausing and playing is peculiar to videos. No sense pausing a button.

displace(left: a number, top: a number) » self

Displacing an element moves it. But without changing the layout around it. This is great for subtle animations, especially if you want to reserve a place for an element while it is still animating. Like maybe a quick button shake or a slot sliding into view.

When you displace an element, it moves relative to the upper-left corner where it was placed. So, if an element is at the coordinates (20, 40) and you displace it 2 pixels left and 6 pixels on top, you end up with the coordinates (22, 46).

 Shoes.app do
   flow margin: 12 do
     # Set up three buttons
     button "One"
     @two = button "Two"
     button "Three"
     # Bounce the second button
     animate do |i|
       @two.displace(0, (Math.sin(i) * 6).to_i)
     end
   end
 end

Notice that while the second button bounces, the other two buttons stay put. If we used a normal move in this situation, the second button would be moved out of the layout and the buttons would act as if the second button wasn't there at all. (See the move example.)

Of particular note: if you use the left and top methods to get the coordinates of a displaced element, you'll just get back the normal coordinates. As if there was no displacement. Displacing is just intended for quick animations!

height() » a number

The vertical screen size of the element in pixels. In the case of images, this is not the full size of the image. This is the height of the element as it is shown right now.

If you have a 150x150 pixel image and you set the width to 50 pixels, this method will return 50.

Also see the width method for an example and some other comments.

hide() » self

Hides the element, so that it can't be seen. See also show and toggle.

left() » a number

Gets you the pixel position of the left edge of the element.

move(left: a number, top: a number) » self

Moves the element to a specific pixel position within its slot. The element is still inside the slot. But it will no longer be stacked or flowed in with the other stuff in the slot. The element will float freely, now absolutely positioned instead.

 Shoes.app do
   flow margin: 12 do
     # Set up three buttons
     button "One"
     @two = button "Two"
     button "Three"
     # Bounce the second button
     animate do |i|
       @two.move(40, 40 + (Math.sin(i) * 6).to_i)
     end
   end
 end

The second button is moved to a specific place, allowing the third button to slide over into its place. If you want to move an element without shifting other pieces, see the displace method.

parent() » a Shoes::Stack or Shoes::Flow

Gets the object for this element's container. Also see the slot's contents to do the opposite: get a container's elements.

remove() » self

Removes the element from its slot. (In other words: throws it in the garbage.) The element will no longer be displayed.

show() » self

Reveals the element, if it is hidden. See also hide and toggle.

style() » styles

Gives you the full set of styles applied to this element, in the form of a Hash. While methods like width and height and top give you back specific pixel dimensions, using style[:width] or style[:top], you can get the original setting (things like "100%" for width or "10px" for top.)

 Shoes.app do
   # A button which take up the whole page
   @b = button "All of it", width: 1.0, height: 1.0
   # When clicked, show the styles
   @b.click { alert(@b.style.inspect) }
 end

style(styles) » styles

Changes the style of an element. This could include the :width and :height of an element, the font :size of some text, the :stroke and :fill of a shape. Or any other number of style settings.

toggle() » self

Hides an element if it is shown. Or shows the element, if it is hidden.

top() » a number

Gets the pixel position of the top edge of the element.

width() » a number

Gets the pixel width for the full size of the element. This method always returns an exact pixel size. In the case of images, this is not the full width of the image, just the size it is shown at. See the height method for more.

Also, if you create an element with a width of 100% and that element is inside a stack which is 120 pixels wide, you'll get back 120. However, if you call style[:width], you'll get "100%".

 Shoes.app do
   stack width: 120 do
     @b = button "Click me", width: "100%" do
       alert "button.width = #{@b.width}\n" +
         "button.style[:width] = #{@b.style[:width]}"
     end
   end
 end

In order to set the width, you'll have to go through the style method again. So, to set the button to 150 pixels wide: @b.style(:width => 150).

To let Shoes pick the element's width, go with @b.style(:width => nil) to empty out the setting.

Next: Background