File Manager Customization

Introduction
Controlling the File Manager
- 2.1 Ordering File Types
- 2.2 Modifying File Types via Customization File
- 2.3 Specifying the Initial File Type
- 2.4 Controlling the Last Used File Type
- 2.5 Specifying the Default View Mode
- 2.6 Defining an Auxiliary Button
- 2.7 Specifying the Initial Directory
Registering New File Types
Manipulating File Types
- 4.1 Accessing All File Type Keys
- 4.2 Inquiring File Type Properties
- 4.3 Modifying File Type Properties
- 4.4 Unregistering File Types

1. Introduction

All load and save commands in Creo Elements/Direct Modeling are triggered from a common file manager.

Like the file browser, the file manager displays files within a directory that match with the patterns of a selected file type. In addition, the file manager contains an 'Options' button that brings up further data related with the load or save command at hand. In the case of save commands, the file manager also displays a 'Select' button and a list region that contains the objects to be saved.

The selection of a file type immediately triggers a command. That command will receive input from the file manager and other input sources - like the input area or mouse picks in a viewport.

File types behaviors can be modified by changing a customization file that is automatically loaded while Creo Elements/Direct Modeling starts up. This customization file also determines the ordering of the file types in the UI.

Alternatively, a set of file type manipulation functions are available to modify specific properties of a file type. For example, the set of currently displayed file types can be modified at runtime.

A new file type can be added to the file manager by adding appropriate specifications to the corresponding command definition (see 4.7.1 Linking Dialogs to the File Manager). These specifications automatically register a new file type to the file manager and link the corresponding file and selection variables of the dialog to the UI components of the file manager.

New file types can also be registered explicitly, particularily of they call already existing commands. The file type registration must specify the information that is necessary for controlling the behavior of the command from the common file manager and vice versa.

Whenever a new file type is registered, whether it be implicitly via a dialog definition or explicitly via a call to the registration function, that file type should also be inserted into a customization file in order to enforce a predefined sequence of file types in the UI.

2. Controlling the File Manager

2.1 Ordering File Types

The ordering of the file types in the file manager UI can be specified in the file

        all_load_save_file_types.dat

At startup time, that file is be searched for in the user, site, corp and sd directories (in that order) and the first one found is used to define the file type ordering in the file manager.

Creo Elements/Direct Modeling is delivered with the file all_load_save_file_types.dat which specifies the ordering of the file types as they appear in the file manager. If this file is removed, the file types are displayed in alphabetical order, which is is rarely practical.

The above file contains a separator that groups the file types into native and non-native load/save file types. This separator is displayed in the file type list in the file manager UI.

All new file types that have been registered implicitly via sd-defdialog or explicitly via sd-register-file-type should preferably be inserted into this file in order to ensure a well defined sequence of file types in the UI.

2.2 Modifying File Types via Customization File

The files mentioned in the previous section allow customization of the individual existing file types. All relevant options of file types can be overridden via the customization file, including titles, tokens, strings and LISP-forms.

More precisely, all keywords supported by the function sd-register-file-type can be overridden via customization. The function sd-inquire-file-type can be used to inquire the properties that are currently being used for a given file type.

As an example, assume that we want to modify the file type :sat and to restrict the saving of ACIS data to version 3.0. Then it suffices to copy the file sd_load_save_file_types.dat into our personal startup directory, rename the file to user_load_save_file_types.dat and to replace the entry

     (:acis_sat)
by
     (:acis_sat :title "ACIS (SAT 3.0)" 
                :out-cmd "native_cad_out :cad_system :acis_sat :version \"3.0\"" 
                :out-cmd-options nil)

This modification sets the :title to "ACIS (SAT 3.0)", overrides the :out-cmd with the new command sequence "native_cad_out :cad_system :acis_sat :version \"3.0\"" and disables the 'Options' button by means of the keyword :out-cmd-options.

Another example of the use of a file type option is the removal of an Annotation file type from the file manager. The following line

     (:hatches :enable-form nil)       ;;Annotation

suppresses the file type :hatches in the file manager when the Annotation module is active. The above approach is required for any file type that is defined after the processing of the customization file (which takes place after the initial startup of Creo Elements/Direct Modeling).

2.3 Specifying the Initial File Type

The initial load and save file types are by default set to :package. However, if the file manager is called while the Annotation application is active, the initial file type is set to :bundle.

This default behavior can be overridden by specifying an initial load file type and an initial save file type with the following function:

    (sd-set-initial-file-type
            :application application         ;default="SolidDesigner"
            :load-file-type file-type-key
            :save-file-type file-type-key)

This function can be called any time before the file manager is activated. Typically, it will be called within some customization file that is loaded when Creo Elements/Direct Modeling starts up. Note that the specified file types need not have been registered at the time of the above call.

