![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
View > Format > DefineThe View > Format > Define command displays a dialog box which allows you to define and modify display formats for directory and versions viewer windows.
The dialog for versions viewer windows Define Versions Format is slightly different from that for directory viewer windows Define Directory Format. In particular, the Define Versions Format dialog does not have the Alignment point check box, the Menu String field and the Make this the default display format check box. The Save Format button in the Define Versions Format dialog is similar to the Define Format button in the Define Directory Format dialog.
This dialog is used to iteratively construct a display format string and then define the format. For a newly defined directory viewer format, a new menu item is automatically created at the end of the Format menu. The label on that menu item can be specified in the Menu String: input area. The internal name of the format will be of the form user_formatN where N = 1,2,3... up to a limit of 15.
For a versions window format, new View > Format menu entries cannot be specified, however, the predefined formats may be changed. For example, the "Standard" format may be changed to produce a different desired format. Also, a user-defined format can be selected in the Control > Show > Versions (Apex/Summit) dialog before a versions window is displayed. The format can be changed after a versions window is displayed by invoking this command, setting the Format Name field to indicate the desired format, and pressing the Try Format button
Format String
A format is defined by building a format string. The format string indicates the data to be presented and how it should be laid-out. The kinds of data fields permitted are listed in the Format field choices list box. The Add Field at Cursor button maybe used to add a selected field to the format string. Fields may also be entered manually.
The format string consists of three kinds of items
- substitution keywords which are replaced in the display line by a field containing some characteristic of the object being displayed. Substitution keywords begin with a percent sign.
- justification and size indicators which may follow the keyword in brackets ([ ])
- other characters, such as spaces, which are placed directly into the display line.
The syntax of a field format in a format string is
%<keyword>[(<name>)][[<alignment><size>[A]]]
The expression in square brackets can be added as a suffix to the keyword to specify a field size and field justification within the column - left, right or centered. If a field's value is larger than the field size, the default is to truncate on the right. To have the entire field always shown, even if it exceeds the field size, a final A can be given. For example,
%Owner[8] - a fixed size 8 character field.
%Size[R8A] - a fixed size 8 character field, right justified and if the value exceeds 8 characters it will all be shown.
If fixed size fields are used, then all columns will line up.
In addition, certain keywords lead to fields which are always a fixed size without needing that to be specified explicitly. For example, UNIX acls (%Acls) and file update times (%Time).
To achieve alignment with variable size fields there is a keyword which specifies that an alignment point should occur for the next character in the display line. For a multi-line display, the next character for all lines will occur at the same column, which is the one after the longest line up to that point. For example, the Cmvc_Attributes format starts
%Dash%Indent%Name%Mark %Align%History ...
This causes the History column for all lines to start after the longest value in the preceding name column. For performance reasons, alignment point should only be used when necessary. For example, the File_Attributes format uses all fixed size fields, before the last one, and needs no alignment points.
%Acls %Owner[8] %Size[R8A] %Time %Indent%Lname%Mark
In a versions window, all fields are aligned by default, so the %Align keyword is not used. No %Align is required for the first field in a format string.
Since the directory display allows multiple levels of subdirectories to be expanded in place, there is a keyword called, %Indent, which inserts the indent spaces based on the nesting level of the item.
To define a new format, iteratively pick a field kind from the field choices list at the top of the dialog and use the Add button to add it to the end of the format string. The field kinds from the choices list are mapped into a single or multiple keyword sequence. To add to the middle of the format string, move the cursor within the format string by clicking the mouse at the desired spot and then press Add.
The Alignment point check box may be used to specify an alignment point before the next field added to the format string. No alignment point is added before the first field, since that field is aligned by default.
The Column Size field may be used to specify a fixed size for the field. In this case, the internal alignment of the field is specified in the Justify options menu by selecting Left, Center, or Right.
While making changes to a format string, there are convenience buttons to Replace and Delete segments of the format string. Adjustments to the format string can also be made by directly editing the format string, for example, to insert more space characters between fields.
Defining or Saving the Format
To define or save a format string, select the Define Format or Save Format button. A format name must be specified in the Format Name field. The set of format names for directory windows is fixed, but any name may be specified for the corresponding menu item. A versions windows format can be given any unique name specified in the Format Name field.
To change the format, simply edit the format string as described above and push the Define Format or Save Format button again.
- Try Format Button
Use the Try Format button to apply the format string to the directory or versions window from which this command was invoked. To apply the format to some other window, drag the menu bar from that window, drop it on the label "Window:" that appears at the top of this dialog, and then push the Try Format button.
Format Keywords
The following format keywords are available for directory windows:
The following format keywords are available for versions windows:
Version Attribute Formats (Apex/Summit)
Special formats are provided for displaying extended version attributes associated with a file or version.
If there are attributes defined in the subsystem in which the Format > Define dialog was invoked, or if there are attributes defined globally via the APEX_VERSION_ATTRIBUTES_KEY switch, the Format field choices list will contain formats for each attribute. These format choices have the form
where <attribute name> is the name of a specific attribute. They display the values of the corresponding attributes. There is also special format for displaying any extended attribute:
When this format is added to the format string via the Add Field at Cursor button, the name of the attribute to be displayed must be entered.
To display all attributes, you may use the format choice:
This format displays the values of all attributes visible in the subsystem containing the version. The attribute values are sorted by the attribute names (which are not displayed).
will display those attribute which are visible in the current context in which the format is defined.
Invoking Apex Shell Formatting Functions (%function)
An apex_shell function can be invoked in a format string. The syntax for a function call is
%function(<function_name>)
The %function keyword invokes the name apex_shell function.
The string value returned by the function will be inserted into the display line.
For a directory window format, the pathname of the directory entry is passed to the function as an argument.
$1 (pathname) the full pathname of the directory entry
For a versions window format, the following arguments are passed
To have acceptable performance when using this option, the function given should be written so that all of it's statements are interpretively executed with no forking of Unix executables. For example, to add the UNIX group_id to the File_Attributes display, a new format could be defined (or the existing one redefined) as the following
%Acls %Owner[8] %function(get_gid) %Align%Size[R8A] %Time %Indent%Lname%Mark
and the following function added to the file $HOME/.Rational/directory_rules.
function get_gid file f "$1" return \Qf.group_id\Q end_function
Additional Topics
For more information, click on a topic:
- View > Format Submenu
- Extended Version Attributes (Apex/Summit)
Rational Software Corporation http://www.rational.com support@rational.com techpubs@rational.com Copyright © 1993-2001, Rational Software Corporation. All rights reserved. |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |