Default Settings

Concepts

• General
• Styles
• Style Reference
• Persistence
• Setting Values
• Other Usability Notes

Functions

• sd-def-setting
• sd-get-setting
• sd-get-setting-value
• sd-set-setting-value
• sd-delete-setting-value
• sd-set-setting-values
• sd-update-current-setting-values
   
• sd-freeze-setting-value
• sd-unfreeze-setting-value
   
• sd-create-settings-style
• sd-delete-settings-style
• sd-delete-all-settings-styles
• sd-set-current-settings-style
• sd-get-current-settings-style
• sd-reset-current-settings-styles
• sd-get-setting-styles-range-list
• sd-get-setting-style-values
   
• sd-force-store-application-settings
• sd-force-reload-application-settings
   
• sd-finalize-application-settings
• sd-set-setting-modifiable-flag
• sd-do-on-all-settings
• sd-show-setting

Concepts

Default settings in Creo Elements/Direct Modeling are presented to the user by means of the Default Settings Browser which can be accessed from the File -> Settings menu.

Each setting is uniquely identified by a path (a string separated with "/" characters) which makes up the tree displayed in the left-most column (header: Setting) of the Default Settings Browser. Each path portion is presented by a localized string, but internally the path is unique across all languages. Branches of the tree can be opened and closed by clicking on the + and - signs in front of parent nodes.

Each setting (leaf of tree) has a definite value type or definite range of possible values. The current value of a setting is displayed in the Value column. If you do a double-click on a value cell of a setting, a little input tool pops up which allows you to modify the current default value. The title of that tool describes what type of value is expected. The label above the input field repeats the description of the setting. A setting may offer a list of proposals which can be accessed from the little down-arrow to the right of the input field. The new setting value is only accepted if it fits to the value type of the setting or if it is a member of a given range. In addition an optional check-function may reject a value too.

The string displayed in the Source column tells you the source of where the current value comes from. This could be a single level string like System, Corp, Site or User, or a combination of a style name and a level in parenthesis. If the current value of a setting is still the system default, the source level is set to System. If you as the user modified a default setting, its source will change to User or a combination of Style-Name and User. For more information about styles and how to define setting values by Corp or Site, please continue reading.

An optional question mark icon in the Help column indicates that there exists additional help for a specific setting or a group of settings (question mark at a parent node). Click this icon to display more detailed information.

A one-line short description is given in the right-most column of the Default Settings Browser. This information gives you a little more information about what the setting is good for.

If you right-click on an item or off an item you'll see a context menu with useful commands. On a parent node item you can expand or collapse this and all other child nodes with one click. If you modified one or more setting values below the selected parent node, one or both Reset ... values below commands become accessible depending on where you stored the value to. With this you can easily reset your modifications back to system, corp or site values. This functionality is also available on single settings.

The right-click commands offered in the menu when clicked off an item (area below all rows or to the left of an item) work on all settings. Here the full settings tree can be expanded or collapsed and also all user values can be restored to system, corp or site values.

Styles

The style concept allows the user (or site, corp or system) to assign certain setting values to a style to easily switch a set of setting values from one style to another. Styles can basically exist on any parent node of the settings tree, but you can only create additional styles on nodes where styles already exist or you can create additional reference styles.

If a style is active, its name is shown in blue color in the Value cell of a parent node. If no style is available, the value cell remains blank. If one or more styles exist for a parent node but no style is active, three dots "..." are shown in the value cell. Some nodes like the Annotation root node don't allow to switch off the style and therefore you'll see a blue style name in that value cell all the time.

If the current value of a setting is determined by a style, the source cell of that setting shows the name of the style plus the level on which the style value was defined on (System, Corp, Site, User).

If you change a setting value interactively at runtime the new value will be assigned automatically to the next active style along the path from the setting leaf to the root of the settings tree. If no style is active up to the root, the value is stored as User value. A user value always remains active no matter which style(s) are active on the path up to the root. Those values are also called Global User Values. For more information about user and style values, please see below.

This default assignment can manually be overwritten if you click the source cell of the setting whose value you just changed. The in-place drop down list allows you to change the value assignment to User (Global user value) or any other style which is active. That way you can have different setting values depending on which style is active at a parent node. The drop-down list also contains a command to reset the current user value. With this another defined site, corp or system value will be restored as setting value.

To switch off the current style (if possible) or to switch to another style or to create a new additional style, click the value cell of a parent node with already defined styles and an in-place range selection UI appears. Here you see which styles are defined on that node. Choose another style and settings which have a value defined in that new style will update their current value and settings which had a value in the previous style defined will determine a new value based on the new active style(s).

If you choose Create new ... from the drop-down list a dialog to create a new style on that node appears. By default the check mark to copy all style values from the previously active style on that node to the new style is set. That way you can create a variation of the style without the need to modify the original style.

On other than root nodes you can determine if the new style should be visible/accessible all the time or whether its visibility depends on which style is currently active at the root node of the parent node (node for which you create a new style).
In the example to the left, the currently active style at the root node ("Annotation") is DIN. Therefore you can tell the new style My Symbol Style to be accessible only if the root style is DIN or all the time. That way you can avoid huge lists of styles on certain parent nodes in case you want different styles to be defined for e.g. ASME, DIN and JIS. This is especially interesting if you deal with style references (see next paragraph).

Technical Note:
The programmatic interface to create a new style (sd-create-settings-style) allows you to specify more sophisticated visibility combinations. For example here it is possible to say that the new style is visible in all root styles but ASME or you can say that a style is visible only in ISO and DIN. The interactive user dialog for style creation only allows to say whether a style is visible in all root styles or the current.

Style Reference

Instead of a single value setting (value-type, range) there may also be settings which reference a style at another node and all values defined in that style make up the values of the setting. These settings are so-called style reference settings and their current values are shown in orange color.
The main advantage of such style reference settings is that a certain set of settings can be referenced in several places and if a value in such a reference style changes, each setting which references this style will be updated with that new value automatically. For example in Annotation is a General/TextStyle implemented which is referenced in all settings which display a text (e.g. view labels, text ..). With that centralized approach it is very easy to simply change e.g. the font of the style reference to be something different and all view labels and texts will be created with that new font from then on.