An example is,

     (sd-set-initial-file-type :application "Annotation"
                               :load-file-type :drawing
                               :save-file-type :drawing)

2.4 Controlling the Last Used File Type

When the file manager is activated a second or third time, it normally displays the file type that was last used in the previous occurence of the file manager. Each Creo Elements/Direct Modeling application has its own last used file types.

Alternatively, the file manager can be instructed to ignore the last used file type and to return to the initial file type on reentering the file manager. The following function controls the displayed file type when activating the file manager:

     (sd-allow-last-used-file-type boolean)

where boolean can be either t or nil.

2.5 Specifying the Default View Mode

The file manager and the file browser contain two icons that cause the view mode of the files to switch between a list and a details mode. In the details mode, additional information such as file size, file type and date of modification is displayed in a tabular format.

The following form

     (sd-set-file-browser-default-view-mode mode),

where mode is either :list or :details, will set the default view mode of file manager and the file browser.

2.6 Defining an Auxiliary Button

An additional auxiliary button can be added to the file manager. The auxiliary button can be installed by the following expression

     (frame2-ui:set-file-aux-option title-string action-string)
 e.g.
     (frame2-ui:set-file-aux-option "XY Options" "my_dialog")

The auxiliary button appears between the 'Options' and the 'Help' buttons. This button can be used to trigger dialogs and functions. In the above example, the activation of the button, titled "XY Options", will trigger the dialog my_dialog.

The auxiliary button can be deinstalled by the following expression

     (frame2-ui:set-file-aux-option)

2.7 Specifying the Initial Directory

The initial directory is set to the last used directory of the previous Creo Elements/Direct Modeling session.

It is important to emphasize that directory changes within the pesd_customize file are not permanent. In order to retain directory changes that have been executed within the pesd_customize file, it is necessary to call the function (ignore-previous-startup-directory) anywhere within the pesd_customize file.

Thus, for example, the following code in the pesd_customize file will force Creo Elements/Direct Modeling to remain in the directory "c:/my_directory" after startup:

     (ignore-previous-startup-directory)
     cd "c:/my_directory"

3. Registering New File Types

In most cases, the registration of a new file type occurs implicitly together with the dialog specifications, as described in 4.7.1 Linking Dialogs to the File Manager.

New file types can also be based on already existing load/save commands. For example, if the same basic dialog is used to support several different file types, then it is necessary to specify each individual file type separately outside the scope of the dialog.

The function sd-register-file-type defines a file type from scratch and discards all previously assigned properties.

(sd-register-file-type key
     :title title_string
     :patterns list_of_pattern_strings

     :in-cmd command_string
     :in-cmd-initial-token token
     :in-cmd-file-token token
     :in-cmd-options token
     :in-form string_with_universal_load_form
     :attempt-in-form-with-any-file  boolean
     :exclude-from-universal-load    boolean
     :universal-load-with-user-units boolean

     :out-cmd command_string
     :out-cmd-initial-token token
     :out-cmd-select-token token
     :out-cmd-file-token token
     :out-cmd-options token
     :override-elements-text text

     :module module_name
     :display boolean
     :enable-form lisp_form

     :in-patterns list_of_pattern_strings
     :out-patterns list_of_pattern_strings
     :in-display boolean
     :out-display boolean
     :in-enable-form lisp_form
     :out-enable-form lisp_form
     :in-title in-title-string
     :out-title out-title-string
     :in-cmd-show-options boolean
     :out-cmd-show-options boolean

     :auto-complete-on-filename keyword
     :allow-old-revision boolean
     :allow-load-as-version boolean

     :force boolean)

Parameters:

key {KEYWORD}

A unique file type keyword. This keyword can be used to define, access and modify data related with the file type.

:title {STRING [key]}

Specifies the text that appears in the list of file types.

:patterns {LIST of STRINGS [nil]}

Specifies the patterns of files that will be displayed in the folder. The patterns specified in :patterns are automatically appended to the title.
Patterns can contain the characters * and ?, which match with any number of characters or with one character, respectively. The following strings represent feasible patterns, "*.xy", "xy.*", "ab*.pkg", and "ab?.pkg".

:in-cmd {STRING [nil]}

Specifies the name of the load command. This command will immediately trigger when the corresponding file type has been selected.

:in-cmd-initial-token {KEYWORD or STRING [nil]}

Specifies a token that will be initially passed to the command before it becomes interactive.

:in-cmd-file-token {KEYWORD or STRING [nil]}

Specifies a token that will be passed to the command before a file name is passed to that command. Upon successful acceptance of a filename, the load command should be designed to automatically terminate. If the file name cannot be accepted by the command, then the load command must remain active.

