User:Jcreer/SMS:DMI Widgets and Dialogs Elements

From XMS Wiki
Jump to navigationJump to search


Elements

Element <check_box>
Info Widget that displays text that is checked/unchecked.
Versions 1, 2
Attributes none
Children text, default, unique_name, dependency, export_text_checked, export_text_unchecked, text_style
Used by item
Example
<check_box>                       	
   <text>Calculate Sediment Transport</text>
   <default>checked</default>
   <unique_name>togCalcSedimentTransport</unique_name>
   <export_text_checked>ON</export_text_checked>
   <export_text_unchecked>OFF</export_text_unchecked>
   <dependency>…</dependency>…
</ check_box >
Element <combo_box>
Info

Widget that displays list of options. Only 1 can be selected. If no default is specified and the optional tag is present, then an empty option will be added to the combo box. If there is no default tag, and no optional tag, then the first item will be default.

In version 2, if a combo box has display_options_arc, and is part of a dialog that is used as an arc attribute, then a limited set of display options will appear for the options of the combo box. The display option for each option of the combo box will only be line thickness and color. The display option is NOT saved at any point and will be reset every time SMS is opened.

Versions 1, 2
Attributes none
Children option, unique_name, optional, dependency, text_style, display_options_arc
Used by item, row, column
Example Creates a combo box with hours, minutes and seconds. Hours is the default item.
<combo_box>
   <unique_name>cbxTransportUnits</unique_name>                	
   <option>
      <text>hours</text>
      <default></default>
   </option>
   <option>
      <text>minutes</text>
	</option>
	<option>
      <text>seconds</text>
   </option>
   <dependency>…</dependency>…
</ combo_box >
Element <contains>
Info Holds all the groups and items of a group.
Versions 2
Attributes none
Children group, item
Used by group
Example
Element <control_curve>
Info Displays an curve push button. When pushed the xy curve values can be updated and a curve is displayed.
Versions 2
Attributes none
Children max_rows, flags, x_column, y_column, unique_name, dependency
Used by item, row, column
Example This example creates a curve limited to 10 rows.
<item>
   <control_curve>
       <unique_name>myCurve1</unique_name>
       <max_rows>10</max_rows>
       <flags>XY_USEDATE</flags>
       <x_column>
          <text>Time
       </x_column>
       <y_column>
  	<text>Velocity</text>   
       </y_column>	
   </control_curve>
  …
Element <control_dataset>
Info

Displays an edit box, and push buttons for select, delete and create. Once selected, the dataset string is placed into the edit box. <dataset_type> can be scalar or vector. Possible keyword outputs are file_name (which is the name of the dataset without path), geom_name, and file_path (full path c:\somewhere) and sms_path.

Versions 1 (<custom_control_XXXX>), 2
Attributes none
Children push_button, dataset_type, unique_name, dependency, default, dataset_name, text_style, use_parameter
Used by item, row, column
Example This example creates the custom control with only the select and delete buttons.
<item>
    <control_dataset>
        <push_button>select<push_button>
        <push_button>delete</push_button>
        <dataset_type>scalar</dataset_type>
    </control_dataset>
Element <control_date>
Info Displays date and time selector, where a date can be selected. Possible output is value, which will be the date formatted as specified in SMS preferences. Possible outputs are year, month, day, hour, minute, second.

Keywords:

  • #DAY_DIGIT
  • #DAY_DIGIT_ZERO
  • #DAYS_IN_YEAR
  • #DAY_SHORT_NAME
  • #DAY_LONG_NAME
  • #MONTH_DIGIT
  • #MONTH_DIGIT_ZERO
  • #MONTH_SHORT_NAME
  • #MONTH_LONG_NAME
  • #YEAR_2
  • #YEAR_4
  • #HOUR
  • #HOUR_ZERO
  • #HOUR_24
  • #HOUR_24_ZERO
  • #MINUTE
  • #MINUTE_ZERO
  • #SECOND
  • #SECOND_ZERO
  • #AM_PM
  • #AM_PM_CAPS
