Visibility and Display

Visibility

A workset’s visibility can be set for a particular view using View.SetWorksetVisibility(). The WorksetVisibility options are Visible (it will be visible if the workset is open), Hidden, and UseGlobalSetting (indicating not to override the setting for the view). The corresponding View.GetWorksetVisibility() method retrieves the current visibility settings for a workset in that view. However, this method does not consider whether the workset is currently open. To determine if a workset is visible in a View, including taking into account whether the workset is open or closed, use View.IsWorksetVisible().

The class WorksetDefaultVisibilitySettings manages default visibility of worksets in a document. It is not available for family documents. If worksharing is disabled in a document, all elements are moved into a single workset; that workset, and any worksets (re)created if worksharing is re-enabled, is visible by default regardless of any current settings.

The following example hides a workset in a given view and hides it by default in other views.

Code Region: Hide a Workset 

public void HideWorkset(Document doc, View view, WorksetId worksetId)
{
    // get the current visibility
    WorksetVisibility visibility = view.GetWorksetVisibility(worksetId);

    // and set it to 'Hidden' if it is not hidden yet
    if (visibility != WorksetVisibility.Hidden)
    {
        view.SetWorksetVisibility(worksetId, WorksetVisibility.Hidden);
    }

    // Get the workset’s default visibility      
    WorksetDefaultVisibilitySettings defaultVisibility = WorksetDefaultVisibilitySettings.GetWorksetDefaultVisibilitySettings(doc);

    // and making sure it is set to 'false'
    if (true == defaultVisibility.IsWorksetVisible(worksetId))
    {
        defaultVisibility.SetWorksetVisibility(worksetId, false);
    }
}

Display Modes

In addition to getting and setting information about the workset visibility, the View class also provides methods to access information on the worksharing display mode and settings. The WorksharingDisplayMode enumeration indicates which mode a view is in, if any:

Member Name

Description

Off

No active worksharing display mode.

CheckoutStatus

The view is displaying the checkout status of elements.

Owners

The view is displaying the specific owners of elements.

ModelUpdates

The view is displaying model updates.

Worksets

The view is displaying which workset each element is assigned to.

Code Region: Activate different worksharing display modes 

public Result Execute(ExternalCommandData commandData, ref string message, ElementSet elements)
{
    View activeView = commandData.View;
    Document doc = activeView.Document;

    // Prepare settings
    Color red = new Color(0xFF, 0x00, 0x00);
    WorksharingDisplayGraphicSettings settingsToApply = new WorksharingDisplayGraphicSettings(true, red);

    // Toggle mode based on the current mode
    using (Transaction t = new Transaction(doc, "Toggle display mode"))
    {
        t.Start();

        WorksharingDisplaySettings settings = WorksharingDisplaySettings.GetOrCreateWorksharingDisplaySettings(doc);

        switch (activeView.GetWorksharingDisplayMode())
        {
            case WorksharingDisplayMode.Off:
                activeView.SetWorksharingDisplayMode(WorksharingDisplayMode.CheckoutStatus);
                settings.SetGraphicOverrides(CheckoutStatus.OwnedByOtherUser, settingsToApply);
                break;
            case WorksharingDisplayMode.CheckoutStatus:
                activeView.SetWorksharingDisplayMode(WorksharingDisplayMode.ModelUpdates);
                settings.SetGraphicOverrides(ModelUpdatesStatus.UpdatedInCentral, settingsToApply);
                break;
            case WorksharingDisplayMode.ModelUpdates:
                activeView.SetWorksharingDisplayMode(WorksharingDisplayMode.Owners);
                settings.SetGraphicOverrides("Target user", settingsToApply);
                break;
            case WorksharingDisplayMode.Owners:
                activeView.SetWorksharingDisplayMode(WorksharingDisplayMode.Worksets);
                settings.SetGraphicOverrides(doc.GetWorksetTable().GetActiveWorksetId(), settingsToApply);
                break;
            case WorksharingDisplayMode.Worksets:
                activeView.SetWorksharingDisplayMode(WorksharingDisplayMode.Off);
                break;
        }

        t.Commit();
    }

    return Result.Succeeded;
}

Graphics Settings

The WorksharingDisplaySettings class controls how elements will appear when they are displayed in any of the worksharing display modes. The colors stored in these settings are a common setting and are shared by all users in the model. Whether a given color is applied is specific to the current user and will not be shared by other users. Note that these settings are available even in models that are not workshared. This is to allow pre-configuring the display settings before enabling worksets so that they can be stored in template files.

Code Region: Worksharing Display Graphic Settings 

