PrevKrusader Tools  Next

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 KDE's action system, which means that the standard Edit Toolbar and Edit Shortcut dialogs will show UserActions, too. The UserActions are stored in ~/.kde/share/apps/krusader/useraction.xml (the file structure is documentated in doxygen headers of UserActionXML). Several examples are included in the documentation. UserActions can be edited / added / imported / exported by using ActionMan. The default UserActions are stored in ~/.kde/share/apps/krusader/useraction-examples.xml. UserActions can appear nearly everywhere where "normal" KActions can be placed. The actions integrate seamlessly into KDE action system, which means that the standard Edit Toolbar and Edit Shortcut dialogs will show UserActions, too. They 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! We provide also an UserActions Forum.

Figure 11.8. 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. However, scripting can be done with the JavaScript console.

Managing UserActions

Open Konfigurator and choose "UserActions -> 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 Ok. 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 OK.

  • To remove a UserAction: Select the UserAction on the left and click the remove 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 KDE's 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 KDE 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

"Distinct Name", "Title" and "Command line"are always required, all the other properties are optional.

  • "Distinct Name": A unique name of the UserAction, used to identify it for KDE's action system.

  • "Icon button": The icon for your UserAction.

  • "Category": Adds a category for a better overview. NOTE: This property is not used yet. It is planned to be used, but has not implemented yet.

  • "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.

  • "Use Tooltip checkbox": Uses the tooltip as description.

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

  • "Startpath": The working directory for the command which will be executed.

  • "Execution mode":

    • "Normal": Normal execution mode.

    • "Run in terminal": Runs the command in the 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 (no URLs)": Tells the placeholder it should return local addresses.

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

  • "Shortcut button": Configures a shortcut for the UserAction.

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 possiblity 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 doesn't 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.

  • Script - executes an external Javascript file.

    NOTE: This is still experimental and the interface may change, feedback is always welcome.

    1. Parameter: path to the external foo.js file, absolute path or relative to <kde-app-data>/krusader/js/. <kde-app-data> is $(kde-config --localprefix)/share/apps/ or $(kde-config --prefix)/share/apps/, for those who don't know where to copy the scripts/extensions. If all the needed files (normally .js and maybe .ui) are in one of these dirs it's sufficient to give the file name only as 1. parameter.

    2. Parameter (optional): a list of variables which should be set, like "return=cmd; a=lalala; b='%_Ask(..)'" so that the placeholder is replaced be the content of the variable cmd and the other two have already these values when the script starts.

  • 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)

PrevHomeNext
Synchronizer Up Konfigurator: Krusader's Configuration Center