Skip to end of metadata
Go to start of metadata

ArkObjRef object represents a specific reference of an arKItect object in a specific treeview.

This means that the ArkObjRef object is attached to a treeview and holds the path of the reference in this treeview. The reference path uniquely identifies the reference in the treeview, e.g. it can consist of the list of the reference's parents in the treeview, starting from the root to the reference itself. The reference full path consist of the treeview and the reference path in the treeview, it uniquely identifies the reference in the system
ArkObjRef objects support the following methods:

Standard interface methods

  • GetName()
    Returns the arKItect object name string.
  • GetDisplayedName()
    Returns the arKItect object name string as displayed in the current treeview.
  • SetName( name )
    Renames the object. name cannot contain the following symbols : '\ / : * ? \ " < > |' - in this case the method raises a ValueError exception.
  • GetArkType()
    Returns the arKItect object type string.
  • GetChildList( [arktypefilter] )
    Returns a list of children matching the arktypefilter. arktypefilter consist of a list of allowed types string, if no parameter is passed then no filter is applied. In case the number of allowed types equals one, it may be passed as a string - no need to put it into a list.
  • GetChildRelationList( [arktypefilter] )
    Same as GetChildList() but returns list of children pairs (ArkObjRef, relType) matching the arktypefilter. relType is one of ARK_RULE_INPUT, ARK_RULE_OUTPUT or ARK_RULE_SIMPLE.
  • GetChild( name, [type] )
    Returns a child object by its name. To distinguish between several objects with the same name, type name may be specified. Both name and type name must be strings. If there is no such child, returns None.
  • GetParent()
    Returns a reference to the parent object. If called for the root object, returns None. Note that in the arKItect, each object can have several instances and thus have several parents. Each ArkObjRef instance represents exactly one object instance, and thus have exactly one parent. If you need to get the list of all parents, use arkiutils library.
  • GetParentRelation()
    Returns an integer constant, indicating the relation between object and its parent.Can be one of the following:
    • RELATION_NONE- returned, if the object is root (and therefore has no parent).
    • RELATION_DIRECT_CHILD- returned if the object is direct child of its parent.
    • RELATION_INDIRECT_CHILD- the object is an indirect child, i.e. some of its parent are hidden (unchecked) by the tree.
  • GetInputFlowList( [arktypefilter] )
    Same as GetChildList() but returns only input flows.
  • GetOutputFlowList( [arktypefilter] )
    Same as GetChildList() but returns only output flows.

  • GetAttribute( name )
    Returns the ArkAttribute object identified by name.If there is no such attribute, or attribute is not visible (hidden by filter), the method raises ValueError. The method never returns None.

    Icon

    GetAttribute(enum) will raise ValueError when the object is filtered out because of the enumerator enum in the current treeview. It may happen when the script is run at the object creation.

  • GetAttributeList()
    Return the ArkAttribute object list, representing all attributes of the object.

    Icon

    GetAttributeList() will not return some enumerators if the object is filtered out because of these enumerators in the current treeview. It may happen when the script is run at the object creation.

  • IsChildFlow( arktype, name, [flowdir] )
    Return a boolean flag, indicating if the child object given by its name and type is a flow or not. If the flowdir parameter is specified, flow direction is also checked. flowdir must be either "input" or "output".
  • GetTree()
    Returns the ArkTreeViewObj where the current object belongs to
  • IsChildPossible( ark_type_name )
    Returns True, if both matrix definition and tree definition allow creating child of the specified type. If it is not possible, returns False. If object if not accessible or frozen, raises an exception.
  • GetID()
    Returns string, containing unique object identifier. Identifier is guaranteed to be the same for all instances of one object in every view, and guaranteed to be different for any different objects.
  • __str__()
    String conversion function, usually should not be called directly. Returns string representation of the object in the form Object_Name(Object_Type).This function is called automatically, when you pass the ArkObjRef object somewhere, where the string is required.