:in-cmd-options {KEYWORD or STRING [nil]}

Specifies a token that will be passed to the command when the options button is pressed. That token should have the effect of raising an additional window that contains further load options. If no token is provided, then the options button will be disabled.

:in-form {LISP-expression-in-string-form [nil]}

Specifies a Lisp form that will be evaluated by the universal load command. This form can contain an entry called :file-slot which will be substituted by the filename that appears in the common file manager.
Assume that a command called my_load_command contains a variable my_file with a :value-type set to :filename. The :in-form would then look like this:

:in-form "(my_load_command :a_file :file-slot)"

:attempt-in-form-with-any-file {BOOLEAN [nil]}

Specifies whether the :in-form should be executed within the universal load command even if the selected file does not match with the given :patterns.

:exclude-from-universal-load {BOOLEAN [nil]}

All file types that appear in the load file manager are automatically used as candidates when loading a file via the universal load command. If this flag is set to t, the dialog will not be included for consideration in the universal load command.

:universal-load-with-user-units {BOOLEAN [nil]}

Inhibits the conversion of user units (i.e. external units) to internal units during a universal load operation. This option should be set to T for file types that load environment files.

:out-cmd {STRING [nil]}

Specifies the name of the save command. See also :in-cmd.

out-cmd-initial-token {KEYWORD or STRING [nil]}

Specifies a token that will be initially passed to the command before it becomes interactive.

:out-cmd-select-token {KEYWORD or STRING [nil]}

Specifies a token that will be passed to the command when the select button is pressed. That token should cause the command to enter the select subaction

:out-cmd-file-token {KEYWORD or STRING [nil]}

Specifies a token that will be passed to the command before a file name is passed to the command. Upon successful acceptance of a filename, the save command should automatically terminate.In case the file name is not processed successfully, the save command must remain active.

:out-cmd-options {KEYWORD or STRING [nil]}

Specifies a token that will be passed to the command when the options button is pressed. That token should have the effect of raising an additional window that contains further save options. If no token is provided, then the options button will be disabled.

:override-elements-text {STRING [nil]}

Specifies text to be written into the area displaying the selected objects. If a text is supplied the Select button will be greyed out.
Dialogs that make use of this feature do not need to possess a selection variable. It is sufficient to insert the file variable into the :filing-variables list and to specify that variable as follows:

:direction :save

:module {STRING [nil]}

Specifies a licence module that must be active in order to choose the file type. The default value nil specifies that the file type will always be accepted.
The list of valid file types is checked each time when the file manager is instantiated. The displayed list only includes file types for currently active modules. Most Creo Elements/Direct Modeling load and save commands are not connected to a module and are therefore always included in the list of file types, unless the parameter :display is modified (see next option).

:display {BOOLEAN [t]}

Specifies whether the file type should be displayed in the list of currently valid file types. If a :module is specified then both the module and the display conditions must be satisfied in order to include the file type in the list of file types.
This parameter can be useful to (temporarily) disinclude basic Creo Elements/Direct Modeling load and save commands when some other application module is active.
This option is typically not used in combination with :enable-form, see comment below.

:enable-form {LISP-form [t]}

Specifies whether the file type should be displayed in the list of currently valid file types.

:in-patterns {LIST of STRINGS}

Overrides the patterns specified in :patterns for the load file manager.

:out-patterns {LIST of STRINGS}

Overrides the patterns specified in :patterns for the save file manager.

:in-display {t nil}

Overrides the :display option for the load file manager.

:out-display {t nil}

Overrides the :display option for the save file manager.

:in-enable-form {LISP-form}

Overrides the :enable-form option for the load file manager.

:out-enable-form {LISP-form}

Overrides the :enable-form option for the save file manager.

:in-title {in-title-string}

Overrides the option :title when displaying the load file manager.

:out-title {out-title-string}

Overrides the option :title when displaying the save file manager.

:in-cmd-show-options {t nil [nil]}

If set to t, this specification causes the 'Options' button to be pressed when this file type is selected in the load file manager, thus causing the options window to be displayed. By default, the 'Options' button is not initially pressed.

:out-cmd-show-options {t nil [nil]}

If set to t, this specification causes the 'Options' button to be pressed when this file type is selected in the save file manager, thus causing the options window to be displayed. By default, the 'Options' button is not initially pressed.

:auto-complete-on-filename {:action-routine | :personality | :none [:action-routine]}

Once the file name of a filing dialog has been established, the dialog immediately enters the :ok-action. This option controls how the completion should be implemented:: :action-routine - the auto complete functionality is implemented within the action routine code.; :personality - the auto complete functionality is implemented within the personality code.; :none - switches the auto complete functionality off.

