forked from SketchUp/ruby-api-docs
-
Notifications
You must be signed in to change notification settings - Fork 0
/
file.LayOut.html
219 lines (163 loc) · 22.8 KB
/
file.LayOut.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
<!DOCTYPE html>
<html>
<head>
<meta charset="UTF-8">
<!-- VIEWPORT -->
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<!-- AUTHOR and GENERATOR -->
<meta name="author" content="SketchUp Extensibility Team">
<meta name="generator" content="YARD https://yardoc.org">
<!-- TITLE -->
<title>
File: LayOut Ruby API — SketchUp Ruby API Documentation
</title>
<!-- SHORTCUT ICON -->
<link rel="shortcut icon" type="image/vnd.microsoft.icon"
href="favicon.ico" />
<!-- GENERIC META PROPERTIES -->
<meta name="url" content="https://ruby.sketchup.com/file.LayOut.html" />
<meta name="image" content="https://ruby.sketchup.com/images/Ruby.svg" />
<meta name="title" content="File: LayOut Ruby API" />
<meta name="name" content="SketchUp Ruby API Documentation" />
<meta name="description" content="LayOut Ruby API" />
<!-- OPEN GRAPH META PROPERTIES -->
<meta property="og:site_name" content="SketchUp Ruby API Documentation" />
<meta property="og:type" content="website" />
<meta property="og:image" content="https://ruby.sketchup.com/images/Ruby.svg" />
<meta property="og:image:width" content="60" />
<meta property="og:image:height" content="60" />
<meta property="og:title" content="File: LayOut Ruby API" />
<meta property="og:url" content="https://ruby.sketchup.com/file.LayOut.html" />
<meta property="og:description" content="LayOut Ruby API" />
<!-- TWITTER CARD META PROPERTIES -->
<meta name="twitter:card" content="summary" />
<meta name="twitter:site" content="@sketchup" />
<meta name="twitter:title" content="File: LayOut Ruby API" />
<meta name="twitter:description" content="LayOut Ruby API" />
<meta name="twitter:image:src" content="https://ruby.sketchup.com/images/Ruby.svg?s=120" />
<meta name="twitter:url" content="https://ruby.sketchup.com/file.LayOut.html" />
<!-- STYLESHEETS -->
<link rel="stylesheet" type="text/css"
href="https://fonts.googleapis.com/css?family=Open+Sans:400,700,400italic" />
<link rel="stylesheet" href="css/style.css" type="text/css" charset="utf-8" />
<link rel="stylesheet" href="css/sketchup.css" type="text/css" charset="utf-8" />
<link rel="stylesheet" href="css/rubyapi.css" type="text/css" charset="utf-8" />
<link rel="stylesheet" href="css/rouge.css" type="text/css" charset="utf-8" />
<!-- SCRIPTS -->
<script type="text/javascript">
pathId = "LayOut";
relpath = '';
</script>
<script type="text/javascript" charset="utf-8" src="js/jquery.js"></script>
<script type="text/javascript" charset="utf-8" src="js/jquery-migrate.js"></script>
<script type="text/javascript" charset="utf-8" src="js/app.js"></script>
<script>
// Every time this page is loaded, it sends this action to SketchUp, telling
// SketchUp that a new page has loaded that has example snippets that should
// be replaced with code editors. Nothing happens if the page is loaded in a
// regular browser outside of the SketchUp client.
$( document ).ready(function() {
if (typeof sketchup == 'object') {
sketchup.page_loaded();
}
});
</script>
</head>
<body>
<!-- SU - start -->
<header id="navbar" role="banner" class="navbar navbar-fixed-top navbar-inverse">
<div id="api-documentation-header">
<div class="navbar-header">
<a class="logo navbar-btn pull-left" href="https://developer.sketchup.com" title="Home">
<img src="images/sketchup-logo.svg" alt="SketchUp">
</a>
<a class="name navbar-brand" href="/en" title="Home">SketchUp Developer Center</a>
<!-- .btn-navbar is used as the toggle for collapsed navbar content -->
<button type="button" class="navbar-toggle" data-toggle="collapse" data-target=".navbar-collapse">
<span class="sr-only">Toggle navigation</span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
</button>
</div>
<div class="navbar-collapse collapse">
<nav role="navigation">
<ul class="menu nav navbar-nav">
<li class="first leaf"><a href="https://forums.sketchup.com/c/developers">Community</a></li>
<li class="leaf"><a href="https://blog.sketchup.com/">SketchUp Blog</a></li>
<li class="leaf"><a href="https://www.sketchup.com/download" class="top-menu--download-button">Download</a></li>
<li class="last expanded dropdown">
<a href="https://www.trimble.com" class="trimble-top-menu-item dropdown-toggle" data-target="#" data-toggle="dropdown"><img src="images/trimble-logo-white.svg" alt="Trimble"><span class="caret"></span></a>
<ul class="dropdown-menu">
<li class="first leaf"><a href="https://connect.trimble.com/">Trimble Connect</a></li>
<li class="leaf"><a href="https://www.trimble.com/Corporate/About_Trimble.aspx">About Trimble</a></li>
<li class="last leaf"><a href="https://buildings.trimble.com/">Trimble Buildings</a></li>
</ul>
</li>
</ul>
</nav>
</div>
</div>
</header>
<!-- SU - end -->
<div id="su-content">
<div class="nav_wrap">
<iframe id="nav" src="file_list.html"></iframe>
<div id="resizer"></div>
</div>
<div id="main" tabindex="-1">
<div id="header">
<div id="menu">
<a href="_index.html">Index</a> »
<span class="title">File: LayOut Ruby API</span>
</div>
<div id="search">
<a class="full_list_link" id="class_list_link"
href="class_list.html">
<svg width="24" height="24">
<rect x="0" y="4" width="24" height="4" rx="1" ry="1"></rect>
<rect x="0" y="12" width="24" height="4" rx="1" ry="1"></rect>
<rect x="0" y="20" width="24" height="4" rx="1" ry="1"></rect>
</svg>
</a>
</div>
<div class="clear"></div>
</div>
<div id="content"><div id='filecontents'>
<h1 id="label-LayOut+Ruby+API">LayOut Ruby API</h1>
<p>The LayOut Ruby API provides an interface for reading and writing data to and from LayOut <span class='object_link'><a href="Layout/Document.html" title="Layout::Document (class)">Layout::Document</a></span>s (.layout files) via an intuitive and easy to learn programming language, Ruby. It can create new <span class='object_link'><a href="Layout/Document.html" title="Layout::Document (class)">Layout::Document</a></span>s as well as read or modify existing <span class='object_link'><a href="Layout/Document.html" title="Layout::Document (class)">Layout::Document</a></span>s.</p>
<h2 id="label-LayOut+Ruby+API+Documentation">LayOut Ruby API Documentation</h2>
<p>The documentation contains reference material for all functions, data structures, constants, and enumerations in the LayOut Ruby API.</p>
<p>The online Ruby API documentation can be found here: <a href="https://ruby.sketchup.com/file.LayOut.html">LayOut Ruby API Online Documentation</a></p>
<h2 id="label-Using+the+LayOut+Ruby+API+in+SketchUp">Using the LayOut Ruby API in SketchUp</h2>
<p>The LayOut Ruby API is included in the SketchUp application, meaning developers may utilize the LayOut Ruby API from within their SketchUp application via the console, or in their SketchUp Ruby extension without being required to include it. For an example of how to use the LayOut Ruby API from within a SketchUp extension, see the RubyExampleCreateLayOut sample.</p>
<h2 id="label-Things+To+Know+About+The+LayOut+Ruby+API">Things To Know About The LayOut Ruby API</h2>
<h3 id="label-LayOut-27s+Coordinate+System">LayOut's Coordinate System</h3>
<p>LayOut uses a 2D coordinate system for <span class='object_link'><a href="Layout/Entity.html" title="Layout::Entity (class)">Layout::Entity</a></span>s, whose origin is at the top-left corner of the page. The positive X axis extends to the right, and the positive Y axis extends downward. The units for all <span class='object_link'><a href="Geom/Point2d.html" title="Geom::Point2d (class)">Geom::Point2d</a></span> objects are inches. All 2D lengths and radii are also specified in inches, unless the function documentation specifies otherwise.</p>
<p><span class='object_link'><a href="Geom/Point3d.html" title="Geom::Point3d (class)">Geom::Point3d</a></span> objects are used for certain functions that interact with a <span class='object_link'><a href="Layout/SketchUpModel.html" title="Layout::SketchUpModel (class)">Layout::SketchUpModel</a></span>. <span class='object_link'><a href="Geom/Point3d.html" title="Geom::Point3d (class)">Geom::Point3d</a></span> objects specify model-space coordinates within a <span class='object_link'><a href="Layout/SketchUpModel.html" title="Layout::SketchUpModel (class)">Layout::SketchUpModel</a></span>.</p>
<h3 id="label-Shared+and+Non-Shared+Groups">Shared and Non-Shared Groups</h3>
<p>A <span class='object_link'><a href="Layout/Group.html" title="Layout::Group (class)">Layout::Group</a></span> may not contain a mix of <span class='object_link'><a href="Layout/Entity.html" title="Layout::Entity (class)">Layout::Entity</a></span>s on both shared and non-shared <span class='object_link'><a href="Layout/Layers.html" title="Layout::Layers (class)">Layout::Layers</a></span>. This is enforced when creating <span class='object_link'><a href="Layout/Group.html" title="Layout::Group (class)">Layout::Group</a></span>s (see <span class='object_link'><a href="Layout/Group.html#initialize-instance_method" title="Layout::Group#initialize (method)">Layout::Group#initialize</a></span>) as well as when moving <span class='object_link'><a href="Layout/Entity.html" title="Layout::Entity (class)">Layout::Entity</a></span>s into a <span class='object_link'><a href="Layout/Group.html" title="Layout::Group (class)">Layout::Group</a></span> (see <span class='object_link'><a href="Layout/Entity.html#move_to_group-instance_method" title="Layout::Entity#move_to_group (method)">Layout::Entity#move_to_group</a></span>). Also, functions that cause an <span class='object_link'><a href="Layout/Entity.html" title="Layout::Entity (class)">Layout::Entity</a></span>'s sharedness to change may have the side effect of splitting <span class='object_link'><a href="Layout/Group.html" title="Layout::Group (class)">Layout::Group</a></span>s (see <span class='object_link'><a href="Layout/Entity.html#move_to_layer-instance_method" title="Layout::Entity#move_to_layer (method)">Layout::Entity#move_to_layer</a></span>). In general, these operations follow the same behavior as the LayOut application itself.</p>
<p>To traverse the hierarchical <span class='object_link'><a href="Layout/Group.html" title="Layout::Group (class)">Layout::Group</a></span> structure of a <span class='object_link'><a href="Layout/Document.html" title="Layout::Document (class)">Layout::Document</a></span>, it is important to understand that due to the rule about shared and non-shared <span class='object_link'><a href="Layout/Group.html" title="Layout::Group (class)">Layout::Group</a></span>s, there are multiple <span class='object_link'><a href="Layout/Group.html" title="Layout::Group (class)">Layout::Group</a></span> structures in a <span class='object_link'><a href="Layout/Document.html" title="Layout::Document (class)">Layout::Document</a></span>. Each <span class='object_link'><a href="Layout/Page.html" title="Layout::Page (class)">Layout::Page</a></span> has its own <span class='object_link'><a href="Layout/Group.html" title="Layout::Group (class)">Layout::Group</a></span> structure that contains all of the <span class='object_link'><a href="Layout/Entity.html" title="Layout::Entity (class)">Layout::Entity</a></span>s on non-shared <span class='object_link'><a href="Layout/Layers.html" title="Layout::Layers (class)">Layout::Layers</a></span> for that <span class='object_link'><a href="Layout/Page.html" title="Layout::Page (class)">Layout::Page</a></span> (see <span class='object_link'><a href="Layout/Page.html#nonshared_entities-instance_method" title="Layout::Page#nonshared_entities (method)">Layout::Page#nonshared_entities</a></span>). Likewise, the <span class='object_link'><a href="Layout/Document.html" title="Layout::Document (class)">Layout::Document</a></span> has a <span class='object_link'><a href="Layout/Group.html" title="Layout::Group (class)">Layout::Group</a></span> structure that contains all of the <span class='object_link'><a href="Layout/Entity.html" title="Layout::Entity (class)">Layout::Entity</a></span>s on shared <span class='object_link'><a href="Layout/Layer.html" title="Layout::Layer (class)">Layout::Layer</a></span>s for the entire <span class='object_link'><a href="Layout/Document.html" title="Layout::Document (class)">Layout::Document</a></span> (see <span class='object_link'><a href="Layout/Document.html#shared_entities-instance_method" title="Layout::Document#shared_entities (method)">Layout::Document#shared_entities</a></span>). These functions provide access to an object, <span class='object_link'><a href="Layout/Entities.html" title="Layout::Entities (class)">Layout::Entities</a></span>, which is a list of <span class='object_link'><a href="Layout/Entity.html" title="Layout::Entity (class)">Layout::Entity</a></span> objects at the top of the hierarchy. Furthermore, the <span class='object_link'><a href="Layout/Group.html#entities-instance_method" title="Layout::Group#entities (method)">Layout::Group#entities</a></span> function provides an inlet to recursively traverse the <span class='object_link'><a href="Layout/Group.html" title="Layout::Group (class)">Layout::Group</a></span> structure.</p>
<h3 id="label-Iterating+Over+Entities+On+A+Page">Iterating Over Entities On A Page</h3>
<p>In cases where you need to iterate over all the <span class='object_link'><a href="Layout/Entity.html" title="Layout::Entity (class)">Layout::Entity</a></span>s that are visible on a <span class='object_link'><a href="Layout/Page.html" title="Layout::Page (class)">Layout::Page</a></span>, including the <span class='object_link'><a href="Layout/Entity.html" title="Layout::Entity (class)">Layout::Entity</a></span>s on both shared and non-shared layers, you can use the <span class='object_link'><a href="Layout/Page.html#entities-instance_method" title="Layout::Page#entities (method)">Layout::Page#entities</a></span> method. This method returns a list that, when iterated over, will visit <span class='object_link'><a href="Layout/Entity.html" title="Layout::Entity (class)">Layout::Entity</a></span>s in exactly the same order they are drawn by LayOut.</p>
<h3 id="label-Locked+Entities">Locked Entities</h3>
<p>Any <span class='object_link'><a href="Layout/Entity.html" title="Layout::Entity (class)">Layout::Entity</a></span> in LayOut can be individually locked or unlocked via the <span class='object_link'><a href="Layout/Entity.html#locked=-instance_method" title="Layout::Entity#locked= (method)">Layout::Entity#locked=</a></span> method. Locked <span class='object_link'><a href="Layout/Entity.html" title="Layout::Entity (class)">Layout::Entity</a></span>s cannot be moved, rotated, scaled, or modified in any way, besides being unlocked.</p>
<h3 id="label-Locked+and+Hidden+Layers">Locked and Hidden Layers</h3>
<p>In LayOut, the locked state of a <span class='object_link'><a href="Layout/Layer.html" title="Layout::Layer (class)">Layout::Layer</a></span> is a <span class='object_link'><a href="Layout/Document.html" title="Layout::Document (class)">Layout::Document</a></span>-wide setting, whereas the visible state of a <span class='object_link'><a href="Layout/Layer.html" title="Layout::Layer (class)">Layout::Layer</a></span> is a per-<span class='object_link'><a href="Layout/Page.html" title="Layout::Page (class)">Layout::Page</a></span> setting. LayOut has a rule that there must always be at least one unlocked, visible <span class='object_link'><a href="Layout/Layer.html" title="Layout::Layer (class)">Layout::Layer</a></span> on every <span class='object_link'><a href="Layout/Page.html" title="Layout::Page (class)">Layout::Page</a></span>. This rule is enforced by the LayOut Ruby API by methods such as <span class='object_link'><a href="Layout/Layer.html#locked=-instance_method" title="Layout::Layer#locked= (method)">Layout::Layer#locked=</a></span>, <span class='object_link'><a href="Layout/Page.html#set_layer_visibility-instance_method" title="Layout::Page#set_layer_visibility (method)">Layout::Page#set_layer_visibility</a></span>, and <span class='object_link'><a href="Layout/Layers.html#remove-instance_method" title="Layout::Layers#remove (method)">Layout::Layers#remove</a></span>.</p>
<h3 id="label-There+Must+Be+At+Least+One+Page+And+One+Layer+In+A+Document">There Must Be At Least One Page And One Layer In A Document</h3>
<p>There must be at least one <span class='object_link'><a href="Layout/Layer.html" title="Layout::Layer (class)">Layout::Layer</a></span> in a <span class='object_link'><a href="Layout/Document.html" title="Layout::Document (class)">Layout::Document</a></span>, and there must be at least one <span class='object_link'><a href="Layout/Page.html" title="Layout::Page (class)">Layout::Page</a></span>. <span class='object_link'><a href="Layout/Layers.html#remove-instance_method" title="Layout::Layers#remove (method)">Layout::Layers#remove</a></span> and <span class='object_link'><a href="Layout/Pages.html#remove-instance_method" title="Layout::Pages#remove (method)">Layout::Pages#remove</a></span> enforce this. Also, new <span class='object_link'><a href="Layout/Document.html" title="Layout::Document (class)">Layout::Document</a></span>s created by <span class='object_link'><a href="Layout/Document.html#initialize-instance_method" title="Layout::Document#initialize (method)">Layout::Document#initialize</a></span> will create a blank <span class='object_link'><a href="Layout/Document.html" title="Layout::Document (class)">Layout::Document</a></span> that starts out with one <span class='object_link'><a href="Layout/Layer.html" title="Layout::Layer (class)">Layout::Layer</a></span> and one <span class='object_link'><a href="Layout/Page.html" title="Layout::Page (class)">Layout::Page</a></span>.</p>
<h3 id="label-Explicit+Transforms+and+Untransformed+Bounds">Explicit Transforms and Untransformed Bounds</h3>
<p>Only some <span class='object_link'><a href="Layout/Entity.html" title="Layout::Entity (class)">Layout::Entity</a></span>s in LayOut have explicit <span class='object_link'><a href="Geom/Transformation2d.html" title="Geom::Transformation2d (class)">Geom::Transformation2d</a></span>: <span class='object_link'><a href="Layout/Ellipse.html" title="Layout::Ellipse (class)">Layout::Ellipse</a></span>, <span class='object_link'><a href="Layout/FormattedText.html" title="Layout::FormattedText (class)">Layout::FormattedText</a></span>, <span class='object_link'><a href="Layout/Image.html" title="Layout::Image (class)">Layout::Image</a></span>, <span class='object_link'><a href="Layout/Rectangle.html" title="Layout::Rectangle (class)">Layout::Rectangle</a></span> and <span class='object_link'><a href="Layout/SketchUpModel.html" title="Layout::SketchUpModel (class)">Layout::SketchUpModel</a></span> will always have an explicit <span class='object_link'><a href="Geom/Transformation2d.html" title="Geom::Transformation2d (class)">Geom::Transformation2d</a></span>. These are the only <span class='object_link'><a href="Layout/Entity.html" title="Layout::Entity (class)">Layout::Entity</a></span>s that will return a value for <span class='object_link'><a href="Layout/Entity.html#untransformed_bounds-instance_method" title="Layout::Entity#untransformed_bounds (method)">Layout::Entity#untransformed_bounds</a></span>. <span class='object_link'><a href="Layout/Entity.html#transform!-instance_method" title="Layout::Entity#transform! (method)">Layout::Entity#transform!</a></span> will work on any <span class='object_link'><a href="Layout/Entity.html" title="Layout::Entity (class)">Layout::Entity</a></span> type, regardless of whether the <span class='object_link'><a href="Layout/Entity.html" title="Layout::Entity (class)">Layout::Entity</a></span> has an explicit <span class='object_link'><a href="Geom/Transformation2d.html" title="Geom::Transformation2d (class)">Geom::Transformation2d</a></span> or not. It is important to note that LayOut will attempt to simplify the <span class='object_link'><a href="Geom/Transformation2d.html" title="Geom::Transformation2d (class)">Geom::Transformation2d</a></span>, which may affect both the untransformed bounds as well as the explicit <span class='object_link'><a href="Geom/Transformation2d.html" title="Geom::Transformation2d (class)">Geom::Transformation2d</a></span> of the <span class='object_link'><a href="Layout/Entity.html" title="Layout::Entity (class)">Layout::Entity</a></span>. Due to this, it is likely that the transform returned by <span class='object_link'><a href="Layout/Entity.html#transformation-instance_method" title="Layout::Entity#transformation (method)">Layout::Entity#transformation</a></span> will be different than the one that was applied. Also, the bounds returned by <span class='object_link'><a href="Layout/Entity.html#untransformed_bounds-instance_method" title="Layout::Entity#untransformed_bounds (method)">Layout::Entity#untransformed_bounds</a></span> will likely be different from the <span class='object_link'><a href="Layout/Entity.html" title="Layout::Entity (class)">Layout::Entity</a></span>'s initial untransformed bounds.</p>
<h3 id="label-Paths+Must+Have+At+Least+Two+Points">Paths Must Have At Least Two Points</h3>
<p><span class='object_link'><a href="Layout/Path.html#initialize-instance_method" title="Layout::Path#initialize (method)">Layout::Path#initialize</a></span> enforces the rule that every <span class='object_link'><a href="Layout/Path.html" title="Layout::Path (class)">Layout::Path</a></span> must contain at least two points. This is because a 0 or 1-point <span class='object_link'><a href="Layout/Path.html" title="Layout::Path (class)">Layout::Path</a></span> is not visible and cannot be selected (or deleted) in the LayOut application.</p>
<h3 id="label-Text+Cannot+Be+Empty">Text Cannot Be Empty</h3>
<p>The functions for <span class='object_link'><a href="Layout/FormattedText.html" title="Layout::FormattedText (class)">Layout::FormattedText</a></span> enforce the rule that the content of the text cannot be empty. This is because an empty text box is not visible and cannot be selected (or deleted) in the LayOut application.</p>
</div></div>
<div id="footer">
Generated by
<a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
</div>
</div>
</div>
</body>
</html>