- Discussion Topics
- Online Resources
- Other Resources
This is an old revision of the document!
A User-Defined Tool (UDT) is a definition of a command-line, where ToDoList fills in live data, and then executes the command on request. With the data, the program that's called makes use of the data to “do something”.
In the above screenshot, a few of the functions seen in the grid include:
Note: None of the above UDTs are in your instance of ToDoList. These are all “user-defined” and added by individuals to enhance their own environment. However, people who use ToDoList are eager to share their UDTs and a home will soon be provided for user contributions. Work in Progress.
The screen above (Preferences > User Defined Tools) lets you configure 3rd party tools to extend ToDoList's functionality. Tools set up there are accessible via the Tools Menu and hotkeys shortcuts. Here are the menu items created from the above UDT configuration:
<!– Note: To provide the greatest flexibility, this functionality has been written very generally, which may make it appear more complex than it really is. To assist you therefore, some examples are included at the end of this section. –>
The goal is to create a command template that can be populated with data at run-time, and then executed from the DOS prompt. It would look something like this:
c:\path\to\program\name.exe -switch1 -switch2 "data1" -switch "data2"
The switches and data are whatever is required for the name.exe program to work. As seen below, the data can be provided by ToDoList in Arguments.
The following details describe the configuration screen as seen above. The column headers of the grid are profiled. Each of the columns has a corresponding entry field under the grid:
Tool Name This lists the currently configured tools. The names are assigned by you / the user. Tools not having a name or path will not appear in the Tools Menu. To change the name of a tool, single-click on the tool name, or if you click on the name and it doesn't open for editing, press F2.
Arguments Construct a set of data that will be passed in the command-line. The down-arrow button attached to this field will display a list of “placeholder” variables for data that ToDoList will substitute when you run the tool. For example an argument might be set as follows:
The $(selTID) is inserted by ToDoList after clicking the down-arrow button to show a list of available data. In that list is “Selected Task ID”. When clicked, the placeholder “$(selTID)” is inserted into the arguments field. So with the above argument set, at runtime, the value of the current selected task will be substituted, maybe #217, and the final command will look something like this.
Whatever happens in that command is outside the scope of ToDoList and this documentation. It's up to you to find or create scripts or programs which do things that you want, and then to get ToDoList to provide those programs with required data to provide the results you seek.
The following table contains all currently supported placeholders (which should be considered case-Sensitive):
|ToDoList Pathname||$(todolist)||Full path to the ToDoList executable|
|Tasklist Pathname||$(pathname)||Full path to the active tasklist|
|Tasklist Folder||$(folder)||Full path to the folder containing the active task list|
|Tasklist File Title||$(filetitle)||The filename of the active tasklist without the extension|
|Tasklist Filename||$(filename)||The full filename of the active tasklist|
|Selected Task ID||$(selTID)||ID of the current selected task|
|Selected Task Title||$(selTTitle)||Title of the current selected task|
|Selected Task External ID||$(selTExtID)||External ID of the current selected task|
|Selected Task Comment||$(selTComments)||Comments of the current selected task|
|User Date||$(userdate, var_date1, “Date Prompt”, default_date)||(see 'User placeholders' below)|
|User Filepath||$(userfile, var_file1, “File Prompt”, default_path)||(see 'User placeholders' below)|
|User Folder||$(userfolder, var_folder1, “Folder Prompt”, default_folder)||(see 'User placeholders' below)|
|User Text||$(usertext, var_text1, “Text Prompt”, default_text)||(see 'User placeholders' below)|
|Today's Date||$(todaysdate)||Date in ISO format|
User placeholders Placeholders prefixed by 'user' will result in the user (you) being prompted to enter information when the UDT is executed. This is useful where the information is not known in advance or it frequently changes. User placeholders typically take 3 additional arguments:
Example of a User Placeholder:
There are no quotes around the user data for the command-line. That could cause a problem with the program that processes the data. The next example adds quotes:
More examples will be provided in the future, here and/or in a related page.
Icon Path Each UDT can have its own icon image. The icon can come from a file of any of these types: .ico, .bmp, .png, .jpg. If the path is set to an executable program, the primary icon from that program will be used, as seen for all of the icons in the above examples. Some icon file types were not usable prior to v22.214.171.124, but the types here should be usable in all current releases.
Run Minimized (checkbox) Runs the tool as a minimized task. Useful for running batch files.
Delete Tool (button) Deletes the selected tool.
There is no UnDo for this. The only way to recover from an accident here is to click Cancel, which will undo everything for the current preference change session.
Test Tool (button) This allows you to run the selected tool using the currently selected task for data if the arguments require it. On clicking the button, a “Test Tool” window displays to tell you “Tool 'path\name.ext' will be run using the following commandline arguments: '-your args'. It will prompt “Do you want to continue?” with a Yes or No button. The arguments will be filled in with currently available data - you will be prompted if required to get user data.
While this is a “test”, the UDT will actually be executed, so be sure that's OK before continuing.
* Tooltips for UDT toolbar buttons On mouseover of a toolbar icon for a UDT, the tooltip will display the name of the UDT, and if assigned, the shortcut assigned to the UDT. So you don't even need to click the toolbar, you can just use a hotkey to execute your UDT. The following image shows the tooltip over the fourth icon of the UDT toolbar shown above. Note this icon has a shortcut of Ctrl+T: The following image shows the shortcut configuration, where under the Tools menu there is a User Defined Tool 4 which has been assigned Ctrl+T. *
The following (rough) examples illustrate possible uses of the tools system and one possible way of solving each challenge.
"$(userfile, var_msxsl, "Path to Msxsl.exe")" "$(pathname)" "$(userfile, var_xslfile, "Path to Xsl file")" "$(folder) $(filetitle).html"
Note that there are two *userfile* placeholders, and that fields are surrounded by quotes as described above.