.. highlightlang:: us

.. index:: DocCreate

.. _doccreate:

DocCreate
=========

.. us.tag  DocCreate ENGLISH Changed400 Changed413 Changed5400

:ref:`DocCreate` creates a new document or opens an existing document. The
document can contain pages with diagrams. The document will be displayed in a
window.

.. function::  hDoc = DocCreate()
    hDoc = DocCreate(ssFileName)
    hDoc = DocCreate(ssFileName, nFlags)
    hDoc = DocCreate(ssFileName, nFlags, ssPassword)

.. us.return

**Return Value**

If the function succeeds, the return value is the handle of the newly created
document. If the function fails, the return value is 0.

.. us.params

**Parameters**

.. uparam:: ssFileName

   *ssFileName* is the complete filename of an existing IPW or IPZ document or an
   empty string (""). If the function is called without parameters or if
   *ssFileName* is an empty string a new document will be created. The document
   will be  visible when the fist page is added to the document. It will stay
   invisible if ``DOC_HIDDEN`` is set.

.. uparam:: nFlags

   *nFlags*

   .. list-table::
      :header-rows: 1

      * - Value
        - Meaning
      * - DOC_HIDDEN (1)
        - Not visible.
      * - DOC_READONLY (2)
        - Document will be opened read-only.
      * - DOC_NO_AUTOSAVE (128)
        - Auto save disabled. Will be ignored for ipw files.
      * - DOC_NO_COPYONOPEN (256)
        - If set, an IPZ file on a network drive is opened without creating a
          local copy. The option has no effect for locally saved files. The 
          option should not be used for files to work with interactively.
          I should be set, if a template file is opened or you just want to read
          some data from the file, for example to read the page names.

.. uparam:: ssPassword

   If the document is password protected the password must be specified.

.. us.comment

**Comment**

If the function is invoked without parameters a new document will be created.
The document will be displayed as soon as a new page page is added to the
document (see :ref:`DocAddPage`).

.. us.example

**Example**

::

   ssFile = GetRootDirectory() + "/template/template-en.ipz";
   hDocTemplate = DocCreate(ssFile, DOC_HIDDEN | DOC_READONLY);
   if (hDocTemplate == 0) {
       MessageBoxError("Cannot open template %s", ssFile);
       return FALSE;
   }
   hDocNew = DocCreate();
   DocCopyPage(hDocTemplate, 3, hDocNew);
   DocDestroy(hDocTemplate);

**Example 2**

Creates a new Document from a template, that contains all template pages.

::

   def DocCreateNew(ssTemplate)
   {
       hDocTemplate = DocCreate(ssTemplate, DOC_HIDDEN | DOC_READONLY);
       if (hDocTemplate == 0) {
           log_error("", "DocCreateNew", "Cannot open template %s", ssTemplate);
           return 0;
       }
       hDoc = DocCreate();
       nPages = DocGetPageCount(hDocTemplate); 
       for (i in 1:nPages) {
           hPageT = DocGetPageHandle(hDocTemplate, i);
           hPage = DocCopyPage(hDocTemplate, i, hDoc);
           PageSetTitle(hPage, PageGetTitle(hPageT));
       }
       DocDestroy(hDocTemplate);
       DocSelectPage(hDoc, 1, FALSE) 
       return hDoc;
    }
    // Example call
    hDoc = DocCreateNew("d:/test.ipw")

.. us.history

**History**

.. list-table::
   :header-rows: 1

   * - Version
     - Description
   * - R2017.2
     - New flag ``DOC_NO_COPYONOPEN`` for ipz documents.
   * - R2012 (5.40)
     - New flag ``DOC_NO_AUTOSAVE`` for ipz documents.
   * - 5.30.2
     - Flags ``DOC_SEC_512`` and ``DOC_SEC_4096`` removed. New files have always
       4096 Bytes/Sector.

.. seealso::
   :ref:`overview-documents`,
   :ref:`DocDestroy`,
   :ref:`DocShow`,
   :ref:`GetRootDirectory`,
   :ref:`DocCopyPage`,
   :ref:`DocAddPage`,
   :ref:`DocSetProtectionFlags`,
   :ref:`DocSave`,
   :ref:`DocIsVisible`,
   :ref:`DocIsReadOnly`,
   :ref:`DocGetPageCount`,
   :ref:`application-limits`

:sub:`id-107438`