shoes-manual 4.0.0

Sign up to get free protection for your applications and to get access to all the features.
Files changed (68) hide show
  1. checksums.yaml +7 -0
  2. data/.gitignore +15 -0
  3. data/Gemfile +3 -0
  4. data/LICENSE.txt +22 -0
  5. data/README.md +69 -0
  6. data/Rakefile +2 -0
  7. data/lib/shoes/manual.rb +45 -0
  8. data/lib/shoes/manual/app.rb +512 -0
  9. data/lib/shoes/manual/version.rb +5 -0
  10. data/shoes-manual.gemspec +27 -0
  11. data/static/PKGBUILD +47 -0
  12. data/static/Shoes.icns +0 -0
  13. data/static/avatar.png +0 -0
  14. data/static/code_highlighter.js +188 -0
  15. data/static/code_highlighter_ruby.js +26 -0
  16. data/static/downloading.png +0 -0
  17. data/static/icon-debug.png +0 -0
  18. data/static/icon-error.png +0 -0
  19. data/static/icon-info.png +0 -0
  20. data/static/icon-warn.png +0 -0
  21. data/static/listbox_button1.png +0 -0
  22. data/static/listbox_button2.png +0 -0
  23. data/static/man-app.png +0 -0
  24. data/static/man-builds.png +0 -0
  25. data/static/man-builds1.png +0 -0
  26. data/static/man-editor-notepad.png +0 -0
  27. data/static/man-editor-osx.png +0 -0
  28. data/static/man-ele-background.png +0 -0
  29. data/static/man-ele-border.png +0 -0
  30. data/static/man-ele-button.png +0 -0
  31. data/static/man-ele-check.png +0 -0
  32. data/static/man-ele-editbox.png +0 -0
  33. data/static/man-ele-editline.png +0 -0
  34. data/static/man-ele-image.png +0 -0
  35. data/static/man-ele-listbox.png +0 -0
  36. data/static/man-ele-progress.png +0 -0
  37. data/static/man-ele-radio.png +0 -0
  38. data/static/man-ele-shape.png +0 -0
  39. data/static/man-ele-textblock.png +0 -0
  40. data/static/man-ele-video.png +0 -0
  41. data/static/man-intro-dmg.png +0 -0
  42. data/static/man-intro-exe.png +0 -0
  43. data/static/man-look-tiger.png +0 -0
  44. data/static/man-look-ubuntu.png +0 -0
  45. data/static/man-look-vista.png +0 -0
  46. data/static/man-run-osx.png +0 -0
  47. data/static/man-run-vista.png +0 -0
  48. data/static/man-run-xp.png +0 -0
  49. data/static/man-shot1.png +0 -0
  50. data/static/manual-en.txt +3531 -0
  51. data/static/manual-ja.txt +2829 -0
  52. data/static/manual.css +184 -0
  53. data/static/menu-corner1.png +0 -0
  54. data/static/menu-corner2.png +0 -0
  55. data/static/menu-gray.png +0 -0
  56. data/static/menu-left.png +0 -0
  57. data/static/menu-right.png +0 -0
  58. data/static/menu-top.png +0 -0
  59. data/static/shoes-dmg.jpg +0 -0
  60. data/static/shoes-icon-blue.png +0 -0
  61. data/static/shoes-icon-brown.png +0 -0
  62. data/static/shoes-icon.png +0 -0
  63. data/static/shoes-manual-apps.gif +0 -0
  64. data/static/shoes-manual-apps.png +0 -0
  65. data/static/shoes_main_window.png +0 -0
  66. data/static/stripe.png +0 -0
  67. data/static/tutor-back.png +0 -0
  68. metadata +193 -0
