Skip to content

PortAL Configuration

Jump to bottom
Jerome edited this page Jan 29, 2020 · 12 revisions

The PortAL configuration file

The configuration file is a XML file named portal.xml. Portal automatically reload the configuration when the XML file is modified. By default PortAL will load the file in the same folder than the binary ; but you can create your personal configuration file

%localappdata%\GUIPro\portal.xml

On recent Windows Operating Systems, you need administrator rights to edit a file in the Program Files folder. Using a configuration in your local application data folder will be easier for you to edit and if you have administrator rights, you can customize the default configuration file for every user in the computer.

Portal main element

The configuration is a simple XML file but it has to follow some rules.

<?xml version="1.0" encoding="UTF-8"?>
<portal>
  <!-- Your configuration here -->
</portal>

The file must contain a portal root element (and only one).

This root element have two possible parameters.

<portal defaultshell="false" showshortcut="true" skin="default">
  • defaultshell (false/true) indicates if you want to launch by default the applications using the windows shell or if you let PortAL execute the application. The windows shell has the possibility to open documents. If the "application" is a HTML file, it will open your default browser to open the page.
  • showshortcut (false/true) indicates if you want to display (by default) the application shortcut in the PortAL menu.
  • skin (name) indicate the preset skin that you want to use ; you can otherwise create your own skin (describe below in the documentation). There is for the moment three skins: default, flat and dark. If you do not specify a value, it will use the fourth skin based on your operation system configuration.

The elements you will place directly in the portal root will be displayed in the system tray (systray).

  • If you place a group, PortAL will display a menu when you will click on the systray icon.
  • If you place an app, PortAL will launch directly the application when you will click on the systray icon.

Generic node

Every node (group, app or the special nodes) have the basic same parameters. They can also have some specific parameters, specially for the app node.

<app name="Name" key="" mod="" over="false" ico="" default="false" showsc="false" break="false"/>
  • name (text) the display name of the node. If you place an & (&amp; to respect the XML convention) the next letter will become the accelerator key while browsing the menu.
  • key/mod the hotkey (combination of the key and his modifier). Please check the HotKey part of his documentation for more details.
  • over (true/false) is the option to activate the hotkey override.
  • ico (file path) specify an icon for the group, which will be display in the systray or in the menu depending the context.
  • default (true/false) the node will be display as the default item in the menu (in bold)
  • showsc (true/false) override the default configuration for "show shortcut".
  • break (true/false) display a menu break after the item (it will create a new column in the menu).

Note that you can assign several hotkeys for a node (group, app, etc).

Group

A group contain other group/app/special nodes, PortAL display the group as a menu or a sub-menu. Here the minimal requirement for a group node:

<group name="Group name">
  <!-- group content -->
</group>

If the group is directly under the portal root, it will be display in the systray. If the group is in another group, it will be display as a sub-menu of his parent group.

By activating the hotkey (or several), PortAL will open the group and display it as a popup menu directly where your mouse is.

<group name="Group name" key="" mod="" over="" ico="">
  <!-- group content -->
</group>

The group node have a special parameter which allow PortAL to automatically open a systray menu when the mouse is moving over the systray icon.

<group name="Group name" autoopen="true">

This option is not recommended but it has been requested !

Application

The application is one of the most important node in the PortAL configuration. It allow you to launch an application, to open a file or even more !

Here a generic app node:

<app name="Name" exe="filepath" param="" path="" />
  • exe (text) is the application you want to execute.
  • param (text / optional) are the parameter that you will pass to the application.
  • path (text / optional) is the execution path that you can override if you want to launch the application to start in a specific path (like a shell or a window explorer).

By default, PortAL will load the icon of the exe to display it in the menu or the systray (depending the context). But you can override it ; like some other elements.

<app name="Name" exe="filepath" ico="filepath" shell="true" elevate="false" events="start,exit" />
  • shell (true/false) override the default configuration for "shell execute".
  • autorun deprecated (true/false) will indicate that the application will be automatically launch when PortAL is executed (like autoopen, this feature was a special request). Please use events start instead.
  • elevate (true/false) if you are not using the "shell" option, PortAL can launch the application with administrator elevation (depending your OS configuration, you might have a elevation approval alert box).
  • events (text) specify the different events when the application will be executed. You can use several events separated by a comma.
  • start - launch when portal start.
  • exit - launch when just portal quit.
  • lock - not yet available
  • unlock - not yet available

More than launch an application, the app node can also browse a folder and list his content.

<app name="My documents" exe="%mydocs%" browse="true" param="*.*" path="true" />
  • browse (true/false) activate the special browse feature.
  • exe (browse) (folder path) indicates the folder that will be browse.
  • param (browse) (file extension filter) filters the files which will be display in the menus.
  • path (browse) (true/empty value) display or not the sub directories.