Versions 1 (<custom_control_XXXX>), 2
Attributes none
Children unique_name, dependency, default, text_style
Used by item, row, column
Example
<item>
   <text>Start date</text>
   <control_date>
       <unique_name>edtDate</unique_name>
   </control_date>
   <card>
       <card_name>DATE</card_name>
       <export_format>"%s Day:%s Month:%s Year:%s Hour:%s Minute%s 
       Second:%s\n", #card_name, edtDate#DAY_DIGIT, 
       edtDate#MONTH_LONG_NAME, edtDate#YEAR_4, edtDate#HOUR_24, 
       edtDate#MINUTE_ZERO, edtDate#SECOND_ZERO</export_format>
   </card>
</item>
Element <control_density>
Info Displays an edit box and combo box. Combo box can contain kg/m^3, gr/cm^3, lb/ft^3. Possible outputs are value and units.

Keywords:

  • #MPV_MG_PER_L
  • #MPV_G_PER_L
  • #MPV_KG_PER_CU_M
  • #MPV_G_PER_CU_CM
  • #MPV_LB_PER_CU_FT
Versions 1 (<custom_control_XXXX>), 2
Attributes none
Children option, unique_name, dependency, range, default, text_style
Used by item, row, column
Example

Displays kg/m^3 and lb/ft^3 in combo box. If kg/m^3 selected and exported, returns the text “kg m”.

<item>
   <text>Density </text>
   <control_density>
       <option>
          <text>kg/m^3</text>
          <export_text>kg m</export_text>
          <unit_keyword>#MPV_KG_PER_CU_M</unit_keyword>
       </option>
       <option>
          <text>lb_ft^3</text>
          <export_text>lbs ft</export_text>
          <unit_keyword>#MPV_LB_PER_CU_FT</unit_keyword>
        </option>
    </control_density>
 …
Element <control_duration>
Info Displays an edit box and combo box. Combo box contains days, hours, minutes, seconds. Possible outputs are value and units.

Keywords:

  • #TIME_SECONDS
  • #TIME_MINUTES
  • #TIME_HOURS
  • #TIME_DAYS
  • #TIME_WEEKS
  • #TIME_YEARS
Versions 1 (<custom_control_XXXX>), 2
Attributes none
Children option, unique_name, dependency, range, default, text_style
Used by item, row, column
Example Displays only minutes and hours in combo box. If hours selected and exported, returns the text “hrs”.
<item>
   <text>Transport Time Step</text>
   <control_duration>
       <option>
          <text>minutes</text>
          <export_text>min</export_text>
          <unit_keyword>#TIME_MINUTES</unit_keyword>
       </option>
       <option>
          <text>hours</text>
          <export_text>hrs</export_text>
          <unit_keyword>#TIME_HOURS</unit_keyword>
          <default></default>
       </option>
   </control_duration>
 …
Element <control_file_opener>
Info

Push button that opens a file open dialog to select files. Possible outputs are file_path.

Versions 1 (<custom_control_XXXX>), 2
Attributes none
Children filter, create_file, unique_name, dependency, default, text_style
Used by item, row, column
Example Opens a file dialog, filtering on files with *.h5 and *.cmcards extensions
<item>
   <text>File:</text>
   <control_file_opener>
    	<filter>Cmcards file (.cmcards)</filter> 
    </control_file_opener>
…
Element <control_length>
Info Displays an edit box and combo box. Combo box can contain meters, cm, mm, um, ft, in. Possible outputs are value and units.

Keywords:

  • #LEN_MM
  • #LEN_CM
  • #LEN_M
  • #LEN_KM
  • #LEN_INCH
  • #LEN_FT
  • #LEN_YD
  • #LEN_MILE
  • #LEN_UM
