.. _Custom Pragmas:

Custom Pragmas
==============


You can enable the following features in the editor for regions of code enclosed in comment pragmas:

-  code folding
-  background color
-  receive a read-only notification when editing within the region

.. figure:: ../../images/common/get_started-custom_pragmas.png

To define pragmas for a project, **Right click** on the project in the Project Explorer view and go to :menuselection:`Properties --> DVT --> Custom Pragmas`.

.. figure:: ../../images/common/custom_pragmas_preference_page.png

User defined custom pragmas are stored in the **.dvt/custom_pragmas.xml** file.

**custom_pragmas.xml file syntax**

.. code-block:: 

  <?xml version="1.0" encoding="UTF-8" standalone="no"?>
  <!DOCTYPE pragmas PUBLIC "-//DVT//custom_pragmas" "custom_pragmas.dtd">
  <pragmas version="1">
      <pragma startPragma="custom pragma start" endPragma="end custom pragma" enabled="TRUE" colorEnabled="TRUE" color="255;0;0" readOnly="TRUE" description="..."/>
  </pragmas>
  

Custom pragmas can be shared using :ref:`Settings Management`.

Custom pragmas defined through Settings Management are not editable and are marked with gray color in the project's property page.

For identical pragmas defined in multiple locations, the precedence is:

-  pragmas defined in **.dvt** (the last defined pragma has the highest priority)
-  pragmas coming from **$DVT_USER_SETTINGS/custom_pragmas.xml**
-  pragmas coming from **$DVT_COMMON_SETTINGS/custom_pragmas.xml**

Overridden pragmas are marked with a strike out line.

.. note:: 

  Two pragmas are identical if they have the same start pragma **or** end pragma.

.. note:: 

  A read-only notification does not prevent editing within the region.

.. note:: 

  You can nest at most 3 custom pragmas.

.. note:: 

  DVT flags the following incorrect pragma usages:

  -  **CUSTOM_PRAGMA_NESTING_EXCEEDED**: More than 3 nested custom pragmas found
  -  **CUSTOM_PRAGMA_UNEXPECTED_END**: No # start found
  -  **CUSTOM_PRAGMA_MISMATCH**: Expecting # found #
  -  **CUSTOM_PRAGMA_NO_END**: No matching # end pragma found

