[kde-doc-english] Competition entry

[Andras Mantia]

Hi,

 Here is a document describing how to configure toolbars in KDE. I hope 
you like it.

Andras
-- 
Quanta Plus developer - http://quanta.sourceforge.net
K Desktop Environment - http://www.kde.org
-------------- next part --------------
Configuring toolbars

1. Actions

 Actions are the basics of interaction between the user and KDE applications. Whenever you click on a menu item, a toolbar icon or use a keyboard shortcut, an
action is executed. Every KDE application has a predefined set of actions and the application developer organizes those in menus and toolbars and provides
pre-defined shortcuts for some of them. The visual representation of an action on a toolbar is an icon and by clicking on the icon the action gets executed.
There is a special kind of action which behaves a little bit differently. This actions are container actions, so they hold more than one action. You can identify these
actions by the small black down arrow in the bottom-right corner of the action's icon [screenshot]. Clicking on it executed the default of the contained actions
(the first one in the list), while if you keep the mouse pressed on the icon a list with the possible actions appear.
 The user cannot change the layout of the menus from the GUI (although it's possible to do by modifying config files), but there is a possibility to change the toolbars and the shortcuts assigned to actions.

2. Actions on toolbars

 The toolbar configuration dialog can be accessed in different ways. One of the possibilities is through the Settings menu, Configure Toolbars menu item.
[here it comes a screenshot of the dialog for applications with one toolbar]
 The dialog contains two main areas:
 - the list of Available actions contains all the actions that are not yet accessible via this toolbar
 - the list of Current actions contains the actions that are on the toolbar

 Adding an action to the toolbar is possible either by clicking on the desired action and later on the right arrow between the two lists or by dragging the action
 and dropping on the Current actions list at the desired position. In the first case the action will be put after the currently selected action from the Current
 actions list. You can reorganize the order of appearance of the actions either by using the up/down arrows that are between the two lists or by drag and drop.
  Removing an action is similar to addition, it possible by using the left arrow button or D&D from the Current actions list to the Available actions list.
 There are two special items in the Available actions, that are always present there, so you can put an unlimited number of such item on a toolbar. These are:
 - line separator: appears as a line between two action icons
 - separator: appears as a larger space between two action icons

 Below the Current actions list you can find the Change Icon button, a convenient way to change the icon of the selected action from the Current Actions list.
As usual OK closes the dialog and applies the changes, Apply applies the changes, so you can verify your changes visually, Cancel closes the dialog without applying your
 modifications. All changes since the last Apply pressing or the last time since you closed the dialog with OK are lost.

  In some cases you will find a different version of the dialog, with an extra drop-down combobox:
  [screenshot of a dialog with multiple toolbars & parts, e.g. Konqueror]

  This is either because:
  - the application has more than one toolbar
  - the application integrates other applications (parts) using the KPart technology

  In both cases you must select first a toolbar and later follow the above steps to modify the specific toolbar. You will notice that if an application uses multiple toolbars,
 the same action can appear on different toolbars, but one action can appear only once on a toolbar.
  A little different is the case when the application integrates other parts. In this case you will notice that two toolbars appear in the dropdown list with the same name
followed by a more or less scriptic word, for example:
 Location Toolbar <Konqueror>
 Location Toolbar <searchbar>
 [might come a screenshot here]

 Those two toolbars are combined into one, yet one of them are provided by the application "Konqueror", the other by the application called "searchbar". You will see that
 the list of available actions are different for the two toolbars, as you can put on the "searchbar" version of the Location toolbar only the actions that are provided by
 the searchbar. Same is for the "Konqueror" case. Whenever you modify the toolbar for a part, the toolbar will be modified in all applications using that part.
 You can see this behavior in case of Katepart (Main Toolbar <KatePartView> in Kate's Configure Toolbars dialog), because if you modify this toolbar, the modifications will be
 visible in Kate, KWrite, KDevelop, Quanta and all the other applications using the Katepart as a text editor.

  The second way of accessing the configure dialog is from the context menu of a toolbar. This behavior is convenient in case of multiple toolbars, as the dialog will default
  automatically to the toolbar that you were clicking on. There are two drawbacks though:
  - it's not accessible from every application
  - in case of parts, the dialog default to the first toolbar with the name of the clicked toolbar. In case of Konqueror's location toolbar, independent of the point where you've
  invoked the context menu, it will always bring up the Location Toolbar <Konqueror>, that being the first Location toolbar in the list.

 3. The look and feel of toolbars

  Aside of putting, removing or arranging actions on toolbars it is also possible to change their look. One possibility is to change them globally. Run the Control Center, choose
  Appearance & Themes->Style and click on the Miscellaneous tab. Here under the Toolbar Setting group you can tune you're toolbars behavior and look:
  - Highlighting buttons under mouse: when checked you will get visual feedback which action would be executed if you click on the current position
  - Transparent toolbars when moving: it is possible to move your toolbar across the screen, inside the application area or undock it an make a separate window (see below). This
  option controls whether only a frame will be visible while you move the toolbar, or the whole toolbar with icons on it.
  - Text position: choose how detailed do you want to see your actions:
  	- Icons only: only an icon will represent the toolbar. If you leave you mouse above an icon for some seconds, the action's name will appear in a tooltip box
	- Text only: instead of an icon, a text (the action's name) will represent the action on the toolbar
	- Text alongside icons: the icon and the action's name in the right of the icon will appear as a visual representation of the action
	- Text under icons: same as the previous one, just that the action's name will appear below the icon.
	The global setting of the text position will be applied to all newly started applications, except for those toolbar that you've already modified separately. (must be verified,
	as it seems to not work correctly in KDE 3.3.0 release). In the case when the action icons doesn't fit on the screen maybe because Text Alongside icons was activated) you will
	see an >> area in the right/bottom part of the toolbar. Clicking on them will bring you a list with the actions not yet visible due to missing screen space.

  Instead of modifying the settings globally, you can do it per toolbar and per application. The common way to access the modifying actions is the toolbar's context menu.
  The items in this menu are:
  - Orientation: well your toolbar appears inside the application. Top, Left, Right and Bottom are self explaining. Floating means that your toolbar will appear in a separate
    (floating) window, Flat means that the toolbar is collapsed. You can click on the double horizontal/vertical lines to get it back to full size [screenshot of flat toolbar]. The orientation can be
    changed with drag and drop as well. Grab the toolbar at the edge of it on the double horizontal/vertical lines.
    - Text position: already explained
    - Icon size: how big will the icons be. The global configuration for this is in Control Center->Appearance & Themes->Icons, Advanced tab. In the Use of Icon list select Toolbar
    or Main Toolbar (you an configure a different value for main toolbars) and select the size and check/uncheck the Double-sized pixels box according to your wish.
    - Hide Toolbar: present only if the application contains only one toolbar. It hides the toolbar. You can get back the toolbar by using Settings->Show Toolbar.
    - Toolbars: a submenu which controls the appearance of toolbars if the application has multiple toolbars. Checked items are visible toolbars, unchecked ones are hidden. The same
    menu can be accessed via Settings->Toolbars.

Configure shortcuts:

To be written. I volunteer for it if you like this document. ;-)
I hope I haven't missed anything regarding the toolbar configuration.
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: not available
Url : http://mail.kde.org/pipermail/kde-doc-english/attachments/20041003/80b8b687/attachment.sig