Objects management methods

  • AddChildObject( arktype, name=None, flowdir='output', variant='empty')
    Add a child object of type arktype and return this child object. If name is None then a dummy object (i.e. with a automatically generated name) is created. Otherwise if the arKItect object (name, arktype) already exists then a reference to this object is added to the child list and in the case the object (name, arktype) does not yet exist it is created and added to the child list. The argument flowdir is used only when arktype is a flow, it specifies if the flow is an 'input' flow or an 'output' flow. If arktype is not a valid type then the function returns None. The argument variant specifies whether variant settings are to be set for the newly added object - possible values are 'empty' and 'current': 'empty' will apply no variant settings, while 'current' will force application of currently active variant settings
  • AddChildReference( arkobjref, flowdir='output' )
    Add a reference to the arKItect object arkobjref to the child list (no effect if arkobjref is already in the child list) and return corresponding ArkObjRef object.
  • RemoveChild( arktype, name, [flowdir] )
    Remove the object of arktype and name from the child list. If no other reference to the object exists then it is destroyed.
  • SetChildFlowDirection(child, flowdir)
    Set the direction of the child flow. direction can be either 'input' or 'output'. child is the a child ArkObjRef.
  • GetParentsOfType( treeName, [typeName])
    This function returns list of all parents of object, having specified type. If typeName is None of not specified, all parents are returned. Search is performed according to tree treeName from its root.This function gives "Get location" functionality to Python scripts.

