FAQ
- How do I create a simple application using UIC?
- How do I use Qt Designer?
- How do I use MainWindow as a basis for my application?
- How do I include icons on toolbars and menus?
- How do I set up an icon repository?
- How do I create a context (right click) menu?
- How do I create a splash screen?
- How do I set up translations?
- How do I set up translation from a single file
- What is an ActionFactory and how does it make my life easier?
- How do I work with the classes generated by compiling my interface design?
- What are slots?
- What is the "Settings" menu?
- How do I show or hide the "Settings" menu?
- What is the toolbar configuration menu?
- How do I show or hide the toolbar configuration menu?
- How do I specify an action target method which takes arguments?
- How do I make sure my UI actions happen on the event thread, and my non-UI actions do not?
How do I create a simple application using UIC?
- Use Qt Designer to define the look of your application. Compile
the .ui files with UIC. [more]
- Create a main class for your application which extends
MainWindow. [API]
- Write an XML file which defines the menus and toolbars used by
your application. [API1
API 2]
How do I use Qt Designer?
- Download this application.
- For you main window, base your design on QWidget. For dialogs,
base your design on QDialog. Ignore the other Q... things for now.
- Be sure to apply a layout to the entire, unselected, widget
when you are done. It doesn't matter whether it is horizontal,
vertical, or grid. Click somewhere on the form so NONE of the
individual controls is selected, and then pick a layout.
- Qt saves the design in an XML file with ".ui" suffix. Compile
these into java files with UIC. [more]
How do I use MainWindow as a basis for my application?
- Create a class which extends MainWindow. Include a "main"
method, which will start your application.
[API]
- In the "main" method, create your application and go through
the basic application lifecycle:
app = new MainApp();
app.splash();
app.init();
app.start();
splash displays the splash screen.
init does whatever preparation is needed - reading data, setting
up localization, initializing the ActionFactory, creating screen
widgets.
start puts the application on the screen.
How do I include icons on toolbars and menus?
- Tell the ActionFactory where your icon repository is.
- When you create an action, include a reference to its icon.
UICAction action = factory.addAction("file_exit", this, "exit",
translator.i18n("E&xit"),
"org.uic.exampleTwo.images.exitIcon",
"Alt-F4",
translator.i18n("Exit the application"),
translator.i18n("Close the application and exit"));
How do I set up an icon repository?
How do I create a context (right click) menu?
- Attach a ComponentMouseClickedAction to the component where you
want the context menu to appear.
ComponentMouseClickedAction mouseAction =
new ComponentMouseClickedAction(this, "mouseClickedSlot");
mouseAction.setDirect(true);
mouseAction.add(this);
- Write a method which retrieves the context menu and displays
it. This method must decide if the mouse click is requesting a
context menu.
public void mouseClickedSlot(int x, int y, int button){
if (button == ComponentMouseClickedAction.MOUSE_BUTTON3) {
ActionFactory actionFactory = MainApp.getActionFactory();
JPopupMenu popup = actionFactory.getPopupMenu("animalEditor_popup");
popup.show(this, x, y);
}
}
- The context menu must be displayed on the event thread. Since
it is in reponse to a UI event, if the target method runs on the
same thread as the firing event, it will be on the correct
thread. The method setDirect(true) takes care of this.
How do I create a splash screen?
Before you start your application, find and load your splash screen.
- Using the class loader, find the image for the splash
screen. The getResource call works equally well, whether the image
is in the file system or in a jar. Create your new splash screen
from this image.
- If you are displaying a progress bar, set the progess to zero.
- Use setPartnerComponent to tell the splash screen when to
close. It will disappear when the component is
displayed. Typically, you want this component to be the main
JFrame of your application. But it can be any component.
Here is a method which does these three things. It is a method on
the main class for the application, which can extend either JFrame
or MainWindow.
private void splash() {
ClassLoader loader = this.getClass().getClassLoader();
URL splashURL = loader.getResource("/images/AnimalSplash.png");
try {
mainSplash = new SplashScreen(splashURL,true);
mainSplash.setProgress(0);
mainSplash.setPartnerComponent(this.getFrame());
} catch (IOException e) {
// no splash found in classpath. Probaby forgot to add it to the jar.
e.printStackTrace();
}
}
How do I set up translations?
For each application context, create a translation property
file. See the API doc for Translate for a description of how to
create the required properties files and a discussion of
contexts. These files can be placed either with related code
files, or in a common location. [API]
In each context, construct a new Translate using the correct
property file. For the MainWindow, you need to create a Translate
to pass in to the createGui method. This might work like this:
Translate translator = new Translate("org.ui.exampleTwo.main", this);
For each generated class, override its translate method and create
the correct object.
public TranslationInterface translate() {
return ( new Translate("org/uic/exampleTwo/editingForm", this));
}
How do I set up translation from a single file?
Create one property with all the translations the application
needs. See the API doc for Translate for details. This file must
use the string "defaultTranslator" for its starting prefix (Files
are named <prefix>_<country code>.properties). This file must be
placed at the top level in the class path, since it will be
searched for without a package name. Any place in the code that a
Translate object is needed, create a default one: new
Translate()
. Do not override the translate method in the generated
ui classes.
[API]
What is an ActionFactory and how does it make my life easier?
The ActionFactory is a central location for your application to
manage Actions. It can also automatically create menus and
toolbars. See the API doc for details and examples.
[API
How do I work with the classes generated by compiling my interface design?
The generated class will contain stub methods which are called in
response to user interface events. You must extend the generated
class and override these methods to make your application respond
to these ui events. Also, different ui features (such as lists)
will be members of the class. You can access these members from
your extended class to provide custom processing (such as a
special action on gaining focus). [more]
What are slots?
Qt Designer calls actions that the user interface can fire
"slots". When UIC creates Java classes from your design, methods
which respond to a ui event will have "slot" in their name. You
will override these methods to make your application respond to
these ui events.
What is the "Settings" menu?
The "Settings" menu is a feature of the MainWindow class. It
contains two entries, "Configure" and "Toolbars". "Configure"
shows a theme-configuration dialog, which allows the user to set
fonts, colors, etc. This entry requires you to have the
uic-optional.jar is in the classpath, and will only after you call
MainWindow.setAllowConfigurationDialog(true)
. "Toolbars" allows the user
to show or hide toolbars.
[API]
How do I show or hide the "Settings" menu?
By default, the menu will appear if you have at least one toolbar.
To get rid of it, you must get rid of the menu entry to configure them.
To do this, on your instance of
MainWindow, call setAllowToolBarHiding(false)
. This method must be
called before the call to createGui.
What is the toolbar configuration menu?
This menu presents the user with configuration options (position,
icons, text, etc) for a toolbar. If you right click on any
toolbar, the menu will appear.
How do I show or hide the toolbar configuration menu?
By default, the menu will appear. To get rid of it, on your
instance of MainWindow, call setAllowToolBarConfiguration(false)
,
before the call to createGui.
How do I specify an action target method which takes arguments?
Many arguments are already supplied in the action and creating the action
will cause it to look for the first match. An action for a checkbox will
look for a method with and also for a method without an argument boolean
.
If what you want is not present; do the following:
First, create an Arguments object. Then use addArgument to add the
desired arguments. The allowed set of arguments are specified in
the api doc for a given action. Finally, pass the Arguments object
to the action constructor.
Arguments args = UICSimpleAction.createArguments();
args.addArgument(ComponentMouseClickedAction.ARGUMENT_POINT);
args.addArgument(ComponentMouseClickedAction.ARGUMENT_BUTTON);
ComponentMouseClickedAction mouseAction =
new ComponentMouseClickedAction(this, "mouseClicked", args);
[more,
API]
How do I make sure my UI actions happen on the event thread, and my non-UI
actions do not?
Actions can be fired on either the event thread or a regular
thread. By default, the action's target method will be called on a
regular thread. There are two ways to get a method called on the
event thread:
- Most actions you use are derived from SwingAction or UICAction, then you can just call
setUIUpdateCommand. The method passed in will be called on the
event thread after the action's target method completes.
[API]
- If you know the action will be fired on the event thread, call
setDirect(true) on the action. This causes the target method to be
called directly from where the action is fired, and not in the actions worker
thread. All of the actions which derive from SwingAction are fired
by UI activity, so they will be fired on the event thread.