public WorksharingDisplayGraphicSettings GetWorksharingDisplaySettings(Document doc, String userName, WorksetId worksetId, bool ownedbyCurrentUser)
{
    WorksharingDisplayGraphicSettings graphicSettings;

    // get or create a WorksharingDisplaySettings current active document
    WorksharingDisplaySettings displaySettings = WorksharingDisplaySettings.GetOrCreateWorksharingDisplaySettings(doc);

    // get graphic settings for a user, if specified
    if (!String.IsNullOrEmpty(userName))
        graphicSettings = displaySettings.GetGraphicOverrides(userName);

     // get graphicSettings for a workset, if specified
    else if (worksetId != WorksetId.InvalidWorksetId)
        graphicSettings = displaySettings.GetGraphicOverrides(worksetId);

    // get graphic settings for the OwnedByCurrentUser status
    else if (ownedbyCurrentUser)
        graphicSettings = displaySettings.GetGraphicOverrides(CheckoutStatus.OwnedByCurrentUser);
                
    // otherwise get graphic settings for the CurrentWithCentral status
     else
          graphicSettings = displaySettings.GetGraphicOverrides(ModelUpdatesStatus.CurrentWithCentral);

     return graphicSettings;
}

The overloaded method WorksharingDisplaySettings.SetGraphicOverrides() sets the graphic overrides assigned to elements based on the given criteria.

Code Region: Graphic Overrides 

public void SetWorksharingDisplaySettings(Document doc, WorksetId worksetId, String userName)
{
    String message = String.Empty;

    // get or create a WorksharingDisplaySettings current active document
    WorksharingDisplaySettings displaySettings = WorksharingDisplaySettings.GetOrCreateWorksharingDisplaySettings(doc);

    // set a new graphicSettings for CheckoutStatus - NotOwned
    WorksharingDisplayGraphicSettings graphicSettings = new WorksharingDisplayGraphicSettings(true, new Color(255, 0, 0));
    displaySettings.SetGraphicOverrides(CheckoutStatus.NotOwned, graphicSettings);

    // set a new graphicSettings for ModelUpdatesStatus - CurrentWithCentral
    graphicSettings = new WorksharingDisplayGraphicSettings(true, new Color(128, 128, 0));
    displaySettings.SetGraphicOverrides(ModelUpdatesStatus.CurrentWithCentral, graphicSettings);

    // set a new graphicSettings by a given userName
    graphicSettings = new WorksharingDisplayGraphicSettings(true, new Color(0, 255, 0));
    displaySettings.SetGraphicOverrides(userName, graphicSettings);

    // set a new graphicSettings by a given workset Id
    graphicSettings = new WorksharingDisplayGraphicSettings(true, new Color(0, 0, 255));
    displaySettings.SetGraphicOverrides(worksetId, graphicSettings);
}

The WorksharingDisplaySettings class can also be used to control which users are listed in the displayed users for the document. The RemoveUsers() method removes users from the list of displayed users and permanently discards any customization of the graphics. Only users who do not own any elements in the document can be removed. The RestoreUsers() method adds removed users back to the list of displayed users and permits customization of the graphics for those users. Note that any restored users will be shown with default graphic overrides and any customizations that existed prior to removing the user will not be restored.

Code Region: Removing Users 

public void RemoveAndRestoreUsers(Document doc)
{
    // get or create a WorksharingDisplaySettings current active document
    WorksharingDisplaySettings displaySettings = WorksharingDisplaySettings.GetOrCreateWorksharingDisplaySettings(doc);

    // get all users with GraphicOverrides
    ICollection<string> users = displaySettings.GetAllUsersWithGraphicOverrides();
           
    // remove the users from the display settings (they will not have graphic overrides anymore)
    ICollection<string> outUserList;
    displaySettings.RemoveUsers(doc, users, out outUserList);

    // show the current list of removed users
    ICollection<string> removedUsers = displaySettings.GetRemovedUsers();

    String message = "Current list of removed users: ";
    if (removedUsers.Count > 0 )
    {
        foreach (String user in removedUsers)
        {
           message += "\n" + user;
        }
    }
    else
    {
        message = "[Empty]";
    }
  
    TaskDialog.Show("Users Removed", message);
            
    // restore the previously removed users
    int number = displaySettings.RestoreUsers(outUserList);
            
    // again, show the current list of removed users
    // it should not contain the users that were restored
    removedUsers = displaySettings.GetRemovedUsers();

    message = "Current list of removed users: ";
    if (removedUsers.Count > 0 )
    {
       foreach (String user in removedUsers)
        {
           message += "\n" + user;
        }
    }
    else
    {
        message = "[Empty]";
    }

    TaskDialog.Show("Removed Users Restored", message);
}
Parent topic: Worksharing