Graphical interface methods

  • GetGraphChildPos( child, view_id )
    Return the child coordinates in the view specified: (x, y, width, height). child can either be the child name string or the corresponding ArkObjRef object. Valid view_id are: ARK_GRAPH_INNER_VIEW, ARK_GRAPH_PEER_VIEW.
  • SetGraphChildPos( child, view_id, x, y, width=0, height=0 )
    Change the child coordinates in the view specified. A value of zero for width or height means that this parameter should not be modified. child can either be the child name string or the corresponding ArkObjRef object. Valid view_id are: ARK_GRAPH_INNER_VIEW, ARK_GRAPH_PEER_VIEW. This method works only if the graph exists (if the graph was changed manually at least once). This method will not create the graph is it doesn`t exist. It is better to use "NewGraphParser"
  • GetObjBGImage( onlyObject = False )
    If background image was specified for the object, this method returns the image, regardless to argument. If object has no own background image, and the argument has its default value False, method tries to get background image of abstract object, associated with the object.If the argument has value of True, then method does not try to refer to abstract object and returns None, if object has no own background. Thus, when the argument is False(default), the method returns visible image, shown in the view.
  • GetObjFGImage( onlyObject = False *)
    If foreground image was specified for the object, this method returns the image, regardless to argument. If object has no own foreground image, and the argument has its default value *False, method tries to get foreground image of abstract object, associated with the object.If the argument has value of True, then method does not try to refer to abstract object and returns None, if object has no own foreground. Thus, when the argument is False(default), the method returns visible image, shown in the view.
  • SetObjBGImage( image )
    Set the object background image. The parameter should be an ArkImage object.
  • SetObjFGImage( image )
    Set the object foreground image. The parameter should be an ArkImage object.
  • GetRefInTree( target_tree )
    Return the corresponding ArkObjRef in the treeview target_tree or raise an exception if no unique corresponding reference could be found. Refer to the description of the reference mapping mechanism.
  • SaveViewAsImage( file_name, view_id = ARK_GRAPH_INNER_VIEW, show_title = True )
    Selects object in a Internal view and saves graph to an image file. Image format is determined by extension. Supported formats are JPG, BMP, TIFF..Valid view_id are: ARK_GRAPH_INNER_VIEW, ARK_GRAPH_PEER_VIEW, ARK_GRAPH_MATDRAW_INNER_VIEW, ARK_GRAPH_MATDRAW_PEER_VIEW.
    If one of Matdraw views is specified as a view_id. With this view_id :
    • The show_title parameter is ignored
    • Additional image formats are supported (PNG, ICO, XPM, ...)
    • ValueError is raised with a human readable error string in case of failure.
  • ResetOuterflowPorts( view_id )
    Recalculates positions and grouping of outerflow ports and redraws the view. Valid view_id are: ARK_GRAPH_INNER_VIEW, ARK_GRAPH_PEER_VIEW

View graph management methods

The following two methods are intended for saving and restoring view graph configuration. View graph configuration describes geometrical positions of the objects in the view, their expansion state and the form of the inks between objects. In arKItect, graph is described by XML file. Using the following two methods, user can get or set the XML graph description.

  • GetGraphXML( graph_id, bForceNew = False, bOnlyVisible = False )
    Returns string, containing XML description of a graph. The graph_id argument specifies, which view configuration is returned. Valid view_id are: ARK_GRAPH_INNER_VIEW, ARK_GRAPH_PEER_VIEW. Set bForceNew to True if graph should be regenerated.
    Set bOnlyVisible to True to get the elements actually present in the diagram.

    Icon

    bOnlyVisible is only available in arKItect 2.1.2 and following

  • SetGraphXML( graph_id, xml, update_subtrees=False )
    Sets the XML for graph. Arguments:
    • xml XML string, having the same format, as returned by GetGraphXML.
    • graph_id Type of graph to return. Valid view types are: ARK_GRAPH_INNER_VIEW, ARK_GRAPH_PEER_VIEW. 
    • update_subtrees (optional) if True, then all corresponding graphs in the sub-trees will be updated, using standard graph synchronization mechanism.
  • SynchronizeViews()
    Synchronize Peer and Inner Views. Peer View of object become the same, as its parent Inner View. Note that the exact format of the XML string is the same as internal arKItect format, which is subject to change in the future versions. Therefore, it is only guaranteed that XML, returned by GetGraphXML will be accepted by the SetGraphXML method.

Variant management methods

Python interface for "Variants" feature. See also description of the ArkChoice objects, ArkVariant objects, ArkPhase objects and global functions GetRootChoice(), GetRootVariant(), GetRootPhase(), GetActiveVariant(), GetActivePhase(), GetDefaultVariant(), GetDefaultPhase().

  • GetChoice( choice, index = 0 )
    Returns boolean value, describing whether given choice is set for the object or not. The argument choice must be an ArkChoice object. Root choice category can not be used as argument (if root choice is passed as argument, exception is raised). index (>= 0) may be specified if the composite choices are used.
  • GetVariant( variant )
    Returns boolean value, describing whether given variant is set for the object or not. The argument variant must be an ArkVariant object. Root variant category can not be used as argument (if root variant is passed as argument, exception is raised). Unlike choices, no composite variants are allowes.
  • GetPhase( phase )
    Returns boolean value, describing whether given phase is set for the object or not. The argument phase must be an ArkPhase object. Root phase category can not be used as argument (if root phase is passed as argument, exception is raised). Unlike choices, no composite phases are allowes.
  • SetChoice( choice, value, index = 0 )
    Set or reset choice flag for the object. choice must be an ArkChoice object. value must be a boolean. index (>= 0) may be specified if the composite choices are used; if the specified index does not exist, all missing composite choices from 1 to index will be created and set to False. If choice has children then value is set for them too.
    Choice object must not be root choice, choice folder or choice category without children.
    In case of incorrect arguments, ValueError exception is raised.
  • SetVariant( variant, value )
    Set or reset variant flag for the object. Variant must be an ArkVariant object. value must be a boolean. If variant has children then value is set for them too.
    Variant object must not be root variant nor variant folder.
    In case of incorrect arguments, ValueError exception is raised.
  • SetPhase( phase, value )
    Set or reset phase flag for the object. Phase must be an ArkPhase object. value must be a boolean. If phase has children then value is set for them too.
    Phase object must not be root phase nor phase folder.
    In case of incorrect arguments, ValueError exception is raised.
  • GetChoiceList( choices )
    choices - list (or any iterable object) of ArkChoice objects.
    Returned value is list of the same length as choices. Each element of the returned list is another list of boolean values, representing "checked" status of a choice in each composite choice column. Number of elements of each inner list is equal to value, returned by ArkObjRef.GetNumberOfCompositeChoices(). In simplest case (number of composite choices is 1), each inner list contains 1 boolean value.
  • GetVariantList( variants )
    variants - list (or any iterable object) of ArkVariant objects.
    Returned value is list of the same length as variants. Each element of the returned list is a boolean value, representing "checked" status of a variant.
  • GetPhaseList( phases )
    phases - list (or any iterable object) of ArkPhase objects.
    Returned value is list of the same length as phases. Each element of the returned list is a boolean value, representing "checked" status of a phase.
  • SetChoiceList( args[, choiceStatus] )
    Allows to set multiple choices at once. Much faster than calling SetChoice in cycle.
    args - list (or any iterable container) of choice descriptions.
    Choice description is roughly a tuple of arguments, passed to the ArkObjRef.SetChoice. It can be one of:
    • Single ArkChoice object
      Corresponding choice is set to "checked".
    • Tuple of 2 elements: (ArkChoice, boolean)
      Corresponding choice is set to "checked" or "unchecked" according to the boolean flag
    • Tuple of 3 elements: (ArkChoice, boolean, int)
      Sets value of a composite choice, see SetChoice for details. Third argument is number of composite choice column.
    Different formats can be used in the same list.
    choiceStatus - optional parameter, can be one of ARK_OBJVAR_UNDEFINED, ARK_OBJVAR_MANUAL, ARK_OBJVAR_PROPAGATED.
  • SetVariantList( args[, variantStatus] )
    Allows to set multiple variants at once. Much faster than calling SetVariant in cycle.
    args - list (or any iterable container) of choice descriptions.
    Variant description is roughly a tuple of arguments, passed to the ArkObjRef.SetVariant. It can be one of:
    • Single ArkVariant object
      Corresponding variant is set to "checked".
    • Tuple of 2 elements: (ArkVariant, boolean)
      Corresponding variant is set to "checked" or "unchecked" according to the boolean flag
    Different formats can be used in the same list.
    variantStatus - optional parameter, can be one of ARK_OBJVAR_UNDEFINED, ARK_OBJVAR_MANUAL, ARK_OBJVAR_PROPAGATED.
  • SetPhaseList( args[, phaseStatus] )
    Allows to set multiple phases at once. Much faster than calling SetPhase in cycle.
    args - list (or any iterable container) of phase descriptions.
    Phase description is roughly a tuple of arguments, passed to the ArkObjRef.SetPhase. It can be one of:
    • Single ArkPhase object
      Corresponding variant is set to "checked".
    • Tuple of 2 elements: (ArkPhase, boolean)
      Corresponding variant is set to "checked" or "unchecked" according to the boolean flag
    Different formats can be used in the same list.
    phaseStatus - optional parameter, can be one of ARK_OBJVAR_UNDEFINED, ARK_OBJVAR_MANUAL, ARK_OBJVAR_PROPAGATED, ARK_OBJVAR_PROPAGATED_UP.
  • CopyOptionsFrom( object )
    Exactly copies choices from the specified ArkObjRef instance.
  • CopyVariantsFrom( object )
    Exactly copies variants from the specified ArkObjRef instance.
  • CopyPhasesFrom( object )
    Exactly copies phases from the specified ArkObjRef instance.
  • IsInVariant ( variant, [phase] )
    Returns True or False, depending on whether the object specified is visible under the variant and phase, if phase is specified. The argument variant must be an ArkVariant object, phase, if specified - must be an instance of ArkPhase object

  • ApplyVariant ( variant )

    Icon

    Deprecated - does nothing and returns None.

    Apply Variant to the current object. The argument variant must be an ArkVariant object or None. If None is passed variant information is removed from the current object.

  • GetNumberOfCompositeChoices()
    Return the number of composite choices (choice columns) of the ArkObjRef object. Default non-composite choices are considered being of size 1.
  • RemoveCompositeChoice( index )
    Remove one of the columns of a composite choice. index must be a nonnegative integer. Does nothing if there's no choice at index, nor if there's only one remaining choice. Since indexes are strictly continuous, all choices at i where i>index are shifted to i-1.
  • ResetChoices(onlyPropagation = False)
    Removes any choice definition from the current object if onlyPropagation is not specified or is True, otherwise removes choice definition from the current object only if its status is ARK_OBJ_PROPAGATED.
  • ResetVariants(onlyPropagation = False)
    Removes any variant definition from the current object if onlyPropagation is not specified or is True, otherwise removes variant definition from the current object only if its status is ARK_OBJ_PROPAGATED.
  • ResetPhases(onlyPropagation = False)
    Removes any phase definition from the current object if onlyPropagation is not specified or True, otherwise removes phase definition from the current object only if its status is ARK_OBJ_PROPAGATED.
  • GetOptionsStatus()
    Returns options' status: ARK_OBJVAR_UNDEFINED or ARK_OBJVAR_MANUAL or ARK_OBJVAR_PROPAGATED.
  • GetVariantsStatus()
    Returns variants' status: ARK_OBJVAR_UNDEFINED or ARK_OBJVAR_MANUAL or ARK_OBJVAR_PROPAGATED.
  • GetPhasesStatus()
    Returns phases' status: ARK_OBJVAR_UNDEFINED or ARK_OBJVAR_MANUAL or ARK_OBJVAR_PROPAGATED or ARK_OBJVAR_PROPAGATED_UP.
  • GetOptions()
    Returns a pair:
    optionsStatus    , [[list of checked ArkChoice objects in column 1], [list of checked ArkChoice objects in column 2], ...] - in case optionsStatus = ARK_OBJVAR_MANUAL
    or
    optionsStatus, [list of referenced ArkObjRef objects] - in case optionsStatus = ARK_OBJVAR_PROPAGATED

  • GetVariants()
    Returns a pair:
    variantsStatus, [list of checked ArkVariant objects, may contain None meaning all is checked]
    or
    variantsStatus, None - in case nothing is checked

  • GetPhases()
    Returns a pair:
    phasesStatus, [list of checked ArkPhase objects, may contain None meaning all is checked] - in case phasesStatus = ARK_OBJVAR_MANUAL
    or
    phasesStatus, [list of referenced ArkObjRef objects] - in case phasesStatus = ARK_OBJVAR_PROPAGATED_UP
    or
    phasesStatus, None - in case nothing is checked

 

 

Properties management methods

In case abstract type of the object allows properties modification( ArkMatrixType.GetProperty(pyark.ARK_ATYPE_FLEXIBLE) returns True) it is possible to rewrite default object's properties (inherited from the abstract type) with new values.

  • SetProperty( PropEntry,PropValue )
    Assign property a new value. For valid PropEntry values see ArkMatrixType . SetProperty():FlashProperties() should be called to apply changes when all needed properties are set.
  • GetProperty(PropEntry)
    Return property value for the given entry. See SetProperty() for valid PropEntry values.

  • FlashProperties()

    Icon

    Be careful, use this method only when you have finished setting properties and want to save modifications. After use of this method it will be impossible to restore previous values

    Write accumulated property changes into memory and database.

  • RestoreProperties()
    Abandon accumulated changes to properties and restore all properties from the memory.
  • ResetProperties()
    Returns object properties to original state, resetting all modifications.

SendAlert management methods

  • GetURL( view_type = ARK_GRAPH_INNER_VIEW, [user_name] )
    Get arkitect:// URL, pointing to the object.
    Arguments:
    view_type - specifies, which view is pointed by the URL. Can be one of ARK_GRAPH_INNER_VIEW, ARK_GRAPH_PEER_VIEW, ARK_GRAPH_MATDRAW_INNER_VIEW, ARK_GRAPH_MATDRAW_PEER_VIEW.
    user_name (optional) - If specified, embeds user login into URL. See functions pyark.GetUserName(), pyark.GetUsers(). If this parameter is not specified, URL is generated without embedded login.

Revision management

Methods are available for any ArkObjRef object except for the root object.

  • CreateRevision( name, comment, replaceOld = False )
    Create a new revision of object, where name is revision number, comment is revision description and replaceOld is a flag indicating whether new revision should replace the old one if there is already a revision with the given name.
    Depends on pyark VariantFilter if varian revisions exist for object
  • RestoreRevision( historyPoint )
    Restore object to revision specified by historyPoint.
  • GetRevisionList()
    Return list of object`s revisions description as a list of dictionaries ('hpoint', 'time', 'user', 'comment', 'name', 'svnrevision')
    Depends on pyark VariantFilter if varian revisions exist for object
  • GetLastRevision()
    Return last object revision description as a dictionary ('hpoint', 'time', 'user', 'comment', 'name', 'modified', 'svnrevision')
    Depends on pyark VariantFilter if variant revisions exist for object
    Depends on pyark VariantFilter if variant revisions exist for object
  • GetCurrentRevision()
    Return current revision working status as a string:
    "last revision name*" - if there are changes after the last revision
    "last revision name"  - if there are no changes after the last revision
    Depends on pyark VariantFilter if variant revisions exist for object
  • GetRevision( historyPoint )
    Return object revision as a read-only ArkObjRef object. An exception will raise if you try to set an attribute from this object.
  • HaveVariantRevisions()
    Returns True if any variant revisions exists for the object

