Skip to content

theirishpenguin/qtonrails

Repository files navigation

qtonrails
=========

This is currently an work-in-progress attempt at building a simple framework that would let a developer comfortable with Rails generate a runnable Qt4 project. So far you can generate a simple CRUD Qt Application by installing the qtonrails plugin and using some generators.


installation
============

Easily installed as a Rails plugin:

./script/plugin install git://github.com/theirishpenguin/qtonrails.git


usage
=====
If you'd like a play then you can certainly run through the following steps to understand how qtonrails works. Here goes...

1. You are going to Qt-ify two of your existing Rails models. Ensure that you have at least one record in the database for each model

2. Ensure you are in the top level directory of your Rails project (ie. not in vendor/plugins/qtonrails)

3. If you're a *NIX user then you should be able to simply run ./script/generate qtify YourFirstModelName YourSecondModelName and straight to step 5

4. Run the following
./script/generate qform YourFirstModelName
./script/generate qpresenters
If it exists, delete the file vendor/plugins/qtonrails/config/routes.rb # TEMP WORKAROUND FOR AN ISSUE
./script/generate qcontroller YourFirstModelName
./script/generate qview YourFirstModelName
Then...
./script/generate qform YourSecondModelName
./script/generate qpresenters
Delete the file vendor/plugins/qtonrails/config/routes.rb # TEMP WORKAROUND FOR AN ISSUE
./script/generate qcontroller YourSecondModelName
./script/generate qview YourSecondModelName
Nearly there...
If it exists, delete the file vendor/plugins/qtonrails/app/qdesigns/qmainwindow.ui # TEMP WORKAROUND FOR AN ISSUE
./script/generate qmainwindow nav_items:YourFirstModelNamePluralized,YourSecondModelNamePluralized
./script/generate qmainwindow nav_items:YourFirstModelNamePluralized,YourSecondModelNamePluralized # NNB: Yes, you did have to do this last step twice!!! Dunno why

5. Require any gems your model layer needs to qtonrails/config/requires_list.rb

6. Change the DEFAULT_ROUTE in qtonrails/config/requires_list.rb if desired (for example, in this case you should probably change the controller part of the default route to be the controller for your first model, rather than the second one)

7. Finally, navigate to the vendor/plugins/qtonrails/ directory and execute the ./run command

What should happen?
===================
You should get to the list screen for your first chosen model, which also acts as a home page. You can do the usual CRUD stuff
- View the record
- Create a new record
- Edit the record data directly in the grid. Or else you can click the edit button, which will bring up your chosen record for editing.
- Delete a record
- Also you can click the navigation link for your second chosen model to get to the same functionality for that model

The idea of this initial release is to show the kind of workflow possible out of the box with qtonrails; and also to help make architectural decisions such as how will we do things like the routing and lots lots more. If you fancy hacking on this project then please fire ahead. I'd be delighted to hear from you if you're interested in this project.


generators
==========
Usage: ./script/generate qcontroller RailsModelName
Description:
    Adds an .rb file containing a QController definition for the RailsModel to the vendor/plugins/qtonrails/app/qcontrollers directory. QControllers are responsible for deciding what data is to be retrieved for the related QView.

Usage: ./script/generate qform RailsModelName
Description:
    Adds a .ui file containing a QForm definition for the RailsModel to the vendor/plugins/qtonrails/app/qdesigns directory. This .ui file can be opened in Qt designer.

Usage: ./script/generate qmainwindow [nav_items:NavItem1,NavItem2,...]
Description:
    Adds a .ui file containing a Qt::MainWindow definition to the vendor/plugins/qtonrails/app/qdesigns directory. This .ui file can be opened in Qt designer. Additionally it creates a ui_proxy (Ruby presentation of the .ui file) for the Qt::MainWindow along with a qpresenter file. NOTE: There is currently a bug that requires this generator to be run twice - it does not work correctly if only run once. An optional argument that can be passed is nav_items - which will build a navigation link for each NavItem specified. Typically, each NavItem is a Rails controller name. If multiple NavItems are specified then they must be separated by a comma and contain no spaces. Though Rails controller names are CapitalCased (eg. FruitOrders), the navigation link will appear in Title Case (eg. Fruit Orders) on the UI.