:allow-old-revision {t nil [nil]}

Enables an option in the file manager that switches the revision of a save operation to an older revision of Creo Elements/Direct Modeling.

:allow-load-as-version {t nil [nil]}

Enables an option in the file manager that allows parts and assemblies to be loaded as versions.

:force {t nil [nil]}

Forces the supplied properties to override the properties that have been specified in a customization file. By default, data supplied in a customization file prevails over calls to sd-register-file-type and sd-modify-file-type.
This option cannot be employed within a customization file.

Comment: The parameters :in-display, :out-display, and :display can be useful to (temporarily) disinclude basic Creo Elements/Direct Modeling load and save commands when some other application module is active. The tests are carried out int the following order:

  - :in-display, :out-display
  - :display
  - :in-enable-form, :out-enable-form
  - :enable-form

Beware: File types that have been registered for the file manager are not automatically available in the input tool file browser. The input tool file browser is used for dialog variables which have the value-type :filename.

By default, the registered file type will appear just below the separator in the file type como box. More suitable positions can be specified by modifying or adding certain customization files as described in section 2.1 Ordering File Types

Example: Suppose we want to introduce two new SAT file types, say :sat3.0 and :sat1.5, one for saving 3D data in version 3.0 and another one for saving data in version 1.5. The following calls are then required:

     (sd-register-file-type :sat3.0
                :title "ACIS (SAT 3.0)"
                :patterns '("*.sat")
                :out-cmd "save_sat :version :30"
                :out-cmd-initial-token :select
                :out-file-token :filename
                :out-cmd-select-token :select)

     (sd-register-file-type :sat1.5
                :title "ACIS (SAT 1.5)"
                :patterns '("*.sat")
                :out-cmd "save_sat :version :15"
                :out-cmd-initial-token :select
                :out-file-token :filename
                :out-cmd-select-token :select)

Hint: Since the above two file types are very similar to the file type :sat, we can inquire the values for the properties :patterns, :out-cmd-initial-token, :out-file-token and :out-cmd-select-token by means of the call (sd-inquire-file-type :sat). The other properties, :title and :out-cmd, are slight modifications of the corresponding :sat properties.

4. Manipulating File Types

4.1 Accessing All File Type Keys

(sd-get-file-type-keys :visible-only boolean)

Parameters:

:visible-only {BOOLEAN [nil]}: If set to t, only file types that are visible in the file manager will be returned.

Return Value:

{LIST of KEYWORDs}

This function returns a list of all file types that have been registered to the file manager.

For example, the call (sd-file-type-keys) will return a list of keywords including the keyword :sat. Note that some of the returned file types will not be visible in the UI (unless :visibible-only is set to t). The visibility of a file type depends on the activation of a corresponding module and on the current Creo Elements/Direct Modeling application or simply on the value of certain file type properties such as :display. Thus, for example, :sat is not displayed in the file manager when the Annotation application is current.

4.2 Inquiring File Type Properties

(sd-inquire-file-type key &optional property)

This function returns the value of the specified property. If no property is specified, a property list containing all properties and values is returned.

For example, the call (sd-inquire-file-type :sat) returns a list with the following contents:

     (...  :TITLE "ACIS (SAT)" 
           :PATTERNS ("*.sat") 
           :OUT-CMD "save_sat"
           :OUT-CMD-OPTIONS :DISPLAY-OPTIONS 
           :OUT-CMD-INITIAL-TOKEN :SELECT
           :OUT-CMD-FILE-TOKEN :FILENAME 
           :OUT-CMD-SELECT-TOKEN :SELECT)

4.3 Modifying File Type Properties

(sd-modify-file-type key property_1 value_1
                         ... 
                         property_n value_n)

This function sets the specified property values. The function can be used to set one or any number of properties. Other properties that were not specified remain unchanged. As an example, assume that we want to modify the file type :sat and to restrict the saving of ACIS data to version 3.0. Then we could call

     (sd-modify-file-type :sat :title "ACIS (SAT 3.0)" 
                               :out-cmd "save_sat :version :30"
                               :out-cmd-options nil)

An alternative way to override individual file type properties is to make additions to a customization file that is loaded when Creo Elements/Direct Modeling is started (see 2.2 Modifying File Types via Customization File).

The customization file specifications remain valid, even if an attempt is made to override them with a subsequent call to sd-modify-file-type. In order to override a customized property, the following additional keyword must be employed

               :force t

in the sd-modify-file-type call.

4.4 Unregistering File Types

(sd-unregister-file-type key)

This function removes the specified file type from the file manager.

For example, the call (sd-unregister-file-type :sat) will remove the file type :sat from the file type list.