NOMADS Graphical Application
|
Property Maintenance Utility (*win/propset) | |
The Property Maintenance utility (*win/propset) is designed to provide the foundation for displaying and maintaining properties. This utility can be used for any PxPlus object within your application.
In PxPlus, this functionality is used by the
NOMADS Environment Maintenance utility to display and maintain
%NOMADS Properties used by the %NOMADS object (*obj/nomads.pvc).
(The Property Maintenance utility was added in PxPlus 2020.)
(The NOMADS Environment Maintenance utility was added in PxPlus 2020.)
The Property Maintenance utility uses two files, a developer-defined Definition File and a user-defined Settings File. The developer-defined Object Definition File is a simple text file that stores information about a PxPlus object and the properties associated with it. At run time, this information is presented in a grid format on the maintenance panel. Property values are entered in the grid and saved to a user-defined Settings File. These settings may be applied to the object on demand by calling the utility's *win/propset;apply method. See
Applying the Properties to the Object.
The *obj/param object can also be used to create, load and maintain an independent object consisting of just the parameters as defined in a Definition File. For usage details with an example, see
*OBJ/PARAM.
(The *OBJ/PARAM object was added in PxPlus 2020.)
Invocation
To run an instance of the Property Maintenance utility, the following CALL syntax is used:
call "*win/propset;maint", def_file$, settings_file$
Where:
|
|
def_file$ |
Pathname of the developer-defined Object Definition File that contains the properties definitions. See
Defining a Definition File. |
|
|
settings_file$ |
Pathname of the user-defined Settings File that contains the properties and their values to be set. See
Settings File. |
Example:
One way to better understand how this works is to look at the PxPlus
NOMADS Environment Maintenance utility as an example. This utility, which was created for the %NOMADS object, is invoked by using the following syntax:
call "*win/propset;maint","*win/nomads_properties.txt","nomads_prop_save.txt"
Where:
|
|
nomads_properties.txt |
PxPlus system Definition File that stores information about the %NOMADS object and the properties associated with it. |
|
|
nomads_prop_save.txt |
User-defined Settings File that stores the values entered in the Properties Grid for %NOMADS properties. |
Below are two examples of maintenance panels created with this utility. See
Performing the Property Maintenance.
|
|
 |
This is an example of the maintenance panel that displays at run time for %NOMADS properties.
It also shows a few values that have been entered by a user.
The properties in the grid are loaded based on the contents of the Definition File that was created specifically for the %NOMADS object. |
|
|
 |
This is an example of how you can use the Property Maintenance utility to create a maintenance panel, similar to the one above, for any PxPlus object within your application.
This is a sample maintenance panel that was created to display and maintain properties for the PxPlus Excel Object.
For details on how this example was created, see
Example: Property Maintenance Task.
After creating your Property Maintenance task, you can add it to the
PxPlus IDE Main Launcher for easy access.
To do this, see
Adding a Property Maintenance Task to IDE Main Launcher. |
To maintain the properties of a PxPlus object within your application, a developer-defined Object Definition File must be manually defined using any name you wish, such as yourobject_properties.txt. The Definition File is a simple text file used for entering specific details about the object and its associated properties.
The Definition File must adhere to the Definition File Format described in the table below. This format was used in defining the PxPlus system Definition File for the %NOMADS object. To look at an excerpt from this file, see
Definition File - %NOMADS Object.
Definition File Format
Although the Settings below are shown in uppercase, the actual text used in the developer-defined Definition File is case insensitive. Spaces are also allowed on either side of the = (equals sign).
Example:
Either Title = or title = (with spaces) is a valid setting, as is Title= or title= (without spaces).
|
Setting |
Description |
|
TITLE= |
(Required) The developer-defined Object Definition File must begin with a line that specifies the Title to display at the top of the maintenance panel.
Example:
TITLE=Maintain NOMADS Environment |
|
OBJECT= |
(Optional) If desired, enter an object handle that will display before the Property name (beside the Property Description: prompt near the bottom of the maintenance panel).
Defaults to _obj if not set.
Example:
OBJECT=%NOMADS |
|
HELPLINK= |
(Optional) If desired, enter a URL address for a resulting link button control that will display to the right of the Property Description text (near the bottom of the maintenance panel). When selected, this link will launch a concurrent panel showing the Web page.
See HELPLINK_TEXT= below.
Example:
HELPLINK=https://manual.pvxplus.com/PXPLUS/NOMADS%20Graphical%20Application/Appendix/NOMADS%20Variables/Overview.htm |
|
HELPLINK_TEXT= |
(Optional) If HELPLINK= is set, "Help" will display as the default text for the resulting link button control.
To override the default text, use this setting to enter the desired text.
Example:
HELPLINK_TEXT=Nomads Properties Help |
|
CATEGORY= |
(Optional) If desired, categories can be used to organize the properties into sub-sections to make locating a particular property easier, particularly if there are many properties that may be set. Define all the properties that belong to a certain category before entering the name of another category.
Example:
CATEGORY=Charts
… then define all the properties for the Charts Category
CATEGORY=Controls
… then define all the properties for the Controls Category Note:
If no CATEGORY= settings are defined, no Category column will display in the Properties Grid. |
|
PROPERTY= |
(Required) Each object property must be defined and should include the PROPERTY= and NOTE= settings at a minimum.
Example:
PROPERTY=Center_Wdw
NOTE=Select to set center next panel when displayed.
For simple text input, these two settings may be all that is needed to define the property. Depending on the desired type of input, additional Property Settings (in the table below) can also be used. Note:
If the NOTE= text will be lengthy, line feeds can be inserted by using the |(pipe symbol) where desired to make the text easier to read.
Example:
NOTE=This is the first part of the note.|This is the second part of the note that will display on the line below.
Property Settings
Other settings, besides the PROPERTY= and NOTE= settings, can be used to define the property:
|
LEN= |
Used to limit the allowable length of string input.
Example:
LEN=2 |
|
CELLFORMAT$= |
Used to specify an input format and length for numeric input.
Example:
CELLFORMAT$="####" |
|
CELLTYPE$= |
Used to specify the grid cell type. Some commonly used cell types are "CheckMark", "DropBox", "Lookup" and "LookupHideBtn". See
Cell Types.
Example:
CELLTYPE$="Lookup" Note:
Use CELLTYPE$="CheckMark" for numeric properties that are set to either 1 (On) or 0 (Off). |
|
LOOKUP= |
Used to indicate a method in a program that can be called to perform lookup logic.
Example:
LOOKUP="program_name";"method_name"
Where:
The corresponding method would look something like:
METHOD_NAME:
g1'row=g1'CurrentRow,g1'column=g1'currentcolumn,qry_val$=g1'value$
process "SOMEQUERY","",qry_val$,[optional parameters]
g1'row=GRID_1.ROW,g1'column=5,g1'value$=qry_val$
return
For common types of lookups, the *win/propset program also recognizes the following standard settings:
|
LOOKUP=File |
Displays a GET_FILE_BOX that will return a file path. |
|
LOOKUP=Directory |
Displays a GET_FILE_BOX that will return a directory path. |
|
LOOKUP=Color (or Colour) |
Displays the standard PxPlus Color query. |
|
LOOKUP=Font |
Displays the standard PxPlus Font query |
|
LOOKUP=Bitmap |
Displays the standard PxPlus Bitmap query |
|
LOOKUP=Query |
Displays a list of all Query library panels. |
|
LOOKUP=Popup |
Displays a list of all Popup library panels. |
|
LOOKUP=Class |
Displays a list of Data Classes. |
|
LOOKUP=Theme |
Displays a list of Themes. |
When using these standard LOOKUP settings, a BITMAP$ value will be provided; however, it may be overridden using the BITMAP$= setting. |
|
BITMAP$= |
Bitmap to be used for the Lookup button.
Example:
BITMAP$="!Find" |
|
TEXT$= |
For a Drop Box entry, set TEXT$= to a delimited string of the available options, ending with the delimiter character.
Example:
TEXT$="Option 1/Option 2/Option 3/" |
|
CELLTBL$= |
If a Drop Box entry requires a translation table, set CELLTBL$= to the translation values (with no delimiters).
Example:
CELLTBL$="123" |
|
CELLTBLWIDTH= |
If a Drop Box entry with a translation table has translation values longer than one character, set CELLTBLWIDTH= to the length of the translation values.
Example:
CELLTBL$="JanFebMarAprMayJunJulAugSepOctNovDec"
CELLTBLWIDTH=3 | |
Definition File - %NOMADS Object
To serve as a guide when creating a developer-defined Object Definition File, it may be helpful to look at the contents of the nomads_properties.txt file for the %NOMADS object, located in the *win directory.
Example:
To provide an example of a developer-defined Object Definition File, the following is an excerpt from the nomads_properties.txt file that shows the TITLE=, OBJECT= and HELPLINK= settings and the other types of property definitions available:
! Title for maintenance dialog
TITLE=Maintain NOMADS Environment
! Object name for displaying Property Description
OBJECT=%NOMADS
! Optional Help link
HELPLINK=https://manual.pvxplus.com/PXPLUS/NOMADS%20Graphical%20Application/Appendix/NOMADS%20Variables/Overview.htm
HELPLINK_TEXT=Nomads Properties Help
…
CATEGORY=Menu Bar
PROPERTY=Menu$
NOTE=Enter the menu group or item to be pasted to the menu bar definition in a different panel.||Example: Group
PROPERTY=Menu_LeftEdge_Clr$
NOTE=Enter the left edge color for menu items.
CELLTYPE$="Lookup"
LOOKUP=Color
PROPERTY=Menu_TextBackground_Clr$
NOTE=Enter the text background color for menu items.
CELLTYPE$="Lookup"
LOOKUP=Color
BITMAP$="!Find"
CATEGORY=Message Library
PROPERTY=Msgmnt$
NOTE=Enter the name of message library being updated in the Message Library Maintenance.
CELLTYPE$="Lookup"
LOOKUP=File
CATEGORY=Panel Persistence
PROPERTY=Panel_Info_Force
NOTE=Select to automatically save panel/control coordinates on the termination of a panel whether or not their values have changed, if panel/object persistence is turned on. Used with Panel Persistence.
CELLTYPE$="CheckMark"
PROPERTY=Panel_Info_Prog$
NOTE=Enter the name of the program that will read and write the panel information to a disk file. Use the generic program *winpnl or create your own. Used with Panel Persistence.
CELLTYPE$="Lookup"
LOOKUP=File
The Property Maintenance panel consists of the following:
|
Definition File |
Displays the pathname of a developer-defined Object Definition File used to load the properties into the grid. This is the first parameter passed when calling the *win/propset;maint method. |
|
Settings File |
Displays the pathname of the user-defined Settings File used to save the values entered in the Properties Grid. This is the second parameter that is needed when calling the *win/propset;maint method. |
|
Copy To |
Launches the Copy Settings File window for copying the user-defined Settings File to another directory.
 |