To set a different style to be referenced or to modify values of the referenced style, double-click the style reference value (orange string) and the Style Reference UI like this pops up:

This UI shows you at a glance which styles you can select and which values are currently defined for each of its sub settings. In the example above, 4 styles are defined: Large, Medium, Small and Standard. Just double-click one of these style names to use its sub setting values for the style reference setting (here Annotation/Text/Appearance).
As you can see from the Style Reference UI, the text style reference setting is made up out of 10 sub settings: Size, Color, Frame, Font, Filled, Ratio, Slant, Angle, Adjust and Linespace. The last column Visible tells you whether the style is visible in all styles which could be active at the root node (here Annotation) or whether it should be visible only in the current root node style (here DIN). That way the list of visible/accessible styles can be kept short in case there are different styles defined for e.g. ASME, JIS or ISO.

To modify a single value within this Style Reference UI, double-click the cell you want to change and the above introduced value change tool appears with the same features as already described.

The context menu on an item (complete row) allows you to do the following:

• Reset 'Style' user values
  If any value of the style sub settings was modified by the user, you can restore those values to site, corp or system defaults. This command is greyed out if no value has been modified by the user.
• Delete user style 'Style'
  Allows you to delete the currently selected style as long as this style is made up of user values only. If site, corp or system has defined values for this style, the style can't be deleted, because it would reappear on next startup of Creo Elements/Direct Modeling when reading the setting definition files. In that case this command is not visible at all.
• Create new style ...
  As described above this command allows you to create a new style by optionally copying values from the currently selected one.

The context menu off an item allows you to reset all user values in all styles and to create a new style.

The Auto Store To behaviour of settings which are style reference settings in combination with reduced visibility is a bit different than described above. Usually a user value is stored automatically to the next active style along the settings path to the root. If you assign a style to a style reference setting which is only visible in the currently active root style, the value will be stored automatically in the root style no matter if there are any other styles active along the path to the setting. With this behaviour it is guaranteed that the style reference value will change if the root style changes. In this situation it may happen that the style assigned to the setting is no longer visible in the new root style and therefore it is bound automatically (stored to) to the root style.

Technical Note:
All sub settings and styles as shown in the Style Reference UI are implemented as regular settings under a node (style node) which is flagged to be a Style Container. Those nodes and all child nodes are suppressed from the tree and can only be accessed via the Style Reference UI. For more details see sd-def-setting.

Persistence

Any modification at runtime in the Default Settings Browser is persistent. That means if you

• Change a setting value
• Restore the system, corp or site value
• Store a setting value in a style
• Create a new style
• Delete a pure user style
• Switch on specific styles on parent nodes

then all these changes are maintained across Creo Elements/Direct Modeling sessions automatically.

On deactivation of a module (e.g. Annotation) or latest on exit of Creo Elements/Direct Modeling one or more default setting files ("xxx.lsp") are written to a Default_Settings subdirectory within the module specific customization subdirectory in your personal customization directory. User values are written to its own file and each style writes its own file too. The filename is derived from the unique path of a setting plus the unique name of a style and starts with a module specific prefix.
Each file contains one call to sd-set-setting-values. This function fills the internal database with all potential values for a specific setting related to user values and styles.
As a site or corp admin you can simply move these files over to a site or corp customization directory to provide site or corp specific style/default values for specific settings. Corp values hide system defaults, site values hide corp and/or system defaults and user values hide site, corp and/or system defaults.

Setting Values

As described in the previous paragraphs the real and current value of a setting depends on the current style(s) situation and eventually on who (user, site, corp, system) provided values for a particular setting.

Whenever a style on a parent node changes, all settings which may be influenced by this change, update their current values automatically.

The algorithm how a setting value is determined is as follows:

1. Does a global user value exist? If yes, take this - it always wins.
2. Is a user, site, corp, system (in that order) value defined in the style which is next active along the path to the settings root? If yes, take this.
3. Continue with 2. for all other active styles on all other parent nodes of the setting up to the root.
4. If no style value is defined, check if default values are defined by site or corp.
5. Finally if all this does not return a value, the system default (must exist) value is taken. This value is not related to any style.

Other Usability Notes

The size of the Default Settings Browser and the width of each column is persistent. Drag the divider between the header titles to make a column wider or smaller. If you double-click the divider, the column to the left is resized to optimally fit its current visible contents.
The Default Settings Browser can be pinned to make it reappear at a certain screen location. To do so, do a right-click on the title bar of the Default Settings Browser and check the Pinned option.

Functions

SD-DEF-SETTING  [function]

(sd-def-setting path
                :application             application
                :title                   title
                :value-type              value-type
                :include-none-item       include-none-item
                :range                   range
                :check-function          check-function
                :default-value           default-value
                :default-style-values    default-style-values
                :action                  action
                :description             description
                :proposals               proposals
                :style-container         style-container
                :style-reference         style-reference
                :help                    help)

Description:

Creates a new default setting and fills it with default values.
In addition pure parent nodes can be created with this function as well. This is needed if the node representation in the Default Settings Browser tree should be localized. For pure parent nodes you only need to specify path, :application and :title.

Parameters:

path {STRING}

Unique "/" separated path of setting within application. The full unique path of the setting is "'application'/'path'".

:application {STRING ["SolidDesigner"]}

Name of application to which the setting belongs to.

:title {STRING}

Optional localized name to identify the setting in the Default Settings Browser. If not given, the last portion of path is taken as title.

:value-type {KEYWORD}

The type of the settings value. The following sd-defdialog value types are supported:

• :length, :positive-length
• :angle
• :number, :positive-number
• :integer, :positive-integer
• :boolean
• :string
• :rgb-color
• :list
• :keyword

:include-none-item {BOOLEAN}

This parameter is only considered if :value-type is set to :rgb-color. If this parameter is set to T, the color range will contain a None entry which causes a nil assignment to the setting when chosen.