@@ -0,0 +1,5 @@
1
+ class Shoes
2
+ module Manual
3
+ VERSION = "4.0.0"
4
+ end
5
+ end
@@ -0,0 +1,27 @@
1
+ # coding: utf-8
2
+ lib = File.expand_path('../lib', __FILE__)
3
+ $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
4
+ require 'shoes/manual/version'
5
+
6
+ Gem::Specification.new do |spec|
7
+ spec.name = "shoes-manual"
8
+ spec.version = Shoes::Manual::VERSION
9
+
10
+ spec.authors = ["Team Shoes"]
11
+ spec.email = ["shoes@librelist.com"]
12
+ spec.homepage = "https://github.com/shoes/shoes-manual"
13
+ spec.summary = %q{Content for the Shoes manual}
14
+ spec.description = %q{Content and loading classes for the Shoes manual}
15
+ spec.license = "MIT"
16
+
17
+ spec.files = `git ls-files -z`.split("\x0")
18
+ spec.test_files = spec.files.grep(%r{^(test|spec|features)/})
19
+ spec.require_paths = ["lib"]
20
+
21
+ spec.add_dependency "shoes-highlighter", "~> 1.0", ">= 1.0.0"
22
+ spec.add_dependency "nokogiri", "~> 1.6.4.1", ">=1.6.4.1" # For converting the manual to HTML
23
+
24
+ spec.add_development_dependency "bundler", "~> 1.7"
25
+ spec.add_development_dependency "rake", "~> 10.0"
26
+ spec.add_development_dependency "pry", "~> 0.10.0"
27
+ end
@@ -0,0 +1,47 @@
1
+ # Original contributor: Michael Fellinger <m.fellinger@gmail.com>
2
+ # Updated by:
3
+ # Tapio Saarinen <admin@bitlong.org>
4
+ # Steve Klabnik <steve@steveklabnik.com>
5
+ # Michael Fellinger <m.fellinger@gmail.com>
6
+
7
+ pkgname=shoes
8
+ pkgver=3.0
9
+ pkgrel=1
10
+ pkgdesc="The best little GUI toolkit, for Ruby."
11
+ url="http://shoesrb.com/"
12
+ arch=(i686 x86_64)
13
+ license="MIT"
14
+ depends=('ruby' 'giflib' 'gtk2' 'curl' 'portaudio' 'tk')
15
+ makedepends=('git')
16
+ conflicts=('shoes')
17
+ replaces=('shoes')
18
+ provides=('shoes')
19
+ backup=()
20
+ install=
21
+ source=()
22
+ md5sums=()
23
+
24
+ _pkgname=shoes
25
+ _gitrepo="git://github.com/shoes/shoes.git"
26
+
27
+ build() {
28
+ cd $srcdir
29
+
30
+ msg "Getting source..."
31
+ if [ -d $_pkgname ]; then
32
+ cd $_pkgname
33
+ git pull || return 1
34
+ else
35
+ git clone $_gitrepo $_pkgname || return 1
36
+ cd $_pkgname
37
+ fi
38
+
39
+ rake
40
+ cd dist
41
+
42
+ mkdir -p $pkgdir/usr/{bin,lib/shoes}
43
+ cp -r * $pkgdir/usr/lib/shoes/
44
+
45
+ ln -s /usr/lib/shoes/shoes $pkgdir/usr/bin/shoes
46
+ install -D -m644 $srcdir/$_pkgname/COPYING $pkgdir/usr/share/licenses/$pkgname/LICENSE
47
+ }
Binary file
Binary file
@@ -0,0 +1,188 @@
1
+ /* Unobtrustive Code Highlighter By Dan Webb 11/2005
2
+ Version: 0.4
3
+
4
+ Usage:
5
+ Add a script tag for this script and any stylesets you need to use
6
+ to the page in question, add correct class names to CODE elements,
7
+ define CSS styles for elements. That's it!
8
+
9
+ Known to work on:
10
+ IE 5.5+ PC
11
+ Firefox/Mozilla PC/Mac
12
+ Opera 7.23 + PC
13
+ Safari 2
14
+
15
+ Known to degrade gracefully on:
16
+ IE5.0 PC
17
+
18
+ Note: IE5.0 fails due to the use of lookahead in some stylesets. To avoid script errors
19
+ in older browsers use expressions that use lookahead in string format when defining stylesets.
20
+
21
+ This script is inspired by star-light by entirely cunning Dean Edwards
22
+ http://dean.edwards.name/star-light/.
23
+ */
24
+
25
+ // replace callback support for safari.
26
+ if ("a".replace(/a/, function() {return "b"}) != "b") (function(){
27
+ var default_replace = String.prototype.replace;
28
+ String.prototype.replace = function(search,replace){
29
+ // replace is not function
30
+ if(typeof replace != "function"){
31
+ return default_replace.apply(this,arguments)
32
+ }
33
+ var str = "" + this;
34
+ var callback = replace;
35
+ // search string is not RegExp
36
+ if(!(search instanceof RegExp)){
37
+ var idx = str.indexOf(search);
38
+ return (
39
+ idx == -1 ? str :
40
+ default_replace.apply(str,[search,callback(search, idx, str)])
41
+ )
42
+ }
43
+ var reg = search;
44
+ var result = [];
45
+ var lastidx = reg.lastIndex;
46
+ var re;
47
+ while((re = reg.exec(str)) != null){
48
+ var idx = re.index;
49
+ var args = re.concat(idx, str);
50
+ result.push(
51
+ str.slice(lastidx,idx),
52
+ callback.apply(null,args).toString()
53
+ );
54
+ if(!reg.global){
55
+ lastidx += RegExp.lastMatch.length;
56
+ break
57
+ }else{
58
+ lastidx = reg.lastIndex;
59
+ }
60
+ }
61
+ result.push(str.slice(lastidx));
62
+ return result.join("")
63
+ }
64
+ })();
65
+
66
+ var CodeHighlighter = { styleSets : new Array };
67
+
68
+ CodeHighlighter.addStyle = function(name, rules) {
69
+ // using push test to disallow older browsers from adding styleSets
70
+ if ([].push) this.styleSets.push({
71
+ name : name,
72
+ rules : rules,
73
+ ignoreCase : arguments[2] || false
74
+ })
75
+
76
+ function setEvent() {
77
+ // set highlighter to run on load (use LowPro if present)
78
+ if (typeof Event != 'undefined' && typeof Event.onReady == 'function')
79
+ return Event.onReady(CodeHighlighter.init.bind(CodeHighlighter));
80
+
81
+ var old = window.onload;
82
+
83
+ if (typeof window.onload != 'function') {
84
+ window.onload = function() { CodeHighlighter.init() };
85
+ } else {
86
+ window.onload = function() {
87
+ old();
88
+ CodeHighlighter.init();
89
+ }
90
+ }
91
+ }
92
+
93
+ // only set the event when the first style is added
94
+ if (this.styleSets.length==1) setEvent();
95
+ }
96
+
97
+ CodeHighlighter.init = function() {
98
+ if (!document.getElementsByTagName) return;
99
+ if ("a".replace(/a/, function() {return "b"}) != "b") return; // throw out Safari versions that don't support replace function
100
+ // throw out older browsers
101
+
102
+ var codeEls = document.getElementsByTagName("CODE");
103
+ // collect array of all pre elements
104
+ codeEls.filter = function(f) {
105
+ var a = new Array;
106
+ for (var i = 0; i < this.length; i++) if (f(this[i])) a[a.length] = this[i];
107
+ return a;
108
+ }
109
+
110
+ var rules = new Array;
111
+ rules.toString = function() {
112
+ // joins regexes into one big parallel regex
113
+ var exps = new Array;
114
+ for (var i = 0; i < this.length; i++) exps.push(this[i].exp);
115
+ return exps.join("|");
116
+ }
117
+
118
+ function addRule(className, rule) {
119
+ // add a replace rule
120
+ var exp = (typeof rule.exp != "string")?String(rule.exp).substr(1, String(rule.exp).length-2):rule.exp;
121
+ // converts regex rules to strings and chops of the slashes
122
+ rules.push({
123
+ className : className,
124
+ exp : "(" + exp + ")",
125
+ length : (exp.match(/(^|[^\\])\([^?]/g) || "").length + 1, // number of subexps in rule
126
+ replacement : rule.replacement || null
127
+ });
128
+ }
129
+
130
+ function parse(text, ignoreCase) {
131
+ // main text parsing and replacement
132
+ return text.replace(new RegExp(rules, (ignoreCase)?"gi":"g"), function() {
133
+ var i = 0, j = 1, rule;
134
+ while (rule = rules[i++]) {
135
+ if (arguments[j]) {
136
+ // if no custom replacement defined do the simple replacement
137
+ if (!rule.replacement) return "<span class=\"" + rule.className + "\">" + arguments[0] + "</span>";
138
+ else {
139
+ // replace $0 with the className then do normal replaces
140
+ var str = rule.replacement.replace("$0", rule.className);
141
+ for (var k = 1; k <= rule.length - 1; k++) str = str.replace("$" + k, arguments[j + k]);
142
+ return str;
143
+ }
144
+ } else j+= rule.length;
145
+ }
146
+ });
147
+ }
148
+
149
+ function highlightCode(styleSet) {
150
+ // clear rules array
151
+ var parsed, clsRx = new RegExp("(\\s|^)" + styleSet.name + "(\\s|$)");
152
+ rules.length = 0;
153
+
154
+ // get stylable elements by filtering out all code elements without the correct className
155
+ var stylableEls = codeEls.filter(function(item) { return clsRx.test(item.className) });
156
+
157
+ // add style rules to parser
158
+ for (var className in styleSet.rules) addRule(className, styleSet.rules[className]);
159
+
160
+
161
+ // replace for all elements
162
+ for (var i = 0; i < stylableEls.length; i++) {
163
+ // EVIL hack to fix IE whitespace badness if it's inside a <pre>
164
+ if (/MSIE/.test(navigator.appVersion) && stylableEls[i].parentNode.nodeName == 'PRE') {
165
+ stylableEls[i] = stylableEls[i].parentNode;
166
+
167
+ parsed = stylableEls[i].innerHTML.replace(/(<code[^>]*>)([^<]*)<\/code>/i, function() {
168
+ return arguments[1] + parse(arguments[2], styleSet.ignoreCase) + "</code>"
169
+ });
170
+ parsed = parsed.replace(/\n( *)/g, function() {
171
+ var spaces = "";
172
+ for (var i = 0; i < arguments[1].length; i++) spaces+= "&nbsp;";
173
+ return "\n" + spaces;
174
+ });
175
+ parsed = parsed.replace(/\t/g, "&nbsp;&nbsp;&nbsp;&nbsp;");
176
+ parsed = parsed.replace(/\n(<\/\w+>)?/g, "<br />$1").replace(/<br \/>[\n\r\s]*<br \/>/g, "<p><br></p>");
177
+
178
+ } else parsed = parse(stylableEls[i].innerHTML, styleSet.ignoreCase);
179
+
180
+ stylableEls[i].innerHTML = parsed;
181
+ }
182
+ }
183
+
184
+ // run highlighter on all stylesets
185
+ for (var i=0; i < this.styleSets.length; i++) {
186
+ highlightCode(this.styleSets[i]);
187
+ }
188
+ }
@@ -0,0 +1,26 @@
1
+ CodeHighlighter.addStyle("rb",{
2
+ comment : {
3
+ exp : /#[^\n]+/
4
+ },
5
+ brackets : {
6
+ exp : /\(|\)|\{|\}/
7
+ },
8
+ string : {
9
+ exp : /'[^']*'|"[^"]*"/
10
+ },
11
+ keywords : {
12
+ exp : /\b(do|end|self|class|def|if|module|yield|then|else|for|until|unless|while|elsif|case|when|break|retry|redo|rescue|raise)\b/
13
+ },
14
+ constant : {
15
+ exp : /\b([A-Z]\w+)\b/
16
+ },
17
+ ivar : {
18
+ exp : /([^@])(@{1,2}\w+)\b/
19
+ },
20
+ ns : {
21
+ exp : /(:{2,})/
22
+ },
23
+ symbol : {
24
+ exp : /(:[A-Za-z0-9_!?]+)/
25
+ }
26
+ });
Binary file
Binary file
Binary file
Binary file
Binary file
Binary file
Binary file
Binary file
Binary file
Binary file
Binary file
Binary file
Binary file
Binary file
Binary file
Binary file
Binary file
Binary file
Binary file
Binary file
Binary file
Binary file
Binary file
Binary file
@@ -0,0 +1,3531 @@
1
+ = Hello! =
2
+
3
+ Shoes is a tiny graphics toolkit. It's simple and straightforward. Shoes was
4
+ born to be easy! Really, it was made for absolute beginners. There's really
5
+ nothing to it.
6
+
7
+ You see, the trivial Shoes program can be just one line:
8
+
9
+ {{{
10
+ #!ruby
11
+ Shoes.app{button("Click me!"){alert("Good job.")}}
12
+ }}}
13
+
14
+ Shoes programs are written in a language called Ruby. When Shoes is handed
15
+ this simple line of Ruby code, a window appears with a button inside reading
16
+ "Click me!" When the button is clicked, a message pops up.
17
+
18
+ On Linux, here's how this might look: !{margin_left: 100}man-shot1.png!
19
+
20
+ While lots of Shoes apps are graphical games and art programs, you can also
21
+ layout text and edit controls easily. !{margin_left: 40}shoes-manual-apps.gif!
22
+
23
+ And, ideally, Shoes programs will run on any of the major platforms out there.
24
+ Microsoft Windows, Apple's Mac OS X, Linux and many others.
25
+
26
+ ^So, welcome to Shoes' built-in manual. This manual is a Shoes program itself!^
27
+
28
+ == Introducing Shoes ==
29
+
30
+ How does Shoes look on OS X and Windows? Does it really look okay? Is it all
31
+ ugly and awkward? People must immediately convulse! It must be so watered down
32
+ trying to do everything.
33
+
34
+ Well, before getting into the stuff about installing and running Shoes, time to
35
+ just check out some screenshots, to give you an idea of what you can do.
36
+
37
+ ==== Mac OS X ====
38
+
39
+ Shoes runs on Apple Mac OS X Leopard, as well as Tiger. Shoes supports PowerPC
40
+ machines as well, however, there is no video support on that platform.
41
+ !man-look-tiger.png!
42
+
43
+ This is the `simple-sphere.rb` sample running on Tiger. Notice that the app
44
+ runs inside a normal OS X window border.
45
+
46
+ The whole sphere is drawn with blurred ovals and shadows. You can draw and
47
+ animate shapes and apply effects to those shapes in Shoes.
48
+
49
+ ==== Windows ====
50
+
51
+ Shoes runs on all versions of '''Microsoft Windows XP''', '''Windows Vista''',
52
+ '''Windows 7''', and anything else '''Windows 2000''' compatible.
53
+ !man-look-vista.png!
54
+
55
+ Above is pictured the `simple-clock.rb` sample running on Windows Vista. This
56
+ example is also draws ovals and lines to build the clock, which is animated to
57
+ repaint itself several times each second.
58
+
59
+ Notice the text on the top of the app, showing the current time. Shoes has the
60
+ skills to layout words using any color, bold, italics, underlines, and supports
61
+ loading fonts from a file.
62
+
63
+ ==== Linux ====
64
+
65
+ Here's a screenshot of the `simple-downloader.rb` sample running on '''Ubuntu
66
+ Linux'''. !man-look-ubuntu.png!
67
+
68
+ Notice the buttons and progress bars. These types of controls look different on
69
+ OS X and Windows. The text and links would look the same, though.
70
+
71
+ Shapes, text, images and videos all look the same on every platforms. However,
72
+ native controls (like edit lines and edit boxes) will match the look of the
73
+ window theme. Shoes will try to keep native controls all within the size you
74
+ give them, only the look will vary.
75
+
76
+ == Installing Shoes ==
77
+
78
+ Okay, on to installing Shoes. I'm sure you're wondering: do I need to install
79
+ Ruby? Do I need to unzip anything? What commands do I need to type?
80
+
81
+ Nope. You don't need Ruby. You don't need WinZip. Nothing to type.
82
+
83
+ On most systems, starting Shoes is just a matter of running the installer and
84
+ clicking the Shoes icon. Shoes comes with everything built in. We'll talk
85
+ through all the steps, though, just to be clear about it.
86
+
87
+ ==== Step 1: Installing Shoes ====
88
+
89
+ You'll want to visit [[http://shoesrb.com/ the site of Shoes]] to download
90
+ the Shoes installer. Usually, you'll just want one of the installers on the
91
+ downloads page of the site. !man-builds1.png!
92
+
93
+ Here's how to run the installer:
94
+
95
+ * On '''Mac OS X''', you'll have a file ending with '''.dmg'''. Double-click this file and a window should appear with a '''Shoes''' icon and an '''Applications''' folder. Following the arrow, drag the Shoes icon into the '''Applications''' folder. !man-intro-dmg.png!
96
+ * On '''Windows''', you'll download a '''.exe''' file. Double-click this file and follow the instructions. !man-intro-exe.png!
97
+ * On '''Linux''', you'll need to compile your own Shoes. Check out [[https://github.com/shoes/shoes/wiki/Building-Shoes-on-Linux this page]] for more. We want to provide packages eventually!
98
+
99
+ ==== Step 2: Start a New Text File ====
100
+
101
+ Shoes programs are just plain text files ending with a '''.rb''' extension.
102
+
103
+ Here are a few ways to create a blank text file:
104
+
105
+ * On '''Mac OS X''', visit your '''Applications''' folder and double-click on the '''TextEdit''' app. A blank editor window should come up. Now, go to the '''Format''' menu and select the '''Make Plain Text''' option. Okay, you're all set! !man-editor-osx.png!
106
+ * On '''Windows''', go to the Start menu. Select '''All Programs''', then '''Accessories''', then '''Notepad'''. !man-editor-notepad.png!
107
+ * On '''Linux''', most distros come with '''gedit'''. You might try running that. Or, if your distro is KDE-based, run '''kate'''.
108
+
109
+ Now, in your blank window, type in the following:
110
+
111
+ {{{
112
+ Shoes.app do
113
+ background "#DFA"
114
+ para "Welcome to Shoes"
115
+ end
116
+ }}}
117
+
118
+ Save to your desktop as `welcome.rb`.
119
+
120
+ ==== Step 3: Run It! Go Shoes! ====
121
+
122
+ To run your program:
123
+
124
+ * On '''Mac OS X''', visit your '''Applications''' folder again. This time, double-click the '''Shoes''' icon in that folder. You should see the red shoes icon appear in the dock. Drag your `welcome.rb` from the desktop on to that dock icon. !man-run-osx.png!
125
+ * On '''Windows''', get to the Start menu. Go into '''All Programs''', then '''Shoes''', then '''Shoes'''. A file selector box should come up. Browse to your desktop and select `welcome.rb`. Click '''OK''' and you're on your way. !man-run-xp.png! !man-run-vista.png!
126
+ * On '''Linux''', run Shoes just like you did in step one. You should see a file selector box. Browse to your desktop, select `welcome.rb` and hit '''OK'''.
127
+
128
+ So, not much of a program yet. But it's something! You've got the knack of it, at least!
129
+
130
+ ==== What Can You Make With Shoes? ====
131
+
132
+ Well, you can make windowing applications. But Shoes is inspired by the web, so
133
+ applications tend to use images and text layout rather than a lot of widgets.
134
+ For example, Shoes doesn't come with tabbed controls or toolbars. Shoes is a
135
+ ''tiny'' toolkit, remember?
136
+
137
+ Still, Shoes does have a few widgets like buttons and edit boxes. And many
138
+ missing elements (like tabbed controls or toolbars) can be simulated with
139
+ images.
140
+
141
+ Shoes is written in part thanks to a very good art engine called Cairo, which
142
+ is used for drawing with shapes and colors. In this way, Shoes is inspired by
143
+ NodeBox and Processing, two very good languages for drawing animated graphics.
144
+
145
+ == The Rules of Shoes ==
146
+
147
+ Time to stop guessing how Shoes works. Some of the tricky things will come
148
+ back to haunt you. I've boiled down the central rules to Shoes. These are the
149
+ things you MUST know to really make it all work.
150
+
151
+ These are general rules found throughout Shoes. While Shoes has an overall
152
+ philosophy of simplicity and clarity, there are a few points that need to be
153
+ studied and remembered.
154
+
155
+ ==== Shoes Tricky Blocks ====
156
+
157
+ Okay, this is absolutely crucial. Shoes does a trick with blocks. This trick
158
+ makes everything easier to read. But it also can make blocks harder to use
159
+ once you're in deep.
160
+
161
+ '''Let's take a normal Ruby block:'''
162
+
163
+ {{{
164
+ ary = ['potion', 'swords', 'shields']
165
+ ary.each do |item|
166
+ puts item
167
+ end
168
+ }}}
169
+
170
+ In Shoes, these sorts of blocks work the same. This block above loops through
171
+ the array and stores each object in the `item` variable. The `item` variable
172
+ disappears (goes out of scope) when the block ends.
173
+
174
+ One other thing to keep in mind is that `self` stays the same inside normal
175
+ Ruby blocks. Whatever `self` was before the call to `each`, it is the same
176
+ inside the `each` block.
177
+
178
+ '''Both of these things are also true for most Shoes blocks.'''
179
+
180
+ {{{
181
+ Shoes.app do
182
+ stack do
183
+ para "First"
184
+ para "Second"
185
+ para "Third"
186
+ end
187
+ end
188
+ }}}
189
+
190
+ Here we have two blocks. The first block is sent to `Shoes.app`. This `app`
191
+ block changes `self`.
192
+
193
+ The other block is the `stack` block. That block does NOT change self.
194
+
195
+ '''For what reason does the `app` block change self?''' Let's start by
196
+ spelling out that last example completely.
197
+
198
+ {{{
199
+ Shoes.app do
200
+ self.stack do
201
+ self.para "First"
202
+ self.para "Second"
203
+ self.para "Third"
204
+ end
205
+ end
206
+ }}}
207
+
208
+ All of the `self`s in the above example are the App object. Shoes uses Ruby's
209
+ `instance_eval` to change self inside the `app` block. So the method calls to
210
+ `stack` and `para` get sent to the app.
211
+
212
+ '''This also is why you can use instance variables throughout a Shoes app:'''
213
+
214
+ {{{
215
+ Shoes.app do
216
+ @s = stack do
217
+ @p1 = para "First"
218
+ @p2 = para "Second"
219
+ @p3 = para "Third"
220
+ end
221
+ end
222
+ }}}
223
+
224
+ These instance variables will all end up inside the App object.
225
+
226
+ '''Whenever you create a new window, `self` is also changed.''' So, this means
227
+ the [[Element.window]] and [[Element.dialog]] methods, in addition to
228
+ Shoes.app.
229
+
230
+ {{{
231
+ Shoes.app title: "MAIN" do
232
+ para self
233
+ button "Spawn" do
234
+ window title: "CHILD" do
235
+ para self
236
+ end
237
+ end
238
+ end
239
+ }}}
240
+
241
+ ==== Block Redirection ====
242
+
243
+ The `stack` block is a different story, though. It doesn't change `self` and
244
+ it's basically a regular block.
245
+
246
+ '''But there's a trick:''' when you attach a `stack` and give it a block, the
247
+ App object places that stack in its memory. The stack gets popped off when the
248
+ block ends. So all drawing inside the block gets '''redirected''' from the
249
+ App's top slot to the new stack.
250
+
251
+ So those three `para`s will get drawn on the `stack`, even though they actually
252
+ get sent to the App object first.
253
+
254
+ {{{
255
+ Shoes.app do
256
+ stack do
257
+ para "First"
258
+ para "Second"
259
+ para "Third"
260
+ end
261
+ end
262
+ }}}
263
+
264
+ A bit tricky, you see? This can bite you even if you know about it.
265
+
266
+ One way it'll get you is if you try to edit a stack somewhere else in your
267
+ program, outside the `app` block.
268
+
269
+ Like let's say you pass around a stack object. And you have a class that edits
270
+ that object.
271
+
272
+ {{{
273
+ class Messenger
274
+ def initialize(stack)
275
+ @stack = stack
276
+ end
277
+ def add(msg)
278
+ @stack.append do
279
+ para msg
280
+ end
281
+ end
282
+ end
283
+ }}}
284
+
285
+ So, let's assume you pass the stack object into your Messenger class when the
286
+ app starts. And, later, when a message comes in, the `add` method gets used to
287
+ append a paragraph to that stack. Should work, right?
288
+
289
+ Nope, it won't work. The `para` method won't be found. The App object isn't
290
+ around any more. And it's the one with the `para` method.
291
+
292
+ Fortunately, each Shoes object has an `app` method that will let you reopen the
293
+ App object so you can do somefurther editing.
294
+
295
+ {{{
296
+ class Messenger
297
+ def initialize(stack)
298
+ @stack = stack
299
+ end
300
+ def add(msg)
301
+ @stack.app do
302
+ append do
303
+ para msg
304
+ end
305
+ end
306
+ end
307
+ end
308
+ }}}
309
+
310
+ As you can imagine, the `app` object changes `self` to the App object.
311
+
312
+ So the rules here are:
313
+
314
+ 1. '''Methods named "app" or which create new windows alter `self` to the App
315
+ object.'''[[BR]](This is true for both Shoes.app and Slot.app, as well as
316
+ [[Element.window]] and [[Element.dialog]].)[[BR]]
317
+ 2. '''Blocks attached to stacks, flows or any manipulation method (such as
318
+ append) do not change self. Instead, they pop the slot on to the app's editing
319
+ stack.'''
320
+
321
+ ==== Careful With Fixed Heights ====
322
+
323
+ Fixed widths on slots are great so you can split the window into columns.
324
+
325
+ {{{
326
+ Shoes.app do
327
+ flow do
328
+ stack width: 200 do
329
+ caption "Column one"
330
+ para "is 200 pixels wide"
331
+ end
332
+ stack width: -200 do
333
+ caption "Column two"
334
+ para "is 100% minus 200 pixels wide"
335
+ end
336
+ end
337
+ end
338
+ }}}
339
+
340
+ Fixed heights on slots should be less common. Usually you want your text and
341
+ images to just flow down the window as far as they can. Height usually happens
342
+ naturally.
343
+
344
+ The important thing here is that fixed heights actually force slots to behave
345
+ differently. To be sure that the end of the slot is chopped off perfectly, the
346
+ slot becomes a '''nested window'''. A new layer is created by the operating
347
+ system to keep the slot in a fixed square.
348
+
349
+ One difference between normal slots and nested window slots is that the latter
350
+ can have scrollbars.
351
+
352
+ {{{
353
+ Shoes.app do
354
+ stack width: 200, height: 200, scroll: true do
355
+ background "#DFA"
356
+ 100.times do |i|
357
+ para "Paragraph No. #{i}"
358
+ end
359
+ end
360
+ end
361
+ }}}
362
+
363
+ These nested windows require more memory. They tax the application a bit more.
364
+ So if you're experiencing some slowness with hundreds of fixed-height slots,
365
+ try a different approach.
366
+
367
+ ==== Image and Shape Blocks ====
368
+
369
+ Most beginners start littering the window with shapes. It's just easier to
370
+ throw all your rectangles and ovals in a slot.
371
+
372
+ '''However, bear in mind that Shoes will create objects for all those
373
+ shapes!'''
374
+
375
+ {{{
376
+ Shoes.app do
377
+ fill black(0.1)
378
+ 100.times do |i|
379
+ oval i, i, i * 2
380
+ end
381
+ end
382
+ }}}
383
+
384
+ In this example, one-hundred Oval objects are created. This isn't too bad.
385
+ But things would be slimmer if we made these into a single shape.
386
+
387
+ {{{
388
+ Shoes.app do
389
+ fill black(0.1)
390
+ shape do
391
+ 100.times do |i|
392
+ oval i, i, i * 2
393
+ end
394
+ end
395
+ end
396
+ }}}
397
+
398
+ Oh, wait. The ovals aren't filled in this time! That's because the ovals have
399
+ been combined into a single huge shape. And Shoes isn't sure where to fill in
400
+ this case.
401
+
402
+ So you usually only want to combine into a single shape when you're dealing
403
+ strictly with outlines.
404
+
405
+ Another option is to combine all those ovals into a single image.
406
+
407
+ {{{
408
+ Shoes.app do
409
+ fill black(0.1)
410
+ image 300, 300 do
411
+ 100.times do |i|
412
+ oval i, i, i * 2
413
+ end
414
+ end
415
+ end
416
+ }}}
417
+
418
+ There we go! The ovals are all combined into a single 300 x 300 pixel image.
419
+ In this case, storing that image in memory might be much bigger than having
420
+ one-hundred ovals around. But when you're dealing with thousands of shapes,
421
+ the image block can be cheaper.
422
+
423
+ The point is: it's easy to group shapes together into image or shape blocks, so
424
+ give it a try if you're looking to gain some speed. Shape blocks particularly
425
+ will save you some memory and speed.
426
+
427
+ ==== UTF-8 Everywhere ====
428
+
429
+ Ruby itself isn't Unicode aware. And UTF-8 is a type of Unicode. (See
430
+ [[http://en.wikipedia.org/wiki/UTF-8 Wikipedia]] for a full explanation of
431
+ UTF-8.)
432
+
433
+ However, UTF-8 is common on the web. And lots of different platforms support
434
+ it. So to cut down on the amount of conversion that Shoes has to do, Shoes
435
+ expects all strings to be in UTF-8 format.
436
+
437
+ This is great because you can show a myriad of languages (Russian, Japanese,
438
+ Spanish, English) using UTF-8 in Shoes. Just be sure that your text editor
439
+ uses UTF-8!
440
+
441
+ To illustrate:
442
+
443
+ {{{
444
+ Shoes.app do
445
+ stack margin: 10 do
446
+ @edit = edit_box width: 1.0 do
447
+ @para.text = @edit.text
448
+ end
449
+ @para = para ""
450
+ end
451
+ end
452
+ }}}
453
+
454
+ This app will copy anything you paste into the edit box and display it in a
455
+ Shoes paragraph. You can try copying some foreign text (such as Greek or
456
+ Japanese) into this box to see how it displays.
457
+
458
+ This is a good test because it proves that the edit box gives back UTF-8
459
+ characters. And the paragraph can be set to any UTF-8 characters.
460
+
461
+ '''Important note:''' if some UTF-8 characters don't display for you, you will
462
+ need to change the paragraph's font. This is especially common on OS X.
463
+
464
+ So, a good Japanese font on OS X is '''AppleGothic''' and on Windows is '''MS
465
+ UI Gothic'''.
466
+
467
+ {{{
468
+ Shoes.app do
469
+ para "てすと (te-su-to)", font: case RUBY_PLATFORM
470
+ when /mingw/; "MS UI Gothic"
471
+ when /darwin/; "AppleGothic, Arial"
472
+ else "Arial"
473
+ end
474
+ end
475
+ }}}
476
+
477
+ Again, anything which takes a string in Shoes will need a UTF-8 string. Edit
478
+ boxes, edit lines, list boxes, window titles and text blocks all take UTF-8. If
479
+ you give a string with bad characters in it, an error will show up in the
480
+ console.
481
+
482
+ ==== The Main App and Its Requires ====
483
+
484
+ '''NOTE:''' This rule is for Raisins. Policeman uses TOPLEVEL_BINDING. So, you
485
+ can get `main`, Ruby top-level object, with the first snippet. Although you
486
+ need to use `Shoes::Para` instead of `Para` outside `Shoes.app` block.
487
+
488
+ Each Shoes app is given a little room where it can create itself. You can
489
+ create classes and set variables and they won't be seen by other Shoes
490
+ programs. Each program runs inside its own anonymous class.
491
+
492
+ {{{
493
+ main = self
494
+ Shoes.app do
495
+ para main.to_s
496
+ end
497
+ }}}
498
+
499
+ This anonymous class is called `(shoes)` and it's just an empty, unnamed class.
500
+ The `Shoes` module is mixed into this class (using `include Shoes`) so that you
501
+ can use either `Para` or `Shoes::Para` when referring to the paragraph class.
502
+
503
+ The advantages of this approach are:
504
+
505
+ * Shoes apps cannot share local variables.
506
+ * Classes created in the main app code are temporary.
507
+ * The Shoes module can be mixed in to the anonymous class, but not the top-level environment of Ruby itself.
508
+ * Garbage collection can clean up apps entirely once they complete.
509
+
510
+ The second part is especially important to remember.
511
+
512
+ {{{
513
+ class Storage; end
514
+
515
+ Shoes.app do
516
+ para Storage.new
517
+ end
518
+ }}}
519
+
520
+ The `Storage` class will disappear once the app completes. Other apps aren't
521
+ able to use the Storage class. And it can't be gotten to from files that are
522
+ loaded using `require`.
523
+
524
+ When you `require` code, though, that code will stick around. It will be kept
525
+ in the Ruby top-level environment.
526
+
527
+ So, the rule is: '''keep your temporary classes in the code with the app and
528
+ keep your permanent classes in requires.'''
529
+
530
+ = Shoes =
531
+
532
+ Shoes is all about drawing windows and the stuff inside those windows. Let's
533
+ focus on the window itself, for now. The other sections [[Slots]] and
534
+ [[Elements]] cover everything that goes inside the window.
535
+
536
+ For here on, the manual reads more like a dictionary. Each page is mostly a
537
+ list of methods you can use for each topic covered. The idea is to be very
538
+ thorough and clear about everything.
539
+
540
+ So, if you've hit this far in the manual and you're still hazy about getting
541
+ started, you should probably either go back to the [[Hello! beginning]] of the
542
+ manual. Or you could try [[https://github.com/downloads/shoes/shoes/nks.pdf Nobody Knows
543
+ Shoes]], the beginner's leaflet PDF.
544
+
545
+ ==== Finding Your Way ====
546
+
547
+ This section covers:
548
+
549
+ * [[Built-in Built-in methods]] - general methods available anywhere in a Shoes program.
550
+ * [[App The App window]] - methods found attached to every main Shoes window.
551
+ * [[Styles The Styles Master List]] - a complete list of every style in Shoes.
552
+ * [[Classes The Classes list]] - a chart showing what Shoes classes subclass what.
553
+ * [[Colors The Colors list]] - a chart of all built-in colors and the [[Built-in.rgb]] numbers for each.
554
+
555
+ If you find yourself paging around a lot and not finding something, give the
556
+ [[Search]] page a try. It's the quickest way to get around.
557
+
558
+ After this general reference, there are two other more specific sections:
559
+
560
+ * [[Slots]] - covering [[Element.stack]] and [[Element.flow]], the two types of slots.
561
+ * [[Elements]] - documentation for all the buttons, shapes, images, and so on.
562
+
563
+ Two really important pages in there are the [[Element Element Creation]] page
564
+ (which lists all the elements you can add) and the [[Common Common Methods]]
565
+ page (which lists methods you'll find on any slot or element.)
566
+
567
+ == Built-in Methods ==
568
+
569
+ These methods can be used anywhere throughout Shoes programs.
570
+
571
+ All of these commands are unusual because you don't attach them with a dot.
572
+ '''Every other method in this manual must be attached to an object with a dot.'''
573
+ But these are built-in methods (also called: Kernel methods.) Which means no dot!
574
+
575
+ A common one is `alert`:
576
+
577
+ {{{
578
+ #!ruby
579
+ alert "No dots in sight"
580
+ }}}
581
+
582
+ Compare that to the method `reverse`, which isn't a Kernel method and is only
583
+ available for Arrays and Strings:
584
+
585
+ {{{
586
+ #!ruby
587
+ "Plaster of Paris".reverse
588
+ #=> "siraP fo retsalP"
589
+ [:dogs, :cows, :snakes].reverse
590
+ #=> [:snakes, :cows, :dogs]
591
+ }}}
592
+
593
+ Most Shoes methods for drawing and making buttons and so on are attached to
594
+ slots. See the section on [[Slots]] for more.
595
+
596
+ ==== Built-in Constants ====
597
+
598
+ Shoes also has a handful of built-in constants which may prove useful if you
599
+ are trying to sniff out what release of Shoes is running.
600
+
601
+ '''Shoes::RELEASE_NAME''' contains a string with the name of the Shoes release.
602
+ All Shoes releases are named, starting with Curious.
603
+
604
+ '''Shoes::RELEASE_ID''' contains a number representing the Shoes release. So,
605
+ for example, Curious is number 1, as it was the first official release.
606
+
607
+ '''Shoes::REVISION''' is the Subversion revision number for this build.
608
+
609
+ '''Shoes::FONTS''' is a complete list of fonts available to the app. This list
610
+ includes any fonts loaded by the [[Built-in.font]] method.
611
+
612
+ === alert(message: a string) » nil ===
613
+
614
+ Pops up a window containing a short message.
615
+
616
+ {{{
617
+ #!ruby
618
+ alert("I'm afraid I must interject!")
619
+ }}}
620
+
621
+ Please use alerts sparingly, as they are incredibly annoying! If you are using
622
+ alerts to show messages to help you debug your program, try checking out the
623
+ [[Built-in.debug]] or [[Built-in.info]] methods.
624
+
625
+ === ask(message: a string) » a string ===
626
+
627
+ Pops up a window and asks a question. For example, you may want to ask someone
628
+ their name.
629
+
630
+ {{{
631
+ #!ruby
632
+ name = ask("Please, enter your name:")
633
+ }}}
634
+
635
+ When the above script is run, the person at the computer will see a window with
636
+ a blank box for entering their name. The name will then be saved in the `name`
637
+ variable.
638
+
639
+ === ask_color(title: a string) » Shoes::Color ===
640
+
641
+ Pops up a color picker window. The program will wait for a color to be picked,
642
+ then gives you back a Color object. See the `Color` help for some ways you can
643
+ use this color.
644
+
645
+ {{{
646
+ #!ruby
647
+ backcolor = ask_color("Pick a background")
648
+ Shoes.app do
649
+ background backcolor
650
+ end
651
+ }}}
652
+
653
+ === ask_open_file() » a string ===
654
+
655
+ Pops up an "Open file..." window. It's the standard window which shows all of
656
+ your folders and lets you select a file to open. Hands you back the name of the
657
+ file.
658
+
659
+ {{{
660
+ #!ruby
661
+ filename = ask_open_file
662
+ Shoes.app do
663
+ para File.read(filename)
664
+ end
665
+ }}}
666
+
667
+ === ask_save_file() » a string ===
668
+
669
+ Pops up a "Save file..." window, similiar to `ask_open_file`, described
670
+ previously.
671
+
672
+ {{{
673
+ #!ruby
674
+ save_as = ask_save_file
675
+ }}}
676
+
677
+ === ask_open_folder() » a string ===
678
+
679
+ Pops up an "Open folder..." window. It's the standard window which shows all of
680
+ your folders and lets you select a folder to open. Hands you back the name of
681
+ the folder.
682
+
683
+ {{{
684
+ #!ruby
685
+ folder = ask_open_folder
686
+ Shoes.app do
687
+ para Dir.entries(folder)
688
+ end
689
+ }}}
690
+
691
+ === ask_save_folder() » a string ===
692
+
693
+ Pops up a "Save folder..." window, similiar to `ask_open_folder`, described
694
+ previously. On OS X, this method currently behaves like an alias of
695
+ `ask_open_folder`.
696
+
697
+ {{{
698
+ #!ruby
699
+ save_to = ask_save_folder
700
+ }}}
701
+
702
+
703
+ === confirm(question: a string) » true or false ===
704
+
705
+ Pops up a yes-or-no question. If the person at the computer, clicks '''yes''',
706
+ you'll get back a `true`. If not, you'll get back `false`.
707
+
708
+ {{{
709
+ #!ruby
710
+ if confirm("Draw a circle?")
711
+ Shoes.app{ oval top: 0, left: 0, radius: 50 }
712
+ end
713
+ }}}
714
+
715
+ === debug(message: a string) » nil ===
716
+
717
+ Sends a debug message to the Shoes console. You can bring up the Shoes console
718
+ by pressing `Alt-/` on any Shoes window (or `⌘-/` on OS X.)
719
+
720
+ {{{
721
+ #!ruby
722
+ debug("Running Shoes on " + RUBY_PLATFORM)
723
+ }}}
724
+
725
+ Also check out the [[Built-in.error]], [[Built-in.warn]] and [[Built-in.info]]
726
+ methods.
727
+
728
+ === error(message: a string) » nil ===
729
+
730
+ Sends an error message to the Shoes console. This method should only be used
731
+ to log errors. Try the [[Built-in.debug]] method for logging messages to
732
+ yourself.
733
+
734
+ Oh, and, rather than a string, you may also hand exceptions directly to this
735
+ method and they'll be formatted appropriately.
736
+
737
+ === exit() ===
738
+
739
+ Stops your program. Call this anytime you want to suddenly call it quits.
740
+
741
+ '''PLEASE NOTE:''' If you need to use Ruby's own `exit` method (like in a
742
+ forked Ruby process,) call `Kernel.exit`.
743
+
744
+ === font(message: a string) » an array of font family names ===
745
+
746
+ Loads a TrueType (or other type of font) from a file. While TrueType is
747
+ supported by all platforms, your platform may support other types of fonts.
748
+ Shoes uses each operating system's built-in font system to make this work.
749
+
750
+ Here's a rough idea of what fonts work on which platforms:
751
+
752
+ * Bitmap fonts (.bdf, .pcf, .snf) - Linux
753
+ * Font resource (.fon) - Windows
754
+ * Windows bitmap font file (.fnt) - Linux, Windows
755
+ * PostScript OpenType font (.otf) - Mac OS X, Linux, Windows
756
+ * Type1 multiple master (.mmm) - Windows
757
+ * Type1 font bits (.pfb) - Linux, Windows
758
+ * Type1 font metrics (.pfm) - Linux, Windows
759
+ * TrueType font (.ttf) - Mac OS X, Linux, Windows
760
+ * TrueType collection (.ttc) - Mac OS X, Linux, Windows
761
+
762
+ If the font is properly loaded, you'll get back an array of font names found in
763
+ the file. Otherwise, `nil` is returned if no fonts were found in the file.
764
+
765
+ Also of interest: the `Shoes::FONTS` constant is a complete list of fonts
766
+ available to you on this platform. You can check for a certain font by using
767
+ `include?`.
768
+
769
+ {{{
770
+ if Shoes::FONTS.include? "Helvetica"
771
+ alert "Helvetica is available on this system."
772
+ else
773
+ alert "You do not have the Helvetica font."
774
+ end
775
+ }}}
776
+
777
+ If you have trouble with fonts showing up, make sure your app loads the font
778
+ before it is used. Especially on OS X, if fonts are used before they are
779
+ loaded, the font cache will tend to ignore loaded fonts.
780
+
781
+ === gradient(color1, color2) » Shoes::Pattern ===
782
+
783
+ Builds a linear gradient from two colors. For each color, you may pass in a
784
+ Shoes::Color object or a string describing the color.
785
+
786
+ === gray(the numbers: darkness, alpha) » Shoes::Color ===
787
+
788
+ Create a grayscale color from a level of darkness and, optionally, an alpha
789
+ level.
790
+
791
+ {{{
792
+ black = gray(0.0)
793
+ white = gray(1.0)
794
+ }}}
795
+
796
+ === info(message: a string) » nil ===
797
+
798
+ Logs an informational message to the user in the Shoes console. So, where
799
+ debug messages are designed to help the program figure out what's happening,
800
+ `info` messages tell the user extra information about the program.
801
+
802
+ {{{
803
+ #!ruby
804
+
805
+ info("You just ran the info example on Shoes #{Shoes::RELEASE_NAME}.")
806
+ }}}
807
+
808
+ For example, whenever a Shy file loads, Shoes prints an informational message
809
+ in the console describing the author of the Shy and its version.
810
+
811
+ === rgb(a series of numbers: red, green, blue, alpha) » Shoes::Color ===
812
+
813
+ Create a color from red, green and blue components. An alpha level (indicating
814
+ transparency) can also be added, optionally.
815
+
816
+ When passing in a whole number, use values from 0 to 255.
817
+
818
+ {{{
819
+ blueviolet = rgb(138, 43, 226)
820
+ darkgreen = rgb(0, 100, 0)
821
+ }}}
822
+
823
+ Or, use a decimal number from 0.0 to 1.0.
824
+
825
+ {{{
826
+ blueviolet = rgb(0.54, 0.17, 0.89)
827
+ darkgreen = rgb(0, 0.4, 0)
828
+ }}}
829
+
830
+ This method may also be called as `Shoes.rgb`.
831
+
832
+ === warn(message: a string) » nil ===
833
+
834
+ Logs a warning for the user. A warning is not a catastrophic error (see
835
+ [[Built-in.error]] for that.) It is just a notice that the program will be
836
+ changing in the future or that certain parts of the program aren't reliable
837
+ yet.
838
+
839
+ To view warnings and errors, open the Shoes console with `Alt-/` (or `⌘-/` on
840
+ OS X.)
841
+
842
+ == The App Object ==
843
+
844
+ An App is a single window running code at a URL. When you switch URLs, a new
845
+ App object is created and filled up with stacks, flows and other Shoes
846
+ elements.
847
+
848
+ The App is the window itself. Which may be closed or cleared and filled with
849
+ new elements. !{margin_left: 100}man-app.png!
850
+
851
+ The App itself, in slot/box terminology, is a flow. See the ''Slots'' section
852
+ for more, but this just means that any elements placed directly at the
853
+ top-level will flow.
854
+
855
+ === Shoes.app(styles) { ... } » Shoes::App ===
856
+
857
+ Starts up a Shoes app window. This is the starting place for making a Shoes
858
+ program. Inside the block, you fill the window with various Shoes elements
859
+ (buttons, artwork, etc.) and, outside the block, you use the `styles` to
860
+ describe how big the window is. Perhaps also the name of the app or if it's
861
+ resizable.
862
+
863
+ {{{
864
+ #!ruby
865
+ Shoes.app(title: "White Circle",
866
+ width: 200, height: 200, resizable: false) {
867
+ background black
868
+ fill white
869
+ oval top: 20, left: 20, radius: 160
870
+ }
871
+ }}}
872
+
873
+ In the case above, a small window is built. 200 pixels by 200 pixels. It's
874
+ not resizable. And, inside the window, two elements: a black background and a
875
+ white circle.
876
+
877
+ Once an app is created, it is added to the [[App.Shoes.APPS]] list. If you
878
+ want an app to spawn more windows, see the [[Element.window]] method and the
879
+ [[Element.dialog]] method.
880
+
881
+ === Shoes.APPS() » An array of Shoes::App objects ===
882
+
883
+ Builds a complete list of all the Shoes apps that are open right now. Once an
884
+ app is closed, it is removed from the list. Yes, you can run many apps at once
885
+ in Shoes. It's completely encouraged.
886
+
887
+ === clipboard() » a string ===
888
+
889
+ Returns a string containing all of the text that's on the system clipboard.
890
+ This is the global clipboard that every program on the computer cuts and pastes
891
+ into.
892
+
893
+ === clipboard = a string ===
894
+
895
+ Stores `a string` of text in the system clipboard.
896
+
897
+ === close() ===
898
+
899
+ Closes the app window. If multiple windows are open and you want to close the
900
+ entire application, use the built-in method `exit`.
901
+
902
+ === download(url: a string, styles) ===
903
+
904
+ Starts a download thread (much like XMLHttpRequest, if you're familiar with
905
+ JavaScript.) This method returns immediately and runs the download in the
906
+ background. Each download thread also fires `start`, `progress` and `finish`
907
+ events. You can send the download to a file or just get back a string (in the
908
+ `finish` event.)
909
+
910
+ If you attach a block to a download, it'll get called as the `finish` event.
911
+
912
+ {{{
913
+ #!ruby
914
+ Shoes.app do
915
+ stack do
916
+ title "Searching Google", size: 16
917
+ @status = para "One moment..."
918
+
919
+ # Search Google for 'shoes' and print the HTTP headers
920
+ download "http://www.google.com/search?q=shoes" do |goog|
921
+ @status.text = "Headers: " + goog.response.headers.inspect
922
+ end
923
+ end
924
+ end
925
+ }}}
926
+
927
+ And, if we wanted to use the downloaded data, we'd get it using
928
+ `goog.response.body`. This example is truly the simplest form of `download`:
929
+ pulling some web data down into memory and handling it once it's done.
930
+
931
+ Another simple use of `download` is to save some web data to a file, using the
932
+ `:save` style.
933
+
934
+ {{{
935
+ #!ruby
936
+ Shoes.app do
937
+ stack do
938
+ title "Downloading Google image", size: 16
939
+ @status = para "One moment..."
940
+
941
+ download "http://www.google.com/logos/nasa50th.gif",
942
+ save: "nasa50th.gif" do
943
+ @status.text = "Okay, is downloaded."
944
+ end
945
+ end
946
+ end
947
+ }}}
948
+
949
+ In this case, you can still get the headers for the downloaded file, but
950
+ `response.body` will be `nil`, since the data wasn't saved to memory. You will
951
+ need to open the file to get the downloaded goods.
952
+
953
+ === location() » a string ===
954
+
955
+ Gets a string containing the URL of the current app.
956
+
957
+ === mouse() » an array of numbers: button, left, top ===
958
+
959
+ Identifies the mouse cursor's location, along with which button is being
960
+ pressed.
961
+
962
+ {{{
963
+ #!ruby
964
+ Shoes.app do
965
+ @p = para
966
+ animate do
967
+ button, left, top = self.mouse
968
+ @p.replace "mouse: #{button}, #{left}, #{top}"
969
+ end
970
+ end
971
+ }}}
972
+
973
+ === owner() » Shoes::App ===
974
+
975
+ Gets the app which launched this app. In most cases, this will be `nil`. But
976
+ if this app was launched using the [[Element.window]] method, the owner will be
977
+ the app which called `window`.
978
+
979
+ === started?() » true or false ===
980
+
981
+ Has the window been fully constructed and displayed? This is useful for
982
+ threaded code which may try to use the window before it is completely built.
983
+ (Also see the `start` event which fires once the window is open.)
984
+
985
+ === visit(url: a string) ===
986
+
987
+ Changes the location, in order to view a different Shoes URL.
988
+
989
+ Absolute URLs (such as http://google.com) are okay, but Shoes will be expecting
990
+ a Shoes application to be at that address. (So, google.com won't work, as it's
991
+ an HTML app.)
992
+
993
+ == The Styles Master List ==
994
+
995
+ You want to mess with the look of things? Well, throughout Shoes, styles are
996
+ used to change the way elements appear. In some cases, you can even style an
997
+ entire class of elements. (Like giving all paragraphs a certain font.)
998
+
999
+ Styles are easy to spot. They usually show up when the element is created.
1000
+
1001
+ {{{
1002
+ Shoes.app title: "A Styling Sample" do
1003
+ para "Red with an underline", stroke: red, underline: "single"
1004
+ end
1005
+ }}}
1006
+
1007
+ Here we've got a `:title` style on the app. And on the paragraph inside the
1008
+ app, a red `:stroke` style and an `:underline` style.
1009
+
1010
+ The style hash can also be changed by using the [[Common.style]] method,
1011
+ available on every element and slot.
1012
+
1013
+ {{{
1014
+ Shoes.app title: "A Styling Sample" do
1015
+ @text = para "Red with an underline"
1016
+ @text.style(stroke: red, underline: "single")
1017
+ end
1018
+ }}}
1019
+
1020
+ Most styles can also be set by calling them as methods. (I'd use the manual
1021
+ search to find the method.)
1022
+
1023
+ {{{
1024
+ Shoes.app title: "A Styling Sample" do
1025
+ @text = para "Red with an underline"
1026
+ @text.stroke = red
1027
+ @text.underline = "single"
1028
+ end
1029
+ }}}
1030
+
1031
+ Rather than making you plow through the whole manual to figure out what styles
1032
+ go where, this helpful page speeds through every style in Shoes and suggests
1033
+ where that style is used.
1034
+
1035
+ === :align » a string ===
1036
+
1037
+ For: ''banner, caption, code, del, em, ins, inscription, link, para, span,
1038
+ strong, sub, sup, subtitle, tagline, title''
1039
+
1040
+ The alignment of the text. It is either:
1041
+
1042
+ * "left" - Align the text to the left.
1043
+ * "center" - Align the text in the center.
1044
+ * "right" - Align the text to the right.
1045
+
1046
+ === :angle » a number ===
1047
+
1048
+ For: ''background, border, gradient''.
1049
+
1050
+ The angle at which to apply a gradient. Normally, gradient colors range from
1051
+ top to bottom. If the `:angle` is set to 90, the gradient will rotate 90
1052
+ degrees counter-clockwise and the gradient will go from left to right.
1053
+
1054
+ === :attach » a slot or element ===
1055
+
1056
+ For: ''flow, stack''.
1057
+
1058
+ 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
1059
+ a bit further, the style `top: 10, left: 10, attach: Window` would
1060
+ place the slot at (10, 10) in the window's coordinates.
1061
+
1062
+ If a slot is attached to an element that moves, the slot will move with it. If
1063
+ the attachment is reset to `nil`, the slot will flow in with the other objects
1064
+ that surround, as normal.
1065
+
1066
+ === :autoplay » true or false ===
1067
+
1068
+ For: ''video''.
1069
+
1070
+ Should this video begin playing after it appears? If set to `true`, the video
1071
+ will start without asking the user.
1072
+
1073
+ === :bottom » a number ===
1074
+
1075
+ For: ''all slots and elements''.
1076
+
1077
+ Sets the pixel coordinate of an element's lower edge. The edge is placed
1078
+ relative to its container's lower edge. So, `bottom: 0` will align the
1079
+ element so that its bottom edge and the bottom edge of its slot touch.
1080
+
1081
+ === :cap » :curve or :rect or :project ===
1082
+
1083
+ For: ''arc, arrow, border, flow, image, mask, rect, star, shape, stack''.
1084
+
1085
+ Sets the shape of the line endpoint, whether curved or square. See the
1086
+ [[Art.cap]] method for more explanation.
1087
+
1088
+ === :center » true or false ===
1089
+
1090
+ For: ''arc, image, oval, rect, shape''.
1091
+
1092
+ Indicates whether the `:top` and `:left` coordinates refer to the center of the
1093
+ shape or not. If set to `true`, this is similar to setting the
1094
+ [[Art.transform]] method to `:center`.
1095
+
1096
+ === :change » a proc ===
1097
+
1098
+ For: ''edit_box, edit_line, list_box''.
1099
+
1100
+ The `change` event handler is stored in this style. See the [[EditBox.change]]
1101
+ method for the edit_box, as an example.
1102
+
1103
+ === :checked » true or false ===
1104
+
1105
+ For: ''check, radio''.
1106
+
1107
+ Is this checkbox or radio button checked? If set to `true`, the box is
1108
+ checked. Also see the [[Check.checked=]] method.
1109
+
1110
+ === :choose » a string ===
1111
+
1112
+ For: ''list_box''.
1113
+
1114
+ Sets the currently chosen item in the list. More information at
1115
+ [[ListBox.choose]].
1116
+
1117
+ === :click » a proc ===
1118
+
1119
+ For: ''arc, arrow, banner, button, caption, check, flow, image, inscription,
1120
+ line, link, mask, oval, para, radio, rect, shape, stack, star, subtitle,
1121
+ tagline, title''.
1122
+
1123
+ The `click` event handler is stored in this style. See the [[Events.click]]
1124
+ method for a description.
1125
+
1126
+ === :curve » a number ===
1127
+
1128
+ For: ''background, border, rect''.
1129
+
1130
+ The radius of curved corners on each of these rectangular elements. As an
1131
+ example, if this is set to 6, the corners of the rectangle are given a curve
1132
+ with a 6-pixel radius.
1133
+
1134
+ === :displace_left » a number ===
1135
+
1136
+ For: ''all slots and elements''.
1137
+
1138
+ Moves a shape, text block or any other kind of object to the left or right. A
1139
+ positive number displaces to the right by the given number of pixels; a
1140
+ negative number displaces to the left. Displacing an object doesn't effect the
1141
+ actual layout of the page. Before using this style, be sure to read the
1142
+ [[Position.displace]] docs, since its behavior can be a bit surprising.
1143
+
1144
+ === :displace_top » a number ===
1145
+
1146
+ For: ''all slots and elements''.
1147
+
1148
+ Moves a shape, text block or any other kind of object up or down. A positive
1149
+ number moves the object down by this number of pixels; a negative number moves
1150
+ it up. Displacing doesn't effect the actual layout of the page or the object's
1151
+ true coordinates. Read the [[Position.displace]] docs, since its behavior can
1152
+ be a bit surprising.
1153
+
1154
+ === :emphasis » a string ===
1155
+
1156
+ For: ''banner, caption, code, del, em, ins, inscription, link, para, span,
1157
+ strong, sub, sup, subtitle, tagline, title''.
1158
+
1159
+ Styles the text with an emphasis (commonly italicized.)
1160
+
1161
+ This style recognizes three possible settings:
1162
+
1163
+ * "normal" - the font is upright.
1164
+ * "oblique" - the font is slanted, but in a roman style.
1165
+ * "italic" - the font is slanted in an italic style.
1166
+
1167
+ === :family » a string ===
1168
+
1169
+ For: ''banner, caption, code, del, em, ins, inscription, link, para, span,
1170
+ strong, sub, sup, subtitle, tagline, title''.
1171
+
1172
+ Styles the text with a given font family. The string should contain the family
1173
+ name or a comma-separated list of families.
1174
+
1175
+ === :fill » a hex code, a Shoes::Color or a range of either ===
1176
+
1177
+ For: ''arc, arrow, background, banner, caption, code, del, em, flow, image,
1178
+ ins, inscription, line, link, mask, oval, para, rect, shape, span, stack, star,
1179
+ strong, sub, sup, subtitle, tagline, title''.
1180
+
1181
+ The color of the background pen. For shapes, this is the fill color, the paint
1182
+ inside the shape. For text stuffs, this color is painted in the background (as
1183
+ if marked with a highlighter pen.)
1184
+
1185
+ === :font » a string ===
1186
+
1187
+ For: ''banner, caption, code, del, em, ins, inscription, link, para, span,
1188
+ strong, sub, sup, subtitle, tagline, title''.
1189
+
1190
+ Styles the text with a font description. The string is pretty flexible, but
1191
+ can take the form "[FAMILY-LIST] [STYLE-OPTIONS] [SIZE]", where FAMILY-LIST is
1192
+ a comma separated list of families optionally terminated by a comma,
1193
+ STYLE_OPTIONS is a whitespace separated list of words where each WORD describes
1194
+ one of style, variant, weight, stretch, or gravity, and SIZE is a decimal
1195
+ number (size in points) or optionally followed by the unit modifier "px" for
1196
+ absolute size. Any one of the options may be absent. If FAMILY-LIST is absent,
1197
+ then the default font family (Arial) will be used.
1198
+
1199
+ === :group » a string ===
1200
+
1201
+ For: ''radio''.
1202
+
1203
+ Indicates what group a radio button belongs to. Without this setting, radio
1204
+ buttons are grouped together with other radio buttons in their immediate slot.
1205
+ "Grouping" radio buttons doesn't mean they'll be grouped next to each other on
1206
+ the screen. It means that only one radio button from the group can be selected
1207
+ at a time.
1208
+
1209
+ By giving this style a string, the radio button will be grouped with other
1210
+ radio buttons that have the same group name.
1211
+
1212
+ === :height » a number ===
1213
+
1214
+ For: ''all slots and elements''.
1215
+
1216
+ Sets the pixel height of this object. If the number is a decimal number, the
1217
+ height becomes a percentage of its parent's height (with 0.0 being 0% and 1.0
1218
+ being 100%.)
1219
+
1220
+ === :hidden » true or false ===
1221
+
1222
+ For: ''all slots and elements''.
1223
+
1224
+ Hides or shows this object. Any object with `hidden: true` are not
1225
+ displayed on the screen. Neither are its children.
1226
+
1227
+ === :inner » a number ===
1228
+
1229
+ For: ''star''.
1230
+
1231
+ The size of the inner radius (in pixels.) The inner radius describes the solid
1232
+ circle within the star where the points begin to separate.
1233
+
1234
+ === :items » an array ===
1235
+
1236
+ For: ''list_box''.
1237
+
1238
+ The list of selections in the list box. See the [[Element.list_box]] method
1239
+ for an example.
1240
+
1241
+ === :justify » true or false ===
1242
+
1243
+ For: ''banner, caption, code, del, em, ins, inscription, link, para, span,
1244
+ strong, sub, sup, subtitle, tagline, title''
1245
+
1246
+ Evenly spaces the text horizontally.
1247
+
1248
+ === :kerning » a number ===
1249
+
1250
+ For: ''banner, caption, code, del, em, ins, inscription, link, para, span,
1251
+ strong, sub, sup, subtitle, tagline, title''.
1252
+
1253
+ Adds to the natural spacing between letters, in pixels.
1254
+
1255
+ === :leading » a number ===
1256
+
1257
+ For: ''banner, caption, inscription, para, subtitle, tagline, title''.
1258
+
1259
+ Sets the spacing between lines in a text block. Defaults to 4 pixels.
1260
+
1261
+ === :left » a number ===
1262
+
1263
+ For: ''all slots and elements''.
1264
+
1265
+ 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
1266
+ slot containing it. If this style is left unset (or set to `nil`,) the object
1267
+ will flow in with the other objects surrounding it.
1268
+
1269
+ You might also want to give it a :top, if it's acting a bit funny. Sometimes it needs both. :)
1270
+
1271
+ === :margin » a number or an array of four numbers ===
1272
+
1273
+ For: ''all slots and elements''.
1274
+
1275
+ Margins space an element out from its surroundings. Each element has a left,
1276
+ top, right, and bottom margin. If the `:margin` style is set to a single
1277
+ number, the spacing around the element uniformly matches that number. In other
1278
+ words, if `margin: 8` is set, all the margins around the element are set to
1279
+ eight pixels in length.
1280
+
1281
+ This style can also be given an array of four numbers in the form `[left, top,
1282
+ right, bottom]`.
1283
+
1284
+ === :margin_bottom » a number ===
1285
+
1286
+ For: ''all slots and elements''.
1287
+
1288
+ Sets the bottom margin of the element to a specific pixel size.
1289
+
1290
+ === :margin_left » a number ===
1291
+
1292
+ For: ''all slots and elements''.
1293
+
1294
+ Sets the left margin of the element to a specific pixel size.
1295
+
1296
+ === :margin_right » a number ===
1297
+
1298
+ For: ''all slots and elements''.
1299
+
1300
+ Sets the right margin of the element to a specific pixel size.
1301
+
1302
+ === :margin_top » a number ===
1303
+
1304
+ For: ''all slots and elements''.
1305
+
1306
+ Sets the top margin of the element to a specific pixel size.
1307
+
1308
+ === :outer » a number ===
1309
+
1310
+ For: ''star''.
1311
+
1312
+ Sets the outer radius (half of the ''total'' width) of the star, in pixels.
1313
+
1314
+ === :points » a number ===
1315
+
1316
+ For: ''star''.
1317
+
1318
+ How many points does this star have? A style of `points: 5` creates a
1319
+ five-pointed star.
1320
+
1321
+ === :radius » a number ===
1322
+
1323
+ For: ''arc, arrow, background, border, gradient, oval, rect, shape''.
1324
+
1325
+ Sets the radius (half of the diameter or total width) for each of these
1326
+ elements. Setting this is equivalent to setting both `:width` and `:height` to
1327
+ double this number.
1328
+
1329
+ === :right » a number ===
1330
+
1331
+ For: ''all slots and elements''.
1332
+
1333
+ Sets the pixel coordinate of an element's right edge. The edge is placed
1334
+ relative to its container's rightmost edge. So, `right: 0` will align the
1335
+ element so that its own right edge and the right edge of its slot touch.
1336
+ Whereas `right: 20` will position the right edge of the element off to the
1337
+ left of its slot's right edge by twenty pixels.
1338
+
1339
+ === :rise » a number ===
1340
+
1341
+ For: ''banner, caption, code, del, em, ins, inscription, link, para, span,
1342
+ strong, sub, sup, subtitle, tagline, title''.
1343
+
1344
+ Lifts or plunges the font baseline for some text. For example, a
1345
+ [[Element.sup]] has a `:rise` of 10 pixels. Conversely, the [[Element.sub]]
1346
+ element has a `:rise` of -10 pixels.
1347
+
1348
+ === :scroll » true or false ===
1349
+
1350
+ For: ''flow, stack''.
1351
+
1352
+ Establishes this slot as a scrolling slot. If `scroll: true` is set, the
1353
+ slot will show a scrollbar if any of its contents go past its height. The
1354
+ scrollbar will appear and disappear as needed. It will also appear inside the
1355
+ width of the slot, meaning the slot's width will never change, regardless of
1356
+ whether there is a scrollbar or not.
1357
+
1358
+ === :secret » true or false ===
1359
+
1360
+ For: ''ask, edit_line''.
1361
+
1362
+ Used for password fields, this setting keeps any characters typed in from
1363
+ becoming visible on the screen. Instead, a replacement character (such as an
1364
+ asterisk) is show for each letter typed.
1365
+
1366
+ === :size » a number ===
1367
+
1368
+ For: ''banner, caption, code, del, em, ins, inscription, link, para, span,
1369
+ strong, sub, sup, subtitle, tagline, title''.
1370
+
1371
+ Sets the pixel size for the font used inside this text block or text fragment.
1372
+
1373
+ Font size may also be augmented, through use of the following strings:
1374
+
1375
+ * "xx-small" - 57% of present size.
1376
+ * "x-small" - 64% of present size.
1377
+ * "small" - 83% of present size.
1378
+ * "medium" - no change in size.
1379
+ * "large" - 120% of present size.
1380
+ * "x-large" - 143% of present size.
1381
+ * "xx-large" - 173% of present size.
1382
+
1383
+ === :state » a string ===
1384
+
1385
+ For: ''button, check, edit_box, edit_line, list_box, radio''.
1386
+
1387
+ The `:state` style is for disabling or locking certain controls, if you don't
1388
+ want them to be edited.
1389
+
1390
+ Here are the possible style settings:
1391
+
1392
+ * nil - the control is active and editable.
1393
+ * "readonly" - the control is active but cannot be edited.
1394
+ * "disabled" - the control is not active (grayed out) and cannot be edited.
1395
+
1396
+ === :stretch » a string ===
1397
+
1398
+ For: ''banner, caption, code, del, em, ins, inscription, link, para, span,
1399
+ strong, sub, sup, subtitle, tagline, title''.
1400
+
1401
+ Sets the font stretching used for a text object.
1402
+
1403
+ Possible settings are:
1404
+
1405
+ * "condensed" - a smaller width of letters.
1406
+ * "normal" - the standard width of letters.
1407
+ * "expanded" - a larger width of letters.
1408
+
1409
+ === :strikecolor » a Shoes::Color ===
1410
+
1411
+ For: ''banner, caption, code, del, em, ins, inscription, link, para, span,
1412
+ strong, sub, sup, subtitle, tagline, title''.
1413
+
1414
+ The color used to paint any lines stricken through this text.
1415
+
1416
+ === :strikethrough » a string ===
1417
+
1418
+ For: ''banner, caption, code, del, em, ins, inscription, link, para, span,
1419
+ strong, sub, sup, subtitle, tagline, title''.
1420
+
1421
+ Is this text stricken through? Two options here:
1422
+
1423
+ * "none" - no strikethrough
1424
+ * "single" - a single-line strikethrough.
1425
+
1426
+ === :stroke » a hex code, a Shoes::Color or a range of either ===
1427
+
1428
+ For: ''arc, arrow, banner, border, caption, code, del, em, flow, image, ins,
1429
+ inscription, line, link, mask, oval, para, rect, shape, span, stack, star,
1430
+ strong, sub, sup, subtitle, tagline, title''.
1431
+
1432
+ The color of the foreground pen. In the case of shapes, this is the color the
1433
+ lines are drawn with. For paragraphs and other text, the letters are printed
1434
+ in this color.
1435
+
1436
+ === :strokewidth » a number ===
1437
+
1438
+ For: ''arc, arrow, border, flow, image, line, mask, oval, rect, shape, star, stack''.
1439
+
1440
+ The thickness of the stroke, in pixels, of the line defining each of these
1441
+ shapes. For example, the number two would set the strokewidth to 2 pixels.
1442
+
1443
+ === :text » a string ===
1444
+
1445
+ For: ''button, edit_box, edit_line''.
1446
+
1447
+ Sets the message displayed on a button control, or the contents of an edit_box
1448
+ or edit_line.
1449
+
1450
+ === :top » a number ===
1451
+
1452
+ For: ''all slots and elements''.
1453
+
1454
+ Sets the top coordinate for an object, relative to its parent slot. If an
1455
+ object is set with `top: 40`, this means the object's top edge will be
1456
+ placed 40 pixels beneath the top edge of the slot that contains it. If no
1457
+ `:top` style is given, the object is automatically placed in the natural flow
1458
+ of its slot.
1459
+
1460
+ You should probably give it a :left, too, if it's acting strange. It likes to have both. :)
1461
+
1462
+ === :undercolor » a Shoes::Color ===
1463
+
1464
+ For: ''banner, caption, code, del, em, ins, inscription, link, para, span,
1465
+ strong, sub, sup, subtitle, tagline, title''.
1466
+
1467
+ The color used to underline text.
1468
+
1469
+ === :underline » a string ===
1470
+
1471
+ For: ''banner, caption, code, del, em, ins, inscription, link, para, span,
1472
+ strong, sub, sup, subtitle, tagline, title''.
1473
+
1474
+ Dictates the style of underline used in the text.
1475
+
1476
+ The choices for this setting are:
1477
+
1478
+ * "none" - no underline at all.
1479
+ * "single" - a continuous underline.
1480
+ * "double" - two continuous parallel underlines.
1481
+ * "low" - a lower underline, beneath the font baseline. (This is generally recommended only for single characters, particularly when showing keyboard accelerators.)
1482
+ * "error" - a wavy underline, usually found indicating a misspelling.
1483
+
1484
+ === :variant » a string ===
1485
+
1486
+ For: ''banner, caption, code, del, em, ins, inscription, link, para, span,
1487
+ strong, sub, sup, subtitle, tagline, title''.
1488
+
1489
+ Vary the font for a group of text. Two choices:
1490
+
1491
+ * "normal" - standard font.
1492
+ * "smallcaps" - font with the lower case characters replaced by smaller variants of the capital characters.
1493
+
1494
+ === :wedge » true or false ===
1495
+
1496
+ For: ''arc''.
1497
+
1498
+ Indicates how arcs are to be filled. If set to true, the arc is filled as a 'pie chart' style wedge. The default setting of false fills the arc to the chord connecting the end points of the arc.
1499
+
1500
+ === :weight » a string ===
1501
+
1502
+ For: ''banner, caption, code, del, em, ins, inscription, link, para, span,
1503
+ strong, sub, sup, subtitle, tagline, title''.
1504
+
1505
+ Set the boldness of the text. Commonly, this style is set to one of the
1506
+ following strings:
1507
+
1508
+ * "ultralight" - the ultralight weight (= 200)
1509
+ * "light" - the light weight (= 300)
1510
+ * "normal" - the default weight (= 400)
1511
+ * "semibold" - a weight intermediate between normal and bold (= 600)
1512
+ * "bold" - the bold weight (= 700)
1513
+ * "ultrabold" - the ultrabold weight (= 800)
1514
+ * "heavy" - the heavy weight (= 900)
1515
+
1516
+ However, you may also pass in the numerical weight directly.
1517
+
1518
+ === :width » a number ===
1519
+
1520
+ For: ''all slots and elements''.
1521
+
1522
+ Sets the pixel width for the element. If the number is a decimal, the width is
1523
+ converted to a percentage (with 0.0 being 0% and 1.0 being 100%.) A width of
1524
+ 100% means the object fills its parent slot.
1525
+
1526
+ === :wrap » a string ===
1527
+
1528
+ For: ''banner, caption, code, del, em, ins, inscription, link, para, span,
1529
+ strong, sub, sup, subtitle, tagline, title''
1530
+
1531
+ How should the text wrap when it fills its width? Possible options are:
1532
+
1533
+ * "word" - Break lines at word breaks.
1534
+ * "char" - Break lines between characters, thus breaking some words.
1535
+ * "trim" - Cut the line off with an ellipsis if it goes too long.
1536
+
1537
+ == Classes List ==
1538
+
1539
+ Here is a complete list of all the classes introduced by Shoes. This chart is
1540
+ laid out according to how classes inherits from each other. Subclasses are
1541
+ indented one level to the right, beneath their parent class.
1542
+
1543
+ {INDEX}
1544
+
1545
+ == Colors List ==
1546
+
1547
+ The following list of colors can be used throughout Shoes. As background
1548
+ colors or border colors. As stroke and fill colors. Most of these colors come
1549
+ from the X11 and HTML palettes.
1550
+
1551
+ All of these colors can be used by name. (So calling the `tomato` method from
1552
+ inside any slot will get you a nice reddish color.) Below each color, also
1553
+ find the exact numbers which can be used with the [[Built-in.rgb]] method.
1554
+
1555
+ {COLORS}
1556
+
1557
+ = Slots =
1558
+
1559
+ Slots are boxes used to lay out images, text and so on. The two most common
1560
+ slots are `stacks` and `flows`. Slots can also be referred to as "boxes" or
1561
+ "canvases" in Shoes terminology.
1562
+
1563
+ Since the mouse wheel and PageUp and PageDown are so pervasive on every
1564
+ platform, vertical scrolling has really become the only overflow that matters.
1565
+ So, in Shoes, just as on the web, width is generally fixed. While height goes
1566
+ on and on.
1567
+
1568
+ Now, you can also just use specific widths and heights for everything, if you
1569
+ want. That'll take some math, but everything could be perfect.
1570
+
1571
+ Generally, I'd suggest using stacks and flows. The idea here is that you want
1572
+ to fill up a certain width with things, then advance down the page, filling up
1573
+ further widths. You can think of these as being analogous to HTML's "block" and
1574
+ "inline" styles.
1575
+
1576
+ ==== Stacks ====
1577
+
1578
+ A stack is simply a vertical stack of elements. Each element in a stack is
1579
+ placed directly under the element preceding it.
1580
+
1581
+ A stack is also shaped like a box. So if a stack is given a width of 250, that
1582
+ stack is itself an element which is 250 pixels wide.
1583
+
1584
+ To create a new stack, use the [[Element.stack]] method, which is available
1585
+ inside any slot. So stacks can contain other stacks and flows.
1586
+
1587
+ ==== Flows ====
1588
+
1589
+ A flow will pack elements in as tightly as it can. A width will be filled, then
1590
+ will wrap beneath those elements. Text elements placed next to each other will
1591
+ appear as a single paragraph. Images and widgets will run together as a series.
1592
+
1593
+ Like the stack, a flow is a box. So stacks and flows can safely be embedded
1594
+ and, without respect to their contents, are identical. They just treat their
1595
+ contents differently.
1596
+
1597
+ Making a flow means calling the [[Element.flow]] method. Flows may contain
1598
+ other flows and stacks.
1599
+
1600
+ Last thing: The Shoes window itself is a flow.
1601
+
1602
+ == Art for Slots ==
1603
+
1604
+ Each slot is like a canvas, a blank surface which can be covered with an
1605
+ assortment of colored shapes or gradients.
1606
+
1607
+ Many common shapes can be drawn with methods like `oval` and `rect`. You'll
1608
+ need to set up the paintbrush colors first, though.
1609
+
1610
+ The `stroke` command sets the line color. And the `fill` command sets the
1611
+ color used to paint inside the lines.
1612
+
1613
+ {{{
1614
+ #!ruby
1615
+ Shoes.app do
1616
+ stroke red
1617
+ fill blue
1618
+ oval top: 10, left: 10,
1619
+ radius: 100
1620
+ end
1621
+ }}}
1622
+
1623
+ That code gives you a blue pie with a red line around it. One-hundred pixels
1624
+ wide, placed just a few pixels southeast of the window's upper left corner.
1625
+
1626
+ The `blue` and `red` methods above are Color objects. See the section on
1627
+ Colors for more on how to mix colors.
1628
+
1629
+ ==== Inspiration from Processing and NodeBox ====
1630
+
1631
+ The artful methods generally come verbatim from NodeBox, a drawing kit for
1632
+ Python. In turn, NodeBox gets much of its ideas from Processing, a Java-like
1633
+ language for graphics and animation. I owe a great debt to the creators of
1634
+ these wonderful programs!
1635
+
1636
+ Shoes does a few things differently from NodeBox and Processing. For example,
1637
+ Shoes has different color methods, including having its own Color objects,
1638
+ though these are very similar to Processing's color methods. And Shoes also
1639
+ allows images and gradients to be used for drawing lines and filling in shapes.
1640
+
1641
+ Shoes also borrows some animation ideas from Processing and will continue to
1642
+ closely consult Processing's methods as it expands.
1643
+
1644
+ === arc(left, top, width, height, angle1, angle2) » Shoes::Shape ===
1645
+
1646
+ Draws an arc shape (a section of an oval) at coordinates (left, top). This
1647
+ method just give you a bit more control than [[oval]], by offering the
1648
+ `:angle1` and `:angle2` styles. (In fact, you can mimick the `oval` method by
1649
+ setting `:angle1` to 0 and `:angle2` to `Shoes::TWO_PI`.)
1650
+
1651
+ === arrow(left, top, width) » Shoes::Shape ===
1652
+
1653
+ Draws an arrow at coordinates (left, top) with a pixel `width`.
1654
+
1655
+ === cap(:curve or :rect or :project) » self ===
1656
+
1657
+ Sets the line cap, which is the shape at the end of every line you draw. If
1658
+ set to `:curve`, the end is rounded. The default is `:rect`, a line which ends
1659
+ abruptly flat. The `:project` cap is also fat, but sticks out a bit longer.
1660
+
1661
+ === fill(pattern) » pattern ===
1662
+
1663
+ Sets the fill bucket to a specific color (or pattern.) Patterns can be colors,
1664
+ gradients or images. So, once the fill bucket is set, you can draw shapes and
1665
+ they will be colored in with the pattern you've chosen.
1666
+
1667
+ To draw a star with an image pattern:
1668
+
1669
+ {{{
1670
+ #!ruby
1671
+ Shoes.app do
1672
+ fill "static/avatar.png"
1673
+ star 200, 200, 5
1674
+ end
1675
+ }}}
1676
+
1677
+ To clear the fill bucket, use `nofill`. And to set the line color (the border
1678
+ of the star,) use the `stroke` method.
1679
+
1680
+ === nofill() » self ===
1681
+
1682
+ Blanks the fill color, so that any shapes drawn will not be filled in.
1683
+ Instead, shapes will have only a lining, leaving the middle transparent.
1684
+
1685
+ === nostroke() » self ===
1686
+
1687
+ Empties the line color. Shapes drawn will have no outer line. If `nofill` is
1688
+ also set, shapes drawn will not be visible.
1689
+
1690
+ === line(left, top, x2, y2) » Shoes::Shape ===
1691
+
1692
+ Draws a line using the current line color (aka "stroke") starting at
1693
+ coordinates (left, top) and ending at coordinates (x2, y2).
1694
+
1695
+ === oval(left, top, diameter) » Shoes::Shape ===
1696
+
1697
+ Draws a circular form at pixel coordinates (left, top) with a width and height
1698
+ of `diameter` pixels. The line and fill colors are used to draw the shape. By
1699
+ default, the coordinates are for the oval's leftmost, top corner, but this can
1700
+ be changed by calling the [[Art.transform]] method or by using the `:center`
1701
+ style on the next method below.
1702
+
1703
+ {{{
1704
+ #!ruby
1705
+ Shoes.app do
1706
+ stroke blue
1707
+ strokewidth 4
1708
+ fill black
1709
+ oval 10, 10, 50
1710
+ end
1711
+ }}}
1712
+
1713
+ To draw an oval of varied proportions, you may also use the syntax: `oval(left, top, width, height)`.
1714
+
1715
+ === oval(styles) » Shoes::Shape ===
1716
+
1717
+ Draw circular form using a style hash. The following styles are supported:
1718
+
1719
+ * `top`: the y-coordinate for the oval pen.
1720
+ * `left`: the x-coordinate for the oval pen.
1721
+ * `diameter`: the width and height of the circle.
1722
+ * `width`: a specific pixel width for the oval.
1723
+ * `height`: a specific pixel height for the oval.
1724
+ * `center`: do the coordinates specific the oval's center? (true or false)
1725
+
1726
+ These styles may also be altered using the `style` method on the Shape object.
1727
+
1728
+ === rect(left, top, width, height, corners = 0) » Shoes::Shape ===
1729
+
1730
+ Draws a rectangle starting from coordinates (left, top) with dimensions of
1731
+ width x height. Optionally, you may give the rectangle rounded corners with a
1732
+ fifth argument: the radius of the corners in pixels.
1733
+
1734
+ Alternate Call:
1735
+ rect(left, top, sidelength): Will draw a square with sides having the given length
1736
+
1737
+
1738
+ As with all other shapes, the rectangle is drawn using the stroke and fill colors.
1739
+
1740
+ {{{
1741
+ #!ruby
1742
+ Shoes.app do
1743
+ stroke rgb(0.5, 0.5, 0.7)
1744
+ fill rgb(1.0, 1.0, 0.9)
1745
+ rect 10, 10, self.width - 20, self.height - 20
1746
+ end
1747
+ }}}
1748
+
1749
+ The above sample draws a rectangle which fills the area of its parent box,
1750
+ leaving a margin of 10 pixels around the edge. Also see the `background`
1751
+ method for a rectangle which defaults to filling its parent box.
1752
+
1753
+ === rect(styles) » Shoes::Shape ===
1754
+
1755
+ Draw a rectangle using a style hash. The following styles are supported:
1756
+
1757
+ * `left`: the x-coordinate for the rectangle.
1758
+ * `top`: the y-coordinate for the rectangle.
1759
+ * `curve`: the pixel radius of the rectangle's corners.
1760
+ * `width`: a specific pixel width for the rectangle.
1761
+ * `height`: a specific pixel height for the rectangle.
1762
+ * `center`: do the coordinates specific the rectangle's center? (true or false)
1763
+
1764
+ These styles may also be altered using the `style` method on the Shape object.
1765
+
1766
+ === rotate(degrees: a number) » self ===
1767
+
1768
+ Rotates the pen used for drawing by a certain number of `degrees`, so that any
1769
+ shapes will be drawn at that angle.
1770
+
1771
+ In this example below, the rectangle drawn at (30, 30) will be rotated 45 degrees.
1772
+
1773
+ {{{
1774
+ #!ruby
1775
+ Shoes.app do
1776
+ fill "#333"
1777
+ rotate 45
1778
+ rect 30, 30, 40, 40
1779
+ end
1780
+ }}}
1781
+
1782
+ === shape(left, top) { ... } » Shoes::Shape ===
1783
+
1784
+ Describes an arbitrary shape to draw, beginning at coordinates (left, top) and
1785
+ continued by calls to `line_to`, `move_to`, `curve_to` and `arc_to` inside the
1786
+ block. You can look at it as sketching a shape with a long line that curves
1787
+ and arcs and bends.
1788
+
1789
+ {{{
1790
+ #!ruby
1791
+ Shoes.app do
1792
+ fill red(0.2)
1793
+ shape do
1794
+ move_to(90, 55)
1795
+ arc_to(50, 55, 50, 50, 0, Shoes::PI/2)
1796
+ arc_to(50, 55, 60, 60, Shoes::PI/2, Shoes::PI)
1797
+ arc_to(50, 55, 70, 70, Shoes::PI, Shoes::TWO_PI-Shoes::PI/2)
1798
+ arc_to(50, 55, 80, 80, Shoes::TWO_PI-Shoes::PI/2, Shoes::TWO_PI)
1799
+ end
1800
+ end
1801
+ }}}
1802
+
1803
+ A shape can also contain other shapes. So, you can place an [[Art.oval]], a
1804
+ [[Art.rect]], a [[Art.line]], a [[Art.star]] or an [[Art.arrow]] (and all of
1805
+ the other methods in this [[Art]] section) inside a shape, but they will not be
1806
+ part of the line. They will be more like a group of shapes are all drawn as
1807
+ one.
1808
+
1809
+ === shape(styles) » Shoes::Shape ===
1810
+
1811
+ Draw an arbitrary shape using a style hash. The following styles are supported:
1812
+
1813
+ * `left`: the x-coordinate for the shape.
1814
+ * `top`: the y-coordinate for the shape.
1815
+
1816
+ These styles may also be altered using the `style` method on the shape object.
1817
+
1818
+ === star(left, top, points = 10, outer = 100.0, inner = 50.0) » Shoes::Shape ===
1819
+
1820
+ Draws a star using the stroke and fill colors. The star is positioned with its
1821
+ center point at coordinates (left, top) with a certain number of `points`. The
1822
+ `outer` width defines the full radius of the star; the `inner` width specifies
1823
+ the radius of the star's middle, where points stem from.
1824
+
1825
+ === stroke(pattern) » pattern ===
1826
+
1827
+ Set the active line color for this slot. The `pattern` may be a color, a
1828
+ gradient or an image, all of which are categorized as "patterns." The line
1829
+ color is then used to draw the borders of any subsequent shape.
1830
+
1831
+ So, to draw an arrow with a red line around it:
1832
+
1833
+ {{{
1834
+ #!ruby
1835
+ Shoes.app do
1836
+ stroke red
1837
+ arrow 0, 100, 10
1838
+ end
1839
+ }}}
1840
+
1841
+ To clear the line color, use the `nostroke` method.
1842
+
1843
+ === strokewidth(a number) » self ===
1844
+
1845
+ Sets the line size for all drawing within this slot. Whereas the `stroke`
1846
+ method alters the line color, the `strokewidth` method alters the line size in
1847
+ pixels. Calling `strokewidth(4)` will cause lines to be drawn 4 pixels wide.
1848
+
1849
+ === transform(:center or :corner) » self ===
1850
+
1851
+ Should transformations (such as `skew` and `rotate`) be performed around the
1852
+ center of the shape? Or the corner of the shape? Shoes defaults to `:corner`.
1853
+
1854
+ === translate(left, top) » self ===
1855
+
1856
+ Moves the starting point of the drawing pen for this slot. Normally, the pen
1857
+ starts at (0, 0) in the top-left corner, so that all shapes are drawn from that
1858
+ point. With `translate`, if the starting point is moved to (10, 20) and a
1859
+ shape is drawn at (50, 60), then the shape is actually drawn at (60, 80) on the
1860
+ slot.
1861
+
1862
+ == Element Creation ==
1863
+
1864
+ Shoes has a wide variety of elements, many cherry-picked from HTML. This page
1865
+ describes how to create these elements in a slot. See the Elements section of
1866
+ the manual for more on how to modify and use these elements after they have
1867
+ been placed.
1868
+
1869
+ === animate(fps) { |frame| ... } » Shoes::Animation ===
1870
+
1871
+ Starts an animation timer, which runs parallel to the rest of the app. The
1872
+ `fps` is a number, the frames per seconds. This number dictates how many times
1873
+ per second the attached block will be called.
1874
+
1875
+ The block is given a `frame` number. Starting with zero, the `frame` number
1876
+ tells the block how many frames of the animation have been shown.
1877
+
1878
+ {{{
1879
+ #!ruby
1880
+ Shoes.app do
1881
+ @counter = para "STARTING"
1882
+ animate(24) do |frame|
1883
+ @counter.replace "FRAME #{frame}"
1884
+ end
1885
+ end
1886
+ }}}
1887
+
1888
+ The above animation is shown 24 times per second. If no number is given, the
1889
+ `fps` defaults to 10.
1890
+
1891
+ === background(pattern) » Shoes::Background ===
1892
+
1893
+ Draws a Background element with a specific color (or pattern.) Patterns can be
1894
+ colors, gradients or images. Colors and images will tile across the
1895
+ background. Gradients stretch to fill the background.
1896
+
1897
+ '''PLEASE NOTE:''' Backgrounds are actual elements, not styles. HTML treats
1898
+ backgrounds like styles. Which means every box can only have one background.
1899
+ Shoes layers background elements.
1900
+
1901
+ {{{
1902
+ #!ruby
1903
+ Shoes.app do
1904
+ background black
1905
+ background white, width: 50
1906
+ end
1907
+ }}}
1908
+
1909
+ The above example paints two backgrounds. First, a black background is painted
1910
+ over the entire app's surface area. Then a 50 pixel white stripe is painted
1911
+ along the left side.
1912
+
1913
+ === banner(text) » Shoes::Banner ===
1914
+
1915
+ Creates a Banner text block. Shoes automatically styles this text to 48 pixels high.
1916
+
1917
+ === border(text, strokewidth: a number) » Shoes::Border ===
1918
+
1919
+ Draws a Border element using a specific color (or pattern.) Patterns can be
1920
+ colors, gradients or images. Colors and images will tile across the border.
1921
+ Gradients stretch to fill the border.
1922
+
1923
+ '''PLEASE NOTE:''' Like Backgrounds, Borders are actual elements, not styles.
1924
+ HTML treats backgrounds and borders like styles. Which means every box can
1925
+ only have one borders. Shoes layers border and background elements, along with
1926
+ text blocks, images, and everything else.
1927
+
1928
+ === button(text) { ... } » Shoes::Button ===
1929
+
1930
+ Adds a push button with the message `text` written across its surface. An
1931
+ optional block can be attached, which is called if the button is pressed.
1932
+
1933
+ === caption(text) » Shoes::Caption ===
1934
+
1935
+ Creates a Caption text block. Shoes styles this text to 14 pixels high.
1936
+
1937
+ === check() » Shoes::Check ===
1938
+
1939
+ Adds a check box.
1940
+
1941
+ === code(text) » Shoes::Code ===
1942
+
1943
+ Create a Code text fragment. This text defaults to a monospaced font.
1944
+
1945
+ === del(text) » Shoes::Del ===
1946
+
1947
+ Creates a Del text fragment (short for "deleted") which defaults to text with a
1948
+ single strikethrough in its middle.
1949
+
1950
+ === dialog(styles) { ... } » Shoes::App ===
1951
+
1952
+ Opens a new app window (just like the [[Element.window]] method does,) but the
1953
+ window is given a dialog box look.
1954
+
1955
+ === edit_box(text) » Shoes::EditBox ===
1956
+
1957
+ Adds a large, multi-line textarea to this slot. The `text` is optional and
1958
+ should be a string that will start out the box. An optional block can be
1959
+ attached here which is called any type the user changes the text in the box.
1960
+
1961
+ {{{
1962
+ #!ruby
1963
+ Shoes.app do
1964
+ edit_box
1965
+ edit_box "HORRAY EDIT ME"
1966
+ edit_box "small one", width: 100, height: 160
1967
+ end
1968
+ }}}
1969
+
1970
+ === edit_line(text) » Shoes::EditLine ===
1971
+
1972
+ Adds a single-line text box to this slot. The `text` is optional and should be
1973
+ a string that will start out the box. An optional block can be attached here
1974
+ which is called any type the user changes the text in the box.
1975
+
1976
+ === em(text) » Shoes::Em ===
1977
+
1978
+ Creates an Em text fragment (short for "emphasized") which, by default, is
1979
+ styled with italics.
1980
+
1981
+ === every(seconds) { |count| ... } » Shoes::Every ===
1982
+
1983
+ A timer similar to the `animation` method, but much slower. This timer fires a
1984
+ given number of seconds, running the block attached. So, for example, if you
1985
+ need to check a web site every five minutes, you'd call `every(300)` with a
1986
+ block containing the code to actually ping the web site.
1987
+
1988
+ === flow(styles) { ... } » Shoes::Flow ===
1989
+
1990
+ A flow is an invisible box (or "slot") in which you place Shoes elements. Both
1991
+ flows and stacks are explained in great detail on the main [[Slots]] page.
1992
+
1993
+ Flows organize elements horizontally. Where one would use a [[Element.stack]]
1994
+ to keep things stacked vertically, a flow places its contents end-to-end across
1995
+ the page. Once the end of the page is reached, the flow starts a new line of
1996
+ elements.
1997
+
1998
+ === image(path) » Shoes::Image ===
1999
+
2000
+ Creates an [[Image]] element for displaying a picture. PNG, JPEG and GIF
2001
+ formats are allowed.
2002
+
2003
+ The `path` can be a file path or a URL. All images loaded are temporarily
2004
+ cached in memory, but remote images are also cached locally in the user's
2005
+ personal Shoes directory. Remote images are loaded in the background; as with
2006
+ browsers, the images will not appear right away, but will be shown when they
2007
+ are loaded.
2008
+
2009
+ === imagesize(path) » [width, height] ===
2010
+
2011
+ Quickly grab the width and height of an image. The image won't be loaded into
2012
+ the cache or displayed.
2013
+
2014
+ URGENT NOTE: This method cannot be used with remote images (loaded from HTTP,
2015
+ rather than the hard drive.)
2016
+
2017
+ === ins(text) » Shoes::Ins ===
2018
+
2019
+ Creates an Ins text fragment (short for "inserted") which Shoes styles with a
2020
+ single underline.
2021
+
2022
+ === inscription(text) » Shoes::Inscription ===
2023
+
2024
+ Creates an Inscription text block. Shoes styles this text at 10 pixels high.
2025
+
2026
+ === link(text, click: proc or string) » Shoes::Link ===
2027
+
2028
+ Creates a Link text block, which Shoes styles with a single underline and
2029
+ colors with a #06E (blue) colored stroke.
2030
+
2031
+ The default LinkHover style is also single-underlined with a #039 (dark blue) stroke.
2032
+
2033
+ === list_box(items: [strings, ...]) » Shoes::ListBox ===
2034
+
2035
+ Adds a drop-down list box containing entries for everything in the `items`
2036
+ array. An optional block may be attached, which is called if anything in the
2037
+ box becomes selected by the user.
2038
+
2039
+ {{{
2040
+ #!ruby
2041
+ Shoes.app do
2042
+ stack margin: 10 do
2043
+ para "Pick a card:"
2044
+ list_box items: ["Jack", "Ace", "Joker"]
2045
+ end
2046
+ end
2047
+ }}}
2048
+
2049
+ Call `ListBox#text` to get the selected string. See the `ListBox` section
2050
+ under `Native` controls for more help.
2051
+
2052
+ === progress() » Shoes::Progress ===
2053
+
2054
+ Adds a progress bar.
2055
+
2056
+ === para(text) » Shoes::Para ===
2057
+
2058
+ Create a Para text block (short for "paragraph") which Shoes styles at 12
2059
+ pixels high.
2060
+
2061
+ === radio(group name: a string or symbol) » Shoes::Radio ===
2062
+
2063
+ Adds a radio button. If a `group name` is given, the radio button is
2064
+ considered part of a group. Among radio buttons in the same group, only one
2065
+ may be checked. (If no group name is given, the radio button is grouped with
2066
+ any other radio buttons in the same slot.)
2067
+
2068
+ === span(text) » Shoes::Span ===
2069
+
2070
+ Creates a Span text fragment, unstyled by default.
2071
+
2072
+ === stack(styles) { ... } » Shoes::Stack ===
2073
+
2074
+ Creates a new stack. A stack is a type of slot. (See the main [[Slots]] page
2075
+ for a full explanation of both stacks and flows.)
2076
+
2077
+ In short, stacks are an invisible box (a "slot") for placing stuff. As you add
2078
+ things to the stack, such as buttons or images, those things pile up
2079
+ vertically. Yes, they stack up!
2080
+
2081
+ === strong(text) » Shoes::Strong ===
2082
+
2083
+ Creates a Strong text fragment, styled in bold by default.
2084
+
2085
+ === sub(text) » Shoes::Sub ===
2086
+
2087
+ Creates a Sub text fragment (short for "subscript") which defaults to lowering
2088
+ the text by 10 pixels and styling it in an x-small font.
2089
+
2090
+ === subtitle(text) » Shoes::Subtitle ===
2091
+
2092
+ Creates a Subtitle text block. Shoes styles this text to 26 pixels high.
2093
+
2094
+ === sup(text) » Shoes::Sup ===
2095
+
2096
+ Creates a Sup text fragment (short for "superscript") which defaults to raising
2097
+ the text by 10 pixels and styling it in an x-small font.
2098
+
2099
+ === tagline(text) » Shoes::Tagline ===
2100
+
2101
+ Creates a Tagline text block. Shoes styles this text to 18 pixels high.
2102
+
2103
+ === timer(seconds) { ... } » Shoes::Timer ===
2104
+
2105
+ A one-shot timer. If you want to schedule to run some code in a few seconds
2106
+ (or minutes, hours) you can attach the code as a block here.
2107
+
2108
+ To display an alert box five seconds from now:
2109
+
2110
+ {{{
2111
+ #!ruby
2112
+ Shoes.app do
2113
+ timer(5) do
2114
+ alert("Your five seconds are up.")
2115
+ end
2116
+ end
2117
+ }}}
2118
+
2119
+ === title(text) » Shoes::Title ===
2120
+
2121
+ Creates a Title text block. Shoes styles these elements to 34 pixels high.
2122
+
2123
+ === video(path or url) » Shoes::Video ===
2124
+
2125
+ Embeds a movie in this slot.
2126
+
2127
+ === window(styles) { ... } » Shoes::App ===
2128
+
2129
+ Opens a new app window. This method is almost identical to the
2130
+ [[App.Shoes.app]] method used to start an app in the first place. The
2131
+ difference is that the `window` method sets the new window's [[App.owner]]
2132
+ property. (A normal Shoes.app has its `owner` set to `nil`.)
2133
+
2134
+ So, the new window's `owner` will be set to the Shoes::App which launched the
2135
+ window. This way the child window can call the parent.
2136
+
2137
+ {{{
2138
+ #!ruby
2139
+ Shoes.app title: "The Owner" do
2140
+ button "Pop up?" do
2141
+ window do
2142
+ para "Okay, popped up from #{owner}"
2143
+ end
2144
+ end
2145
+ end
2146
+ }}}
2147
+
2148
+ == Events ==
2149
+
2150
+ Wondering how to catch stray mouse clicks or keyboard typing? Events are sent
2151
+ to a slot whenever a mouse moves inside the slot. Or whenever a key is
2152
+ pressed. Even when the slot is created or destroyed. You can attach a block
2153
+ to each of these events.
2154
+
2155
+ Mouse events include `motion`, `click`, `hover` and `leave`. Keyboard typing
2156
+ is represented by the `keypress` event. And the `start` and `finish` events
2157
+ indicate when a canvas comes into play or is discarded.
2158
+
2159
+ So, let's say you want to change the background of a slot whenever the mouse
2160
+ floats over it. We can use the `hover` event to change the background when the
2161
+ mouse comes inside the slot. And `leave` to change back when the mouse floats
2162
+ away.
2163
+
2164
+ {{{
2165
+ #!ruby
2166
+ Shoes.app do
2167
+ s = stack width: 200, height: 200 do
2168
+ background red
2169
+ hover do
2170
+ s.clear { background blue }
2171
+ end
2172
+ leave do
2173
+ s.clear { background red }
2174
+ end
2175
+ end
2176
+ end
2177
+ }}}
2178
+
2179
+ === click { |button, left, top| ... } » self ===
2180
+
2181
+ The click block is called when a mouse button is clicked. The `button` is the
2182
+ number of the mouse button which has been pressed. The `left` and `top` are
2183
+ the mouse coordinates at which the click happened.
2184
+
2185
+ To catch the moment when the mouse is unclicked, see the [[Events.release]] event.
2186
+
2187
+ === finish { |self| ... } » self ===
2188
+
2189
+ When a slot is removed, it's finish event occurs. The finish block is
2190
+ immediately handed `self`, the slot object which has been removed.
2191
+
2192
+ === hover { |self| ... } » self ===
2193
+
2194
+ The hover event happens when the mouse enters the slot. The block gets `self`,
2195
+ meaning the object which was hovered over.
2196
+
2197
+ To catch the mouse exiting the slot, check out the [[Events.leave]] event.
2198
+
2199
+ === keypress { |key| ... } » self ===
2200
+
2201
+ Whenever a key (or combination of keys) is pressed, the block gets called. The
2202
+ block is sent a `key` which is a string representing the character (such as the
2203
+ letter or number) on the key. For special keys and key combos, a Ruby symbol
2204
+ is sent, rather than a string.
2205
+
2206
+ So, for example, if `Shift-a` is pressed, the block will get the string `"A"`.
2207
+
2208
+ However, if the F1 key is pressed, the `:f1` symbol is received. For
2209
+ `Shift-F1`, the symbol would be `:shift_f1`.
2210
+
2211
+ The modifier keys are `control`, `shift` and `alt`. They appear in that order.
2212
+ If `Shift-Control-Alt-PgUp` is pressed, the symbol will be
2213
+ `:control_shift_alt_page_up`.
2214
+
2215
+ One thing about the shift key. You won't see the shift key on most keys. On
2216
+ US keyboards, `Shift-7` is an ampersand. So you'll get the string `"&"` rather
2217
+ than `:shift_5`. And, if you press `Shift-Alt-7` on such a keyboard, you'll
2218
+ get the symbol: `:alt_&`. You'll only see the shift modifier on the special
2219
+ keys listed a few paragraphs down.
2220
+
2221
+ {{{
2222
+ #!ruby
2223
+ Shoes.app do
2224
+ @info = para "NO KEY is PRESSED."
2225
+ keypress do |k|
2226
+ @info.replace "#{k.inspect} was PRESSED."
2227
+ end
2228
+ end
2229
+ }}}
2230
+
2231
+ Keep in mind that Shoes itself uses a few hotkeys. Alt-Period (`:alt_.`),
2232
+ Alt-Question (`:alt_?`) and Alt-Slash (`:alt_/`) are reserved for Shoes.
2233
+
2234
+ The list of special keys is as follows: `:escape`, `:delete`, `:backspace`,
2235
+ `:tab`, `:page_up`, `:page_down`, `:home`, `:end`, `:left`, `:up`, `:right`,
2236
+ `:down`, `:f1`, `:f2`, `:f3`, `:f4`, `:f5`, `:f6`, `:f7`, `:f8`, `:f9`, `:f10`,
2237
+ `:f11` and `:f12`.
2238
+
2239
+ One caveat to all of those rules: normally the Return key gives you a string
2240
+ `"\n"`. When pressed with modifier keys, however, you end up with
2241
+ `:control_enter`, `:control_alt_enter`, `:shift_alt_enter` and the like.
2242
+
2243
+ === leave { |self| ... } » self ===
2244
+
2245
+ The leave event takes place when the mouse cursor exits a slot. The moment it
2246
+ no longer is inside the slot's edges. When that takes place, the block is
2247
+ called with `self`, the slot object which is being left.
2248
+
2249
+ Also see [[Events.hover]] if you'd like to detect the mouse entering a slot.
2250
+
2251
+ === motion { |left, top| ... } » self ===
2252
+
2253
+ The motion block gets called every time the mouse moves around inside the slot.
2254
+ The block is handed the cursor's `left` and `top` coordinates.
2255
+
2256
+ {{{
2257
+ #!ruby
2258
+ Shoes.app width: 200, height: 200 do
2259
+ background black
2260
+ fill white
2261
+ @circ = oval 0, 0, 100, 100
2262
+
2263
+ motion do |top, left|
2264
+ @circ.move top - 50, left - 50
2265
+ end
2266
+ end
2267
+ }}}
2268
+
2269
+ === release { |button, left, top| ... } » self ===
2270
+
2271
+ The release block runs whenever the mouse is unclicked (on mouse up). When the
2272
+ finger is lifted. The `button` is the number of the button that was depressed.
2273
+ The `left` and `top` are the coordinates of the mouse at the time the button
2274
+ was released.
2275
+
2276
+ To catch the actual mouse click, use the [[Events.click]] event.
2277
+
2278
+ === resize { |self| ... } » self ===
2279
+
2280
+ The resize block runs whenever the app is resized. Be careful with this one, since
2281
+ the block will be fired with every pixel of motion, even a simple resize may call
2282
+ the block dozens of times.
2283
+
2284
+ === start { |self| ... } » self ===
2285
+
2286
+ The first time the slot is drawn, the start event fires. The block is handed
2287
+ `self`, the slot object which has just been drawn.
2288
+
2289
+ == Manipulation Blocks ==
2290
+
2291
+ The manipulation methods below make quick work of shifting around slots and
2292
+ inserting new elements.
2293
+
2294
+ === append() { ... } » self ===
2295
+
2296
+ Adds elements to the end of a slot.
2297
+
2298
+ {{{
2299
+ #!ruby
2300
+ Shoes.app do
2301
+ @slot = stack { para 'Good Morning' }
2302
+ timer 3 do
2303
+ @slot.append do
2304
+ title "Breaking News"
2305
+ tagline "Astronauts arrested for space shuttle DUI."
2306
+ end
2307
+ end
2308
+ end
2309
+ }}}
2310
+
2311
+ The `title` and `tagline` elements will be added to the end of the `@slot`.
2312
+
2313
+ === after(element) { ... } » self ===
2314
+
2315
+ Adds elements to a specific place in a slot, just after the `element` which is
2316
+ a child of the slot.
2317
+
2318
+ === before(element) { ... } » self ===
2319
+
2320
+ Adds elements to a specific place in a slot, just before the `element` which is
2321
+ a child of the slot.
2322
+
2323
+ === clear() » self ===
2324
+
2325
+ Empties the slot of any elements, timers and nested slots. This is effectively
2326
+ identical to looping through the contents of the slot and calling each
2327
+ element's `remove` method.
2328
+
2329
+ === clear() { ... } » self ===
2330
+
2331
+ The clear method also takes an optional block. The block will be used to
2332
+ replace the contents of the slot.
2333
+
2334
+ {{{
2335
+ #!ruby
2336
+ Shoes.app do
2337
+ @slot = stack { para "Old text" }
2338
+ timer 3 do
2339
+ @slot.clear { para "Brand new text" }
2340
+ end
2341
+ end
2342
+ }}}
2343
+
2344
+ In this example, the "Old text" paragraph will be cleared out, replaced by the
2345
+ "Brand new text" paragraph.
2346
+
2347
+ === prepend() { ... } » self ===
2348
+
2349
+ Adds elements to the beginning of a slot.
2350
+
2351
+ {{{
2352
+ #!ruby
2353
+ Shoes.app do
2354
+ @slot = stack { para 'Good Morning' }
2355
+ timer 3 do
2356
+ @slot.prepend { para "Your car is ready." }
2357
+ end
2358
+ end
2359
+ }}}
2360
+
2361
+ The `para` element is added to the beginning of the `@slot`.
2362
+
2363
+ == Position of a Slot ==
2364
+
2365
+ Like any other element, slots can be styled and customized when they are created.
2366
+
2367
+ To set the width of a stack to 150 pixels:
2368
+
2369
+ {{{
2370
+ #!ruby
2371
+ Shoes.app do
2372
+ stack(width: 150) { para "Now that's precision." }
2373
+ end
2374
+ }}}
2375
+
2376
+ Each style setting also has a method, which can be used to grab that particular
2377
+ setting. (So, like, the `width` method returns the width of the slot in
2378
+ pixels.)
2379
+
2380
+ === displace(left: a number, top: a number) » self ===
2381
+
2382
+ A shortcut method for setting the :displace_left and :displace_top styles.
2383
+ Displacing is a handy way of moving a slot without altering the layout. In
2384
+ fact, the `top` and `left` methods will not report displacement at all. So,
2385
+ generally, displacement is only for temporary animations. For example,
2386
+ jiggling a button in place.
2387
+
2388
+ The `left` and `top` numbers sent to `displace` are added to the slot's own
2389
+ top-left coordinates. To subtract from the top-left coordinate, use negative
2390
+ numbers.
2391
+
2392
+ === gutter() » a number ===
2393
+
2394
+ The size of the scrollbar area. When Shoes needs to show a scrollbar, the
2395
+ scrollbar may end up covering up some elements that touch the edge of the
2396
+ window. The `gutter` tells you how many pixels to expect the scrollbar to
2397
+ cover.
2398
+
2399
+ This is commonly used to pad elements on the right, like so:
2400
+
2401
+ {{{
2402
+ #!ruby
2403
+ Shoes.app do
2404
+ stack margin_right: 20 + gutter do
2405
+ para "Insert fat and ratified declaration of independence here..."
2406
+ end
2407
+ end
2408
+ }}}
2409
+
2410
+ === height() » a number ===
2411
+
2412
+ The vertical size of the viewable slot in pixels. So, if this is a scrolling
2413
+ slot, you'll need to use `scroll_height()` to get the full size of the slot.
2414
+
2415
+ === hide() » self ===
2416
+
2417
+ Hides the slot, so that it can't be seen. See also [[Position.show]] and [[Position.toggle]].
2418
+
2419
+ === left() » a number ===
2420
+
2421
+ The left pixel location of the slot. Also known as the x-axis coordinate.
2422
+
2423
+ === move(left, top) » self ===
2424
+
2425
+ Moves the slot to specific coordinates, the (left, top) being the upper left
2426
+ hand corner of the slot.
2427
+
2428
+ === remove() » self ===
2429
+
2430
+ Removes the slot. It will no longer be displayed and will not be listed in its
2431
+ parent's contents. It's gone.
2432
+
2433
+ === scroll() » true or false ===
2434
+
2435
+ Is this slot allowed to show a scrollbar? True or false. The scrollbar will
2436
+ only appear if the height of the slot is also fixed.
2437
+
2438
+ === scroll_height() » a number ===
2439
+
2440
+ The vertical size of the full slot, including any of it which is hidden by scrolling.
2441
+
2442
+ === scroll_max() » a number ===
2443
+
2444
+ The top coordinate which this slot can be scrolled down to. The top coordinate
2445
+ of a scroll bar is always zero. The bottom coordinate is the full height of
2446
+ the slot minus one page of scrolling. This bottom coordinate is what
2447
+ `scroll_max` returns.
2448
+
2449
+ This is basically a shortcut for writing `slot.scroll_height - slot.height`.
2450
+
2451
+ To scroll to the bottom of a slot, use `slot.scroll_top = slot.scroll_max`.
2452
+
2453
+ === scroll_top() » a number ===
2454
+
2455
+ The top coordinate which this slot is scrolled down to. So, if the slot is
2456
+ scrolled down twenty pixels, this method will return `20`.
2457
+
2458
+ === scroll_top = a number ===
2459
+
2460
+ Scrolls the slot to a certain coordinate. This must be between zero and
2461
+ `scroll_max`.
2462
+
2463
+ === show() » self ===
2464
+
2465
+ Reveals the slot, if it is hidden. See also [[Position.hide]] and
2466
+ [[Position.toggle]].
2467
+
2468
+ === style() » styles ===
2469
+
2470
+ Calling the `style` method with no arguments returns a hash of the styles
2471
+ presently applied to this slot.
2472
+
2473
+ While methods such as `height` and `width` return the true pixel dimensions of
2474
+ the slot, you can use `style[:height]` or `style[:width]` to get the dimensions
2475
+ originally requested.
2476
+
2477
+ {{{
2478
+ #!ruby
2479
+ Shoes.app do
2480
+ @s = stack width: "100%"
2481
+ para @s.style[:width]
2482
+ end
2483
+ }}}
2484
+
2485
+ In this example, the paragraph under the stack will display the string "100%".
2486
+
2487
+ === style(styles) » styles ===
2488
+
2489
+ Alter the slot using a hash of style settings. Any of the methods on this page
2490
+ (aside from this method, of course) can be used as a style setting. So, for
2491
+ example, there is a `width` method, thus there is also a `width` style.
2492
+
2493
+ {{{
2494
+ #!ruby
2495
+ Shoes.app do
2496
+ @s = stack { background green }
2497
+ @s.style(width: 400, height: 200)
2498
+ end
2499
+ }}}
2500
+
2501
+ === toggle() » self ===
2502
+
2503
+ Hides the slot, if it is shown. Or shows the slot, if it is hidden.
2504
+
2505
+ === top() » a number ===
2506
+
2507
+ The top pixel location of the slot. Also known as the y-axis coordinate.
2508
+
2509
+ === width() » a number ===
2510
+
2511
+ The horizontal size of the slot in pixels.
2512
+
2513
+ == Traversing the Page ==
2514
+
2515
+ You may find yourself needing to loop through the elements inside a slot. Or
2516
+ maybe you need to climb the page, looking for a stack that is the parent of an
2517
+ element.
2518
+
2519
+ On any element, you may call the `parent` method to get the slot directly above
2520
+ it. And on slots, you can call the `contents` method to get all of the
2521
+ children. (Some elements, such as text blocks, also have a `contents` method
2522
+ for getting their children.)
2523
+
2524
+ === contents() » an array of elements ===
2525
+
2526
+ Lists all elements in a slot.
2527
+
2528
+ === parent() » a Shoes::Stack or Shoes::Flow ===
2529
+
2530
+ Gets the object for this element's container.
2531
+
2532
+ = Elements =
2533
+
2534
+ Ah, here's the stuff of Shoes. An element can be as simple as an oval shape. Or
2535
+ as complex as a video stream. You've encountered all of these elements before
2536
+ in the Slots section of the manual.
2537
+
2538
+ Shoes has seven native controls: the Button, the EditLine, the EditBox, the
2539
+ ListBox, the Progress meter, the Check box and the Radio. By "native"
2540
+ controls, we mean that each of these seven elements is drawn by the operating
2541
+ system. So, a Progress bar will look one way on Windows and another way on OS
2542
+ X.
2543
+
2544
+ Shoes also has seven basic other types of elements: Background, Border, Image,
2545
+ Shape, TextBlock, Timer and Video. These all should look and act the same on
2546
+ every operating system.
2547
+
2548
+ Once an element is created, you will often still want to change it. To move it
2549
+ or hide it or get rid of it. You'll use the commands in this section to do that
2550
+ sort of stuff. (Especially check out the [[Common Common Methods]] section for
2551
+ commands you can use on any element.)
2552
+
2553
+ So, for example, use the `image` method of a Slot to place a PNG on the screen.
2554
+ The `image` method gives you back an Image object. Use the methods of the Image
2555
+ object to change things up.
2556
+
2557
+ == Common Methods ==
2558
+
2559
+ A few methods are shared by every little element in Shoes. Moving, showing,
2560
+ hiding. Removing an element. Basic and very general things. This list
2561
+ encompasses those common commands.
2562
+
2563
+ One of the most general methods of all is the `style` method (which is also
2564
+ covered as the [[Position.style]] method for slots.)
2565
+
2566
+ {{{
2567
+ #!ruby
2568
+ Shoes.app do
2569
+ stack do
2570
+ # Background, text and a button: both are elements!
2571
+ @back = background green
2572
+ @text = banner "A Message for You, Rudy"
2573
+ @press = button "Stop your messin about!"
2574
+
2575
+ # And so, both can be styled.
2576
+ @text.style size: 12, stroke: red, margin: 10
2577
+ @press.style width: 400
2578
+ @back.style height: 10
2579
+ end
2580
+ end
2581
+ }}}
2582
+
2583
+ For specific commands, see the other links to the left in the Elements section.
2584
+ Like if you want to pause or play a video file, check the [[Video]] section,
2585
+ since pausing and playing is peculiar to videos. No sense pausing a button.
2586
+
2587
+ === displace(left: a number, top: a number) » self ===
2588
+
2589
+ Displacing an element moves it. But without changing the layout around it.
2590
+ This is great for subtle animations, especially if you want to reserve a place
2591
+ for an element while it is still animating. Like maybe a quick button shake or
2592
+ a slot sliding into view.
2593
+
2594
+ When you displace an element, it moves relative to the upper-left corner where
2595
+ it was placed. So, if an element is at the coordinates (20, 40) and you
2596
+ displace it 2 pixels left and 6 pixels on top, you end up with the coordinates
2597
+ (22, 46).
2598
+
2599
+ {{{
2600
+ #!ruby
2601
+ Shoes.app do
2602
+ flow margin: 12 do
2603
+ # Set up three buttons
2604
+ button "One"
2605
+ @two = button "Two"
2606
+ button "Three"
2607
+
2608
+ # Bounce the second button
2609
+ animate do |i|
2610
+ @two.displace(0, (Math.sin(i) * 6).to_i)
2611
+ end
2612
+ end
2613
+ end
2614
+ }}}
2615
+
2616
+ Notice that while the second button bounces, the other two buttons stay put.
2617
+ If we used a normal `move` in this situation, the second button would be moved
2618
+ out of the layout and the buttons would act as if the second button wasn't
2619
+ there at all. (See the [[Common.move]] example.)
2620
+
2621
+ '''Of particular note:''' if you use the `left` and `top` methods to get the
2622
+ coordinates of a displaced element, you'll just get back the normal
2623
+ coordinates. As if there was no displacement. Displacing is just intended for
2624
+ quick animations!
2625
+
2626
+ === height() » a number ===
2627
+
2628
+ The vertical screen size of the element in pixels. In the case of images, this
2629
+ is not the full size of the image. This is the height of the element as it is
2630
+ shown right now.
2631
+
2632
+ If you have a 150x150 pixel image and you set the width to 50 pixels, this
2633
+ method will return 50.
2634
+
2635
+ Also see the [[Common.width]] method for an example and some other comments.
2636
+
2637
+ === hide() » self ===
2638
+
2639
+ Hides the element, so that it can't be seen. See also [[Common.show]] and
2640
+ [[Common.toggle]].
2641
+
2642
+ === left() » a number ===
2643
+
2644
+ Gets you the pixel position of the left edge of the element.
2645
+
2646
+ === move(left: a number, top: a number) » self ===
2647
+
2648
+ Moves the element to a specific pixel position within its slot. The element is
2649
+ still inside the slot. But it will no longer be stacked or flowed in with the
2650
+ other stuff in the slot. The element will float freely, now absolutely
2651
+ positioned instead.
2652
+
2653
+ {{{
2654
+ #!ruby
2655
+ Shoes.app do
2656
+ flow margin: 12 do
2657
+ # Set up three buttons
2658
+ button "One"
2659
+ @two = button "Two"
2660
+ button "Three"
2661
+
2662
+ # Bounce the second button
2663
+ animate do |i|
2664
+ @two.move(40, 40 + (Math.sin(i) * 6).to_i)
2665
+ end
2666
+ end
2667
+ end
2668
+ }}}
2669
+
2670
+ The second button is moved to a specific place, allowing the third button to
2671
+ slide over into its place. If you want to move an element without shifting
2672
+ other pieces, see the [[Common.displace]] method.
2673
+
2674
+ === parent() » a Shoes::Stack or Shoes::Flow ===
2675
+
2676
+ Gets the object for this element's container. Also see the slot's
2677
+ [[Traversing.contents]] to do the opposite: get a container's elements.
2678
+
2679
+ === remove() » self ===
2680
+
2681
+ Removes the element from its slot. (In other words: throws it in the garbage.)
2682
+ The element will no longer be displayed.
2683
+
2684
+ === show() » self ===
2685
+
2686
+ Reveals the element, if it is hidden. See also [[Common.hide]] and
2687
+ [[Common.toggle]].
2688
+
2689
+ === style() » styles ===
2690
+
2691
+ Gives you the full set of styles applied to this element, in the form of a
2692
+ Hash. While methods like `width` and `height` and `top` give you back specific
2693
+ pixel dimensions, using `style[:width]` or `style[:top]`, you can get the
2694
+ original setting (things like "100%" for width or "10px" for top.)
2695
+
2696
+ {{{
2697
+ #!ruby
2698
+ Shoes.app do
2699
+ # A button which take up the whole page
2700
+ @b = button "All of it", width: 1.0, height: 1.0
2701
+
2702
+ # When clicked, show the styles
2703
+ @b.click { alert(@b.style.inspect) }
2704
+ end
2705
+ }}}
2706
+
2707
+ === style(styles) » styles ===
2708
+
2709
+ Changes the style of an element. This could include the `:width` and `:height`
2710
+ of an element, the font `:size` of some text, the `:stroke` and `:fill` of a
2711
+ shape. Or any other number of style settings.
2712
+
2713
+ === toggle() » self ===
2714
+
2715
+ Hides an element if it is shown. Or shows the element, if it is hidden.
2716
+
2717
+ === top() » a number ===
2718
+
2719
+ Gets the pixel position of the top edge of the element.
2720
+
2721
+ === width() » a number ===
2722
+
2723
+ Gets the pixel width for the full size of the element. This method always
2724
+ returns an exact pixel size. In the case of images, this is not the full width
2725
+ of the image, just the size it is shown at. See the [[Common.height]] method
2726
+ for more.
2727
+
2728
+ Also, if you create an element with a width of 100% and that element is inside
2729
+ a stack which is 120 pixels wide, you'll get back `120`. However, if you call
2730
+ `style[:width]`, you'll get `"100%"`.
2731
+
2732
+ {{{
2733
+ #!ruby
2734
+ Shoes.app do
2735
+ stack width: 120 do
2736
+ @b = button "Click me", width: "100%" do
2737
+ alert "button.width = #{@b.width}\n" +
2738
+ "button.style[:width] = #{@b.style[:width]}"
2739
+ end
2740
+ end
2741
+ end
2742
+ }}}
2743
+
2744
+ In order to set the width, you'll have to go through the [[Common.style]]
2745
+ method again. So, to set the button to 150 pixels wide: `@b.style(width: 150)`.
2746
+
2747
+ To let Shoes pick the element's width, go with `@b.style(width: nil)` to
2748
+ empty out the setting.
2749
+
2750
+ == Background ==
2751
+
2752
+ A background is a color, a gradient or an image that is painted across an
2753
+ entire slot. Both backgrounds and borders are a type of Shoes::Pattern.
2754
+ !{margin_left: 100}man-ele-background.png!
2755
+
2756
+ Even though it's called a ''background'', you may still place this element in
2757
+ front of other elements. If a background comes after something else painted on
2758
+ the slot (like a `rect` or an `oval`,) the background will be painted over that
2759
+ element.
2760
+
2761
+ The simplest background is just a plain color background, created with the
2762
+ [[Element.background]] method, such as this black background:
2763
+
2764
+ {{{
2765
+ #!ruby
2766
+ Shoes.app do
2767
+ background black
2768
+ end
2769
+ }}}
2770
+
2771
+ A simple background like that paints the entire slot that contains it. (In
2772
+ this case, the whole window is painted black.)
2773
+
2774
+ You can use styles to cut down the size or move around the background to your liking.
2775
+
2776
+ To paint a black background across the top fifty pixels of the window:
2777
+
2778
+ {{{
2779
+ #!ruby
2780
+ Shoes.app do
2781
+ background black, height: 50
2782
+ end
2783
+ }}}
2784
+
2785
+ Or, to paint a fifty pixel column on the right-side of the window:
2786
+
2787
+ {{{
2788
+ #!ruby
2789
+ Shoes.app do
2790
+ background black, width: 50, right: 50
2791
+ end
2792
+ }}}
2793
+
2794
+ Since Backgrounds are normal elements as well, see also the start of the
2795
+ [[Elements]] section for all of its other methods.
2796
+
2797
+ === to_pattern() » a Shoes::Pattern ===
2798
+
2799
+ Yanks out the color, gradient or image used to paint this background and places
2800
+ it in a normal Shoes::Pattern object. You can then pass that object to other
2801
+ backgrounds and borders. Reuse it as you like.
2802
+
2803
+ == Border ==
2804
+
2805
+ A border is a color, gradient or image painted in a line around the edge of any
2806
+ slot. Like the Background element in the last section, a Border is a kind of
2807
+ Shoes::Pattern. !{margin_left: 100}man-ele-border.png!
2808
+
2809
+ The first, crucial thing to know about border is that all borders paint a line
2810
+ around the '''inside''' of a slot, not the outside. So, if you have a slot
2811
+ which is fifty pixels wide and you paint a five pixel border on it, that means
2812
+ there is a fourty pixel wide area inside the slot which is surrounded by the
2813
+ border.
2814
+
2815
+ This also means that if you paint a Border on top of a [[Background]], the
2816
+ edges of the background will be painted over by the border.
2817
+
2818
+ Here is just such a slot:
2819
+
2820
+ {{{
2821
+ #!ruby
2822
+ Shoes.app do
2823
+ stack width: 50 do
2824
+ border black, strokewidth: 5
2825
+ para "=^.^=", stroke: green
2826
+ end
2827
+ end
2828
+ }}}
2829
+
2830
+ If you want to paint a border around the outside of a slot, you'll need to wrap
2831
+ that slot in another slot. Then, place the border in the outside slot.
2832
+
2833
+ {{{
2834
+ #!ruby
2835
+ Shoes.app do
2836
+ stack width: 60 do
2837
+ border black, strokewidth: 5
2838
+ stack width: 50 do
2839
+ para "=^.^=", stroke: green
2840
+ end
2841
+ end
2842
+ end
2843
+ }}}
2844
+
2845
+ In HTML and many other languages, the border is painted on the outside of the
2846
+ box, thus increasing the overall width of the box. Shoes was designed with
2847
+ consistency in mind, so that if you say that a box is fifty pixels wide, it
2848
+ stays fifty pixels wide regardless of its borders or margins or anything else.
2849
+
2850
+ Please also check out the [[Elements]] section for other methods used on borders.
2851
+
2852
+ === to_pattern() » a Shoes::Pattern ===
2853
+
2854
+ Creates a basic pattern object based on the color, gradient or image used to
2855
+ paint this border. The pattern may then be re-used in new borders and
2856
+ backgrounds.
2857
+
2858
+ == Button ==
2859
+
2860
+ Buttons are, you know, push buttons. You click them and they do something.
2861
+ Buttons are known to say "OK" or "Are you sure?" And, then, if you're sure,
2862
+ you click the button. !{margin_left: 100}man-ele-button.png!
2863
+
2864
+ {{{
2865
+ #!ruby
2866
+ Shoes.app do
2867
+ button "OK!"
2868
+ button "Are you sure?"
2869
+ end
2870
+ }}}
2871
+
2872
+ The buttons in the example above don't do anything when you click them. In
2873
+ order to get them to work, you've got to hook up a block to each button.
2874
+
2875
+ {{{
2876
+ #!ruby
2877
+ Shoes.app do
2878
+ button "OK!" do
2879
+ append { para "Well okay then." }
2880
+ end
2881
+ button "Are you sure?" do
2882
+ append { para "Your confidence is inspiring." }
2883
+ end
2884
+ end
2885
+ }}}
2886
+
2887
+ So now we've got blocks for the buttons. Each block appends a new paragraph to
2888
+ the page. The more you click, the more paragraphs get added.
2889
+
2890
+ It doesn't go much deeper than that. A button is just a clickable phrase.
2891
+
2892
+ Just to be pedantic, though, here's another way to write that last example.
2893
+
2894
+ {{{
2895
+ #!ruby
2896
+ Shoes.app do
2897
+ @b1 = button "OK!"
2898
+ @b1.click { para "Well okay then." }
2899
+ @b2 = button "Are you sure?"
2900
+ @b2.click { para "Your confidence is inspiring." }
2901
+ end
2902
+ }}}
2903
+
2904
+ This looks dramatically different, but it does the same thing. The first
2905
+ difference: rather than attaching the block directly to the button, the block
2906
+ is attached later, through the `click` method.
2907
+
2908
+ The second change isn't related to buttons at all. The `append` block was
2909
+ dropped since Shoes allows you to add new elements directly to the slot. So we
2910
+ can just call `para` directly. (This isn't the case with the `prepend`,
2911
+ `before` or `after` methods.)
2912
+
2913
+ Beside the methods below, buttons also inherit all of the methods that are
2914
+ [[Common]].
2915
+
2916
+ === click() { |self| ... } » self ===
2917
+
2918
+ When a button is clicked, its `click` block is called. The block is handed
2919
+ `self`. Meaning: the button which was clicked.
2920
+
2921
+ === focus() » self ===
2922
+
2923
+ Moves focus to the button. The button will be highlighted and, if the user
2924
+ hits Enter, the button will be clicked.
2925
+
2926
+ == Check ==
2927
+
2928
+ Check boxes are clickable square boxes than can be either checked or unchecked.
2929
+ A single checkbox usually asks a "yes" or "no" question. Sets of checkboxes
2930
+ are also seen in to-do lists. !{margin_left: 100}man-ele-check.png!
2931
+
2932
+ Here's a sample checklist.
2933
+
2934
+ {{{
2935
+ #!ruby
2936
+ Shoes.app do
2937
+ stack do
2938
+ flow { check; para "Frances Johnson" }
2939
+ flow { check; para "Ignatius J. Reilly" }
2940
+ flow { check; para "Winston Niles Rumfoord" }
2941
+ end
2942
+ end
2943
+ }}}
2944
+
2945
+ You basically have two ways to use a check. You can attach a block to the
2946
+ check and it'll get called when the check gets clicked. And/or you can just
2947
+ use the `checked?` method to go back and see if a box has been checked or not.
2948
+
2949
+ Okay, let's add to the above example.
2950
+
2951
+ {{{
2952
+ #!ruby
2953
+ Shoes.app do
2954
+ @list = ['Frances Johnson', 'Ignatius J. Reilly',
2955
+ 'Winston Niles Rumfoord']
2956
+
2957
+ stack do
2958
+ @list.map! do |name|
2959
+ flow { @c = check; para name }
2960
+ [@c, name]
2961
+ end
2962
+
2963
+ button "What's been checked?" do
2964
+ selected = @list.map { |c, name| name if c.checked? }.compact
2965
+ alert("You selected: " + selected.join(', '))
2966
+ end
2967
+ end
2968
+ end
2969
+ }}}
2970
+
2971
+ So, when the button gets pressed, each of the checks gets asked for its status,
2972
+ using the `checked?` method.
2973
+
2974
+ Button methods are listed below, but also see the list of [[Common]] methods,
2975
+ which all elements respond to.
2976
+
2977
+ === checked?() » true or false ===
2978
+
2979
+ Returns whether the box is checked or not. So, `true` means "yes, the box is checked!"
2980
+
2981
+ === checked = true or false ===
2982
+
2983
+ Marks or unmarks the check box. Using `checked = false`, for instance,
2984
+ unchecks the box.
2985
+
2986
+ === click() { |self| ... } » self ===
2987
+
2988
+ When the check is clicked, its `click` block is called. The block is handed
2989
+ `self`, which is the check object which was clicked.
2990
+
2991
+ Clicks are sent for both checking and unchecking the box.
2992
+
2993
+ === focus() » self ===
2994
+
2995
+ Moves focus to the check. The check will be highlighted and, if the user hits
2996
+ Enter, the check will be toggled between its checked and unchecked states.
2997
+
2998
+ == EditBox ==
2999
+
3000
+ Edit boxes are wide, rectangular boxes for entering text. On the web, they
3001
+ call these textareas. These are multi-line edit boxes for entering longer
3002
+ descriptions. Essays, even! !{margin_left: 100}man-ele-editbox.png!
3003
+
3004
+ Without any other styling, edit boxes are sized 200 pixels by 108 pixels. You
3005
+ can also use `:width` and `:height` styles to set specific sizes.
3006
+
3007
+ {{{
3008
+ #!ruby
3009
+ Shoes.app do
3010
+ edit_box
3011
+ edit_box width: 100, height: 100
3012
+ end
3013
+ }}}
3014
+
3015
+ Other controls (like [[Button]] and [[Check]]) have only click events, but both
3016
+ [[EditLine]] and EditBox have a `change` event. The `change` block is called
3017
+ every time someone types into or deletes from the box.
3018
+
3019
+ {{{
3020
+ #!ruby
3021
+ Shoes.app do
3022
+ edit_box do |e|
3023
+ @counter.text = e.text.size
3024
+ end
3025
+ @counter = strong("0")
3026
+ para @counter, " characters"
3027
+ end
3028
+ }}}
3029
+
3030
+ Notice that the example also uses the [[EditBox.text]] method inside the block.
3031
+ That method gives you a string of all the characters typed into the box.
3032
+
3033
+ More edit box methods are listed below, but also see the list of [[Common]]
3034
+ methods, which all elements respond to.
3035
+
3036
+ === change() { |self| ... } » self ===
3037
+
3038
+ Each time a character is added to or removed from the edit box, its `change`
3039
+ block is called. The block is given `self`, which is the edit box object which
3040
+ has changed.
3041
+
3042
+ === focus() » self ===
3043
+
3044
+ Moves focus to the edit box. The edit box will be highlighted and the user will
3045
+ be able to type into the edit box.
3046
+
3047
+ === text() » self ===
3048
+
3049
+ Return a string of characters which have been typed into the box.
3050
+
3051
+ === text = a string ===
3052
+
3053
+ Fills the edit box with the characters of `a string`.
3054
+
3055
+ == EditLine ==
3056
+
3057
+ Edit lines are a slender, little box for entering text. While the EditBox is
3058
+ multi-line, an edit line is just one. Line, that is. Horizontal, in fact.
3059
+ !{margin_left: 100}man-ele-editline.png!
3060
+
3061
+ The unstyled edit line is 200 pixels wide and 28 pixels wide. Roughly. The
3062
+ height may vary on some platforms.
3063
+
3064
+ {{{
3065
+ #!ruby
3066
+ Shoes.app do
3067
+ stack do
3068
+ edit_line
3069
+ edit_line width: 400
3070
+ end
3071
+ end
3072
+ }}}
3073
+
3074
+ You can change the size by styling both the `:width` and the `:height`.
3075
+ However, you generally only want to style the `:width`, as the height will be
3076
+ sized to fit the font. (And, in current versions of Shoes, the font for edit
3077
+ lines and edit boxes cannot be altered anyway.)
3078
+
3079
+ If a block is given to an edit line, it receives `change` events. Check out the
3080
+ [[EditBox]] page for an example of using a change block. In fact, the edit box
3081
+ has all the same methods as an edit line. Also see the list of [[Common]]
3082
+ methods, which all elements respond to.
3083
+
3084
+ === change() { |self| ... } » self ===
3085
+
3086
+ Each time a character is added to or removed from the edit line, its `change`
3087
+ block is called. The block is given `self`, which is the edit line object which
3088
+ has changed.
3089
+
3090
+ === focus() » self ===
3091
+
3092
+ Moves focus to the edit line. The edit line will be highlighted and the user
3093
+ will be able to type into the edit line.
3094
+
3095
+ === text() » self ===
3096
+
3097
+ Return a string of characters which have been typed into the box.
3098
+
3099
+ === text = a string ===
3100
+
3101
+ Fills the edit line with the characters of `a string`.
3102
+
3103
+ == Image ==
3104
+
3105
+ An image is a picture in PNG, JPEG or GIF format. Shoes can resize images or
3106
+ flow them in with text. Images can be loaded from a file or directly off the
3107
+ web. !{margin_left: 100}man-ele-image.png!
3108
+
3109
+ To create an image, use the `image` method in a slot:
3110
+
3111
+ {{{
3112
+ #!ruby
3113
+ Shoes.app do
3114
+ para "Nice, nice, very nice. Busy, busy, busy."
3115
+ image "static/shoes-manual-apps.gif"
3116
+ end
3117
+ }}}
3118
+
3119
+ When you load any image into Shoes, it is cached in memory. This means that if
3120
+ you load up many image elements from the same file, it'll only really load the
3121
+ file once.
3122
+
3123
+ You can use web URLs directly as well.
3124
+
3125
+ {{{
3126
+ #!ruby
3127
+ Shoes.app do
3128
+ image "http://hacketyhack.heroku.com/images/logo.png"
3129
+ end
3130
+ }}}
3131
+
3132
+ When an image is loaded from the web, it's cached on the hard drive as well as
3133
+ in memory. This prevents a repeat download unless the image has changed. (In
3134
+ case you're wondering: Shoes keeps track of modification times and etags just
3135
+ like a browser would.)
3136
+
3137
+ Shoes also loads remote images in the background using system threads. So,
3138
+ using remote images will not block Ruby or any intense graphical displays you
3139
+ may have going on.
3140
+
3141
+ === full_height() » a number ===
3142
+
3143
+ The full pixel height of the image. Normally, you can just use the
3144
+ [[Common.height]] method to figure out how many pixels high the image is. But
3145
+ if you've resized the image or styled it to be larger or something, then
3146
+ `height` will return the scaled size.
3147
+
3148
+ The `full_height` method gives you the height of image (in pixels) as it was
3149
+ stored in the original file.
3150
+
3151
+ === full_width() » a number ===
3152
+
3153
+ The full pixel width of the image. See the [[Image.full_height]] method for an
3154
+ explanation of why you might use this method rather than [[Common.width]].
3155
+
3156
+ === path() » a string ===
3157
+
3158
+ The URL or file name of the image.
3159
+
3160
+ === path = a string ===
3161
+
3162
+ Swaps the image with a different one, loaded from a file or URL.
3163
+
3164
+ == ListBox ==
3165
+
3166
+ List boxes (also called "combo boxes" or "drop-down boxes" or "select boxes" in
3167
+ some places) are a list of options that drop down when you click on the box.
3168
+ !{margin_left: 100}man-ele-listbox.png!
3169
+
3170
+ A list box gets its options from an array. An array (a list) of strings,
3171
+ passed into the `:items` style.
3172
+
3173
+ {{{
3174
+ #!ruby
3175
+ Shoes.app do
3176
+ para "Choose a fruit:"
3177
+ list_box items: ["Grapes", "Pears", "Apricots"]
3178
+ end
3179
+ }}}
3180
+
3181
+ So, the basic size of a list box is about 200 pixels wide and 28 pixels high.
3182
+ You can adjust this length using the `:width` style.
3183
+
3184
+ {{{
3185
+ #!ruby
3186
+ Shoes.app do
3187
+ para "Choose a fruit:"
3188
+ list_box items: ["Grapes", "Pears", "Apricots"],
3189
+ width: 120, choose: "Apricots" do |list|
3190
+ @fruit.text = list.text
3191
+ end
3192
+
3193
+ @fruit = para "No fruit selected"
3194
+ end
3195
+ }}}
3196
+
3197
+ Next to the `:width` style, the example uses another useful option. The
3198
+ `:choose` option tells the list box which of the items should be highlighted
3199
+ from the beginning. (There's also a [[ListBox.choose]] method for highlighting
3200
+ an item after the box is created.)
3201
+
3202
+ List boxes also have a [[ListBox.change]] event. In the last example, we've got
3203
+ a block hooked up to the list box. Well, okay, see, that's a `change` block.
3204
+ The block is called each time someone changes the selected item.
3205
+
3206
+ Those are the basics. Might you also be persuaded to look at the [[Common]]
3207
+ methods page, a complete list of the methods that all elements have?
3208
+
3209
+ === change() { |self| ... } » self ===
3210
+
3211
+ Whenever someone highlights a new option in the list box (by clicking on an
3212
+ item, for instance,) its `change` block is called. The block is given `self`,
3213
+ which is the list box object which has changed.
3214
+
3215
+ === choose(item: a string) » self ===
3216
+
3217
+ Selects the option in the list box that matches the string given by `item`.
3218
+
3219
+ === focus() » self ===
3220
+
3221
+ Moves focus to the list box. The list box will be highlighted and, if the user
3222
+ hits the up and down arrow keys, other options in the list will be selected.
3223
+
3224
+ === items() » an array of strings ===
3225
+
3226
+ Returns the complete list of strings that the list box presently shows as its options.
3227
+
3228
+ === items = an array of strings ===
3229
+
3230
+ Replaces the list box's options with a new list of strings.
3231
+
3232
+ === text() » a string ===
3233
+
3234
+ A string containing whatever text is shown highlighted in the list box right
3235
+ now. If nothing is selected, `nil` will be the reply.
3236
+
3237
+ == Progress ==
3238
+
3239
+ Progress bars show you how far along you are in an activity. Usually, a
3240
+ progress bar represents a percentage (from 0% to 100%.) Shoes thinks of
3241
+ progress in terms of the decimal numbers 0.0 to 1.0. !{margin_left: 100}man-ele-progress.png!
3242
+
3243
+ A simple progress bar is 200 pixels wide, but you can use the `:width` style
3244
+ (as with all Shoes elements) to lengthen it.
3245
+
3246
+ {{{
3247
+ Shoes.app do
3248
+ stack margin: 0.1 do
3249
+ title "Progress example"
3250
+ @p = progress width: 1.0
3251
+
3252
+ animate do |i|
3253
+ @p.fraction = (i % 100) / 100.0
3254
+ end
3255
+ end
3256
+ end
3257
+ }}}
3258
+
3259
+ Take a look at the [[Common]] methods page for a list of methods found an all
3260
+ elements, including progress bars.
3261
+
3262
+ === fraction() » a decimal number ===
3263
+
3264
+ Returns a decimal number from 0.0 to 1.0, indicating how far along the progress bar is.
3265
+
3266
+ === fraction = a decimal number ===
3267
+
3268
+ Sets the progress to a decimal number between 0.0 and 1.0.
3269
+
3270
+ == Radio ==
3271
+
3272
+ Radio buttons are a group of clickable circles. Click a circle and it'll be
3273
+ marked. Only one radio button can be marked at a time. (This is similar to the
3274
+ ListBox, where only one option can be selected at a time.) !{margin_left: 100}man-ele-radio.png!
3275
+
3276
+ So, how do you decide when to use radio buttons and when to use list boxes?
3277
+ Well, list boxes only show one highlighted item unless you click on the box and
3278
+ the drop-down appears. But radio buttons are all shown, regardless of which is
3279
+ marked.
3280
+
3281
+ {{{
3282
+ #!ruby
3283
+ Shoes.app do
3284
+ para "Among these films, which do you prefer?\n"
3285
+ radio; para strong("The Taste of Tea"), " by Katsuhito Ishii\n"
3286
+ radio; para strong("Kin-Dza-Dza"), " by Georgi Danelia\n"
3287
+ radio; para strong("Children of Heaven"), " by Majid Majidi\n"
3288
+ end
3289
+ }}}
3290
+
3291
+ Only one of these three radios can be checked at a time, since they are grouped
3292
+ together in the same slot (along with a bunch of `para`.)
3293
+
3294
+ If we move them each into their own slot, the example breaks.
3295
+
3296
+ {{{
3297
+ #!ruby
3298
+ Shoes.app do
3299
+ stack do
3300
+ para "Among these films, which do you prefer?"
3301
+ flow { radio; para "The Taste of Tea by Katsuhito Ishii" }
3302
+ flow { radio; para "Kin-Dza-Dza by Georgi Danelia" }
3303
+ flow { radio; para "Children of Heaven by Majid Majidi" }
3304
+ end
3305
+ end
3306
+ }}}
3307
+
3308
+ This can be fixed, though. You can group together radios from different slots,
3309
+ you just have to give them all the same group name.
3310
+
3311
+ Here, let's group all these radios in the `:films` group.
3312
+
3313
+ {{{
3314
+ #!ruby
3315
+ Shoes.app do
3316
+ stack do
3317
+ para "Among these films, which do you prefer?"
3318
+ flow do
3319
+ radio :films
3320
+ para "The Taste of Tea by Katsuhito Ishii"
3321
+ end
3322
+ flow do
3323
+ radio :films
3324
+ para "Kin-Dza-Dza by Georgi Danelia"
3325
+ end
3326
+ flow do
3327
+ radio :films
3328
+ para "Children of Heaven by Majid Majidi"
3329
+ end
3330
+ end
3331
+ end
3332
+ }}}
3333
+
3334
+ For more methods beyond those listed below, also look into the [[Common]]
3335
+ methods page. Because you get those methods on every radio as well.
3336
+
3337
+ === checked?() » true or false ===
3338
+
3339
+ Returns whether the radio button is checked or not. So, `true` means "yes, it
3340
+ is checked!"
3341
+
3342
+ === checked = true or false ===
3343
+
3344
+ Marks or unmarks the radio button. Using `checked = false`, for instance,
3345
+ clears the radio.
3346
+
3347
+ === click() { |self| ... } » self ===
3348
+
3349
+ When the radio button is clicked, its `click` block is called. The block is
3350
+ handed `self`, which is an object representing the radio which was clicked.
3351
+
3352
+ Clicks are sent for both marking and unmarking the radio.
3353
+
3354
+ === focus() » self ===
3355
+
3356
+ Moves focus to the radio. The radio will be highlighted and, if the user hits
3357
+ Enter, the radio will be toggled between its marked and unmarked states.
3358
+
3359
+ == Shape ==
3360
+
3361
+ A shape is a path outline usually created by drawing methods like `oval` and
3362
+ `rect`. !{margin_left: 100}man-ele-shape.png!
3363
+
3364
+ See the [[Common]] methods page. Shapes respond to all of those methods.
3365
+
3366
+ == TextBlock ==
3367
+
3368
+ The TextBlock object represents a group of text organized as a single element.
3369
+ A paragraph containing bolded text, for example. A caption containing links and
3370
+ bolded text. (So, a `caption` is a TextBlock type. However, `link` and
3371
+ `strong` are TextClass types.) !{margin_left: 100}man-ele-textblock.png!
3372
+
3373
+ All of the various types of TextBlock are found on the [[Element Element
3374
+ Creation]] page.
3375
+
3376
+ * [[Element.banner]], a 48 pixel font.
3377
+ * [[Element.title]], a 34 pixel font.
3378
+ * [[Element.subtitle]], a 26 pixel font.
3379
+ * [[Element.tagline]], an 18 pixel font.
3380
+ * [[Element.caption]], a 14 pixel font.
3381
+ * [[Element.para]], a 12 pixel font.
3382
+ * [[Element.inscription]], a 10 pixel font.
3383
+
3384
+ === contents() » an array of elements ===
3385
+
3386
+ Lists all of the strings and styled text objects inside this block.
3387
+
3388
+ === replace(a string) ===
3389
+
3390
+ Replaces the text of the entire block with the characters of `a string`.
3391
+
3392
+ === text() » a string ===
3393
+
3394
+ Return a string of all of the characters in this text box. This will strip off
3395
+ any style or text classes and just return the actual characters, as if seen on
3396
+ the screen.
3397
+
3398
+ === text = a string ===
3399
+
3400
+ Replaces the text of the entire block with the characters of `a string`.
3401
+
3402
+ === to_s() » a string ===
3403
+
3404
+ An alias for [[TextBlock.text]]. Returns a flattened string of all of this
3405
+ TextBlock's contents.
3406
+
3407
+ == Timers ==
3408
+
3409
+ Shoes contains three timer classes: the Animation class, the Every class and
3410
+ the Timer class. Both Animations and Everies loop over and over after they
3411
+ start. Timers happen once. A one-shot timer.
3412
+
3413
+ Animations and Everies are basically the same thing. The difference is that
3414
+ Animations usually happen many, many times per second. And Everies happen only
3415
+ once every few seconds or rarely.
3416
+
3417
+ === start() » self ===
3418
+
3419
+ Both types of timers automatically start themselves, so there's no need to use
3420
+ this normally. But if you [[Timers.stop]] a timer and would like to start it up
3421
+ again, then by all means: use this!
3422
+
3423
+ === stop() » self ===
3424
+
3425
+ Pauses the animation or timer. In the case of a one-shot timer that's already
3426
+ happened, it's already stopped and this method will have no effect.
3427
+
3428
+ === toggle() » self ===
3429
+
3430
+ If the animation or timer is stopped, it is started. Otherwise, if it is
3431
+ already running, it is stopped.
3432
+
3433
+ == Video ==
3434
+
3435
+ Shoes supports embedding of QuickTime, Flash video (FLV), DivX, Xvid and
3436
+ various other popular video formats. This is all thanks to VideoLAN and ffmpeg,
3437
+ two sensational open source libraries. Use the `video` method on a slot to
3438
+ setup a Shoes::Video object. !{margin_left: 100}man-ele-video.png!
3439
+
3440
+ In addition to video formats, some audio formats are also supported, such as
3441
+ MP3, WAV and Ogg Vorbis.
3442
+
3443
+ Video support is optional in Shoes and some builds do not support video. For
3444
+ example, video support is unavailable for PowerPC. When you download Shoes, the
3445
+ build for your platform will be marked `novideo` in the filename if no video
3446
+ support is available.
3447
+
3448
+ === hide() » self ===
3449
+
3450
+ Hides the video. If already playing, the video will continue to play. This just
3451
+ turns off display of the video. One possible use of this method is to collapse
3452
+ the video area when it is playing an audio file, such as an MP3.
3453
+
3454
+ === length() » a number ===
3455
+
3456
+ The full length of the video in milliseconds. Returns nil if the video is not
3457
+ yet loaded.
3458
+
3459
+ === move(left, top) » self ===
3460
+
3461
+ Moves the video to specific coordinates, the (left, top) being the upper left
3462
+ hand corner of the video.
3463
+
3464
+ === pause() » self ===
3465
+
3466
+ Pauses the video, if it is playing.
3467
+
3468
+ === playing?() » true of false ===
3469
+
3470
+ Returns true if the video is currently playing. Or, false if the video is
3471
+ paused or stopped.
3472
+
3473
+ === play() » self ===
3474
+
3475
+ Starts playing the video, if it isn't already playing. If already playing, the
3476
+ video is restarted from the beginning.
3477
+
3478
+ === position() » a decimal ===
3479
+
3480
+ The position of the video as a decimanl number (a Float) between the beginning
3481
+ (0.0) and the end (1.0). For instance, a Float value of 0.5 indicates the
3482
+ halfway point of the video.
3483
+
3484
+ === position = a decimal ===
3485
+
3486
+ Sets the position of the video using a Float value. To move the video to its
3487
+ 25% position: `@video.position = 0.25`.
3488
+
3489
+ === remove() » self ===
3490
+
3491
+ Removes the video from its slot. This will stop the video as well.
3492
+
3493
+ === show() » self ===
3494
+
3495
+ Reveals the video, if it has been hidden by the `hide()` method.
3496
+
3497
+ === stop() » self ===
3498
+
3499
+ Stops the video, if it is playing.
3500
+
3501
+ === time() » a number ===
3502
+
3503
+ The time position of the video in milliseconds. So, if the video is 10 seconds
3504
+ into play, this method would return the number 10000.
3505
+
3506
+ === time = a number ===
3507
+
3508
+ Set the position of the video to a time in milliseconds.
3509
+
3510
+ === toggle() » self ===
3511
+
3512
+ Toggles the visibility of the video. If the video can be seen, then `hide` is
3513
+ called. Otherwise, `show` is called.
3514
+
3515
+ = AndSoForth =
3516
+
3517
+ A place for some other information.
3518
+
3519
+ == Sample Apps ==
3520
+
3521
+ Have fun!
3522
+
3523
+ {SAMPLES}
3524
+
3525
+ == FAQ ==
3526
+
3527
+ Hope this helps:
3528
+
3529
+ * You can join [[http://librelist.com/browser/shoes/ Shoes ML]] and feel free ask your questions.
3530
+ * [[http://github.com/shoes/shoes/ Official Current Source Code]] is on GitHub.
3531
+ * [[https://github.com/shoes/shoes/wiki Wiki]] for Shoes general info.