Special nodes

Separator

<sep name=""/>

About

<about name=""/>

Reload (deprecated)

<reload name=""/>

Quit

<quit name=""/>

Variables

The variables node is a special node under the portal root node. It allows you to create new variables which could be use afterwards in your configuration file.

Here an example:

<portal>
  <variables>
    <var name="test" value="my test value"/>
    <var name="docs" value="%mydocs%/documents/"/>
  </variables>
  <group>
     <!-- your config where you can use %test% or %docs% -->
  </group>
</portal>

Skin

There is two way to set a skin in Portal ; with the skin attribute for the portal node (see above in the documentation) or using the skin node. That node allow you to create your own skin.

The skin node have three possible attributes:

  • base (color pair) defines the text color and the background color for all items.
  • selected (color pair) define the text color and the background color for an item when selected.
  • edge (true / sel / unsel / empty value) define if there is an edge display between the icon and the text.

A color pair is formed by two colors separated by a comma or a space. A color should be describe in hexadecimal format, you can add a # before in order to read it easily.

Please note that PortAL can understand color with 3 or 6 characters ; otherwise the black color will be returned.

The skin node can have three child node ; which are all optional.

  • border (border node) composed of a border size, border round and border color. A non-referenced element will have a 0 value.
  • background (gradiant node) composed of a color pair and a direction (h/v ; optional).
  • icon (gradiant node) composed of a color pair and a direction (h/v ; optional).

Example (an ugly one):

<portal>
  <skin base="" selected="#000:#FCF4ED" edge="true">
    <border size="1" round="5" color="#ffffff"/>
    <background color="#000000:#ffffff" direction="v"/>
    <icon color="#ffffff:#000000"/>
  </skin>
</portal>

Hotkeys

Keys

There is three differents way to configure a key in PortAL.

  • A letter or a number like A or 1
  • A special name like F1, NUM_0 or SPACE.
  • The keycode number like 222 (which is the key just below "escape")

View the special key binding

Modifiers

By default, if you do not specialy a modifier, PortAL will use the Win key. So you have to use the None modifier if you do not want a modifier. The modifier value ask for letters in order to determine which modifier will be used for your hotkey.

  • C - Ctrl
  • A - Alt
  • S - Shift
  • W - Win
  • Other letter - None Please note that PortAL need to uppercase to work properly.

mod="C" or mod="Ctrl" set the Ctrl modifier. You should press the Ctrl key with the another key configure with key value.

mod="AS" or mod="Alt Shift" set the Alt and Shift modifier. You should press the Alt key and Shift key with the another key configure with key value.

mod="N" is the standard to not use a modifier with the key.

Override

The override option allow to bypass the system and create an hotkey on a system hotkey. For example, Win + E is a generic system hotkey which start a file explorer.

Using over="true", you would override the system an catch the original hotkey with PortAL.

Several hotkeys per node

PortAL handle up to 10 hotkeys per node. You can use the combo key/mod/over but you can also use key1/mod1/over1, then key2/mod2/over2, then key3/mod3/over3, etc. Please note that if you do not configure key2, you won't be able to use key3

Variables replacement

  • %win% - The windows directory (generally C:\windows\ or C:\WINNT\ for Windows 2000 systems).
  • %programfiles% - The Program Files directories (generally C:\program files\ and c:\program files x86). Look into both directories on x64 platforms.
  • %programfiles86% - The x86 program file folder while running under x64 platform.
  • %system% - The System directory (generally C:\windows\system).
  • %system86% - The x64 System directory while running under x64 platform.
  • %mydocs% - My documents directory.
  • %mymusic% - My Music directory.
  • %myvideo% - My Videos directory.
  • %desktop% - The Desktop directory.
  • %appdata% - The Application Data directory.
  • %portal% - The PortAL directory.
  • %config% - The current open configuration file.
  • %clipboard% - The current clipboard content. It supports text and file. When there are several files in the clipboard, it only paste the first one.
  • %clipboards% - The current clipboard content. It supports text and files. When there are several files in the clipboard, it paste them all with a space as separator.

PortAL also handle OS common variables and will perform some dynamic replacements.

Icons

When you specify an icon for a node, you can select a specific icon in the file.

<app exe="%win%\explorer.exe" ico="%win%\explorer.exe"/>

Will use the default explorer icon ; at this moment the ico is optional because PortAL will by default take the icon from the exe.

<app exe="%win%\explorer.exe" ico="%win%\explorer.exe,6"/>

will use the 6° icon in the explorer binary file (in this case it is the full recycle bin icon).

Clone this wiki locally