Versions 1 (<custom_control_XXXX>), 2
Attributes none
Children option, unique_name, dependency, range, default, text_style
Used by item, row, column
Example Displays only cm, and mm in combo box. If cm selected and exported, returns the text “centimeter”.
<item>
   <text>Length</text>
   <control_length>
       <option>
          <text>cm</text>
          <export_text>centimeter</export_text>
          <unit_keyword>#LEN_CM</unit_keyword>
       </option>
       <option>
          <text>mm</text>
          <export_text>mm</export_text>
          <unit_keyword>#LEN_MM</unit_keyword>
          <default></default>
        </option>
    </control_length>
Element <control_velocity>
Info Displays an edit box and combo box. Combo box can contain m/sec, m/min, m/hours, etc.... Also could be m/sec, cm/sec, ft/sec, etc... The option tag specifies which options are displayed. The edit box will display doubles, within the given range, if provided. Possible outputs are value and units.

Keywords:

  • #VEL_M_PER_S
  • #VEL_KM_PER_H
  • #VEL_FT_PER_S
  • #VEL_MPH
  • #VEL_KNOTS
  • #VEL_CM_PER_S
  • #VEL_MM_PER_S
Versions 1 (<custom_control_XXXX>), 2
Attributes none
Children option, unique_name, dependency, range, default, text_style
Used by item, row, column
Example Displays m/sec and cm/sec in combo box. If m/sec selected and exported, returns the text “m sec”.
<item>
   <text>Velocity </text>
   <control_velocity>
       <unique_name>ccVelocity</unique_name>
       <range>0-100</range>
       <option>
          <text>m/sec</text>
          <export_text>m sec</export_text>
          <unit_keyword>#VEL_M_PER_S</unit_keyword>
       </option>
       <option>
          <text>cm/sec</text>
          <export_text>cm sec</export_text>
          <unit_keyword>#VEL_CM_PER_S</unit_keyword>
        </option>
    </control_velocity>
 …
Element <control_volume_flow>
Info Displays an edit box and combo box. Combo box can contain m^3/sec, m^3/min, m^3/hours, etc.... Also could be m^3/sec, cm^3/sec, ft^3/sec, etc... The option tag specifies which options are displayed. The edit box will display doubles, within the given range, if provided. Possible outputs are value and units.
Versions 2
Attributes none
Children option, unique_name, dependency, range, default, text_style
Used by item, row, column
Example Displays m^3/sec and cm^3/sec in combo box. If m^3/sec selected and exported, returns the text “m^3 sec”.
<item>
   <text>Volume flow</text>
   <control_volume_flow>
       <unique_name>ccVolumeFlow</unique_name>
       <range>0-100</range>
       <option>
          <text>m^3/sec</text>
          <export_text>m^3 sec</export_text>
          <unit_keyword>#VFLOW_CU_M_PER_SEC</unit_keyword>
       </option>
       <option>
          <text>cm^3/sec</text>
          <export_text>cm^3 sec</export_text>
          <unit_keyword>#VFLOW_CU_CM_PER_SEC</unit_keyword>
        </option>
    </control_volume_flow>
 …
Element <dataset_name>
Info Determines the name of the dataset to be created. Uses the standard printf and sprintf format (www.cplusplus.com/reference/clibrary/cstdio/printf/). The keywords #row_number, #column_number, #row_name, and #column_name are used when the dataset is in a table.
Versions 1, 2
Attributes none
Children none
Used by control_dataset
Example
<control_dataset>                           
    <dataset_name>”Five percent Layer %d”, #row_number</dataset_name>
	…
</control_dataset>
Element <dataset_type>
Info Determines if the dataset is scalar or vector.
Versions 1, 2
Attributes none
Children none
Used by control_dataset
Example
<control_dataset>                           
    <dataset_type>scalar</dataset_type>
	…
</control_dataset>
Element <default>
Info Sets the initial default value of a widget. Can also be used to state the default combo-box option.
Versions 1, 2
Attributes none
Children none
Used by edit_box, check_box, option, any element that begins with “custom_control”
Example 1
<edit_box>                       	
    <default>1.5</default>
