CoCreate Modeling code examples: Secure part

topic end
<!--
   * Set TOPICTITLE = <nop>CoCreate Modeling code examples: Secure part
-->

<style type="text/css">
pre { background-color:#FFEECC; }
</style>

---++ <nop>CoCreate Modeling code examples: Secure a part against sectioning in Annotation views

---+++ The task at hand

Sometimes you do not want a part to be sectioned in Annotation section views (or
docuplanes). In such a case, you can either use the built-in
functionality in Annotation to "secure" a part, or you can programmatically
assign a special "don't section" flag to a part.

The standard functionality in Annotation is usually preferrable because
it allows to precisely define in which views the part should be protected
against sectioning. However, the Annotation module must be activated to
use the standard functionality, but maybe you want to globally prevent
a part from being sectioned, and you want to do that at part creation time
(i.e. while using Modeling). Developer's Kit to the rescue: A global 
"don't section" flag can be set using APIs from the Developer's
Kit which have become available with OSDM 2005. We will now use those
APIs to develop a simple dialog.

---+++ The dialog code

For the impatient, here is the complete dialog:

<pre style="background-color:#FFEECC;margin-top:0;margin-bottom:0;">
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;; Description:  "Secures" a part against (2D and 3D) Annotation sections
;; Author:       Claus Brod  
;; Language:     Lisp
;;
;; (C) Copyright 2005 Claus Brod, all rights reserved
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
(in-package :clausbrod.de)
(use-package :oli)

</pre>
<pre style="background-color:#CCEEAA;margin-top:0;margin-bottom:0;">
(sd-defdialog 'secure_part
         :dialog-title "Secure part" :toolbox-button t</pre>
<pre style="background-color:#CCDDAA;margin-top:0;margin-bottom:0;">
         :variables
         '(
            (Part :value-type :part
             :after-input
              (sd-set-variable-status 'Secured 
                :value (sd-inq-secure-section-flag Part)))
            (Secured :value-type :boolean
                     :initial-value (when Part (sd-inq-secure-section-flag Part))
          )
</pre><pre style="background-color:#CCEE66;margin-top:0;margin-bottom:0;">
         :ok-action
         '(sd-set-secure-section-flag Part :secure-section-flag Secured)
</pre><pre style="background-color:#CCEEAA;margin-top:0;margin-bottom:0;">
         )
</pre>

<img src="%ATTACHURL%/securepart.png" align="right" alt="Secure part dialog" />
Among other things, the dialog code does the following:
   * Defines a new command called =secure_part= which can be 
     run from the user input line and in other Lisp code.
   * Creates a simple dialog (see image to the right) with the following
     UI elements:
      * OK button
      * Cancel button
      * Help button
      * A part entry field consisting of a part button and a text field
      * A flag entry field for the "secured" state consisting of
        a checkbox and a label
   * Registers an entry in the toolbox which starts the dialog
   * When the dialog opens, the currently active part will
     automatically be selected
   * Allows to click the "Part" button and select any part
   * When a part is selected, its current "secured" state is checked and
     indicated in the "secured" checkbox
   * Allows to change the "secured" state by clicking the checkbox
   * Sets the new state of the part when clicking the OK button
   * Allows to UNDO the change
   * Registers the new command with the system so that it can be
     used together with preselection (select a part, then
     run the dialog, and the preselected part will appear in the
     part entry field)
   * When you run the command while the recorder is active, any
     interactions with the dialog are automatically recorded
     properly, just as if it was an internal command.
 
Quite a bit of functionality for just a few lines of very simple code!

---+++ The code explained

Let us now dissect the code step by step to learn how it works.

<pre>
(in-package :clausbrod.de)
</pre>

My own definitions in this file go to the Lisp package =:clausbrod.de= so that
if somebody else defines symbols with the same names, they won't collide.

<pre>
(use-package :oli)
</pre>

All the APIs from the Developer's Kit are defined in the =:oli= Lisp package,
and the above line makes them available for the following code.

<pre style="background-color:#CCEEAA;">
(sd-defdialog 'secure_part
         :dialog-title "Secure part" :toolbox-button t
</pre>

Those two lines start the definition of an <nop>CoCreate Modeling _dialog_. The dialog's name
is =secure_part=. A dialog always also defines a new command which can be used
from the user input line (example: =secure_part :part "/p1" :secured t=).

<img src="%ATTACHURL%/securepart_toolbox.png" align="right" alt="Secure part toolbox entry" />
=:dialog-title= defines what is displayed as the title of the dialog in the UI, and 
the =:toolbox-button= keyword registers an entry in the toolbox from 
which you can start the dialog.

The next two lines in the code start the _variables_ section:

<pre style="background-color:#CCDDAA;">
        :variables
         '(
</pre>

Variables are containers which can hold data of various useful types, such as:
   * Numbers
   * Directions
   * Parts, assemblies, workplanes etc.
   * Filenames
   * Text
   * Booleans (t/nil)

Some of these are simple data types (such as numbers or text fields), but some
are quite intelligent - for example, when you click a filename button, it will
automatically pop up a file browser and let you select a file; and when you
click a part button, it will automatically start <nop>CoCreate Modeling's selector with all its
advanced selection mechanisms.

In our case, we want to hold only two pieces of data - a part
and its "secured" status. The part is of type, well, "part", which is
indicated by the parameter for the =:value-type= keyword:

<pre style="background-color:#CCDDAA;">
            (Part :value-type :part
             :after-input
              (sd-set-variable-status 'Secured 
                :value (sd-inq-secure-section-flag Part)))
</pre>

But what's that funny =:after-input= thing about? This is actually the most complicated
part of the whole dialog. Whenever a part is selected, the Lisp code which follows
=:after-input= will automatically be executed. Let us rewrite this code for
slightly better readability:

<pre style="background-color:#CCDDAA;">
  (sd-set-variable-status 'Secured :value (sd-inq-secure-section-flag Part)))
</pre>

That looks a little simpler already. So we use the Developer's Kit
function =sd-inq-secure-section-flag= to inquire the "secured" status of
=Part=. This value is then transferred into the dialog variable
=Secured= (which we will define in a second) using the =sd-set-variable-status=
function.

<pre style="background-color:#CCDDAA;">
            (Secured :value-type :boolean
                     :initial-value (when part (sd-inq-secure-section-flag Part))
                     )
          ) 
</pre>

Aha, so here's the missing definition for the =Secured= variable. This variable is
of type =boolean=, so it can only hold a simple true/false decision - but that's
precisely what we need to indicate the current "secured" state of a part.

The variable =Part= is set to the current part when the dialog is started. But
what if no part has been set as the current part? The =:initial-value= check
for the =Secured= variable takes care of this situation.

To summarize: When we select a new part, we inquire its "secured" status
and copy that status into the =Secured= variable - which automatically
updates the UI!

Note the closing parenthesis after the definition for =Secured= - this closes
the list of variables which we started earlier.

Let us now finish up the dialog:
<pre style="background-color:#CCEE66;">
         :ok-action
         '(sd-set-secure-section-flag Part :secure-section-flag Secured)
         )
</pre>

The code which follows =:ok-action= is executed when the user clicks the OK
button. In our case, we want to run the =sd-set-secure-section-flag=
function which changes the section flag for =Part=; here, we simply use
the current status of the =Secured= dialog variable (which the user can 
change by clicking the checkbox) as the new "secured" status for the
selected part.

And that's all!

-- Main.ClausBrod - 22 Mar 2005
-- Main.DerWolfgang - 26 Apr 2005 _:initial-value for Secured_

%COMMENT{type="below" nonotify="on"}%Hallo Claus,
es fehlt eine Klammer im Code weiter oben

-- Main.EdgarAufdermauer - 16 Nov 2007
to top
End of topic
Skip to action links | Back to top
You are here: CoCreateModeling > MacroSecurePart

r1.14 - 24 Jul 2009 - 19:58 - ClausBrod to top
CoCreateModeling
Welcome