|
(Properties Grid) |
The grid lists the properties defined for the PxPlus object and is also used to define the settings for desired properties.
It consists of the following columns:
|
Category |
Properties can be sorted into categories to make it easier to find a particular property. Click the column heading to toggle between ascending or descending order. |
|
Property |
By default, properties are initially sorted by Category (if defined) and then by Property name for each Category. To sort the entire list by Property name, click the Property column heading to toggle between ascending or descending order. |
|
Set |
Select this check box to set the value entered for the property to allow it to be applied. This check box is selected automatically when a value is entered in the Value/Expression column.
If a value is entered and the Set check box is not selected, the value will not be applied after it is saved in the user-defined Settings File.
To sort the entire list to see which properties have the Set check box selected, click the Set column heading. |
|
Exp |
Select this check box if the value to be entered in the Value/Expression column will be an expression. |
|
Value/Expression |
Enter a value for the property.
Depending on the contents of the developer-defined Object Definition File, the value may be set by a check box, a string or numeric entry, selected from a query containing data from another table, or selected from a predefined list of possible values. | |
|
Property Description |
Describes the selected property and the method for setting its value when clicking on a row in the grid. |
|
Reset |
Clears the contents of the user-defined Settings File so that properties can be defined again from the beginning. Prior to clearing this file, a message will display. |
|
Display Settings |
Displays the last saved contents of the user-defined Settings File in a separate window (for viewing only). |
|
OK |
Saves the values in the Value/Expression column to the user-defined Settings File and exits the utility.
If a value was entered and the Set check box was not selected, the value will be saved as a remark line (i.e. begins with ! exclamation point) and will not be applied. Therefore, any property values set by another means (e.g. in the
START_UP Program) will not be overwritten unless deliberately set in the Properties Grid.
Null values that do not have the Set check box selected are not saved. |
|
Cancel |
Exits the utility without saving any values. |
|
Apply |
Similar to the OK button but does not exit the utility after saving. |
Once the values for the desired properties have been entered in the Properties Grid on the maintenance panel, the values can then be saved to the user-defined Settings File when either the OK or Apply button is selected.
Example:
To provide an example of a user-defined Settings File, below is a sample nomads_prop_save.txt file that shows the %NOMADS properties that were set:
Chart$="plus"
Chart_Colors$=X$
! PublicAutoChart=1 (This line begins with ! (exclamation point), indicating it is a remark line. As a result, this value will not be applied.)
FM_Clear_Option$="1"
FM_Update_Option$="L"
SuppressWindXMakeFolder=1
To apply the properties (saved in the user-defined Settings File) to the object itself, the following syntax is used:
call "*win/propset;apply",object_id,settings_file$
Where:
|
|
object_id |
Object identifier associated with the object for which the properties should be applied. |
|
|
settings_file$ |
Pathname of the text file containing properties and values to be set. |
Because the object handler is passed in the CALL, the object must be instantiated.
Example:
|
PxPlus Excel Object Properties: |
X=new("*obj/excel)
call "*win/propset;apply",X,"excel_prop_save.txt" |
This example was created using the
PxPlus Excel Object. It demonstrates how you can use this utility to define a new Property Maintenance task for any PxPlus object within your application.
Calling Syntax - PxPlus Excel Object
To run an instance of the Property Maintenance utility for the PxPlus Excel object, the following CALL syntax can be used:
call "*win/propset;maint","*win/excel_properties.txt","excel_prop_save.txt"
Where:
|
|
excel_properties.txt |
Developer-defined Object Definition File used to store information about the PxPlus Excel object and the properties associated with it. See
Definition File - PxPlus Excel Object. |
|
|
excel_prop_save.txt |
User-defined Settings File used to store the values entered in the Properties Grid for Excel object properties. See
Settings File - PxPlus Excel Object. |
Definition File - PxPlus Excel Object
In the example below, the developer-defined Object Definition File below (excel_properties.txt) defines the properties of the PxPlus Excel object, which are not read only.
Since the object handle is variable, no OBJECT= was used. A sort by Category (see
CATEGORY= setting) was not included in this example, since only six properties were defined.
! Title for maintenance dialog
TITLE=PxPlus Excel Object Properties
PROPERTY=CASE_SENSITIVE_SEARCH
NOTE=Defaults to 'Off' for case insensitive searches. Set to 'On' for case sensitive searches. Bitmap to display to the left of the tab, if applicable.
CELLTYPE$="CheckMark"
PROPERTY=DISPLAY_ALERTS
NOTE=Allows suppression of Excel message boxes. Defaults to 'Off'.
CELLTYPE$="CheckMark"
PROPERTY=KEEP_VISIBLE
NOTE=Check to keep the Excel application active and visible when the PxPlus Excel object is dropped. Has no effect if the VISIBLE property has not been set. Defaults to 'Off'.
CELLTYPE$="CheckMark"
PROPERTY=MATCH_ENTIRE_CELL
NOTE=Defaults to 'Off' for partial matches within cell contents. Set to 'On' to force matches on the entire cell contents.
CELLTYPE$="CheckMark"
PROPERTY=SEP$
NOTE=Delimiter used on various Read$ and Write methods to separate individual cell values. Defaults to the standard PxPlus field delimiter SEP ($8A$).
LEN=10
PROPERTY=VISIBLE
NOTE=Allows the Excel application to be visible. Defaults to 'Off'.
CELLTYPE$="CheckMark"
Based on the contents of this file, the following maintenance panel displays at run time, which can be used to enter values:
Settings File - PxPlus Excel Object
In the example below, the user-defined Settings File below (excel_prop_save.txt) stores the values entered for the PxPlus Excel object properties in the Properties Grid above.
KEEP_VISIBLE=1
SEP$=excel_sep$
VISIBLE=1
After creating your Property Maintenance task, you can add this task to the
PxPlus IDE Main Launcher.
To do this, the first step is to define a task with this program. In the
Task Definition dialog, enter the following:
|
|
Panel/Program |
Enter: "*win/propset;maint" |
|
|
Parameter 1 |
This is the first argument, def_file$, which is the pathname of the developer-defined Object Definition File that contains property definition information. |
|
|
Parameter 2 |
This is the second argument, settings_file$, which is the pathname of the user-defined Settings File that contains the properties and values to be set. |
Once the task is defined, the second step is to add it to a menu in the IDE Main Launcher using
Menu Maintenance.
Example:
As an example, below is the task definition for the NOMADS Environment Maintenance utility:
See Also
PROPERTY Declare Object Properties
NOMADS Environment Maintenance
START_UP Initialization Program
*OBJ/PARAM Parameter Object