README.md in ProMotion-0.3.0 vs README.md in ProMotion-0.4.0
- old
+ new
@@ -1,10 +1,12 @@
# ProMotion - A new way to easily build RubyMotion apps.
ProMotion introduces a new object called "Screens". Screens have a one-to-one relationship
with your app's designed screens.
+NEW video tutorial! Go watch it here: http://www.clearsightstudio.com/insights/tutorial-make-youtube-video-app-rubymotion-promotion/
+
Check out the tutorial here: http://www.clearsightstudio.com/insights/ruby-motion-promotion-tutorial
Sample app here: https://github.com/jamonholmgren/promotion-tutorial
Typical app file structure:
@@ -24,14 +26,14 @@
## Usage
Loading your home screen:
```ruby
-# In /app/app_delegate.rb (note that AppDelegate extends ProMotion::AppDelegateParent)
-class AppDelegate < ProMotion::AppDelegateParent
+# In /app/app_delegate.rb
+class AppDelegate < ProMotion::AppDelegate
def on_load(app, options)
- open_screen MyHomeScreen.new(nav_bar: true)
+ open MyHomeScreen.new(nav_bar: true)
end
end
```
Creating a basic screen:
@@ -52,80 +54,83 @@
# Refresh the data if you want
end
end
```
-Creating a tabbed bar from a screen (this has to be done inside a screen -- it won't work
-in your app_delegate.rb). This will set the tab bar as the root view controller for your app,
-so keep that in mind.
+Creating a tabbed bar with multiple screens. This will set the tab bar as the root view controller for your app,
+so keep that in mind. It can be done from the AppDelegate#on_load or from a screen.
-NOTE: It needs to be done in the on_appear or afterward, not the `on_load` or
-`will_appear`. We will likely fix this in the future, but for now that's a restriction.
+### Creating a tab bar with several screens
```ruby
-def on_appear
- @home ||= MyHomeScreen.new(nav_bar: true)
- @settings ||= SettingsScreen.new
- @contact ||= ContactScreen.new(nav_bar: true)
- @tab_bar ||= open_tab_bar @home, @settings, @contact
+def on_load(app, options)
+ @home = MyHomeScreen.new(nav_bar: true)
+ @settings = SettingsScreen.new
+ @contact = ContactScreen.new(nav_bar: true)
+ @tab_bar = open_tab_bar @home, @settings, @contact
end
```
For each screen that belongs to the tab bar, you need to set the tab name and icon in the files.
In this example, we would need add the following to the three files (my_home_screen.rb, settings_screen.rb, contact_screen.rb):
```ruby
-def on_opened
- set_tab_bar_item title: "Tab Name Goes Here", icon: "tab_icon.png" # in resources folder
+def on_load
+ set_tab_bar_item title: "Tab Name Goes Here", icon: "icons/tab_icon.png" # in resources/icons folder
+
+ # or...
+ set_tab_bar_item title: "Contacts", system_icon: UITabBarSystemItemContacts
end
```
-Any view item (UIView, UIButton, etc) can be used with add_element.
+### Adding view elements
+
+Any view item (UIView, UIButton, custom UIView subclasses, etc) can be used with add_element.
The second argument is a hash of settings that get applied to the
element before it is dropped into the view.
```ruby
@label = add_element UILabel.alloc.initWithFrame(CGRectMake(5, 5, 20, 20)), {
text: "This is awesome!",
- font: UIFont.UIFont.systemFontOfSize(18)
+ font: UIFont.systemFontOfSize(18)
}
```
-Add a nav_bar button and a tab_bar icon:
+Add nav_bar buttons:
```ruby
set_nav_bar_right_button "Save", action: :save_something, type: UIBarButtonItemStyleDone
-set_tab_bar_item title: "Contacts", system_icon: UITabBarSystemItemContacts
+set_nav_bar_left_button "Cancel", action: :return_to_some_other_screen, type: UIBarButtonItemStylePlain
```
Open a new screen:
```ruby
def settings_button_tapped
# ...with a class...
- open_screen SettingsScreen
+ open SettingsScreen
# ...or with an instance...
@settings_screen = SettingsScreen.new
- open_screen @settings_screen
+ open @settings_screen
end
```
Open a new screen as a modal:
```ruby
-open_screen SettingsScreen, modal: true
+open SettingsScreen, modal: true
```
You can pass in arguments to other screens if they have accessors:
```ruby
class HomeScreen < ProMotion::Screen
# ...
def settings_button_tapped
- open_screen ProfileScreen.new(user: some_user)
+ open ProfileScreen.new(user: some_user)
end
end
class ProfileScreen < ProMotion::Screen
attr_accessor :user
@@ -138,15 +143,15 @@
```
Close a screen (modal or in a nav controller), passing back arguments to the previous screen's "on_return" method:
```ruby
-class ItemScreen
+class ItemScreen < ProMotion::Screen
# ...
def save_and_close
if @model.save
- close_screen(model_saved: true)
+ close(model_saved: true)
end
end
end
class MainScreen < ProMotion::Screen
@@ -263,9 +268,231 @@
<td> </td>
<td>set_tab_bar_item(args)</td>
<td>
Creates the tab that is shown in a tab bar item.<br />
Arguments: <code>{ icon: "imagename", systemIcon: UISystemIconContacts, title: "tabtitle" }</code>
+ </td>
+ </tr>
+ <tr>
+ <td> </td>
+ <td>on_appear</td>
+ <td>
+ Callback for when the screen appears.<br />
+ </td>
+ </tr>
+ <tr>
+ <td> </td>
+ <td>will_appear</td>
+ <td>
+ Callback for before the screen appears.<br />
+ </td>
+ </tr>
+ <tr>
+ <td> </td>
+ <td>will_disappear</td>
+ <td>
+ Callback for before the screen disappears.<br />
+ </td>
+ </tr>
+ <tr>
+ <td> </td>
+ <td>will_rotate(orientation, duration)</td>
+ <td>
+ Callback for before the screen rotates.<br />
+ </td>
+ </tr>
+ <tr>
+ <td> </td>
+ <td>on_opened **Deprecated**</td>
+ <td>
+ Callback when screen is opened via a tab bar. Please don't use this, as it will be removed in the future<br />
+ Use will_appear
+ </td>
+ </tr>
+ <tr>
+ <td> </td>
+ <td>set_nav_bar_left_button(title, args = {})</td>
+ <td>
+ Set a left nav bar button.<br />
+ </td>
+ </tr>
+ <tr>
+ <td> </td>
+ <td>set_nav_bar_right_button(title, args = {})</td>
+ <td>
+ Set a right nav bar button.<br />
+ <img src="http://i.imgur.com/whbkc.png" />
+ </td>
+ </tr>
+ <tr>
+ <td> </td>
+ <td>should_autorotate</td>
+ <td>
+ iOS 5 return true/false if screen should rotate<br />
+ </td>
+ </tr>
+ <tr>
+ <td> </td>
+ <td>should_rotate(orientation)</td>
+ <td>
+ Return true/false for rotation to orientation.<br />
+ </td>
+ </tr>
+ <tr>
+ <td> </td>
+ <td>supported_orientation?(orientation)</td>
+ <td>
+ Returns true/false if orientation is in NSBundle.mainBundle.infoDictionary["UISupportedInterfaceOrientations"].<br />
+ Shouldn't need to override this.
+ </td>
+ </tr>
+ <tr>
+ <td> </td>
+ <td>supported_orientations</td>
+ <td>
+ Returns supported orientation mask<br />
+ </td>
+ </tr>
+ <tr>
+ <td> </td>
+ <td>title</td>
+ <td>
+ Returns title of current screen.<br />
+ </td>
+ </tr>
+ <tr>
+ <td> </td>
+ <td>title=(title)</td>
+ <td>
+ Sets title of current screen.<br />
+ </td>
+ </tr>
+ <tr>
+ <td>
+ ScreenElements<br />
+ Included in Screen by default
+ </td>
+ <td>add_element(view, attrs = {})</td>
+ <td>
+ Adds the view to the screen after applying the attributes.<br />
+ </td>
+ </tr>
+ <tr>
+ <td> </td>
+ <td>remove_element</td>
+ <td>
+ Removes the view from the superview and sets it to nil<br />
+ </td>
+ </tr>
+ <tr>
+ <td> </td>
+ <td>bounds</td>
+ <td>
+ Accessor for self.view.bounds<br />
+ </td>
+ </tr>
+ <tr>
+ <td> </td>
+ <td>frame</td>
+ <td>
+ Accessor for self.view.frame<br />
+ </td>
+ </tr>
+ <tr>
+ <td> </td>
+ <td>view</td>
+ <td>
+ Accessor for self.view<br />
+ </td>
+ </tr>
+ <tr>
+ <td>
+ SystemHelper<br />
+ Included in Screen by default
+ </td>
+ <td>ios_version</td>
+ <td>
+ Returns the iOS version that is running on the device<br />
+ </td>
+ </tr>
+ <tr>
+ <td> </td>
+ <td>ios_version_greater?(version)</td>
+ <td>
+ Returns true if 'ios_version' is greater than the version passed in, false otherwise<br />
+ </td>
+ </tr>
+ <tr>
+ <td> </td>
+ <td>ios_version_greater_eq?(version)</td>
+ <td>
+ Returns true if 'ios_version' is greater than or equal to the version passed in, false otherwise<br />
+ </td>
+ </tr>
+ <tr>
+ <td> </td>
+ <td>ios_version_is?(version)</td>
+ <td>
+ Returns true if 'ios_version' is equal to the version passed in, false otherwise<br />
+ </td>
+ </tr>
+ <tr>
+ <td> </td>
+ <td>ios_version_less?(version)</td>
+ <td>
+ Returns true if 'ios_version' is less than the version passed in, false otherwise<br />
+ </td>
+ </tr>
+ <tr>
+ <td> </td>
+ <td>ios_version_less_eq?(version)</td>
+ <td>
+ Returns true if 'ios_version' is less than or equal to the version passed in, false otherwise<br />
+ </td>
+ </tr>
+ <tr>
+ <td>ScreenNavigation<br />
+ included in Screen
+ </td>
+ <td>app_delegate</td>
+ <td>
+ Returns the AppDelegate<br />
+ </td>
+ </tr>
+ <tr>
+ <td> </td>
+ <td>close(args = {})</td>
+ <td>
+ Closes the current screen, passes args back to the previous screen's on_return method<br />
+ </td>
+ </tr>
+ <tr>
+ <td> </td>
+ <td>open_root_screen(screen)</td>
+ <td>
+ Closes all other open screens and opens `screen` at the root.<br />
+ </td>
+ </tr>
+ <tr>
+ <td> </td>
+ <td>open(screen, args = {})</td>
+ <td>
+ Pushes the screen onto the navigation stack or opens in a modal<br />
+ argument options :hide_tab_bar, :modal, any accessors in `screen`
+ </td>
+ </tr>
+ <tr>
+ <td> </td>
+ <td>open_tab(tab)</td>
+ <td>
+ Opens the tab where the "string" title is equal to the passed in tab<br />
+ </td>
+ </tr>
+ <tr>
+ <td> </td>
+ <td>open_tab_bar(*screens)</td>
+ <td>
+ Open a UITabBarController with the specified screens as the root view controller of the current app<br />
</td>
</tr>
</table>
### What about MVC?