The Shoes Manual

The Styles Master List

You want to mess with the look of things? Well, throughout Shoes, styles are used to change the way elements appear. In some cases, you can even style an entire class of elements. (Like giving all paragraphs a certain font.)

Styles are easy to spot. They usually show up when the element is created.

 Shoes.app title: "A Styling Sample" do
   para "Red with an underline", stroke: red, underline: "single"
 end

Here we've got a :title style on the app. And on the paragraph inside the app, a red :stroke style and an :underline style.

The style hash can also be changed by using the style method, available on every element and slot.

 Shoes.app title: "A Styling Sample" do
   @text = para "Red with an underline"
   @text.style(stroke: red, underline: "single")
 end

Most styles can also be set by calling them as methods. (I'd use the manual search to find the method.)

 Shoes.app title: "A Styling Sample" do
   @text = para "Red with an underline"
   @text.stroke = red
   @text.underline = "single"
 end

Rather than making you plow through the whole manual to figure out what styles go where, this helpful page speeds through every style in Shoes and suggests where that style is used.

:align » a string

For: banner, caption, code, del, em, ins, inscription, link, para, span, strong, sub, sup, subtitle, tagline, title

The alignment of the text. It is either:

"left" - Align the text to the left.
"center" - Align the text in the center.
"right" - Align the text to the right.

:angle » a number

For: background, border, gradient.

The angle at which to apply a gradient. Normally, gradient colors range from top to bottom. If the :angle is set to 90, the gradient will rotate 90 degrees counter-clockwise and the gradient will go from left to right.

:attach » a slot or element

For: flow, stack.

Pins a slot relative to another slot or element. Also, one may write :attach => Window to position the slot at the window's top, left corner. Taking this a bit further, the style :top => 10, :left => 10, :attach => Window would place the slot at (10, 10) in the window's coordinates.

If a slot is attached to an element that moves, the slot will move with it. If the attachment is reset to nil, the slot will flow in with the other objects that surround, as normal.

:autoplay » true or false

For: video.

Should this video begin playing after it appears? If set to true, the video will start without asking the user.

:bottom » a number

For: all slots and elements.

Sets the pixel coordinate of an element's lower edge. The edge is placed relative to its container's lower edge. So, :bottom => 0 will align the element so that its bottom edge and the bottom edge of its slot touch.

:cap » :curve or :rect or :project

For: arc, arrow, border, flow, image, mask, rect, star, shape, stack.

Sets the shape of the line endpoint, whether curved or square. See the cap method for more explanation.

:center » true or false

For: arc, image, oval, rect, shape.

Indicates whether the :top and :left coordinates refer to the center of the shape or not. If set to true, this is similar to setting the transform method to :center.

:change » a proc

For: edit_box, edit_line, list_box.

The change event handler is stored in this style. See the change method for the edit_box, as an example.

:checked » true or false

For: check, radio.

Is this checkbox or radio button checked? If set to true, the box is checked. Also see the checked= method.

:choose » a string

For: list_box.

Sets the currently chosen item in the list. More information at choose.

:click » a proc

For: arc, arrow, banner, button, caption, check, flow, image, inscription, line, link, mask, oval, para, radio, rect, shape, stack, star, subtitle, tagline, title.

The click event handler is stored in this style. See the click method for a description.

:curve » a number

For: background, border, rect.

The radius of curved corners on each of these rectangular elements. As an example, if this is set to 6, the corners of the rectangle are given a curve with a 6-pixel radius.

:displace_left » a number

For: all slots and elements.

Moves a shape, text block or any other kind of object to the left or right. A positive number displaces to the right by the given number of pixels; a negative number displaces to the left. Displacing an object doesn't effect the actual layout of the page. Before using this style, be sure to read the displace docs, since its behavior can be a bit surprising.

:displace_top » a number

For: all slots and elements.

Moves a shape, text block or any other kind of object up or down. A positive number moves the object down by this number of pixels; a negative number moves it up. Displacing doesn't effect the actual layout of the page or the object's true coordinates. Read the displace docs, since its behavior can be a bit surprising.

:emphasis » a string

For: banner, caption, code, del, em, ins, inscription, link, para, span, strong, sub, sup, subtitle, tagline, title.

Styles the text with an emphasis (commonly italicized.)

This style recognizes three possible settings:

"normal" - the font is upright.
"oblique" - the font is slanted, but in a roman style.
"italic" - the font is slanted in an italic style.

:family » a string

For: banner, caption, code, del, em, ins, inscription, link, para, span, strong, sub, sup, subtitle, tagline, title.

Styles the text with a given font family. The string should contain the family name or a comma-separated list of families.

:fill » a hex code, a Shoes::Color or a range of either

For: arc, arrow, background, banner, caption, code, del, em, flow, image, ins, inscription, line, link, mask, oval, para, rect, shape, span, stack, star, strong, sub, sup, subtitle, tagline, title.

The color of the background pen. For shapes, this is the fill color, the paint inside the shape. For text stuffs, this color is painted in the background (as if marked with a highlighter pen.)

:font » a string

For: banner, caption, code, del, em, ins, inscription, link, para, span, strong, sub, sup, subtitle, tagline, title.

Styles the text with a font description. The string is pretty flexible, but can take the form "[FAMILY-LIST] [STYLE-OPTIONS] [SIZE]", where FAMILY-LIST is a comma separated list of families optionally terminated by a comma, STYLE_OPTIONS is a whitespace separated list of words where each WORD describes one of style, variant, weight, stretch, or gravity, and SIZE is a decimal number (size in points) or optionally followed by the unit modifier "px" for absolute size. Any one of the options may be absent. If FAMILY-LIST is absent, then the default font family (Arial) will be used.

:group » a string

For: radio.

Indicates what group a radio button belongs to. Without this setting, radio buttons are grouped together with other radio buttons in their immediate slot. "Grouping" radio buttons doesn't mean they'll be grouped next to each other on the screen. It means that only one radio button from the group can be selected at a time.

By giving this style a string, the radio button will be grouped with other radio buttons that have the same group name.

:height » a number

For: all slots and elements.

Sets the pixel height of this object. If the number is a decimal number, the height becomes a percentage of its parent's height (with 0.0 being 0% and 1.0 being 100%.)

:hidden » true or false

For: all slots and elements.

Hides or shows this object. Any object with :hidden => true are not displayed on the screen. Neither are its children.

:inner » a number

For: star.

The size of the inner radius (in pixels.) The inner radius describes the solid circle within the star where the points begin to separate.

:items » an array

For: list_box.

The list of selections in the list box. See the list_box method for an example.

:justify » true or false

For: banner, caption, code, del, em, ins, inscription, link, para, span, strong, sub, sup, subtitle, tagline, title

Evenly spaces the text horizontally.

:kerning » a number

For: banner, caption, code, del, em, ins, inscription, link, para, span, strong, sub, sup, subtitle, tagline, title.

Adds to the natural spacing between letters, in pixels.

:leading » a number

For: banner, caption, inscription, para, subtitle, tagline, title.

Sets the spacing between lines in a text block. Defaults to 4 pixels.

:left » a number

For: all slots and elements.

Sets the left coordinate of this object to a specific pixel. Setting :left => 10 places the object's left edge ten pixels away from the left edge of the slot containing it. If this style is left unset (or set to nil,) the object will flow in with the other objects surrounding it.

:margin » a number or an array of four numbers

For: all slots and elements.

Margins space an element out from its surroundings. Each element has a left, top, right, and bottom margin. If the :margin style is set to a single number, the spacing around the element uniformly matches that number. In other words, if :margin => 8 is set, all the margins around the element are set to eight pixels in length.

This style can also be given an array of four numbers in the form [left, top, right, bottom].

:margin_bottom » a number

For: all slots and elements.

Sets the bottom margin of the element to a specific pixel size.

:margin_left » a number

For: all slots and elements.

Sets the left margin of the element to a specific pixel size.

:margin_right » a number

For: all slots and elements.

Sets the right margin of the element to a specific pixel size.

:margin_top » a number

For: all slots and elements.

Sets the top margin of the element to a specific pixel size.

:outer » a number

For: star.

Sets the outer radius (half of the total width) of the star, in pixels.

:points » a number

For: star.

How many points does this star have? A style of :points => 5 creates a five-pointed star.

:radius » a number

For: arc, arrow, background, border, gradient, oval, rect, shape.

Sets the radius (half of the diameter or total width) for each of these elements. Setting this is equivalent to setting both :width and :height to double this number.

:right » a number

For: all slots and elements.

Sets the pixel coordinate of an element's right edge. The edge is placed relative to its container's rightmost edge. So, :right => 0 will align the element so that its own right edge and the right edge of its slot touch. Whereas :right => 20 will position the right edge of the element off to the left of its slot's right edge by twenty pixels.

:rise » a number

For: banner, caption, code, del, em, ins, inscription, link, para, span, strong, sub, sup, subtitle, tagline, title.

Lifts or plunges the font baseline for some text. For example, a sup has a :rise of 10 pixels. Conversely, the sub element has a :rise of -10 pixels.

:scroll » true or false

For: flow, stack.

Establishes this slot as a scrolling slot. If :scroll => true is set, the slot will show a scrollbar if any of its contents go past its height. The scrollbar will appear and disappear as needed. It will also appear inside the width of the slot, meaning the slot's width will never change, regardless of whether there is a scrollbar or not.

:secret » true or false

For: ask, edit_line.

Used for password fields, this setting keeps any characters typed in from becoming visible on the screen. Instead, a replacement character (such as an asterisk) is show for each letter typed.

:size » a number

For: banner, caption, code, del, em, ins, inscription, link, para, span, strong, sub, sup, subtitle, tagline, title.

Sets the pixel size for the font used inside this text block or text fragment.

Font size may also be augmented, through use of the following strings:

"xx-small" - 57% of present size.
"x-small" - 64% of present size.
"small" - 83% of present size.
"medium" - no change in size.
"large" - 120% of present size.
"x-large" - 143% of present size.
"xx-large" - 173% of present size.

:state » a string

For: button, check, edit_box, edit_line, list_box, radio.

The :state style is for disabling or locking certain controls, if you don't want them to be edited.

Here are the possible style settings:

nil - the control is active and editable.
"readonly" - the control is active but cannot be edited.
"disabled" - the control is not active (grayed out) and cannot be edited.

:stretch » a string

For: banner, caption, code, del, em, ins, inscription, link, para, span, strong, sub, sup, subtitle, tagline, title.

Sets the font stretching used for a text object.

Possible settings are:

"condensed" - a smaller width of letters.
"normal" - the standard width of letters.
"expanded" - a larger width of letters.

:strikecolor » a Shoes::Color

For: banner, caption, code, del, em, ins, inscription, link, para, span, strong, sub, sup, subtitle, tagline, title.

The color used to paint any lines stricken through this text.

:strikethrough » a string

For: banner, caption, code, del, em, ins, inscription, link, para, span, strong, sub, sup, subtitle, tagline, title.

Is this text stricken through? Two options here:

"none" - no strikethrough
"single" - a single-line strikethrough.

:stroke » a hex code, a Shoes::Color or a range of either

For: arc, arrow, banner, border, caption, code, del, em, flow, image, ins, inscription, line, link, mask, oval, para, rect, shape, span, stack, star, strong, sub, sup, subtitle, tagline, title.

The color of the foreground pen. In the case of shapes, this is the color the lines are drawn with. For paragraphs and other text, the letters are printed in this color.

:strokewidth » a number

For: arc, arrow, border, flow, image, line, mask, oval, rect, shape, star, stack.

The thickness of the stroke, in pixels, of the line defining each of these shapes. For example, the number two would set the strokewidth to 2 pixels.

:text » a string

For: button, edit_box, edit_line.

Sets the message displayed on a button control, or the contents of an edit_box or edit_line.

:top » a number

For: all slots and elements.

Sets the top coordinate for an object, relative to its parent slot. If an object is set with :top => 40, this means the object's top edge will be placed 40 pixels beneath the top edge of the slot that contains it. If no :top style is given, the object is automatically placed in the natural flow of its slot.

:undercolor » a Shoes::Color

For: banner, caption, code, del, em, ins, inscription, link, para, span, strong, sub, sup, subtitle, tagline, title.

The color used to underline text.

:underline » a string

For: banner, caption, code, del, em, ins, inscription, link, para, span, strong, sub, sup, subtitle, tagline, title.

Dictates the style of underline used in the text.

The choices for this setting are:

"none" - no underline at all.
"single" - a continuous underline.
"double" - two continuous parallel underlines.
"low" - a lower underline, beneath the font baseline. (This is generally recommended only for single characters, particularly when showing keyboard accelerators.)
"error" - a wavy underline, usually found indicating a misspelling.

:variant » a string

For: banner, caption, code, del, em, ins, inscription, link, para, span, strong, sub, sup, subtitle, tagline, title.

Vary the font for a group of text. Two choices:

"normal" - standard font.
"smallcaps" - font with the lower case characters replaced by smaller variants of the capital characters.

:weight » a string

For: banner, caption, code, del, em, ins, inscription, link, para, span, strong, sub, sup, subtitle, tagline, title.

Set the boldness of the text. Commonly, this style is set to one of the following strings:

"ultralight" - the ultralight weight (= 200)
"light" - the light weight (= 300)
"normal" - the default weight (= 400)
"semibold" - a weight intermediate between normal and bold (= 600)
"bold" - the bold weight (= 700)
"ultrabold" - the ultrabold weight (= 800)
"heavy" - the heavy weight (= 900)

However, you may also pass in the numerical weight directly.

:width » a number

For: all slots and elements.

Sets the pixel width for the element. If the number is a decimal, the width is converted to a percentage (with 0.0 being 0% and 1.0 being 100%.) A width of 100% means the object fills its parent slot.

:wrap » a string

For: banner, caption, code, del, em, ins, inscription, link, para, span, strong, sub, sup, subtitle, tagline, title

How should the text wrap when it fills its width? Possible options are:

"word" - Break lines at word breaks.
"char" - Break lines between characters, thus breaking some words.
"trim" - Cut the line off with an ellipsis if it goes too long.

Next: Classes List