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:
app/
screens/
photos/
list_photos_screen.rb
show_photo_screen.rb
edit_photo_screen.rb
home_screen.rb
settings_screen.rb
models/
views/
app_delegate.rb
Loading your home screen:
# In /app/app_delegate.rb (note that AppDelegate extends ProMotion::AppDelegateParent)
class AppDelegate < ProMotion::AppDelegateParent
def on_load(app, options)
open_screen MyHomeScreen.new(nav_bar: true)
end
endCreating a basic screen:
class HomeScreen < ProMotion::Screen
title "Home"
def on_load
# Set up the elements in your view with add_element:
@label = add_element UILabel.alloc.initWithFrame(CGRectMake(5, 5, 20, 20)), {
text: "This is awesome!",
font: UIFont.systemFontOfSize(18)
}
end
def on_appear
# Refresh the data if you want
end
endCreating 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.
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.
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
endFor 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):
def on_opened
set_tab_bar_item title: "Tab Name Goes Here", icon: "tab_icon.png" # in resources folder
endAny view item (UIView, UIButton, 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.
@label = add_element UILabel.alloc.initWithFrame(CGRectMake(5, 5, 20, 20)), {
text: "This is awesome!",
font: UIFont.systemFontOfSize(18)
}Add a nav_bar button and a tab_bar icon:
set_nav_bar_right_button "Save", action: :save_something, type: UIBarButtonItemStyleDone
set_tab_bar_item title: "Contacts", system_icon: UITabBarSystemItemContactsOpen a new screen:
def settings_button_tapped
# ...with a class...
open_screen SettingsScreen
# ...or with an instance...
@settings_screen = SettingsScreen.new
open_screen @settings_screen
endOpen a new screen as a modal:
open_screen SettingsScreen, modal: trueYou can pass in arguments to other screens if they have accessors:
class HomeScreen < ProMotion::Screen
# ...
def settings_button_tapped
open_screen ProfileScreen.new(user: some_user)
end
end
class ProfileScreen < ProMotion::Screen
attr_accessor :user
def on_load
self.user # => some_user instance
end
endClose a screen (modal or in a nav controller), passing back arguments to the previous screen's "on_return" method:
class ItemScreen
# ...
def save_and_close
if @model.save
close_screen(model_saved: true)
end
end
end
class MainScreen < ProMotion::Screen
# ...
def on_return(args = {})
if args[:model_saved]
self.reload_something
end
end
endUse a custom view controller:
def on_load
set_view_controller MyCustomViewController
# Note: on_appear will not fire when using a custom
# view controller.
endThe helper add_element takes any view object and adds it to the current view. You can also use the helper ProMotion::ViewHelper.set_attributes(view, attributes) to do the same thing without adding it to the current view. Screens include this helper by default.
@element = add_element UIView.alloc.initWithFrame(CGRectMake(0, 0, 20, 20)), {
backgroundColor: UIColor.whiteColor
}
@element = set_attributes UIView.alloc.initWithFrame(CGRectMake(0, 0, 20, 20)), {
backgroundColor: UIColor.whiteColor
}You can create sectioned table screens easily. TableScreen, SectionedTableScreen, GroupedTableScreen. This is loosely based on motion-table (there are a few minor differences). We will eventually combine the two.
class SettingsScreen < ProMotion::GroupedTableScreen
title "Settings"
def on_load
add_right_nav_button(label: "Save", action: :save)
set_tab_bar_item(title: "Settings", icon: "settings.png")
end
# table_data is automatically called. Use this format in the return value.
# Grouped tables are the same as plain tables
def table_data
[{
title: "Your Account",
cells: [
{ title: "Edit Profile", action: :edit_profile, arguments: { id: 3 } },
{ title: "Log Out", action: :log_out },
{ title: "Notification Settings", action: :notification_settings }
]
}, {
title: "App Stuff",
cells: [
{ title: "About", action: :show_about },
{ title: "Feedback", action: :show_feedback }
]
}]
end
# This method allows you to create a "jumplist", the index on the right side of the table
def table_data_index
return ["A", "B", "C"]
end
# Your table cells, when tapped, will execute the corresponding actions and pass in arguments:
def edit_profile(arguments)
# ...
end
endYou can provide remotely downloaded images for cells by including the CocoaPod "SDWebImage" in your Rakefile and doing this:
cells: [
{
title: "Cell with image",
remoteImage: { url: "http://placekitten.com/200/300", placeholder: "some-local-image" }
}
](not comprehensive yet...working on this)
| Class or Module | Method | Description |
|---|---|---|
| Screen | is_modal? | Returns if the screen was opened in a modal window. |
| has_nav_bar? | Returns if the screen is contained in a navigation controller. | |
| set_tab_bar_item(args) |
Creates the tab that is shown in a tab bar item. Arguments: { icon: "imagename", systemIcon: UISystemIconContacts, title: "tabtitle" }
|
|
| on_appear |
Callback for when the screen appears. |
|
| will_appear |
Callback for before the screen appears. |
|
| will_disappear |
Callback for before the screen disappears. |
|
| will_rotate(orientation, duration) |
Callback for before the screen rotates. |
|
| on_opened **Deprecated** |
Callback when screen is opened via a tab bar. Please don't use this, as it will be removed in the future Use will_appear |
|
| set_nav_bar_left_button(title, args = {}) |
Set a left nav bar button. |
|
| set_nav_bar_right_button(title, args = {}) |
Set a right nav bar button.
|
|
| should_autorotate |
iOS 5 return true/false if screen should rotate |
|
| should_rotate(orientation) |
Return true/false for rotation to orientation. |
|
| supported_orientation?(orientation) |
Returns true/false if orientation is in NSBundle.mainBundle.infoDictionary["UISupportedInterfaceOrientations"]. Shouldn't need to override this. |
|
| supported_orientations |
Returns supported orientation mask |
|
| title |
Returns title of current screen. |
|
| title=(title) |
Sets title of current screen. |
|
|
ScreenElements Included in Screen by default |
add_element(view, attrs = {}) |
Adds the view to the screen after applying the attributes. |
| remove_element |
Removes the view from the superview and sets it to nil |
|
| bounds |
Accessor for self.view_controller.view.bounds |
|
| frame |
Accessor for self.view_controller.view.frame |
|
| view |
Accessor for self.view_controller.view |
|
|
SystemHelper Included in Screen by default |
ios_version |
Returns the iOS version that is running on the device |
| ios_version_greater?(version) |
Returns true if 'ios_version' is greater than the version passed in, false otherwise |
|
| ios_version_greater_eq?(version) |
Returns true if 'ios_version' is greater than or equal to the version passed in, false otherwise |
|
| ios_version_is?(version) |
Returns true if 'ios_version' is equal to the version passed in, false otherwise |
|
| ios_version_less?(version) |
Returns true if 'ios_version' is less than the version passed in, false otherwise |
|
| ios_version_less_eq?(version) |
Returns true if 'ios_version' is less than or equal to the version passed in, false otherwise |
|
| ScreenNavigation included in Screen |
app_delegate |
Returns the AppDelegate |
| close_screen(args = {}) |
Closes the current screen, passes args back to the previous screen's on_return method |
|
| fresh_start(screen) |
'restarts' app with the screen passed in |
|
| open_screen(screen, args = {}) |
Pushes the screen onto the navigation stack argument options :hide_tab_bar, :modal |
|
| open_tab(tab) |
Opens the tab where the "string" title is equal to the passed in tab |
|
| open_tab_bar(*screens) |
Open a UITabBarController with the specified screens as the root view controller of the current app |
I'm a big believer in MVC (I'm a Rails developer, too). I found that most of the time working in RubyMotion seems to happen in the ViewControllers and views are mainly custom elements. This pattern is probably best for navigation controller and tab bar based apps.
Feedback welcome via twitter @jamonholmgren or email jamon@clearsightstudio.com.
I'm really looking for feedback. Tweet me with your ideas or open a ticket (I don't mind!) and let's discuss.