:range {LIST of STRINGS, NUMBERS or KEYWORDS}

Instead of a :value-type a set of predefined values can be implemented by supplying a range list. String, number and keyword range lists are supported. For more information about ranges, please see the dialog generator manual.

:check-function {SYMBOL}

Optional check-function to verify the user input as potential new value for the setting against a user supplied additional check. See here for more information. Note, a check-function is also supported for :style-reference (see below) settings. With this the amount of allowed styles can be reduced based on a check-function.

:default-value {Type same as :value-type or member of :range}

The system default value of the setting. This is the value which is used as setting value if no style value exists and if no other site or corp value exists. Note, length and angle values need to be in internal units, i.e. mm and rad.

:default-style-values {List of Lists}

Defines style values for this setting. Each entry of this parameter list consists of a list with three entries:

1. Style Path - Path to a parent node on which the style is specified
2. Style keyword - Identifier of the style at the style path node
3. Value - The settings value in the specified style

The parameter list can contain any number of such style - value lists. If a specified style at the specified style path does not exist yet or if even the style path node does not exist yet, a style with a name derived from the style identifier keyword and if necessary a settings node is created on-the-fly. Therefore it is good practice to create the style path node and the style itself upfront. See sd-create-settings-style for more information.

:action {Function symbol}

Action which is called whenever the value of the setting changed either interactively by the user or triggered by a style change. The function passed here must accept one parameter and this parameter will be the new value of the setting when called.

:description {STRING}

Optional one-line description of the setting and its purpose to appear in the Description column of the Default Settings Browser.

:proposals {LIST}

Optional list of items which need to fit to :value-type. The user is not constrained to these proposals, but commonly used values could be offered as proposals. See here for more details.

:style-container {BOOLEAN}

A setting flagged as Style Container is thought to be a parent node setting to be referenced by other settings by means of the parameter :style-reference. See here for a detailed explanation of style reference settings and their purpose. A style container node and all its child nodes are invisible in the tree and can only the accessed through the Style Reference UI.

:style-reference {STRING}

Path to a setting node which is flagged as Style Container. Any given value-type is ignored for this setting and if an explicit :range specification is not given an implicit range is derived from the styles and their visibility defined at the referenced style container. Therefore an explicit range should only be specified in very rare cases.
The value of a style reference setting is the style identifier keyword as defined at the style container. The full description of how style reference settings are visualized and how to interact with these settings is described in the concepts section.

:help {STRING or LISP-Expression}

If a value for this parameter is given, a question mark appears in the Help column for this setting. If this parameter value is a string, a click on the question mark causes a lookup of a page using this string as Page-ID. If this parameter is a LISP-expression, the expression is evaluated if the question mark is clicked.

Return Value:

t - success

nil - failure

Examples:

1. A parent node with localizable title:

     (sd-def-setting "Symbol/Appearance"
                     :application "Annotation"
                     :title "Appearance")  ;; to be localized
   