</edit_box >
Example 2 Check box is checked
<check_box>                       	
    <default>checked</default>
</check_box >
Example 3 Check box isn’t checked
<check_box>                   	    
    <default>unchecked</default>
</check_box >
Example 4 Combo box hours is default
<combo_box>
   <option>
      <text>minutes</text>
   </option>
   <option>
      <text>hours</text>
      <default></default>
   </option>
Example 5 Custom control date always has a date formatted as “day-month-year hour:minute:second”.
<control_date>
    <default>16-7-2010 14:45:32</default>
</control_date>


Element <dialog>
Info Used to define a dialog.
Versions 2
Attributes none
Children dialog_name, page
Used by dialogs
Example
Element <dialog_name>
Info Specifies the name of a dialog. This is required. This name is used by link_to.
Versions 2
Attributes none
Children none
Used by dialog
Example
Element <dialogs>
Info Contains all the dialogs used in a model.
Versions 2
Attributes none
Children dialog
Used by model
Example
Element <display_options_arc>
Info Specifies that the options in the combo box are to be used as arc/nodestring boundary condition display options. This element should only be used once in the schema.
Versions 2
Attributes none
Children none
Used by combo_box
Example
Element <flags>
Info Flags are optional, and are used to modify the behavior/appearance of the control_curve. Only 1 flag is currently defined: XY_USEDATE. When this flag is set, the x column becomes a date/time calendar.
Versions 2
Attributes none
Children none
Used by control_curve
Example This example creates a curve button with the date/time flag.
<item>
    <control_curve>
        <unique_name>myCurve1</unique_name>
        <flags>XY_USEDATE</flags>
        <x_column>
           <text>Time
        </x_column>
        <y_column>
   	<text>Velocity</text>   
        </y_column>	
    </control_curve>
  …
Element <group>
Info Tree group item that contains one or more items or groups.
Versions 1, 2
Attributes none
Children text, dependency, text_style, contains
Used by page_def, contains
Example
<group>
   <text> Timing </text>
   <item>
  	… tree item stuff
   </item>
</group>
Element <item>
Info Tree item contains one or more widgets (combo_box, text_box, edit_box, etc). A tree item can contain multiple cards (version 1), but those cards must be mutually exclusive.
Versions 1, 2
Attributes none
Children text, card, dependency, text_box, edit_box, check_box, combo_box, table, any element starting with “custom_control”, text_style
Used by group
Example
<item>
     <text>Transport Time Step</text>
     <edit_box>…. </edit_box>
     <card>…</card>
Element <max_rows>
Info Optional element used to limit the number of rows the user can specify in a SMS:Dynamic Model Interface Schema#Element <control_curve>control_curve. If this element is not used, the max_rows is unlimited.
Versions 2
Attributes none
Children none
Used by control_curve
Example This example creates a curve button with the date/time flag.
<item>
    <control_curve>
        <unique_name>myCurve1</unique_name>
        <max_rows>10</max_rows>
        <x_column>
           <text>Time
        </x_column>
        <y_column>
     	   <text>Velocity</text>  
        </y_column>	
    </control_curve>
  …
Element <new_line>
Info Creates a new line before adding the next widget in a tree item.
Versions 1, 2
Attributes none
Children none
Used by item
Example In the dialog there would be:
    Breaking Efficency:   [edit box]        (new_line called)
    Friction Efficency:


<item>
    <text>Non-cohesive bedload entrainment</text>
         <text_box>
            <text>Breaking Efficency:</text>
         </text_box>
         <edit_box>
            <unique_name>edtBreakingEff</unique_name>
         </edit_box>
         <new_line></new_line>
         <text_box>
            <text>Friction Efficency:</text>
         </text_box>
