Subpicture Functions
- Last UpdatedJan 07, 2026
- 4 minute read
Management of subpictures
This chapter describes functions to create new subview and component, traverse subpictures, elements tree and change current subpicture.
|
subview_new (<name>) |
||
|
The function creates a new subview. The subview will be placed within the current view. Current subpicture cannot be set to "automatic" when this function is executed. |
||
|
Input Parameters: |
||
|
name |
string |
Name for new subview (optional). |
|
Returned value: |
||
|
[0] |
KcsElementHandle |
Handle to created subview. |
|
Exceptions: |
||
|
kcs_ArgumentError |
Invalid parameter type. |
|
|
kcs_NameOccupied |
Name is already in use in current view. |
|
|
kcs_DrawingNotCurrent |
No drawing was current. |
|
|
kcs_Error |
General error. |
|
|
component_new (<name>) |
||
|
The function creates a new component. The component will be placed within the current subview. Current subpicture cannot be set to "automatic" when this function is executed. |
||
|
Input Parameters: |
||
|
name |
string |
Name for new component (optional). |
|
Returned value: |
||
|
[0] |
KcsElementHandle |
Handle to created component. |
|
Exceptions: |
||
|
kcs_ArgumentError |
Invalid parameter type. |
|
|
kcs_NameOccupied |
Name is already in use in current subview. |
|
|
kcs_DrawingNotCurrent |
No drawing was current. |
|
|
kcs_Error |
General error. |
|
|
subpicture_current_set (subpictureHandle) |
||
|
The function sets a subpicture to be current for the creation of new geometry. If a component subpicture element handle is give, this will be set as current. If a handle to view or subview is given, the component (and subview) will be chosen by the system. If no argument is given the subpicture will be automatically chosen each time geometry is created. Note: If you will try to set a view or a subview which has no children as current then system will create component (and subview) and set it current. |
||
|
Input Parameters: |
||
|
subpictureHandle |
KcsElementHandle |
Handle to subpicture (optional). |
|
Returned value: |
||
|
[0] |
KcsElementHandle |
Handle to created component. |
|
Exceptions: |
||
|
kcs_ArgumentError |
Invalid parameters list. |
|
|
kcs_HandleInvalid |
Specified handle is not valid. |
|
|
kcs_DrawingNotCurrent |
No drawing was current. |
|
|
kcs_Error |
General error. |
|
|
subpicture_current_get () |
||
|
The function returns the current subpicture status. If an empty result list is returned, this means that the current subpicture setting is set to "automatic". Note: If you will use that function when current subpicture settings is not set to "automatic" and there are no views, subviews or components system will create one at set is as current. Handles of created subpictures will be returned. |
||
|
Input Parameters: |
||
|
None |
||
|
Returned value: |
||
|
[0] |
List of ElementHandle |
If not empty then handles to current view (first list item), subview (second list item) and component (third list item). |
|
Exceptions: |
||
|
kcs_ArgumentError |
Invalid parameters list. |
|
|
kcs_DrawingNotCurrent |
No drawing was current. |
|
|
kcs_Error |
General error. |
|
|
subpicture_name_set(subpictureHandle, name) |
||
|
The function sets new name for existing subpicture. Name of form view can't be changed. If name is not empty and there is another subpicture on this level with the same name exception will be raised. |
||
|
Input Parameters: |
||
|
subpictureHandle |
KcsElementHandle |
Handle to subpicture element |
|
name |
String |
New name for subpicture |
|
Returned value: |
||
|
None |
||
|
Exceptions: |
||
|
kcs_ArgumentError |
Invalid parameters list. |
|
|
kcs_HandleInvalid |
Specified handle is not valid. |
|
|
kcs_DrawingNotCurrent |
No drawing was current. |
|
|
kcs_NameOccupied |
There is another subpicture on this level with the same name. |
|
|
kcs_CantChangeFormViewName |
Form view name can't be changed. |
|
|
subpicture_name_get(subpictureHandle) |
||
|
The function gets name of existing subpicture. |
||
|
Input Parameters: |
||
|
subpictureHandle |
KcsElementHandle |
Handle to element. |
|
Returned value: |
||
|
[0] |
String |
Name of existing subpicture. |
|
Exceptions: |
||
|
kcs_ArgumentError |
Invalid parameters list. |
|
|
kcs_HandleInvalid |
Specified handle is not valid. |
|
|
kcs_DrawingNotCurrent |
No drawing was current. |
|
|
kcs_NotFound |
There is no next sibling element. |
|
|
kcs_Error |
General error. |
|
|
Example: |
||
|
# Example: kcs_ex_draft30.py |
||
|
subpicture_save(subpHandle) |
||
|
The function saves subpicture given by handle to standard subpicture databank. Subpicture name will be used for saving so it must be set first. |
||
|
Input Parameters: |
||
|
subpHandle |
ElementHandle |
Subpicture handle |
|
Returned value: |
||
|
None |
||
|
Exceptions: |
||
|
kcs_ArgumentError |
Invalid arguments list. |
|
|
kcs_HandleInvalid |
Given handle is not valid. |
|
|
kcs_SubpictureNotValid |
Given subpicture is not valid. |
|
|
kcs_NameInvalid |
Given subpicture has invalid name. |
|
|
kcs_NameOccupied |
Subpicture’s name is already in use in standard subpicture databank |
|
|
kcs_NameUsedInWorkspace |
There is another object in the workspace with the same name as given subpicture’s name. |
|
|
kcs_DrawingNotCurrent |
There is no current drawing. |
|
|
kcs_GeneralError |
General error. Subpicture can not be saved. |
|
|
|
||
|
subpicture_insert(subpName, <parentHandle>), <databank='SBD_PICT'>) |
||
|
The function inserts a subpicture from the SBD_PICT (default) or SBD_STD databank under given parent given by handle. It is required to use the parent subpicture on the correct level. If the given subpicture is a view no parent must be given. Only subpictures with 001=102 are handled. Note: The sample function SubpictureInsert defined in CommonSample.py module takes care of missing parent subpicture creation. It extends possibilities of subpicture_insert function allowing user to specify any subpicture handle as parent for inserting one. It will find the correct subpicture level and create missing subpictures if needed. |
||
|
Input Parameters: |
||
|
subpName |
string |
Subpicture name. |
|
parentHandle |
ElementHandle |
Handle to parent subpicture. Should be specified only if subpicture stored in standard subpicture databank is a subview or component. |
|
Databank |
integer |
Valid types:
|
|
Returned value: |
||
|
[0] |
ElementHandle |
Handle to inserted subpicture. |
|
Exceptions: |
||
|
kcs_ArgumentError |
Invalid arguments list. |
|
|
kcs_HandleInvalid |
Given handle is not valid. |
|
|
kcs_SubpictureNotValid |
Given subpicture is not valid. |
|
|
kcs_NameInvalid |
Given subpicture has invalid name. |
|
|
kcs_NameOccupied |
Subpicture’s name is already in use in standard subpicture databank |
|
|
kcs_NameUsedInWorkspace |
There is another object in the workspace with the same name as given subpicture’s name. |
|
|
kcs_DrawingNotCurrent |
There is no current drawing. |
|
|
kcs_GeneralError |
General error. Subpicture can not be saved. |
|
|
plate_part_insert (PlatePartName, Pos2D) |
||
|
The function inserts a 2D view in the current drawing showing a given plate part, and returns a handle to the created view. |
||
|
Input Parameters: |
||
|
PlatePartName |
string |
Name of plate part. |
|
Pos2D |
Point2D |
Position of the view (will coincide with middle of view extension). |
|
Returned value: |
||
|
[0] |
KcsElementHandle |
Handle to the resulting view. |
|
Exceptions: |
||
|
kcs_ArgumentError |
Invalid parameters. |
|
|
kcs_DrawingNotCurrent |
No drawing was current. |
|
|
kcs_GeneralError |
Failure inserting plate part view. |
|
|
Example: |
||
|
#Example: kcs_ex_draft37.py CommonSample.py |
||