2. Setting without any style values:

     (sd-def-setting "Symbol/Appearance/AbsAngle"
                     :application "Annotation"
                     :title "Abs Angle"
                     :value-type :angle
                     :default-value 0
                     :action #'(lambda (v) (format t "~%New abs angle: ~A" v))
                     :proposals `(,(/ pi 4) ,(/ pi 2))
                     :description "Absolute angle of new symbol.")
   

3. Setting with style values:

     (sd-def-setting "Symbol/Appearance/Size"
                     :application "Annotation"
                     :title "Size"
                     :value-type :length
                     :default-value 3.5
                     :default-style-values '(("Annotation" :din 5)
                                             ("Annotation" :jis 2.8)
                                             ("Annotation/Symbol/Appearance" :standard 3))
                     :action #'(lambda (v) (format t "~%New size: ~A" v))
                     :proposals '(2.5 3.5 5 7 10 14)
                     :description "Size of new symbol.")
   

4. A style container setting with two sub settings:

     (sd-def-setting "General/TextStyle"
                     :application "Annotation" 
                     ;; :title not needed because style containers are invisible
                     :style-container t)
     (sd-def-setting "General/TextStyle/Size"
                     :application "Annotation"
                     :title "Size"  ;; to appear as column header in Style Reference UI
                     :value-type :positive-length
                     :action  #'(lambda (v) (format t "~%New text size: ~S" v))
                     :proposals '(1 2 3 4 5)
                     :default-value  3.5
                     :default-style-values `(("Annotation/General/TextStyle" :standard 5)
                                             ("Annotation/General/TextStyle" :ansi ,(* 0.18 25.4))
                                             ("Annotation/General/TextStyle" :din 3.5)
                                             ("Annotation/General/TextStyle" :jis 2.5))
                     :description "Size of text")
     (sd-def-setting "General/TextStyle/Color"
                     :application "Annotation"
                     :title "Color"  ;; to appear as column header in Style Reference UI
                     :value-type :rgb-color
                     :action  '(lambda (v) (format t "~%New color: ~S" v))
                     :default-value (sd-rgb-to-color 1,1,1)
                     :default-style-values `(("Annotation/General/TextStyle" :standard ,(sd-rgb-to-color 0.0,0.625,1.0))
                                             ("Annotation/General/TextStyle" :din ,(sd-rgb-to-color 1.0,1.0,0.0)))
                     :description "Color of text")
   

5. Setting which references a style container:

     (sd-def-setting "Text/Appearance/TextStyle"
                     :application "Annotation"
                     :style-reference "Annotation/General/TextStyle"
                     :title "Text Style"
                     :action #'(lambda (v)
                                 (let ((style-values (sd-get-setting-style-values
                                                      "Annotation/General/TextStyle"
                                                      v
                                                      '("Size" "Color"))))
                                   (format t "~%Size in style ~S: ~S" v (first style-values))
                                   (format t "~%Color in style ~S: ~S" v (second style-values))))
                     :default-value :standard
                     :description "Text Style Reference")
   

SD-GET-SETTING  [function]

(sd-get-setting path)

Description:

Returns the property list of the setting specified by path.

Parameters:

path {STRING}

Full unique path of setting including application.

Return Value:

property list - success

nil - setting does not exist

Example:

  (sd-get-setting "Annotation/Symbol/Appearance/Size")
    returns:
      '(:GUI-SOURCE "System"
        :SOURCE :SD
        :VALUE 3.5
        :PROPOSALS (2.5 3.5 5 7 10 14)
        :DESCRIPTION "Size of new symbol."
        :ACTION (LAMBDA (V) (FORMAT T "~%New size: ~A" V))
        :DEFAULT-VALUE  (:SD (:STYLES (("Annotation" :DIN 5)
                                       ("Annotation" :JIS 2.8)
                                       ("Annotation/Symbol/Appearance" :STANDARD 3))
                              :DEFAULT 3.5))
        :VALUE-TYPE :LENGTH
        :TITLE "Size"
        :APPLICATION "Annotation"
        :NODE-ID 1788280)

SD-GET-SETTING-VALUE  [function]

(sd-get-setting-value path)

Description:

Returns the current value of the setting specified by path. Note, if the value-type of the setting is related to units, the value is returned in internal units (mm or rad).

Parameters:

path {STRING}

Full unique path of setting including application.

Return Value:

current-value - success

nil - setting does not exist

Example:

  ;; 1. make sure that "Standard" style is set at parent node:
  (sd-set-current-settings-style "Annotation/Symbol/Appearance" :standard)
  ;; 2. get current value:
  (sd-get-setting-value "Annotation/Symbol/Appearance/Size") 
    returns: 3

SD-SET-SETTING-VALUE  [function]

(sd-set-setting-value path 
                      :value        value
                      :level        level
                      :style-path   style-path
                      :style        style
                      :call-action  call-action
                      :update-pds   update-pds)

Description:

Assigns a default or style value at a specific level to a setting. The current value of the setting is automatically updated based on the active styles situation.

Parameters:

path {STRING}

Full unique path of setting including application.

:value {LISP object}

New default (no :style-path/:style is given) or style (:style-path/:style is given) value which relates to given level. Note, value must fit to the value-type of the setting. A potentially existing setting check-function is not executed as well.
If level is :user and no :style-path/:style is given, the new value is stored automatically according to the auto store rules.

:level {KEYWORD [:user]}

One of :user, :site, :corp or :sd. Specifies the customization level to which the value should be stored to.

:style-path {STRING}

Only valid in combination with :style.
Full path to a parent node on which a style with identifier :style is defined. Specifies that value should be stored in this style.

:style {KEYWORD}

Only valid in combination with :style-path.
Identifier of a style defined at parent node given in :style-path. Specifies that value should be stored in this style.

:call-action {BOOLEAN [t]}

Indicates whether the action of the setting should be called with the new value which is determined automatically after this function.

:update-pds {BOOLEAN [t]}

Flag to make this value assignment persistent or not.

Return Value:

value - success

nil - failure

Examples:

1. Set a new user default value (auto-stored to Standard style if active at Appearance node):

     (sd-set-setting-value "Annotation/Symbol/Appearance/Size" :value 5.5)
   

2. Set a new system (:sd) :din style value:

     (sd-set-setting-value "Annotation/Symbol/Appearance/Size"
                           :value 4.8
                           :level :sd
                           :style-path "Annotation"
                           :style :din)
   

SD-DELETE-SETTING-VALUE  [function]

(sd-delete-setting-value :path           path
                         :path-pattern   path-pattern
                         :level          level
                         :default-value  default-value
                         :styles         styles
                         :call-action    call-action
                         :update-pds     update-pds) 

Description:

Deletes one or more default or style values from one or more settings on one or more levels. If neither path nor path-pattern are given, the values of all settings which are currently accessible in your session will be deleted.
NOTE: If you delete a setting value on site, corp or sd level, the deletion of the value is for the current Modeling session only. This is because the setting values will be filled again automatically from site, corp and/or system (sd) setting files on next Creo Elements/Direct Modeling startup.

Parameters:

:path {STRING}

Full unique path of a setting including application whose value should be deleted.

:path-pattern {STRING}

A setting path with wildcard characters or regular expressions to address a number of settings which match the path-pattern. See sd-string-match-pattern-p for a full explanation of what patterns are possible.

:level {KEYWORD or list of KEYWORDS [:user]}

Specifies on which customization level the setting values should be deleted. By default just user values will be deleted.
All parameter value alternatives are:

• :user - user customization level
• :site - site customization level
• :corp - corp customization level
• :sd - system (sd) customization level
• A list of any combinations of :user, :site, :corp and/or :sd
• :all - equal to '(:user :site :corp :sd)

Deletion of site/corp/sd setting values are for the current session only. See NOTE above.

:default-value {BOOLEAN [t]}

Flag to indicate whether the default value (not style value) on the specified level(s) should be deleted or not. NOTE: The default value on :sd level can't be deleted.

:styles {t or list of style-path style pairs [t]}

Specifies which style values of the setting should be deleted.
Possible parameter values are:

• t - all style values defined for the setting will be deleted
• (list of style-path style pairs) - the value of a specific style identified by style-path string and style keyword will be deleted. This list can contain any number of such pairs.

:call-action {BOOLEAN [t]}

Indicates whether the specific setting action should be called automatically if the setting value has changed due to the removal of a setting value.

:update-pds {BOOLEAN [t]}

Indicates whether the removal of a user value should update the persistent data storage or not. If PDS is not updated, the removal is for the current session only, otherwise the removal becomes persistent. NOTE: The removal of site/corp/sd values can't be persistent, because the setting files on those levels can't be altered by the user.

Return Value:

t - at least one setting value has been deleted

nil - no value of the specified setting(s) was deleted

Examples:

1. Delete all user default and style values of all settings:

     (sd-delete-setting-value)
   

2. Delete all Annotation-Symbol-Appearance settings of user/site/corp levels to make the sd (system) defaults active again:

     (sd-delete-setting-value :path-pattern "Annotation/Symbol/Appearance/*"
                              :level '(:user :site :corp))
   

3. Delete user and system DIN and Standard style values from symbol size setting:

     (sd-delete-setting-value :path "Annotation/Symbol/Appearance/Size"
                              :level '(:user :sd)
                              :default-value nil
                              :styles '("Annotation" :din
                                        "Annotation/Symbol/Appearance" :standard))
   

SD-SET-SETTING-VALUES  [function]

(sd-set-setting-values :level        level
                       :application  application
                       :title        title
                       :style-path   style-path
                       :style        style
                       :values       values
                       :visible-if   visible-if)

Description:

Assigns default or style values to settings. Only one set of values can be defined by one call to this function. If no :style-path/:style is given, the function defines default values. If :style-path and :style are given, then values for the specified style are defined.
Note, this function is usually only called implicitely by loading xxx.lsp files automatically from the Default_Settings subdirectory within the user/site/corp/sd customization directories on startup of Creo Elements/Direct Modeling or one of its add-on modules. These files are automatically written on any interactive settings modification. See here for more information on settings persistence.
Additional note: Since this function is usually only called from customization files at startup of Creo Elements/Direct Modeling, the current setting values are not updated after a call to this function. This is done at startup time after all default setting definition files are loaded to optimize performance. In case you manually want to call this function, you need to make sure that the current values of all affected settings are updated. Use sd-update-current-setting-values to do so.

Parameters:

:level {KEYWORD}

Usually implicitly given if call was initiated from a Default_Settings/*.lsp file automatically loaded from user/site/corp/sd customization directories on startup of Creo Elements/Direct Modeling.
If called explicitly this can be one of :user, :site, :corp or :sd.

:application {STRING}

Name of a valid Creo Elements/Direct Modeling application to which the settings, whose values should be set, belong to.

:title {STRING}

Title of style if style does not exist yet and will be created on-the-fly.

:style-path {STRING}

Full path (including application) to a parent node at which style with identifier :style is defined or will be defined on-the-fly (see :title parameter).

:style {KEYWORD}

Identifier of a style defined at the parent node given by :style-path. If style does not exist yet, it will be created on-the-fly (see :title parameter).

:values {LIST of setting-sub-path and value pairs}

List of relative setting path strings and setting value pairs. For default values, the relative setting path is the full path to the setting without the first application path portion.
For style values the relative setting path is the full path to the setting without the style path as given in :style-path. Therefore it is only possible to fill settings located underneath of :style-path with values.
If the setting with the composed path does not exist (yet), the data given by this function is stored, but a tree node is not created yet. A tree node is only created by sd-def-setting.
The given setting values must fit to the setting value types and a probably given check-function is not executed as well.

:visible-if {KEYWORD, LIST of KEYWORDS, (not KEYWORD), (not LIST of KEYWORDS}

Only valid in combination with :style-path and :style.
Controls the visibility of the style which is created on-the-fly if needed. See sd-create-settings-style for more information.

Return Value:

t - success

nil - failure

Examples:

1. Set default user values:

     (sd-set-setting-values :application "Annotation"
                            :level :user
                            :values `("Symbol/Appearance/Size" 5
                                      "Symbol/Appearance/Adjust" :bottom_left
                                      "General/TextStyle/Color" ,(sd-rgb-to-color 0,0,1)))
   