Element <optional>
Info Placed inside widgets to suppress a warning message from being displayed if the widgets data is empty. By default, data associated with a widget is required. If the <optional> tag is included and the widget’s data is empty, a warning message won’t be displayed.
Versions 1, 2
Attributes none
Children none
Used by text_box, combo_box, edit_box, table, any element that starts with “custom_control”, check_box
Example
<optional></optional>
Element <range>
Info Determines the range of acceptable values in an edit_box. Can use the keywords GREATER_THAN, GREATER_THAN_EQUALS, LESS_THAN and LESS_THAN_EQUALS. Numbers assumed inclusive unless otherwise specified.
Versions 1, 2
Attributes none
Children none
Used by edit_box, any element that starts with “control” except control_file_opener, control_dataset and control_date
Example 1
<edit_box>                       	
    <range>0-1</range>
</ edit_box >
Example 2
<range>0 – 5.6546</range>
Example 3
<range>GREATER_THAN 0</range>
Example 4
<range>GREATER_THAN 0.0 - LESS_THAN 5.0</range>
Example 5 Both examples are equivalent
<range>0.0 - LESS_THAN 5.0</range>
<range>GREATER_THAN_EQUALS 0.0 - LESS_THAN 5.0</range>

Attributes

Attributes <amount>
Info
Values integer
Versions 3
Used by execute_progress_update
Attributes <behavior>
Info When a user changes a role, you can define behaviors that automatically update the roles.
Values

None: no enforcement of rules in the dialog

Swap: all assigned up front. When some object is being assigned a role and is there are already a max number of objects assigned to the role, then any objects that had that role will be switched to the old role of the object being asgined until we surpass the maximum amount of that role, then unassigned.

Max_hide: Don’t allow the role to show up in the combo box to be assigned to a "object" if the max has been reached for that role.

Swap_max_default: (not implemented yet) Enforce max with default is like swap, but instead of the old option, it changes it to the default or unassigned (if no default provided) value. Chooses the first or last “object” of the role it encounters to change.

Versions 3
Used by roles
Attributes <bind_to>
Info Binds a coverage to a mesh, or grid
Values MEHS2D, CGRID
Versions 3
Used by coverage
Attributes <columns>
Info Represents a column in the H5 file that we are mapping to
Values #timestep, #point, #arc, #polygon, #coverage, #material
Versions 3
Used by xmdf_data
Attributes <corner_skip>
Info Skip corners when exporting neighbors
Values true, false
Versions 3
Used by process_each_neighbor
Attributes <create_file>
Info If attribute is specified, then create_file is true
Values None
Versions 3
Used by control_file_selector
Attributes <dataset_type>
Info Specify the dataset type as scalar or vector. Default is scalar.
Values scalar, vector
Versions 3
Used by control_dataset
Attributes <dataset_widget>
Info When exporting points from a dataset, the attribute identifies the dataset widget being used (contains the selected dataset)
Values Name of the dataset_widget
Versions 3
Used by process_each_point
Attributes <datatype>
Info
Values float, double, integer, text
Versions 3
Used by xmdf_data
Attributes <default_executable_name32>
Info Sets the initial default file name for the 32-bit executable.
Values text
Versions 3
Used by executable
Attributes <default_executable_name64>
Info Sets the initial default file name for the 64-bit executable.
Values text
Versions 3
Used by executable
Attributes <description_text>
Info A detailed description of why a model check failed. This text is displayed to the user.
Values string
Versions 3
Used by model_check
Attributes <dim>
Info Specifies that when the dependency is false, the widget should be dimmed, not hidden.
Values none
Versions 1
Used by dependency
Attributes <display>
Info This is used to describe how the dialog should display.

FLEX is the default. In this mode, there is a tree on the left hand side of the dialog. Clicking on an item in the tree will display that portion of the tree along with any child items below the clicked item. Other items will be hidden on the right hand side.

FULL will show a tree on the left hand side of the dialog. Clicking on an item in the tree will move the scroll bars on the right hand side to make the item visible. All items that are not disabled due to dependencies are shown on the right hand side of the dialog in this mode.

NO_NAV will have no left hand side tree. Instead, all items that are not disabled due to dependencies are shown in this mode. Added in SMS 11.2.

