http://docs.kde.org/
PrevKrusader ToolsNext

UserActions

With ActionMan you can set up, configure and manage UserActions. Some general settings are configured with Konfigurator. With UserActions you can perform actions on files in the panel or to access Krusader internal functions with parameters directly using placeholders. The actions integrate seamlessly into Plasma™ action system, which means that the standard Edit Toolbar and Edit Shortcut dialogs will show UserActions, too. The UserActions are stored in ~/.local/share/krusader/useractions.xml or krusader/useraction.xml in the folder which can be determined using the qtpaths --paths GenericDataLocation command. Several examples are included in the documentation. UserActions can be edited / added / imported / exported by using ActionMan. The default UserActions are stored in /usr/share/krusader/useraction-examples.xml. UserActions can appear nearly everywhere where “normal” KActions can be placed. The actions can even be placed in the menu bar, but for that the krusaderui.rc file must be edited. A few examples:

Krusader's UserActions tool is very powerful and customizable if you are familiar with writing UserActions in general.

Tip

Several UserActions are provided by default. Please upload your favorite UserActions so that they become available for the Krusader community. Thanks!

Figure 9.7. ActionMan

ActionMan

Basically, UserActions are a method to call external programs with variable parameters. For example, you could have a UserAction with the following xmms --enqueue %aList("Selected")% to enqueue all selected items of the active panel to the current instance of xmms. Additionally, there is limited access to Krusader internal functions requiring parameters. For example, %aPanelSize("80")% will set the width of the active panel to 80% of the Krusader mainwindow. Since the parameter of placeholders can contain other placeholders, few scripts are possible.

Managing UserActions

Open Konfigurator and choose User Actions → Start ActionMan, in which you can add, edit, remove, import and export UserActions.

  • Add Action: If you add an new action, you get an empty input mask where you can enter all the properties you desire. The action will be added as soon as you press Apply. Afterwards, the name is shown in the list on the left.

  • To edit a UserAction: Select the UserAction on the left. Then choose it if you want to edit its properties. The changes will only take effect when you press Apply.

  • To remove a UserAction: Select the UserAction on the left and click the button.

  • To import a UserAction: If you import some actions, they will be automatically added to your list. If there are name conflicts (the names have to be unique because these are the ID for Plasma™ action system), you are asked to resolve them. For this, the list on the left will only show the actions where conflicts exist. You can now give them new names or remove them.

  • Export Action: If you export a UserAction you have to give a filename in which to store it. If it does not exist, it will be created. If the file already contains UserActions, the action you are exporting will be added to that file.

All actions you have defined are now shown in the user menu and in Plasma™ dialogs for changing shortcuts and managing the toolbar. In addition, all actions available for the current item will also show up in the right click menu.

Basic Properties

Identifier, Title and Command line are always required, all the other properties are optional.

  • Identifier: A unique name of the UserAction, used to identify it for Plasma™ action system.

  • Icon button: The icon for your UserAction.

  • Category: Categories are used for a better overview. They appear as submenu items in the Useractions menu.

  • Title: The title displayed in the menus or dialogs.

  • Tooltip: A tooltip for your UserAction, e.g. displayed in the toolbar on mouseover.

  • Description: A description of what the UserAction does. This is also displayed as What's This if you Shift+F1 click on your UserAction.

  • Command: The command which will be executed. You can add placeholder using a GUI with the add button.

  • Workdir: The working folder for the command which will be executed.

  • Execution mode:

    • Normal: Normal execution mode.

    • Run in terminal: Runs the command in the terminal.

    • Run in embedded terminal emulator: Runs the command in the embedded terminal.

    • Collect output: Collects the output of the executed program in a GUI window.

    • Separate standard error: When “Collect output” is used the stdout and stderr are separately collected.

  • Command accepts:

    • Local files only (no URLs): Tells the placeholder it should return local addresses.

    • URLs (remote and local): Tells the placeholder it should return URLs.

  • Default shortcut: Configures a default shortcut for the UserAction.

  • Enabled: if checked, the useraction is shown in the User Menu, otherwise the useraction will be hidden.

Command-line syntax