Usage: ./script/generate presenters
Description:
    Auto-generates presenter files for all qforms in vendor/plugins/qtonrails/app/qdesigns directory. The generated files live in the vendor/plugins/qtonrails/app/presenters directory. You can edit these files to change the presentation logic that controls the qform.

    For each qform, this step also auto-generates a .ui.rb file in the vendor/plugins/qtonrails/app/ui_proxies directory. These .ui.rb files are a Ruby code representation of the Qt Designer .ui files. You should never hand edit these files as they will be overwritten on calling this generator again. Instead change the presenter files.

Usage: ./script/generate qtify RailsModelName1 [RailsModelName2 RailsModelName3 ...]
Description:
    This is the qtonrails equivalent of ./script/generate scaffold Foo in the traditional Rails sense. It creates the full set of skeleton files under the vendor/plugins/qtonrails/app directory to run a Qt version of your Rails model. After generating, you can run your Qt application form the vendor/plugins/qtonrails directory using the ./run command. Additionally, you can find .ui files under the vendor/plugins/qtonrails/app/qdesigns directory that can be opened and edited in Qt Designer. Also there are editable files under the qcontrollers, qpresenters and qviews directories. The files in the ui_proxies directory are not intended to be edited. You can specify as many RailsModelName's as you like as arguments, each one will exist as a section in your application accessible from the navigation menu.

Usage: ./script/generate qview RailsModelName
Description:
    Adds a .rb file containing a QView definition for the RailsModel to the vendor/plugins/qtonrails/app/qviews directory. The qview decides what screen to display or how to refresh a screen that is already shown. As such it is probably more like a controller in the traditional Rails sense than a View.

KDE Support
-----------
There is very very early work started on generating a KDE app instead of a Qt app. There are 'kdeify' and 'kmainwindow' generators available which currently generates slightly different code from it's Qt cousin. Also use, ./run-kde instead of the ./run which is used to launch Qt applications.

Interesting titbits
-------------------
QtrTableModel: One core class is the QtrTableModel class which lives in the lib directory. The QtrTableModel wraps any RailsModel and provides us with a tablemodel (Qt::AbstractTableModel), which sits between a list of records of a Rails model (eg. a list of Product objects) and the widget that displays them in your application (eg. a Qt::TableView widget). A tablemodel is just data - it doesn't know that it's based on a Product model.

Recent changes
--------------
* Support for a basic menu to move between different areas of the application (eg. between controllers)
* Model validation errors displayed in when creating/editing a record via a form
* Added support for Date/Time/DateTime types (you can now in-situ edit them in grid or have appropirate widgets generated in forms)
* No longer display timestamps by default on grid
* Basic work started on allowing KDE apps to be generated, as opposed to just Qt apps


Known issues
------------
* Clicking View/Edit/Delete without selecting a row causes a crash
* Model validation errors not displayed in when editing a record via an in-situ grid
* Selecting a row actually selects a cell within the row - this may be undesirable
* No work done on handling booleans or checkbox widgets just yet
* Grids do not resize or autoexpand to fit entire screen
* Use the ./clean_app script to delete autogenerated files in the qtonrails/app directory if you want to rerun the qtify or kdeify generators from scratch for a second time
* Qt on Rails generates a QTimeEdit widget instead of a QDateTimeEdit widget for Time attributes of a model. This differs from the Rail's approach, which generates a Date and Time HTML select boxes when scaffolding a Time attribute. So, in Qt on Rails, if you want to represent a field with Date and Time information then use a DateTime attribute on a model and if you want to represent a Time only field (no date information) then use a Time attribute on the model.

whoami
======

My name is Declan McGrath. I'm a commercial Ruby developer and an Open Source enthusiast quitely watching the Irish FOSS scene burn brightly. You can follow me on Twitter at http://twitter.com/theirishpenguin and some people have even been known to get me at the email declan [AT] weuseopensource.com :-) For more information on the man behind the mouse you can check out https://wiki.ubuntu.com/declanmg


contribute
==========

Patches appreciated and you are cordially invited to get involved with the qtonrails project at any level. In particular, we are looking for people with some experience of Qt or KDE to help guide us on where to go with this plugin and also help development if desired. Get in contact using the details listed above.


Copyright (c) 2009-2010 [Declan McGrath], released under the MIT license

About

A Rails approach to building Qt4 and KDE applications

Resources

License

Stars

Watchers

Forks

Packages

No packages published