IWbsFieldsRepository.UpdateField (IWbsField, Boolean, FieldUserScope) Method

Namespace: Qdv.UserApi.Fields
Assembly: Qdv.UserApi (in Qdv.UserApi.dll)
Updates a field, whether the complete definition or just the formatting for the specified users.
VB
C#
F#
C++
JScript
Copy
void UpdateField( 
   IWbsField field, 
   bool onlyFormatting, 
   FieldUserScope forUsers 
)

Parameters

field
IWbsField

The field to be updated.

onlyFormatting
bool

Indicates whether only the field formatting is to be saved (including 'hidden by user/admin' info). If true, the field definition will not be saved.

forUsers
FieldUserScope

<default>

Exception type Condition

QdvApiException

A DB problem occurred.

ArgumentException

A field with the IWbsField.NumericID of the field doesn't exist.

ArgumentNullException

The field is null reference (Nothing in Visual Basic).

InvalidWbsFieldException

The field is invalid, i.e. it contains inconsistencies.

Remarks
 

If the field is a master breakdown field, then also its child discrete value fields are updated/added/deleted (they are stored in IWbsFieldMasterBreakdownInfo.BreakdownByDiscreteValues)

Also non-Admin is allowed to define the fields with this method.

This method doesn't refresh the UI with the changes. You need to call RepaintWbsWithChanges method after you have finished all your changes in this fields repository. But if you modified the position or visibility of any field in its IWbsField.Formatting, then you need to call slower IEstimate.CheckAndRepaint.

Example
 

VB
C#
F#
C++
JScript
Copy
// Create and format a new free WBS field MYFIELD.
  
 // Create a field instance, a unique numeric ID will be generated automatically.
 IWbsField newWbsField = es.WbsFieldsRepository.CreateFieldInstance(WbsFieldKind.FreeField, "MYFIELD");
 newWbsField.FieldName = "My new field";
 newWbsField.SubHeader = "created by a macro";
  
 // Add the new field to the repository.
 es.WbsFieldsRepository.AddField(newWbsField);
  
 // Change the formatting of the field. These settings are user-specific.
 // Do it for all users now.
 // First, make the field visible because all newly added fields are hidden and placed at the very end.
 newWbsField.Formatting.HiddenByAdmin = false;
 newWbsField.Formatting.HiddenByUser = false;
 // Change some formatting.
 newWbsField.Formatting.ColumnWidth = 20;
 newWbsField.Formatting.Header1Formatting.ForeColor = System.Drawing.Color.Red;
 newWbsField.Formatting.Header2Formatting.ForeColor = System.Drawing.Color.DarkGreen;
 newWbsField.Formatting.DataFormatting.BackgroundColor = System.Drawing.Color.LightPink;
  
 // Apply the formatting changes to the repository (no UI repainting yet).
 es.WbsFieldsRepository.UpdateField(newWbsField, false, FieldUserScope.AllUsers);
  
 // Change the column position. Don't set newWbsField.Formatting.ColumnPosition directly, as this is unreliable.
 // Instead, use SetFieldPosition, which takes care of possible problems.
 // Place the field after Quantity column. Even if Quantity column is at a different position for each user,
 // the SetFieldPosition takes care of it and it places the field in all user profiles correctly.
 IWbsField quantityField = es.WbsFieldsRepository.GetFieldByMnemonic("WBS_Quantity");
 es.WbsFieldsRepository.SetFieldPosition(newWbsField,
     FieldPlacementPosition.AfterGivenField,
     quantityField,
     FieldUserScope.AllUsers);
  
 // Repaint the changes. Normally, if the position of an EXISTING field is changed, you must call slow CheckAndRepaint().
 // But since we have changed the position of a NEWLY ADDED field, we can use much faster RepaintWbsWithChanges().
 es.WbsFieldsRepository.RepaintWbsWithChanges();                   

The following example creates a new free WBS field, changes its formatting. At the end, the position of the new field is set to be right after the "WBS_Quantity" field. And this is done for all users, not for just the current one.

Version
 
Available since QDV 7.18.655.

.NET Framework

Supported in: 4.8, 4.7, 4.6, 4.5.2