Values FLEX, FULL, NO_NAV
Versions 1
Used by declare_page
Attributes <display_options_hide>
Info Don’t show a specific combo-box option in the display option dialog of SMS. This only applies to <combo_box> ‘s that have included the <display_options> element. Default value is false.
Values <option display_options_hide = “true”>
Versions 3
Used by option
Attributes <double_click>
Info The double_click attribute (if true) indicates that this is the menu item to be launched on a double click event.
Values true, false
Versions 2
Used by menu_item
Attributes <executable_order>
Info Defines the order in which this executable should run relative to other executables in the same simulation.
Values interger starting at 1
Versions 2
Used by executable
Attributes <feature>
Info Determine whether to select, points, arcs or polys
Values point, arc, poly
Versions 2
Used by control_feature_selector, process_each_neighbor
Attributes <fix_text>
Info A brief summary of what steps to take to fix a model check failure. This text is displayed to the user.
Values string
Versions 3
Used by model_check
Attributes <file_type>
Info Specifies a file type of <declare_file_def> defines the file type.
Values CARD_ASCII, SEQUENTIAL_ASCII, SEQUENTIAL_BINARY, XMDF
Versions 2
Used by declare_file_def, section
Attributes <filter>
Info When selecting a file, used to filter the available files by the extension type. The filter tag contains two parts. The first part is the text describing the filter that gets displayed to the user. The second part is a pair of parentheses that contains the actual filter.
Values string “(“string “)” ex. Cmcards file (.cmcards)
Versions 3
Used by control_file_selector
Attributes <footer>
Info Exported text inside a table that is placed at the end
Values string
Versions 1
Used by export_table, export_each_row, export_column
Attributes <geometry>
Info The default behavior is to only allow geometric objects that are contained under a simulation to be a candidate for selection. Otherwise “all” geometries are candidates.
Values all
Versions 2
Used by control_dataset
Attributes <header>
Info Exported text inside a table that is placed at the beginning
Values string
Versions 1
Used by export_table, export_each_row, export_column
Attributes <help_button_url>
Info Provides online help when the help button is clicked. Loads the specified url in a web browser.
Values string
Versions 2
Used by declare_dialog
Example
<declare_dialog   name=”Model Control”
               help_button_url=”www.aquaveo.com”>
      …
</declare_dialog>
Attributes <help_button_wiki>
Info Provides online help when the help button is clicked. Loads the specified url in a web browser.
Values string
Versions 2
Used by declare_dialog
Example
<dialog   name=”Model Control”
    help_button_wiki=”DynSrhModelControl”>
      …
</dialog>
Attributes <ignore_on_read>
Info Ignore when reading
Values None
Versions 2
Used by export_format, export_group, export_optional, process_each_arc, process_each_coverage, process_each_material, process_each_point, process_each_polygon, process_each_row, process_on_condition, process_on_count, section
Attributes <increment>
Info An increment values. Used Increment from the min time to the max time, using the increment
Values positive integer

1 : default

Versions 2
Used by control_set
Attributes <interior_polygon>
Info Only used for polygons when finding neighbors. Specify the polygon preference.
Values “interior_first”, “exterior_first”, “interior_only”, “exterior_only”
Versions 3
Used by process_each_neighbor
Attributes <i_order>
Info Start at min i and go to max. Only used by cartesian grids and process_each_neighbor on quad trees.
Values “ascending”, “descending”
Versions 3
Used by process_each_arc, process_each_coverage, process_each_material, process_each_point, process_each_polygon, process_each_row
Attributes <j_order>
Info Start at min j and go to max. Only used by cartesian grids and process_each_neighbor on quad trees.
Values “ascending”, “descending”
Versions 3
Used by process_each_arc, process_each_coverage, process_each_material, process_each_point, process_each_polygon, process_each_row
Attributes <layers>
Info Represents a layer in the H5 file that we are mapping to
Values “#timestep”, “#point”, “#arc”, “#polygon”, “#coverage”, “#material”
Versions 3
Used by xmdf_data