Basically, everything you type in the command line will get executed (if you type “ls -l”, “ls -l” gets executed). You have the possibility to get a character string from Krusader which represents the current state of the panel. This is done using placeholders. A placeholder begins with a percent-sign ('%') and is followed by a panel indicator ('a' for the active, 'o' for the other, 'l' for the left and 'r' for the right panel. If the placeholder does not need a panel to operate on, you have to indicate this by an underscore ('_')). Then comes the name of the placeholder (see the list below), which may get some parameters enclosed in quotes. Finally, again the percent sign.

This sounds very complicated, so let's make an example: '%aList("Selected")%' is replaced by a list of all selected items in the active panel. So a command like 'xmms --enqueue %aList("All", " ", "", "*.mp3")%' will execute xmms with a list of all .mp3s in the current panel, separated by a single blank.

Currently, these placeholders are implemented:

  • Path - replaced by the panels path

    1. Parameter (optional): Automatic escape spaces. Default: yes

  • Count - replaced by the number of <first parameter>

    1. Parameter: Which items; either “All”, “Selected”, “Files” or “Dirs”

  • Filter - replaced by the panel's filter mask

  • Current - replaced by the current item

    1. Parameter (optional): Omit the current path. Default: no

    2. Parameter (optional): Automatic escape spaces. Default: yes

  • List - replaced by a list of all <first parameter>

    1. Parameter: Which items; either “All”, “Selected”, “Files” or “Dirs”

    2. Parameter (optional): Separator between the items. Default: “ ”

    3. Parameter (optional): Omit the current path. Default: no

    4. Parameter (optional): Filtermask (for all but “Selected”). Default: *

    5. Parameter (optional): Automatic escape spaces. Default: yes

  • Select - manipulates the selection in a panel

    1. Parameter: Filtermask

    2. Parameter (optional): manipulate in which way; either “Set”, “Add” or “Remove”. Default: “Set”

  • Goto - changes the panels' path to <first parameter>

    1. Parameter: A relative or absolute path, or an URL

    2. Parameter (optional): Open the location in a new tab. Default: no

  • Ask - asks the user for some text and is replaced by the answer

    1. Parameter: The Question

    2. Parameter (optional): A default answer

    3. Parameter (optional): A caption for the question box

  • Clipboard - manipulates the clipboard

    1. Parameter: The text that should go to the clipboard (you may want to use “%aCurrent%” here)

    2. Parameter (optional): Append the text to the current content of the clipboard with this separator

  • Copy - copies a file, useful for quick, local backups

    1. Parameter: What should be copied

    2. Parameter: Where it should be copied

  • Sync - opens the Synchronizer with a given profile

    1. Parameter: A profile for the Synchronizer

  • NewSearch - opens the search windows with a given profile

    1. Parameter: A profile for the search module

  • Profile - loads a given panel profile

    1. Parameter: A panel profile

  • Each - splits the commandline into a list. These commands are executed one after another.

    1. Parameter: A list item (all, all files, all dirs, all selected).

  • Move - move from source to destination.

    1. Parameter: A source

    2. Parameter: A destination

  • PanelSize - change the ratio between the two panels.

    1. Parameter (optional): A integer value, e.g., 80 makes the active panel use 80% of Krusader's width (height in vertical mode), omitting the parameter means 50%.

  • Ask - cancel the execution.

    1. Parameter (optional): A string for the cancel question.

  • ListFile - is replaced by path/file name of a temporary file containing a list of items

    1. Parameter: path/filename

  • ColSort - set the sorting on a column of a specific panel.

    1. Parameter: Column: Either “Name”, “Ext”, “Type”, “Size”, “Modified”, “Perms”, “rwx”, “Owner” and “Group”

    2. Parameter: Sort sequence: Either “Toggle”, “Asc”, “Desc”

  • View - set the view mode.

    1. Parameter: View mode: Either “generic”, “text”, “hex”

    2. Parameter: Window Mode: Either “tab”, “window”

A GUI-based helper for placeholder adding is provided. Spaces in Path, Current and List are by default, automatically escaped. There is one more important thing to know: All placeholders that interact with Krusader internal functions are called at expand time (meaning directly when the placeholders are replaced). External programs are called at execution time (meaning after all placeholders are replaced).

Advanced Properties

Here you can configure where your command should be visible (for the right click menu). In addition, it is possible to change the command executed and confirm it separately. You can also set a user under which the command should be executed.

  • Configures if the action is valid for a Protocol, Path, MIME type or File name.

  • Tweaking the command line before being executed.

  • Set a different user for the execution (this has no effect in Krusader internal functions)