2. Fill existing style with user values:

     (sd-set-setting-values :application "Annotation"
                            :level :user
                            :title "Standard"
                            :style-path "Annotation/Symbol/Appearance"
                            :style :standard
                            :values `("AbsAngle" ,(sd-deg-to-rad 5)
                                      "Size" 10))  
   

3. Create a new on-the-fly text style (site level) which is only visible if JIS is active at root:

     (sd-set-setting-values :application "Annotation"
                            :level :site
                            :title "Site Text Style"
                            :style-path "Annotation/General/TextStyle"
                            :style :site_style
                            :visible-if :jis
                            :values `("Size" 4.2
                                      "Color" ,(sd-rgb-to-color 1,0,1)))   
   

SD-UPDATE-CURRENT-SETTING-VALUES  [function]

(sd-update-current-setting-values :subpath      subpath
                                  :call-action  call-action)

Description:

This function causes a forced update of all setting values underneath the parent node given by subpath. Usually this update takes place automatically but if you use sd-set-setting-values to fill multiple style values manually (without going through the Default_Settings/xxx.lsp customization files), you need to make sure that the current setting values are updated correctly by calling this function.

Parameters:

:subpath {STRING}

Path to a parent node. If given, all current setting values underneath this node are updated. If not given, all setting values are updated.

:call-action {BOOLEAN [t]}

Indicates whether the specific setting action should be called automatically if the setting value has changed due to this forced update.

Return Value:

t - always

Example:

Make sure that style values set by sd-set-setting-values update the affected settings correctly:

  (sd-set-setting-values :application "Annotation"
                         :level :user
                         :title "Standard"
                         :style-path "Annotation/Symbol/Appearance"
                         :style :standard
                         :values `("AbsAngle" ,(sd-deg-to-rad 5)
                                   "Size" 10))

  (sd-update-current-setting-values :subpath "Annotation/Symbol/Appearance")

SD-FREEZE-SETTING-VALUE  [function]

(sd-freeze-setting-value :path          path
                         :path-pattern  path-pattern
                         :subpath       subpath)

Description:

Freezes the values (default, style, user, site, corp, system) of one or more settings and/or styles of one or more parent nodes. If neither path, path-pattern nor subpath is given, the values and styles of all settings are frozen.
Use this function to remember the values of certain settings at a specific time. After that you can modify setting values or styles freely and you can return to the frozen setting values and styles via sd-unfreeze-setting-value to undo the changes you did to the setting values and styles after the freeze time.

Parameters:

:path {STRING}

Full unique path (including application) to a specific setting or parent node whose values or style should be remembered.

:path-pattern {STRING}

A setting path with wildcard characters or regular expressions to address a number of settings or parent nodes which match the path-pattern. See sd-string-match-pattern-p for a full explanation of what patterns are possible.

:subpath {STRING}

Path to a parent node to address all settings and parent nodes underneath this node. Note, the node specified by this parameter will not be included.

Return Value:

t - success

nil - failure

Example:

1. Freeze the values of one specific setting:

     (sd-freeze-setting-value :path "Annotation/Symbol/Appearance/Size")
   

2. Freeze all symbol appearance settings including its active style:

     (sd-freeze-setting-value :path-pattern "Annotation/Symbol/Appearance*")
   

3. Freeze all setting values and styles:

     (sd-freeze-setting-value)
   

SD-UNFREEZE-SETTING-VALUE  [function]

(sd-unfreeze-setting-value :path          path
                           :path-pattern  path-pattern
                           :subpath       subpath)

Description:

Restores (unfreezes) the values (default, style, user, site, corp, system) of one or more settings and/or styles of one or more parent nodes as frozen via a call to sd-freeze-setting-value. If neither path, path-pattern nor subpath is given, the values and styles of all settings are unfrozen.
Use this function to undo any setting value or style changes you did since a call to sd-freeze-setting-value.
Note: Calls to sd-freeze-setting-value and sd-unfreeze-setting-value should always be synchronized, i.e. pairwise calls should be called with the same parameters.

Parameters:

:path {STRING}

Full unique path (including application) to a specific setting or parent node whose values or style should be restored.

:path-pattern {STRING}

A setting path with wildcard characters or regular expressions to address a number of settings or parent nodes which match the path-pattern. See sd-string-match-pattern-p for a full explanation of what patterns are possible.

:subpath {STRING}

Path to a parent node to address all settings and parent nodes underneath this node. Note, the node specified by this parameter will not be included.

Return Value:

t - success

nil - failure

Example:

1. Unfreeze the values of one specific setting:

     (sd-unfreeze-setting-value :path "Annotation/Symbol/Appearance/Size")
   

2. Unfreeze all symbol appearance settings including its active style:

     (sd-unfreeze-setting-value :path-pattern "Annotation/Symbol/Appearance*")
   

3. Unfreeze all setting values and styles:

     (sd-unfreeze-setting-value)
   

SD-SET-SETTING-MODIFIABLE-FLAG  [function]

(sd-set-setting-modifiable-flag :path          path
                                :path-pattern  path-pattern
                                :subpath       subpath
                                :modifiable    modifiable)

Description:

Allows to secure a specific setting or multiple settings from interactive user modification. The user is allowed to see the current setting value, but he cannot modify the value in an interactive way. To set the modifiable flag of all settings, don't specify path, path-pattern or subpath.

Parameters:

:path {STRING}

Full unique path (including application) to a specific setting which should be secured against modification.

:path-pattern {STRING}

A setting path with wildcard characters or regular expressions to address a number of settings which match the path-pattern. See sd-string-match-pattern-p for a full explanation of what patterns are possible.

:subpath {STRING}

Path to a parent node. If given, all settings underneath this node are specified.

:modifiable {BOOLEAN [t]}

Set this parameter to nil to secure the specified setting(s) against modification. Set this parameter to t to allow user modification at runtime again (default).

Return Value:

t - success

nil - failure

Example:

1. Secure one specific setting:

     (sd-set-setting-modifiable-flag :path "Annotation/Symbol/Appearance/Size"
                                     :modifiable nil)
   

2. Disallow modification of all symbol appearance settings:

     (sd-set-setting-modifiable-flag :subpath "Annotation/Symbol/Appearance"
                                     :modifiable nil)
   

3. Allow interactive modification of all settings:

     (sd-set-setting-modifiable-flag)
   

SD-FINALIZE-APPLICATION-SETTINGS  [function]

(sd-finalize-application-settings application)

Description:

Call this function to remove all application specific settings from the Default Settings Browser on deactivation of application. If you don't call this function, all application specific settings will still be visible in the Default Settings Browser although the application is not active anymore.
All necessary bookkeeping actions (like PDS) are performed automatically.

Parameters:

application {STRING} - Name of application as given in sd-def-setting

Return Value:

t - success

nil - failure

Example:

(sd-unsubscribe-event (sd-module-deactivation-event "ANNOTATION")
                      'finalize-Annotation-settings-on-deactivation)

(defun finalize-Annotation-settings-on-deactivation (&rest args)
  (declare (ignore args))
  (sd-finalize-application-settings "Annotation"))

(sd-subscribe-event (sd-module-deactivation-event "ANNOTATION")
                    'finalize-Annotation-settings-on-deactivation)

SD-FORCE-STORE-APPLICATION-SETTINGS  [function]

(sd-force-store-application-settings application)

Description:

Usually on deactivation of a module (e.g. Annotation) or latest on exit of Creo Elements/Direct Modeling one or more default setting files of settings which were modified by the user are written automatically to a Default_Settings subdirectory within the application specific customization subdirectory in your personal customization directory.
If you want to force a write of these files without deactivating this application, call this function.

Parameters:

application {STRING} - Name of application as given in sd-def-setting

Return Value:

t - success

nil - failure

Example:

(sd-force-store-application-settings "Annotation")

SD-FORCE-RELOAD-APPLICATION-SETTINGS  [function]

(sd-force-reload-application-settings application)

Description:

Usually on activation of a module (e.g. Annotation) all module specific setting values are automatically loaded from corp, site and user files.
If you want to refresh the settings of a specific application by reloading all corp, site and user setting files of this application, call this function.

Parameters:

application {STRING} - Name of application as given in sd-def-setting

Return Value:

t - success

nil - failure

Example:

(sd-force-reload-application-settings "Annotation")

SD-CREATE-SETTINGS-STYLE  [function]

(sd-create-settings-style style-path style
                          :title       title
                          :secured     secured
                          :visible-if  visible-if)

Description:

Creates a new style with identifier style at the specified settings parent node (style-path).
Styles can only be created on parent nodes where styles are defined by Creo Elements/Direct Modeling already or on style container nodes. The new style may be a secured style and/or may be of restricted visibility based on the active style at the root node.
Usually there is no need to explicitly call this function because styles are implicitly created by loading style setting files from user/site/corp/sd customization directories on startup of Creo Elements/Direct Modeling or one of its modules.

Parameters:

style-path {STRING}

Full unique path of setting parent node including application.

style {KEYWORD}

Unique identifier of the new style at the specified node.

:title {STRING}

Optional title of the new style. If this parameter is not given, a title is automatically generated from the style identifier.
If a style with the same identifier at the same parent node exists already and this parameter is given, the title of the existing style will be replaced by this title.

:secured {BOOLEAN}

Set this parameter to T to disallow deletion of this style. I.e. even a (sd-delete-settings-style ... :forced t) will not delete a secured style.

:visible-if {KEYWORD, LIST of KEYWORDS, (not KEYWORD), (not LIST of KEYWORDS}

Restricts the visibility of the new style based on the active style at the application root node. This parameter has no effect if you create a new root style.
The parameter can be one of:

• KEYWORD
  A simple style identifier keyword (styles defined at root node) like :din or :ansi
• LIST of KEYWORDS
  A list of style identifier keywords like '(:din :iso)
• (not KEYWORD)
  A list starting with NOT followed by a root style identifier. The meaning of this is that the new style will be visible in all styles but the given style after NOT. Example: '(not :ansi)
• (not LIST of KEYWORDS}
  The new style should not be visible if one of the given root styles is active. Example: '(not (:din :jis))

Return Value:

count - number of styles defined at style-path

Examples:

1. A new root node style:

     (sd-create-settings-style "Annotation" :my_din :title "My DIN")
   

2. A new text style which is only visible in DIN and My DIN:

     (sd-create-settings-style "Annotation/General/TextStyle" :din_text_style
                               :title "DIN Text Style"
                               :visible-if '(:din :my_din))
   

3. Try to create a style on a node where creation is not allowed:

     (sd-create-settings-style "Annotation/Text/Appearance"
                               :text_style :title "Text Style")
       => nil
   

SD-DELETE-SETTINGS-STYLE  [function]

(sd-delete-settings-style style-path style
                          :forced                 forced
                          :update-setting-values  update-setting-values)

Description:

Deletes a specific style and all its user style value definition files of all applications. If forced is not given, the deletion of a style is only possible if just user style values exist. Otherwise the style would reappear on the next startup of Creo Elements/Direct Modeling.
Note, a secured style can't even be deleted with forced set to t. See sd-create-settings-style for more details.

Parameters:

style-path {STRING}

Full unique path of setting parent node including application.

style {KEYWORD}

Identifier of the style at the specified node.

:forced {BOOLEAN}

Set this parameter to t if you want the style to be deleted in any case (potentially for this Modeling session only because it may reappear in the next session if site/corp or sd setting files exist which define setting values for this style).

:update-setting-values {BOOLEAN [t]}

If this parameter is given, all settings which may be influenced by the deletion of this style, update their current values automatically.

Return Value:

t - success

nil - failure

Examples:

  (sd-delete-settings-style "Annotation/General/TextStyle" :site_style)  => nil
  (sd-delete-settings-style "Annotation/General/TextStyle" :site_style :forced t)  => t

SD-DELETE-ALL-SETTINGS-STYLES  [function]

(sd-delete-all-settings-styles style-path
                               :forced         forced
                               :incl-children  incl-children)

Description:

Deletes all styles at a specific parent node and optionally at subnodes as well. If forced is not given, just user styles (styles with just user values defined) will be deleted. For more information see sd-delete-settings-style.

Parameters:

style-path {STRING}

Full unique path of setting parent node including application.

:forced {BOOLEAN}

Set this parameter to t if you want all styles to be deleted in any case (potentially for this Modeling session only because some may reappear in the next session if site/corp or sd setting files exist which define setting values for styles).

:incl-children {BOOLEAN}

If this parameter is set to T, all styles defined at subnodes of style-path will be deleted as well.

Return Value:

t - at least one style was deleted successfully

nil - no style could be deleted

Example:

Delete all user styles of Annotation application:

  (sd-delete-all-settings-styles "Annotation" :incl-children t)

SD-SET-CURRENT-SETTINGS-STYLE  [function]

(sd-set-current-settings-style style-path style
                               :update-pds             update-pds
                               :update-setting-values  update-setting-values)

Description:

Sets a specific style at a parent node active or resets a style.

Parameters:

style-path {STRING}

Unique path (including application) to a node with styles.

style {KEYWORD or NIL}

Identifier of a style at style-path. If this parameter is NIL or :no_style, any style at style-path is switched off, i.e. no style is active after this call.
NOTE: Some parent nodes (e.g. "Annotation") force a style to be active all the time. Therefore switching off the active style at this node will fail.

:update-pds {BOOLEAN [t]}

Flag to indicate whether this change is persistent or not.

:update-setting-values {BOOLEAN [t]}

If this parameter is given, all settings which may be influenced by the activation of this style (deactivation of current style), update their current values automatically.

Return Value:

style - if style could be activated

nil - failure or no active style

Example:

  (sd-set-current-settings-style "Annotation" :din)

SD-GET-CURRENT-SETTINGS-STYLE  [function]

(sd-get-current-settings-style style-path)

Description:

Returns the currently active style at node specified by style-path.

Parameters:

style-path {STRING}

Unique path (including application) to a node with styles.

Return Value:

style - identifier keyword of active style

nil - no style active or failure

Example:

  (sd-get-current-settings-style "Annotation")  => :din

SD-RESET-CURRENT-SETTINGS-STYLES  [function]

(sd-reset-current-settings-styles :update-pds update-pds)

Description:

Resets all currently active styles on all nodes with styles.

Parameters:

:update-pds {BOOLEAN [t]}

Indicates whether this change should be persistent or not.

Return Value:

(values) - always

Example:

  (sd-reset-current-settings-styles)

SD-GET-SETTING-STYLE-VALUES  [function]

(sd-get-setting-style-values style-path style settings-list)

Description:

Call this function to retrieve the values of sub settings of a style container within a specific style.
See sd-def-setting for more information about style containers.

Parameters:

style-path {STRING}

Unique path (including application) to a node with serves as style container.

style {KEYWORD}

Identifier of a style at the style-path node in which the subsetting values should be returned. Note, this style does not need to be active at this node.

settings-list {LIST of STRINGS}

List of relative setting paths (subsettings) underneath the node given by style-path. The result list of this function will contain the style value of each setting composed out of style-path/settings-list-entry.

Return Value:

multiple values

1. List of setting values (same order as in settings-list) in specified style
2. Flag to indicate whether values are user values or not. nil means, no value is a user value, t means, at least one is a user value and :all means, all returned values are user values

nil - failure

Examples:

1. Get current :ansi text style values:

     (multiple-value-bind (results user-flag)
       (sd-get-setting-style-values "Annotation/General/TextStyle" :ansi '("Size" "Color")))
         => results   = '(4.572 255)
            user-flag = t
   

2. Set user values for :din style and get values afterwards:

     (sd-set-setting-value "Annotation/General/TextStyle/Size"
                           :style-path "Annotation/General/TextStyle"
                           :style :din
                           :value 5.55)
     (sd-set-setting-value "Annotation/General/TextStyle/Color"
                           :style-path "Annotation/General/TextStyle"
                           :style :din
                           :value (sd-rgb-to-color 1,0,0))
     (multiple-value-bind (results user-flag)
       (sd-get-setting-style-values "Annotation/General/TextStyle" :din '("Size" "Color")))
         => results   = '(5.55 16711680)
            user-flag = :all
   

3. Reset all :din style user values and get values afterwards:

     (sd-delete-setting-value :path-pattern "Annotation/General/TextStyle/*"
                              :default-value nil
                              :styles '("Annotation/General/TextStyle" :din))
     (multiple-value-bind (results user-flag)
       (sd-get-setting-style-values "Annotation/General/TextStyle" :din '("Size" "Color")))
         => results   = '(3.5 16776960)
            user-flag = nil
   

4. See fifth example of sd-def-setting too.

SD-GET-SETTING-STYLES-RANGE-LIST  [function]

(sd-get-setting-styles-range-list path)

Description:

Returns a list of all visible styles a the node specified by path in a format so that this list can be used by a dialog generator range variable.

Parameters:

path {STRING}

Unique path (including application) to a node whose visible styles should be inquired.

Return Value:

list - a list of (:keyword :label "Label") lists with all visible styles

nil - failure or no styles available

Examples:

  (sd-get-setting-styles-range-list "Annotation")
    => '((:ansi :label "ASME") (:din :label "DIN") (:iso :label "ISO")
         (:jis :label "JIS"))

  (sd-get-setting-styles-range-list "Annotation/General/TextStyle")
    => '((:large-inch :label "Large (inch)") (:medium-inch :label "Medium (inch)")
         (:small-inch :label "Small (inch)") (:standard :label "Standard"))

SD-DO-ON-ALL-SETTINGS  [function]

(sd-do-on-all-settings function :path-pattern path-pattern)

Description:

Generic function to iterate through all settings and parent nodes to call a user-defined function. The settings for which the function should be called can be restricted by passing a path-pattern.
Note: The order in which function is called is undefined.

Parameters:

function {LISP function symbol}

Function to be called for each setting. This function has to accept two parameters. On iteration the first parameter will be the unique settings path including application and the second parameter will contain the settings data as returned by sd-get-setting.

:path-pattern {STRING}

If not given, function will be called for all settings and parent nodes. If this parameter is given, it can be a settings path with wildcard characters or regular expressions to restrict the number of settings to the ones which match the path-pattern. See sd-string-match-pattern-p for a full explanation of what patterns are possible.

Return Value:

t - success

nil - failure

Example:

  (defun count-size-settings ()
    (let ((count 0))
      (sd-do-on-all-settings #'(lambda (path data)
                                 (declare (ignore path data))
                                 (incf count))
                             :path-pattern "*/Size")
      count))

SD-SHOW-SETTING  [function]

(sd-show-setting path
                 :select-item     select-item
                 :scroll-visible  scroll-visible
                 :expand          expand
                 :collapse        collapse
                 :expand-all      expand-all
                 :collapse-all    collapse-all
                 :collapse-other  collapse-other
                 :show-browser    show-browser)

Description:

Shows a specific setting in the Default Settings Browser and controls how other setting branches should behave.

Parameters:

path {STRING}

Unique path (including application) of a setting which should become visible in the Default Settings Browser.

:select-item {BOOLEAN [t]}

Select settings entry row in the browser or not.

:scroll-visible {BOOLEAN [t]}

If manual scrolling would be required to make the setting visible in the browser, do this automatically to guarantee that the setting is in the visible part of a ll settings.

:expand {BOOLEAN}

If the setting given by path is a parent node and this parameter is t, expand this parent node. Same as if you would click the + icon in front of the parent node setting. Child nodes are not expanded.

:collapse {BOOLEAN}

If the setting given by path is a parent node and this parameter is t, collapse this parent node. Same as if you would click the - icon in front of the parent node setting. Child nodes are not collapsed, i.e. they maintain their state when this node is expanded the next time.

:expand-all {BOOLEAN [t]}

Recursively expands this parent node and all child nodes.

:collapse-all {BOOLEAN}

Recursively collapses this parent node and all child nodes.

:collapse-other {BOOLEAN}

Useful in combination with :expand or :expand-all. Tells to collapse all other parent nodes except the one given in path and its child nodes. Setting this parameter to t is useful to show just the branch and child nodes of the specified setting by collapsing all other nodes to keep the tree as small as possible.

:show-browser {BOOLEAN [t]}

Show the Default Settings Browser if it is not visible yet.

Return Value:

t - success

nil - failure

Examples:

  (sd-show-setting "Annotation/Text")

  (sd-show-setting "Annotation/Symbol" :collapse-other t)