In this section we go beyond listing widgets to actually using Kommander. If you want to have a good experience you will find this section very helpful.
At first glance the editor looks pretty obvious, and in many ways it is. Click on the icon to create a new form, then click a widget and click or click and drag on the form. There are the widget handles that will be familiar to anyone who ever put a picture in a word processing document. What is less obvious are the little things. One thing to mention up front is widget naming. Names must be unique and Kommander employs a naming scheme of the formal widget name and a number unique to that widget type. You can rename a widget and Kommander will not allow a duplicate name. However if you build a complex dialog and decide to start renaming you're going to have problems. Signals and slots will manage naming for you and any widget you change will be reflected in the signals and slots connections. Unfortunately we never got this feature in the widget functions. So ever call to that widget will be wrong. You could close the dialog and open it in a text editor like KWrite and do find and replace. A better solution is to start out with some idea what kind of descriptive names you want to give to key widgets. It may be a waste of time naming Labels, but scripts and container widgets for data quickly prove a real mistake not to name. You can also set icons for scripts making them even quicker to visually identify.
The first thing you will notice is a properties window, generally docked on the left. Explore this! Here you will find many useful settings for forms and widgets. Some of them would be layout settings, icons, if something is active, text and more. For instance if you put a TreeWidget in a form you can change the default path separator, which is useful if you have data in there. It's easy for a slash to create a sub-item accidentally. Here you will also find selection modes, whether to highlight the whole row in multi column widgets and more. Before you assune something is just how Kommander is check this.
If you play with layouts and lose a widget behind another or off the form the object explorer will come in handy. It's also nice for seeing structure. The next very useful view is the log view which shows stdout and stderr. The error view is indispensable. This is where your debug() commands prints and where you get detailed information. For instance when using the database plugin this gives you additional information with data errors. It also shows you all shell calls and more. The Stdout view lets you see what would go to the shell or an application using this like Quanta. The dialog view is of little use unless you have a lot of dialogs open. The Action view is only active with MainWindow use and in that case it is the only way to add Actions, menu and toolbar items.
Kommander makes it easy to add custom tools, which you can develop in Kommander, to the editor. We will be shipping some with Kommander as well as making some available for download. You can add your own easily. First have a look and see where they are. If they are installed they are on the tools menu below the splitter. The Kommander menu offers access to widgets. The Custom menu offers access to installed plugins. The Editor menu is where your custom tools go. To manually add a tool first decide if you are going to make it available system wide or just to your desktop. System wide start from the directory KDE is installed in. For your desktop user start in the hidden KDE directory in your home directory, usually ~/kde. From either the path is/share/apps/kmdr-editor/editor/ If the dialog you add needs access to tools or files you can put them in a subdirectory. Whatever Kommander dialogs you put there will be recognized and added to your menu on startup. Clicking the menu will load the dialog. You will note there is a templates directory there too and you can add templates for new dialogs.
Several tools are included with this release, already installed on the tools meu under editor. More tools are under development for project management, database front end development, code snippets and more. The most imporant and useful tool to look for is the examples dialog. As the editor is no longer under development for KDE3 it cannot insert a dialog in the current editor, but it will open any selected dialog in a new instance of the editor. There are old dialogs from the early days of Kommander, tutorials from more recent development and the current section showing new features of this release. Looking at these should help. Keep an eye on our web site for more.
People love to share Kommander dialogs. Almost without fail they don't know about laying them out. Make a dialog and then try resizing it and see what happens. Wouldn't it be nice if it behaved like it should instead of leaving your widgets the same? It gets worse when you share it and differences in fonts, monitor size and X pixel resolution conspire to make your masterpiece look like it was put together by a three year old using bubblegum and thumbtacks. Always, always always... Lay out your dialogs!
Okay, you're sold you don't want a frustrated email from me asking you to please layout your dialog. How do you do it. There are layout buttons on the toolbar and the context menu. Since Kommander is based on an older version of Qt Designer you can look at Qt Designer docs and tutorials here. I'm just going to mention a few basics and a few tips.
Use the Grid. This will place everything in a “best guess” location
Remember containers are separate. A TabWidget, GroupBox or layout group has it's own layout. So don't forget the window.
Widgets that are not visible during execution can make layout seem more challenging. What to do with them? I recommend grouping them in their own layour next to or below your main layout. Your visible widgets will simply push these aside and give you a predictable result.
Look at your properties were you can set a widget to expand or do other things as well as minimum and maximum size. A little experimentation will teach you a lot. You can also set a tighter spacing here,
And now for a few tricks and tips.
Along with basic layout you can use splitters. When your dialog is running you can drag the splitter up and down or right and left to get a better look at things. It may look like there is a limitation here or it doesn't work. It works and has no limitations. Just make sure to put multiple widgets into two layouts and make sure when you click or right click to get the layout and not just a child widget. You are free to create a maze of splitters as long as you adhere to the rules.
Fake docs are possible! Create a GroupBox and drop widgets on it. Position it in your layout so that when it's invisible other widgets/layouts will expand to take it's place. Now toggle it's visibility with a button or menu.
ToolBox tricks - The Toolbox has an editor bug where you can't add widget panels in the editor without it going nuts. As a result you need to add them at run time. However it looks for one widget and if you want something complex you should use a groupbox and lay it out. then layout your dialog with the groupbox at the outside, even if it goes off the edge of the window. Now load it on initialization into the ToolBox. Your window layout will snap into place.
Layout glitches can occur where widgets set to something like Minimum/Expanding can end up obscured before you complete layout on the window. The layout system will honor your oddness and can be shrunk to obscure scrollbars and more. Make sure all is visible before finishing layout and consider not using minimum in that case.
For more on this look up the Qt Designer docs for Qt 3.x.
One of the very useful features inherited from Qt Designer was signals and slots. Of course the interface has been redesigned in an attempt to make it friendly to Kommander. Signals and slots are internal event control for TQt/TDE applications. We try to make it so you don't have to know the difference between C++ data types, but if you use the new function to create connections on the fly it is handy to be able to copy that information from the connection tool. Let's look at what all this means. Something happens in one of you widgets. It could be click on, double clicked, have it's value changed, something selected or a menu could be requested. That is just some of the possible events that would enable a signal to be sent. You may want to change the list in a ListBox if a new selection is made in a ComboBox. That's a useful feature in a sophisticated application and the only way to do it without having to press a button next is to have a signal connected to a slot. That slot could be in a script or button. When the slot receives the signal it goes about doing what it was told. There is a tool to edit these connections. Pay attention when do this as there are a good number of inherited signals and slots. Telling a script which is invisible when the dialog is run to adjust it's size by accident when you meant to execute will have you wondering what happened.
To access the connection tool you can open it by right clicking anywhere on the dialog and selecting it. Click the menu and you will see a list of connections made at the bottom. Above that are two lists of signals and slots and above them the respective sender and receiver are selected. An easy way to make connections is visually. Look at the toolbar or the Tools menu. There are three items grouped there. A pointer, signals and slot connections and the tab order or widgets. Selecting this sets connection mode for the curios. Click on your widget to send the signal and drag it to your widget to receive it in a slot. As you do this you will see a line and drop indications on the widget under the mouse. The StatusBar on the Editor will tell you what is being connected.
In version 1.3 there is a Kommander function connect() which allows you to connect signals and slots on the fly. This is useful if you just used createWidget. Obviously you can't use the dialog for something Kommander doesn't yet know exists. Unfortunately there are too many combinations to list so you have to type out signals and slots. These must be typed verbatim or they will fail. This is where the connection tool is handy again. Open it and select two widgets like the two you want to connect and read the connection information. if it says execute(const TQString&) that is exactly what you must type.
As of version 1.3 Kommander adds Slot functions. You can see this in the Function Browser, which is uncharacteristicly less than friendly with descriptions here. What Kommander is doing is reading every slot registered for a given widget and making it available directly. This is very useful. For instance the Table widget doesn't have a default method to auto adjust column width. You may find this annoying, but if you look under slots there it is. The TextEdit is also lacking in built in functions for any real editing, but look under slots and there is anything you could wish for. You may have to reference some docs or just experiment. It is simply too difficult to document every slot available in builtin widgets and plugins. Most slots however are self explanatory.
Would you like to comment or contribute an update to this page?
Send feedback to the TDE Development Team