Custom view filter support

These methods support the "Custom view filter" functionality, allowing Python script to customize visibility of object children in arKitect. In order to define custom filter, object must have CustoVirewFilter event handler.

  • ReloadCustomFilter()
    Clears currently loaded custom view filter data for this object. On next access to object children in a view, where custom view filter is active, it will be loaded again. Always returns None.

History management methods

  • GetHistory([dateFrom, dateTo, userNameFilter, hpIdFrom, hpIdTo])
    This function retrieves history of the object in the project. All arguments are optional and allow to filter retrieved history more precisely:
    • dateFrom, dateTo - datetime objects that define the part of history being retrieved. In order to use date time objects, you need to import datetime module (see example below) in your script.
    • userNameFilter- If specified, returns only records, related to the specified user.
    • hpIdFrom, hpIdTo - if specified, returns only records within the range

    Return value is a list of tuples, each tuple representing separate history record, as visible in History dialog. Each tuple consists of following 8 elements: (hpId, userName, date, treeViewName, action, actionClass, historyValue, sessionId), where date is a datetime type, and other elements are strings.

    Icon

    Be careful, there may be a lot of history information in the project, so properly set the filters to make retrieval last not so long

Example calling GetHistory:

  • GetActiveUsers()
    Returns the list of names of аctive users for the view path given by ArkObjRef.

ArkObjRef object.

  • No labels