Initialization FIles
Initialization is accomplished by executing commands in WinPTE command files, which by convention, have a .pte extension.
.pte Files
These are plain text files and contain WinPTE commands. The format is one command per line, with the only exception being the begindef/enddef which enclose a multiline macro function or key definition. The commands in the file will be executed sequentially and any errors will stop the load process and report the error. Macro function and key definitions are commands with the side-effect of defining a macro.
On startup WinPTE will load the main.pte file, it will search for it in the working directory and failing to find it there will look in its installation directory. If it does not find it or the file loads with errors then a small set of predefined key definitions will be created. This is a bare minimum and only intended to be used to correct the load error. Without its macro definitions WinPTE is barely usable, so testing of changes to startup files is very important, at least to make sure they load without errors.
The main.pte file contains macro functions and key definitions for the 'default' language template. It also loads all other startup command files using the 'macro fileName' command which has the effect of executing commands in another file.
Language template definitions files are also loaded by main.pte via the 'macro' command.
If present in the installation directory, or the WinPTE search path (more on that later), then the custom.pte file will also be loaded. This file is intended to hold commands and customizations added by you. This file is not present in the install script and is not going to be overwritten by a new installation.
.ptc Files
These are precompiled macro files used for improving load time and can be safely ignored or deleted. They will be recreated if they are missing, or a newer version of the corresponding .pte file exists or if the WinPTE build number of the running instance differs from the build number of the instance that created the .ptc file.
Command Line Options
The start up file can be overridden on the command line by specifying the startup file prefixed with @ character. All files so prefixed will be executed sequentially. If the execution does not result in any errors then the main.pte file will not be loaded! In the past this allowed complete customization of startup, today with so much functionality being part of the main.pte file, it is less feasible but the mechanism is still there.
Additionally WinPTE will execute the value of PTEEXEC environment variable if it is defined. The text will be executed as an arbitrary WinPTE command. Since this happens before any command files are loaded (even ones specified on the command line) only built-in commands can be used.
By default WinPTE when launched will pass its arguments to an existing instance of WinPTE and exit without ever creating the main window. Some command line options are evaluated before the main window is created and are useful for controlling a previously loaded instance of WinPTE.
| Option | Properties |
|---|---|
| /New | Launch a new instance even if another instance is already running. |
| /b | Bring a previous instance of WinPTE to the foreground. This is done before the main window is created and if /New is not used then will exit without creating a window. |
| @fileName | load the file with the 'macro' command. Has the effect of executing all lines as WinPTE commands |
| fileName | load the file using the edit command. Has the effect of loading it as text |
| any other options | appended to the previous command being executed. Useful for edit command that takes /row=line# and /col=Col# to specify the cursor position for the loaded file. |
WinPTE is also Pipe enabled, if launched from a console window with standard input coming from a pipe it will send the text from the pipe to a previous instance of WinPTE, if there is no previous instance it will launch a new instance and pass the piped text to it. The latter is done to make sure that the instance being piped to exists once the pipe is closed. Otherwise the command prompt will not appear until WinPTE is exited.
The piped in text will be appended to the internal read only file '.WinPTE'.
So you can pipe command output to WinPTE from the console and it will be loaded as text. Also if you execute WinPTE without providing /New it will load the passed in file name(s) into an existing instance, passing any command line options. So to load a file and move the cursor to a given line/column, execute the following:
WinPTE "fileName" /row=Line# /col=Col#
This can be used for loading files into WinPTE from other programs that allow definition of external tools and can pass current cursor position information on the command line.
Macro Keys, Functions and Language Templates
Language templates define a list of file extensions to be associated with the template. When a file is loaded all templates are checked for a matching extension and the file is associated with the first one found. From that moment on all macro calls and key resolution will use the associated template definitions.
Each language template can optionally specify what other template it is based on (i.e. derived from) this is used as a primitive inheritance mechanism during macro and key resolution. The default template is the base for all templates that do not have an explicit base defined.
All key strokes and macro calls are resolved using the language specific template first, then the template it is based on, and the template that the base template is based on, and so on, until finally the default template is reached. The first template in the inheritance list to define the key or function provides the macro definition for that call. If the key or function is not defined then an error is displayed.
Key definitions and macro functions at this point in time are the same with the only difference being that keys are predefined and either have a definition associated with them or not, while macro functions are user defined and come into being when their definition is encountered or a forward reference is created with the 'key' command. This means that a function has to be declared before it is encountered as a reference in another definition or an error will occur on loading of the file containing the reference to the undefined function.
Character case is significant for key and function names.
All functions and keys can have an optional extension or list of extensions appended to the end of the name. The extensions are the same as file extensions and separated by . These are used to associate the definition with a particular language template. If the extension is not given then the definition is added to the 'default' language template. If an extension does not match one of the language template associated extensions an error is raised.
Commands
WinPTE has a few built-in commands that are executed as text typed on the command line. You can also define your own commands, which map to macro functions when invoked. It is expected that the macro function will do its own parsing of the command line contents to extract its parameters. To by pass any user defined commands and execute the built-in command, prefix the command with an !.
Several user defined commands are defined in the main.pte file. For example 'open' which uses the open files dialog is not a built in command and will execute the 'edit' command for any selected files to load them. Another example is 'cd' command to change the current working directory. This command is overridden by a user defined command so that the directory passed as a parameter could be added to the recent directory list. Similarly for the 'quit' command which adds the file to the recent files list. All menus, toolbars, pop-up menus and recent lists are macro defined and maintained.
Language Templates
Macro functions and key definitions for a particular language template are contained in .pte files in the FileExt subdirectory of WinPTE. All commands that define language template specific configuration or macro definition contain an extension parameter which is used to associate it with a language template. Other than that there is nothing particular about the file in which the command is encountered and can be defined anywhere.
The location of the language template files and the fact that they contain configuration commands and macro definitions for that template is only a convention. All the commands can be put into a single file, split up or mixed up amongst different files.
Persistence of User Data and Configuration
All configuration data is in the process of being moved to the data store, which is an event driven hierarchical database that is loaded on startup from the WinPTE.xml file in the user profile (Application Data/WinPTE/WinPTE.xml) and stored on exit in the same file.
Some configuration commands will only create entries in the data store if the data is not already defined. This has the effect of initializing the data but will not overwrite it on subsequent launches of WinPTE. After initial creation the data is expected to be modified via the Options Pane interface. Language template specific settings are such data, the exception being macro definitions which are loaded each time from the command file since they are not persisted to the data store. The rest are left as they were during the first execution until the data store node for the template is deleted.
Data points for Language Templates are stored under the /editor/session/templates/TemplateName node.
The data in the data store contains passive and active data points, uniquely identified by the path of the data point. Passive data points are used to persist data and query data when it is needed. Active data points are used for persistence like the passive data points, but will also generate an immediate effect on the state of WinPTE when the value of the data changes. Current value of active data points also reflects the current state of this data in WinPTE.
An example of an active data point is /editor/session/window/show data point which has a numeric value representing the main window "Show" state: <0 minimized, 0 restored, >0 maximized. Reading this value reflects the current window state and changing this value will change the current window state. There are many such points representing the GUI components of WinPTE.
Template data in the data store is a combination of active and passive data points. The column colorization setting and the extension list is active, while other settings are passive data points.
Menus, Toolbars and Actions
In WinPTE all user interactive GUI components are defined through an "action" definition. An action defines the icon, caption, description, function called to implement the action and a macro definition to update the state of the action: visible, enabled, checked, caption and description.
Actions are grouped into action lists, which can be displayed as either toolbars or menus depending on the context. The actions and action lists will update all GUI control instances that represent them when the action or action list value changes. Therefore all instances of an action or an action list, regardless of whether they are menu items or toolbar buttons will always reflect the current definition of the action or the list. Changing the caption will affect all menu items and buttons.
Actions come in several flavors:
- Buttons represent menu items and normal buttons
- Check buttons represent check menu items and check buttons that convey on/off state of some property or setting
- Dropdown represent sub menus or menu buttons on the toolbar, these take an action list as a parameter to define the menu contents.
- Split Dropdown represent split drop down buttons that are a combination of button and a drop down menu. , these take an action list as a parameter to define the menu contents.
- Edit represent edit text boxes that can be added to menus or toolbars. These are not currently used but they are available.
- Combo represent combo boxes that can be added to menus or toolbars. These are not currently used but they are available.